@fps-games/vfx 0.1.1

package/docs/VFX_LIBRARY_EXECUTION_PLAN.md

@@ -0,0 +1,229 @@
+# VFX 库集成 — 执行方案 (v1)
+
+> 目标:把 `lumber-order` / `lumber-truck` 用到的特效统一进 `fps-vfx-library`(格式见 [`VFX_LIBRARY_PLAN.md`](./VFX_LIBRARY_PLAN.md) 的 `VfxEffectPackage` v1.1);把两个项目各隔离出一个「去特效」版本;用设计好的流程(`@fps/vfx-runtime` + glob 自动发现 + `vfx add`)把特效重新集成回去;做**前后视觉对比测试**,每项目 3 个特效,直到通过再给结论。
+>
+> 本方案基于对照真实代码的实地侦察(特效清单/触发点/去特效改动点/测试手段),所有文件:行引用均来自侦察结果。
+
+---
+
+## 0. 总策略:先在 6 个特效上跑通全链路,再批量铺开
+
+不一上来就迁移全部 23 个特效。**先用每项目 3 个代表性特效把「格式 → 统一进库 → 去特效 → 集成回来 → 前后对比」整条链路跑通**,验证格式与流程没问题后,再规模化迁移其余特效(Phase G)。理由:23 个里 20 个两项目实现不一致、共享基建已分叉(见 §6),全量迁移是高成本的逐个 canonical 裁定;若格式/流程有坑,在 6 个上暴露代价最低。
+
+链路:
+```
+原项目(保留, 作 before 基线)
+    └─(copy)→ 隔离版 ──去特效(service no-op)──集成库(@fps/vfx-runtime + vfx add + glob)──作 after
+                                                                          │
+原项目 before 截图  ───────────────  前后同机位对比(固定相机 + 固定 spawn)  ─── 隔离版 after 截图
+```
+
+---
+
+## 1. 关键决策与假设(先确认)
+
+| 项 | 决策 | 说明 |
+|---|------|------|
+| 格式 | `VfxEffectPackage` v1.1(已定) | 每特效出 `index.ts` 导出 package;data 用薄包装调 `createDataDrivenEffectPackage`,code 手写 `create()`。见 `VFX_LIBRARY_PLAN.md` §4。 |
+| 隔离版形态 | **git 分支**(已定) | 各项目 repo 建分支 `vfx-library-integration`。before = 基线分支(原特效),after = 集成分支。**顺序采集**(先在基线分支采 before,再切集成分支采 after,复用同端口)。 |
+| before 基线来源 | **基线分支当前实现** | 不需要先去特效才能拿 before——before 就是原特效在基线分支跑出来的样子。 |
+| 去特效方式 | **service 边界 no-op**(非删目录) | 单点改动、可编译、可 `git revert`。见 §7。 |
+| canonical 选择 | 项目独有特效取该项目版;**共享特效 `vehicle-exhaust-smoke` 取 order 版**并在两项目都验 | 见 §6。 |
+| 测试触发 | `game.playEffectPackage(id, params, 固定世界坐标)` + 锁相机 | 见 §8。 |
+| 运行 | 必须 `pnpm dev`(debug 面板 / data 特效只在 DEV 编入) | order:3006 / truck:3007;before/after 顺序跑,复用同端口。 |
+
+> 决策已确认(2026-06-26):隔离用 git 分支;6 个测试特效见 §2;先跑 6 个;`vehicle-exhaust-smoke` canonical 取 order 版。
+
+---
+
+## 2. 选定的测试特效(每项目 3 个,共 5 个库包——含 1 个跨项目复用)
+
+刻意覆盖 **code 粒子 / code+mesh+GLB / data manifest / 特殊时机 bespoke / 跨项目复用** 五种情形:
+
+### lumber-order(3)
+
+| 特效 id | 类型 | 现状触发(file:line) | 强制触发(简化测试) |
+|---|---|---|---|
+| `vehicle-exhaust-smoke` | code 粒子,**跟随型** | 顾客卡车进队列即播并挂车 `CustomerTruckQueueSystem.ts:309` | 进场后 `playEffectPackage('vehicle-exhaust-smoke', {}, 固定坐标)`,持续粒子,天然稳定 |
+| `lumber-debris-scatter` | **code + mesh + GLB** | worker 砍倒树 `WorkerAutomationSystem.ts:2170`(GLB `ImportMeshAsync` index.ts:459 + Box fallback :496) | dev 钩子 `setInterval(()=>gameInstance.playEffectPackage('lumber-debris-scatter',{},坐标),2000)`——验证 mesh+GLB 装载路径 |
+| `tree_chop_dust_burst` | **data / manifest** | 仅面板预览(debug-only,无游戏触发) | 面板 Play 或 dev 钩子 `playEffectPackage('tree_chop_dust_burst')`——验证 data adapter 管线 |
+
+### lumber-truck(3)
+
+| 特效 id | 类型 | 现状触发(file:line) | 强制触发(简化测试) |
+|---|---|---|---|
+| `intro-tree-grow-smoke` | **code,bespoke,特殊时机** | 开场进场动画逐行播 `LumberIntroTreeAnimationSystem.ts:304`(`src/vfx/intro-tree-grow-smoke.ts`,**不在注册表**) | 正是用户说的「特殊时机」典型。集成时**封装成 code VfxEffectPackage**;测试用 dev 钩子进场即在固定锚点播/循环 |
+| `wood_crusher_sawdust` | **data / manifest** | 剥皮机加工 `LumberProductionSystem.ts:2346` | 面板 Play 或 dev 钩子 `playEffectPackage('wood_crusher_sawdust',{},坐标)`——data 管线 |
+| `vehicle-exhaust-smoke` | code 粒子,跟随型 | 卡车进队列挂车 `TruckQueueSystem.ts:437` | 同 order——**与 order 复用同一个库包**,顺带验证「一个库包跨两项目复用」 |
+
+**覆盖矩阵**:code 粒子 ✓、code+mesh+GLB ✓、data manifest ✓×2、bespoke 特殊时机 ✓、跨项目复用 ✓(`vehicle-exhaust-smoke` 一个库包两项目用)。
+
+> 去重后实际需要进库的**库包 = 5 个**(`vehicle-exhaust-smoke` 共用):exhaust / lumber-debris-scatter / tree_chop_dust_burst / intro-tree-grow-smoke / wood_crusher_sawdust。
+
+---
+
+## 3. 阶段总览
+
+| 阶段 | 名称 | 产出 | 验收 |
+|---|---|---|---|
+| P0 | 准备 + 基线截图 | 隔离版目录;原项目 6 特效的 before 截图/多帧 | before 资产齐全、机位/spawn 已固定记录 |
+| P1 | 库核心 + 格式落地 | `@fps/vfx-runtime`(抽自 lumber-order,含已打补丁 adapter + glob `buildRegistry`) | 最小宿主能注册并播放 1 data + 1 code 包 |
+| P2 | 统一 5 个测试库包 | `fps-vfx-library/packages/effects/<id>/`(含 index.ts/资源/参数/`?url` 映射)+ `index.json` | `validate-manifest` 通过;5 包 id 唯一 |
+| P3 | 去特效(隔离版) | 两隔离版 service no-op,可编译可运行无特效 | `pnpm dev` 起得来、跑得动、零特效、无报错 |
+| P4 | 集成库回隔离版 | 隔离版装 `@fps/vfx-runtime` + `vfx add` 6 特效 + glob 自动发现 + 面板挂载 | 面板下拉见到 6 特效、能 Play |
+| P5 | 前后视觉对比测试 | 6 特效 before/after 截图对比 + 结论 | 见 §9 验收标准 |
+| P6 | 迭代到通过 | 修问题直到 §9 全绿 | 给最终结论 |
+| G | (后续)规模化 | 迁移其余特效、reconcile 分叉实现 | 不在本轮闭环 |
+
+---
+
+## 4. P0 — 准备 + 基线截图(关键:before 必须先采)
+
+1. **建隔离分支**(每个项目 repo 各建一个 git 分支 `vfx-library-integration`):
+   - `lumber-order-260525`、`lumber-truck` 各 `git checkout -b vfx-library-integration`。
+   - before = 基线分支当前 HEAD(原特效);after = 集成分支。
+   - 不同时跑两分支:**顺序**采集(基线分支采 before → 切集成分支采 after),复用同端口 3006/3007。
+2. **固定测试夹具(两边一致)**:每特效定死 ①视口 1280×720(可选 DPR2)②相机位姿(锁定 `cameraPanService` 不漂移 / 或用相机 debug 面板存一个固定 rig)③`spawnTransform` 固定世界坐标(绕开 playerRight/player 锚点漂移)④触发后到「关键帧」的等待方式(code 取确定性峰值帧;data 取多帧序列)。把这套夹具写成一个**可复用的 dev 钩子 + chrome-devtools 脚本**,before/after 共用。
+3. **采 before**:在**基线分支**(3006/3007,`pnpm dev`)用上述夹具触发并截图:
+   - code 特效(exhaust / debris / intro):单关键帧 `before.png`(确定性,后续可做 diff)。
+   - data 特效(tree_chop_dust_burst / wood_crusher_sawdust):多帧 `before-f01..f05.png`(非确定性)。
+   - 落盘:`benchmark-results/vfx-ab/<project>/<id>/before*.png`(沿用项目已有 `benchmark-results/ab-*` 命名惯例)。
+4. 记录每特效的夹具参数(相机 rig / spawn 坐标 / 帧时刻)到一个 `fixtures.json`,after 阶段原样复用。
+
+> ⚠️ before 必须在任何改动前采;intro-tree-grow-smoke 的 before 走其现有 `playIntroTreeGrowSmoke`,在同一固定锚点触发。
+
+---
+
+## 5. P1 — 库核心 + 格式落地
+
+按 `VFX_LIBRARY_PLAN.md` §4–§7 抽取 `@fps/vfx-runtime`。**重点是吸收 lumber-order 已经打过的补丁,而非照搬旧库**:
+
+1. 从 `lumber-order-260525` 抽:`types.ts`(含 `VfxEffectHandle.ready?`)、`EffectPackageService.ts`、`SceneVfxService.ts`、`rendering.ts`、`manifestRuntimePackage.ts`(→ 改名导出 `createDataDrivenEffectPackage`)、已打补丁的 `adapters/*.v1.js`(读 `emitter.origin`,**非旧库世界原点版**)、通用面板 `runtime-vfx-debug-panel.ts`。
+2. 写 `buildRegistry`(纯函数,放库里;glob 调用留项目侧,见 `VFX_LIBRARY_PLAN.md` §6.3)。
+3. reconcile 共享基建分叉:`types.ts` / `manifestRuntimePackage.ts` / `wood-sawdust-effect-factory.ts` 两项目已 diff,选 lumber-truck 较新的运行时特性(`runtimeModules` / `debarker` 锚点)与 lumber-order 的 `VfxParamsFile`/`ready` 合并成单一版本。
+4. **验收**:最小 Babylon 宿主里注册并播放「1 个 data 包(tree_chop_dust_burst) + 1 个 code 包(vehicle-exhaust-smoke)」,各调一个参数生效、定位正确(data 不落世界原点)。
+
+---
+
+## 6. P2 — 统一 5 个测试库包进 fps-vfx-library
+
+**这不是机械复制**(侦察结论:23 特效里 20 个两项目 `index.ts` 实现不一致)。对 5 个测试包逐个定 canonical:
+
+| 库包 id(规范化) | canonical 来源 | 类型 | 要点 |
+|---|---|---|---|
+| `vehicle.code.exhaust_smoke` | **lumber-order 版**(已定),**两项目都要 after 验** | code | 跟随逻辑用 `root.getWorldMatrix()`;库包只定位、跟随由宿主 reparent。truck 的 after 会与其旧版略有差异,属复用验证范畴 |
+| `resource.code.lumber_debris_scatter` | lumber-order 版 | code+mesh+GLB | GLB 资源需 `?url` 打包;Box fallback 保留 |
+| `tree.particle.chop_dust_burst` | 现 data 版(两项目同源美术) | data | 薄包装 + `?url` 贴图映射;adapter 读 `emitter.origin` |
+| `tree.code.intro_grow_smoke` | lumber-truck `src/vfx/intro-tree-grow-smoke.ts` | code(bespoke) | **封装**:把独立模块包成 `VfxEffectPackage`(加 `create()`/`debugParams`),纳入 playEffectPackage 通道 |
+| `build.particle.wood_crusher_sawdust` | 现 manifest 版(淘汰 legacy 工厂版 `wood-crusher-sawdust`) | data | 同源双实现去重(见下) |
+
+**统一时必须处理的冲突**(侦察发现):
+- `wood_crusher_sawdust`(manifest)与 `wood-crusher-sawdust`(legacy 工厂)内部 manifest id 相同 → **合并,保留 manifest 版**。
+- id 与目录名不一致(如 `run-footstep-dust` 目录 → id `build.particle.run_footstep_dust`)→ 以 id 为准。
+- kebab vs snake 混用 → 规范化 `category.type.snake_name`(本轮 5 个先规范化,其余 Phase G)。
+- 每个 data 包按 `VFX_LIBRARY_PLAN.md` §4.5 配 `?url` 资产映射、替换为已打补丁运行时 js。
+
+产出:5 个 `packages/effects/<id>/` + `generate-index` 出 `index.json` + `validate-manifest`(含 id 跨包唯一)。
+
+> 注:旧库现有 6 个 Cocos 数据包与项目特效**无 id 重叠、仅语义相近**,本轮不强行对齐,留 Phase G。
+
+---
+
+## 7. P3 — 去特效(隔离版,service no-op 单点)
+
+目标:隔离版可编译、可运行、完全不播特效、可回滚。**保留 `types.ts` 与 `index.ts` barrel**(被大量 import,删目录会引发大面积编译错误)。
+
+### lumber-order-vfxlib
+- `src/services/EffectPackageService.ts:71` `playEffectPackage(...)` → 首行 `return null`(最深卡点,production+scene+面板全灭)。
+- `src/core/Game.ts:232-235` `initFromConfig()` 不调用;`:262` `warmupRuntimeVfx()` no-op/不调用;`new`/`dispose` 保留无害。
+- 各 System 调用点(`MoneyDropSystem.ts:331`、`UnlockSystem.ts:304`、`CustomerTruckQueueSystem.ts:309`、`WorkerAutomationSystem.ts:566/781/1218/2142/2170/2183`、`PlayerFootstepDustSystem.ts:70`)**全部不动**(靠 no-op 返回 null;API 本就 `| null` 已守卫)。
+- 3 个 VFX debug 面板(`main.ts:524/740/764`)可留(预览走 no-op 不报错)。
+
+### lumber-truck-vfxlib
+- `src/services/SceneVfxService.ts:199` `playEffectPackage(...)` → 首行 `return null`;`:162 initFromConfig`/`:181 prewarm`/`:188 prewarmDelayed` 各自首行早退。
+- `src/core/Game.ts:205-208` 不调用 init/prewarm 三行;`new`/`dispose` 保留。
+- System 调用点(`LumberUpgradeVfxSystem.ts:47`、`TruckQueueSystem.ts:437`、`LumberSceneVisibilitySystem.ts:259/312/436`、`LumberVehicleAnimationSystem.ts:287`、`LumberProductionSystem.ts:2346/3534/3550/3567/3586`、`Lumber3CSystem.ts:1331`)不动。
+- **特例 intro-tree-grow-smoke**:它不走 playEffectPackage,需单独让 `LumberIntroTreeAnimationSystem.ts:304` 的 `playTreeGrowSmoke` no-op(否则去特效不彻底)。
+
+**验收**:两隔离版 `pnpm dev`(3016/3017)能进游戏、能玩、**画面无任何特效**、控制台无报错;`git diff` 仅集中在上述 service/Game 文件,可一键回滚。
+
+---
+
+## 8. P4 — 集成库回隔离版
+
+1. 隔离版安装 `@fps/vfx-runtime`(workspace `file:` 链接或 pnpm workspace 引用)。
+2. **撤掉 P3 的 no-op**?否——P3 是「移除项目自带特效系统」,P4 是「换成库的运行时」。具体:把隔离版的 `src/services/SceneVfxService`/`EffectPackageService` 替换为对 `@fps/vfx-runtime` 的封装(保留 `Game` 期望的 `new(scene)`/`initFromConfig()`/`dispose()` 钩子),`playEffectPackage` 转发到库。
+3. `vfx add` 把 5 个库包复制进隔离版 `src/assets/vfx/effects/<id>/`(exhaust 两项目都加)。
+4. 项目侧 `src/assets/vfx/index.ts` 改成 glob 自动发现(`import.meta.glob('./effects/*/index.ts', {eager:true})` + `buildRegistry`),**不手动注册**。
+5. 面板:沿用各自现有 VFX 面板(已在 DEV 自动挂载),确认下拉能列出 5 特效。
+6. intro-tree-grow-smoke:把 `LumberIntroTreeAnimationSystem` 的触发改为调 `playEffectPackage('tree.code.intro_grow_smoke', ...)`(从直接 import bespoke 模块切到库包)。
+
+**验收**:两隔离版 `pnpm dev`,VFX 面板下拉见到对应特效,点 Play 能在固定锚点播放。
+
+---
+
+## 9. P5 — 前后视觉对比测试
+
+### 工具
+- **chrome-devtools MCP**(`navigate_page` / `evaluate_script` / `resize_page` / `take_screenshot`),比 claude-in-chrome 更适合固定机位可复现截图;与项目已有 `scripts/benchmark-frame-time.mjs`(原生 CDP)一脉相承。
+
+### 流程(每特效)
+1. `resize_page` 1280×720(可选再做 DPR2)。
+2. `navigate_page` 到 after(隔离版 3016/3017);轮询 `!!window.gameInstance`(order)/`!!window.game`(truck)就绪。
+3. 用 P0 记录的 `fixtures.json` **复用完全相同的相机位姿 + spawn 坐标 + 帧时刻**。
+4. `evaluate_script` 触发:order `window.gameInstance.playEffectPackage(id,params,固定坐标)`;truck `window.playEffectPackage(id,params,固定坐标)`。
+5. 等到关键帧 → `take_screenshot` → 落 `after*.png`。
+
+### 对比方法(按确定性分流)
+- **code 特效**(exhaust / debris / intro,确定性黄金分割序列):单关键帧 **逐像素 diff**(`before.png` vs `after.png` → `diff.png`),阈值内即视为一致。
+- **data 特效**(tree_chop_dust_burst / wood_crusher_sawdust,Babylon `Math.random` ~24 处,非确定性):**多帧序列 + 人工视觉对比 + 可选 SSIM**(下采样后结构相似度),比对覆盖范围/色调/爆发包络/时长,不做逐像素。
+
+### 产物
+```
+benchmark-results/vfx-ab/<project>/<id>/
+    before.png / after.png / diff.png        # code 特效
+    before-f0x.png / after-f0x.png           # data 特效多帧
+```
+最后生成一页对比汇总(并排缩略图 + 判定)。
+
+### 验收标准(全绿才算 OK)
+1. 两隔离版集成后能 `pnpm dev` 进游戏、无运行时报错。
+2. 5 个库包都能经面板/`playEffectPackage` 触发,定位正确(data 不落世界原点,§4.5 风险已规避)。
+3. code 特效 diff 在阈值内(视觉等同);data 特效多帧人工对比「视觉等同/可接受」。
+4. `vehicle-exhaust-smoke` 在**两个项目**都通过(证明跨项目复用)。
+5. mesh+GLB(lumber-debris-scatter)、bespoke(intro)两条特殊路径均正常。
+
+---
+
+## 10. P6 — 迭代到通过 + 结论
+
+按 §9 逐项核对;不过的:定位问题(多半落在 §11 风险点)→ 修 `@fps/vfx-runtime` 或库包配置 → 重测该特效。全绿后给结论:哪些特效一致、哪些有可接受差异、根因与修复、流程是否可推广到全量。
+
+---
+
+## 11. 风险与对策(均来自代码侦察)
+
+| 风险 | 影响 | 对策 |
+|---|---|---|
+| 旧库 adapter 粒子落世界原点、不建 root | data 特效失位 | 用 lumber-order **已打补丁** adapter(读 `emitter.origin`),P1 就并入 |
+| data 类不导出 setPosition、不跟随 | exhaust 若做成 data 会不跟车 | exhaust 用 **code 类**(本就如此);data 仅一次性定位 |
+| mesh 特效 `fetch()` GLSL + 自建 root | data-mesh 着色器 404/失位 | 着色器 `?url` 打包;本轮 mesh 用 code 版(lumber-debris-scatter)规避 |
+| data 特效贴图靠 `urlForPackagePath` + 旧库是 `gs://` | 贴图 404 | 每包 `index.ts` 用 `?url` 显式映射 packagePath |
+| data 特效 `Math.random` 非确定性 | 逐像素 diff 假阳性 | data 走多帧/SSIM/人工,不做像素 diff |
+| debug-only/data 特效只在 dev 编入 | prod 测不到 | 全程 `pnpm dev` |
+| 23 特效 20 个实现分叉 + 共享基建分叉 | 全量统一成本高 | 本轮只统一 5 个;全量留 Phase G 逐个 reconcile |
+| 相机每帧跟玩家漂移 | 前后机位不一致 | 锁 `cameraPanService` / 存固定 rig + 固定 spawn 坐标 |
+| intro 不走 playEffectPackage | 去特效/集成易漏 | 单独 no-op 其触发 + 集成时封装成库包并改触发 |
+
+---
+
+## 12. 已确认决策(2026-06-26)
+
+1. 隔离版形态:**git 分支**(各项目 repo 建 `vfx-library-integration`)。
+2. 6 个测试特效(§2):**认可**。
+3. 分阶段:**先在 6 个特效跑通(P0–P6),其余留 Phase G**。
+4. `vehicle-exhaust-smoke` canonical:**取 lumber-order 版**(两项目都验 after)。
+
+---
+
+*本执行方案配合 [`VFX_LIBRARY_PLAN.md`](./VFX_LIBRARY_PLAN.md)(格式与运行时设计)使用。先验证、再规模化。*