Apex GP

Devlog

How the AI drives, and how it makes mistakes

How Apex GP's opponents follow a racing line, scale their speed by skill, and act out armed driver errors through the car's own controls. Plus what the model can't do.

I'm one developer making an open-wheel racing game, Apex GP. I can't hand-animate a field of opponents, and a grid of identical perfect drivers is dull to race against. So the opponents are a small driver model: a line to follow, a speed they're allowed to carry, a skill number, and an error that can be armed. This post walks through it. Every number below is from the repo, so you can check it.

The line

The AI follows a racing line that is computed offline. racing_line() in tools/blender/track_layout.py is a minimum-curvature solve. It takes lateral offsets within the road (the road half-width minus a 1.3 m margin) and relaxes them with Gauss-Seidel iteration: 3000 sweeps on a coarse pass over every fifth sample, then 300 sweeps at full resolution. tools/gen_circuits.py calls it for each of the 12 circuits and writes the result into the shipped JSON as racing_offset. game/scripts/track.gd loads that array, and the driver reads it.

Steering is pure pursuit in game/scripts/ai_driver.gd. The driver picks a point ahead on the line, with a look-ahead of 6.0 + v * 0.45 metres clamped to 8–40 m. It then steers along the arc that reaches that point.

The pack through a hairpin from the overhead replay camera
The line, from the overhead replay camera. The cars follow the curve of the hairpin rather than the middle of the road. Captured in Apex GP.

The speed

Speed comes from a precomputed profile, build_speed_profile() in game/scripts/track.gd. For each point on the racing line it works out the corner-limited speed from the local curvature, using 0.86 of the car's raw grip as the usable figure and counting downforce. Then it does a backward pass for braking, with deceleration taken at 0.8 of the theoretical value, and a forward pass for acceleration, limited by traction or engine power.

Each frame the driver scans a window ahead (12 + v * 0.35 metres) for the lowest profile speed and multiplies it by skill, pace, and the square root of the tyres' current grip. Below the target it holds the throttle open; above it, it brakes in proportion. A pile of corrections follows in the same function: they ease the brake once the front tyres are really slipping, cut the throttle when the rear tyres are saturated, and unwind the steering on power oversteer.

Skill, pace and the Pro line

skill is the driver's own level. Settings.DIFFICULTY_SKILL in game/scripts/settings.gd maps Easy / Medium / Hard / Pro to 0.88, 0.94, 0.97 and 1.04 in Quick Race. Career uses 0.96, 0.985, 1.0 and 1.04 (DIFF_SKILL in game/scripts/career.gd). The speed profile is the car's limit at 1.0, so Pro asks for a little more than that. The comment on PRO_SKILL says 1.04 is about 3% quicker per lap, the highest value that stayed clean on every track I tried.

Above 1.0, the driver also gets two extra behaviours, and nothing below does:

  • Defending. On a straight above 45 m/s, if a faster car is close behind in the same lane, the driver moves once, PRO_DEFEND_SHIFT = 1.6 m toward the inside of the coming corner. The side is latched until the straight ends, so there's no weaving, and it does nothing if a car is alongside.
  • Earlier passes. The look-ahead for committing to a pass is extended by PRO_PASS_EXTRA = 10 m.

That's why pace is a separate variable. pace is the speed multiplier from the strategy view's driver instructions (game/scripts/race_risk.gd: CONSERVE 0.975, BALANCED 1.0, PUSH 1.015, ATTACK 1.025). If pushing just raised skill, a car on PUSH would switch on the Pro craft. So the two are kept apart.

Avoiding and overtaking

There's no overtaking script. The driver looks for a car within 30 + v * 0.4 metres ahead whose lateral position is within 2.6 m of its own and which it's closing on. It then sets a lateral bias, line_bias, of 2.4 m toward the side with more room, or 1.2 m if it's already far out from the centre. The bias moves toward its target at 2 m/s, and the pursuit target is the racing line plus that bias, clamped to stay inside the road edge. Off the line the car is slower, so the target speed is multiplied by 0.96.

