# v2: vehicles

Handling, drivetrain, damage, classes, the Metro, interiors, customisation, networking, audio,
brands and models. Index: `agents/world-format-v2.md`. Schema: `agents/v2-formats.md`
section 11 (`handling`, `vehicle`). Brief: `agents/v2-l-vehicles.md`. Built: road vehicles v0
in `v2/sim/vehicles/` on kernel Rapier (`v2/sim/physics/`), Metro via the systems
(`systems.md`).

**Rapier's ray-cast vehicle can't give real handling:** it ports Bullet's `btRaycastVehicle`
(one friction-slip clamp per wheel, no slip-angle curve, no engine or differential), and the JS
binding v1 ships doesn't expose `roll_influence` (hence v1's own anti-roll torque). Rapier
keeps the chassis body, wheel casts and contacts; tyres and drivetrain are ours (plain JS now,
a Rust module later).

## Handling
- **Tyres:** per-wheel spin; forces from slip ratio and slip angle through a reduced Magic
  Formula (B, C, D, E) with a combined-slip friction ellipse; grip scales with load and
  `physmat.friction x wetGripMul/iceGripMul x wetness x compound x tyre heat x pressure`. Blend
  to a kinematic no-slip model below ~3 m/s (avoids Pacejka's divide-by-zero jitter). A brush
  model can swap in behind the same interface. The owned car sub-steps wheels x4 per tick;
  remote and traffic cars don't.
- **Assists** (named, tunable): speed-sensitive lock, yaw damping, handbrake rear-grip drop
  with a yaw cap, rollover guard, brake ramp, ABS/TCS, nitro.
- **Reference preset `core:handling/v1-arcade`** (`origin: "v1"`, car.js numbers) is a CI
  regression that must reproduce v1's feel. Target decided 2026-09-27 (orchestrator,
  delegated): today's v1 after the 2026-09-24 braking pass, re-measured by running v1's own
  car.js in Node (`v2/sim/vehicles/tools/measure-v1.mjs`): 0-60 mph 5.383 s, top 102.97 mph
  (v1's 46 m/s cap), turning circle 27.89 m at full lock, peak handbrake yaw 2.763 rad/s, slide
  recovery 0.867 s, 60-0 braking 23.5 m. **v2's hatch matches all five within 5%** (built).
  Body lean and dive stay cosmetic.

## Drivetrain
Engine torque table (v1's `torqueAt` as default), inertia, idle, redline, limiter, engine
braking; clutch as a torque-limited coupling; gearbox ratios, final drive, shift time,
auto/manual; open, locked or limited-slip differential (Jolt's model); FWD/RWD/AWD split. As
built, engine, clutch, gearbox and diff are solved together per sub-step. Electric drives
(Metro, e-buses, scooters) draw from the electricity system.

## Damage
- A vehicle is an ordinary `EntityClass`: panels and doors on hinges with `breakForce`, wheels
  on joints to suspension arms. A broken joint fires `onBreak` and the part becomes a prop; a
  lost wheel drops that corner onto the chassis (scrape and sparks).
- **Dents:** per-panel vertex-displacement buffers read in the vertex shader (GTA V /
  Wreckfest). Dents are events `{part, localPt, dir, mag}` replayed identically on every peer;
  persistent damage is a `DamageRow` blob. Colliders stay rigid.
- **Knock-on effects via systems:** holed radiator, coolant leak, engine heat into the heat
  field, power loss, seizure; holed fuel tank, a flammable puddle entity, server-owned fire,
  the tank exploding at temperature; tyre punctures from bullets, stingers or kerbs (rims mean
  low grip and sparks); battery and alternator power lights, siren and radio. v1's `wreck.js`
  stages (smoke, fire, critical) remain the summary health.

## Classes (five abstract bases)
- `core:vehicle_wheeled`: hatch, saloon, estate, SUV, van (v1's five loft kinds), hackney cab,
  private hire, police car (`siren`, `lightbar`), single and double-decker buses (tall centre
  of gravity, real rollover, two decks and stairs).
- `core:vehicle_twowheel`: motorbikes, bicycles, e-scooters with a keep-upright lean
  controller; big impulses throw the rider into ragdoll.
- `core:vehicle_rail`: Metro and East Coast Main Line.
- `core:vehicle_boat`: pontoon buoyancy, thrust and rudder, reading the Tyne's flow and tide.
- `core:vehicle_rotor`: v1 arcade flight as a preset; later collective/cyclic with assists.

## Rails (Metro)
Not free physics: cars on a track spline at distance `s` with 1D dynamics
(`m s'' = traction - brake - m g grade - rolling - drag`), each car posed from two bogies on a
kinematic body (so it shoves things and carries passengers as a moving frame, as v1's
`trains.js` does). Power from the overhead line: lose it and the train coasts to a stop
(built, with a power-cut test). Derailment (overspeed on a curve, or an obstruction impulse)
switches cars to dynamic bodies with breakable couplers. Signals and points are I/O entities.
Server-owned; networked as `(s, v)` per train.

## Interiors
Classes declare `interior` volumes (load bay, bus decks, Metro saloon, boat deck) and `seats[]`
(driver/passenger, pose, exposure, exit point). Occupants are simulated and replicated in
vehicle-local coordinates; frame acceleration feeds the active ragdoll (`simulation.md`).

## Catalogue, upgrades, customisation
A `vehicle` component: base, handling preset, wheels (steer, drive, brake, radius, tyre),
engine, gearbox, diff, upgrade `slots`, interior, assists. Upgrades are `ncl:vpart/*` classes
with `fits` tags and multiplicative `mods`; the instance stores
`kv.build = {slots, paint, livery, tune}` with tune clamped to declared ranges. Final stats =
class, then parts, then tune, computed identically everywhere; the server checks behaviour
against the build hash.

## Networking
The driver's peer owns the car; an empty car passes to the nearest peer; far traffic is the
server's kinematic spine, becoming physical near players (a physics loan, `networking.md`).
State at 20-30 Hz unreliable (position, smallest-three rotation, velocities, inputs, per-wheel
compression and spin as a byte each), with Rocket League-style input decay for extrapolation.
Reliable events: part detached, dent, tyre burst, doors, horn, siren.

## Audio
`engine{rpm, load, throttle, gear}` drives granular engine audio; per-wheel slip x surface
drives skids; suspension bumps, scrapes, impacts, shifts, turbo, horn, siren. Metro: traction
whine from `v`, rail-joint clack at fixed `s` intervals, overhead-line arcing.

## Brands: parody, like GTA
Official `ncl` content ships parody makes only. UK/EU trademark law has no US-style realism
defence, and distinctive shapes are protected (the LEVC TX taxi, the Mini): the hackney is a
generic cab. Invented bus operators and liveries (not Stagecoach, Go North East). The Metro
keeps real stations and route numbers but parodies the "M" logo and varies the livery. Brand
names come from an LLM pass checked against UKIPO. Mods may ship real brands at their author's
risk, flagged in the manifest.

## Where models come from
1. Parametric first: v1's `carbody.js` loft generator as the fallback for any car or van, with
   parts cut at authored seams.
2. Kit-bash kits (Kenney Car Kit, CC0; Quaternius Cars under the QAL, see `characters.md`)
   for parts and proportions.
3. AI meshes arrive as one piece and need part segmentation before they are catalogue entries;
   until then, traffic LOD shells only. Avoid Sketchfab CC-BY replicas of real cars.