lecodes-sdk 0.20.2 → 1.1.0

package/src/gl/vehicle/Vehicle.ts

@@ -0,0 +1,666 @@
+// A car, as an aspect on a 3D Node, backed by Jolt's wheeled-vehicle constraint (creator-physics).
+// The 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(body, hubFL.aspect(Wheel), hubFR.aspect(Wheel), hubRL.aspect(Wheel), hubRR.aspect(Wheel))
+//     .aspect(Shape, { box: [0.9, 0.4, 2.1] })
+//     .aspect(Vehicle, { mass: 1200 })
+//
+//   class Controls extends System<'controls'> {
+//     updateBefore() {                       // EARLY: this frame's step drives what the keys say
+//       const v = car.vehicle
+//       const fwd = (Input.key('KeyW') ? 1 : 0) - (Input.key('KeyS') ? 1 : 0)
+//       v.throttle = Math.abs(fwd)
+//       v.ratio = fwd < 0 ? -1 : 1           // the sign of the ratio IS the direction
+//       v.steer = (Input.key('KeyD') ? 1 : 0) - (Input.key('KeyA') ? 1 : 0)
+//       for (const w of v.wheels) w.brake = Input.key('Space') && !w.steer ? 4500 : 0
+//     }
+//   }
+//
+// This aspect is the car as HARDWARE: mass, engine, steering, aero, and the INPUTS a driver writes —
+// `throttle`, `steer`, `steerForce`, `ratio`, `clutch` here, `brake` on each `Wheel`. Everything a
+// DRIVER decides is the game's: which gear, when the clutch bites, whether the engine can stall,
+// when the hands let go of the wheel in a slide, a gyro, ABS, a keyboard's pedal travel. All of
+// those are a few lines over the sensors this class exposes (`rpm`, `speed`, `driftAngle`,
+// `yawRate`, `steerAngle`, `steerTorque`, and per wheel `spin`, `slip`, `load`, the forces…), and
+// the car-demo project carries a full driver as a reference. Anything per-wheel lives on the
+// `Wheel` aspect of the wheel's own node (which is where Jolt keeps it too); Vehicle collects every
+// Wheel under itself and groups them into axles by Z.
+//
+// The engine gets NUMBERS: the blob of settings (`_buildSettings`, live re-tunable) and one input
+// vector per frame. It never shapes them — no taper, no rate limit, no gearbox, no idle governor.
+//
+// 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 through the inputs, never per-frame `node.position` writes.
+
+import { Aspect, _phaseStamp } from "../../core/Aspect"
+import type { FieldMeta } from "../../core/fields"
+import { Mat4 } from "../../math/mat4"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../../math/vec"
+import { cw, type QuatLike } from "../../math/quat"
+import { Gizmos } from "../../scene/gizmos"
+import { Node } from "../Node"
+import { DEFAULT_FRICTION, Physics } from "../physics/Physics"
+import { Shape } from "../physics/Shape"
+import { STATE_HEADER, SUSPENSION_MIN_FRACTION, WHEEL_STATE, Wheel, resolveTire, type Point } from "./Wheel"
+
+/** Which axle the engine drives — the default for every wheel's own `driven` share. */
+export type DriveLayout = "rear" | "front" | "all" | "none"
+
+/**
+ * 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 EngineConfig {
+  /** Peak torque in N·m (default 500). The single biggest "how fast is it" knob. */
+  torque?: number
+  /** Redline in RPM (default 6000) — Jolt's own clamp; a rev limiter's stutter is the game's. */
+  maxRpm?: number
+  /** Idle RPM (default 1000): the engine's floor. `0` = no floor — the engine can be dragged to a
+   *  standstill and stall, and holding idle (a governor), cranking it, are the game's to write. */
+  idleRpm?: number
+  /**
+   * The engine's CHARACTER: points `{ x, y }` in NORMALISED units — x a fraction of the redline, y a
+   * fraction of `torque`, x ascending. Left out, Jolt's own broad curve is used.
+   *
+   * `[{ x: 0, y: 0.8 }, { x: 0.66, y: 1 }, { x: 1, y: 0.8 }]` is an ordinary petrol engine (peak two
+   * thirds up, falling to the redline); `[{ x: 0, y: 1 }, { x: 1, y: 1 }]` is flat, an electric motor.
+   */
+  curve?: Point[]
+  /** 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
+}
+
+/**
+ * The steering wheel as a BODY the tires push back on, simulated by the engine every sub-step. With
+ * it, `steer` is where the driver's hands AIM the wheel and `steerForce` how firmly they hold it;
+ * where the road wheels end up is physics:
+ *
+ *     I·θ̈ = T_hand + T_align·(1 − powerSteering) + T_stop − (damping + endStop.damping·depth)·θ̇ − parkingFriction(v) − friction
+ *
+ * `T_align` is the tires' self-aligning torque (`steering.caster` / `trail` / `trailAtPeak` — the
+ * same torque `steerTorque` reports without a feedback body, for a force-feedback wheel). `T_hand`
+ * is the driver's arms, `steering.driver`. So: heavy at speed, light when the front lets go,
+ * self-centring on release, and in a slide a let-go wheel swings into opposite lock by itself.
+ * Without `feedback` there is no body: `steer` is the road wheels' angle as a fraction of `maxAngle`.
+ */
+export interface SteeringFeedback {
+  /** Moment of inertia of wheel + column + rack about the axis, kg·m² (default 1). Heavier = slower
+   *  off the mark under the hands, but a wheel whipping into counter-steer carries further. */
+  inertia?: number
+  /** Viscous damping, N·m·s/rad (default 25): what keeps a let-go wheel from ringing about centre. */
+  damping?: number
+  /** The column's own dry friction, N·m, at any speed (default 8) — rack and bearings: the floor a
+   *  free wheel's spin decays against, and what keeps a let-go wheel from creeping under a small torque. */
+  friction?: number
+  /** The contact patch's dry friction while (nearly) parked, N·m (default 40), fading out by 1.5 m/s
+   *  — why a parked car is hard to steer, and why a wheel left turned stays turned. */
+  parkingFriction?: number
+  /** Power steering, 0..1 (default 0.5): the share of the tires' aligning torque the wheel never
+   *  sees. It is NOT a gain on the angle: 0 is a kart (heavy, full of feel, a held key gives up its
+   *  lock early at speed), 1 is a dead rim that neither centres nor counter-steers. */
+  powerSteering?: number
+  /** The END STOP before the lock — rubber, not a wall (default `{ band: 16, torque: 120, damping: 150 }`):
+   *  over the last `band` degrees the rack pushes back toward centre with the SQUARE of the depth,
+   *  `torque` N·m at the lock, and damps by `damping` N·m·s/rad × depth. A wheel let go on the stop
+   *  eases back off it a few degrees; `band: 0` = the hard clamp only. */
+  endStop?: { band?: number, torque?: number, damping?: number }
+}
+
+/** The driver's ARMS on a `feedback` wheel — an actuator with numbers, because a stiff hand spring
+ *  has to be integrated with the column every sub-step. WHAT the hands do (aim, hold, let go) is
+ *  the game's, per frame, through `steer` and `steerForce`. */
+export interface SteeringDriver {
+  /** The most torque the hands can put on the wheel, N·m (default 130). The ceiling on how much lock
+   *  a held key keeps at speed against the tires' pull. */
+  maxTorque?: number
+  /** How stiff the arms are, N·m/rad of the gap between where they aim and where the wheel is (default 500). */
+  stiffness?: number
+  /** The fastest the hands turn the road wheels, deg/s (default 120): the hands cannot PUSH a wheel
+   *  that already outruns them, they can still hold and brake it; a let-go wheel is uncapped. */
+  maxRate?: number
+  /** Seconds the hands' torque takes to build to `maxTorque` (default 0.1): muscles do not step. */
+  rampTime?: number
+}
+
+/** The column's numbers as the engine gets them. Defaults = the car-demo's verified setup. */
+const FEEDBACK_DEFAULTS = { inertia: 1.0, damping: 25, friction: 8, parkingFriction: 40, powerSteering: 0.5 }
+const END_STOP_DEFAULTS = { band: 16, torque: 120, damping: 150 }
+const DRIVER_DEFAULTS: Required<SteeringDriver> = { maxTorque: 130, stiffness: 500, maxRate: 120, rampTime: 0.1 }
+
+export interface SteeringConfig {
+  /** Steering lock in degrees (default 35): what `steer = ±1` means. */
+  maxAngle?: number
+  /** The front axle's GEOMETRY, the source of the tires' self-aligning torque (`steerTorque`, and
+   *  what a `feedback` wheel is pushed by): the mechanical caster's trail, metres (default 0.03)… */
+  caster?: number
+  /** …and the pneumatic trail, metres (default 0.025) — the patch's own lever, which collapses as the
+   *  tire reaches its peak slip angle (the steering going light when the front lets go)… */
+  trail?: number
+  /** …to this fraction of itself at the peak (default 0.5). */
+  trailAtPeak?: number
+  /** Simulate the steering wheel as a body the tires push back on (`SteeringFeedback`). `true` = the
+   *  defaults. Without it `steer` sets the road wheels' angle directly. */
+  feedback?: boolean | SteeringFeedback
+  /** The driver's arms on a `feedback` wheel (`SteeringDriver`); the defaults without it. */
+  driver?: SteeringDriver
+}
+
+/**
+ * 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
+}
+
+/** Blob v15 — see bridges.d.ts for the field-by-field layout. */
+const BLOB_VERSION = 15
+const BLOB_HEADER = 34
+const BLOB_WHEEL_FIXED = 15
+/** The input vector's fixed head: throttle, steer, steerForce, ratio, clutch — then one brake per wheel. */
+const INPUT_FIXED = 5
+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 RAD2DEG = 180 / Math.PI
+/** `driftAngle` fades in over this band of ground speed, m/s: under it a tire's slip angle is the
+ *  noise of a patch that is not going anywhere. */
+const DRIFT_SPEED_FROM = 1
+const DRIFT_SPEED_FULL = 2
+const clamp = (v: number, lo: number, hi: number): number => (v < lo ? lo : v > hi ? hi : v)
+
+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
+  /** 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") — the default for every wheel's own `driven`
+   *  share: 1 on that axle, 0 elsewhere. `none` = no drive at all (a trailer, a pushed cart). */
+  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"
+  /**
+   * 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.
+   *
+   * **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.
+   *
+   * 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`.
+   */
+  antiRoll: boolean | number = true
+  /** Pitch/roll limit in degrees (default 60) before the constraint rights the car. 180 turns it off. */
+  maxTilt = 60
+  /** 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` × 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. `clutch` (the input) scales it 0..1. */
+  clutchStrength = 10
+  /** The clutch's torque CAPACITY, N·m (default 0 = none: Jolt's viscous clutch alone, torque =
+   *  `clutchStrength` × slip speed, no ceiling — rigid at any real slip). Set it and the clutch
+   *  SLIPS at this much torque × `clutch` — a dry clutch, emulated a physics step at a time: a
+   *  launch can be feathered, and a dumped clutch in too high a gear drags the engine down instead
+   *  of lurching. A road car's is ~1.5× the engine's peak torque. */
+  clutchCapacity = 0
+
+  engine: EngineConfig = { torque: 500, maxRpm: 6000, idleRpm: 1000, inertia: 0.5, braking: 0.2 }
+  steering: SteeringConfig = { maxAngle: 35 }
+  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 },
+    driveAxle: { label: "Drive", options: [ "rear", "front", "all", "none" ] },
+    differential: { options: [ "lsd", "open", "locked" ] },
+    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 },
+    clutchCapacity: { label: "Clutch capacity", min: 0, step: 50 },
+    engine: { hidden: true },
+    steering: { hidden: true },
+    aero: { hidden: true },
+  }
+  static editor = { rebuild: true }
+
+  /** Driver systems tick at the default 0, so their inputs land in the SAME early pass, before this flush. */
+  protected override updateOrder = 100
+
+  private _id = 0
+  private _bodyId = 0
+  private _builtMass = 0
+  private _wheels: Wheel[] = []
+  private _state = new Float32Array(STATE_HEADER)
+  private _stateFrame = -1
+  private _throttle = 0
+  private _steer = 0
+  private _steerForce = 1
+  private _ratio = 1
+  private _clutch = 1
+  private _input = new Float32Array(INPUT_FIXED)
+  private _sent = new Float32Array(INPUT_FIXED)
+  private _dirty = true          // an input write since the last send
+  private _retunePending = false
+
+  onAttach(): void {
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    if (!_creator.vehicleCreate) {
+      console.warn("Vehicle needs a newer host (no vehicleCreate) — the car will not move")
+      return
+    }
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("Vehicle requires a Shape aspect (the chassis collider) — add it first: node.aspect(Shape, { box: […] }).aspect(Vehicle, {…})")
+    }
+    if (shape._isTriangleMesh) {
+      throw new Error("Vehicle: the chassis cannot use Shape { mesh: true } (a triangle mesh can't be a dynamic body) — use { mesh: 'convex' } or a box")
+    }
+    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)")
+    }
+
+    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: hubFL.aspect(Wheel)")
+    }
+
+    const shapeId = shape._claim()  // the vehicle owns the shape; drop the pick-only body
+    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
+    // 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 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(STATE_HEADER + this._wheels.length * WHEEL_STATE)
+    this._input = new Float32Array(INPUT_FIXED + this._wheels.length)
+    this._sent = new Float32Array(INPUT_FIXED + this._wheels.length)
+    this._dirty = true
+  }
+
+  onDetach(): void {
+    if (this._id) { _creator.vehicleDestroy(this._id); this._id = 0; this._bodyId = 0 }
+    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
+  }
+
+  /**
+   * Re-configuring an attached vehicle retunes it in place — the way a drift button switches the
+   * differential without the car so much as blinking:
+   *
+   *   car.aspect(Vehicle, { differential: drift ? 'locked' : 'lsd' })
+   *
+   * Live: `differential`, `engine`, `steering`, `aero`, `maxTilt`, `friction`, `clutchStrength`,
+   * `clutchCapacity`, `antiRoll` (its stiffness, on axles that have a bar), and every `Wheel`'s
+   * `tire`. Everything else describes the car's STRUCTURE — `mass`, `centerOfMass`, which wheels
+   * exist and where, their suspension, the driven shares — 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.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
+    }
+    this._retunePending = true
+    if (this._bodyId) _creator.physicsSetFriction?.(this._bodyId, this.friction)
+  }
+
+  /** @internal A wheel's tire changed: re-send the tuning before the next step (one send however
+   *  many wheels changed this frame). */
+  _retuneSoon(): void { this._retunePending = true }
+
+  /** Native vehicle id (0 until attached / no physics support). */
+  get id(): number { return this._id }
+  /** The chassis rigid body id (for `physicsApplyImpulse`-style calls). */
+  get bodyId(): number { return this._bodyId }
+  /** The wheels, front axle first, in the order the engine knows them. */
+  get wheels(): readonly Wheel[] { return this._wheels }
+
+  // --- inputs -----------------------------------------------------------------------------------
+  // Plain fields a driver writes; the early pass hands them to the engine as one vector before the
+  // step (`updateBefore`). Sticky: a value keeps applying until it is written again. Write them from
+  // a system's `updateBefore` and the very same physics step drives what the keys say.
+
+  /** Throttle 0..1 — the engine's pedal. No sign: the direction is `ratio`'s. */
+  get throttle(): number { return this._throttle }
+  set throttle(v: number) { this._throttle = clamp(v, 0, 1); this._dirty = true }
+  /** Steering −1..1. Without `steering.feedback`: the road wheels' angle as a fraction of `maxAngle`,
+   *  applied as is (a taper with speed, a rate limit, are the game's). With it: where the hands AIM
+   *  the wheel; the tires decide where the road wheels end up. */
+  get steer(): number { return this._steer }
+  set steer(v: number) { this._steer = clamp(v, -1, 1); this._dirty = true }
+  /** How firmly the hands hold a `feedback` wheel, 0..1 (default 1): the hands' torque is capped at
+   *  `driver.maxTorque × steerForce`. 0 = let go — the tires alone have the wheel: back to centre in
+   *  a grip corner, into opposite lock in a slide. Ignored without a feedback wheel. */
+  get steerForce(): number { return this._steerForce }
+  set steerForce(v: number) { this._steerForce = clamp(v, 0, 1); this._dirty = true }
+  /** The ONE gear ratio the engine runs (default 1): engine rpm = wheel rpm × ratio × the final
+   *  drive (3.42). The SIGN is the direction — negative is reverse — and 0 is neutral. */
+  get ratio(): number { return this._ratio }
+  set ratio(v: number) { this._ratio = v; this._dirty = true }
+  /** Clutch engagement 0..1 (default 1 = home). 0 = out: the engine is free of the wheels. */
+  get clutch(): number { return this._clutch }
+  set clutch(v: number) { this._clutch = clamp(v, 0, 1); this._dirty = true }
+
+  /**
+   * EARLY phase: hand this frame's inputs to the engine, before the step. The vector is sent when
+   * anything changed — and every frame while a throttle, steer or brake is non-zero, because that is
+   * what keeps a driven car awake (an idle car with zero input sleeps). The pending re-tune (a
+   * config or tire change) goes first, so the step runs on the new numbers.
+   */
+  protected updateBefore(): void {
+    if (!this._id) return
+    if (this._retunePending) {
+      this._retunePending = false
+      _creator.vehicleSetTuning?.(this._id, this._buildSettings())
+    }
+    const input = this._input
+    input[0] = this._throttle
+    input[1] = this._steer
+    input[2] = this._steerForce
+    input[3] = this._ratio
+    input[4] = this._clutch
+    let active = this._throttle !== 0 || this._steer !== 0
+    let changed = this._dirty
+    for (let i = 0; i < this._wheels.length; i++) {
+      const b = Math.max(0, this._wheels[i]!.brake)
+      if (b !== 0) active = true
+      if (b !== this._sent[INPUT_FIXED + i]) changed = true
+      input[INPUT_FIXED + i] = b
+    }
+    if (changed || active) {
+      _creator.vehicleSetInput(this._id, input)
+      this._sent.set(input)
+      this._dirty = false
+    }
+  }
+
+  /** Teleport upright and clear all motion (velocity, engine rpm, wheel spin). Defaults to the
+   *  chassis node's current pose — `reset()` alone un-flips a car where it lies. The inputs are
+   *  kept and re-sent on the next early pass. */
+  reset(position?: Vec3Like, rotation?: QuatLike): this {
+    if (!this._id) return this
+    const p = position ?? this.node.worldPosition
+    // No rotation given: keep the heading, drop the roll/pitch — the point of reset is to land upright.
+    const wq = this.node.worldQuaternion
+    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
+    this._dirty = true   // the engine zeroed its copy of the inputs
+    return this
+  }
+
+  /** Push the chassis (a boost pad, an explosion) — an instantaneous impulse in kg·m/s. */
+  applyImpulse(v: Vec3Like): this {
+    if (this._bodyId) _creator.physicsApplyImpulse(this._bodyId, cx(v), cy(v), cz(v))
+    return this
+  }
+
+  // --- readouts (one native read per PHASE — early sees the pre-step state, late the settled one —
+  //     shared by the car and every wheel; keyed on core/Aspect's _phaseStamp) -------------------
+
+  private _read(): Float32Array {
+    if (this._id && this._stateFrame !== _phaseStamp.value) {
+      _creator.vehicleGetState(this._id, this._state)
+      this._stateFrame = _phaseStamp.value
+    }
+    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 RPM. */
+  get rpm(): number { return this._read()[1]! }
+  /** How many wheels touch the ground this frame. */
+  get wheelsOnGround(): number { return this._read()[2]! }
+  /** At least one wheel on the ground. */
+  get grounded(): boolean { return this._read()[2]! > 0 }
+  /** Chassis velocity in world space, m/s. */
+  get velocity(): Vec3 { const s = this._read(); return new Vec3(s[3]!, s[4]!, s[5]!) }
+  /** Chassis angular velocity in world space, rad/s. */
+  get angularVelocity(): Vec3 { const s = this._read(); return new Vec3(s[6]!, s[7]!, s[8]!) }
+  /** How fast the car is turning about the vertical, in degrees per second — positive turning RIGHT
+   *  (the same sense as `steer`). The signal a counter-steer assist reads. */
+  get yawRate(): number { return -this._read()[7]! * RAD2DEG }
+  /**
+   * The car's slip angle in degrees: the angle between where the nose points and where the car is
+   * actually travelling, positive when it is travelling to the RIGHT of the nose. 0 going straight,
+   * ±180 backing up, and past ~10° the rear has stepped out — a drift.
+   */
+  get slipAngle(): number {
+    const s = this._read()
+    const vx = s[3]!, vz = s[5]!
+    if (vx * vx + vz * vz < 0.25) return 0   // under 0.5 m/s the direction is noise
+    const f = this.node.forward
+    const along = f.x * vx + f.z * vz
+    const right = -f.z * vx + f.x * vz   // chassis right is (−f.z, 0, f.x) for forward f
+    return Math.atan2(right, along) * RAD2DEG
+  }
+  /**
+   * The angle of the SLIDE, degrees, signed like `slipAngle` (positive = travelling to the right of
+   * the nose), −180..180: the angle between the car's axis and where its REAR AXLE travels — the
+   * mean of the non-steering wheels (every wheel if all of them steer), its velocity from the
+   * body's velocity and spin. Unlike `slipAngle` (the body's, at its centre) this is 0 on a clean
+   * corner at ANY speed: at walking pace and full lock the body already travels ~20° off its nose
+   * while the rear axle rolls straight along it. It is the rear stepping out — what a gyro comes in
+   * on, and what a drift meter should show — and unlike the tires' own `Wheel.slipAngle` it does
+   * not fold at 90°: a backward entry reads 110°, not 70°. The axis it is measured from is the one
+   * the DRIVETRAIN pushes along — the nose for a positive `ratio`, the tail for a negative one — so
+   * honest reversing reads 0, and a car spun round in a forward gear reads past 90°. 0 at a
+   * standstill: with no speed a direction is noise, so it fades in over walking pace,
+   * `DRIFT_SPEED_FROM`..`DRIFT_SPEED_FULL` of the axle's ground speed.
+   */
+  get driftAngle(): number {
+    if (this._wheels.length === 0) return 0
+    // The rear axle in chassis space: the non-steering wheels' mean position (the hubs are the
+    // chassis' children, so a wheel node's position IS its chassis-local place).
+    let rx = 0, ry = 0, rz = 0, n = 0
+    for (const w of this._wheels) if (!w.steer) { const p = w.node.position; rx += p.x; ry += p.y; rz += p.z; n++ }
+    if (n === 0) for (const w of this._wheels) { const p = w.node.position; rx += p.x; ry += p.y; rz += p.z; n++ }
+    const r = this.node.quaternion.rotateVec3([ rx / n, ry / n, rz / n ])
+    // Its velocity: v + ω × r, in the ground plane.
+    const st = this._read()
+    const vx = st[3]!, vz = st[5]!, wx = st[6]!, wy = st[7]!, wz = st[8]!
+    const ax = vx + (wy * r.z - wz * r.y)
+    const az = vz + (wx * r.y - wy * r.x)
+    const ground = Math.hypot(ax, az)
+    const weight = clamp((ground - DRIFT_SPEED_FROM) / (DRIFT_SPEED_FULL - DRIFT_SPEED_FROM), 0, 1)
+    if (weight === 0) return 0
+    const f = this.node.forward
+    const dir = this._ratio < 0 ? -1 : 1
+    const along = dir * (f.x * ax + f.z * az) / ground
+    const right = dir * (-f.z * ax + f.x * az) / ground   // chassis right is (−f.z, 0, f.x) for forward f
+    return Math.atan2(right, along) * RAD2DEG * weight
+  }
+  /** Where the steered wheels actually are, in degrees, right-positive: the angle `steer` set, or
+   *  with `steering.feedback` where the column has come to. */
+  get steerAngle(): number { return this._read()[9]! }
+  /** The tires' self-aligning torque on the steering, N·m, positive = it pulls the wheel to the
+   *  RIGHT — what the driver feels: heavy at speed, light when the front lets go, and the
+   *  counter-steer in a slide. Reported with or without a `feedback` wheel: the signal a
+   *  force-feedback steering wheel is driven by. */
+  get steerTorque(): number { return this._read()[10]! }
+
+  // --- setup ----------------------------------------------------------------------------------
+
+  /** 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 = 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[order[0]!]!.z
+    for (const i of order) {
+      if (Math.abs(centres[i]!.z - ref) > AXLE_EPS) { axle++; ref = centres[i]!.z }
+      axleOf[i] = found[i]!.axle ?? axle
+    }
+    const maxAxle = Math.max(...axleOf)
+
+    // 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 measured = w._measure()
+      w.radius ??= measured.radius
+      w.width ??= measured.width
+      w.steer ??= a === 0
+      w.driven ??= this.driveAxle === "none" ? 0 : this.driveAxle === "all" ? 1 : (this.driveAxle === "front" ? a === 0 : a === maxAxle) ? 1 : 0
+      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 * (1 - SUSPENSION_MIN_FRACTION))
+      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 curve = this.engine.curve ?? []
+    const diff = typeof this.differential === "number"
+      ? this.differential
+      : DIFFERENTIALS[this.differential] ?? DIFFERENTIALS.lsd
+    const tires = this._wheels.map((w) => resolveTire(w.tire))
+    const st = this.steering
+    const lock = Math.max(0, st.maxAngle ?? 35)
+    const fb = st.feedback === true ? {} : st.feedback || null
+    const stop = fb?.endStop ?? {}
+    const drv = st.driver ?? {}
+
+    let size = BLOB_HEADER + curve.length * 2
+    for (const t of tires) size += BLOB_WHEEL_FIXED + (t.side.length + t.forward.length) * 2
+    const out = new Float32Array(size)
+    out[0] = BLOB_VERSION
+    out[1] = this.mass
+    out[2] = this.centerOfMass === undefined ? 1 : 0
+    out[3] = this.centerOfMass ?? 0
+    out[4] = this.engine.torque ?? 500
+    out[5] = this.engine.maxRpm ?? 6000
+    out[6] = Math.max(0, 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] = Math.max(0, this.aero.downforce ?? 0)
+    out[14] = Math.max(0, this.aero.drag ?? 0.03)
+    out[15] = fb ? 1 : 0
+    out[16] = fb?.inertia ?? FEEDBACK_DEFAULTS.inertia
+    out[17] = fb?.damping ?? FEEDBACK_DEFAULTS.damping
+    out[18] = fb?.parkingFriction ?? FEEDBACK_DEFAULTS.parkingFriction
+    out[19] = st.caster ?? 0.03
+    out[20] = st.trail ?? 0.025
+    out[21] = st.trailAtPeak ?? 0.5
+    out[22] = drv.maxTorque ?? DRIVER_DEFAULTS.maxTorque
+    out[23] = drv.stiffness ?? DRIVER_DEFAULTS.stiffness
+    out[24] = fb?.powerSteering ?? FEEDBACK_DEFAULTS.powerSteering
+    out[25] = drv.maxRate ?? DRIVER_DEFAULTS.maxRate
+    out[26] = stop.band ?? END_STOP_DEFAULTS.band
+    out[27] = stop.torque ?? END_STOP_DEFAULTS.torque
+    out[28] = stop.damping ?? END_STOP_DEFAULTS.damping
+    out[29] = fb?.friction ?? FEEDBACK_DEFAULTS.friction
+    out[30] = drv.rampTime ?? DRIVER_DEFAULTS.rampTime
+    out[31] = Math.max(0, this.clutchCapacity)
+    out[32] = this._wheels.length
+    out[33] = curve.length
+    let at = BLOB_HEADER
+    for (const p of curve) { out[at++] = p.x; out[at++] = p.y }
+    this._wheels.forEach((w, i) => {
+      const t = tires[i]!
+      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 ? lock : 0
+      out[at++] = Math.max(0, w.driven ?? 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++] = t.traction
+      out[at++] = t.circle
+      out[at++] = t.side.length
+      out[at++] = t.forward.length
+      for (const p of t.side) { out[at++] = p.x; out[at++] = p.y }
+      for (const p of t.forward) { out[at++] = p.x; out[at++] = p.y }
+    })
+    return out
+  }
+
+  /** 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 {
+    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" })
+  }
+}