evomeme 0.1.9 → 0.1.10

package/dist/skills/en-US/threejs-3d-game/references/engine-asset-pipeline.md

@@ -0,0 +1,153 @@
+# Engine: Asset Loading and Animation Pipeline
+
+Focuses on **how to safely connect GLB at runtime**, and how to consume **canonical asset packages** (`model.glb` + `asset.json`).
+
+Load this file when loading/binding meshes, `AnimationMixer`, root motion, collision proxies, or post-import performance. Paths and config contracts are still governed by `file-structure.md`. For the alignment process, see skill `game-asset-align`.
+
+## Canonical Package (Mandatory)
+
+**After Blender modeling/modification, the Stage board MUST be opened first. Only after the user views it and clicks "confirm current version, allow import" may the next import step proceed.** `evomeme_stage_open({workspace_dir,asset_id,target:"three_js"})`; format checks and `alignment.ready` only indicate technical status and cannot skip confirmation. After changing the model, textures, lights, or display configuration, the old confirmation becomes invalid and it MUST be viewed and confirmed again.
+
+Before entering the game, Tripo / code-modeled / Blender / uploaded models MUST be:
+
+```text
+assets/canonical/<asset_id>/model.glb
+assets/canonical/<asset_id>/asset.json
+```
+
+Sync into the Vite project:
+
+```text
+evomeme_asset_sync_to_three
+-> public/assets/canonical/<asset_id>/
+```
+
+Key fields in `asset.json`: `forward_axis`, `scale_hint_metres`, `yaw/pitch/roll_offset_degrees`, `verified_by`.
+For directional assets (characters/firearms/vehicles), `verified_by` MUST NOT be `unverified`.
+
+Runtime convention: **-Z forward, +Y up** (same as Godot). For full scenes, use the synced `src/evomeme-stage/<id>/canonical_loader.js` and call `loadReviewedScene`. It shares scene-runtime.js and three-appearance.js with Stage, reproducing the confirmed PBR, lights, environment, camera, and existing baked display path. The project must use Three.js **0.170.0**; mismatched versions will error and require dependencies to be unified before viewing again.
+
+The package includes three.appearance.json (confirmed profile, diagnostics, and file fingerprints), THREE_IMPORT.md, the pinned runtime, and independently viewable three-preview.html. The old applyCanonicalOrientation.ts is only for compatibility with old model code; it is not responsible for full-scene display.
+
+## Output and Loading Preferences
+
+| Purpose | Format |
+| --- | --- |
+| Three runtime | Prefer GLB (PBR) + same-directory `asset.json` |
+| Animation exchange | FBX as needed, then import carefully or convert offline to GLB |
+| Printing / AR | STL/3MF, USDZ - not the default for this game runtime |
+
+- Use `GLTFLoader` (`three/addons/loaders/GLTFLoader.js`).
+- Runtime URL: `./` relative paths, `/assets/canonical/<id>/model.glb`, or external `http(s)`; arbitrary site-root absolute paths are prohibited (see deployment rules).
+- Put loading in the asset layer / `game/three` helpers; **do not** `load` inside entity per-frame update.
+- Business code references assets through `manifest` / `config` / canonical `asset_id`, and does not hardcode bare URLs.
+
+```ts
+import * as THREE from 'three';
+import { loadReviewedScene } from '../../evomeme-stage/courtyard/canonical_loader.js';
+
+// assetBase comes from deployment resource config, points to this scene directory, and ends with /.
+const runtime = await loadReviewedScene({
+  renderer, world: scene, camera, assetBase: config.assets.courtyard,
+});
+// Game main loop; the game is responsible for updating camera aspect and renderer size.
+runtime.render(camera, deltaSeconds);
+// When leaving the scene
+runtime.dispose();
+```
+
+A full environment is loaded only once inside one Scene. Props use appearanceEnabled:false to attach to an existing environment. The returned root node already has canonical TRS applied; do not wrap it in compensating rotation or scale again. The return value also includes animations and stats; gameplay, physics, and animation playback are taken over by the game's asset layer. R3F or custom postprocessing must take over the render loop and call runtime.render; merely letting the framework call renderer.render will skip the full scene bake/postprocessing path.
+
+## Wrapping Entities
+
+When importing a scene package into game entities, explicitly handle:
+
+- **MUST** use `asset.json` to unify scale, pivot, and orientation (outer `Group`)
+- Bounding boxes / logical bounds
+- **Collision proxy separated from visuals**
+- Loading failure placeholder or error state
+- Records: file size, triangle count, material count, texture dimensions, clip names, `verified_by`
+
+## AnimationMixer
+
+```ts
+const mixer = new THREE.AnimationMixer(gltf.scene);
+const action = mixer.clipAction(gltf.animations[0]);
+action.play();
+
+// After useFrame / simulation: seconds
+mixer.update(deltaSeconds);
+```
+
+- Map gameplay states to clips: idle / walk-run / jump / attack / hurt / fall / turn, etc.
+- Arcade default: **in-place animation + code-driven displacement**; if root motion is retained, it MUST be intentional.
+- On restart, stop actions and dispose the mixer to avoid stacked playback.
+
+## Root Motion and Imported Animation Notes (Engine Side)
+
+If upstream rigging/retargeting pitfalls exist, fix them on the engine side this way:
+
+1. When in-place animation is needed, handle it preferentially **after import**; do not depend on uncontrolled upstream `animate_in_place` behavior.
+2. When making an animation in-place, change only the top-level root bone position track (common name `Root.position`), and pin only horizontal XZ; **preserve Y** (jumping rise/fall).
+3. Do not broadly delete Hip/Pelvis or twist tracks: some rigs skin limbs to twist bones, and deleting tracks will collapse limbs.
+
+```ts
+for (const clip of clips) {
+  for (const tr of clip.tracks) {
+    if (tr.name !== 'Root.position') continue;
+    const v = tr.values;
+    const x0 = v[0];
+    const z0 = v[2];
+    for (let i = 0; i < v.length; i += 3) {
+      v[i] = x0;
+      v[i + 2] = z0;
+    }
+  }
+}
+```
+
+If batch retargeting produces `NlaTrack` / `NlaTrack.001`: map to preset names by index according to the **request order**, then after loading set `clip.name = 'walk'` and select by name.
+
+Log after loading: `gltf.animations.map(c => \`${c.name} ${c.tracks.length} tracks\`)`. Healthy humanoid clips should drive many bones; very few tracks usually mean upstream rigging is broken, so fix rigging first.
+
+### FBX Intake (Common for Humanoid Retargeting)
+
+- `FBXLoader` depends on `fflate`; bundlers generally include it automatically.
+- The same take may produce two clips with different `|` path depths: **keep the shallower** one.
+- Select clips with keywords (walk / idle / attack); do not blindly use `animations[0]` unless the pipeline guarantees a single take.
+- FBX is often Phong and darker than GLB PBR; final art alignment can convert offline to GLB.
+- Apart from "pinning horizontal motion on a single root bone", avoid further loader-side animation "fixes" (they easily make things worse).
+
+## Performance Discipline
+
+- Browser/mobile: control polygon count and texture dimensions; hero pieces high quality + instanced/procedural supporting elements.
+- Share geometry/material as much as possible when cloning.
+- Dispose loaded resources on scene exit / level change.
+- Record renderer diagnostics before and after import: calls, triangles, geometries, textures, materials, file size.
+- Runtime stutter, pooling, DPR, and LOD are covered in `engine-performance.md`.
+
+## Import Checkup Checklist
+
+- [ ] File size and triangle count are acceptable
+- [ ] Mesh / material / texture counts and dimensions
+- [ ] PBR appearance under current lighting
+- [ ] Metric scale and pivot / bounds come from `asset.json`, not guesses
+- [ ] `verified_by` is recorded (directional assets are not unverified)
+- [ ] Collision proxy is separate and visible in debug
+- [ ] Clip names, durations, and root-motion strategy are clear
+- [ ] Failure has a placeholder; success path enters manifest/config/canonical
+- [ ] No leaks on unload and restart
+- [ ] No hardcoded compensating rotation in gameplay code
+
+## Common Fixes
+
+| Problem | Handling |
+| --- | --- |
+| Too large/small | Normalize bounds on the outer Group |
+| Wrong orientation | **Change asset.json / return to the board**, do not permanently hard-rotate inside gameplay wrappers |
+| Wrong scale | Write `scale_hint_metres`, then reload |
+| Broken geometry | `evomeme_asset_repair_blender` -> board alignment again -> sync again |
+| Animation foot sliding/drifting away | Keep exported root motion, then pin only XZ as above |
+| Too expensive | Reduce geometry, shrink textures, reduce unique retopology |
+| Material too dark/bright | Color space, tone mapping, ambient light, exposure |
+| Strange collision | Visual mesh does not participate in physics; create a separate proxy |

