# 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: | personality | drives like | |---|---| | `commuter` | careful: a modest speed (15 m/s), its own lane on the right, early gentle braking, a big following gap, smooth inputs | | `aggressive` | fast and late on the brakes, tailgates (0.35 s), pulls out to overtake, leans on whoever is alongside | | `racer` | a minimum-curvature racing line across the full road width (outside, apex, outside), corner speeds from `v = sqrt(latG·g/k)` with braking points as late as its measured brakes allow, flat out on exits | | `drifter` | flicks and handbrakes into corners, then holds the slide on countersteer and throttle (target ~28° body slip, yaw-rate damped); turns the car's assists off | | `tourist` | lost: slow, wanders in its lane, sometimes misses a corner, stops, and U-turns back to it, stops for no reason, hesitates (publishes `ai.hazard`) | 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`): ```luau 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`, `aimOffset` (metres right of its line to aim for, e.g. a pickup), `pace` (multiplier on its planned speed, for rubber-banding). 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.

# aiDrivers.paths The route geometry AI drivers drive by, computed once per path: `resample(points, loop, spacing)` (even spacing; sparse waypoints are joined with a Catmull-Rom spline), `normals` (right of travel), `curvatures` (signed 1/m, positive turning right, smoothed), `racingLine(points, loop, halfWidth)` (each point slid sideways within the road to minimise curvature: outside on entry, apex clipped, outside on exit), `offset` (a lane), `speedProfile(points, loop, curvature, { latG, maxSpeed, decel })` (cornering limit `sqrt(latG*g/k)` with braking points worked backwards from every corner), `distances` and `nearest`. Pure functions over `{vector}`; `AiDriver` calls them, and anything else that needs a racing line or a speed plan (a ghost car, a minimap line, a track editor) can too. ```luau local Paths = require("aiDrivers.paths") local pts = Paths.resample(waypoints, true, 2) local line = Paths.racingLine(pts, true, 3.5) local v = Paths.speedProfile(line, true, Paths.curvatures(line, true), { latG = 0.9, maxSpeed = 60, decel = 8 }) ```