evomeme 0.1.9 → 0.1.10

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)

package/dist/skills/en-US/threejs-3d-game/references/file-structure.md

@@ -0,0 +1,353 @@
+# 3D Game File Structure Specification
+
+This document defines the standard file structure for browser 3D games. The project is a Vite + React + React Three Fiber application: the 3D view is managed by R3F / Three.js, and the DOM UI is managed by React. **This is the only normative source for all 3D code structure and config files in this plugin**. `game-director`, `game-designer`, `game-art`, `threejs-aaa-graphics-builder`, and `game-test` MUST follow this file when a 3D project's config or directory structure is involved.
+
+**Core principle:** React Three Fiber (`<Canvas>`) owns the 3D / WebGL world; React DOM (`src/ui`) owns all formal HUDs, menus, dialogs, settings, inventory, quests, and narrative panels. R3F `<Html>` MUST NOT replace the formal HUD. Cross-layer communication goes through the **event bus**, **input actions**, and explicit **simulation state**.
+
+## `/public/config.json` Rules
+
+`/public/config.json` is the game's external runtime configuration file and is output unchanged as `/dist/config.json` after build.
+
+### Storage Rules
+
+1. All user-tunable colors, gameplay parameters, balance values, and asset URLs MUST be written into `/public/config.json`; hardcoding them in business code is prohibited.
+2. Game code MUST read config through `fetch("./config.json")` (relative path); using the absolute path `/config.json` is prohibited; directly `import config.json` from the `src` directory is prohibited.
+3. The same user-tunable value MUST NOT be repeatedly hardcoded in React, R3F, Three, or CSS.
+
+### Structure Requirement: Strictly Flat
+
+config **MUST be a flat top-level object**. Each parameter is a direct top-level key. Grouping by `assets`, `images`, `gameplay`, `colors`, `params`, etc. is **prohibited**:
+
+```json
+// Correct - flat
+{ "image_background": { ... }, "player_move_speed": { ... } }
+
+// Wrong - nested groups are prohibited
+{ "assets": { "background": { ... } }, "gameplay": { "speed": { ... } } }
+```
+
+Each key falls into one of two categories:
+
+- **Visible parameters** (keys that do not start with `_`): exposed for user editing and MUST use the standard schema below.
+- **Invisible parameters** (keys that start with `_`): internal fields (such as `_game_name`, `_config_version`); raw values are allowed and the schema is not used.
+
+### Visible Parameter Schema
+
+```json
+"key_name": {
+  "value": <actual value>,
+  "type": "int" | "float" | "color" | "bool" | "string" | "audio" | "image" | "video",
+  "label": "<user-language label, <=10 chars>",
+  "min": <number>,
+  "max": <number>
+}
+```
+
+Rules:
+
+- `type` can only be `int`, `float`, `color`, `bool`, `string`, `audio`, `image`, or `video`.
+- `label` uses the user's language and is at most 10 characters long.
+- `min`/`max` appear only for `int`/`float`, and both MUST be provided together.
+- `type: "color"` uses a hexadecimal color string.
+- `type: "image"` MUST additionally declare `"image_type": "Asset"` and `"size": "widthxheight"` (for example `"1440x2560"`) so display size can be judged when true image dimensions cannot be read.
+- For `audio`/`image`/`video`, `value` MUST be a real accessible external `http(s)` URL; local relative paths are prohibited. Images/meshes are generated asynchronously upstream; a transient 404 URL does not mean the asset is invalid, and the asset MUST NOT be rewritten, replaced, or deleted for that reason.
+
+### Example
+
+```json
+{
+  "_game_name": "Example 3D Game",
+  "_config_version": 1,
+  "player_move_speed": { "value": 4.5, "type": "float", "label": "Move Speed", "min": 1, "max": 12 },
+  "camera_follow_lag": { "value": 0.12, "type": "float", "label": "Cam Lag", "min": 0.01, "max": 0.5 },
+  "theme_background_color": { "value": "#0b1020", "type": "color", "label": "Bg Color" },
+  "enable_shake": { "value": true, "type": "bool", "label": "Shake" },
+  "start_button_text": { "value": "Start Game", "type": "string", "label": "Start Text" },
+  "bgm_main": { "value": "https://example.com/bgm.mp3", "type": "audio", "label": "BGM" },
+  "model_player": {
+    "value": "https://example.com/player.glb",
+    "type": "string",
+    "label": "Player"
+  }
+}
+```
+
+Code-side read pattern:
+
+```ts
+await loadConfig()
+const speed = getSetting<number>('player_move_speed', 4.5)
+```
+
+## `/user_upload` Directory Rules
+
+`/user_upload` is a virtual directory for user-uploaded assets. Files under it are not real asset files; they only store asset links or metadata.
+
+1. When user-uploaded assets are needed, first read the corresponding file under `/user_upload` and extract the real URL.
+2. Do not treat `/user_upload/...` as a local asset path; final code MUST reference the extracted real URL.
+
+## Deployment and Path Rules
+
+1. The final deployment artifact is fixed as `/dist`, deployed as a static site, and runtime resources MUST be directly accessible by the browser.
+2. `/dist` MUST run independently of the source directory: all runtime code, resources, chunks, CSS, audio, images, models, and configuration may reference only files inside `/dist` or external `http(s)` links. Relative paths or build-artifact internal paths MUST be used, and runtime references pointing to the source directory are strictly prohibited.
+3. `vite.config.ts` MUST set `base: './'`, making build artifacts use relative paths (`./assets/...`) so they work when deployed under any subpath.
+4. All runtime string paths (`fetch`, `Audio`, dynamic `import`, CSS `url()`, `GLTFLoader`) MUST use `./` relative paths or external `http(s)` URLs. Absolute paths starting with `/` (site root paths) are prohibited.
+
+## Required Files at Project Root
+
+- `/project.md`: the only source of game requirements (design document); all subsequent development is based on this file.
+- `/public/config.json`: the runtime configuration and asset-binding contract.
+- `/src`: Vite + React + R3F source code.
+- `/dist`: build artifact and deliverable.
+
+## Tech Stack
+
+| Tech | Role |
+| --- | --- |
+| Vite | Build and development server |
+| React | App shell and DOM UI |
+| React Three Fiber (R3F) | Mounts Three.js `Canvas`, lifecycle, and `useFrame` orchestration |
+| Three.js | WebGL rendering, camera, lights, meshes, `AnimationMixer`, GLB, etc. |
+| Tailwind CSS v4 | DOM UI styling |
+| mitt | Event bus between React UI and game runtime |
+| `public/config.json` | External runtime configuration |
+| pnpm | Package manager (`pnpm install` / `pnpm build`) |
+
+## Required Top-Level Structure
+
+```text
+.
++-- index.html
++-- package.json
++-- public/
+|   +-- config.json
+|   +-- assets/            # Optional static asset directory
++-- src/
+    +-- main.tsx
+```
+
+Full recommended tree:
+
+```text
+.
++-- index.html
++-- package.json
++-- pnpm-lock.yaml
++-- tsconfig.json
++-- vite.config.ts
++-- public/
+|   +-- config.json
+|   +-- assets/
++-- src/
+    +-- main.tsx
+    +-- App.tsx
+    +-- index.css
+    +-- config/
+    |   +-- config.ts          # fetch public/config.json -> loadConfig() / getSetting()
+    |   +-- types.ts           # Config types (optional)
+    +-- game/
+    |   +-- bridge/
+    |   |   +-- gameBus.ts     # mitt event bus
+    |   |   +-- gameCommands.ts
+    |   |   +-- gameEvents.ts
+    |   +-- simulation/
+    |   |   +-- state.ts       # Serializable, testable game state
+    |   |   +-- systems/       # Deterministic gameplay systems
+    |   |   +-- rules.ts       # Rules with no Three / React dependencies
+    |   +-- content/
+    |   |   +-- encounters/
+    |   |   +-- items/
+    |   |   +-- maps/
+    |   +-- input/
+    |   |   +-- actions.ts
+    |   |   +-- bindings.ts
+    |   |   +-- inputState.ts
+    |   +-- assets/
+    |   |   +-- manifest.ts    # Stable asset keys, URLs, metadata
+    |   +-- audio/
+    |   |   +-- audioManager.ts
+    |   |   +-- audioHooks.ts
+    |   |   +-- audioPrefs.ts
+    |   +-- three/             # No React import; unit-testable Three modules
+    |       +-- buildWorld.ts
+    |       +-- orbitCameraRig.ts
+    |       +-- character/
+    |       +-- creatures/
+    +-- ui/
+    |   +-- components/
+    |   |   +-- GameCanvas.tsx # R3F <Canvas>, useFrame, world mount
+    |   +-- hud/
+    |   +-- menus/
+    |   +-- overlays/
+    |   +-- store/
+    |       +-- useGameUiStore.ts
+    +-- components/            # Shared DOM UI primitives (non-game business UI)
+    +-- lib/
+        +-- utils.ts
+```
+
+## File Responsibilities
+
+| Path | Owner | Role |
+| --- | --- | --- |
+| `index.html` | tech | Shell page; mounts `#root` / `#app` and loads `/src/main.tsx`. |
+| `package.json` | tech | Scripts and dependencies; MUST expose `build` (usually also `dev`). |
+| `public/config.json` | product / ops | Runtime-tunable parameters and content pointers; prefer changing this over source. |
+| `src/main.tsx` | tech | Startup: after `loadConfig()`, `createRoot(...).render(<App />)`. |
+
+## Deliverables
+
+The game is not complete unless **both** exist:
+
+| Artifact | When | Why |
+| --- | --- | --- |
+| `public/config.json` | Always in the source tree | Ops/runtime configuration source; copied into `dist/` by Vite build. |
+| `dist/index.html` | After `pnpm build` | Deliverable static entry point. |
+
+After a successful build, `dist/config.json` (`public/config.json` runtime copy) should also exist.
+
+## Package Management and Scripts
+
+- Package manager: **pnpm** (default; do not use npm/yarn).
+- Install: `pnpm install`
+- Production build: `pnpm build`
+- Local development: `pnpm dev`
+
+Minimum script contract:
+
+```json
+{
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "tsc && vite build",
+    "preview": "vite preview --host 127.0.0.1"
+  }
+}
+```
+
+Verification before a new project is ready:
+
+1. `public/config.json` exists.
+2. `pnpm install` succeeds.
+3. `pnpm build` succeeds and outputs **`dist/index.html`** (and `dist/config.json`).
+4. Entry chain is healthy: `index.html` -> `src/main.tsx` -> `loadConfig()` -> `<App />` (`GameCanvas` + DOM HUD).
+
+## Startup Flow
+
+```text
+main.tsx
+  -> loadConfig()
+  -> createRoot(...).render(<App />)
+App.tsx
+  -> GameCanvas (R3F <Canvas>, World + useFrame)
+  -> Hud / MobileHud
+  -> PauseMenu, overlays (as needed)
+
+GameCanvas.tsx
+  -> buildWorldInto / GLTFLoader (via game/three)
+  -> useFrame: simulation step + scene sync + camera
+```
+
+`GameCanvas.tsx` is the **WebGL <-> React DOM boundary**. DOM UI is overlaid above Canvas (composed in `App`). On unmount, dispose Three resources and bus subscriptions.
+
+## Layering Rules
+
+### R3F / 3D Runtime (`src/ui/components/GameCanvas.tsx` + `src/game/three/`)
+
+**`GameCanvas.tsx` (mount boundary) is responsible for:**
+
+- Creating the R3F `<Canvas>` (shadows, `gl`, `dpr`, and other defaults are in `engine-runtime.md`)
+- `useFrame` orchestration: read input/simulation -> update `Object3D` or state -> `mixer.update` -> camera (rendering is left to R3F; unless offscreen, do not manually call `renderer.render`)
+- Assembling the scene root: `buildWorldInto(group)`, asynchronous GLB loading
+- Disposing geometry, materials, `AnimationMixer`, and bus subscriptions on StrictMode remount / unmount
+
+**`game/three/*` (pure Three modules) is responsible for:**
+
+- Scene construction, math, and loading helpers with no React imports
+- Not secretly changing DOM outside React refs
+
+Emit gameplay facts with `gameBus.emit()`; accept UI commands (pause, reset, use item, etc.) through `gameBus` / command types.
+
+**Prohibited:**
+
+- `import` React components or hooks inside `game/three`
+- Piling formal HUD/menus into R3F `<Html>`
+- Scattering touch joystick / gesture mapping in `useFrame` or random components (centralize in `game/input` or UI -> unified actions)
+
+### React DOM UI (`src/ui` + `src/components`)
+
+**Responsible for:** HUD, bars, buttons, main/pause/settings menus, inventory, quests, dialogs, results, toast; emits `command:*` through `gameBus`; reads runtime state through `useGameUiStore()` (or equivalent).
+
+**Prohibited:** directly taking `Mesh` / `Object3D` inside HUD and changing `position` every frame; writing core rules in UI components; putting per-game business UI into `src/components`; duplicating joystick bindings across multiple components without going through `game/input`.
+
+### Simulation (`src/game/simulation`)
+
+Responsible for player/enemy state, inventory, quests, combat values, pure rules, and serializable saves. Must have no Three.js / R3F / React dependencies.
+
+### Content (`src/game/content`)
+
+Responsible for levels, maps, encounters, waves, items, rewards, and other static design data. React components and the `Object3D` lifecycle are prohibited from coupling to it.
+
+### Input (`src/game/input`)
+
+Responsible for unified actions, keyboard/mouse/virtual joystick/touch bindings, and the semantic input surface shared by UI and `GameCanvas`. Undocumented scattered hardcoded bindings are prohibited; directly rewriting persistent simulation root state is prohibited.
+
+### Assets (`src/game/assets`)
+
+Responsible for stable keys, URLs, types, and metadata for glTF / textures / audio / VFX. Hardcoding `"/foo/bar.glb"` throughout gameplay, UI, and scene modules is prohibited.
+
+### Audio (`src/game/audio`)
+
+Responsible for reading BGM/SFX paths and toggles from config, Web Audio / HTMLAudio playback and dispose, listening to `gameBus` to map gameplay facts to sound, and applying `command:audio-prefs` emitted by HUD. Playing in-game SFX with `new Audio()` inside HUD is prohibited; creating new audio sources or footstep loops every frame in `useFrame` is prohibited; in-game BGM MUST NOT remain after exit/results/failure/restart. Unlock, event hooks, and cleanup details are in `engine-audio.md`.
+
+## Event Bridge Rules
+
+Files: `src/game/bridge/gameBus.ts`, `gameEvents.ts`, `gameCommands.ts`.
+
+Naming:
+
+- `command:*` - React -> game runtime
+- `game:*` - global session / world events
+- `player:*` - player state
+- `enemy:*` - enemy state
+- `ui:*` - UI-facing events
+- `game:feedback` / `player:movement` - in-game feedback cues (SFX + VFX); payload is plain data
+
+When adding events, update the `gameCommands.ts` / `gameEvents.ts` types in the same change.
+
+## Diagnostics and Test Hooks
+
+Install when `GameCanvas` mounts and clean up on unmount; type declarations go in `src/vite-env.d.ts`.
+
+- `window.__THREE_GAME_DIAGNOSTICS__`: renderer info, simulation snapshot, input state, entity count, etc. (for canvas inspector / AAA scorecard).
+- `window.__THREE_GAME_TEST_HOOKS__`: `seed` / `setState` / `setPausedForScreenshot` / `setReducedMotion` / `hideDebugUi` (for visual regression and bot playtest).
+
+Put deterministic random in `src/lib/random.ts` or `src/game/simulation/random.ts`; business paths are prohibited from using `Math.random`.
+
+## Hard Methodology
+
+- **Keep layering:** `game/three` MUST NOT import React; DOM UI MUST NOT directly drive `Object3D`. Prefer `gameBus` or a single input/simulation facade.
+- **Simulation first:** rules are in `game/simulation`, not in `useFrame` or `Hud.tsx`.
+- **Centralized input:** physical -> semantic mapping is in `game/input`.
+- **Content is data:** levels/maps/items are in `game/content`.
+- **Asset directory:** glTF / textures / audio go through `manifest.ts` or config keys.
+- **Centralized in-game audio:** only `game/audio`; preferences go through the bus.
+- **Centralized config:** tunable parameters are in `public/config.json`.
+- **UI placement:** business DOM UI is in `src/ui`; shared primitives are in `src/components`; formal HUD is never an R3F child node.
+- **Verification:** run `pnpm build` after meaningful changes.
+
+## Anti-Patterns
+
+- Building full menus / inventory / settings inside `useFrame`
+- Grabbing scene-internal refs from arbitrary React components and changing mesh everywhere
+- Putting combat rules into `Hud.tsx`
+- Using `Mesh.userData` as a persistent database for UI/saves
+- Input and state drifting from multiple sources
+- Copying the same touch action mapping across multiple files
+- Hardcoding the same glTF/texture URL string in multiple places
+- Using `src/main.ts` instead of `src/main.tsx` while following this specification
+- Replacing this layout with CRA, Next.js, or npm-only scaffolding (unless the user asks)
+
+## Output Expectations
+
+When adding features, state the owning layer (R3F/Three orchestration / React UI / Simulation / Content / Input / Assets / Audio) and why. Route cross-layer behavior through `gameBus` (or the agreed single facade), and update event types. Confirm with `pnpm build`.

