@genex-ai/cli-demo 0.11.0 → 0.14.2

package/templates/skills/genex-threejs-physics-rapier/references/colliders-from-assets.md

@@ -0,0 +1,202 @@
+# Colliders from assets
+
+Everything here documents `src/controllers/shared/colliders.ts` as installed
+by `npx genex controller`. All helpers assume `PhysicsWorld.create()` has
+already resolved — constructing a collider before WASM init throws.
+
+## Contents
+
+- Decision table: which collider for which asset
+- Explicit primitive helpers
+- Auto-colliders from a GLB scene
+- Hull vs trimesh
+- Scale pitfalls
+- Collider options
+- Sensors
+- End-to-end: a genex model prop
+
+## Decision table: which collider for which asset
+
+| Asset | Collider | Why |
+| --- | --- | --- |
+| ground, walls, crates, platforms (box-shaped) | `cuboidCollider` | cheapest, exact for boxes |
+| dynamic prop from `npx genex model` (barrel, rock, chair) | `convexHullColliderFromMesh` (or `collidersFromObject(..., "hull")` for multi-mesh GLBs) | tight fit, still convex/fast/solid |
+| static level GLB (terrain piece, building interior, track) | `trimeshColliderFromMesh` per mesh | exact triangles; safe because it never moves |
+| ball-shaped things | `ballCollider` | exact sphere |
+| tall dynamic props, posts | `capsuleCollider` / `cylinderCollider` | stable standing shapes |
+| pickups, triggers, zones | any shape + `{ sensor: true, mass: 0 }` | overlap events, no contact forces |
+| the player, cars, drones | none of the above — `npx genex controller` | controllers own their collider recipes |
+
+## Explicit primitive helpers
+
+```ts
+import {
+  cuboidCollider,
+  ballCollider,
+  capsuleCollider,
+  cylinderCollider,
+} from "./controllers/shared/colliders.ts";
+
+cuboidCollider(world, body, [1, 0.4, 2.4], { friction: 1 }); // HALF extents: 2 x 0.8 x 4.8 box
+ballCollider(world, body, 0.5);
+capsuleCollider(world, body, 0.3, 0.3);   // (halfHeight, radius)
+cylinderCollider(world, body, 0.15, 3);   // (halfHeight, radius)
+```
+
+Two classic mistakes, called out because they are silent:
+
+- **Cuboid takes HALF extents.** A `[1, 0.4, 2.4]` collider is a 2 × 0.8 × 4.8
+  box. Do not halve twice.
+- **Capsule/cylinder arg order is `(halfHeight, radius)`** — the REVERSE of
+  `THREE.CapsuleGeometry(radius, length)` — and the capsule's `halfHeight`
+  covers the cylindrical section only: total height is
+  `2 * halfHeight + 2 * radius`, so `(0.3, 0.3)` is 1.2 units tall.
+
+All helpers return the created `RAPIER.Collider` and accept a `ColliderOptions`
+last argument (below), including `position`/`rotation` relative to the body.
+
+## Auto-colliders from a GLB scene
+
+`collidersFromObject` walks every visible mesh under an object and creates one
+collider per mesh — the batteries-included path for GLBs:
+
+```ts
+import { collidersFromObject } from "./controllers/shared/colliders.ts";
+
+const gltf = await loader.loadAsync("./assets/models/weathered-wooden-barrel.glb");
+const model = gltf.scene;
+scene.add(model);
+
+const body = physics.createBody({ type: "dynamic", position: [0, 2, 0] }, model);
+collidersFromObject(world, body, model, "hull", { friction: 0.7, density: 400 });
+```
+
+- Shapes: `"cuboid"` (bounding box per mesh — cheapest), `"ball"` (bounding
+  sphere), `"hull"` (convex hull per mesh — the default choice for `genex
+  model` props), `"trimesh"` (exact triangles — static geometry only).
+- `object3d` must be the SAME object registered to the body (their frames must
+  coincide); call it right after `createBody`, before the first step.
+- Hidden meshes are skipped unless you pass `includeInvisible: true` in the
+  options.
+- It returns the array of created colliders, so you can attach events or
+  retune later.
+
+For a single mesh you can target directly, the explicit forms skip the
+traversal:
+
+```ts
+import {
+  convexHullColliderFromMesh,
+  trimeshColliderFromMesh,
+} from "./controllers/shared/colliders.ts";
+
+convexHullColliderFromMesh(world, dynamicBody, propMesh, { density: 400 });
+trimeshColliderFromMesh(world, fixedBody, levelMesh, { friction: 1 });
+```
+
+Both bake the mesh's current world transform relative to the body, so the
+collider lands exactly where the mesh renders.
+
+## Hull vs trimesh
+
+| | Convex hull | Trimesh |
+| --- | --- | --- |
+| fit | shrink-wraps the mesh; concavities filled in (a mug loses its opening) | exact triangles, concavities preserved |
+| solidity | solid volume | **hollow shell** — a body starting inside it is stuck or falls through |
+| cost | cheap contacts | expensive contacts; scales with triangle count |
+| dynamic bodies | yes — the default for props | **never on fast dynamic bodies** — thin hollow triangles are the classic tunneling recipe |
+| static level geometry | fine but approximate | the right tool |
+
+When one hull is too crude for a concave prop, prefer either of these before
+reaching for a dynamic trimesh:
+
+- **Per-mesh hulls:** most multi-part GLBs already split into several meshes,
+  and `collidersFromObject(world, body, model, "hull")` gives one hull per
+  part — a compound of convex pieces approximates concavity well.
+- **A few hand-placed primitives:** two or three `cuboidCollider`s with
+  `position` offsets often beat any auto shape (this is how the bundled
+  vehicle chassis recipes work).
+
+`"hull"` can also fail outright on degenerate/coplanar geometry — the helper
+throws with the mesh name; fall back to `"cuboid"` for such meshes.
+
+## Scale pitfalls
+
+Colliders copy geometry **at creation time**; they do not track later
+transforms.
+
+- **Scale the model BEFORE creating colliders.** Normalize the GLB (e.g.
+  `model.scale.setScalar(targetHeight / bboxHeight)`) first, then create the
+  body and colliders. Changing `scale` afterwards resizes the render mesh
+  only — the collider keeps the old size.
+- **Put scale on the mesh, not on the registered root.** The auto-collider
+  path faithfully replicates an upstream quirk: the registered root's world
+  scale is double-counted in collider sizing, so a root scaled 2× produces
+  colliders 2× larger than the rendered meshes. Scaling child meshes (or the
+  GLB scene before registering a plain unscaled root) avoids the quirk
+  entirely.
+- **`"ball"` uses `scale.x` only** (same upstream quirk, replicated not
+  fixed) — a non-uniformly scaled sphere gets the wrong radius. Use `"hull"`
+  for squashed spheres.
+- **Verify visually.** `physics.enableDebug(scene)` draws every collider as a
+  wireframe — one glance catches every scale/offset mistake in this section.
+
+## Collider options
+
+`ColliderOptions`, accepted by every helper (and applied via
+`applyColliderOptions(collider, options)` if you retune at runtime):
+
+| Option | Notes |
+| --- | --- |
+| `friction` | negative values are legal and load-bearing — the bundled character capsule ships with `-0.5` because its traction is synthetic; do not clamp |
+| `restitution` | bounciness 0–1 |
+| `density` / `mass` | **mutually exclusive — picking both throws.** `density` is kg/m³ (water ≈ 1000, wood ≈ 400–700); `mass` is absolute kg |
+| `sensor` | overlap detection, no contact forces |
+| `position` / `rotation` | collider pose relative to its body (euler XYZ radians) |
+| `collisionGroups` / `solverGroups` | raw Rapier bitmasks |
+| `contactSkin` | extra contact thickness — trades a visual gap for less jitter |
+| `frictionCombineRule` / `restitutionCombineRule`, `activeCollisionTypes` | raw Rapier passthroughs |
+
+Density matters more than it looks: impulse-driven controllers push bodies by
+force, so a crate with the default density reacts very differently from one at
+`density: 100`. Give props deliberate densities.
+
+## Sensors
+
+```ts
+const zone = cuboidCollider(world, zoneBody, [2, 1, 2], { sensor: true, mass: 0 });
+physics.setColliderEvents(zone, {
+  onIntersectionEnter: ({ other }) => { if (other.object3d === playerRoot) enterZone(); },
+  onIntersectionExit:  ({ other }) => { if (other.object3d === playerRoot) leaveZone(); },
+});
+```
+
+Always give sensors `mass: 0` when they hang off a dynamic body (e.g. a
+vehicle's boarding sensor) so they add no mass. Remember exit events fire both
+handler families — keep exit logic idempotent (see the physics-setup
+reference).
+
+## End-to-end: a genex model prop
+
+```ts
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { collidersFromObject } from "./controllers/shared/colliders.ts";
+
+const loader = new GLTFLoader();
+const gltf = await loader.loadAsync("./assets/models/weathered-wooden-barrel.glb");
+const barrel = gltf.scene;
+
+// 1. Normalize scale FIRST (target: 1.1 units tall).
+const bbox = new THREE.Box3().setFromObject(barrel);
+barrel.scale.setScalar(1.1 / (bbox.max.y - bbox.min.y));
+
+// 2. Wrap in an unscaled root, add to the scene, register, then colliders.
+const root = new THREE.Object3D();
+root.add(barrel);
+scene.add(root);
+const body = physics.createBody({ type: "dynamic", position: [3, 2, 0] }, root);
+collidersFromObject(world, body, root, "hull", { friction: 0.7, density: 500 });
+```
+
+Generating the GLB itself (`npx genex model "..."`) is covered by
+`$genex-ai-model`.

package/templates/skills/genex-threejs-physics-rapier/references/physics-setup.md

@@ -0,0 +1,207 @@
+# Physics world setup
+
+Everything here documents `src/controllers/shared/physics-world.ts` as
+installed by `npx genex controller`. The class names, methods, and defaults
+below are the real exports — use them as written.
+
+## Contents
+
+- Creating the world
+- Rigid bodies and the mesh registry
+- Kinematic platforms
+- Collision and sensor events
+- Sleeping bodies
+- Tunneling and CCD
+- Pause, slow motion, and per-step gating
+- Debug rendering and teardown
+- Ground-query userData flags
+- The benign boot warning
+
+## Creating the world
+
+```ts
+import { PhysicsWorld } from "./controllers/shared/physics-world.ts";
+
+const physics = await PhysicsWorld.create();                    // Earth defaults
+const moon = await PhysicsWorld.create({ gravity: [0, -1.62, 0] });
+```
+
+`PhysicsWorld.create()` awaits `RAPIER.init()` — the WASM is embedded in
+`@dimforge/rapier3d-compat`, so no bundler configuration is needed, and
+multiple `create()` calls share a single init. **Nothing may construct any
+`RAPIER.*` object before this promise resolves**; collider helpers assume it
+already has.
+
+Options you actually touch (`PhysicsWorldOptions`, defaults in parentheses):
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `gravity` | `[0, -9.81, 0]` | world gravity, m/s² |
+| `timeStep` | `1/60` | fixed simulation step in seconds; exposed as `physics.timeStep` and mirrored into `world.timestep` — the ONLY dt physics code may use |
+| `maxDelta` | `1/30` | per-frame wall-clock clamp (spiral-of-death guard: at most 2 substeps per frame at the default step); raise it to let physics catch up after long hitches |
+| `interpolate` | `true` | lerp rendered poses between fixed steps — leave on |
+
+The remaining options (`numSolverIterations` 4, `numInternalPgsIterations` 1,
+`allowedLinearError` 0.001, `predictionDistance` 0.002, `minIslandSize` 128,
+`maxCcdSubsteps` 1, `contactNaturalFrequency` 30, `lengthUnit` 1) mirror the
+solver defaults the controllers were tuned against — change them only with a
+measured reason.
+
+## Rigid bodies and the mesh registry
+
+```ts
+const body = physics.createBody(
+  {
+    type: "dynamic",            // "dynamic" | "fixed" | "kinematicPosition" | "kinematicVelocity"
+    position: [0, 3, 0],
+    rotation: [0, Math.PI / 2, 0], // euler XYZ radians, or a THREE.Quaternion
+    linearDamping: 0.1,
+    ccd: true,                  // fast small bodies only
+    userData: { controller: { excludeVehicleRay: true } },
+  },
+  mesh                          // optional: registers mesh to follow the body
+);
+```
+
+Passing an `Object3D` as the second argument calls
+`physics.registerBody(body, object3d)` for you: every `physics.step`, the
+object's position/quaternion are driven from the body pose, interpolated
+between fixed steps. Registry rules:
+
+- **Register scene-root-level groups and add them to the scene FIRST.** The
+  parent's inverse world matrix and the object's world scale are captured at
+  registration time and never refreshed — if the registered object's parent
+  later moves or scales, the sync silently desyncs.
+- `physics.unregisterBody(body)` stops the sync; `physics.removeBody(body)`
+  also drops collider event handlers and removes the body (and its colliders)
+  from the world. `physics.getObject3d(body)` returns the registered object.
+- The registered object's transform is OWNED by physics. To teleport, move the
+  body (`body.setTranslation({ x, y, z }, true)` — the `true` wakes it), never
+  the mesh.
+
+Colliders are attached separately — see
+`references/colliders-from-assets.md` in this skill.
+
+## Kinematic platforms
+
+Moving/rotating platforms are `kinematicPosition` bodies whose next pose is set
+inside `onBeforeStep`, so Rapier derives their velocities and carries riders:
+
+```ts
+const platBody = physics.createBody(
+  { type: "kinematicPosition", position: [-2, 0.6, 8] },
+  platformMesh
+);
+cuboidCollider(world, platBody, [1.5, 0.15, 1.5], { friction: 1 });
+
+let simTime = 0;
+physics.onBeforeStep(() => {
+  simTime += physics.timeStep;
+  platBody.setNextKinematicTranslation({ x: -2 + 3 * Math.sin(simTime * 0.5), y: 0.6, z: 8 });
+  // rotating: rotBody.setNextKinematicRotation(quaternion)
+});
+```
+
+Advance your own `simTime` by `physics.timeStep` (as above), never by the
+render delta. Set platform poses **before** controller `update()` calls in the
+same callback so characters standing on them read fresh platform velocity.
+
+## Collision and sensor events
+
+Per-collider handlers — `setColliderEvents` also enables
+`ActiveEvents.COLLISION_EVENTS` on the collider (without that flag Rapier never
+reports the pair):
+
+```ts
+physics.setColliderEvents(pickupCollider, {
+  onIntersectionEnter: ({ other }) => {
+    // other: { collider, rigidBody, object3d } — object3d is the registered
+    // mesh of the other body, or null
+    if (other.object3d === playerRoot) collect();
+  },
+});
+```
+
+- Solid contacts fire `onCollisionEnter`; sensor overlaps fire
+  `onIntersectionEnter`. **Exit events fire BOTH** `onCollisionExit` and
+  `onIntersectionExit` — intentional, do not "fix" it; make exit handlers
+  idempotent.
+- `physics.clearColliderEvents(collider)` removes handlers
+  (`removeBody` does it automatically).
+- `physics.onCollisionEvent((h1, h2, started) => ...)` is a raw tap over every
+  drained event; its one intended consumer is the enter/exit system:
+  `physics.onCollisionEvent((h1, h2, s) => mgr.handleIntersectionEvent(h1, h2, s))`
+  (see `$genex-threejs-vehicle-controllers`). Both hooks return an unsubscribe
+  function.
+
+## Sleeping bodies
+
+Dynamic bodies sleep when at rest (`canSleep` default `true`) — good: sleeping
+islands cost nothing, and the mesh sync skips sleeping bodies so their meshes
+simply hold still. What to know:
+
+- Waking is automatic on contact and impulse. When you move a body directly,
+  pass the wake flag: `body.setTranslation(pos, true)`, `body.setLinvel(v, true)`.
+- A body you nudge by writing tiny velocities every few frames may keep
+  falling asleep between nudges — create it with `canSleep: false` instead of
+  fighting the sleep threshold.
+- If a stack "freezes" mid-air after you deleted its support, you removed the
+  body without waking neighbors — `physics.removeBody` handles the common case;
+  exotic cases can call `body.wakeUp()` on neighbors.
+
+## Tunneling and CCD
+
+A fast small body can pass through a thin collider entirely between two fixed
+steps. In order of preference:
+
+1. Make static geometry **thick** (the ground in the setup snippet is a 0.5
+   thick box, not a plane).
+2. Enable CCD on the fast body: `ccd: true` in `createBody` (projectiles,
+   thrown props). `maxCcdSubsteps` stays at 1 unless you measure misses.
+3. Never fix tunneling with a trimesh on the moving body — trimeshes are
+   hollow and make it worse (see the colliders reference).
+4. Shrinking `timeStep` is a last resort: it changes tuning for every
+   controller in the scene.
+
+## Pause, slow motion, and per-step gating
+
+- `physics.paused = true` freezes simulation without banking time — unpausing
+  never replays the gap.
+- `physics.timeScale = 0.5` is half-speed slow-mo (1 = realtime).
+- `physics.stepsLastFrame` is the number of fixed substeps the latest `step()`
+  ran (can be 0 on a fast frame). Use it to gate once-per-physics-step work
+  done outside the physics loop, e.g. applying a platform's turn to the camera
+  only on frames where a substep actually ran.
+
+## Debug rendering and teardown
+
+```ts
+physics.enableDebug(scene);   // wireframe of every collider — tuning only
+physics.disableDebug();       // remove + dispose the lines
+physics.dispose();            // free the Rapier world, event queue, registries
+```
+
+Debug lines cost CPU/GPU every frame — never leave them on in a published
+game. `physics.debugEnabled` reports the current state.
+
+## Ground-query userData flags
+
+Controllers probe the world for "ground" (character ray, wheel shapecasts).
+Bodies opt out via `userData` at creation (`ControllerUserData` shape):
+
+```ts
+{ controller: { excludeRay: true } }           // ignored by ALL ground queries
+{ controller: { excludeCharacterRay: true } }  // ignored by the character's ground ray only
+{ controller: { excludeVehicleRay: true } }    // ignored by wheel shapecasts only
+```
+
+The character body itself should carry `excludeVehicleRay: true` so car wheels
+never treat the on-foot player as drivable ground — the character skill's
+wiring does this.
+
+## The benign boot warning
+
+`@dimforge/rapier3d-compat` 0.19.3 prints one console warning at init —
+`using deprecated parameters for the initialization function; pass a single object instead` —
+from its own embedded WASM loader. It is not caused by game code, cannot be
+silenced from game code, and affects nothing. Leave it alone.

package/templates/skills/genex-threejs-skill-router/SKILL.md

@@ -16,6 +16,9 @@ map, execution order, and acceptance gate.
 | Work needed | Load |
 | --- | --- |
 | shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, floating origins | `$genex-threejs-camera-direction` |
+| on-foot player movement: walk/run/jump, third-person character, slopes, stairs, moving platforms, animation binding | `$genex-threejs-character-controller` |
+| the player drives or flies something: cars, drones, vehicle physics, gearbox, enter/exit between character and vehicle | `$genex-threejs-vehicle-controllers` |
+| anything falls, collides, gets pushed, or needs physics: Rapier world setup, colliders for meshes and GLBs, collision events | `$genex-threejs-physics-rapier` |
 | launch and docking timelines, procedural transform phases, springs, staging, rotating-frame alignment, debris motion | `$genex-threejs-procedural-animation` |
 | reusable scalar/vector fields, domain warping, causal masks, procedural normals | `$genex-threejs-procedural-fields` |
 | atlas-filtered blocks, planetary surfaces, terrain wetness, lava/emissive procedural surfaces, authored frame PBR, specular AA | `$genex-threejs-procedural-materials` |

package/templates/skills/genex-threejs-skill-router/references/routing-map.md

@@ -17,16 +17,21 @@ Three.js release or branch, and do not blindly copy demo architecture.
 
 1. Define the game contract: player verb, win/interaction loop, target device,
    camera distance, scene scale, motion, and frame budget.
-2. Select the minimum scene-generation skills: geometry, materials, vegetation,
+2. Wire the gameplay layer for the player verb: the physics world via
+   `$genex-threejs-physics-rapier` when anything falls, collides, or gets
+   pushed; on-foot movement via `$genex-threejs-character-controller`;
+   driving/flying and character↔vehicle enter/exit via
+   `$genex-threejs-vehicle-controllers`.
+3. Select the minimum scene-generation skills: geometry, materials, vegetation,
    architecture, planets, water, precipitation, clouds, or VFX.
-3. Add camera direction when framing, controls, transitions, or scale perception
+4. Add camera direction when framing, controls, transitions, or scale perception
    affect play.
-4. Add procedural animation when object motion needs authored phases,
+5. Add procedural animation when object motion needs authored phases,
    convergence, looping, or deterministic timelines.
-5. Add shared fields before writing multiple independent noise layers.
-6. Add lighting, atmosphere, and shadows only after the no-post baseline reads.
-7. Add image-pipeline, bloom, exposure, grading, or AO last.
-8. Validate in a real browser with fixed seeds, captures, interaction checks,
+6. Add shared fields before writing multiple independent noise layers.
+7. Add lighting, atmosphere, and shadows only after the no-post baseline reads.
+8. Add image-pipeline, bloom, exposure, grading, or AO last.
+9. Validate in a real browser with fixed seeds, captures, interaction checks,
    and performance evidence.
 
 ## Acceptance gate
@@ -39,6 +44,9 @@ A routed Genex scene is incomplete until it exposes:
 - debug views for generated fields, masks, or passes;
 - a no-post baseline that still communicates the subject;
 - a clear quality tier or render-budget knob when the effect is expensive;
+- when physics or controllers are in play, a fixed-timestep loop: per-frame
+  work (platforms, enter/exit, controller updates) runs inside the physics
+  world's before-step hook, then the world steps — never in the render loop;
 - browser evidence showing the canvas renders, moves, and responds to input.
 
 ## Publish and multiplayer awareness

package/templates/skills/genex-threejs-vehicle-controllers/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: genex-threejs-vehicle-controllers
+description: Add a drivable car or a flyable drone to a Genex Three.js game with `npx genex controller car` / `npx genex controller drone` — shapecast-wheel vehicle physics with a gearbox, PD quadcopter flight, tuned presets, character enter/exit with animation and camera handoff, all over Rapier physics. Use whenever the player drives or flies something.
+---
+
+# Genex Three.js Vehicle Controllers
+
+Real vehicle physics for plain Three.js games: a car built from a dynamic
+chassis body plus one shapecast wheel per corner (suspension spring/damper,
+slip-curve tire model, speed-sensitive steering, engine torque curve with an
+RPM-threshold automatic gearbox), and a quadcopter drone flown by a PD
+attitude controller mixing four thrust propellers. Both are vendored
+TypeScript classes copied INTO the game — not an npm dependency — so the code
+is yours to read and tune.
+
+## Install
+
+Run inside the game project (where `genex init` ran):
+
+```bash
+npx genex controller car      # VehicleController + ShapeCastWheel + presets
+npx genex controller drone    # DroneController + presets
+npm i @dimforge/rapier3d-compat
+```
+
+Files land in `src/controllers/` (shared physics glue, the vehicle or drone
+module, `interact/enter-exit.ts`, and the input + follow-camera modules).
+Existing files are never overwritten (use `--force` to refresh). For the
+on-foot character that enters these vehicles, also run
+`npx genex controller character` and load `$genex-threejs-character-controller`.
+
+## The loop contract (get this right first)
+
+Every controller exposes `update(dt?)` that must run once per **fixed physics
+substep, BEFORE `world.step()`**. The `dt` argument is ignored — all internal
+math uses `world.timestep`. Wire it through `PhysicsWorld` (installed with
+every controller kind):
+
+```ts
+const physics = await PhysicsWorld.create();
+
+physics.onBeforeStep(() => {
+  const dt = physics.timeStep;
+  // 1. kinematic platforms (setNextKinematicTranslation/Rotation)
+  mgr.update(dt);                                // 2. enter/exit manager
+  if (!character.isParked) character.update(dt); // 3. controller brains
+  car.update(dt);
+  drone.update(dt);
+});                                              // 4. world.step() runs after
+
+renderer.setAnimationLoop(() => {
+  physics.step(clock.getDelta()); // fixed substeps + interpolated mesh sync
+  // camera + render here — render-delta code never goes inside onBeforeStep
+});
+```
+
+Never call a controller's `update()` from the render loop, never step the
+world yourself, and never feed the render delta into physics code.
+
+## Wiring references
+
+- [references/car.md](references/car.md) — chassis body + colliders, wheels,
+  presets with provenance, gearbox and RPM, drift vs rollover tuning.
+- [references/drone.md](references/drone.md) — body + propeller mounts,
+  VELOCITY vs POSITION control modes, the PD gain mass-scaling rule, presets.
+- [references/enter-exit.md](references/enter-exit.md) — `EnterExitManager`,
+  park/unpark, sensor tuning, seat animations (`Sitting_Enter` /
+  `Driving_Loop` / `Sitting_Exit`), follow-camera handoff.
+
+## Presets at a glance
+
+Spread a preset into the controller and build colliders/wheels/propellers
+from its recipe (exact code in the references).
+
+| Preset | Kind | Feel | Provenance |
+| --- | --- | --- | --- |
+| `arcade-kart` | car | AWD, stiff, forgiving — the safe default | upstream demo, verbatim |
+| `muscle-drift` | car | soft, rear-biased torque, power-oversteers | upstream demo, verbatim |
+| `offroad-bouncy` | car | long-travel springs, big wheels, low grip | Genex-authored |
+| `race-grip` | car | stiff RWD, 4-speed auto gearbox, flat controllable drift | Genex-authored, testbed-tuned |
+| `camera-drone` | drone | slow, heavily damped filming platform (~2 kg) | Genex-authored |
+| `racing-drone` | drone | agile FPV-style racer (~5 kg) | Genex-authored |
+| `heavy-lifter` | drone | ~298 kg cargo platform, POSITION gains pre-scaled | upstream demo, verbatim |
+
+## Multiplayer: vehicle occupancy is shared state
+
+If the game is multiplayer, **who is in what vehicle must be synced** — a
+remote player vanishing into an apparently empty car reads as a bug. Load
+`$genex-threejs-multiplayer` before writing any networking code, then:
+
+- Publish occupancy with the player's state (e.g. `driving: "car" | null`)
+  or as a shared key — and the occupied vehicle's pose with it.
+- Same authority rule as the character: the **local player simulates the
+  physics of whatever they occupy**; remote vehicles are interpolated
+  visuals only. Never run `VehicleController`/`DroneController` for a
+  remote player — drive a plain mesh from their synced pose.
+- An unoccupied vehicle needs one owner too: elect one client (e.g. the
+  first in the room) to simulate it and publish its pose as shared state.
+
+## Boundaries and troubleshooting
+
+- Physics world setup, collider strategy for `genex model` GLBs, and general
+  Rapier pitfalls live in `$genex-threejs-physics-rapier`.
+- Camera systems beyond the bundled follow camera: `$genex-threejs-camera-direction`.
+- Skid smoke, dust, rotor wash: `$genex-threejs-procedural-vfx`, driven by
+  the telemetry getters listed in the references (`wheel.slipStrength`,
+  `drone.propellersInfo`).
+- **One-time console warning at boot** ("using deprecated parameters for the
+  initialization function...") comes from the Rapier WASM loader itself —
+  harmless, not fixable from game code. Do not chase it.