evomeme-dev 0.1.7

package/skills/phaser-2d-graphics-builder/references/vfx-recipes.md

@@ -0,0 +1,67 @@
+# VFX Recipes (Phaser 2D)
+
+Event-driven visual effects that clarify game state. Load only after sprites and compose are readable. Core rule still applies: FX never substitutes for authored art.
+
+Cross-link: hand-feel timing principles in `../game-designer/references/game-feel.md`; UI motion in `../game-art/references/animation-specs.md`. This file is **in-world / camera FX** for Phaser.
+
+## Principles
+
+1. **One trigger → one readable beat.** Prefer a single strong burst over layered noise.
+2. **Severity scale.** Pickup < hit < kill < fail/clear. Strongest events must still leave the next decision visible.
+3. **Pool everything.** No allocating emitters per bullet in `update`.
+4. **Sync with audio when present.** Same frame as SFX when `game-audio` is wired.
+5. **No ambient filler** to hide empty Far layers.
+
+## Recipe Table
+
+| Event | Primary FX | Duration | Notes |
+| --- | --- | --- | --- |
+| Light confirm (UI-adjacent in world) | Small scale pop + brief spark | 100–200ms | Keep off HUD DOM |
+| Pickup / coin | Radial burst (8–16 particles) + optional arc to HUD anchor | 200–350ms | High contrast; don’t blanket Play |
+| Hit (player) | White/red flash on sprite + tiny camera shake | 80–120ms | Invuln blink separate from flash |
+| Hit (enemy) | Impact ring or directional sparks + hitstop 1–2 frames | 100–180ms | Direction from attack vector |
+| Block / parry | Sharp spark + short freeze | 80–150ms | Distinct from hurt |
+| Dash / boost | Motion streaks or afterimage (2–3 ghosts) | During dash | Cap ghosts; fade quick |
+| Death / explode | Larger burst + brief screen flash ≤30% alpha | 300–500ms | Then remove clutter |
+| Spawn | Poof / ring expand | 200–300ms | Telegraph if hostile |
+| Charge telegraph | Pulse outline / growing warning glyph | Wind-up length | Must be readable before damage |
+| Zone warning | Edge vignette or floor decal pulse | While zone active | Center Play stays clear |
+| Combo / milestone | Short celebratory burst + optional zoom punch | 250–400ms | Don’t stack with death FX |
+| Fail / soft lock | Gray flash or desat pulse | 200ms | Not seizure-level strobe |
+
+## Implementation Notes (Phaser)
+
+- Prefer `this.add.particles` with preconfigured `ParticleEmitter` reused via pools, or a small `VfxSystem.burst(kind, x, y, dir?)` API.
+- Sprite flash: tween `setTintFill` / short `setAlpha` blink; clear tint on complete.
+- Afterimages: spawn faded copies at depth just below hero; auto-destroy.
+- Screen flash: camera-fixed Rectangle or Image at Screen FX depth; fade out; ignore input blocking.
+- Respect `technical-art.md` emitter and particle caps; on spam (machine-gun hits), coalesce to rate-limited bursts.
+
+## Anti-Patterns
+
+- Permanent floating dust as “atmosphere” when Far art is missing.
+- Full-screen rainbow particles on every tap.
+- Shake so strong platforms/hazards can’t be aimed at.
+- Additive glow soup that blows out silhouette edges.
+- FX that spawn without a gameplay event (pure decoration loops).
+
+## Severity Ladder (default)
+
+```text
+0  none
+1  sprite-only (tint/scale)
+2  local particles
+3  local particles + camera punch
+4  screen flash + particles + punch
+```
+
+Map events to ≤ one ladder step above the previous severity so players learn intensity.
+
+## Checklist
+
+Before scoring VFX/motion ≥ 2:
+
+- [ ] Every FX kind maps to a gameplay event
+- [ ] Caps documented in technical art brief
+- [ ] Mobile screenshot shows FX without hiding hazards
+- [ ] No ambient-only particle layer required for “premium”

package/skills/phaser-2d-graphics-builder/references/visual-scorecard.md

