evomeme 0.1.9 → 0.1.10-beta.13

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

@@ -1,116 +0,0 @@
-# 引擎：资产加载与动画管线
-
-关注 **运行时如何安全接入 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 |