evomeme-dev 0.1.7

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

@@ -0,0 +1,96 @@
+# 引擎：性能
+
+卡顿、掉帧、生成尖峰、移动端低帧时加载。
+
+画像流程与验收证据见 `../game-test`；AAA 渲染预算 / LOD 美术侧见 `../threejs-aaa-graphics-builder/references/technical-art.md`。本文件只管**实现期引擎约束**。
+
+## 优先做的几件事
+
+1. **对象池**：子弹、拾取、碎片、短效 VFX 载体 — 热路径禁止狂 `new` / `dispose` 网格
+2. **共享资源**：重复件用 `InstancedMesh` 或共享 geometry / material / texture
+3. **DPR 上限**：默认 cap `2`（见 `engine-runtime.md` Canvas 配置）；移动端可再降
+4. **热路径零分配**：`useFrame` / simulation 不每帧 `{}` / `new Vector3`；复用临时向量
+5. **物理先减成本**：简单 collider、sleeping、少动态体、窄 sensor；CCD 只给需要的 body（见 `engine-physics.md`）
+
+## 渲染侧
+
+| 手段 | 何时 |
+| --- | --- |
+| `InstancedMesh` | 车道标、螺栓、窗户、草地、碎屑、重复道具 |
+| 共享 geometry/material | clone 实体时勿各自 clone 材质链 |
+| 视锥 / 距离剔除 | 远景与屏外动态体 |
+| `LOD` | 背景件、密集世界套件 |
+| 阴影减负 | 少 caster、小 shadow map、接触阴影/blob 替代 |
+| 后处理限流 | 只保留可读性必需的 pass |
+| 贴图纪律 | 尺寸可控、复用、mipmap；避免同屏大量唯一大贴图 |
+
+优化顺序：**先查 DPR / post / shadow / 实例化 / 剔除**，再砍视觉密度；不要一上来删英雄件可读性。
+
+用户向性能以 **production preview**（`pnpm build` + preview）为准，勿用 dev server 帧率当证据。
+
+## 对象池（3D）
+
+```ts
+// 示意：池内持有已构建的 Object3D + 可选物理 body 句柄
+function acquireBullet(): BulletView {
+  const b = pool.pop() ?? createBulletView();
+  b.root.visible = true;
+  // 启用 collider / 重置 transform
+  return b;
+}
+
+function releaseBullet(b: BulletView): void {
+  b.root.visible = false;
+  // 停 mixer、关 body、摘监听；不要 dispose 共享几何
+  pool.push(b);
+}
+```
+
+重开关卡：归还池内全部活跃实例，再清未池化的关卡专属资源。
+
+## CPU 与降频
+
+- 移动 / 相机 / mixer 每帧；AI、寻路、远距清理可 5–10Hz。
+- 多个 `AnimationMixer` 只更新可见 / 近距实体。
+- DOM HUD 用事件/store 推送，避免每帧强制 React 重渲染整棵树。
+
+## 物理成本（摘要）
+
+- 视觉 mesh ≠ 碰撞体；用原始体 / 复合体。
+- 屏外或休眠体可 sleeping；窄化 sensor。
+- 诊断里暴露 body / collider / CCD / sensor 计数（见 runtime 钩子）。
+
+## 内存与切关
+
+- 换关 dispose：本关独有几何、材质、贴图、render target、mixer、物理 body。
+- 公共材质库 / 共享 atlas 可留。
+- 音频资源清理见 `engine-audio.md`。
+
+## 诊断字段（实现侧）
+
+在 `__THREE_GAME_DIAGNOSTICS__` 中尽量提供：
+
+- `renderer.info`：`render.calls`、`triangles`、`memory.geometries`、`memory.textures`
+- DPR、阴影/后处理开关摘要
+- 实体计数、池大小、活跃 mixer 数
+- 物理（若有）：engine、timestep、bodies、colliders、sensors、ccdBodies
+
+## 快检表
+
+| 症状 | 常因 | 处理 |
+| --- | --- | --- |
+| 越玩越慢 | 未 dispose / 订阅叠加 | 查 restart 与池归还 |
+| 周期性顿 | GC | 池化、减 `useFrame` 分配 |
+| 一直低帧 | draw call / 三角面 / DPR | 实例化、LOD、cap DPR、减 shadow |
+| 生成尖峰 | 当场 new 网格 | 预池 / 预加载 |
+| 物理卡 | body/接触过多 | 简 collider、sleeping、减动态体 |
+| 导入后暴跌 | 重模/大贴图 | 降面、缩贴图（生成侧 + 导入体检） |
+
+## 引擎反模式
+
+- 在未量测前先砍美术细节
+- 用 dev server FPS 当发布性能证据
+- 每帧 new 几何 / 材质 / `Audio`
+- 大量唯一 mesh 本可用 `InstancedMesh`
+- 精细导入 mesh 当碰撞体
+- 移动端不 cap DPR

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