@@ -0,0 +1,129 @@
+# Visual Scorecard (Phaser 2D)
+
+Score active-play screenshots, not idle title screens or isolated asset sheets. Prefer **mobile portrait** screenshots; add desktop when the project targets it.
+
+Scores are self-assessed against the anchors below, so they drift optimistic. For premium/showcase claims: cite Measured Evidence where possible, run the Fresh-Eyes Review, and compare against packaged anchors before finalizing.
+
+## Calibration Anchors
+
+Reference screenshots for score calibration are packaged in `phaser-2d-graphics-builder/assets/scorecard-anchors/`:
+
+- `scene-1.jpeg` — score ~1: geometric/simple hero and props on a flat sparse stage, utility HUD.
+- `scene-2.jpeg` — score ~2: authored sprites and scene art, readable state HUD, intentional composition; still short of dense active-play showcase.
+- `scene-3.jpg` — score ~2.5–3: dense layered authored world in active play, varied character family, readable state feedback, cohesive HUD.
+
+Before scoring World/environment, Hero/player, Sprite fidelity, Compose, or VFX, **view the anchors** and compare: if your screenshot reads closer to `scene-1.jpeg` than `scene-3.jpg` for that surface, the category is at most a 1–2 regardless of how much code was written.
+
+Do not score against title screens, collages, or marketing montages.
+
+## Scoring Scale
+
+- 0: Placeholder. Flat colors, missing art, unreadable state, debug UI, or no evidence.
+- 1: Basic styled. Playable and themed, but obvious prototype assets, flat composition, or generic UI.
+- 2: Premium stylized. Authored silhouettes, layered world, readable state, cohesive UI/world, measured performance.
+- 3: Showcase. Strong art direction, memorable hero and world, dense authored detail, excellent readability, polished VFX, diagnostics.
+
+## Categories
+
+1. Art direction.
+   - 0: No clear theme.
+   - 1: Theme is mostly a palette swap.
+   - 2: Theme affects sprites, world layers, UI, and feedback.
+   - 3: Distinct identity on every production surface.
+2. Hero/player.
+   - 0: Colored rectangle / emoji / default shape.
+   - 1: Basic sprite with glow or simple tint.
+   - 2: Authored silhouette, clear facing, state cues (hurt/boost).
+   - 3: Memorable sprite language with expressive feedback.
+3. Obstacles/enemies.
+   - 0: Same box as everything else.
+   - 1: Recolored repeated silhouette.
+   - 2: At least three readable variants with telegraphs.
+   - 3: Varied family with anticipation and gameplay clarity.
+4. Rewards/interactables.
+   - 0: Plain circle/token.
+   - 1: Repeated icon with simple pulse.
+   - 2: Two authored forms with idle/collect states.
+   - 3: Desirable, animated, clearly valued in motion.
+5. World/environment.
+   - 0: Flat fill or empty stage.
+   - 1: Single background image, sparse props.
+   - 2: Layered Play/Near/Mid/Far matching `scene-profiles` profile.
+   - 3: Dense authored world that still preserves play readability.
+6. Sprite fidelity / atlas.
+   - 0: Procedural shapes only.
+   - 1: Mixed placeholder + one real image.
+   - 2: Key surfaces from MCP/user art; consistent PPI and facing; sheets measured before load.
+   - 3: Cohesive atlas/mip strategy, clean cutouts, no stretched mush.
+7. Compose (camera / parallax / tint).
+   - 0: No depth; camera fights the player.
+   - 1: Parallax or tint used as the whole style.
+   - 2: Intentional camera, parallax ratios, depth sort, readable overlays.
+   - 3: Cinematic but disciplined compose; never hides the next decision.
+8. VFX/motion.
+   - 0: None or random ambient particles.
+   - 1: Generic particles/trails.
+   - 2: Event-driven FX for hit, pickup, fail, combo, spawn, dash.
+   - 3: High-impact FX that clarify state and stay within budget.
+9. UI/HUD.
+   - 0: Debug text or missing UI.
+   - 1: Generic stat cards over the canvas.
+   - 2: Genre HUD via DOM overlay; colors echo world signals.
+   - 3: Cohesive hierarchy and polished transitions without covering Play.
+10. Performance evidence.
+   - 0: No notes after visual changes.
+   - 1: Informal "seems fine".
+   - 2: Texture/display/particle budget notes + mobile screenshot.
+   - 3: Before/after or budget-aware notes, pooling, atlas strategy.
+
+## Thresholds
+
+Premium:
+
+- Every category at least 2.
+- Average at least 2.3.
+- Mobile active-play screenshot when portrait mobile is in scope.
+- Technical-art / budget notes after graphics changes.
+
+Showcase:
+
+- At least six categories score 3.
+- No category below 2.
+- Average at least 2.7.
+- Performance evidence includes before/after or budget-aware notes.
+
+## Automatic Failures
+
+Any of these prevents a premium/showcase claim:
+
+- Active screenshot is placeholder-dominant (SVG/rect/emoji as hero or main threats).
+- Main world is a flat fill with no authored Far/Mid layers when the profile requires them.
+- Hero is mostly a shape plus glow/particles.
+- Obstacles or rewards are one repeated silhouette recolored.
+- Ambient particles or full-screen flash are the primary “art”.
+- Compose (shake/vignette/parallax) hides the next gameplay decision.
+- Dense formal HUD drawn in Canvas instead of DOM without an explicit project requirement.
+- No asset sourcing ledger for premium hero/background surfaces.
+- Claimed premium while required references were skipped.
+
+## Fresh-Eyes Review
+
+Before finalizing premium/showcase:
+
+1. Look only at the latest active-play screenshot for 10 seconds.
+2. Name the weakest two categories without reading the scorecard you just filled.
+3. If either is below 2, lower scores and keep working—or report blockers.
+4. Confirm Automatic Failures are absent.
+
+## Measured Evidence
+
+Prefer citing:
+
+- `public/config.json` keys bound for hero/bg/parallax.
+- Screenshot paths (mobile/desktop).
+- Texture sizes / atlas notes / particle max counts from the technical art brief.
+- Phaser Scale mode confirmation (no CSS canvas scale).
+
+## Output
+
+When claiming premium/showcase, paste a filled table: category, score 0–3, one-line evidence, measured evidence if any. Include average and list Automatic Failures remaining (or “none”).