package/dist/skills/en-US/threejs-aaa-graphics-builder/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: threejs-aaa-graphics-builder
+description: Upgrade Three.js scenes with high-quality art direction, materials, lighting, shaders, VFX, asset acquisition, and render budgets. Use when 3D browser games need measurable visual quality improvement beyond prototype graphics.
+---
+
+# Three.js AAA Graphics Builder
+
+## Purpose
+
+Own the production graphics pass. Convert basic screenshots into authored, high-density, performance-aware visual experiences.
+
+
+## Use When
+
+Screenshots still look basic, models look primitive, worlds are sparse, UI/world art feels generic, or the user asks for premium, AAA, high-fidelity, showcase, or less-basic graphics.
+
+## Required References
+
+These references are required phase-entry gates, not optional reading:
+
+- Load `../game-art/references/scene-profiles.md` and select a `scene_profile_id` before world kit, lighting polish, or any claim that World/environment is authored. Read only the **World + 3D · Lighting + Entities + Reject** sections for that profile; this skill executes the production pass against it.
+- Load `references/visual-scorecard.md` before scoring, judging completion, or making any premium/AAA/showcase claim.
+- Load `references/implementation-blueprint.md` before changing graphics architecture, materials, VFX, rendering, diagnostics, or broad visual systems.
+- Load `references/model-recipes.md` before building or upgrading hero/player, obstacle, enemy, pickup, world-kit, material, or prop models.
+- Load `references/render-recipes.md` before changing lighting, tone mapping, shadows, fog, post-processing, materials, or render composition.
+- Load `references/technical-art.md` before premium/AAA/showcase graphics work, shaders/material systems, VFX systems, generated/imported asset cleanup, LOD/instancing work, or visual changes that could affect browser performance.
+- Load `references/shader-cookbook.md` before writing any custom shader, `onBeforeCompile` injection, material recipe, sky, or post-processing chain; use its proven values and GLSL patterns instead of improvising.
+- Load `references/checklists/aaa-game-quality-gate.md` and `references/checklists/aaa-visual-scorecard.md` before declaring a game premium, AAA, showcase, complete, release-ready, or less basic.
+- Load the relevant checklist before focused work: `references/checklists/procedural-model-quality.md`, `references/checklists/material-lighting-quality.md`, `references/checklists/performance-safe-visual-detail.md`, or `references/checklists/technical-art-quality.md`.
+- Load `references/graphics-prompt-templates.md` only when the user asks for reusable prompts, a graphics-pass prompt, or a task template.
+
+For broad "still looks basic", premium, AAA, high-fidelity, showcase, or less-basic graphics work, load the scene-profiles paradigm (3D Lighting rail) plus all five core references (`visual-scorecard`, `implementation-blueprint`, `model-recipes`, `render-recipes`, `technical-art`) as the first action in the phase. Track them in a reference ledger with yes/no, path, and failure reason. Do not mark the graphics phase complete while any required reference is skipped.
+
+External asset sourcing gate:
+
+- For premium/AAA/showcase/high-fidelity/less-basic graphics with a hero/player, character, creature, boss, vehicle, ship, building, weapon, signature prop, complex pickup, or hero environment piece, prefer authored procedural factories from `references/model-recipes.md` before settling for placeholders. Remote mesh generation is offline in the current release.
+- For concept needs, texture/material references, decals, logos, faction marks, icons, GUI art, skies, backgrounds, or title/menu art: prefer procedural/CSS/canvas UI art; use user-supplied local images via `evomeme_upload_game_asset`.
+- Create an asset sourcing ledger for each high-value surface: procedural / hybrid / user-provided, plus outputs or skip reason.
+- `not-needed` is valid only after the relevant path was considered and the ledger explains why external assets would not improve a non-hero support surface, or why an attempted MCP/CDN call shows a real blocker.
+- For premium hero surfaces, procedural-only is allowed; document that constraint and still meet silhouette/material/lighting quality via procedural authorship or user-provided GLB/FBX.
+
+## Workflow
+
+1. Capture or inspect active desktop/mobile screenshots.
+2. Confirm or select a `scene_profile_id` from `../game-art/references/scene-profiles.md` (World / 3D · Lighting / Entities). If missing, write it before upgrading surfaces.
+3. Score visuals across art direction, hero/player, obstacles, rewards, world, materials, render, VFX, UI, and performance evidence.
+4. Add missing graphics architecture: material library, procedural textures/decals, model factories, world prop kit, technical-art budget, VFX system, render pipeline, diagnostics.
+5. Fill the external asset sourcing ledger per surface: procedural Three.js factory, user-provided model/2D reference, or a hybrid.
+6. Upgrade every weak visible surface, not only one hero object. World layers must match the chosen scene-profiles paradigm (Play / Near / Mid / Far / Motion).
+7. Add lighting/render/material polish after authored forms exist, following the paradigm's Lighting stack intent and `references/render-recipes.md`.
+8. Add event-driven VFX tied to gameplay state.
+9. Re-score screenshots against the calibration anchors, citing the inspector's measured metrics. Continue until every premium category is at least 2/3 or report exact blockers.
+10. Run the fresh-eyes review per `references/visual-scorecard.md` before finalizing premium/AAA/showcase claims.
+11. Verify renderer diagnostics against the render budget table, technical-art budget, desktop/mobile screenshots, console/page errors, canvas pixels, imported asset budgets, and playability.
+
+## Core Rule
+
+Do not make primitives look AAA by adding glow. First build authored forms, then materials, then lighting, then effects.
+
+## Final Response
+
+Report the reference ledger, external asset sourcing ledger, technical art brief, score before/after, production surfaces upgraded, files changed, screenshots/artifacts, renderer diagnostics, imported asset diagnostics when relevant, VFX readability and render-budget tradeoffs, and remaining blockers. For premium/AAA/showcase claims, include the filled visual scorecard exactly as defined in `references/visual-scorecard.md`, including average and automatic failures remaining.