package/dist/skills/en-US/threejs-3d-game/references/engine-audio.md

@@ -0,0 +1,70 @@
+# Engine: Audio Runtime
+
+The audio runtime lives in `game/audio` + `gameBus`. Asset generation and music selection go through `../game-audio`; this file only governs **runtime wiring and lifecycle**.
+
+Load this file when changing in-game BGM/SFX playback, unlock, mute, or restart cleanup.
+
+## Ownership
+
+| Item | Location |
+| --- | --- |
+| Playback / decode / dispose | `game/audio` (`audioManager`, etc.) |
+| Gameplay facts -> sound | `audioHooks` subscribes to `gameBus` (`game:*` / `player:*` / `game:feedback`) |
+| Mute / volume preferences | HUD emits `command:audio-prefs` -> `audioPrefs` applies |
+| URL / toggles | `public/config.json` or `game/assets` manifest |
+
+Prohibited:
+
+- Playing in-game SFX with `new Audio()` inside HUD / `useFrame`
+- Creating new audio sources or footstep loops every frame
+- Duplicating playback logic across multiple components
+
+## User-Gesture Unlock
+
+Browsers require resuming `AudioContext` (or equivalent unlock) after a **user gesture**:
+
+- The first "start / continue / tap Canvas" path calls `audioManager.unlock()` (or `context.resume()`)
+- Unlock failure must be visible (logs / diagnostics); do not fail silently
+- Mobile MUST be verified once on a real device or with a simulated gesture
+
+## Event-Driven Hooks (Minimum Set)
+
+Play sounds by state, not as random decoration:
+
+| Event Class | Examples |
+| --- | --- |
+| UI | Click, pause, retry |
+| Progress | Pickup, score, milestone / combo |
+| Pressure | Hurt, failure, danger approaching |
+| Ability | Dash / accelerate / fire |
+| Ambience | BGM or environment loop (toggleable) |
+
+Payloads such as `game:feedback` / `player:movement` use plain data; `game/audio` maps them to concrete clips, and does not write URLs into UI.
+
+## Lifecycle
+
+- **Pause / hidden page**: stop or lower in-game BGM; `visibilitychange` MUST NOT stack a second loop
+- **Failure / results / restart**: stop in-game loops and short SFX; remove subscriptions for this run only; return pooled audio sources (if any)
+- **Level change**: unload buffers unique to this level; common UI sounds may remain
+- **Mute / volume**: preferences MUST apply to all groups (BGM / SFX / UI)
+
+## With config
+
+`http(s)` URLs for BGM/SFX, default volume, and whether music is enabled go into flat `config.json`; code reads through `getSetting` / manifest keys, and scattered hardcoded paths are prohibited.
+
+## Troubleshooting
+
+- File URL, MIME, CORS
+- Whether decode/load rejects are visible
+- Whether `play` is called without ever unlocking
+- Whether SFX is triggered every frame
+- Whether pause/restart causes double BGM
+- Whether mute misses any group
+
+## Engine Anti-Patterns
+
+- UI buttons directly call `new Audio(url).play()`
+- Depending on autoplay without unlocking
+- BGM residue / stacked listeners after restart
+- Business code hardcodes audio URLs
+- Writing generation-pipeline details into `game/audio` (generation belongs to the `game-audio` skill)