package/skills/threejs-3d-game/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: threejs-3d-game
+description: 用 Three.js、React Three Fiber、TypeScript 与 Vite 实现 3D 浏览器游戏。在需要 R3F Canvas、模拟系统、DOM HUD 覆盖层、事件总线桥接或 3D 项目文件结构时使用。
+---
+
+# Three.js 3D 游戏实现
+
+## 概述
+
+本技能用于 3D 浏览器游戏的具体实现阶段。
+
+技术栈：**Three.js + React + R3F + TypeScript + Vite + pnpm**。R3F `<Canvas>` 负责 3D / WebGL 世界；React DOM（`src/ui`）负责 HUD、菜单与叙事面板。跨层通信走事件总线、统一输入动作与可序列化模拟状态。
+
+## 架构原则
+
+1. **R3F 与 DOM 分离**
+   - `<Canvas>` / `game/three` 拥有场景、网格、灯光、`AnimationMixer`、摄像机编排。
+   - `src/ui` 拥有正式 HUD、菜单、设置、背包、任务与叙事面板。
+   - 禁止用 R3F `<Html>` 替代正式 HUD。
+
+2. **模拟优先于渲染**
+   - 规则、数值、胜负、存档放在 `game/simulation`，无 Three / React 依赖。（与 2D 技能的 System 对位：规则真相层）
+   - `useFrame` 只编排：读输入/模拟 → 同步 `Object3D` → mixer/相机；不写核心规则。
+
+3. **纯 Three 模块可单测**
+   - `game/three/*` 禁止 import React；场景构建与数学助手可独立验证。
+
+4. **资产键稳定**
+   - 全部游戏代码通过 `manifest` / `public/config.json` 引用资产，不在业务代码中硬编码 glTF / 贴图路径。
+
+## 实现指导
+
+- 通过 `gameBus`（mitt）让 React UI 发 `command:*`，游戏运行时发 `game:*` / `player:*` 等事实事件。
+- 输入物理映射集中在 `game/input`，UI 与 Canvas 只消费统一语义动作。
+- 内容数据（关卡、遭遇、道具）放在 `game/content`，与渲染生命周期解耦。
+- 音频集中在 `game/audio`，由总线事件驱动；禁止在 HUD 里 `new Audio()` 播局内音效（细节见 `references/engine-audio.md`）。
+- Canvas / gl / DPR 默认与 R3F 加载边界见 `references/engine-runtime.md`。
+
+## 覆盖的 3D 游戏类型
+
+- 第三人称 / 俯视探索与轻量动作
+- 无尽跑酷、障碍躲避
+- 载具、弹珠、刚体小品
+- 轻量射击或遭遇战
+- 需要立体空间表现的休闲玩法
+
+## 摄像机与表现
+
+- 早期确定摄像机模型：跟随、轨道、锁定、过肩。
+- 摄像机逻辑与游戏规则分离；震动 / FOV 变化服务于可读性。
+- 资源在 StrictMode 重挂载 / 卸载时必须 dispose（几何、材质、mixer、总线订阅）。
+- 细节见 `references/engine-input-camera.md`。
+
+## 引擎参考（按需加载）
+
+写/改 3D 运行时代码时，在 `file-structure.md` 之外按任务加载，勿一次性预读全部：
+
+| 任务 | 加载 |
+| --- | --- |
+| 帧循环、Canvas/gl 默认、dispose、白屏/双循环、R3F 政策、诊断钩子 | `references/engine-runtime.md` |
+| 输入意图、触控粘滞、镜头跟随 / FOV | `references/engine-input-camera.md` |
+| 物理选型、Rapier/固定步、碰撞代理 | `references/engine-physics.md` |
+| GLB/FBX 导入、AnimationMixer、根运动、导入性能 | `references/engine-asset-pipeline.md` |
+| 卡顿、池化、InstancedMesh、DPR、LOD、热路径分配 | `references/engine-performance.md` |
+| AudioContext 解锁、总线播音、静音、重开清理 | `references/engine-audio.md` |
+
+目录与分层以本技能 `file-structure.md` 为准；**不要**按无关的 `core/entities/systems` 脚手架另建目录。
+
+## UI 集成
+
+- HUD、指令菜单、设置与叙事界面用 React DOM，叠在 Canvas 之上（`App` 组合）。
+- `GameCanvas.tsx` 是 WebGL ↔ React DOM 边界。
+- 业务 UI 放 `src/ui`；共享无业务原语放 `src/components`。
+
+## 脚手架与配置
+
+新项目入口：`index.html`、`src/main.tsx`、`public/config.json`。包管理器为 **pnpm**。构建产物落到 `dist/`，需包含 `dist/index.html` 和 `dist/config.json`。
+
+目录布局、分层职责、config schema 与部署路径以 `references/file-structure.md` 为唯一规范来源。
+
+## 常见反模式
+
+- 在 `useFrame` 或 `Hud.tsx` 里写战斗/胜负规则
+- 用 R3F `<Html>` 堆正式菜单与设置
+- `game/three` 里 import React hooks / 组件
+- HUD 直接拿 `Object3D` 引用每帧改 `position`
+- 多处硬编码同一 glTF / 贴图路径
+- 额外 `new WebGLRenderer` 或第二套 rAF 与 R3F 抢循环
+- 不 cap DPR、热路径狂建网格/音源
+- HUD 里 `new Audio()` 播局内音效
+- 用 CRA / Next.js / npm-only 脚手架替换本规范（除非用户明确要求）
+
+## References
+
+**引擎（本技能）**
+- 文件结构与分层：`references/file-structure.md`
+- 运行时 / Canvas / R3F 政策：`references/engine-runtime.md`
+- 输入与摄像机：`references/engine-input-camera.md`
+- 物理与碰撞：`references/engine-physics.md`
+- 资产加载与动画：`references/engine-asset-pipeline.md`
+- 性能：`references/engine-performance.md`
+- 音频运行时：`references/engine-audio.md`
+
+**跨技能（玩法 / 验收，非引擎实现细节）**
+- 玩法工作流：`../game-designer/references/gameplay-workflows.md`
+- 手感调优：`../game-designer/references/game-feel.md`
+- 关卡设计：`../game-designer/references/game-design-level-design.md`
+- 物理选型（设计侧对照）：`../game-designer/references/physics-engine-selection.md`
+- 新游戏完成定义：`../game-designer/references/checklists/new-game-definition-of-done.md`
+- 美术风格指南：`../game-art/references/art-styles.md`
+- UI 风格规范：`../game-ui/references/ui-styles.md`
+- 音频资产生成：`../game-audio/SKILL.md`
+- QA / 性能画像：`../game-test/SKILL.md`

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

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Three.js 3D Game"
+  short_description: "搭建结构清晰的三维浏览器游戏，分离玩法模拟、场景渲染与界面"
+  default_prompt: "请使用 $threejs-3d-game 根据我的需求实现这个三维浏览器游戏，并保持玩法模拟、三维场景和界面边界清晰。"
+
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,116 @@
+# 引擎：资产加载与动画管线
+
+关注 **运行时如何安全接入 GLB/FBX**。
+
+加载/绑定网格、AnimationMixer、根运动、碰撞代理、导入后性能时加载本文件。路径与 config 契约仍以 `file-structure.md` 为准。
+
+## 输出与加载偏好
+
+| 用途 | 格式 |
+| --- | --- |
+| Three 运行时 | 优先 GLB（PBR） |
+| 动画交换 | FBX 按需，再谨慎导入或离线转 GLB |
+| 打印 / AR | STL/3MF、USDZ —— 非本游戏运行时默认 |
+
+- 用 `GLTFLoader`（`three/addons/loaders/GLTFLoader.js`）。
+- 运行时 URL：`./` 相对路径或外部 `http(s)`；禁止站点根绝对路径 `/...`（见部署规则）。
+- 加载放在资产层 / `game/three` 助手，**不要**在实体每帧 update 里 `load`。
+- 业务代码通过 `manifest` / `config` 键引用，不硬编码 URL。
+
+```ts
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+
+const loader = new GLTFLoader();
+const gltf = await loader.loadAsync(urlFromManifest);
+wrapper.add(gltf.scene);
+```
+
+## 包装实体
+
+导入场景包进游戏实体时显式处理：
+
+- 统一 scale、pivot、朝向（可外层 `Group`）
+- 包围盒 / 逻辑 bounds
+- **与视觉分离的 collision proxy**
+- 加载失败占位或错误态
+- 记录：文件大小、三角面、材质数、贴图尺寸、clip 名
+
+## AnimationMixer
+
+```ts
+const mixer = new THREE.AnimationMixer(gltf.scene);
+const action = mixer.clipAction(gltf.animations[0]);
+action.play();
+
+// useFrame / 模拟后：秒
+mixer.update(deltaSeconds);
+```
+
+- 玩法状态映射到 clip：idle / walk-run / jump / attack / hurt / fall / turn 等。
+- 街机默认：**原地动画 + 代码位移**；若保留根运动，必须有意为之。
+- 重启时 stop actions、dispose mixer，避免叠播。
+
+## 根运动与导入动画注意（引擎侧）
+
+上游绑定/重定向的坑若存在，在引擎侧固定修法：
+
+1. 需要原地动画时优先在**导入后**处理，不要依赖不可控的上游 `animate_in_place` 行为。
+2. 原地化时只改顶层根骨位置轨（常见名 `Root.position`），且只钉死水平 XZ，**保留 Y**（跳跃起伏）。
+3. 不要广谱删 Hip/Pelvis 或 twist 轨：部分绑定把肢体蒙在 twist 上，删轨会塌肢体。
+
+```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;
+    }
+  }
+}
+```
+
+批处理重定向若得到 `NlaTrack` / `NlaTrack.001`：按**请求顺序**用下标映射到预设名，加载后 `clip.name = 'walk'` 再按名选取。
+
+加载后打日志：`gltf.animations.map(c => \`${c.name} ${c.tracks.length} tracks\`)`。人型健康 clip 应驱动大量骨骼；只有极少 track 通常是上游绑定坏了，先修绑定。
+
+### FBX 摄入（人型重定向常见）
+
+- `FBXLoader` 依赖 `fflate`；bundler 一般自动带上。
+- 同一 take 可能出现两条不同 `|` 深度路径的 clip：**保留更浅**的那条。
+- 用关键词选 clip（walk / idle / attack），不要盲目 `animations[0]` 除非管线保证单 take。
+- FBX 常是 Phong，比 GLB PBR 暗；最终美术对齐可离线转 GLB。
+- 除「单根骨水平钉死」外，避免再在 loader 侧「修正」动画（易越修越坏）。
+
+## 性能纪律
+
+- 浏览器/移动：控面数、贴图尺寸；英雄件高质量 + 实例化/程序化配角。
+- Clone 时尽量共享 geometry/material。
+- 离场 / 换关 dispose 已加载资源。
+- 导入前后记 renderer diagnostics：calls、triangles、geometries、textures、materials、文件体积。
+- 运行时卡顿、池化、DPR、LOD 见 `engine-performance.md`。
+
+## 导入体检清单
+
+- [ ] 文件大小与三角面可接受
+- [ ] 网格 / 材质 / 贴图数量与尺寸
+- [ ] 当前灯光下 PBR 观感
+- [ ] 米制尺度与 pivot / bounds
+- [ ] 碰撞代理独立且调试可见
+- [ ] clip 名、时长、根运动策略明确
+- [ ] 失败有占位；成功路径进 manifest/config
+- [ ] 卸载与重开无泄漏
+
+## 常见修复
+
+| 问题 | 处理 |
+| --- | --- |
+| 过大/过小 | 外层 Group 归一化 bounds |
+| 朝向错 | wrapper 旋转，或生成侧对齐选项 |
+| 动画滑步/飘走 | 保留导出根运动后按上式只钉 XZ |
+| 太贵 | 降面、缩贴图、少唯一重模 |
+| 材质过暗/过亮 | 色域、tone mapping、环境光、曝光 |
+| 碰撞怪 | 视觉 mesh 不参与物理，另建 proxy |

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