package/dist/skills/en-US/threejs-aaa-graphics-builder/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Three.js AAA Graphics Builder"
+  short_description: "Comprehensively improve a 3D game's models, materials, lighting, effects, and rendering quality"
+  default_prompt: "Please use $threejs-aaa-graphics-builder to improve this 3D game's overall visual quality, and refine its models, materials, lighting, effects, and performance presentation."
+
+policy:
+  allow_implicit_invocation: false

package/{skills → dist/skills/zh-CN}/evomeme-cloud-fs/SKILL.md

@@ -21,7 +21,7 @@ description: 讲解 evomeme工作区 init、.evomemeignore，以及源码提交
 - 把包内 skill 复制到工作区 **`.codex/skills/`**
 - 确认本机登录态（供后续 MCP 使用）
 
-npm 包名为 **`evomeme`**（可执行入口 `evomeme`）。
+npm 包名为 **`evomeme`**（可执行入口 `evomeme`）。
 
 ### 用法
 
@@ -85,13 +85,13 @@ npx -y evomeme@latest install --ide codex
 | 工具名 | 功能 |
 | --- | --- |
 | `evomeme_submit_game_code` | **游戏发布**（非纯源码上传）：按 `.evomemeignore` 收集并全量覆盖云端作品，**必须包含可运行的 `dist/`**；不可撤销。 |
