# 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. ## Changes - **1.1.8**: declares roadPieces as a dependency, so installing aiDrivers brings it and AiDriver's road-following references resolve in a new world (1.1.7 installed without it, leaving those references unresolved and blocking a push). - **1.1.7**: drives vehiclesKit vehicles through `Vehicle:setIntent` and hands over to a seated person; `aimOffset` and `pace` fields.

# torqueCars Drivable cars that behave like machines, as one family switched by one setting. Twelve kinds in three looks, each with its own engine character, gearing and drive layout, and every part swappable while you drive. Built on the engine's own vehicle physics: `WheelCollider` tyres that spin and slip, a `ShaftNetwork` drivetrain (engine torque curve → clutch → gearbox → differentials → wheels) solved inside the physics step, and a `SoftBody` shell that crumples where it is hit and **stays crumpled** until the car is reset. ## First example Install torqueCars (it brings `driveSurfaces` for ground grip when you install that too). Then, with the world in **play**, run this from the console (`execute`) — or paste it into your scene's `entrypoint.luau` inside `function onLoad() ... end`: ```luau local Assemble = require("torqueCars.assemble") local car = Assemble.spawn({ kind = "rally", position = vector.create(0, 0.2, 6) }) -- W/S throttle and brake (S at a stop reverses), A/D steer, Space brake, -- Ctrl handbrake, E/Q shift, M auto/manual, R reset, Backspace respawn. ``` The car takes the player's driving controls at once (gamepad and touch too). To make a car **each joining player's own body**, build it under the scene's player prototype in `build.luau`: ```luau local Assemble = require("torqueCars.assemble") local body = entity.spawn("body", { parent = prototype }) Assemble.build(body, { kind = "coupe", look = "real" }) body.component.add("Car", { kind = "coupe", look = "real", control = "player" }) prototype.component.add("PlayerPrototype", { body = body, camera = rig }) ``` Add a `Garage` component to any scene entity and **G** opens the parts panel. ## The family: one setting each Every field below is on the `Car` component and can be changed live (from the garage, from code with `car:setPart(slot, name)`, or in the inspector): | field | values | |---|---| | `kind` | `hatchback` `coupe` `muscle` `rally` `drift` `pickup` `van` `suv` `buggy` `kart` `boxtruck` `electric` | | `look` | `lowpoly` `toy` `real` | | `paint` | `white` `red` `orange` `yellow` `green` `blue` `purple` `black` `silver` `teal` `pink` `brown` (empty = the kind's) | | `engine` | `i4` `turbo4` `v6` `v8` `v12` `diesel` `rotary` `electric` `kart` | | `gearbox` | `manual5` `manual6` `auto` `sequential` `direct` | | `diff` | `open` `lsd` `locked` | | `tyres` | `road` `sport` `slick` `drift` `offroad` `snow` `studded` `steel` | | `control` | `player` `script` (AI / code via `setIntent`) `none` | | `autoShift`, `assists` | auto gear changes; ABS + traction control | An empty part name means "the kind's own". All data is in `torqueCars.catalog`. ### Measured 0–100 km/h (stock, flat tarmac, assists on, simulated time) All twelve measured together on a 2 km tarmac strip with `Bench.accelerate`, full-rate controller. | kind | layout · engine · gearbox | 0–100 | real class | |---|---|---|---| | hatchback | FWD · 1.6 four 122 hp · 5-sp manual | 10.9 s | 9–11 s | | coupe | RWD · 3.5 V6 330 hp · 6-sp manual · LSD | 6.9 s | 5–6 s | | muscle | RWD · 6.2 V8 455 hp · 6-sp manual · LSD | 7.0 s | 4.5–5.5 s | | rally | AWD · 2.0 turbo four 300 hp · sequential | 5.2 s | 4–5 s | | drift | RWD · twin-rotor 240 hp · 5-sp · welded diff | 7.2 s | 5.5–6.5 s | | pickup | RWD · 6.2 V8 · 6-sp automatic | 8.6 s | 6.5–8 s | | van | FWD · 2.5 turbo-diesel 180 hp · 5-sp | 14.1 s | 11–14 s | | suv | AWD · 3.5 V6 · automatic | 7.4 s | 7–8.5 s | | buggy | RWD · 1.6 four · sequential · locked | 8.1 s | 6–7 s | | kart | RWD solid axle · 125cc 45 hp two-stroke · sequential | 7.7 s | 4–5 s | | boxtruck | RWD · diesel · automatic, 5.2 t | never: governed at 93 km/h (0–80 in 20.1 s) | 30–45 s | | electric | AWD · 300 kW dual motor · single speed | 4.3 s | 3.5–4.5 s | Measure your own with `torqueCars.bench` (`Bench.accelerate(car, 100)`, `Bench.brake(car, 60)`, `Bench.brakeRolling(car, 60)`); the bench turns the car's `lod` off. The powerful rear-drivers (muscle, coupe) and the kart are traction-limited off the line: traction control holds the driven tyres near their peak slip, and with it off they spin without limit (#20654), so they launch slower than their real twins. ### Measured 60–0 km/h braking (stock hatchback, road tyres, ABS, rolling start) | tarmac | concrete | sand | cobbles | gravel | mud | dirt | wet tarmac | grass | snow | ice | |---|---|---|---|---|---|---|---|---|---|---| | 17.2 m | 18.4 m | 19.0 m | 20.6 m | 22.0 m | 22.6 m | 23.2 m | 26.3 m | 27.3 m | 33.7 m | 113.8 m | Gravel stops 28 % later than tarmac, ice 6.6× later. Sand and mud stop shorter than their grip alone suggests because the wheels sink and plough (the surface's bogging drag), as they do in a real car. Studded tyres multiply ice grip 4.2×, snow tyres snow grip 1.9×, off-road tyres loose ground 1.35×. ### Measured damage A rally car driven into the valley's concrete crash wall at 60 km/h (crash detector closing speed 44–50 km/h, the rest absorbed in the first instants of contact) kept a permanent crush of **9.5 cm** nose-first and **12.7 cm** side-on, unchanged 5 s later. The dent stays until `reset()` or a respawn, which rebuild the shell undamaged. The rigid core spans the cabin (76 % of the length), so the shell's nose and tail are the crumple zones. ### Cost Per car on a desktop (native, in the editor): the driver runs at the physics tick, about 0.3–0.8 ms a step (network inputs are written only when they change; each `ShaftNetwork:set` costs ~0.2 ms), and the soft-body shell ~0.15–0.2 ms a step at resolution 5 (36–40 particles). Script-driven cars more than 60 m from this peer's own car run their controller every other step (`lod`, on by default). ## How it drives - **Engine**: full-throttle torque curve per engine (idle, redline, limiter); idle governor; turbo spool lag (turbo four, diesel); a rev limiter that cuts fuel in 70 ms bursts. Engine braking from friction and pumping losses. - **Clutch**: automatic — slips to launch, opens for every shift, re-engages (manual ≈0.3 s, sequential 80 ms, automatic slurs like a torque converter). - **Gearbox**: auto-shift by rpm and pedal (kickdown included) or manual E/Q; holding brake at a standstill selects reverse. - **Differentials**: open, limited-slip (preload + bias) or locked; AWD cars add a biased centre diff. - **Tyres**: grip curve per tyre set, multiplied by the ground under each wheel (`driveSurfaces`) and the set's affinity for that ground — studded tyres on ice, off-road tyres on gravel. - **Body**: a plastic soft-body shell held to the chassis along the cabin floor, so the nose and tail are crumple zones. A 60 km/h wall hit leaves about 10 cm of permanent crush (9.5 cm measured nose-first, 12.7 cm side-on). `car:reset()` (R) repairs it. `car.damage` counts from the shell's settled shape, so a fresh or respawned car reads 0 %. - **Cockpit**: the body draws its inner faces as dark cabin trim and leaves the glass open from inside, and every car carries a steering wheel in front of its seat, so a camera at `car.mountSeat` sits in a cabin and one at `car.mountHood` looks over the bonnet. - **Respawn**: `respawn()` (Backspace) takes the car back to where it stood once it had settled after spawning (a spawner that moves the car in its first second moves the spawn point with it), or to `setSpawn`'s point, set down on the ground there. - **Drag**: aerodynamic drag, rolling resistance and soft-ground bogging. ## Values a car publishes Gauges, engine sounds, cameras and AI read the car only through named values on the chassis (`car.rpm`, `car.kmh`, `car.gear`, `car.load`, …). The full list and the `Car` API are in `CONTRACT.md` in this package. ## Contents - `Car` component — the driver (input or script), drivetrain control, assists, damage, values. - `Garage` component — the live parts panel (G / d-pad up / touch). - `torqueCars.assemble` — builds a car under a chassis entity (`build`, `spawn`). - `torqueCars.catalog` — kinds, engines, gearboxes, diffs, tyres, paints. - `torqueCars.bodies` — the 36 body meshes, wheels and paints (three looks). - `torqueCars.bench` — 0–100 and braking measurements. - `torqueCars.cars` — registry of live cars (`Cars.all()`, `Cars.localPlayer()`). - `driveControls` input map — throttle, steer, brake, handbrake, boost, recover (keyboard, gamepad, touch); the car's own, so it does not depend on the engine's vehicle map. - `carControls` input map — shift, auto/manual, respawn, garage (keyboard, gamepad, touch). - `carGallery` scene — every kind in every look side by side. ## Multiplayer Each car is simulated by the peer that owns it (a player's car by that player, AI cars by the host); every other peer draws it from the owner's poses. The engine replicates the soft-body dents from the owner, so everyone sees the same crumpled panels, including a player who joins later. The values a voice, a gauge or a brake lamp needs (`car.rpm`, `car.load`, `car.throttle`, `car.gear`, `car.shiftCount`, `car.boost`, `car.skid`, `car.brake`, `car.impactCount`, …) are declared with a replication rate, so remote cars sound and light up as they drive. The part fields (`kind`, `engine`, `tyres`, …) are synced: a swap made in one player's garage reaches every peer. Driving intent and network inputs are local to the owner. Verified on one machine with the engine's replication read-outs; a second real client has not been connected yet. ## Known engine limits - **#20569** — wheels do not read the ground's named surfaces yet, so each car ray-casts under its wheels itself and asks `driveSurfaces` for the grip. - **#20610** — rolling resistance is in progress in the engine; the car applies its own rolling resistance and drag as forces and leaves `rollingResistance` off double-counting. - **#20543** — wheels have no volume and cannot come off: a crash dents the body but never knocks a wheel loose, and a wheel can clip through a wall the body stops at. - **#20654** — held at full throttle a wheel can spin up without limit; the rev limiter and traction control (assists) keep it in check, with assists off a stationary burnout can over-spin. - **#21001** — a drivetrain's cost grows quickly with its parts, so every car uses the smallest network for its layout (7 parts FWD/RWD, 9 AWD) and writes network inputs only when they change. - **#21241 / #21242** — synced entity references and lists with gaps do not reach other players; the car keeps none in synced fields (the shell's attachment is re-made on each peer).

