lecodes-cli 0.17.2 → 0.18.0

package/runtime/sdk/gl/Vehicle.ts

@@ -0,0 +1,519 @@
+// A car, as an aspect on a 3D Node, backed by Jolt's wheeled-vehicle constraint in creator-gl. 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(bodyModel, wheelFL, wheelFR, wheelRL, wheelRR)
+//     .aspect(Shape, { box: [0.9, 0.4, 2.1] })
+//     .aspect(Vehicle, { mass: 1200, wheels: [
+//       { node: wheelFL }, { node: wheelFR }, { node: wheelRL }, { node: wheelRR },
+//     ] })
+//
+//   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}`
+//   })
+//
+// 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.
+//
+// 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.
+
+import { Aspect } 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 { glState } from "./state"
+import { Node } from "./Node"
+import { Physics } from "./Physics"
+import { Shape } from "./Shape"
+
+/** Which axle the engine drives. Per-wheel `powered` 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
+}
+
+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 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. */
+  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. */
+  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
+}
+
+/** 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". */
+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
+  /**
+   * 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.
+   *
+   * `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.
+   *
+   * 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.
+   */
+  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
+  /** 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. */
+  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 },
+    differential: { options: [ "lsd", "open", "locked" ] },
+    wheels: { hidden: true },
+    gears: { hidden: true },
+    suspension: { hidden: true },
+    engine: { hidden: true },
+    steering: { 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 _stateFrame = -1
+
+  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)")
+    }
+    if (this.wheels.length === 0) throw new Error("Vehicle needs at least one wheel — `wheels: [{ node: … }, …]`")
+
+    this._resolved = this._resolve()
+    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)
+    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)
+    this._builtMass = this.mass
+    this._state = new Float32Array(7 + this._resolved.length * WHEEL_STATE)
+  }
+
+  onDetach(): void {
+    if (this._id) { _creator.vehicleDestroy(this._id); this._id = 0; this._bodyId = 0 }
+    this.node.get(Shape)?._recreatePickBody()
+  }
+
+  /**
+   * 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`, `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.
+   */
+  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)
+  }
+
+  /** 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 }
+
+  // --- 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).
+   */
+  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))
+    }
+    return this
+  }
+
+  /** Teleport upright and clear all motion (velocity, engine, gearbox, wheel spin). Defaults to the
+   *  chassis node's current pose — `reset()` alone un-flips a car where it lies. */
+  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
+    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 frame, shared by every getter) ----------------------------
+
+  private _read(): Float32Array {
+    if (this._id && this._stateFrame !== glState.frame) {
+      _creator.vehicleGetState(this._id, this._state)
+      this._stateFrame = glState.frame
+    }
+    return this._state
+  }
+
+  /** 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]! }
+  /** Any wheel on the ground — false while airborne. */
+  get grounded(): boolean { return this._read()[3]! > 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,
+   *  falling to `steering.atSpeed`. The same curve the engine applies; useful on a HUD. */
+  get steerLock(): number {
+    const atSpeed = Math.max(0, this.steering.atSpeed ?? 10)
+    if (atSpeed <= 0 || atSpeed >= this.maxSteer) return this.maxSteer
+    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]!,
+    }
+  }
+
+  // --- setup ----------------------------------------------------------------------------------
+
+  /** Resolve every wheel default: node → entity id + centre, Z → axle, layout → steer/power/brakes. */
+  private _resolve(): ResolvedWheel[] {
+    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)
+    let axle = 0
+    let ref = centres[byZ[0]!]!.z
+    for (const i of byZ) {
+      const w = this.wheels[i]!
+      if (Math.abs(centres[i]!.z - ref) > AXLE_EPS) { axle++; ref = centres[i]!.z }
+      axleOf[i] = w.axle ?? axle
+    }
+    const maxAxle = Math.max(...axleOf)
+
+    return this.wheels.map((w, 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
+  }
+
+  /** 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 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
+    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
+    }
+    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. */
+  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" })
+    }
+    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" })
+  }
+}

package/runtime/sdk/gl/{AnimationClip.ts → animation/AnimationClip.ts}

@@ -1,7 +1,8 @@
 // AnimationClip — the unit of the animation system: immutable data (name, duration, tracks that
 // target bone NAMES, not entities). One representation for a GLB's embedded clips (model.anim.clips),
 // clips loaded from other files (Mixamo: one GLB per animation) and procedural clips built from
-// curves. An Animator binds clips to a skeleton by name. See docs/animation-plan.md.
+// curves. An Animator binds clips to a skeleton by name. Clip EVENTS (`addEvent`) live here too —
+// a fact about the clip's timeline, shared wherever it plays. See docs/animator-plan.md.
 //
 //   const [hero, idle, run] = await Promise.all([
 //     Model.load(asset('./hero.glb')),
