@genex-ai/cli-demo 0.11.0 → 0.14.2

package/templates/skills/genex-threejs-vehicle-controllers/references/car.md

@@ -0,0 +1,162 @@
+# Car: VehicleController + ShapeCastWheel
+
+The car is three cooperating pieces:
+
+- **`VehicleController`** (`vehicle/vehicle-controller.ts`) — the brain. It
+  creates a dynamic Rapier body **without colliders**, owns the drivetrain
+  (engine torque curve, gear ratios, RPM-threshold auto shift), routes
+  drive/brake/steer demands to the wheels, and applies their suspension +
+  friction impulses to the body.
+- **`ShapeCastWheel`** (`vehicle/wheel.ts`) — one per corner, created via
+  `car.addWheel()`. Each wheel sweeps a cylinder at the ground, computes a
+  suspension spring/damper impulse and slip-curve tire friction, and drives
+  its own visual groups (steer, suspension bounce, spin).
+- **`vehiclePresets`** (`vehicle/presets.ts`) — complete car recipes:
+  `carConfig`, chassis collider specs, shared wheel options, and four wheel
+  slots (order FL, FR, RL, RR).
+
+Conventions: **+Z is the car's forward axis**, +X is left, and positive steer
+input turns LEFT. Wheel `position` is the axle mount point in chassis-local
+space.
+
+## Wiring (matches the shipped preset shapes)
+
+```ts
+import * as THREE from "three";
+import { PhysicsWorld } from "./controllers/shared/physics-world.ts";
+import { cuboidCollider } from "./controllers/shared/colliders.ts";
+import { VehicleController } from "./controllers/vehicle/vehicle-controller.ts";
+import { vehiclePresets } from "./controllers/vehicle/presets.ts";
+import { KeyboardInput } from "./controllers/character/keyboard-input.ts";
+
+const physics = await PhysicsWorld.create();
+const world = physics.world;
+
+// 1. Controller (creates the dynamic body — no colliders yet).
+const preset = vehiclePresets["arcade-kart"];
+const car = new VehicleController({
+  world,
+  position: new THREE.Vector3(12, 1.4, 4),
+  carConfig: preset.carConfig,
+});
+
+// 2. Chassis colliders — YOU attach them to car.body from the preset recipe.
+for (const c of preset.chassisColliders) {
+  cuboidCollider(world, car.body, [c.halfExtents.x, c.halfExtents.y, c.halfExtents.z], {
+    position: [c.offset.x, c.offset.y, c.offset.z],
+    density: c.density,
+  });
+}
+
+// 3. Wheels — shared options + per-slot role flags. Register all four
+//    before the first update() so the torque split is stable.
+const wheelGeom = new THREE.CylinderGeometry(0.5, 0.5, 0.3, 20);
+wheelGeom.rotateZ(Math.PI / 2); // the wheel model spins around LOCAL X
+for (const slot of preset.wheelSlots) {
+  const wheel = car.addWheel({
+    ...preset.wheelShared,
+    ...slot,
+    position: new THREE.Vector3(slot.position.x, slot.position.y, slot.position.z),
+  });
+  const mesh = new THREE.Mesh(wheelGeom, wheelMat);
+  wheel.modelObject.add(mesh); // wheelGroup steers, suspensionGroup bounces, modelObject spins
+}
+
+// 4. Scene graph: chassis mesh under chassisObject, chassisObject in the scene.
+car.chassisObject.add(carBodyMesh); // your visual chassis (a genex model GLB works)
+scene.add(car.chassisObject);
+physics.registerBody(car.body, car.chassisObject); // interpolated render sync
+
+// 5. Input + fixed-step update (BEFORE world.step(), via onBeforeStep).
+const kb = new KeyboardInput(); // WASD/arrows drive+steer, Space = brake
+physics.onBeforeStep(() => {
+  car.setMovement(kb.getCarMovement());
+  car.update();
+});
+```
+
+`setMovement` merges field-wise — send the complete `CarMovementIntent`
+every frame (a stale partial leaves old `true`s behind), which
+`kb.getCarMovement()` already does. Touch input: pass
+`{ joystickL: { x, y } }` from `TouchJoystick` (pushing right steers right).
+
+If an on-foot character shares the world, create its body with
+`userData: { controller: { excludeVehicleRay: true } }` so the wheels never
+treat the player as drivable ground.
+
+## Presets and provenance
+
+| Preset | Drivetrain | Suspension | Notes |
+| --- | --- | --- | --- |
+| `arcade-kart` | 600 HP, AWD, front steer, single gear | stiff (springK 38000) | upstream demo "Vehicle 1", verbatim. The safe default. |
+| `muscle-drift` | 600 HP, AWD with rear `driveTorqueWeight: 2` | soft (springK 25000) | upstream demo "Vehicle 2", verbatim. Power-oversteers into drifts under throttle. |
+| `offroad-bouncy` | 450 HP, AWD, wider steering | soft, long travel (rayLength 0.8), bigger wheels | Genex-authored starting point derived from arcade-kart. |
+| `race-grip` | 800 HP, RWD, 4-speed gearbox | very stiff (springK 42000) | Genex-authored, tuned in the testbed (see below). |
+
+**Suspension scales with mass.** `springK`/`dampingC` in `wheelShared` were
+tuned against each preset's `assumedChassisDensity` (200 for all four). If
+your chassis is materially heavier or lighter, rescale `springK`
+proportionally and keep `dampingC` below `2*sqrt(springK * massPerWheel)` —
+too little spring bottoms out, too much damping locks the suspension solid.
+
+## Gearbox and RPM
+
+- Peak engine torque derives as `engineHorsepower * 7022 / engineMaxRPM`
+  (N·m); "car feels slow" → raise `engineHorsepower`.
+- A single-entry `gearRatios` (arcade-kart, muscle-drift) disables shifting.
+  Multiple entries enable the auto shift: up above `shiftUpRPM`, down below
+  `shiftDownRPM`, with `shiftCooldown` seconds between shifts.
+  `transmissionMode: "manual"` shifts only via `car.setGear(index)`.
+- Live telemetry for HUDs: `car.engineRPM` (drive-weighted average wheel RPM
+  × drive ratio), `car.gearIndex` (0-based — display `gearIndex + 1`),
+  `car.currLinVel.length() * 3.6` for km/h.
+- **Why race-grip's gearing works** (and what to check if you author your
+  own gearbox): rolling resistance grows with wheel speed, so each gear has
+  a drag-limited equilibrium RPM it can never exceed on flat ground
+  (measured in the testbed: ~5500 / ~4900 / ~4100 for race-grip's gears
+  1–3). `shiftUpRPM` must sit BELOW the current gear's equilibrium or the
+  shift point is never reached and the car sits at redline forever.
+  race-grip uses `shiftUpRPM: 4300`, giving clean upshifts with post-shift
+  RPM ~2800–3000 — safely above `shiftDownRPM: 2400`, so no gear hunting.
+  Lower `rollingResistanceCoef` (race-grip: 0.004 vs default 0.007) raises
+  every gear's ceiling and buys the shifter headroom.
+
+## Drift tuning: tire grip vs rollover
+
+The knobs, in the order to reach for them:
+
+- `tireGripFactor` (wheel option, default 1.5) — averaged with the ground
+  collider's friction: effective grip = `(surfaceFriction + tireGripFactor) / 2`.
+  Lower = more slide everywhere.
+- `latFrictionEllipseScale` — scales ONLY the cornering half of the friction
+  ellipse. The direct drift knob: below 1 the car slides sideways sooner
+  while braking/accelerating stay strong.
+- `driveTorqueWeight` on the rear slots (muscle-drift uses 2) — rear-biased
+  torque makes throttle break the rear loose.
+- Brake-and-turn (Space is the brake) initiates a slide with any preset.
+
+**The rollover trap** — measured in the testbed while retuning `race-grip`:
+the lateral slip curve keeps ~90% grip even in a full slide, so peak lateral
+acceleration is about `(surfaceFriction + tireGripFactor) / 2 *
+latFrictionEllipseScale` in g. If that exceeds the chassis's static rollover
+threshold (`halfTrack / comHeight` — ~1.0 g for the race-grip chassis), a
+hard slide TRIPS THE CAR OVER instead of drifting. The race-grip retune
+fixed exactly this, two-sided:
+
+1. capped lateral grip with `latFrictionEllipseScale: 0.8` (and
+   `lngFrictionEllipseScale: 1.15` so braking/launch stay strong), and
+2. lowered the center of mass — a light cabin collider (density 60) over a
+   low-slung main mass (offset y −0.15) keeps the CoM near axle height so
+   hard cornering leans instead of tipping.
+
+If your car flips in corners, do the same: lower the grip-side product or
+lower the CoM. Raising `springK` alone does not fix rollover.
+
+## Telemetry for effects
+
+Per wheel (from `car.wheels`, a `ReadonlyMap<string, ShapeCastWheel>`):
+`wheel.slipStrength` (0..1, max of longitudinal/lateral slip — the skid
+smoke/screech trigger), `wheel.rayHitPos` + `wheel.rayHitNormal` (where to
+spawn marks), `wheel.wheelLinVel` (surface speed), `wheel.rayHit` (null when
+airborne). Vector getters are live internal instances — `.copy()` them,
+never mutate. Value getters are one-frame-stale snapshots by design.

