aiDrivers

AI drivers for cars, with personalities. Put the AiDriver component on a car's chassis — a torqueCars Car, or a builtin VehicleController car as a fallback — give it a path, and it drives: steering by pure pursuit, choosing its speed from the curvature ahead, keeping its distance, overtaking, catching slides, and getting itself unstuck. One field picks how it drives:

Personalities are data tables in aiDrivers.personalities; add your own with define(name, extend(base, changes)).

Use it

Paste into a fresh world with torqueCars installed (in play, from a script or execute):

local Assemble = require("torqueCars.assemble")

-- a ground to drive on
local ground = entity.spawn("ground")
ground.component.add("Model", { model = "cube", material = asset.resolve("@builtin::materials.grass", "material") })
ground.component.add("BoxCollider", {})
ground.position = { 0, -0.5, -60 }
ground.localScale = { 300, 1, 300 }
task.wait(0.2) -- let the collider register

-- a loop of points (sparse points are splined; a roadPieces road or a waypoint entity works too)
local loop = {}
for i = 0, 15 do
	local a = i / 16 * math.pi * 2
	table.insert(loop, vector.create(math.sin(a) * 70, 0, -60 + math.cos(a) * 45))
end

-- a car, driven by an AI racer
local car = Assemble.spawn({ kind = "coupe", position = vector.create(0, 0.3, -15), yaw = math.pi / 2, control = "script" })
local ai = car.component.add("AiDriver", { personality = "racer", roadWidth = 10 })
ai:setPath(loop, true)

task.wait(30)
print(ai:laps().best, ai:state().offPath, ai:stats().avgTickMs)

Or open the AiDriversShowcase scene: a 1.2 km test loop (main straight, esses, sweeper, two hairpins) with five labelled cars, one per personality, lapping it.

What's inside

• AiDriver (component) — the driver. Fields personality, path (roadPieces road or waypoint-parent entity), loop, autoPath, roadWidth, laneOffset, speedLimit, driving, seed. Methods setPath(points, loop), clearPath(), setPersonality(name), laps(), state(), stats(), resetStats(), linePoints(), respawnOnPath().
• aiDrivers.personalities — the personality tables, get, define, extend, names.
• aiDrivers.paths — resampling (Catmull-Rom), normals, curvature, racing line, lane offset, speed profile with braking points, nearest point.
• aiDrivers.traffic — one car list a second shared by every driver on the peer (torqueCars cars and VehicleControllers).
• aiDrivers.track — the test loop: points, grid slots, a builder (ground, asphalt, kerbs, start line) and a waypoint-entity builder.
• AiDriversShowcase (scene) — the loop and five cars.

How it behaves

• Path sources, in order: points given to setPath; the path entity (a roadPieces RoadPiece → require("roadPieces.roads").pathOf, else its children's positions in order); with autoPath, the nearest roadPieces road. Resampled to 2 m.
• Line: a lane lane metres right of the centre (commuter 1.8, tourist 1.6), or for lineUse > 0 a racing line inside roadWidth minus the car's half width.
• Learning the car: the planned braking drops to 92 % of the deceleration it measures under full brake, and the cornering g drops 7 % each time it runs more than 3 m wide in a corner, so one personality fits a kart and a box truck.
• Awareness: cars in a bending cone ahead set an ACC-style target speed (minGap + followGap·v); overtakers pull 2.8 m aside; everyone goes round a stalled car; a mutual stand-off is broken after 2.5 s by ignoring the blocker.
• Recovery (no car stays stuck for long): two clocks run every tick. One counts time under 1.5 m/s for any reason (wedged on a barrier, pinned by a car, stuck in a ditch, mid-drift or mid-U-turn); the other counts time without gaining 6 m along the path (crawling, circling, shunting back and forth). Planned stops (a tourist's pause, standing lost) hold both; they are short by design. Slow for 2 s → 1.6 s reverse, steering so the nose swings toward the path, the other lock on each retry. Slow for 5 s, a fourth reverse-out, or 8 s without progress (4 s when far off the road) → Car:respawn back on its line at the nearest clear point ahead (no other car within 8 m), facing along it, with any drift or tourist manoeuvre cancelled. A tourist's missed turn is capped (12 s overshoot, 6 s lost, 20 s U-turn before it is put back on the road). Flipped for 2 s → Car:reset() upright where it is. state() reports slowTime, noProgressTime, reverseTries and lastRecovery.
• Cost: only on the peer that owns the car, at 15-30 Hz, allocation-free per tick except the shared car list.

Known limits

• #1404 — built-in roads are in progress, so a driver follows a point list: a roadPieces road's centreline, waypoint entities, or points you give it.
• #20569 — the wheels do not read the ground's named surfaces; the car finds its grip itself, and the driver learns it only by measuring its braking and cornering, so its first corner on ice or gravel can run wide.
• #20654 — at full throttle with assists off a wheel can spin without limit; drivers keep the car's assists on.
• #20586 — there is no streaming terrain yet; a path is assumed to be on ground that is loaded.
• #21241 / #21242 — the path is not synced (a reference and a long point list): the AI runs only on the peer that owns the car (the host for spawned AI), and everyone else sees the car through its replicated pose and values. If that peer leaves, its AI cars stop.
• Recovery is a last resort — a car that stays slow is reversed out and, if that fails, put back on its line; it is not a planner, so a car can need several tries to get round a pile-up.
• #20946 — measured on the native desktop engine only.