@@ -11,9 +12,9 @@
 //   const slash = await AnimationClip.load(asset('./attacks.glb'), 'Slash')   // one out of many
 //   const bob = AnimationClip.from({ tracks: { Hips: { position: [[0, [0,0,0]], [1, [0,0.05,0]]] } } })
 
-import { fetch, type FetchResponse } from "../runtime/fetch"
-import type { Vec3Like } from "../math/vec"
-import type { QuatLike } from "../math/quat"
+import { fetch, type FetchResponse } from "../../runtime/fetch"
+import type { Vec3Like } from "../../math/vec"
+import type { QuatLike } from "../../math/quat"
 
 /** A keyframe: `[time (s), value]`. */
 export type ClipKey<V> = [number, V]
@@ -39,6 +40,8 @@ export type ClipInfo = { name: string, duration: number, trackCount: number }
 const PATH = { position: 0, rotation: 1, scale: 2 } as const
 const INTERP = { linear: 0, step: 1 } as const
 
+const setCache = new Map<number, AnimationClip[]>()
+
 const readInfo = (setId: number): ClipInfo[] =>
   ((_creator.getClipSetInfo(setId) ?? []) as ClipInfo[]).map((c) => ({ name: c.name, duration: c.duration, trackCount: c.trackCount ?? 0 }))
 
@@ -61,6 +64,8 @@ export class AnimationClip {
   readonly _set: number
   /** @internal */
   readonly _index: number
+  /** @internal events: seconds + name, sorted (the engine gets them normalized via setClipEvents). */
+  _events: { t: number, name: string }[] = []
 
   private constructor(set: number, index: number, info: ClipInfo) {
     this._set = set
@@ -70,10 +75,32 @@ export class AnimationClip {
     this.trackCount = info.trackCount
   }
 
-  /** @internal — wrap a clip of an existing native set (a GLB's embedded clips). */
+  /** @internal — a placeholder for a Playback that never started (unknown clip). */
+  static _none(): AnimationClip { return new AnimationClip(0, 0, { name: "", duration: 0, trackCount: 0 }) }
+
+  /** @internal — wrap the clips of an existing native set (a GLB's embedded clips). Cached per set
+   *  so every model / clone sharing the set gets the SAME objects (events added on one apply to all —
+   *  as they do in the engine). */
   static _ofSet(setId: number): AnimationClip[] {
     if (!setId) return []
-    return readInfo(setId).map((info, i) => new AnimationClip(setId, i, info))
+    let clips = setCache.get(setId)
+    if (!clips) { clips = readInfo(setId).map((info, i) => new AnimationClip(setId, i, info)); setCache.set(setId, clips) }
+    return clips
+  }
+
+  /** Mark a moment of the clip (SECONDS from its start) with an event name: `kick.addEvent(0.4, 'hit')`
+   *  → `anim.on('hit', (clip, layer) => …)` fires when the playhead crosses it, loops included.
+   *  Events are part of the clip: every model playing it gets them; `slice()` keeps the ones inside
+   *  the range, re-timed. Chainable. */
+  addEvent(time: number, name: string): this {
+    this._events.push({ t: Math.min(Math.max(0, time), this.duration), name })
+    this._events.sort((a, b) => a.t - b.t)
+    this._pushEvents()
+    return this
+  }
+  private _pushEvents(): void {
+    const d = this.duration
+    _creator.setClipEvents(this._set, this._index, new Float32Array(this._events.map((e) => (d > 0 ? e.t / d : 0))))
   }
 
   /** Load ONE clip from a GLB: the file's only/first clip, or the one named / at the given index. */
@@ -147,7 +174,10 @@ export class AnimationClip {
     const setId = _creator.sliceClip(this._set, this._index, st, e)
     if (setId === 0) throw new Error(`AnimationClip.slice: bad range ${start}${end !== undefined ? `–${end}` : ""} of '${this.name}' (${this.duration.toFixed(2)}s)`)
     const info = readInfo(setId)[0] ?? { name: this.name, duration: e - st, trackCount: this.trackCount }
-    return new AnimationClip(setId, 0, info)
+    const out = new AnimationClip(setId, 0, info)
+    // the engine re-timed the event TIMES; carry the names the same way
+    out._events = this._events.filter((ev) => ev.t >= st - 1e-6 && ev.t <= e + 1e-6).map((ev) => ({ t: Math.min(Math.max(0, ev.t - st), e - st), name: ev.name }))
+    return out
   }
 
   private static _label(source: string | FetchResponse): string {