lecodes-cli 0.17.2 → 0.18.1

package/runtime/sdk/gl/CharacterController.ts

@@ -4,44 +4,70 @@
 //
 //   const hero = new Mesh(capsuleGeometry(), material)
 //     .aspect(Shape, { capsule: { halfHeight: 0.6, radius: 0.3 } })
-//     .aspect(CharacterController, { speed: 6, jumpSpeed: 8 })
-//   Input.on('move', (x, z) => hero.controller.move(x, z))
-//   Input.on('jump', () => 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
@@ -53,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
+  }
+}

package/runtime/sdk/gl/Geometry.ts

@@ -20,6 +20,11 @@ export class Geometry {
   normals: Float32Array
   indices: Uint16Array
   uv: Float32Array
+  /** Lightmap UV set (2 floats per vertex, non-overlapping, inside the unit square) — the
+   *  `Lightmap` atlas samples a Mesh through it. The box and cylinder builders fill it (their `uv`
+   *  tiles per face, which would fold every face onto the same texels); absent = the host reuses
+   *  `uv`, which is right for a plane. */
+  uv1?: Float32Array
   /** @internal native mesh-type enum (0 triangles / 1 edges / 2 vertices). */
   _meshKind = 0
 
@@ -50,29 +55,75 @@ export class Geometry {
     this._meshKind = kind === "edges" ? 1 : kind === "vertices" ? 2 : 0
   }
 
-  static box(): Geometry { return createCube() }
+  /** A box; `size` (default 1) scales the vertices AND lays the lightmap chart out in proportion to
+   *  the faces' areas (a floor's top face gets the texels, not its 1 m side strips). */
+  static box(size: Vec3Like | number = 1): Geometry { return createCube(size) }
   static sphere(options?: SphereOptions): Geometry { return createSphere(options) }
   static cylinder(options?: CylinderOptions): Geometry { return createCylinder(options) }
   static plane(options?: PlaneOptions): Geometry { return createPlane(options) }
 }
 
+// Gutter between lightmap charts (fraction of the chart square): the bake dilates each rect by a
+// few texels and the shader samples bilinearly, so neighbouring faces must not touch in uv1.
+const LM_GUTTER = 0.03
+
+type Rect = { x: number, y: number, w: number, h: number }
+
+/** Shelf-pack rectangles (metres) into the unit square at the largest uniform scale — every face
+ *  gets texels in proportion to its area, so a 64×1×64 floor's top face isn't squeezed into the
+ *  same cell as its 1 m side strips. Returns rects in input order. */
+const packCharts = (dims: [number, number][]): Rect[] => {
+  const order = dims.map((_, i) => i).sort((a, b) => dims[b][1] - dims[a][1])
+  const attempt = (scale: number): Rect[] | null => {
+    const out: Rect[] = new Array(dims.length)
+    let x = 0, y = 0, rowH = 0
+    for (const i of order) {
+      const w = dims[i][0] * scale, h = dims[i][1] * scale
+      if (x > 0 && x + w > 1) { y += rowH + LM_GUTTER; x = 0; rowH = 0 }
+      if (w > 1 || y + h > 1) return null
+      out[i] = { x, y, w, h }
+      x += w + LM_GUTTER
+      rowH = Math.max(rowH, h)
+    }
+    return out
+  }
+  let lo = 0, hi = 1 / Math.max(...dims.map((d) => Math.max(d[0], d[1])))
+  let best = attempt(hi)
+  if (!best) {
+    for (let it = 0; it < 40; it++) {
+      const mid = (lo + hi) / 2
+      const r = attempt(mid)
+      if (r) { best = r; lo = mid } else hi = mid
+    }
+  }
+  return best ?? dims.map(() => ({ x: 0, y: 0, w: 1, h: 1 }))
+}
+
 // --- cube ---
