evomeme 0.1.9 → 0.1.10-beta.13

package/dist/skills/en-US/phaser-2d-graphics-builder/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Phaser 2D Graphics Builder"
+  short_description: "Comprehensively improve a 2D game's characters, scenes, composition, effects, and overall visual quality"
+  default_prompt: "Please use $phaser-2d-graphics-builder to improve this 2D game's overall visual quality, and refine its characters, scene layering, composition, and effects presentation."
+
+policy:
+  allow_implicit_invocation: false

package/dist/skills/en-US/threejs-3d-game/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: threejs-3d-game
+description: Implement 3D browser games with Three.js, React Three Fiber, TypeScript, and Vite. Use when R3F Canvas, simulation systems, DOM HUD overlays, event-bus bridging, or 3D project file structure is needed.
+---
+
+# Three.js 3D Game Implementation
+
+## Overview
+
+This skill is for the concrete implementation phase of 3D browser games.
+
+Tech stack: **Three.js + React + R3F + TypeScript + Vite + pnpm**. R3F `<Canvas>` owns the 3D / WebGL world; React DOM (`src/ui`) owns the HUD, menus, and narrative panels. Cross-layer communication goes through the event bus, unified input actions, and serializable simulation state.
+
+## Architecture Principles
+
+1. **Separate R3F and DOM**
+   - `<Canvas>` / `game/three` owns scenes, meshes, lights, `AnimationMixer`, and camera orchestration.
+   - `src/ui` owns the formal HUD, menus, settings, inventory, quests, and narrative panels.
+   - MUST NOT use R3F `<Html>` as a replacement for the formal HUD.
+
+2. **Simulation Before Rendering**
+   - Rules, values, win/loss, and saves belong in `game/simulation`, with no Three / React dependencies. (Aligned with the System layer in the 2D skill: the rules source-of-truth layer.)
+   - `useFrame` only orchestrates: read input/simulation -> sync `Object3D` -> mixer/camera; it does not write core rules.
+
+3. **Pure Three Modules Must Be Unit-Testable**
+   - `game/three/*` MUST NOT import React; scene construction and math helpers can be verified independently.
+
+4. **Stable Asset Keys + Canonical Semantics**
+   - All game code references assets through `manifest` / `public/config.json` / canonical packages, and does not hardcode glTF / texture paths in business code.
+   - **3D meshes MUST come from** `assets/canonical/<id>/` (or from `evomeme asset sync <id> --target three_js --project "<project>" --workspace "<workspace>" --json` syncing to `public/assets/canonical/<id>/`).
+   - After loading, orientation/scale **MUST** be applied according to `asset.json` (see `references/engine-asset-pipeline.md`); hardcoding `rotation.y += Math.PI` inside entities is prohibited.
+   - Alignment and preview default to `game-asset-align` + CLI `evomeme stage --asset <id> --target three_js`. Read the [CLI contract](../game-asset-align/references/tool-contract.md): `evomeme` abbreviates `npx -y evomeme@latest` or a local build of the same version; supply `--workspace` and use `--json` for automation. Keep Stage in a persistent session, return its URL at startup, and run subsequent commands in another terminal.
+   - **After Blender modeling or modification, Stage MUST be opened first, and the asset may only be imported after the user views and confirms the current Three.js version.** `alignment.ready=true` or `asset align` does not replace user confirmation; do not manually copy or click on behalf of the user to bypass the gate.
+
+## Implementation Guidance
+
+- Use `gameBus` (mitt) so React UI emits `command:*`, and the game runtime emits factual events such as `game:*` / `player:*`.
+- Centralize physical input mapping in `game/input`; UI and Canvas only consume unified semantic actions.
+- Put content data (levels, encounters, items) in `game/content`, decoupled from the rendering lifecycle.
+- Centralize audio in `game/audio`, driven by bus events; MUST NOT play in-game SFX with `new Audio()` inside the HUD (see `references/engine-audio.md` for details).
+- Canvas / gl / DPR defaults and R3F loading boundaries are covered in `references/engine-runtime.md`.
+
+## Covered 3D Game Types
+
+- Third-person / top-down exploration and lightweight action
+- Endless runners and obstacle dodging
+- Vehicles, pinball, and rigid-body sketches
+- Lightweight shooting or encounter battles
+- Casual gameplay that needs spatial 3D presentation
+
+## Camera and Presentation
+
+- Decide the camera model early: follow, orbit, lock-on, over-the-shoulder.
+- Separate camera logic from game rules; shake / FOV changes serve readability.
+- Resources MUST be disposed on StrictMode remount / unmount (geometry, materials, mixer, bus subscriptions).
+- See `references/engine-input-camera.md` for details.
+
+## Engine References (Load As Needed)
+
+When writing/modifying 3D runtime code, load references by task in addition to `file-structure.md`; do not pre-read everything at once:
+
+| Task | Load |
+| --- | --- |
+| Frame loop, Canvas/gl defaults, dispose, blank screen/double loop, R3F policy, diagnostic hooks | `references/engine-runtime.md` |
+| Input intent, touch stickiness, camera follow / FOV | `references/engine-input-camera.md` |
+| Physics selection, Rapier/fixed step, collision proxies | `references/engine-physics.md` |
+| GLB/FBX import, AnimationMixer, root motion, import performance | `references/engine-asset-pipeline.md` |
+| Stutter, pooling, InstancedMesh, DPR, LOD, hot-path allocation | `references/engine-performance.md` |
+| AudioContext unlock, bus-driven audio playback, mute, restart cleanup | `references/engine-audio.md` |
+
+Directory structure and layering are governed by this skill's `file-structure.md`; **do not** create separate directories based on the unrelated `core/entities/systems` scaffold.
+
+## UI Integration
+
+- HUDs, command menus, settings, and narrative interfaces use React DOM, overlaid above Canvas (`App` composition).
+- `GameCanvas.tsx` is the WebGL <-> React DOM boundary.
+- Business UI goes in `src/ui`; shared non-business primitives go in `src/components`.
+
+## Scaffolding and Configuration
+
+New project entry points: `index.html`, `src/main.tsx`, `public/config.json`. The package manager is **pnpm**. Build artifacts go to `dist/`, which must include `dist/index.html` and `dist/config.json`.
+
+Directory layout, layering responsibilities, config schema, and deployment paths use `references/file-structure.md` as the only normative source.
+
+## Common Anti-Patterns
+
+- Writing combat/win-loss rules in `useFrame` or `Hud.tsx`
+- Piling formal menus and settings into R3F `<Html>`
+- Importing React hooks / components inside `game/three`
+- HUD directly holding an `Object3D` reference and changing `position` every frame
+- Hardcoding the same glTF / texture path in multiple places
+- Adding an extra `new WebGLRenderer` or a second rAF that competes with R3F's loop
+- Not capping DPR; aggressively creating meshes/audio sources on hot paths
+- Playing in-game SFX with `new Audio()` inside the HUD
+- Replacing this specification with a CRA / Next.js / npm-only scaffold (unless the user explicitly requests it)
+
+## References
+
+**Engine (This Skill)**
+- File structure and layering: `references/file-structure.md`
+- Runtime / Canvas / R3F policy: `references/engine-runtime.md`
+- Input and camera: `references/engine-input-camera.md`
+- Physics and collision: `references/engine-physics.md`
+- Asset loading and animation: `references/engine-asset-pipeline.md`
+- Performance: `references/engine-performance.md`
+- Audio runtime: `references/engine-audio.md`
+
+**Cross-Skill (Gameplay / Acceptance, Not Engine Implementation Details)**
+- Gameplay workflow: `../game-designer/references/gameplay-workflows.md`
+- Game-feel tuning: `../game-designer/references/game-feel.md`
+- Level design: `../game-designer/references/game-design-level-design.md`
+- Physics selection (design-side comparison): `../game-designer/references/physics-engine-selection.md`
+- Definition of done for new games: `../game-designer/references/checklists/new-game-definition-of-done.md`
+- Art style guide: `../game-art/references/art-styles.md`
+- UI style specification: `../game-ui/references/ui-styles.md`
+- Audio asset generation: `../game-audio/SKILL.md`
+- QA / performance profiling: `../game-test/SKILL.md`

package/dist/skills/en-US/threejs-3d-game/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Three.js 3D Game"
+  short_description: "Build clearly structured 3D browser games, separating gameplay simulation, scene rendering, and interface"
+  default_prompt: "Please use $threejs-3d-game to implement this 3D browser game according to my requirements, while keeping the boundaries between gameplay simulation, 3D scene, and interface clear."
+
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,155 @@
+# 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`.
+
+Resolve the `evomeme` launcher through the [CLI contract](../../game-asset-align/references/tool-contract.md) and supply the workspace explicitly. Keep Stage in a persistent foreground session and run sync in another terminal.
+
+## 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 --asset <id> --workspace "<workspace>" --target three_js --json`; 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 <id> --target three_js --project "<project>" --workspace "<workspace>" --json
+-> 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 | Edit and re-export from Blender (`evomeme asset repair <id>` supports origin/grounding) -> confirm in Stage again -> sync |
+| 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