lecodes-cli 0.18.0 → 0.18.2

package/runtime/sdk/gl/Vehicle.ts

@@ -2,28 +2,28 @@
 // node is the CHASSIS: it needs a Shape (its collision body) and must NOT also carry a Physics aspect
 // — Vehicle owns its rigid body, the way CharacterController owns its controller.
 //
-//   const car = new Node("car").add(bodyModel, wheelFL, wheelFR, wheelRL, wheelRR)
+//   const car = new Node('car')
+//     .add(body, wheelFL.aspect(Wheel), wheelFR.aspect(Wheel),
+//                wheelRL.aspect(Wheel), wheelRR.aspect(Wheel))
 //     .aspect(Shape, { box: [0.9, 0.4, 2.1] })
-//     .aspect(Vehicle, { mass: 1200, wheels: [
-//       { node: wheelFL }, { node: wheelFR }, { node: wheelRL }, { node: wheelRR },
-//     ] })
+//     .aspect(Vehicle, { mass: 1200 })
 //
 //   setLoop(() => {
-//     const gas = (Input.key("KeyW") ? 1 : 0) - (Input.key("KeyS") ? 1 : 0)
-//     car.vehicle.drive(gas, (Input.key("KeyD") ? 1 : 0) - (Input.key("KeyA") ? 1 : 0), 0, Input.key("Space") ? 1 : 0)
-//     hud.text = `${Math.round(car.vehicle.speed * 3.6)} km/h  gear ${car.vehicle.gear}`
+//     const gas = (Input.key('KeyW') ? 1 : 0) - (Input.key('KeyS') ? 1 : 0)
+//     car.vehicle.drive(gas, (Input.key('KeyD') ? 1 : 0) - (Input.key('KeyA') ? 1 : 0), 0, Input.key('Space') ? 1 : 0)
+//     hud.text = `${Math.round(car.vehicle.speed * 3.6)} km/h  gear ${car.gearbox.gear}`
 //   })
 //
-// That is the whole minimum: every wheel property is derived from where the wheel NODE sits. Wheels
-// are grouped into axles by their Z, the FRONT axle steers, the rear one drives and holds the
-// handbrake — override any of it per wheel (`steer`, `powered`, `handbrake`) or per vehicle
-// (`powered: "all"`). Chassis space is forward −Z / up +Y — the SDK's own convention, the one
-// `node.forward` reports: if the model faces the other way, rotate the MODEL (a child), never the
-// chassis node.
+// This aspect is the car as a WHOLE: mass, engine, steering, aero. Anything per-wheel lives on the
+// `Wheel` aspect of the wheel's own node (which is where Jolt keeps it too), and the gearbox is the
+// `Gearbox` aspect — policy, not physics. Vehicle collects every Wheel under itself, groups them into
+// axles by Z, and installs a default Gearbox if the node has none.
 //
-// Physics OWNS the chassis transform while a vehicle is attached — drive it with `drive()`, don't set
-// node.position. Each wheel node's LOCAL transform is overwritten every step (suspension travel, steer
-// angle, spin), so a wheel model that needs a corrective rotation must wear it on a child node.
+// Chassis space is forward −Z / up +Y — the SDK's own convention, the one `node.forward` reports: if
+// the model faces the other way, rotate the MODEL (a child), never the chassis node. Physics owns the
+// chassis transform: drive it with `drive()`, never per-frame `node.position` writes.
+//
+// Layering, and why it is where it is: docs/vehicle-rework-plan.md.
 
 import { Aspect } from "../core/Aspect"
 import type { FieldMeta } from "../core/fields"
@@ -32,204 +32,161 @@ import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
 import { cw, type QuatLike } from "../math/quat"
 import { Gizmos } from "../scene/gizmos"
 import { glState } from "./state"
+import { Gearbox } from "./Gearbox"
 import { Node } from "./Node"
-import { Physics } from "./Physics"
+import { DEFAULT_FRICTION, Physics } from "./Physics"
 import { Shape } from "./Shape"
+import { STATE_HEADER, WHEEL_STATE, Wheel } from "./Wheel"
 
-/** Which axle the engine drives. Per-wheel `powered` overrides it. */
+/** Which axle the engine drives. A wheel's own `drive` overrides it. */
 export type DriveLayout = "rear" | "front" | "all"
 
-export interface WheelConfig {
-  /** The node posed by this wheel — a child of the chassis, or its name (looked up under the
-   *  chassis). Optional: a wheel can be physics-only (no visual). */
-  node?: Node | string
-  /** Where the wheel CENTRE sits when the car rests on flat ground, in chassis space. Defaults to
-   *  the wheel node's own position, so a placed model needs nothing here. */
-  position?: Vec3Like
-  /** Wheel radius in metres (default 0.35). Set it to match the model — too small and the car
-   *  scrapes, too large and it floats. */
-  radius?: number
-  /** Wheel width in metres (default 0.25). */
-  width?: number
-  /** Does this wheel steer? Default: the wheels on the front axle. */
-  steer?: boolean
-  /** Does the engine drive this wheel? Default: from the vehicle's `powered` layout. */
-  powered?: boolean
-  /** Foot brake on this wheel (default true). */
-  brake?: boolean
-  /** Handbrake on this wheel. Default: every non-steering wheel (locking the front wheels of a
-   *  moving car is not a handbrake turn, it's a crash). */
-  handbrake?: boolean
-  /** Axle group, front to back. Derived from Z when omitted; set it for a car whose wheels are not
-   *  in neat left/right pairs. Pairs an axle's wheels for the differential and the anti-roll bar. */
-  axle?: number
-}
+/**
+ * How an axle's two wheels share torque.
+ *  - `lsd` — limited slip (Jolt's 1.4 ratio), the sane default.
+ *  - `open` — fully open: a lifted or spinning wheel takes ALL the torque.
+ *  - `locked` — both wheels forced to the same speed. Breaks traction predictably: the drift diff.
+ *  A number is the raw max/min wheel-speed ratio (> 1; smaller is more locked).
+ */
+export type DifferentialMode = "lsd" | "open" | "locked"
 
