evomeme 0.1.9 → 0.1.10-beta.13

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

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

@@ -0,0 +1,199 @@
+# Engine Runtime (R3F / Three.js)
+
+This file defines R3F / Three.js **engine-layer** conventions (see `file-structure.md`). It does not include design, levels, or game-feel juice recipes.
+
+Load this file when writing/modifying runtime, Canvas/gl defaults, loops, lifecycle, blank-screen/double-loop issues, dispose, diagnostic hooks, or R3F loading boundaries.
+
+## Directory and Ownership Mapping
+
+| Responsibility | Location in This Project |
+| --- | --- |
+| DOM startup, CSS | `main.tsx` / `App.tsx` / `index.css` |
+| Renderer, Canvas, pixel ratio | `ui/components/GameCanvas.tsx` (R3F `<Canvas>`) |
+| Frame-loop orchestration | `useFrame` in `GameCanvas` (do not start another `requestAnimationFrame`) |
+| Input collection -> semantic actions | `game/input` |
+| Rules / state / fixed-step physics | `game/simulation` (no Three / React) |
+| Camera, world meshes, mixer | `game/three/*` (no React) + `useFrame` sync |
+| UI bridge | `game/bridge` + `src/ui` |
+| Asset keys / loading | `game/assets` + `game/three` loading helpers |
+| Diagnostics / test hooks | Installed when `GameCanvas` mounts, cleaned up on unmount |
+
+## Canvas / Renderer Defaults
+
+**MUST NOT** create another `new THREE.WebGLRenderer` outside `GameCanvas`. The only WebGL entry point is R3F `<Canvas>`.
+
+Recommended defaults (can be tuned per project, but must be set explicitly; do not rely on implicit defaults):
+
+```tsx
+import { Canvas } from '@react-three/fiber';
+import * as THREE from 'three';
+
+<Canvas
+  shadows
+  dpr={[1, 2]} // Pixel ratio cap 2
+  gl={{
+    antialias: true,
+    alpha: false,
+    powerPreference: 'high-performance',
+    outputColorSpace: THREE.SRGBColorSpace,
+    toneMapping: THREE.ACESFilmicToneMapping,
+    toneMappingExposure: 1.05,
+  }}
+  camera={{ fov: 50, near: 0.1, far: 500, position: [0, 5, 10] }}
+>
+  {/* World + useFrame orchestration */}
+</Canvas>
+```
+
+Rules:
+
+- Leave resize / aspect to R3F; do not use CSS `transform: scale` to pretend the canvas was resized.
+- Shadows: `shadows` + light `castShadow`; mobile may turn off or reduce cascades (see `engine-performance.md`).
+- Color space and tone mapping must be consistent with imported PBR; if too dark/bright, check here and ambient light first, then change assets.
+- Deeper lighting/postprocessing recipes belong to `threejs-aaa-graphics-builder`; this file only sets startup defaults.
+
+## Frame Update Order
+
+Keep an explicit order every frame (under R3F, orchestrated by `useFrame`; rendering is left to R3F):
+
+```text
+input intents
+  -> fixed physics (if any, accumulator)
+  -> gameplay / simulation systems
+  -> animation / mixer / VFX sockets
+  -> camera
+  -> UI bridge (emit facts / write store)
+  -> (R3F automatically renders; unless offscreen, do not manually call renderer.render)
+```
+
+Rules:
+
+- `useFrame` only orchestrates; it does not write core win/loss/combat rules.
+- A second active `requestAnimationFrame` game loop MUST NOT compete with R3F rendering.
+- Use frame intervals in seconds; clamp sleep/stutter (common scaffold upper bound around `0.05`-`0.1` seconds).
+
+```ts
+// Inside useFrame: delta is already seconds; clamp is still recommended
+const dt = Math.min(state.clock.getDelta(), 0.05);
+```
+
+### `useFrame` Priority (Recommended)
+
+R3F: in `useFrame(fn, priority)`, **higher priority runs earlier**; default is `0`; **negative numbers run after the default render**.
+
+| priority | Content |
+| --- | --- |
+| `> 0` (such as `1`) | Input sampling -> fixed-step physics -> simulation |
+| `0` (default) | `Object3D` sync, mixer, VFX socket, camera follow |
+| `< 0` | Diagnostic sampling only / hooks that need to read finished frame results (optional) |
+
+Do not register multiple competing `useFrame` writers for the same responsibility. Fixed-step physics details are in `engine-physics.md`.
+
+## R3F Policy
+
+### Loading Boundaries
+
+- **Formal game assets** (GLB/texture keys, failure placeholders, manifest): place in `game/assets` + `game/three` loading helpers; triggered once by `GameCanvas` / world root.
+- `useLoader` / `<Suspense>`: only for explicit mount-boundary prototypes or local helpers; **do not** have every entity component separately `useLoader` the same URL without a unified cache/dispose strategy.
+- Business code does not hardcode glTF URLs; it goes through manifest / `config.json`.
+
+### `@react-three/drei` Allowlist
+
+| Usable (Carefully) | Prohibited as Formal Solution |
+| --- | --- |
+| Development-oriented Helpers, lightweight environment/HDR helpers (toggleable) | Piling formal HUD / menus / settings into `<Html>` |
+| Explicitly needed `OrbitControls` (edit/inspect mode; gameplay mode must be toggleable) | Using drei controls to bypass `game/input` semantic actions |
+| | Replacing `src/ui` with in-Canvas DOM |
+
+Formal HUD, virtual joystick, settings panels -> React DOM (`src/ui`).
+
+### Other
+
+- `game/three/*` **MUST NOT** `import` React / R3F hooks.
+- StrictMode double-mount: subscriptions and WebGL resource creation MUST be idempotent and cleanable.
+
+## First Runnable Slice (Engine Minimum)
+
+Have these engine-side pieces first, then discuss content density:
+
+1. Canvas + scene root + resize / camera aspect (including the gl/dpr defaults above)
+2. Single update path (`useFrame`)
+3. Input -> semantic action -> one simulation step
+4. `Object3D` sync for at least one movable entity
+5. Minimal collision or trigger detection (custom or physics)
+6. Resource and listener cleanup on failure/restart
+7. Diagnostic hooks (see below)
+
+Reject: view-only without control; leftover entities/listeners/physics bodies after restart; competing multiple loops.
+
+## Lifecycle and dispose
+
+StrictMode will double-mount; unmount must be repeatable and idempotent.
+
+MUST clean up:
+
+- Geometry, materials, textures (including maps attached to materials)
+- `AnimationMixer` and clip actions
+- Physics world / body / collider
+- `gameBus` subscriptions, DOM / window listeners
+- Diagnostics and test hooks (`window.__THREE_GAME_*`)
+- In-game audio loops / short SFX (see `engine-audio.md`)
+
+```ts
+import * as THREE from 'three';
+
+export function disposeObject3D(root: THREE.Object3D): void {
+  root.traverse((object) => {
+    const mesh = object as THREE.Mesh;
+    if (mesh.geometry) mesh.geometry.dispose();
+    const materials = Array.isArray(mesh.material)
+      ? mesh.material
+      : mesh.material
+        ? [mesh.material]
+        : [];
+    for (const material of materials) {
+      for (const value of Object.values(material as unknown as Record<string, unknown>)) {
+        if (value && typeof value === 'object' && (value as { isTexture?: boolean }).isTexture) {
+          (value as THREE.Texture).dispose();
+        }
+      }
+      material.dispose();
+    }
+  });
+}
+```
+
+## Diagnostic Hooks
+
+Install when `GameCanvas` mounts and clean up on unmount (types written in `vite-env.d.ts`):
+
+- `window.__THREE_GAME_DIAGNOSTICS__`: renderer info, simulation snapshot, input state, entity count, physics body/collider counts (if any), DPR/shadow summary
+- `window.__THREE_GAME_TEST_HOOKS__`: `seed` / `setState` / `setPausedForScreenshot` / `setReducedMotion` / `hideDebugUi`
+
+Put deterministic random in `simulation` or `lib/random`; bare `Math.random` is prohibited in business paths.
+
+## Engine Failure Triage (Runtime)
+
+| Symptom | Check First |
+| --- | --- |
+| Blank screen / empty canvas | Canvas DOM and CSS dimensions; WebGL context; whether there is only one loop; camera near/far/orientation; whether the scene has visible objects and lights; whether overlay covers Canvas; whether resize updates aspect; whether color space/exposure "hides" objects |
+| Enters but cannot move | Whether input produces intent; whether simulation steps; whether `Object3D` syncs from simulation; whether code is in the wrong layer |
+| Slower over time / leak | dispose; whether geometry/material/audio sources are created every frame; whether bus subscriptions stack -> `engine-performance.md` |
+| Restart anomalies | Whether entities, timers, mixers, physics bodies, listeners, and audio are cleaned up on restart paths |
+| Low-frame jitter | delta clamp; whether physics incorrectly uses variable timestep; whether DPR is too high |
+| No sound | Whether AudioContext was not unlocked -> `engine-audio.md` |
+
+More detailed asset/audio/performance acceptance checklists are in `../game-test`; this file only retains engine ownership decisions.
+
+## Engine Anti-Patterns
+
+- Writing rules source of truth in `useFrame` or HUD
+- A second rAF loop + double rendering with R3F; or an extra `new WebGLRenderer`
+- `game/three` imports React
+- Using `<Html>` as a replacement for formal DOM HUD
+- Entity components each use `useLoader` without unified dispose
+- Visual mesh as collider
+- Syncing physics -> visual transforms in multiple places
+- Restart without dispose / listener removal
+- Hardcoded tunable parameters instead of `public/config.json`
+- Business code hardcodes glTF/texture URLs (should go through manifest / config)