@@ -0,0 +1,142 @@
+# 引擎：物理与碰撞
+
+Three.js / R3F **只负责渲染**；物理是并行世界，固定步长推进后，在一处把 body 变换同步到 `Object3D`。
+
+添加/更换物理、载具、弹珠、刚体、传感器、高速碰撞时加载本文件。玩法向说明可与 `../game-designer/references/physics-engine-selection.md` 对照；**实现以本文件 + `file-structure.md` 分层为准**。
+
+## 选型阶梯
+
+1. **自定义碰撞**：街机触发、拾取、车道、子弹、简单 overlap、确定性轨道；手感靠作者而非仿真。
+2. **Rapier**（`@dimforge/rapier3d-compat`）：默认严肃 3D 物理——刚体、传感器、多接触、高速、球类、斜坡、移动平台、可靠浏览器/移动表现。
+3. **cannon-es**：小规模刚体、希望避开 WASM 时的轻量 JS 回退。
+4. **Jolt**：明确需要其特性且能接受集成成本时再考虑。
+5. **Ammo.js**：仅存量项目或强依赖时；新项目不要默认。
+6. **Matter.js**：仅 2D 玩法（即便用 Three 渲染）。
+
+多数需要「真物理」的新 3D 项目选 Rapier。
+
+## 按类型速查
+
+| 用自定义 | 用 Rapier |
+| --- | --- |
+| 无尽跑酷、车道躲避、简单射击、拾取门 | 迷你高尔夫、台球、弹珠、弹球、物理谜题 |
+| 脚本化障碍、简单球/盒 overlap | 平台、移动平台、斜坡、角色控制器 |
+| 手感定制的赛车护栏 | 碎片堆、箱子、高速需 CCD 的物体 |
+| | 大量 sensor / 碰撞事件 |
+
+避免用精细视觉 mesh 做碰撞：用原始体、复合体、凸包；静态关卡几何才考虑简化三角网。生成 GLB 必须另做 **collision proxy**。
+
+## 本项目中的所有权
+
+| 事项 | 落点 |
+| --- | --- |
+| World / body / collider 创建与销毁 | `game/simulation` 下物理模块，或明确的 `PhysicsWorld` 门面 |
+| 固定步长 `step` | 模拟更新（由 `useFrame` 调进 simulation） |
+| 视觉同步 | `useFrame` 内**唯一**一处：body → `Object3D` |
+| Debug 画 collider | `game/three` 或诊断层；发布关闭 |
+
+禁止：在渲染组件里 `createRigidBody`；多处写 `mesh.position` 与 body 抢所有权；重启后残留 body。
+
+## 更新顺序（含物理）
+
+```text
+input intents → fixed physics step → game state / collision events → VFX / camera / UI → render
+```
+
+## Rapier 接入模式
+
+安装（本仓库包管理为 pnpm）：
+
+```bash
+pnpm add @dimforge/rapier3d-compat
+```
+
+初始化一次后再开玩法：
+
+```ts
+import RAPIER from '@dimforge/rapier3d-compat';
+
+await RAPIER.init();
+const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });
+```
+
+固定步长累加器：
+
+```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;
+  }
+}
+```
+
+刚体 + 碰撞体 + 同步：
+
+```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,
+);
+
+// 唯一同步点
+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);
+```
+
+高速开启 CCD（有成本，只给需要的 body）：
+
+```ts
+RAPIER.RigidBodyDesc.dynamic().setCcdEnabled(true);
+```
+
+传感器 / 触发器：
+
+```ts
+RAPIER.ColliderDesc.ball(1)
+  .setSensor(true)
+  .setActiveEvents(RAPIER.ActiveEvents.COLLISION_EVENTS);
+```
+
+## 实现规则
+
+- 移动平台 / 脚本障碍用 **kinematic** body，视觉与物理一起动。
+- 拾取、终点、检查点、伤害区用 **sensor**。
+- 角色控制器优先胶囊、锁旋转、运动学移动（除非要布娃娃）。
+- 街机载具：不要只靠裸刚体；控制逻辑 + 碰撞响应组合。
+- 使用 sleeping，重启时移除/dispose body，避免陈旧仿真。
+- 调参单位与场景尺度一致；显式设摩擦、恢复、阻尼、质量/密度、重力缩放、碰撞组。
+- Debug：body/collider 计数、接触对、速度；发布构建关闭。
+
+## 验证（物理改动）
+
+- `pnpm build` / 类型检查
+- 真实输入改变 body 状态
+- 碰撞 / 触发路径通
+- 重启无残留 body
+- 高速不隧道穿模
+- 低帧尖峰下仿真不崩
+- 诊断中记录：引擎、步长、body/collider 数、CCD、sensor、危险 collider
+
+## 常见失败
+
+- 变步长物理 → 手感漂
+- 视觉与物理多处同步 → 漂移
+- 重启残留 body
+- 用导入 mesh 碰撞 → 慢且错
+- 高速无 CCD → 穿透
+- Sensor 未开 active events
+- Kinematic 平台只动了 mesh 没动物理

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