package/dist/skills/en-US/threejs-3d-game/references/engine-input-camera.md

@@ -0,0 +1,84 @@
+# Engine: Input and Camera
+
+Input and camera live in `game/input` + `game/three`. This does not include UI visual design or numerical juice recipes (for game feel, see `game-designer/references/game-feel.md`).
+
+Load this file when changing controls, touch stickiness, camera follow, FOV, or pointer lock.
+
+## Input: Intent and Ownership
+
+1. **Collection** (keyboard/mouse / pointer / touch / gamepad) is separated from **simulation**.
+2. Physical device -> semantic action (such as `move`, `dash`, `confirm`) is centralized in `game/input`.
+3. `GameCanvas` / DOM HUD only reads the unified input surface; hardcoded keybindings MUST NOT be scattered inside `useFrame`.
+4. UI buttons enter the runtime through the same action set or `command:*`, and do not duplicate a separate rule set inside buttons.
+
+### Stickiness and Cancellation
+
+- MUST handle `pointerup` / `pointercancel` / `blur` / `visibilitychange` to avoid stuck joysticks or dash buttons.
+- Pointer controls use `setPointerCapture`; test environments may not have a real pointerId, so tolerate that.
+- Use `event.code` for keys (layout-independent); do not rely only on `key`.
+- CSS `touch-action` is set intentionally and with controlled scope; avoid full-page scrolling stealing gestures.
+- After failure / pause / restart, restore focus and make restarted controls usable.
+
+### Movement Composition (Desktop + Joystick)
+
+Normalize if the sum of the key vector and joystick vector has length > 1 (scaffold pattern):
+
+```ts
+target.copy(keyVector).add(pointerVector);
+if (target.lengthSq() > 1) target.normalize();
+```
+
+When mobile is in scope: the virtual joystick is in DOM (`src/ui`) and writes to the same `move` intent through `game/input`; do not bind another conflicting listener set inside Canvas.
+
+### Input Troubleshooting
+
+- Whether focus is on a page that can receive keyboard input
+- Whether listeners are attached to the correct element
+- `touch-action` / viewport meta / safe area
+- Whether DPR makes touch hit areas too small
+- Whether resize updates after rotation
+- Whether desktop keyboard/mouse still works after adding mobile controls
+- Whether UI emits intent instead of directly changing simulation root state
+
+## Camera: Model and Responsibilities
+
+Choose one primary model early and write it into the implementation (logic in `game/three`; rules still in simulation):
+
+| Model | Applies To |
+| --- | --- |
+| Follow + fixed offset | Runners, top-down action, arcade |
+| Orbit / inspect | Showcases, slower exploration |
+| Target lock | Tactical, lock-on combat |
+| Over-the-shoulder | Lightweight third-person |
+
+Rules:
+
+- Separate camera from game rules: the camera reads "follow target pose / event pulses" and does not rewrite win/loss state.
+- Shake / FOV kick only serve readability and MUST NOT block the next decision area.
+- Readability: the next decision is visible, the player is sufficiently centered, and threats are not hidden by HUD/camera clipping.
+- Accessibility: avoid excessive shake, flashing, and uncontrollable motion; respect hooks such as `setReducedMotion`.
+
+### Follow Lag (Exponential Smoothing)
+
+Common scaffold form (`lag` is the time constant in seconds; it may come from `camera_follow_lag` in `config.json`):
+
+```ts
+const desired = target.clone().add(offset);
+const factor = 1 - Math.exp(-delta / Math.max(0.001, lag));
+camera.position.lerp(desired, factor);
+camera.lookAt(lookTarget);
+```
+
+Tunable axes (change engine parameters, not rules): follow lag, look-ahead, height, distance, FOV, near/far planes, pull-in strategy for collision/occlusion.
+
+### Verify Camera and Controls Together
+
+After changing speed or acceleration, MUST retest:
+
+- Whether high speed clips through geometry or the camera loses the target
+- Whether turning fights with look-ahead
+- Whether pointer should freeze or unlock when pause/menu opens
+
+## Config Contract
+
+Tunable items such as camera lag, FOV, and whether screen shake is enabled go into flat `public/config.json` (see `file-structure.md`); copying magic numbers across multiple camera files is prohibited.