@@ -0,0 +1,70 @@
+# 引擎：音频运行时
+
+音频运行时落在 `game/audio` + `gameBus`。资产生成与选曲走 `../game-audio`；本文件只管**运行时接线与生命周期**。
+
+改局内 BGM/SFX 播放、解锁、静音、重开清理时加载。
+
+## 所有权
+
+| 事项 | 落点 |
+| --- | --- |
+| 播放 / decode / dispose | `game/audio`（`audioManager` 等） |
+| 玩法事实 → 声音 | `audioHooks` 订阅 `gameBus`（`game:*` / `player:*` / `game:feedback`） |
+| 静音 / 音量偏好 | HUD 发 `command:audio-prefs` → `audioPrefs` 应用 |
+| URL / 开关 | `public/config.json` 或 `game/assets` manifest |
+
+禁止：
+
+- HUD / `useFrame` 里 `new Audio()` 播局内音效
+- 每帧新建音源或脚步循环
+- 在多个组件复制播放逻辑
+
+## 用户手势解锁
+
+浏览器要求在**用户手势**后 resume `AudioContext`（或等价解锁）：
+
+- 首次「开始 / 继续 / 点按 Canvas」路径调用 `audioManager.unlock()`（或 `context.resume()`）
+- 解锁失败要可见（日志 / 诊断），勿静默
+- 移动端必须实机或模拟手势验一次
+
+## 事件驱动钩子（最小集）
+
+按状态发声，不随机装饰：
+
+| 事件类 | 示例 |
+| --- | --- |
+| UI | 点击、暂停、重试 |
+| 进度 | 拾取、得分、里程碑 / combo |
+| 压力 | 受伤、失败、危险接近 |
+| 能力 | 冲刺 / 加速 / 开火 |
+| 氛围 | BGM 或环境 loop（可关） |
+
+`game:feedback` / `player:movement` 等 payload 用普通数据；`game/audio` 映射到具体 clip，不把 URL 写进 UI。
+
+## 生命周期
+
+- **暂停 / 隐藏页**：停或压低局内 BGM；`visibilitychange` 勿叠出第二个 loop
+- **失败 / 结算 / 重开**：停局内 loop 与短效；摘掉仅本局订阅；归还池化音源（若有）
+- **换关**：卸本关独有 buffer；公共 UI 音可留
+- **静音 / 音量**：偏好必须作用到所有分组（BGM / SFX / UI）
+
+## 与 config
+
+BGM/SFX 的 `http(s)` URL、默认音量、是否开音乐进扁平 `config.json`；代码经 `getSetting` / manifest 键读取，禁止散落硬编码路径。
+
+## 故障检查
+
+- 文件 URL、MIME、CORS
+- decode/load reject 是否可见
+- 是否从未 unlock 就 play
+- SFX 是否每帧触发
+- 暂停/重开后是否双 BGM
+- mute 是否漏某一组
+
+## 引擎反模式
+
+- UI 按钮直接 `new Audio(url).play()`
+- 未 unlock 就依赖自动播放
+- 重开残留 BGM / 监听叠加
+- 业务代码硬编码音频 URL
+- 把生成管线细节写进 `game/audio`（生成属 `game-audio` skill）

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