-const createCube = (): Geometry => {
+const createCube = (size: Vec3Like | number = 1): Geometry => {
+  const sx = typeof size === "number" ? size : cx(size)
+  const sy = typeof size === "number" ? size : cy(size)
+  const sz = typeof size === "number" ? size : cz(size)
   const vertices = new Float32Array(6 * 4 * 3)
   const normals = new Float32Array(6 * 4 * 3)
-  const uv = new Float32Array(6 * 4 * 3)
+  const uv = new Float32Array(6 * 4 * 2)
+  const uv1 = new Float32Array(6 * 4 * 2)
   const indices = new Uint16Array(6 * 6)
   let cnt = 0, indicesCnt = 0
   const sides = [ -0.5, 0.5 ]
+  // face extents along the (a, b) parameters below: ±x faces span (z, y), ±y faces (x, z), ±z faces (x, y)
+  const charts = packCharts([ [ sz, sy ], [ sz, sy ], [ sx, sz ], [ sx, sz ], [ sx, sy ], [ sx, sy ] ])
   for (let i = 0; i < 6; i++) {
     const s = cnt
     const side = i % 2 === 0 ? -0.5 : 0.5
+    const c = charts[i]
     for (const a of sides) {
       for (const b of sides) {
         uv.set([ a + 0.5, b + 0.5 ], cnt * 2)
-        if (i === 0 || i === 1) { vertices.set([ side, b, -a ], cnt * 3); normals.set([ side * 2, 0, 0 ], cnt * 3) }
-        if (i === 2 || i === 3) { vertices.set([ a, side, -b ], cnt * 3); normals.set([ 0, side * 2, 0 ], cnt * 3) }
-        if (i === 4 || i === 5) { vertices.set([ a, b, side ], cnt * 3); normals.set([ 0, 0, side * 2 ], cnt * 3) }
+        uv1.set([ c.x + (a + 0.5) * c.w, c.y + (b + 0.5) * c.h ], cnt * 2)
+        if (i === 0 || i === 1) { vertices.set([ side * sx, b * sy, -a * sz ], cnt * 3); normals.set([ side * 2, 0, 0 ], cnt * 3) }
+        if (i === 2 || i === 3) { vertices.set([ a * sx, side * sy, -b * sz ], cnt * 3); normals.set([ 0, side * 2, 0 ], cnt * 3) }
+        if (i === 4 || i === 5) { vertices.set([ a * sx, b * sy, side * sz ], cnt * 3); normals.set([ 0, 0, side * 2 ], cnt * 3) }
         cnt++
       }
     }
@@ -81,7 +132,9 @@ const createCube = (): Geometry => {
     else indices.set([ s2, s1, s, s1, s2, s3 ], indicesCnt)
     indicesCnt += 6
   }
-  return new Geometry(vertices, normals, indices, uv)
+  const g = new Geometry(vertices, normals, indices, uv)
+  g.uv1 = uv1
+  return g
 }
 
 // --- sphere ---
@@ -143,6 +196,8 @@ const createCylinder = (options: CylinderOptions = {}): Geometry => {
   const vertices = new Float32Array(verticesCount * 3)
   const normals = new Float32Array(verticesCount * 3)
   const uv = new Float32Array(verticesCount * 2)
+  // lightmap chart: the side strip across the upper half, the two caps as discs in the lower half
+  const uv1 = new Float32Array(verticesCount * 2)
   const indices = new Uint16Array(edges * 6 + edges * 6)
   const sides = [ -0.5, 0.5 ]
   let cnt = 0, indicesCnt = 0
@@ -159,6 +214,7 @@ const createCylinder = (options: CylinderOptions = {}): Geometry => {
         if (smooth) normals.set([ x, 0, y ], cnt * 3)
         else normals.set([ normalX, 0, normalY ], cnt * 3)
         uv.set([ (i + j) / edges, side + 0.5 ], cnt * 2)
+        uv1.set([ (i + j) / edges, 0.55 + (side + 0.5) * 0.43 ], cnt * 2)
         cnt++
       }
     }
@@ -168,19 +224,24 @@ const createCylinder = (options: CylinderOptions = {}): Geometry => {
   }
   for (const side of sides) {
     const center = cnt
-    vertices.set([ 0, side, 0 ], cnt * 3); normals.set([ 0, side * 2, 0 ], cnt * 3); cnt++
+    const capU = side > 0 ? 0.75 : 0.25   // lightmap disc centre per cap
+    vertices.set([ 0, side, 0 ], cnt * 3); normals.set([ 0, side * 2, 0 ], cnt * 3)
+    uv1.set([ capU, 0.25 ], cnt * 2); cnt++
     for (let i = 0; i < edges; i++) {
       const x = Math.cos(i / edges * Math.PI * 2), y = Math.sin(i / edges * Math.PI * 2)
       if (side > 0) vertices.set([ x * radiusTop, side, y * radiusTop ], cnt * 3)
       else vertices.set([ x * radiusBottom, side, y * radiusBottom ], cnt * 3)
       normals.set([ 0, side * 2, 0 ], cnt * 3)
+      uv1.set([ capU + x * 0.22, 0.25 + y * 0.22 ], cnt * 2)
       if (side < 0) indices.set([ center, center + i + 1, center + 1 + ((i + 1) % edges) ], indicesCnt)
       else indices.set([ center + 1 + ((i + 1) % edges), center + i + 1, center ], indicesCnt)
       indicesCnt += 3
       cnt++
     }
   }
-  return new Geometry(vertices, normals, indices, uv)
+  const g = new Geometry(vertices, normals, indices, uv)
+  g.uv1 = uv1
+  return g
 }
 
 // --- plane ---