lecodes-cli 0.18.0 → 0.18.2

package/runtime/sdk/gl/CameraPlace.ts

@@ -1,51 +1,52 @@
-// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
-// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
-// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
-// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
-//
-//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
-//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
-//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
-//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
-//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
-//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
-//     releases.
-//   • Edit mode: draws a frustum gizmo (the editor's camera preview reads the same place).
-// See docs/scene-camera-place-plan.md.
-
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { Gizmos } from "../scene/gizmos"
-import type { Camera } from "./Camera"
-import type { Node } from "./Node"
-
-export class CameraPlace extends Aspect<"cameraPlace", Node> {
-  static readonly aspect = "cameraPlace"
-  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
-  fov = 60
-  /** Near clip distance. */
-  near = 0.01
-  /** Far clip distance = view range. */
-  far = 1000
-  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
-   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
-  active = false
-  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
-  static fields: FieldMeta<CameraPlace> = {
-    fov: { label: "FOV", min: 1, max: 179, step: 1 },
-    near: { min: 0.001, max: 10, step: 0.01 },
-    far: { min: 1, max: 100000, step: 1 },
-    active: { label: "Active camera" },
-  }
-  static editor = { rebuild: true }
-
-  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
-  applyTo(camera: Camera): void {
-    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
-  }
-
-  /** Edit mode: the frustum marker (−Z = view). Play mode never calls this. */
-  rebuild(): void {
-    Gizmos.frustum(this.node.worldMatrix, this.fov, 16 / 9, 0.6, { color: this.active ? "#ffffff" : "#9aa3b2" })
-  }
-}
+// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
+// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
+// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
+// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
+//
+//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
+//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
+//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
+//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
+//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
+//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
+//     releases.
+//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
+// See docs/scene-camera-place-plan.md.
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import { Gizmos } from "../scene/gizmos"
+import type { Camera } from "./Camera"
+import type { Node } from "./Node"
+
+export class CameraPlace extends Aspect<"cameraPlace", Node> {
+  static readonly aspect = "cameraPlace"
+  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
+  fov = 60
+  /** Near clip distance. */
+  near = 0.01
+  /** Far clip distance = view range. */
+  far = 1000
+  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
+   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
+  active = false
+  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
+  static fields: FieldMeta<CameraPlace> = {
+    fov: { label: "FOV", min: 1, max: 179, step: 1 },
+    near: { min: 0.001, max: 10, step: 0.01 },
+    far: { min: 1, max: 100000, step: 1 },
+    active: { label: "Active camera" },
+  }
+  static editor = { rebuild: true }
+
+  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
+  applyTo(camera: Camera): void {
+    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
+  }
+
+  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
+   *  clicking it selects the node. Play mode never calls this. */
+  rebuild(): void {
+    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
+  }
+}

package/runtime/sdk/gl/CharacterController.ts

@@ -4,45 +4,70 @@
 //
 //   const hero = new Mesh(capsuleGeometry(), material)
 //     .aspect(Shape, { capsule: { halfHeight: 0.6, radius: 0.3 } })
-//     .aspect(CharacterController, { speed: 6, jumpSpeed: 8 })
-//   setLoop(() => hero.controller.move((Input.key('KeyD') ? 1 : 0) - (Input.key('KeyA') ? 1 : 0),
-//                                       (Input.key('KeyS') ? 1 : 0) - (Input.key('KeyW') ? 1 : 0)))
-//   Input.on('keydown', e => { if (e.code === 'Space') hero.controller.jump() })
+//     .aspect(CharacterController)
+//   setLoop(() => hero.controller.move((Input.key('KeyD') ? 1 : 0) - (Input.key('KeyA') ? 1 : 0) * SPEED,
+//                                      (Input.key('KeyS') ? 1 : 0) - (Input.key('KeyW') ? 1 : 0) * SPEED))
+//   Input.on('keydown', e => { if (e.code === 'Space' && hero.controller.grounded) hero.controller.velocityY = 7 })
 //