package/dist/skills/en-US/threejs-3d-game/references/engine-performance.md

@@ -0,0 +1,96 @@
+# Engine: Performance
+
+Load when addressing stutter, frame drops, generation spikes, or low mobile frame rate.
+
+Profiling flow and acceptance evidence are in `../game-test`; AAA rendering budgets / LOD art-side guidance is in `../threejs-aaa-graphics-builder/references/technical-art.md`. This file only governs **implementation-time engine constraints**.
+
+## First Things to Prioritize
+
+1. **Object pools**: bullets, pickups, fragments, short-lived VFX carriers - hot paths MUST NOT aggressively `new` / `dispose` meshes
+2. **Shared resources**: repeated pieces use `InstancedMesh` or shared geometry / material / texture
+3. **DPR cap**: default cap `2` (see `engine-runtime.md` Canvas config); mobile may go lower
+4. **Zero allocation on hot paths**: `useFrame` / simulation does not create `{}` / `new Vector3` every frame; reuse temporary vectors
+5. **Reduce physics cost first**: simple colliders, sleeping, fewer dynamic bodies, narrow sensors; CCD only for bodies that need it (see `engine-physics.md`)
+
+## Rendering Side
+
+| Technique | When |
+| --- | --- |
+| `InstancedMesh` | Lane markers, bolts, windows, grass, debris, repeated props |
+| Shared geometry/material | Do not clone each material chain separately when cloning entities |
+| Frustum / distance culling | Far scenery and offscreen dynamic bodies |
+| `LOD` | Background pieces, dense world kits |
+| Shadow reduction | Fewer casters, smaller shadow maps, contact shadows/blob substitutes |
+| Postprocessing throttling | Keep only passes required for readability |
+| Texture discipline | Controlled size, reuse, mipmap; avoid many unique large textures on screen |
+
+Optimization order: **check DPR / post / shadow / instancing / culling first**, then reduce visual density; do not start by deleting hero-piece readability.
+
+User-facing performance is governed by **production preview** (`pnpm build` + preview); do not use dev server frame rate as evidence.
+
+## Object Pools (3D)
+
+```ts
+// Illustration: the pool holds constructed Object3D + optional physics body handles
+function acquireBullet(): BulletView {
+  const b = pool.pop() ?? createBulletView();
+  b.root.visible = true;
+  // Enable collider / reset transform
+  return b;
+}
+
+function releaseBullet(b: BulletView): void {
+  b.root.visible = false;
+  // Stop mixer, disable body, remove listeners; do not dispose shared geometry
+  pool.push(b);
+}
+```
+
+On level restart: return all active pooled instances, then clean non-pooled level-specific resources.
+
+## CPU and Throttling
+
+- Movement / camera / mixer every frame; AI, pathfinding, and distant cleanup can run at 5-10Hz.
+- Multiple `AnimationMixer` instances update only visible / nearby entities.
+- DOM HUD is pushed by events/store; avoid forcing the whole React tree to rerender every frame.
+
+## Physics Cost (Summary)
+
+- Visual mesh != collider; use primitives / compounds.
+- Offscreen or resting bodies can sleep; narrow sensors.
+- Expose body / collider / CCD / sensor counts in diagnostics (see runtime hooks).
+
+## Memory and Level Changes
+
+- On level change, dispose: level-unique geometry, materials, textures, render targets, mixers, physics bodies.
+- Common material libraries / shared atlases may remain.
+- Audio resource cleanup is covered in `engine-audio.md`.
+
+## Diagnostic Fields (Implementation Side)
+
+Provide as much as possible in `__THREE_GAME_DIAGNOSTICS__`:
+
+- `renderer.info`: `render.calls`, `triangles`, `memory.geometries`, `memory.textures`
+- DPR, shadow/postprocessing toggle summary
+- Entity count, pool size, active mixer count
+- Physics (if any): engine, timestep, bodies, colliders, sensors, ccdBodies
+
+## Quick Check Table
+
+| Symptom | Common Cause | Handling |
+| --- | --- | --- |
+| Slower over time | Missing dispose / stacked subscriptions | Check restart and pool return |
+| Periodic hitch | GC | Pooling, reduce `useFrame` allocation |
+| Always low frame rate | draw call / triangles / DPR | Instancing, LOD, cap DPR, reduce shadow |
+| Generation spike | Creating meshes on the spot | Pre-pool / preload |
+| Physics stutter | Too many bodies/contacts | Simpler colliders, sleeping, fewer dynamic bodies |
+| Sharp drop after import | Retopology / large textures | Reduce geometry, shrink textures (generation side + import checkup) |
+
+## Engine Anti-Patterns
+
+- Cutting art detail before measuring
+- Using dev server FPS as release performance evidence
+- Creating new geometry / material / `Audio` every frame
+- Many unique meshes that could use `InstancedMesh`
+- Detailed imported mesh as collider
+- Not capping DPR on mobile