package/templates/skills/genex-threejs-vehicle-controllers/references/drone.md

@@ -0,0 +1,150 @@
+# Drone: DroneController + propellers
+
+`DroneController` (`drone/drone-controller.ts`) is a PD flight brain over a
+**caller-created** dynamic body: each registered propeller contributes thrust
+along its mount's local +Y plus a reaction torque; every step the brain
+computes a hover throttle (weight / total upward thrust potential) and mixes
+per-propeller attitude corrections on top, clamped so attitude control never
+costs altitude. Unlike the car, the controller never creates or frees the
+body — you build body, colliders, and chassis visuals, then hand them over.
+
+`dronePresets` (`drone/presets.ts`) are complete recipes: `config` (merged
+over `DEFAULT_DRONE_CONFIG`), four propeller slots in a quad-X layout, and a
+collider recipe (`body`) with the density the gains were tuned against.
+
+## Wiring (from the preset recipe)
+
+```ts
+import * as THREE from "three";
+import { PhysicsWorld } from "./controllers/shared/physics-world.ts";
+import { cuboidCollider, cylinderCollider } from "./controllers/shared/colliders.ts";
+import { DroneController, type PropellerOptions } from "./controllers/drone/drone-controller.ts";
+import { dronePresets } from "./controllers/drone/presets.ts";
+import { KeyboardInput } from "./controllers/character/keyboard-input.ts";
+
+const physics = await PhysicsWorld.create();
+const preset = dronePresets["camera-drone"];
+
+// 1. Chassis visual root + one mount Object3D per propeller (descendants of
+//    the chassis; local +Y = thrust axis). spinModel is optional blade visual.
+const chassis = new THREE.Group();
+chassis.add(coreMesh); // your body visual
+const propellers: PropellerOptions[] = [];
+for (const p of preset.propellers) {
+  const mount = new THREE.Object3D();
+  mount.position.set(p.position.x, p.position.y, p.position.z);
+  chassis.add(mount);
+  const blade = new THREE.Mesh(bladeGeom, bladeMat);
+  mount.add(blade);
+  propellers.push({
+    object: mount,
+    spinModel: blade,
+    maxThrust: p.maxThrust,
+    torqueRatio: p.torqueRatio,
+    invertTorque: p.invertTorque,
+  });
+}
+scene.add(chassis);
+
+// 2. Dynamic body + colliders from the preset recipe (density sets the mass).
+const body = physics.createBody({ type: "dynamic", position: [-6, 1.6, 14] }, chassis);
+const b = preset.body;
+cuboidCollider(physics.world, body,
+  [b.cuboidHalfExtents.x, b.cuboidHalfExtents.y, b.cuboidHalfExtents.z],
+  { density: b.density });
+for (const pos of b.armCylinders.positions) {
+  cylinderCollider(physics.world, body, b.armCylinders.halfHeight, b.armCylinders.radius,
+    { position: [pos.x, pos.y, pos.z], density: b.density });
+}
+
+// 3. Controller + fixed-step update (BEFORE world.step()).
+const drone = new DroneController({
+  world: physics.world,
+  body,
+  chassis,
+  propellers,
+  config: preset.config,
+});
+const kb = new KeyboardInput(); // W/S throttle, A/D yaw, arrows pitch/roll
+physics.onBeforeStep(() => {
+  drone.setMovement(kb.getDroneMovement());
+  drone.update();
+});
+```
+
+The keyboard scheme is deliberately asymmetric (WASD = throttle/yaw, arrows
+= pitch/roll — they are NOT aliases; do not "unify" them). Touch sticks map
+as `joystickL` = climb/yaw, `joystickR` = pitch/roll.
+
+## Control modes: VELOCITY vs POSITION
+
+`DroneControlMode` — switch at runtime with `drone.setControlMode(mode)`:
+
+- **`"VELOCITY"`** — stick flying: inputs command velocities (up to
+  `maxHorizSpeed` / `maxVertSpeed` / `maxYawRate`) and the PD loop converts
+  them to tilt + throttle. Use while a player is on board.
+- **`"POSITION"`** — autopilot: the drone holds `targetPos` and faces
+  `targetFwd`. Use for parked, idle, or scripted drones. The parking recipe
+  (also what the enter/exit hook does on dismount):
+
+```ts
+drone.setTarget(drone.currPos, drone.bodyZAxis); // hold HERE, facing THIS way
+drone.setControlMode("POSITION");
+```
+
+Set the target BEFORE anything else moves — `currPos`/`bodyZAxis` are live
+vectors; `setTarget` copies them.
+
+## The PD gain mass-scaling rule
+
+`DroneConfig` gains fall into two families — this is the single most common
+tuning mistake:
+
+- **`VERT_POS_P/D`, `HORIZ_POS_P/D`** (POSITION-mode hold gains) are in
+  **absolute force units** — they MUST scale with the drone's mass. The
+  library defaults fit a ~2 kg drone; the `heavy-lifter` preset (~298 kg)
+  ships them pre-scaled ×100 (e.g. `VERT_POS_P: 900` vs default 9). A drone
+  that sags away from its hold point or oscillates around it after a mass
+  change has stale POSITION gains.
+- **`HORIZ_VEL_P`, `VERT_VEL_P`** (VELOCITY-mode gains) are in
+  **acceleration units** — mass-independent, usually fine as-is.
+- `airDragFactor` is also an absolute force per (m/s): meaningful on a 2 kg
+  drone, cosmetic on a 300 kg one.
+- Attitude feel: sluggish to tilt → raise `TILT_P`; wobbles/overshoots after
+  a maneuver → raise `TILT_D`. `maxTiltAngle` caps how far it leans (and
+  therefore horizontal acceleration).
+
+Tune at runtime with `drone.updateConfig({ TILT_P: 18 })` — it recomputes
+the cached tilt limit when `maxTiltAngle` changes.
+
+## Propeller sizing
+
+- Size `maxThrust` so total thrust ≈ **2× the drone's weight**: hover
+  throttle then sits near 0.5, which maximizes attitude authority (the mixer
+  clamps corrections to `min(1 - hover, hover)`). Check `drone.hoverThrottle`
+  at runtime — near 1 means underpowered (climbs barely, steers worse).
+- Diagonal pairs must share the same `invertTorque` value (quad-X
+  counter-rotation) or reaction torques won't cancel and the drone yaws
+  constantly.
+- `debug: true` on a propeller attaches upstream thrust/torque arrows +
+  axis markers under the mount — great while building a custom frame.
+
+## Presets and provenance
+
+| Preset | Mass | Feel | Provenance |
+| --- | --- | --- | --- |
+| `camera-drone` | ~2 kg (density 335) | gentle 20° tilt limit, strong drag, floaty on purpose | Genex-authored |
+| `racing-drone` | ~5 kg (density 240) | full 45° tilt, fast yaw, snappy `TILT_P: 18` | Genex-authored |
+| `heavy-lifter` | ~298 kg (density 200) | huge climb reserve, hover ~0.146, POSITION gains ×100 | upstream demo, verbatim |
+
+Each preset's `notes` field carries its own plain-language tuning hints; the
+`approxMassKg`/`approxHoverThrottle` fields are documentation values (Rapier
+derives the real mass from the colliders and density).
+
+## Telemetry for effects
+
+`drone.propellersInfo` (a `ReadonlyMap<string, PropellerState>`) exposes per
+propeller: `finalThrottle` (0..1 mixer output — rotor-wash/audio intensity),
+`worldThrustPos`/`worldThrustDir` (where and which way to emit), and
+`thrustImpulse`. `drone.hoverThrottle` reads the last computed hover value.
+All vectors are reused internal instances — copy, never mutate.