@@ -0,0 +1,199 @@
+# 引擎运行时（R3F / Three.js）
+
+本文件为 R3F / Three.js **引擎层**约定（见 `file-structure.md`）。不含策划、关卡、手感 juice 配方。
+
+写/改运行时、Canvas/gl 默认、循环、生命周期、白屏/双循环、dispose、诊断钩子、R3F 加载边界时加载本文件。
+
+## 目录与所有权映射
+
+| 职责 | 本项目落点 |
+| --- | --- |
+| DOM 启动、CSS | `main.tsx` / `App.tsx` / `index.css` |
+| 渲染器、Canvas、像素比 | `ui/components/GameCanvas.tsx`（R3F `<Canvas>`） |
+| 帧循环编排 | `GameCanvas` 的 `useFrame`（勿另起 `requestAnimationFrame`） |
+| 输入采集 → 语义动作 | `game/input` |
+| 规则 / 状态 / 固定步物理 | `game/simulation`（无 Three / React） |
+| 相机、世界网格、mixer | `game/three/*`（无 React）+ `useFrame` 同步 |
+| UI 桥 | `game/bridge` + `src/ui` |
+| 资产键 / 加载 | `game/assets` + `game/three` 加载助手 |
+| 诊断 / 测试钩子 | `GameCanvas` 挂载安装，卸载清理 |
+
+## Canvas / 渲染器默认
+
+**禁止**在 `GameCanvas` 外再 `new THREE.WebGLRenderer`。唯一 WebGL 入口是 R3F `<Canvas>`。
+
+推荐默认（可按项目微调，但须显式设定，勿依赖隐式）：
+
+```tsx
+import { Canvas } from '@react-three/fiber';
+import * as THREE from 'three';
+
+<Canvas
+  shadows
+  dpr={[1, 2]} // 像素比上限 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 编排 */}
+</Canvas>
+```
+
+规则：
+
+- resize / aspect 交给 R3F；勿用 CSS `transform: scale` 假装缩放画布。
+- 阴影：`shadows` + 灯光 `castShadow`；移动端可关或减 cascade（见 `engine-performance.md`）。
+- 色域与 tone mapping 与导入 PBR 一致；过暗/过亮先查这里与环境光，再改资产。
+- 更深的光影/后处理配方属 `threejs-aaa-graphics-builder`，本文件只定启动默认。
+
+## 帧更新顺序
+
+每帧保持显式顺序（R3F 下由 `useFrame` 编排，渲染交给 R3F）：
+
+```text
+input intents
+  → fixed physics（若有，累加器）
+  → gameplay / simulation systems
+  → animation / mixer / VFX sockets
+  → camera
+  → UI bridge（emit 事实 / 写 store）
+  →（R3F 自动 render；除非离屏否则不要手调 renderer.render）
+```
+
+规则：
+
+- `useFrame` 只编排，不写核心胜负/战斗规则。
+- **禁止**第二个活跃的 `requestAnimationFrame` 游戏循环与 R3F 抢渲染。
+- 帧间隔按秒使用；对休眠/卡顿做 clamp（脚手架常用上限约 `0.05`–`0.1` 秒）。
+
+```ts
+// useFrame 内：delta 已是秒；仍建议 clamp
+const dt = Math.min(state.clock.getDelta(), 0.05);
+```
+
+### `useFrame` 优先级（建议）
+
+R3F：`useFrame(fn, priority)` 中 **priority 越大越早执行**；默认 `0`；**负数在默认渲染之后**执行。
+
+| priority | 内容 |
+| --- | --- |
+| `> 0`（如 `1`） | 输入采样 → 固定步物理 → simulation |
+| `0`（默认） | `Object3D` 同步、mixer、VFX socket、相机跟随 |
+| `< 0` | 仅诊断采样 / 需读完帧结果的钩子（可选） |
+
+同一职责不要注册多个互相抢写的 `useFrame`。物理固定步细节见 `engine-physics.md`。
+
+## R3F 政策
+
+### 加载边界
+
+- **正式游戏资产**（GLB/贴图键、失败占位、manifest）：放在 `game/assets` + `game/three` 加载助手；由 `GameCanvas` / 世界根触发一次加载。
+- `useLoader` / `<Suspense>`：仅用于明确的挂载边界原型或局部辅助；**不要**在每个实体组件里各自 `useLoader` 同一 URL 却无统一缓存/dispose 策略。
+- 业务代码不硬编码 glTF URL；走 manifest / `config.json`。
+
+### `@react-three/drei` 白名单
+
+| 可用（谨慎） | 禁止作正式方案 |
+| --- | --- |
+| 开发向 Helpers、轻量环境/HDR 辅助（可关） | `<Html>` 堆正式 HUD / 菜单 / 设置 |
+| 明确需要的 `OrbitControls`（编辑/观察关，玩法关须可关） | 用 drei 控件绕过 `game/input` 语义动作 |
+| | 用 Canvas 内 DOM 替代 `src/ui` |
+
+正式 HUD、虚拟摇杆、设置面板 → React DOM（`src/ui`）。
+
+### 其他
+
+- `game/three/*` **禁止** `import` React / R3F hooks。
+- StrictMode 双挂载：订阅与 WebGL 资源创建必须幂等可清理。
+
+## 首个可运行切片（引擎最小集）
+
+引擎侧先具备这些，再谈内容密度：
+
+1. Canvas + 场景根 + resize / 相机 aspect（含上节 gl/dpr 默认）
+2. 单一更新路径（`useFrame`）
+3. 输入 → 语义动作 → 模拟一步
+4. 至少一个可动实体的 `Object3D` 同步
+5. 碰撞或触发的最小检测（自定义或物理）
+6. 失败/重开时的资源与监听清理
+7. 诊断钩子（见下）
+
+拒绝：只能看不能控；重开后残留实体/监听/物理体；多循环互抢。
+
+## 生命周期与 dispose
+
+StrictMode 会双挂载；卸载必须可重复执行且幂等。
+
+必须清理：
+
+- 几何、材质、纹理（含材质上挂的 map）
+- `AnimationMixer` 与 clip actions
+- 物理 world / body / collider
+- `gameBus` 订阅、DOM / window 监听
+- 诊断与测试钩子（`window.__THREE_GAME_*`）
+- 局内音频 loop / 短效（见 `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();
+    }
+  });
+}
+```
+
+## 诊断钩子
+
+在 `GameCanvas` 挂载时安装、卸载时清理（类型写在 `vite-env.d.ts`）：
+
+- `window.__THREE_GAME_DIAGNOSTICS__`：renderer info、模拟快照、输入状态、实体计数、物理体/碰撞体计数（若有）、DPR/阴影摘要
+- `window.__THREE_GAME_TEST_HOOKS__`：`seed` / `setState` / `setPausedForScreenshot` / `setReducedMotion` / `hideDebugUi`
+
+确定性随机放 `simulation` 或 `lib/random`；业务路径禁止裸 `Math.random`。
+
+## 引擎故障分流（运行时）
+
+| 现象 | 优先检查 |
+| --- | --- |
+| 白屏 / 空画布 | Canvas DOM 与 CSS 尺寸；WebGL 上下文；是否只有一个循环；相机 near/far/朝向；场景是否有可见物体与灯光；overlay 是否盖住 Canvas；resize 是否更新 aspect；色域/曝光是否把物体「隐掉」 |
+| 能进但不能动 | 输入是否产出意图；模拟是否步进；`Object3D` 是否从模拟同步；是否写错层 |
+| 越玩越卡 / 泄漏 | dispose；是否每帧 new 几何/材质/音源；总线订阅是否叠加 → `engine-performance.md` |
+| 重开异常 | 实体、timer、mixer、物理体、监听、音频是否在 restart 路径清理 |
+| 低帧抖动 | delta clamp；物理是否误用变步长；DPR 是否过高 |
+| 无声 | 是否未 unlock AudioContext → `engine-audio.md` |
+
+更细的资产/音频/性能验收清单见 `../game-test`；本文件只保留引擎归属判断。
+
+## 引擎反模式
+
+- 在 `useFrame` 或 HUD 写规则真相
+- 第二套 rAF 循环 + R3F 双渲染；或额外 `new WebGLRenderer`
+- `game/three` import React
+- 用 `<Html>` 替代正式 DOM HUD
+- 实体组件各自 `useLoader` 且无统一 dispose
+- 视觉 mesh 当碰撞体
+- 多处同步物理→视觉变换
+- 重启不 dispose / 不摘监听
+- 可调参数硬编码，不走 `public/config.json`
+- 业务代码硬编码 glTF/贴图 URL（应走 manifest / config）