package/dist/skills/en-US/threejs-3d-game/references/engine-physics.md

@@ -0,0 +1,142 @@
+# Engine: Physics and Collision
+
+Three.js / R3F **is only responsible for rendering**; physics is a parallel world. After advancing with a fixed timestep, synchronize body transforms to `Object3D` in one place.
+
+Load this file when adding/replacing physics, vehicles, pinball, rigid bodies, sensors, or high-speed collisions. Gameplay-facing guidance can be compared with `../game-designer/references/physics-engine-selection.md`; **implementation is governed by this file + the layering in `file-structure.md`**.
+
+## Selection Ladder
+
+1. **Custom collision**: arcade triggers, pickups, lanes, bullets, simple overlaps, deterministic tracks; game feel is authored, not simulated.
+2. **Rapier** (`@dimforge/rapier3d-compat`): the default for serious 3D physics - rigid bodies, sensors, multiple contacts, high speed, balls, slopes, moving platforms, reliable browser/mobile behavior.
+3. **cannon-es**: small-scale rigid bodies, lightweight JS fallback when you want to avoid WASM.
+4. **Jolt**: consider only when its features are explicitly needed and the integration cost is acceptable.
+5. **Ammo.js**: only for existing projects or strong dependencies; do not default to it for new projects.
+6. **Matter.js**: only for 2D gameplay (even if rendered with Three).
+
+Most new 3D projects that need "real physics" choose Rapier.
+
+## Quick Lookup by Type
+
+| Use Custom | Use Rapier |
+| --- | --- |
+| Endless runners, lane dodging, simple shooting, pickup gates | Mini golf, billiards, pinball, pachinko, physics puzzles |
+| Scripted obstacles, simple sphere/box overlap | Platforms, moving platforms, slopes, character controllers |
+| Racing guardrails with authored feel | Debris piles, boxes, high-speed objects that need CCD |
+| | Many sensors / collision events |
+
+Avoid using detailed visual meshes for collision: use primitives, compound shapes, or convex hulls; only simplified triangle meshes should be considered for static level geometry. Generated GLB MUST have a separate **collision proxy**.
+
+## Ownership in This Project
+
+| Item | Location |
+| --- | --- |
+| World / body / collider creation and destruction | Physics module under `game/simulation`, or an explicit `PhysicsWorld` facade |
+| Fixed-timestep `step` | Simulation update (called into simulation by `useFrame`) |
+| Visual sync | The **only** place inside `useFrame`: body -> `Object3D` |
+| Debug collider drawing | `game/three` or diagnostics layer; off in release |
+
+Prohibited: calling `createRigidBody` inside render components; writing `mesh.position` in multiple places and competing with body ownership; leaving body residue after restart.
+
+## Update Order (Including Physics)
+
+```text
+input intents -> fixed physics step -> game state / collision events -> VFX / camera / UI -> render
+```
+
+## Rapier Integration Pattern
+
+Install (this repository's package manager is pnpm):
+
+```bash
+pnpm add @dimforge/rapier3d-compat
+```
+
+Initialize once before starting gameplay:
+
+```ts
+import RAPIER from '@dimforge/rapier3d-compat';
+
+await RAPIER.init();
+const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });
+```
+
+Fixed-timestep accumulator:
+
+```ts
+const fixedDt = 1 / 60;
+let accumulator = 0;
+
+function stepPhysics(deltaSeconds: number) {
+  accumulator += Math.min(deltaSeconds, 0.1);
+  while (accumulator >= fixedDt) {
+    world.timestep = fixedDt;
+    world.step();
+    accumulator -= fixedDt;
+  }
+}
+```
+
+Rigid body + collider + sync:
+
+```ts
+const body = world.createRigidBody(
+  RAPIER.RigidBodyDesc.dynamic()
+    .setTranslation(0, 2, 0)
+    .setLinearDamping(0.25)
+    .setAngularDamping(0.5),
+);
+world.createCollider(
+  RAPIER.ColliderDesc.ball(0.5).setRestitution(0.6).setFriction(0.4),
+  body,
+);
+
+// The only sync point
+const t = body.translation();
+const r = body.rotation();
+mesh.position.set(t.x, t.y, t.z);
+mesh.quaternion.set(r.x, r.y, r.z, r.w);
+```
+
+Enable CCD for high speed (has cost; only for bodies that need it):
+
+```ts
+RAPIER.RigidBodyDesc.dynamic().setCcdEnabled(true);
+```
+
+Sensors / triggers:
+
+```ts
+RAPIER.ColliderDesc.ball(1)
+  .setSensor(true)
+  .setActiveEvents(RAPIER.ActiveEvents.COLLISION_EVENTS);
+```
+
+## Implementation Rules
+
+- Moving platforms / scripted obstacles use **kinematic** bodies, and visual and physics move together.
+- Pickups, finish lines, checkpoints, and damage zones use **sensor**.
+- Character controllers prefer capsules, locked rotation, and kinematic movement (unless ragdoll is required).
+- Arcade vehicles: do not rely only on a bare rigid body; combine control logic + collision response.
+- Use sleeping, and remove/dispose bodies on restart to avoid stale simulation.
+- Tuning units must match scene scale; explicitly set friction, restitution, damping, mass/density, gravity scale, and collision groups.
+- Debug: body/collider counts, contact pairs, velocity; off in release builds.
+
+## Verification (Physics Changes)
+
+- `pnpm build` / type check
+- Real input changes body state
+- Collision / trigger paths work
+- No body residue after restart
+- High speed does not tunnel through geometry
+- Simulation does not collapse under low-frame spikes
+- Diagnostics record: engine, timestep, body/collider count, CCD, sensor, risky collider
+
+## Common Failures
+
+- Variable-timestep physics -> drifting feel
+- Visual and physics sync in multiple places -> drift
+- Body residue after restart
+- Imported mesh used for collision -> slow and wrong
+- High speed without CCD -> penetration
+- Sensor active events not enabled
+- Kinematic platform only moves the mesh and not physics