-| `evomeme_upload_game_asset` | 将受支持的本地图片、音频或视频交给服务端上传 TOS；内容审核通过后才返回公开 `asset_url`。其他类型禁止上传。 |
+| `evomeme_upload_game_asset` | 将受支持的本地图片、音频、视频或常见 3D 模型（GLB/GLTF/FBX/OBJ/STL）交给服务端上传 TOS；内容审核通过后才返回公开 `asset_url`。其他类型禁止上传。 |
 
 ### `evomeme_submit_game_code`
 
 把当前工作区里按 `.evomemeignore` 收集到的 **utf-8 文本源码**，全量同步到云端作品。
 
-**硬性约束：任何二进制文件都不得通过本工具上传**（含图片、模型、音视频、字体、压缩包等）。源码提交只收集文本；受支持的图片、音频和视频只能经 `evomeme_upload_game_asset` 上 TOS，模型、字体、压缩包和其他类型不支持上传。提交前还必须通过下文的发布产物门禁；发现任一二进制或绝对本地依赖时，禁止调用本工具。
+**硬性约束：任何二进制文件都不得通过本工具上传**（含图片、模型、音视频、字体、压缩包等）。源码提交只收集文本；受支持的图片、音频、视频和常见 3D 模型（GLB/GLTF/FBX/OBJ/STL）只能经 `evomeme_upload_game_asset` 上 TOS，字体、压缩包和其他未列出类型不支持上传。提交前还必须通过下文的发布产物门禁；发现任一二进制或绝对本地依赖时，禁止调用本工具。
 
 可选参数：
 
@@ -164,7 +164,7 @@ npx -y evomeme@latest install --ide codex
 
 ### `evomeme_upload_game_asset`
 
-将受支持的本地图片、音频或视频交给服务端上传 TOS，内容安全审核通过后才返回公开 `asset_url`；其他类型禁止上传。提交源码前处理媒体资源时优先用本工具；说明见 `../evomeme-tos-upload/SKILL.md`。
+将受支持的本地图片、音频、视频或常见 3D 模型（GLB/GLTF/FBX/OBJ/STL）交给服务端上传 TOS，内容安全审核通过后才返回公开 `asset_url`；其他类型禁止上传。提交源码前处理媒体 / 模型资源时优先用本工具；说明见 `../evomeme-tos-upload/SKILL.md`。
 
 ---