# AiDriver An AI driver for the car it sits on. Put it on a car's chassis: a torqueCars `Car` (driven through `Car:setIntent`) or a builtin `VehicleController` (driven through its own `setIntent`, throttle -1..1). It only thinks on the peer that owns the car (`entity:isLocal()`), at the personality's rate (15-40 Hz), and keeps its inputs between ticks. What it does each tick: finds where it is along its line (nearest point, searched in a window around the last one; a whole-path search only after a knock), steers by pure pursuit at a lookahead that grows with speed plus yaw-rate feedback (damps the weave and catches oversteer), takes a target speed from the curvature ahead (`v = sqrt(latG * 9.81 / k)`, pulled down before corners by its braking deceleration), keeps a gap to the car ahead (a cone in front of it, against a car list shared by every driver and refreshed once a second), overtakes or goes round a stopped car, gets itself unstuck (under 1.5 m/s for 2 s, for any reason: 1.6 s reverse with the nose swinging toward the path, the other lock on each retry; still slow at 5 s, or 8 s without gaining 6 m along the path, 4 s when far off the road: respawned on its line at the nearest clear point ahead, no other car within 8 m, drift or tourist manoeuvre cancelled), resets upright when flipped for 2 s, and drives back to its line after being knocked off. It learns the car: the braking it plans for drops to what it measures, and the cornering g drops a little each time it runs wide. **Fields:** `personality` (commuter, aggressive, racer, drifter, tourist), `path` (a roadPieces road, or an entity whose children are waypoints in order), `loop`, `autoPath` (follow the nearest roadPieces road when nothing else is given), `roadWidth`, `laneOffset` (-1 = the personality's lane), `speedLimit` (m/s, 0 = none), `driving`, `seed`, `aimOffset` (metres right of its own line to aim for, kept inside the road: a pickup to grab), `pace` (0.3 to 1.6, multiplier on the speed it plans, read every tick: rubber-banding). **vehiclesKit vehicles:** on a vehiclesKit `Vehicle` (whose VehicleController is stepped from the Vehicle's own intent every physics step) the driver drives through `Vehicle:setIntent`, braking at a stop to reverse. When a person sits in the driver's seat it hands the controls back (`setIntent(nil)`) and waits until the seat is free again. **Methods:** `setPath(points, loop)`, `clearPath()`, `setPersonality(name)` (any name defined in `aiDrivers.personalities`), `laps()` → `{ count, last, best, times, current }` (physics seconds, start-line crossing to crossing), `state()` (mode, index, offPath, speed, targetSpeed, pedals, drift phase, body `slip`, `rearSlipAngle`/`rearSlipMean`/`rearSlipMax`, tourist state, stuck/reset counts, `slowTime`/`noProgressTime`/`reverseTries`/`lastRecovery`, learned `planGrip`/`planDecel`), `stats()` → `{ avgTickMs, maxTickMs, ticks, rate, msPerSecond }`, `resetStats()`, `linePoints()`, `respawnOnPath()` (nearest clear point on its line). **Values it publishes** on the chassis: `ai.hazard` (stopped or lost; replicated), `ai.lap`. ```luau local Assemble = require("torqueCars.assemble") local car = Assemble.spawn({ kind = "coupe", position = vector.create(0, 0.3, 0), control = "script" }) local ai = car.component.add("AiDriver", { personality = "racer", roadWidth = 9 }) ai:setPath({ vector.create(0, 0, 0), vector.create(0, 0, -120), vector.create(60, 0, -150), vector.create(80, 0, -20) }, true) ```

