@genex-ai/cli-demo 0.12.1 → 0.14.2

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.

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.