package/templates/skills/genex-threejs-vehicle-controllers/references/enter-exit.md

@@ -0,0 +1,199 @@
+# Enter/exit: character ↔ vehicle handoff
+
+`EnterExitManager` (`interact/enter-exit.ts`) owns the whole flow: it puts a
+proximity sensor on every registered vehicle, surfaces a "Press F" prompt
+when the on-foot character walks into one, and on interact **parks** the
+character (hidden + physics disabled) and hands control — input routing and
+camera target — to the vehicle; interacting again places the character
+beside the vehicle and hands control back.
+
+It needs the on-foot character from `npx genex controller character`
+(`CharacterController` implements the `park()`/`unpark()` contract the
+manager calls; see `$genex-threejs-character-controller`). `CHARACTER_ID`
+(`"character"`) is the reserved id for the on-foot unit.
+
+## Wiring
+
+```ts
+import { EnterExitManager, CHARACTER_ID } from "./controllers/interact/enter-exit.ts";
+
+const mgr = new EnterExitManager({
+  world: physics.world,
+  character, // the CharacterController instance
+  applyCharacterInput: () => {
+    character.setMovement(kb.getCharacterMovement()); // routed only while on foot
+  },
+  onPromptChange: (target) => {
+    // Drive your DOM prompt from here; fires on change only (incl. -> null).
+    promptEl.textContent = target ? `Press F to enter ${target.label}` : "";
+    promptEl.style.display = target ? "block" : "none";
+  },
+  onHandoff: (fromId, toId) => {
+    // Fires after control switches — seat visuals + input hygiene (below).
+  },
+});
+
+mgr.registerVehicle({
+  id: "car",
+  label: "Car",
+  vehicle: car,                       // VehicleController satisfies this structurally
+  exitAxis: "bodyX",                  // cars step out sideways
+  exitLength: 2.2,
+  // radius ≥ the chassis half-length (2.4 here) — see "Sensor and exit tuning".
+  sensor: { kind: "cylinder", halfHeight: 0.5, radius: 2.5, offset: { x: 0, y: 0.1, z: 0 } },
+  applyInput: () => car.setMovement(kb.getCarMovement()), // routed only while driving
+});
+
+mgr.registerVehicle({
+  id: "drone",
+  label: "Drone",
+  vehicle: drone,
+  exitAxis: "up",                     // the drone drops the pilot off below it
+  exitLength: 1.6,
+  sensor: { kind: "ball", radius: 2.4 },
+  applyInput: () => drone.setMovement(kb.getDroneMovement()),
+  onOccupantEnter: () => {
+    drone.setControlMode("VELOCITY"); // stick flying while boarded
+  },
+  onOccupantExit: () => {
+    // Fires BEFORE the character is unparked — capture the hold pose first.
+    drone.setTarget(drone.currPos, drone.bodyZAxis);
+    drone.setControlMode("POSITION"); // autopilot-hover where it was left
+  },
+});
+
+// Sensor events: feed the raw collision tap into the manager.
+physics.onCollisionEvent((h1, h2, started) =>
+  mgr.handleIntersectionEvent(h1, h2, started)
+);
+
+// Interact: EDGE-triggered (key transition, never a held-key poll — that
+// would enter and exit every frame). kb.onInteract is the F key, pre-guarded.
+kb.onInteract(() => mgr.requestInteract());
+```
+
+Loop order per fixed substep (inside `physics.onBeforeStep`): **`mgr.update(dt)`
+FIRST** (consumes the interact request, refreshes the camera feed, routes
+input to the active unit), then the controller `update()`s, then the world
+steps. Skip `character.update()` while `character.isParked`. Sensor events
+drain after the step, so proximity lags input by at most one frame — as
+designed.
+
+Registration order = prompt priority: when two sensors overlap, the first
+registered vehicle wins the prompt.
+
+## Sensor and exit tuning
+
+- Default sensor: cylinder `halfHeight 0.4, radius 1.5, offset (0, 0.1, 0)`.
+  `radius` is the knob that matters for prompt range. Sensors are mass-0 —
+  they never shift the chassis center of mass.
+- **Long-chassis gotcha (measured in the testbed):** the sensor is centered
+  on the body, so if the chassis half-length exceeds the sensor radius
+  (testbed car: half-length 2.4 vs radius 2.2), walking up from dead astern
+  touches the bumper before the capsule enters the sensor — the prompt only
+  appears after sliding along the side, while a side approach prompts
+  immediately. Fix: sensor radius ≥ chassis half-length, or an offset
+  sensor per end.
+- `exitLength` (default 1.5) is how far along `exitAxis` the character
+  reappears. Raise it if the character spawns inside a wide chassis. The
+  default equals the default sensor radius so immediate re-entry stays
+  possible — intended.
+- Exiting a flipped vehicle whose forward axis is parallel to up produces a
+  degenerate exit basis (faithful upstream non-guard). If vehicles in your
+  game can end up nose-down, right them before allowing exit.
+
+## Seat visuals: Sitting_Enter / Driving_Loop / Sitting_Exit
+
+`park()` hides the character body and visuals — the manager does NOT animate
+a seated pilot; that is game glue on the `onHandoff` seam. The pattern: keep
+a reference to the character's visual model, re-parent it into a seat anchor
+under the vehicle's chassis object, and play the seat clips through a
+dedicated `THREE.AnimationMixer` (the locomotion state machine is idle while
+parked). The clips ship in `animation-library.glb` (installed by
+`npx genex controller character`).
+
+```ts
+const seatMixer = new THREE.AnimationMixer(characterModel);
+const seatAnchor = new THREE.Group();
+
+function enterSeat(host: THREE.Object3D, seatPos: THREE.Vector3) {
+  seatAnchor.position.copy(seatPos);        // e.g. (0, 0.55, -0.6) for a car cabin
+  host.add(seatAnchor);
+  characterModel.position.set(0, 0, 0);     // remember the old pose to restore on exit
+  characterModel.quaternion.identity();
+  seatAnchor.add(characterModel);
+  const enter = seatMixer.clipAction(sittingEnterClip); // "Sitting_Enter"
+  enter.reset();
+  enter.setLoop(THREE.LoopOnce, 1);
+  enter.clampWhenFinished = true;
+  enter.play();
+  // On the mixer's "finished" event, crossFade to the "Driving_Loop" action.
+}
+
+function exitSeat() {
+  // Optionally play "Sitting_Exit" (LoopOnce) before restoring; then:
+  seatMixer.stopAllAction();
+  seatAnchor.removeFromParent();
+  character.root.add(characterModel);       // restore the remembered pose
+}
+
+// onHandoff wiring: enter when control moves TO a vehicle, exit when it
+// returns to the character.
+onHandoff: (fromId, toId) => {
+  if (toId !== CHARACTER_ID) enterSeat(hostFor(toId), seatPosFor(toId));
+  else exitSeat();
+  // Input hygiene: zero the released unit's held inputs, or an exited car
+  // keeps driving on its last merged input state.
+  if (fromId === "car") car.setMovement({ forward: false, backward: false,
+    steerLeft: false, steerRight: false, brake: false });
+}
+```
+
+While parked, tick `seatMixer.update(renderDelta)` in the render loop
+instead of the locomotion `CharacterAnimations.update()`. With a rig-less
+model (no matching clips) skip the mixer and just re-seat the visual — the
+handoff still works.
+
+## Camera handoff via FollowCamera
+
+The manager exposes a camera feed; the bundled `FollowCamera` consumes it.
+Per RENDER frame (render delta — never inside the fixed step):
+
+```ts
+const t = mgr.cameraTarget;              // activeUnit.currPos + bodyYAxis * 0.5
+followCam.moveTo(t.x, t.y, t.z, true);
+followCam.setUp(mgr.cameraUp);           // activeUnit.upAxis
+if (mgr.activeControllerId === CHARACTER_ID) {
+  if (physics.stepsLastFrame > 0 && character.isOnPlatform) {
+    followCam.applyPlatformTurn(character.turnOnYQuat); // per-physics-step delta
+  }
+} else if (mgr.activeVehicle) {
+  followCam.alignHeading(mgr.activeVehicle.bodyZAxis, delta); // ease behind the vehicle
+}
+followCam.update(delta);
+```
+
+`alignHeading` eases the orbit behind the vehicle at `headingAlignGain`
+(default 5; 0 disables) and always yields to an active user drag-orbit.
+`cameraTarget`/`cameraUp` are reused internal vectors — copy, never mutate.
+
+**Follow camera v1 limits (by design):** no pointer-lock look mode, no
+truck/pan (the pivot is always the followed unit), and the orbit space
+assumes up ≈ +Y — `camera.up` lerps toward the fed up-axis, but a
+far-from-Y gravity direction will misbehave. For rigs beyond this, see
+`$genex-threejs-camera-direction`.
+
+## Multiplayer
+
+Occupancy is shared state — remote players must see who is in what. With
+`$genex-threejs-multiplayer` (load it before writing any networking code):
+
+- Put `driving: "car" | "drone" | null` in each player's synced state; on
+  remote change, show/hide that player's on-foot avatar and seat their
+  visual in the vehicle (the seat-visual pattern above, minus the physics).
+- The occupant simulates the vehicle and publishes its pose; everyone else
+  interpolates a plain mesh. Never run the vehicle controllers for a remote
+  player's vehicle.
+- Gate entry on a shared occupancy key so two players can't board the same
+  seat: claim it (e.g. `room.shared.set("occupant:car", room.id)`) and treat
+  a losing race as "prompt stays up".