-// You drive horizontal intent + jump; the controller integrates gravity and Jolt handles collision
-// against the world. `grounded` reports whether it's on walkable ground. It runs in the EARLY update
-// phase (feeds this frame's step). Note: it collides with solid bodies but PASSES THROUGH triggers,
-// and (v1) is not itself detected by triggers and isn't pointer-pickable while active.
+// The two halves of the velocity have different NATURES, so they have different channels:
+//
+//   • HORIZONTAL — `move(x, z)`, world units/s, a PER-FRAME COMMAND. A walking character's horizontal
+//     velocity is muscle-driven and not conserved: stop pushing, stop moving. So the command expires
+//     each frame — no call this frame means standing still, and releasing the keys needs no explicit
+//     zero. It is latched for the whole frame, so every physics sub-step of that frame sees it.
+//   • VERTICAL — `velocityY`, LATCHED ballistic state. Gravity integrates into it in the engine;
+//     you seed it for a jump / dash / bounce pad / explosion (`velocityY = 7`, `velocityY += 3`).
+//     There is deliberately no ground check: coyote time, double jumps and wall jumps all need
+//     the caller's own condition.
+//
+// `velocity` reads back what the solver ENDED UP with after the last step (post-collision) — walk into
+// a wall and it reads ~0 even though you commanded 5. Everything runs on the engine's fixed clock, so
+// the aspect has no per-frame update: a character costs zero JS work per frame.
+//
+// FREE MODE — `gravityScale = 0` turns the character into a swimmer / flyer / drone: no gravity, and
+// (because Jolt would otherwise snap it down to the floor it passes over) no stick-to-floor and no
+// stair walking either. There the vertical is muscle-driven too, so `move()` takes all three
+// components and the whole velocity becomes a per-frame command.
+//
+// ROTATION AND SCALE stay the node's: the engine writes only the position, so a rig can be yawed and
+// scaled directly instead of needing a child node for the visuals (a capsule is symmetric about its up
+// axis, so its yaw is physically irrelevant either way).
+//
+// CROUCHING goes through the Shape aspect (`node.aspect(Shape, { capsule: … })`) — see `resizing`.
+//
+// Note: it collides with solid bodies but PASSES THROUGH triggers, and (v1) is not itself detected by
+// triggers and isn't pointer-pickable while active.
 
 import { Aspect } from "../core/Aspect"
-import { Vec3 } from "../math/vec"
+import type { FieldMeta } from "../core/fields"
+import { Vec3, cx, cy, cz, type Vec2Like, type Vec3Like } from "../math/vec"
+import type { CompAxis, CompWriter } from "../core/compWrite"
 import { Shape } from "./Shape"
 import type { Node } from "./Node"
 
-const clamp1 = (v: number): number => (v < -1 ? -1 : v > 1 ? 1 : v)
+/** Where the character's feet are, as reported by the solver after the last step. */
+export type GroundState = "ground" | "slope" | "unsupported" | "air"
 