# torqueCars.assemble Builds a whole car under one chassis entity from a kind and part names: dynamic chassis with its centre of mass at the kind's height and weight split, four `WheelCollider` wheels with the tyre set's grip curve and drawn wheels, the `ShaftNetwork` drivetrain for the drive layout, and the plastic `SoftBody` shell held along the cabin floor. Idempotent: running `build` again updates the car in place (a live part swap). `spawn` builds a car and adds the `Car` component (synced in play). ```luau local Assemble = require("torqueCars.assemble") local car = Assemble.spawn({ kind = "pickup", look = "toy", position = vector.create(0, 0.2, 0), yaw = 0 }) ```

# aiDrivers.personalities How each kind of AI driver drives, as plain data tables that `AiDriver` reads every tick: target speed scale and cap, cornering g, planned braking deceleration, pedal and steering gains and smoothing, pure-pursuit lookahead, following gap, randomness, lane, how much of the road a racing line may use, and switches for overtaking, leaning on cars, drifting (target slip angle) and the tourist's moods (wander, missed turns, random stops, hesitations), plus the brain's tick rate. Built in: `commuter` (careful, modest speed, early braking, big gap, smooth), `aggressive` (fast, late braking, tailgates, overtakes, leans on cars), `racer` (racing line, brakes as late as grip allows, flat out on exits), `drifter` (handbrake flick into corners, holds the slide on countersteer and throttle; turns the car's assists off), `tourist` (slow, wanders, misses turns and U-turns back, stops for no reason). Add one with `define(name, table)`, usually from `extend(base, changes)`; `AiDriver:setPersonality(name)` then drives by it. ```luau local P = require("aiDrivers.personalities") P.define("granny", P.extend("commuter", { maxSpeed = 8, followGap = 4, label = "Granny" })) car.component.get("AiDriver"):setPersonality("granny") ```

# aiDrivers.track A ready-made ~1.2 km closed test loop for AI drivers and its builder. `points(origin)` gives the centreline control points in driving order (main straight, a right-hander into esses, a long sweeper, two hairpins, a fast kink), `centreline(origin, spacing)` the same splined and evenly spaced, `gridSlot(origin, slot)` a grid position behind the start line, `build({ origin, roadWidth, tile, synced, parent })` draws it (a 420 m grass ground box that is the only collider, flat asphalt tiles, a centre dash, red and white kerbs on the corners, a chequered start line) and `waypoints({ origin, parent, synced })` spawns the control points as an `aiPath` entity of waypoint children, ready for an AiDriver's `path` field. Used by the AiDriversShowcase scene and handy for testing any driving AI.

# 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 }) ```