@@ -0,0 +1,84 @@
+# 引擎：输入与摄像机
+
+输入与相机落在 `game/input` + `game/three`。不含 UI 视觉设计、不含 juice 数值配方（手感见 `game-designer/references/game-feel.md`）。
+
+改控制、触控粘滞、镜头跟随、FOV、指针锁定时加载本文件。
+
+## 输入：意图与所有权
+
+1. **采集**（键鼠 / 指针 / 触控 / 手柄）与 **模拟** 分离。
+2. 物理设备 → 语义动作（如 `move`、`dash`、`confirm`）集中在 `game/input`。
+3. `GameCanvas` / DOM HUD 只读统一输入面，禁止在 `useFrame` 里散落硬编码键位。
+4. UI 按钮通过同一套动作或 `command:*` 进入运行时，不在按钮里复制一套规则。
+
+### 粘滞与取消
+
+- 必须处理 `pointerup` / `pointercancel` / `blur` / `visibilitychange`，避免摇杆或冲刺键粘住。
+- 指针控件使用 `setPointerCapture`；测试环境可能无真实 pointerId，需容错。
+- 键位用 `event.code`（布局无关），不要只靠 `key`。
+- CSS `touch-action` 有意设置且范围可控；避免整页滚动偷走手势。
+- 失败 / 暂停 / 重开后恢复焦点与重启控件可用。
+
+### 移动合成（桌面 + 摇杆）
+
+键向量与摇杆向量相加后长度 > 1 则归一化（脚手架模式）：
+
+```ts
+target.copy(keyVector).add(pointerVector);
+if (target.lengthSq() > 1) target.normalize();
+```
+
+移动端在范围内时：虚拟摇杆在 DOM（`src/ui`），经 `game/input` 写入同一 `move` 意图；不要在 Canvas 内再绑一套冲突监听。
+
+### 输入故障检查
+
+- 焦点是否在可接收键盘的页面上
+- 监听是否挂在正确元素
+- `touch-action` / viewport meta / 安全区
+- DPR 导致触控热区过小
+- 旋转后 resize 是否更新
+- 加了移动控件后桌面键鼠是否仍可用
+- UI 是否发出意图，而非直接改模拟根状态
+
+## 摄像机：模型与职责
+
+早期选定一种主模型并写进实现（逻辑在 `game/three`，规则仍在 simulation）：
+
+| 模型 | 适用 |
+| --- | --- |
+| 跟随 + 固定偏移 | 跑酷、俯视动作、街机 |
+| 轨道 / 观察 | 展示、慢节奏探索 |
+| 锁定目标 | 战术、锁定战 |
+| 过肩 | 轻量第三人称 |
+
+规则：
+
+- 相机与游戏规则分离：相机读「跟随目标位姿 / 事件脉冲」，不改写胜负状态。
+- 震动 / FOV kick 只服务可读性，不得挡住下一决策区。
+- 可读性：下一决策可见、玩家足够居中、威胁不被 HUD/相机裁切藏住。
+- 无障碍：避免过度震动、闪烁、不可控运动；尊重 `setReducedMotion` 类钩子。
+
+### 跟随滞后（指数平滑）
+
+脚手架常用形式（`lag` 为时间常数，秒；可来自 `config.json` 的 `camera_follow_lag`）：
+
+```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);
+```
+
+可调轴（改引擎参数，不改规则）：跟随滞后、look-ahead、高度、距离、FOV、近远平面、碰撞/遮挡时的拉近策略。
+
+### 相机与控制一起验
+
+改速度或加速度后，必须复测：
+
+- 高速是否穿模或镜头丢目标
+- 转向是否与 look-ahead 打架
+- 暂停/菜单打开时是否应冻结或解锁指针
+
+## 与 config 的约定
+
+镜头滞后、FOV、是否震屏等可调项进扁平 `public/config.json`（见 `file-structure.md`），禁止在多个相机文件里复制魔法数。