That's all a pass is: the target line moves sideways and the car follows it.

Chase view, one car offset to the left of the cars ahead
A pass is that sideways shift, not a separate animation. Chase camera: the yellow car is on a different line from the cars ahead. Captured in Apex GP.

The mistakes

Errors are rolled in game/scripts/race_risk.gd, once per lap per car from lap 2, with a per-car seeded generator. The base chance depends on the instruction: 1%, 3%, 8% and 15% for CONSERVE, BALANCED, PUSH and ATTACK. Worn or cold tyres multiply it by up to 3 and up to 1.6. A soaked track multiplies it by up to 2.5, and a damaged car by up to 2. It's capped at 0.6. A roll that hits picks a kind with weights 0.40 / 0.35 / 0.25 for lock-up, wide and snap. Street circuits have no run-off to run wide onto, so they use 0.60 / 0 / 0.40.

A hit doesn't do anything immediately. It's armed, and handed to the driver partway through the lap. _act_error() in ai_driver.gd then waits for a spot where that error makes sense, and gives up after ERR_GIVE_UP = 45 seconds:

  • LOCKUP waits for a hard stop: braking over 0.35, above 28 m/s, with a corner 10–45 m ahead. Then it turns the ABS off and brakes at full. The fronts lock and the car runs deep. It lasts up to ERR_LOCK_S = 1.1 s, and adds ERR_FLAT_SPOT = 0.025 tyre wear for the flat spot.
  • WIDE waits for a corner exit at 16–30 m/s with the throttle open. Then it aims the line ERR_WIDE_OUT = 1.0 m past the road edge, so the car steers onto the kerb and run-off. It lasts up to ERR_WIDE_S = 0.9 s, or ends early once the outside wheels are 0.6 m over the edge.
  • SNAP waits for a slow corner with the throttle on, at 14–45 m/s. Then it turns traction control off, goes to full throttle, and adds 40% steering lock. It ends after ERR_SNAP_S = 0.7 s, or at ERR_SNAP_BETA = 0.30 rad (about 17°) of body slip. The comment says the aim is a small moment that's caught, never a scripted spin.

Afterwards the throttle is limited to 0.45 for 2.2 s (3.0 s after a snap) while the driver gathers it up. Nothing teleports the car; the physics, the surface and the stewards decide the cost.

Cockpit view down a straight
The view the driver steers from. A lock-up is this same car with the ABS off and the brake held. This frame is not that moment: no locked fronts, no tyre smoke.

What's artificial

  • Mistakes only exist in the strategy view. RaceRisk is owned by the strategy mode and is live only while it's in use. In driving mode the plain AI runs with no armed errors, and so do headless calibration runs.
  • aggression does nothing. Each driver gets a random value between 0.3 and 0.9, and nothing reads it. It's a placeholder for a personality I haven't built. There's also a _mistake_timer in drive() that is reset and counted down but never used. And the comment on skill says "0.9 .. 1.0", which is out of date, given the values above.
  • No learning, and no blue-flag manners. I found no code for a car moving over for a leader. The only defending is the single Pro move.
  • Judgement is just the bias. A driver doesn't know whether a gap will close. It sees a car in its lane and shifts.
  • Strategy is thin. The stand-in policy in RaceRisk picks an instruction for each AI car every 3 s from tyre life, damage and gaps. The driver code itself has no fuel or weather plan.

What I'd fix next: put aggression to use, probably by scaling PRO_PASS_EXTRA-style commitment per driver. And make the avoidance shift anticipate the closing speed instead of reacting to it.

The game

Apex GP is at apexgp.racing. All teams, drivers and sponsors are fictional.

AI assistance

The code, shaders and some assets in Apex GP were produced with AI tools, under my direction. Some front-end media and the announcer voice lines were generated with AI models, and the credits page marks them as such.

— Phil

← All devlog posts · RSS