-export class CharacterController extends Aspect<"controller", Node> {
-  static readonly aspect = "controller"
+// Index = JPH::EGroundState (0 OnGround / 1 OnSteepGround / 2 NotSupported / 3 InAir).
+const GROUND_STATES: readonly GroundState[] = ["ground", "slope", "unsupported", "air"]
+
+const scratch = new Float32Array(3)
+let warnedFreeMove = false
 
-  /** Horizontal move speed (world units/s). */
-  speed = 5
-  /** Jump take-off speed (world units/s). */
-  jumpSpeed = 7
-  /** Character-tuned gravity (world units/s²), separate from the world gravity — usually stronger for
-   *  snappier feel. Applied to the vertical velocity each frame. */
-  gravity = -20
-  /** Max ground slope (degrees) the character treats as walkable. Set before attach. */
-  maxSlope = 45
+export class CharacterController extends Aspect<"controller", Node> implements CompWriter {
+  static readonly aspect = "controller"
 
-  updateBeforePhysics = true // EARLY phase — set velocity so THIS frame's step consumes it
+  // Both tunables are accessor-backed (they write through to the engine), and describeFields only
+  // enumerates own enumerable fields — so the inspector is told about them explicitly. The default
+  // VALUES still come from a fresh instance through the getters; this only supplies the keys.
+  static fields: FieldMeta<CharacterController> = {
+    gravityScale: { editor: "number", min: 0, step: 0.1, label: "Gravity scale" },
+    maxSlope: { editor: "number", min: 0, max: 89, step: 1, label: "Max slope°" },
+  }
 
   private _charId = 0
-  private _mx = 0
-  private _mz = 0
-  private _jumpQueued = false
-  private _vy = 0
-  private _ex = 0   // external horizontal velocity (world units/s) — root motion from an Animator
-  private _ez = 0
+  private _gravityScale = 2
+  private _maxSlope = 45
 
   onAttach(): void {
     if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
@@ -54,57 +79,160 @@ export class CharacterController extends Aspect<"controller", Node> {
       throw new Error("CharacterController needs a convex Shape (capsule recommended) — { mesh: true } is a triangle mesh; use { mesh: 'convex' } or a capsule")
     }
     const shapeId = shape._claim() // the character owns the shape; it is not a rigid body
+    // Read the options through their PUBLIC accessors, never the `_backing` fields: chisel drops an
+    // accessor pair whose name is only ever an object-literal key, and then
+    // `aspect(CharacterController, { gravityScale: 0 })` silently leaves the default in place (the
+    // character keeps falling instead of entering free mode). One property read here keeps the pair.
     this._charId = _creator.characterCreate(this.node.id, shapeId, this.maxSlope)
+    if (!this._charId) return
+    _creator.characterSetGravityScale(this._charId, this.gravityScale)
+    this.node._xf = this._charId   // routes node.position / .x / .y / .z / .matrix writes to the character
+    this.node._xfKind = 1
   }
 
   onDetach(): void {
     if (this._charId) { _creator.characterDestroy(this._charId); this._charId = 0 }
-    this.node.get(Shape)?._recreatePickBody()
+    this.node._xf = 0
+    this.node._xfKind = 0
+    this.node.get(Shape)?._recreatePickBody()   // hands the routing back to the pick body
   }
 
   /** Native character id (0 until attached / no physics support). */
   get id(): number { return this._charId }
 
-  /** Horizontal move intent; each component in [-1, 1] (e.g. from input). Sticky — set 0 to stop. */
-  move(x: number, z: number): void { this._mx = clamp1(x); this._mz = clamp1(z) }
+  /**
+   * This frame's movement command, in world units/s — NOT normalized, NOT a per-frame displacement
+   * (that is what Unity's `Move` takes; passing `v * dt` here gives a character 60× too slow).
+   *
+   * Two components = horizontal `(x, z)`, the everyday call. Three = the whole velocity, for free mode
+   * (`gravityScale = 0`); with gravity on, the vertical component fights the ballistic one and the
+   * character barely falls, so that combination warns.
+   *
+   * Sticky only within the frame: the command expires once the engine consumes it. It also **takes the
+   * axis back from a latched `velocity`** — commanding is claiming ownership, which is what keeps the
+   * two horizontal sources from ever fighting.
+   */
+  move(x: number, z: number): void
+  move(v: Vec2Like | Vec3Like): void
+  move(x: number | Vec2Like | Vec3Like, z?: number): void {
+    if (!this._charId) return
+    if (typeof x === "number") { _creator.characterMove(this._charId, x, z ?? 0); return }
+    // cz() is typed for 3-component inputs; a Vec2 legitimately has no `z` and reads undefined here.
+    const third = cz(x as Vec3Like)           // undefined for a Vec2 / 2-tuple / 2-long typed array
+    if (third === undefined) { _creator.characterMove(this._charId, cx(x), cy(x)); return }
+    if (this._gravityScale !== 0 && !warnedFreeMove) {
+      warnedFreeMove = true
+      console.warn("CharacterController.move(): the 3-component form is the FREE-mode command (swimming / flying) and expects gravityScale = 0. With gravity on it overwrites the falling speed every frame, so the character will hang in the air. Use move(x, z) and velocityY for a walking character.")
+    }
+    _creator.characterMoveFree(this._charId, cx(x), cy(x), third)
+  }
 
-  /** Queue a jump; consumed on the next frame if grounded. */
-  jump(): void { this._jumpQueued = true }
+  /** Vertical velocity (world units/s) — LATCHED: gravity works on it, you seed it. `= 7` to jump,
+   *  `+= 3` to stack an explosion on top of the current motion. No ground check: guard it yourself
+   *  with `grounded` (or don't, for a double jump). Overridden every frame by a 3-component `move()`.
+   *  `velocity.y = 7` is the same channel — pick whichever reads better. */
+  get velocityY(): number {
+    if (!this._charId) return 0
+    _creator.characterGetVelocity(this._charId, scratch)
+    return scratch[1]
+  }
+  set velocityY(v: number) {
+    if (this._charId) _creator.characterSetVerticalVelocity(this._charId, v)
+  }
 
-  /** @internal — extra world-space horizontal velocity added on top of `move()` this frame (root motion). */
-  _setExternalVelocity(x: number, _y: number, z: number): void { this._ex = x; this._ez = z }
+  /** Multiplier over the world gravity (`Physics.configure({ gravity })`); default 2, for the snappier
+   *  fall games want. **0 = free mode**: no gravity, no stick-to-floor, no stair stepping — a swimmer
+   *  or a drone, driven by the 3-component `move()`. */
+  get gravityScale(): number { return this._gravityScale }
+  set gravityScale(v: number) {
+    this._gravityScale = v
+    if (this._charId) _creator.characterSetGravityScale(this._charId, v)
+  }
 
-  /** True while standing on walkable ground (OnGround). */
+  /** Max ground slope (degrees) the character treats as walkable; default 45. Live. */
+  get maxSlope(): number { return this._maxSlope }
+  set maxSlope(v: number) {
+    this._maxSlope = v
+    if (this._charId) _creator.characterSetMaxSlope(this._charId, v)
+  }
+
+  /**
+   * True while a requested collider resize hasn't taken — you asked to stand up and there is something
+   * overhead. Resizing goes through the `Shape` aspect itself:
+   *
+   *     hero.aspect(Shape, { capsule: CROUCHED })   // always fits — you are shrinking
+   *     hero.aspect(Shape, { capsule: STANDING })   // may be refused under a low ceiling
+   *     if (hero.controller.resizing) …             // still crouched; call it again next frame
+   *
+   * A refusal changes nothing, so the retry is just the same call again — and it is an exact headroom
+   * test against the real capsule, unlike a hand-rolled raycast (a ray is a line; a capsule has girth).
+   * The FEET stay planted across a resize, so the character neither hovers nor sinks.
+   */
+  get resizing(): boolean {
+    return this.node.get(Shape)?._resizeRefused ?? false
+  }
+
+  /** True while standing on walkable ground. */
   get grounded(): boolean {
     return this._charId ? _creator.characterGetGroundState(this._charId) === 0 : false
   }
 
-  /** Ground state: 0 on-ground, 1 on-steep-slope, 2 touching-but-unsupported, 3 in-air. */
-  get groundState(): number {
-    return this._charId ? _creator.characterGetGroundState(this._charId) : 3
+  /** Where the feet are after the last step: on walkable ground, on too-steep ground, touching
+   *  something that can't support it, or in the air. */
+  get groundState(): GroundState {
+    return this._charId ? (GROUND_STATES[_creator.characterGetGroundState(this._charId)] ?? "air") : "air"
   }
 
-  /** Current velocity (world units/s, fresh Vec3). */
+  /**
+   * READ — the velocity the solver ended up with after the most recent step (world units/s, fresh
+   * Vec3): what HAPPENED, not what you asked for. Walking into a wall reads ~0, sliding along one
+   * reads the tangent. Unlike Unity's synchronous `Move`, our step runs later in the frame, so a read
+   * is up to one frame old — irrelevant for animation speed, fall damage or "am I blocked", which is
+   * what it is for. (Exact wall contact would need a contact normal; the engine has none yet.)
+   *
+   * WRITE — LATCH the whole velocity: a knockback, a wall jump, a launch pad. Unlike `move()` it does
+   * not expire, so the character keeps flying, and gravity still pulls the vertical down into a real
+   * ballistic arc. It stays until `move()` takes the axis back — so a game simply doesn't call
+   * `move()` while the throw lasts, and ends it on its own terms:
+   *
+   *     hero.controller.velocity = [dir.x * 12, 6, dir.z * 12]   // hit by the blast
+   *     // …in the loop:
+   *     if (thrown) { if (hero.controller.grounded) thrown = false }   // landing ends it
+   *     else hero.controller.move(ix * SPEED, iz * SPEED)              // …and this reclaims the axis
+   *
+   * Note nothing clears the latch by itself, landing included — so a thrown character that never gets
+   * a `move()` keeps sliding along the ground (a kinematic controller has no friction).
+   *
+   * Reading is not the inverse of writing: `c.velocity = c.velocity` is NOT a no-op, because the read
+   * reports the measured result (against a wall it is ~0 and would cancel the throw). In flight the
+   * two agree closely, so read-modify-write mid-air behaves as expected.
+   *
+   * `c.velocity.y = 7` (the direct spelling) is a jump — the compiler routes it to the exact
+   * `velocityY` channel via `_writeComp` below, no vector allocated — and `c.velocity.x = 3` latches
+   * the whole vector with the measured velocity filling in the other two, i.e. the read-modify-write
+   * above spelled naturally. A STORED copy is still a copy: `const v = c.velocity; v.y = 7` does nothing.
+   */
   get velocity(): Vec3 {
-    const o = new Float32Array(3)
-    if (this._charId) _creator.characterGetVelocity(this._charId, o)
-    return new Vec3(o[0], o[1], o[2])
+    if (!this._charId) return new Vec3(0, 0, 0)
+    _creator.characterGetVelocity(this._charId, scratch)
+    return new Vec3(scratch[0], scratch[1], scratch[2])
   }
-
-  /** Teleport to a world position (clears vertical velocity). */
-  teleport(x: number, y: number, z: number): this {
-    if (this._charId) _creator.characterSetPosition(this._charId, x, y, z)
-    this._vy = 0
-    return this
+  set velocity(v: Vec3Like) {
+    if (this._charId) _creator.characterSetVelocity(this._charId, cx(v), cy(v), cz(v))
   }
 
-  update(dt: number): void {
+  /** Compile-time list (chisel reads it, then strips it): the getters whose `c.<getter>.<axis> = v`
+   *  spelling is routed to `_writeComp` below. See core/compWrite.ts. */
+  static _comps = [ "velocity" ]
+
+  /** @internal `c.velocity.<axis> = v` compiles to this: the vertical axis is the precise `velocityY`
+   *  channel, any other latches the whole vector with the measured rest. */
+  _writeComp(_prop: string, axis: CompAxis, v: number): void {
     if (!this._charId) return
-    const grounded = _creator.characterGetGroundState(this._charId) === 0
-    if (grounded && this._vy < 0) this._vy = 0          // landed
-    if (this._jumpQueued && grounded) this._vy = this.jumpSpeed
-    this._jumpQueued = false
-    this._vy += this.gravity * dt                        // integrate gravity (CharacterVirtual is kinematic)
-    _creator.characterSetVelocity(this._charId, this._mx * this.speed + this._ex, this._vy, this._mz * this.speed + this._ez)
+    if (axis === "y") { _creator.characterSetVerticalVelocity(this._charId, v); return }
+    _creator.characterGetVelocity(this._charId, scratch)
+    if (axis === "x") scratch[0] = v
+    else if (axis === "z") scratch[2] = v
+    _creator.characterSetVelocity(this._charId, scratch[0], scratch[1], scratch[2])
   }
 }

package/runtime/sdk/gl/Gearbox.ts

@@ -0,0 +1,212 @@
+// The gearbox of a `Vehicle`, as an aspect on the same node. It is deliberately NOT in the engine:
+// picking a gear is policy, not physics — two RPM thresholds and a latency timer — and every game
+// wants its own. The engine keeps only the physical half (the clutch's stiffness and the coupled
+// engine/wheel solve), and is told one ratio and one clutch scalar per frame.
+//
+//   car.aspect(Gearbox, { ratios: [2.66, 1.78, 1.3, 1.0, 0.74], reverse: -2.9 })
+//
+// A `Vehicle` with no `Gearbox` attaches this one with its defaults, so a car that never mentions
+// gears still drives.
+//
+// Custom behaviour is a subclass overriding ONE method:
+//
+//   class SportBox extends Gearbox {
+//     select(v: Vehicle): number { return v.rpm > 6200 ? this.gear + 1 : this.gear }
+//   }
+//
+// The clutch is two things multiplied. The SHIFT envelope (`shiftTime`/`clutchTime`) stays with the
+// base class on purpose: a forgotten ramp breaks a car silently — no drive at all, or a slammed
+// clutch. The TAKE-UP (`takeUp`) is the left-foot half, and is overridable for a car that launches
+// unusually — a torque converter, a rally launch control.
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import type { Node } from "./Node"
+import type { Vehicle } from "./Vehicle"
+
+// How far above idle counts as "revs to spare". A simulated engine cannot fall below its idle — the
+// physics clamps it — so being AT idle is the observable form of "the wheels are dragging me under".
+// This is the tolerance for reading that clamp, not a tuning knob.
+const IDLE_MARGIN = 1.05
+
+// The car this gearbox belongs to. Read through the aspect accessor rather than node.get(Vehicle),
+// so this file needs Vehicle only as a TYPE and the two do not import each other at runtime.
+const carOf = (n: Node): Vehicle | null => (n as unknown as { vehicle?: Vehicle }).vehicle ?? null
+
+export class Gearbox extends Aspect<"gearbox", Node> {
+  static readonly aspect = "gearbox"
+
+  /** Forward gear ratios, first gear first. Engine RPM = wheel speed × ratio × the differential. */
+  ratios: number[] = [ 2.66, 1.78, 1.3, 1.0, 0.74 ]
+  /** Reverse ratio — negative, because a ratio's SIGN is what reverse means to the engine. */
+  reverse = -2.9
+  /** Shift up when the engine passes this fraction of its redline. */
+  shiftUp = 0.67
+  /** Shift down when it falls below this fraction. */
+  shiftDown = 0.33
+  /** How long a shift takes, in seconds — the clutch is out for this long. */
+  shiftTime = 0.2
+  /** How long the clutch takes to re-engage afterwards. */
+  clutchTime = 0.3
+  /** How long to wait after a shift before another is allowed — without it a car sitting on a
+   *  threshold hunts between two gears. */
+  latency = 0.5
+
+  /** How far the clutch bites the instant drive is asked for from rest, 0..1. It only has to COUPLE
+   *  the shafts — how much torque that passes is the engine's business, so a feathered throttle
+   *  still pulls away gently at the same bite point. */
+  bite = 0.4
+
+  static fields: FieldMeta<Gearbox> = {
+    reverse: { max: -0.1, step: 0.1 },
+    shiftUp: { min: 0.1, max: 1, step: 0.01 },
+    shiftDown: { min: 0, max: 0.9, step: 0.01 },
+    shiftTime: { min: 0, max: 3, step: 0.05 },
+    clutchTime: { min: 0, max: 3, step: 0.05 },
+    latency: { min: 0, max: 3, step: 0.05 },
+    bite: { min: 0, max: 1, step: 0.05 },
+    ratios: { hidden: true },
+  }
+
+  /** Current gear: −1 reverse, 0 neutral, 1… forward. Read it for a HUD. */
+  gear = 0
+  /** True while a shift is in progress — the clutch is out and the engine is not driving the wheels. */
+  get shifting(): boolean { return this._shiftLeft > 0 }
+
+  private _shiftLeft = 0      // seconds of clutch-out left
+  private _engageLeft = 0     // seconds of clutch re-engagement left
+  private _waitLeft = 0       // anti-hunting
+  private _take = 0           // how far the CAR's own state wants the clutch in, latched per frame
+
+  /** EARLY phase: the pair has to be latched before this frame's step consumes it. */
+  updateBefore(dt: number): void {
+    const v = carOf(this.node)
+    if (!v || !v.id) return
+
+    this._waitLeft = Math.max(0, this._waitLeft - dt)
+
+    if (this._shiftLeft > 0) {
+      // Mid-shift: clutch fully out, and the moment it ends the re-engagement ramp starts.
+      this._shiftLeft = Math.max(0, this._shiftLeft - dt)
+      if (this._shiftLeft === 0) this._engageLeft = this.clutchTime
+    } else {
+      const want = this.select(v)
+      if (want !== this.gear) this.shift(want)
+      else this._engageLeft = Math.max(0, this._engageLeft - dt)
+    }
+
+    // The pedal only moves while no shift is in flight. During one the revs say nothing about
+    // whether the wheels can sustain them: an engine still spinning down from the last gear reads as
+    // "revs to spare" and would drop the clutch straight back in — enough to shove a stopped car
+    // several km/h with no throttle at all. Freezing it is what a driver does anyway; the foot is
+    // already down, and the envelope owns the clutch until the gear is in.
+    if (this._shiftLeft === 0 && this._engageLeft === 0) {
+      this._take = Math.max(0, Math.min(1, this.takeUp(v, dt)))
+    }
+
+    v._setTransmission(this.ratio, this.clutch)
+  }
+
+  /**
+   * The driver's left foot: where the clutch pedal is, ignoring shifts. Returns the new engagement.
+   *
+   * A driver does not compute anything. They watch the tacho: **revs sinking to idle means the
+   * wheels are about to drag the engine under, and that is when you push the clutch in.** That
+   * single test replaces every ratio and threshold — the crossover it finds is the exact speed where
+   * engine braking stops and the engine would start PUSHING instead, and it finds it per gear
+   * without being told the gear.
+   *
+   * The pedal comes back UP only for the throttle. Healthy revs are not on their own a reason to
+   * engage: a car standing still shows healthy revs too — the wheels simply are not turning to say
+   * otherwise — and a clutch dropped on that evidence lurches the car off with no throttle at all.
+   *
+   * Three things fall out of it for free:
+   *
+   * - **A braked car stops.** The engine cannot stall, so a clutch left in at 0 km/h feeds idle
+   *   torque to the wheels forever and the car creeps against its own brakes. Here the revs pin at
+   *   idle, so the pedal goes down and the brakes have nothing to fight.
+   * - **Reverse is not a special case.** No ratio takes part, so it needs no separate number — which
+   *   is exactly why a fixed road-speed threshold got reverse wrong.
+   * - **Hill starts judder instead of stalling.** Let the pedal out, the load pulls the revs down,
+   *   the rule pushes it straight back in, and the clutch sits slipping at the bite point until the
+   *   car moves. So the test deliberately ignores the throttle — gating it on "no throttle" would
+   *   stall the car under load. Throttle only holds the floor at `bite`.
+   *
+   * The cost is honest and small: once the pedal is down the revs sit at idle and cannot rise on
+   * their own, so **coasting downhill gives no engine braking until you touch the throttle** — which
+   * is precisely what a car with the clutch in does. Slipping it permanently to keep listening would
+   * bring the creep straight back.
+   */
+  protected takeUp(v: Vehicle, dt: number): number {
+    if (this.gear === 0) return 0
+    const idle = v.engine.idleRpm ?? 1000
+    const step = dt / Math.max(this.clutchTime, dt)
+    const asked = v.throttle !== 0
+    let take = this._take
+    if (v.rpm <= idle * IDLE_MARGIN) take -= step   // being dragged under: pedal goes down
+    else if (asked) take += step                    // revs to spare AND somewhere to go: let it up
+    // Asking for drive also holds the pedal at the bite point however far down the rule wants it;
+    // that is what makes a launch — and a hill start — slip instead of collapsing to nothing.
+    return asked ? Math.max(take, this.bite) : take
+  }
+
+  /**
+   * Which gear the car should be in. The default is an ordinary automatic: pull away from neutral in
+   * the direction of the throttle, shift up past `shiftUp` of the redline and down below `shiftDown`,
+   * and refuse to shift again for `latency` seconds. Override this and nothing else.
+   */
+  select(v: Vehicle): number {
+    const throttle = v.throttle
+    // Neutral, or asked to go the other way: engage once the car has (nearly) stopped.
+    if (this.gear === 0 || throttle * this.gear < 0) {
+      if (Math.abs(v.speed) > 1 && this.gear !== 0) return this.gear
+      return throttle > 0 ? 1 : throttle < 0 ? -1 : this.gear
+    }
+    if (this.gear < 0 || this._waitLeft > 0 || this.shifting) return this.gear
+    const rpm = v.rpm
+    const max = v.engine.maxRpm ?? 6000
+    // Upshifting needs COUPLED revs. With the clutch out the engine is free, so a blip at a
+    // standstill reads as 6000 rpm and the box would climb to top gear without the car moving —
+    // then launch in it. Downshifting stays open either way: it can only take you to a lower gear,
+    // which is where a car with dying revs belongs.
+    if (rpm > max * this.shiftUp && this.clutch >= 1 && this.gear < this.ratios.length) return this.gear + 1
+    if (rpm < max * this.shiftDown && this.gear > 1) return this.gear - 1
+    return this.gear
+  }
+
+  /** Change gear now, with the clutch envelope. Safe to call from `select()` or from game code
+   *  (a sequential manual is `if (Input.key('KeyE')) car.gearbox.shift(car.gearbox.gear + 1)`). */
+  shift(gear: number): void {
+    const clamped = Math.max(-1, Math.min(this.ratios.length, Math.round(gear)))
+    if (clamped === this.gear) return
+    // The envelope is for swapping one ENGAGED gear for another. If nothing is coupled there is
+    // nothing to disengage, so it is skipped: neutral at either end, and equally a car sitting still
+    // with the pedal already down — picking reverse there should pull away the moment it is asked
+    // to, not sit out a shift it never had to make.
+    const swapping = this.gear !== 0 && clamped !== 0 && this._take > 0
+    this.gear = clamped
+    this._shiftLeft = swapping ? this.shiftTime : 0
+    this._engageLeft = swapping ? this.clutchTime : 0
+    this._waitLeft = this.latency + this._shiftLeft
+  }
+
+  /** The ratio the engine should be running: 0 in neutral, negative in reverse. */
+  get ratio(): number {
+    if (this.gear === 0) return 0
+    if (this.gear < 0) return this.reverse
+    return this.ratios[this.gear - 1] ?? 1
+  }
+
+  /**
+   * The clutch scalar 0..1 the engine is given: the SHIFT envelope (out during a shift, ramping back
+   * over `clutchTime`) times the driver's pedal (`takeUp`). Two independent reasons for the clutch
+   * to be out, so they multiply: mid-shift is out however healthy the revs are, and an engine being
+   * dragged to idle is out whatever gear it just picked.
+   */
+  get clutch(): number {
+    if (this._shiftLeft > 0) return 0
+    const envelope =
+      this._engageLeft > 0 && this.clutchTime > 0 ? 1 - this._engageLeft / this.clutchTime : 1
+    return envelope * this._take
+  }
+}