-export interface SuspensionConfig {
-  /** How far the wheel can travel, in metres (default 0.3). */
-  travel?: number
-  /** Spring frequency in Hz — bigger is stiffer (default 1.5; a race car is ~2.5, a truck ~1). */
-  stiffness?: number
-  /** Damping ratio, 0..1 (default 0.5). Low values pogo. */
-  damping?: number
+export interface EngineConfig {
+  /** Peak torque in N·m (default 500). The single biggest "how fast is it" knob. */
+  torque?: number
+  /** Redline in RPM (default 6000). */
+  maxRpm?: number
+  /** Idle RPM (default 1000) — the engine never falls below it. */
+  idleRpm?: number
+  /**
+   * The engine's CHARACTER: a flat list `[rpm, torque, rpm, torque, …]` in NORMALISED units — x is
+   * a fraction of the redline, y a fraction of `torque`. Left out, Jolt's own broad curve is used.
+   *
+   * `[0, 0.8, 0.66, 1, 1, 0.8]` is an ordinary petrol engine (peak two thirds up, falling to the
+   * redline); `[0, 1, 1, 1]` is flat, which is what an electric motor feels like.
+   */
+  curve?: number[]
+  /** Moment of inertia in kg·m² (default 0.5) — how eagerly it revs when the clutch is out. */
+  inertia?: number
+  /** Engine braking: angular damping of the engine itself (default 0.2). */
+  braking?: number
 }
 
 export interface SteeringConfig {
-  /** The lock still available, in degrees, once the car reaches `speed` (default 10). `0` turns the
-   *  taper off entirely — full lock at any speed. */
+  /** Steering lock in degrees at a standstill (default 35). */
+  lock?: number
+  /**
+   * The lock still available, in degrees, once the car reaches `speed` (default 10) — what stops a
+   * car over-driving its own front tires.
+   *
+   * A tire makes its peak grip at a few degrees of slip angle, and the steering angle a corner needs
+   * falls with the SQUARE of speed. Holding full lock at 100 km/h therefore asks the front for
+   * several times what it can give: the tires saturate, the car ploughs on, and the wheel stops
+   * answering. In between the lock eases on `(1 − v/speed)²`, which tracks the real curve closely.
+   * `0` turns the taper off — full lock at any speed.
+   */
   atSpeed?: number
   /** The speed in m/s at which the lock has fallen to `atSpeed` (default 30 ≈ 108 km/h). */
   speed?: number
-  /** How fast the front wheels may turn, in degrees per second (default 220). `0` = instantly. */
+  /** How fast the front wheels may turn, in degrees per second (default 220). A keyboard asks for
+   *  full lock in one frame, which no steering wheel can do, and that step alone snaps a tire past
+   *  its peak. `0` = instantly. */
   rate?: number
 }
 
-export interface EngineConfig {
-  /** Peak engine torque in N·m (default 500). The single biggest "how fast is it" knob. */
-  torque?: number
-  /** Redline in RPM (default 6000). */
-  maxRpm?: number
-}
-
-/** One wheel's live state (`vehicle.wheel(i)`) — the same numbers Jolt's own vehicle debug overlay
- *  shows. `gripLateral` saturating while `slipAngle` climbs is what "it will not turn at speed"
- *  looks like in data. */
-export interface WheelState {
-  /** Touching the ground this step. */
-  contact: boolean
-  /** Longitudinal slip RATIO: 0 = rolling in sync with the ground, ~1 = spinning up or locked.
-   *  Unsigned — it does not say whether the tire is driving or braking. */
-  slip: number
-  /** Slip ANGLE in degrees: how far the tire's travel direction is off from where it points.
-   *  Unsigned, 0..90. Past the friction curve's peak (~3°) the tire is sliding sideways. */
-  slipAngle: number
-  /** Longitudinal friction coefficient actually applied this step (curve value × ground friction). */
-  gripLong: number
-  /** Lateral friction coefficient actually applied this step — the cornering budget. */
-  gripLateral: number
-  /** Current suspension length in metres (short = compressed). */
-  suspension: number
-  /** Steer angle in degrees, positive to the right. */
-  steer: number
-  /** Wheel spin in rad/s (× radius ≈ the speed the tire is laying down). */
-  spin: number
+/**
+ * Aerodynamics. Both numbers are quoted the same way — **a fraction of the car's own weight at
+ * 30 m/s (108 km/h)** — and both grow with the SQUARE of speed from there, so `0.5` at 30 m/s is
+ * `2.0` at 60 m/s. One mental model for both, and no drag coefficients or frontal areas to invent.
+ */
+export interface AeroConfig {
+  /**
+   * Downforce (default 0 — a car with no wing). The knob that decides whether a car corners better
+   * or worse the faster it goes: tire grip is a constant, but the force a corner demands grows with
+   * v², so with no downforce every car runs out of road at speed. `0.6` roughly doubles a car's
+   * cornering at 150 km/h; a road car is nearer `0.1`, a race car well past `1`.
+   *
+   * It presses along the CHASSIS' own down axis (that is what keeps a car planted over a crest) and
+   * only while a wheel is on the ground — a car on its roof is never launched by its own wing.
+   */
+  downforce?: number
+  /** Air resistance (default 0.03 — an ordinary car). What gives a car a top speed at all. */
+  drag?: number
 }
 
-/** How an axle's two wheels share torque.
- *  - `'lsd'` — limited slip (Jolt's 1.4 ratio), the sane default.
- *  - `'open'` — fully open: a lifted or spinning wheel takes ALL the torque.
- *  - `'locked'` — both wheels forced to the same speed. Breaks traction predictably: the drift diff.
- *  A number is the raw max/min wheel-speed ratio (> 1; smaller is more locked). */
-export type DifferentialMode = "lsd" | "open" | "locked"
-
-const DEFAULT_GEARS = [ 2.66, 1.78, 1.3, 1.0, 0.74 ]
-/** Floats vehicleGetState writes per wheel — see the WheelState fields. */
-const WHEEL_STATE = 8
-/** Limited-slip ratios: `<= 0` tells the host "fully open". */
+/** Blob v5 — see bridges.d.ts for the field-by-field layout. */
+const BLOB_VERSION = 5
+const BLOB_HEADER = 21
+const BLOB_WHEEL = 15
 const DIFFERENTIALS: Record<DifferentialMode, number> = { lsd: 1.4, open: 0, locked: 1 }
 const GRAVITY = 9.81          // only used to place the wheels at their resting height
 const AXLE_EPS = 0.35         // wheels within this many metres in Z are the same axle
 const clamp = (v: number, lo: number, hi: number): number => (v < lo ? lo : v > hi ? hi : v)
 
-/** A wheel's STRUCTURE, resolved once at attach: where it is, what it does. The tunable numbers
- *  (lock in degrees, brake torques) are applied in _buildSettings, so re-tuning picks them up. */
-type ResolvedWheel = {
-  entityId: number
-  cx: number, cy: number, cz: number     // wheel centre at rest, chassis space
-  radius: number
-  width: number
-  steers: boolean
-  powered: boolean
-  braked: boolean
-  handbraked: boolean
-  axle: number
-}
-
 export class Vehicle extends Aspect<"vehicle", Node> {
   static readonly aspect = "vehicle"
 
   /** Chassis mass in kg (default 1200). Wheels are massless in this model. */
   mass = 1200
-  /** The wheels, front to back. At least one; four is a car. */
-  wheels: WheelConfig[] = []
-  /** Which axle the engine drives (default "rear"). */
-  powered: DriveLayout = "rear"
-  /** Steering lock in degrees (default 35) for the wheels that steer — at a standstill. How much of
-   *  it survives at speed is `steering`'s job. */
-  maxSteer = 35
+  /** Centre of mass height in chassis space (metres, negative = lower). Left out, it drops to halfway
+   *  down the chassis shape — a car with its mass at the shape's centre tips over. */
+  centerOfMass?: number
+  /** Which axle the engine drives (default "rear"). A wheel's own `drive` overrides it. */
+  driveAxle: DriveLayout = "rear"
+  /** Differential lock across each driven axle. `locked` is the drift setup — both wheels turn
+   *  together, so the pair lets go as a pair. Live: re-configure the aspect to switch it mid-drive. */
+  differential: DifferentialMode | number = "lsd"
   /**
-   * Speed-sensitive steering — what stops a car from over-driving its own front tires.
-   *
-   * A tire makes its peak grip at a few degrees of slip angle, and the steering angle a corner
-   * actually needs falls with the SQUARE of speed. So holding full lock at 100 km/h asks the front
-   * for several times what it can give: the tires saturate, the car ploughs straight on, and the
-   * wheel stops answering. `atSpeed` is the lock left once the car reaches `speed`; in between it
-   * eases on `(1 − v/speed)²`, which tracks the real curve closely.
+   * Anti-roll bars between each axle's wheels — what stops a car rolling onto its inside wheels in a
+   * fast corner. `true` (default) is a bar 0.01 as stiff as the wheel's own spring; a number is that
+   * ratio directly, and `0` / `false` removes the bars.
    *
-   * `rate` is the other half: a keyboard asks for full lock in a single frame, which no steering
-   * wheel can do, and that step alone is enough to snap a tire past its peak.
+   * **The numbers are far smaller than they look and the gain is steep** — Jolt's bar feeds
+   * `lengthDifference × stiffness × dt` as a bias into the suspension's own soft constraint, so 4%
+   * of the spring already flattens the body. Measured on a 1250 kg car: `0` → 1.3° of roll at 0.86 g,
+   * `0.01` → 0.6°, `0.15` → 0.2° (flat), `0.5` → the car HOPS.
    *
-   * Both run inside the physics step, so they behave the same at any frame rate. `{ atSpeed: 0,
-   * rate: 0 }` gives the raw lock, instantly — arcade-direct, and how it behaved before this existed.
+   * This is the knob for how much a car visibly LEANS, not for wheel lift: bars change how far the
+   * body tips, not how much load transfers. For lift, lower `centerOfMass`.
    */
-  steering: SteeringConfig = { atSpeed: 10, speed: 30, rate: 220 }
-  /**
-   * Tire grip multiplier (default 1). Below 1 slides, above 1 sticks.
-   *
-   * This scales the tire's own friction curve. The grip a wheel ACTUALLY gets is combined with the
-   * ground it stands on — `sqrt(tire × groundFriction)` — and a body's friction defaults to 0.6, so
-   * a road you want a car to really corner on wants `Physics { friction: 1 }` (read
-   * `wheel(i).gripLateral` to see what the tires actually got).
-   */
-  grip = 1
-  /** Friction of the CHASSIS body itself — how it slides when it lands on its roof or side.
-   *  Nothing to do with the tires; those are `grip` × the ground's friction. */
-  chassisFriction = 0.6
-  /** Foot-brake torque per wheel in N·m (default 1500); the handbrake pulls 3× on its wheels. */
-  brakeTorque = 1500
-  /** Anti-roll bars between each axle's wheels (default on) — what keeps a car from tripping in a
-   *  fast corner. */
-  antiRoll = true
+  antiRoll: boolean | number = true
   /** Pitch/roll limit in degrees (default 60) before the constraint rights the car. 180 turns it off. */
   maxTilt = 60
-  /** Suspension: one travel distance, one stiffness, one damping. */
-  suspension: SuspensionConfig = { travel: 0.3, stiffness: 1.5, damping: 0.5 }
-  /** Engine: peak torque + redline. */
-  engine: EngineConfig = { torque: 500, maxRpm: 6000 }
-  /** Forward gear ratios, shifted automatically. Reverse is fixed. */
-  gears: number[] = DEFAULT_GEARS
-  /** Differential lock across each driven axle (and between axles on an all-wheel-drive car).
-   *  `'locked'` is the drift setup — both wheels turn together, so the pair lets go as a pair.
-   *  Live: re-configure the aspect to switch it mid-drive (see `onReconfigure`). */
-  differential: DifferentialMode | number = "lsd"
-  /** Centre of mass height in chassis space (metres, negative = lower). Left out, it drops to
-   *  halfway down the chassis shape — a car with its mass at the shape's centre tips over. */
-  centerOfMass?: number
-
-  /** Scene-editor inspector: the flat, tunable half. */
+  /** Friction of the CHASSIS body itself — how it slides when it lands on its roof or side. Nothing
+   *  to do with the tires; those are the `Wheel`'s `tire.grip` × the ground's friction. */
+  friction = DEFAULT_FRICTION
+  /** Strength of the clutch when fully engaged (default 10). Small values slip; large ones weld the
+   *  engine to the wheels. The `Gearbox` scales it 0..1 while shifting. */
+  clutchStrength = 10
+
+  engine: EngineConfig = { torque: 500, maxRpm: 6000, idleRpm: 1000, inertia: 0.5, braking: 0.2 }
+  steering: SteeringConfig = { lock: 35, atSpeed: 10, speed: 30, rate: 220 }
+  aero: AeroConfig = { downforce: 0, drag: 0.03 }
+
+  /** Scene-editor inspector: the flat, tunable half. The grouped objects are edited in code. */
   static fields: FieldMeta<Vehicle> = {
     mass: { min: 1, step: 10 },
-    powered: { label: "Drive", options: [ "rear", "front", "all" ] },
-    maxSteer: { label: "Steering lock", min: 0, max: 80, step: 1 },
-    grip: { min: 0.1, max: 3, step: 0.05 },
-    chassisFriction: { label: "Chassis friction", min: 0, max: 2, step: 0.05 },
-    brakeTorque: { label: "Brake torque", min: 0, step: 50 },
-    maxTilt: { label: "Max tilt", min: 0, max: 180, step: 5 },
+    driveAxle: { label: "Drive", options: [ "rear", "front", "all" ] },
     differential: { options: [ "lsd", "open", "locked" ] },
-    wheels: { hidden: true },
-    gears: { hidden: true },
-    suspension: { hidden: true },
+    antiRoll: { label: "Anti-roll" },
+    maxTilt: { label: "Max tilt", min: 0, max: 180, step: 5 },
+    friction: { label: "Chassis friction", min: 0, max: 2, step: 0.05 },
+    clutchStrength: { label: "Clutch", min: 0.5, max: 100, step: 0.5 },
     engine: { hidden: true },
     steering: { hidden: true },
+    aero: { hidden: true },
   }
   static editor = { rebuild: true }
 
   private _id = 0
   private _bodyId = 0
   private _builtMass = 0
-  private _resolved: ResolvedWheel[] = []
-  private _state = new Float32Array(7 + WHEEL_STATE)
+  private _wheels: Wheel[] = []
+  private _state = new Float32Array(STATE_HEADER)
   private _stateFrame = -1
+  private _throttle = 0
+  private _steer = 0
+  private _brake = 0
+  private _handbrake = 0
 
   onAttach(): void {
     if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
@@ -247,26 +204,42 @@ export class Vehicle extends Aspect<"vehicle", Node> {
     if (this.node.has(Physics)) {
       throw new Error("Vehicle owns its own rigid body — remove the Physics aspect from the chassis node (put `mass` on the Vehicle instead)")
     }
-    if (this.wheels.length === 0) throw new Error("Vehicle needs at least one wheel — `wheels: [{ node: … }, …]`")
 
-    this._resolved = this._resolve()
+    this._wheels = this._collectWheels()
+    if (this._wheels.length === 0) {
+      throw new Error("Vehicle found no wheels — put a Wheel aspect on each wheel node under the chassis: wheelFL.aspect(Wheel)")
+    }
+
     const shapeId = shape._claim()  // the vehicle owns the shape; drop the pick-only body
-    const ids = new Uint32Array(this._resolved.map((w) => w.entityId))
-    this._id = _creator.vehicleCreate(this.node.id, shapeId, this._buildSettings(), ids)
+    this._id = _creator.vehicleCreate(this.node.id, shapeId, this._buildSettings())
     if (!this._id) {
       console.warn(`Vehicle: the engine refused the settings for "${this.node.name}" — check the wheel list`)
       shape._recreatePickBody()
       return
     }
     this._bodyId = _creator.vehicleBodyId ? _creator.vehicleBodyId(this._id) : 0
-    if (this._bodyId) _creator.physicsSetFriction?.(this._bodyId, this.chassisFriction)
+    // The chassis body owns the node's transform, so route position writes to it (see Node._xf) —
+    // `car.position = p` places the car instead of being silently overwritten by the next sync. It is
+    // the WEAK form of the operation: it keeps the car's velocity and its roll, so a respawn still
+    // wants `reset(p)`, which also uprights it and clears engine, gearbox and wheel spin.
+    this.node._xf = this._bodyId
+    this.node._xfKind = this._bodyId ? 2 : 0
+    if (this._bodyId && this.friction !== DEFAULT_FRICTION) {
+      _creator.physicsSetFriction?.(this._bodyId, this.friction)
+    }
     this._builtMass = this.mass
-    this._state = new Float32Array(7 + this._resolved.length * WHEEL_STATE)
+    this._state = new Float32Array(STATE_HEADER + this._wheels.length * WHEEL_STATE)
+    // A car with no gearbox still has to drive: install the default automatic.
+    if (!this.node.has(Gearbox)) this.node.aspect(Gearbox)
   }
 
   onDetach(): void {
     if (this._id) { _creator.vehicleDestroy(this._id); this._id = 0; this._bodyId = 0 }
-    this.node.get(Shape)?._recreatePickBody()
+    for (const w of this._wheels) w._vehicle = null
+    this._wheels = []
+    this.node._xf = 0
+    this.node._xfKind = 0
+    this.node.get(Shape)?._recreatePickBody()   // hands the routing back to the pick body
   }
 
   /**
@@ -275,41 +248,42 @@ export class Vehicle extends Aspect<"vehicle", Node> {
    *
    *   car.aspect(Vehicle, { differential: drift ? 'locked' : 'lsd' })
    *
-   * Live: `differential`, `grip`, `maxSteer`, `steering`, `engine`, `gears`, `brakeTorque`,
-   * `maxTilt`, `chassisFriction`. Everything else describes the car's STRUCTURE — `mass`,
-   * `centerOfMass`, `wheels`, `suspension`, `powered`, `antiRoll` — and is baked into the constraint
-   * at attach; to change one of those, detach and attach the aspect again.
+   * Live: `differential`, `engine`, `steering`, `aero`, `maxTilt`, `friction`, `clutchStrength`, and
+   * every `Wheel`'s `tire.grip` and brake torques. Everything else describes the car's STRUCTURE —
+   * `mass`, `centerOfMass`, which wheels exist and where, their suspension, `driveAxle`, `antiRoll` — and
+   * is baked into the constraint at attach; to change one of those, re-attach the aspect.
    */
   onReconfigure(): void {
     if (!this._id) return
-    if (this.wheels.length !== this._resolved.length) {
-      console.warn("Vehicle: the wheel list can't change on a live car — remove and re-add the aspect")
-      return
-    }
     if (this.mass !== this._builtMass) {
       console.warn(`Vehicle: mass is fixed once the body exists (still ${this._builtMass} kg) — re-add the aspect to change it`)
       this.mass = this._builtMass
     }
     _creator.vehicleSetTuning?.(this._id, this._buildSettings())
-    if (this._bodyId) _creator.physicsSetFriction?.(this._bodyId, this.chassisFriction)
+    if (this._bodyId) _creator.physicsSetFriction?.(this._bodyId, this.friction)
   }
 
   /** Native vehicle id (0 until attached / no physics support). */
   get id(): number { return this._id }
   /** The chassis rigid-body id — the same handle the plain body calls take. */
   get bodyId(): number { return this._bodyId }
+  /** The wheels, in blob order (front axle first). */
+  get wheels(): readonly Wheel[] { return this._wheels }
 
   // --- driving --------------------------------------------------------------------------------
 
   /**
    * The driver's controls, all in [-1, 1] (brakes in [0, 1]). Sticky: the last values keep applying
-   * until the next call, so a held key does not need re-sending. `forward < 0` engages reverse once
-   * the car has stopped (the gearbox is automatic).
+   * until the next call, so a held key does not need re-sending. `forward < 0` asks for reverse; the
+   * `Gearbox` engages it once the car has stopped.
    */
   drive(forward: number, steer = 0, brake = 0, handbrake = 0): this {
     if (this._id) {
-      _creator.vehicleSetInput(this._id, clamp(forward, -1, 1), clamp(steer, -1, 1),
-        clamp(brake, 0, 1), clamp(handbrake, 0, 1))
+      this._throttle = clamp(forward, -1, 1)
+      this._steer = clamp(steer, -1, 1)
+      this._brake = clamp(brake, 0, 1)
+      this._handbrake = clamp(handbrake, 0, 1)
+      _creator.vehicleSetInput(this._id, this._throttle, this._steer, this._brake, this._handbrake)
     }
     return this
   }
@@ -324,6 +298,8 @@ export class Vehicle extends Aspect<"vehicle", Node> {
     const q: QuatLike = rotation ?? [ 0, wq.y, 0, wq.w ]
     _creator.vehicleReset(this._id, cx(p), cy(p), cz(p), cx(q), cy(q), cz(q), cw(q))
     this._stateFrame = -1
+    const box = this.node.get(Gearbox)
+    if (box) box.gear = 0
     return this
   }
 
@@ -333,7 +309,12 @@ export class Vehicle extends Aspect<"vehicle", Node> {
     return this
   }
 
-  // --- readouts (one native read per frame, shared by every getter) ----------------------------
+  /** @internal The Gearbox's latched pair: the one ratio the engine runs, and the clutch envelope. */
+  _setTransmission(ratio: number, clutch: number): void {
+    if (this._id) _creator.vehicleSetTransmission(this._id, ratio, clamp(clutch, 0, 1))
+  }
+
+  // --- readouts (one native read per frame, shared by the car and every wheel) -------------------
 
   private _read(): Float32Array {
     if (this._id && this._stateFrame !== glState.frame) {
@@ -343,177 +324,150 @@ export class Vehicle extends Aspect<"vehicle", Node> {
     return this._state
   }
 
+  /** @internal One value out of wheel `index`'s slice — see WHEEL_STATE in Wheel.ts. */
+  _wheelState(index: number, k: number): number {
+    const s = this._read()
+    const at = STATE_HEADER + index * WHEEL_STATE + k
+    return at < s.length ? s[at]! : 0
+  }
+
   /** Speed along the car's forward axis in m/s — negative when reversing (× 3.6 for km/h). */
   get speed(): number { return this._read()[0]! }
   /** Engine revolutions per minute. */
   get rpm(): number { return this._read()[1]! }
-  /** Current gear: -1 reverse, 0 neutral, 1… forward. */
-  get gear(): number { return this._read()[2]! }
   /** How many wheels are touching the ground. */
-  get wheelsOnGround(): number { return this._read()[3]! }
+  get wheelsOnGround(): number { return this._read()[2]! }
   /** Any wheel on the ground — false while airborne. */
-  get grounded(): boolean { return this._read()[3]! > 0 }
+  get grounded(): boolean { return this._read()[2]! > 0 }
   /** Chassis velocity in world units/s (fresh Vec3). */
-  get velocity(): Vec3 { const s = this._read(); return new Vec3(s[4]!, s[5]!, s[6]!) }
-  /** The steering lock, in degrees, the car is allowed at its current speed — `maxSteer` at rest,
+  get velocity(): Vec3 { const s = this._read(); return new Vec3(s[3]!, s[4]!, s[5]!) }
+  /** The last throttle handed to `drive()` — what the gearbox reads to know which way you want to go. */
+  get throttle(): number { return this._throttle }
+  /** The last steer input handed to `drive()`, [-1, 1]. */
+  get steerInput(): number { return this._steer }
+  /** The last foot-brake input handed to `drive()`, [0, 1] — the pedal, not the resulting force. */
+  get brake(): number { return this._brake }
+  /** The last handbrake input handed to `drive()`, [0, 1]. */
+  get handbrake(): number { return this._handbrake }
+  /** Current gear from the attached `Gearbox`: −1 reverse, 0 neutral, 1… forward. */
+  get gear(): number { return this.node.get(Gearbox)?.gear ?? 0 }
+  /** The steering lock, in degrees, the car is allowed at its current speed — the full lock at rest,
    *  falling to `steering.atSpeed`. The same curve the engine applies; useful on a HUD. */
   get steerLock(): number {
+    const lock = this.steering.lock ?? 35
     const atSpeed = Math.max(0, this.steering.atSpeed ?? 10)
-    if (atSpeed <= 0 || atSpeed >= this.maxSteer) return this.maxSteer
+    if (atSpeed <= 0 || atSpeed >= lock) return lock
     const full = this.steering.speed ?? 30
     const t = full > 0 ? Math.min(Math.abs(this.speed) / full, 1) : 1
-    return atSpeed + (this.maxSteer - atSpeed) * (1 - t) * (1 - t)
-  }
-
-  /** One wheel's live state, by its index in `wheels`. */
-  wheel(index: number): WheelState {
-    const s = this._read()
-    const base = 7 + index * WHEEL_STATE
-    if (index < 0 || base + WHEEL_STATE > s.length) {
-      return { contact: false, slip: 0, slipAngle: 0, gripLong: 0, gripLateral: 0, suspension: 0, steer: 0, spin: 0 }
-    }
-    return {
-      contact: s[base] !== 0,
-      slip: s[base + 1]!,
-      slipAngle: s[base + 2]!,
-      gripLong: s[base + 3]!,
-      gripLateral: s[base + 4]!,
-      suspension: s[base + 5]!,
-      steer: s[base + 6]!,
-      spin: s[base + 7]!,
-    }
+    return atSpeed + (lock - atSpeed) * (1 - t) * (1 - t)
   }
 
   // --- setup ----------------------------------------------------------------------------------
 
-  /** Resolve every wheel default: node → entity id + centre, Z → axle, layout → steer/power/brakes. */
-  private _resolve(): ResolvedWheel[] {
+  /** Every Wheel under the chassis, ordered front axle first, with its axle group resolved. */
+  private _collectWheels(): Wheel[] {
+    const found: Wheel[] = []
+    this.node.traverse((n) => { const w = n.get(Wheel); if (w) found.push(w) })
+    if (found.length === 0) return found
+
     const chassisInv = this.node.worldMatrix.invert()
-    const centres = this.wheels.map((w) => {
-      if (w.position) return new Vec3(cx(w.position), cy(w.position), cz(w.position))
-      const node = this._wheelNode(w)
-      if (!node) {
-        throw new Error("Vehicle: a wheel needs either `position` or a `node` to take its position from")
-      }
-      return chassisInv.mul(node.worldMatrix).position
-    })
-
-    // Axles: sort by Z (front first) and start a new group whenever the gap is more than AXLE_EPS.
-    const axleOf = new Array<number>(this.wheels.length).fill(0)
-    // Forward is −Z, so the front axle is the most NEGATIVE z.
-    const byZ = centres.map((_, i) => i).sort((a, b) => centres[a]!.z - centres[b]!.z)
+    const centres = found.map((w) => chassisInv.mul(w.node.worldMatrix).position)
+
+    // Axles: sort by Z (forward is −Z, so the front axle is the most NEGATIVE) and start a new group
+    // whenever the gap is more than AXLE_EPS.
+    const order = centres.map((_, i) => i).sort((a, b) => centres[a]!.z - centres[b]!.z)
+    const axleOf = new Array<number>(found.length).fill(0)
     let axle = 0
-    let ref = centres[byZ[0]!]!.z
-    for (const i of byZ) {
-      const w = this.wheels[i]!
+    let ref = centres[order[0]!]!.z
+    for (const i of order) {
       if (Math.abs(centres[i]!.z - ref) > AXLE_EPS) { axle++; ref = centres[i]!.z }
-      axleOf[i] = w.axle ?? axle
+      axleOf[i] = found[i]!.axle ?? axle
     }
     const maxAxle = Math.max(...axleOf)
 
-    return this.wheels.map((w, i) => {
+    // Bind each wheel in front-to-back order, resolving what it did not say.
+    const wheels: Wheel[] = []
+    for (const i of order) {
+      const w = found[i]!
       const a = axleOf[i]!
-      const steers = w.steer ?? a === 0
-      const powered = w.powered ?? (this.powered === "all" || (this.powered === "front" ? a === 0 : a === maxAxle))
-      const handbrake = w.handbrake ?? !steers
-      const c = centres[i]!
-      const node = this._wheelNode(w)
-      return {
-        entityId: node ? node.id : 0,
-        cx: c.x, cy: c.y, cz: c.z,
-        radius: w.radius ?? 0.35,
-        width: w.width ?? 0.25,
-        steers,
-        powered,
-        braked: w.brake ?? true,
-        handbraked: handbrake,
-        axle: a,
-      }
-    })
-  }
-
-  private _wheelNode(w: WheelConfig): Node | null {
-    if (!w.node) return null
-    if (typeof w.node !== "string") return w.node
-    const found = this.node.bone(w.node)
-    if (!found) console.warn(`Vehicle: no node named "${w.node}" under "${this.node.name}" — that wheel will be invisible`)
-    return found
+      const measured = w._measure()
+      w.radius ??= measured.radius
+      w.width ??= measured.width
+      w.steer ??= a === 0
+      w.drive ??= this.driveAxle === "all" || (this.driveAxle === "front" ? a === 0 : a === maxAxle)
+      w.handbrake ??= !w.steer
+      w.axle = a
+      const rest = centres[i]!
+      // Where the suspension hangs from, so the wheel CENTRE ends up where the author put it: the
+      // spring sags by g/(2πf)² under its own load (mass-independent), and that sag is what separates
+      // the resting length from full droop.
+      const travel = w.suspension.travel ?? 0.4
+      const stiffness = w.suspension.stiffness ?? 1.4
+      const sag = Math.min(GRAVITY / ((2 * Math.PI * stiffness) ** 2), travel * 0.6)
+      const attach = new Vec3(rest.x, rest.y + (travel - sag), rest.z)
+      w._bind(this, wheels.length, rest, attach)
+      wheels.push(w)
+    }
+    return wheels
   }
 
   /** Pack the whole configuration into the one blob the host ABI takes (see bridges.d.ts). */
   private _buildSettings(): Float32Array {
-    const travel = this.suspension.travel ?? 0.3
-    const stiffness = this.suspension.stiffness ?? 1.5
-    const damping = this.suspension.damping ?? 0.5
-    const maxRpm = this.engine.maxRpm ?? 6000
-    const gears = this.gears.length ? this.gears : DEFAULT_GEARS
-    // Where the suspension hangs from, so the wheel CENTRE ends up where the author put it: the
-    // spring sags by g/(2πf)² under its own load (mass-independent), and that sag is what separates
-    // the resting length from full droop.
-    const sag = Math.min(GRAVITY / ((2 * Math.PI * stiffness) ** 2), travel * 0.6)
-    const attachOffset = travel - sag
-
+    const curve = this.engine.curve ?? []
+    const curveCount = Math.floor(curve.length / 2)
     const diff = typeof this.differential === "number"
       ? this.differential
       : DIFFERENTIALS[this.differential] ?? DIFFERENTIALS.lsd
 
-    const out = new Float32Array(21 + gears.length + this._resolved.length * 10)
-    out[0] = 3                                   // blob version
+    const out = new Float32Array(BLOB_HEADER + curveCount * 2 + this._wheels.length * BLOB_WHEEL)
+    out[0] = BLOB_VERSION
     out[1] = this.mass
     out[2] = this.centerOfMass === undefined ? 1 : 0
     out[3] = this.centerOfMass ?? 0
-    out[4] = travel
-    out[5] = stiffness
-    out[6] = damping
-    out[7] = this.engine.torque ?? 500
-    out[8] = maxRpm / 6
-    out[9] = maxRpm
-    out[10] = maxRpm * 0.67                      // shift up
-    out[11] = maxRpm * 0.33                      // shift down
-    out[12] = this.grip
-    out[13] = this.antiRoll ? 1 : 0
-    out[14] = this.maxTilt
-    out[15] = gears.length
-    out[16] = this._resolved.length
-    out[17] = diff                               // v2: limited-slip ratio (<= 0 = open)
-    out[18] = Math.max(0, this.steering.atSpeed ?? 10)   // v3: speed-sensitive steering
-    out[19] = this.steering.speed ?? 30
-    out[20] = Math.max(0, this.steering.rate ?? 220)
-    let at = 21
-    for (const g of gears) out[at++] = g
-    for (const w of this._resolved) {
-      out[at++] = w.cx
-      out[at++] = w.cy + attachOffset
-      out[at++] = w.cz
-      out[at++] = w.radius
-      out[at++] = w.width
-      out[at++] = w.steers ? this.maxSteer : 0
-      out[at++] = w.powered ? 1 : 0
-      out[at++] = w.braked ? this.brakeTorque : 0
-      out[at++] = w.handbraked ? this.brakeTorque * 3 : 0
-      out[at++] = w.axle
+    out[4] = this.engine.torque ?? 500
+    out[5] = this.engine.maxRpm ?? 6000
+    out[6] = this.engine.idleRpm ?? 1000
+    out[7] = this.engine.inertia ?? 0.5
+    out[8] = this.engine.braking ?? 0.2
+    out[9] = this.clutchStrength
+    out[10] = diff
+    out[11] = this.antiRoll === true ? 0.01 : this.antiRoll === false ? 0 : Math.max(0, this.antiRoll)
+    out[12] = this.maxTilt
+    out[13] = this.steering.lock ?? 35
+    out[14] = Math.max(0, this.steering.atSpeed ?? 10)
+    out[15] = this.steering.speed ?? 30
+    out[16] = Math.max(0, this.steering.rate ?? 220)
+    out[17] = Math.max(0, this.aero.downforce ?? 0)
+    out[18] = Math.max(0, this.aero.drag ?? 0.03)
+    out[19] = this._wheels.length
+    out[20] = curveCount
+    let at = BLOB_HEADER
+    for (let i = 0; i < curveCount * 2; i++) out[at++] = curve[i]!
+    for (const w of this._wheels) {
+      out[at++] = w._attach.x
+      out[at++] = w._attach.y
+      out[at++] = w._attach.z
+      out[at++] = w.radius ?? 0.35
+      out[at++] = w.width ?? 0.25
+      out[at++] = w.steer ? (this.steering.lock ?? 35) : 0
+      out[at++] = w.drive ? 1 : 0
+      out[at++] = w.brake ? w.brakeTorque : 0
+      out[at++] = w.handbrake ? w.brakeTorque * 3 : 0
+      out[at++] = w.axle ?? 0
+      out[at++] = w.suspension.travel ?? 0.4
+      out[at++] = w.suspension.stiffness ?? 1.4
+      out[at++] = w.suspension.damping ?? 0.5
+      out[at++] = w.tire.grip ?? 1
+      out[at++] = w.tire.curve === "arcade" ? 1 : 0
     }
     return out
   }
 
-  /** Edit mode: wheels as circles at their resting height with their travel range, plus a forward
-   *  arrow — enough to place a wheel without running the game. Play mode never calls this. */
+  /** Edit mode: which way the chassis faces. Each wheel draws its own circle and travel range — see
+   *  `Wheel.rebuild()`. Play mode never calls this. */
   rebuild(): void {
-    let resolved: ResolvedWheel[]
-    try { resolved = this._resolve() } catch { return }
-    const world = new Mat4(this.node.worldMatrix)
-    const travel = this.suspension.travel ?? 0.3
-    const P = (x: number, y: number, z: number): Vec3 => world.transformPoint([ x, y, z ])
-    for (const w of resolved) {
-      const ring: Vec3[] = []
-      for (let i = 0; i < 24; i++) {
-        const t = (i / 24) * Math.PI * 2
-        ring.push(P(w.cx, w.cy + Math.sin(t) * w.radius, w.cz + Math.cos(t) * w.radius))
-      }
-      Gizmos.polyline(ring, { color: w.steers ? "#5b8ef0" : "#9aa3b2", closed: true })
-      Gizmos.line(P(w.cx, w.cy + travel * 0.6, w.cz), P(w.cx, w.cy - travel * 0.4, w.cz), { color: "#59606d" })
-      if (w.powered) Gizmos.cross(P(w.cx, w.cy, w.cz), w.radius * 0.35, { color: "#e0b25a" })
-    }
+    const w = new Mat4(this.node.worldMatrix)
+    const P = (x: number, y: number, z: number): Vec3 => w.transformPoint([ x, y, z ])
     Gizmos.polyline([ P(0, 0, 0), P(0, 0, -1.2), P(-0.15, 0, -1.0), P(0, 0, -1.2), P(0.15, 0, -1.0) ], { color: "#ffffff" })
   }
 }