@fps-games/vfx 0.1.1

package/docs/vfx-integration_chatgpt.md

@@ -0,0 +1,462 @@
+# 特效系统集成文档（VFX Integration）
+
+本文档面向无法直接访问代码库的工程师，描述项目中视觉特效（VFX）系统的整体架构、核心接口、完整调用链路，以及新增特效的标准步骤。渲染基于 Babylon.js（`SpriteManager` / `ParticleSystem`）。文中代码片段均摘自真实代码（个别处为突出主干有删减）。
+
+## 1. 架构总览
+
+特效系统分为四层：**特效包定义 → 服务层 → 触发层 → 驱动与销毁**。
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 特效包定义层  src/assets/vfx/                             │
+│   每个特效一个自包含目录：实现 + 参数 + 贴图                │
+│   在注册表中登记后即可被全局按 ID 调用                      │
+└─────────────────────────────────────────────────────────┘
+                          ↓ 注册（编译期）
+┌─────────────────────────────────────────────────────────┐
+│ 服务层  src/services/                                     │
+│   SceneVfxService（门面） → EffectPackageService（核心）   │
+│   负责：查包、参数合并、建 root 节点、追踪活跃 handle       │
+└─────────────────────────────────────────────────────────┘
+                          ↓ 依赖注入（Game.init → gameplay）
+┌─────────────────────────────────────────────────────────┐
+│ 触发层  src/systems/                                      │
+│   各 gameplay System 在 update() 中调用                   │
+│   sceneVfxService.playEffectPackage(id, params, spawn)   │
+└─────────────────────────────────────────────────────────┘
+                          ↓ 返回 VfxEffectHandle
+┌─────────────────────────────────────────────────────────┐
+│ 驱动与销毁                                                │
+│   每帧：scene.onBeforeRenderObservable（特效内部自驱动）   │
+│   销毁：handle.dispose() / 超时定时器 / 场景卸载兜底        │
+└─────────────────────────────────────────────────────────┘
+```
+
+数据流：**配置（json/tuning） → 加载（注册表） → 触发（System） → 更新（Babylon 帧回调） → 销毁（handle.dispose）**。
+
+设计上的两个核心约定：
+
+- **特效包对宿主零感知**：特效只拿到一个 `root: TransformNode`，不知道也不关心自己挂在谁身上；跟随、定位全靠调用方操作 root。
+- **统一参数模型**：所有特效参数是一个扁平字典，支持五层来源合并（默认值 → 落盘参数 → 调试覆盖 → 运行时传参），同一套参数同时服务于运行时调用和调试面板调参。
+
+## 2. 核心接口
+
+整个系统围绕三个接口运转（定义于 `src/assets/vfx/types.ts`）：
+
+```typescript
+/** 一个特效包：自包含、可注册、可参数化 */
+export interface VfxEffectPackage<PParams extends VfxParamValues = VfxParamValues> {
+  id: string;                              // 全局唯一 ID，如 'vehicle-exhaust-smoke'
+  nameZh: string;                          // 中文名，如 '小车尾气'
+  manifest?: VfxEffectManifest;            // 元数据（来自 effect.json）
+  defaultParams: PParams;                  // 代码内默认参数（全量）
+  savedParams?: Partial<VfxParamValues>;   // 编辑器保存参数（来自 vfx-params.json）
+  debugParams: VfxParamDefinition[];       // 调试面板控件定义（滑杆/颜色/枚举）
+  debugAnchor?: VfxDebugAnchor;            // 调试预览时的锚点（'player' 等）
+  spawnParams?: VfxSpawnParamKeys;         // 生成偏移参数的 key 映射（可选）
+  create(context: VfxEffectPackageContext<PParams>): VfxEffectHandle;  // 工厂方法
+}
+
+/** create() 收到的上下文 */
+export interface VfxEffectPackageContext<PParams> {
+  scene: Scene;                 // Babylon 场景
+  root: TransformNode;          // 服务层已建好的根节点（位置/朝向已设置）
+  position: Vector3;            // 世界坐标生成位置
+  rotationY: number;            // Y 轴朝向
+  renderingGroupId?: number;    // 渲染组（不传则用 VFX 默认组）
+  params: PParams;              // 合并完成的最终参数
+}
+
+/** create() 的返回值：调用方拿到的控制句柄 */
+export interface VfxEffectHandle {
+  root: TransformNode;          // 可被 reparent 实现跟随
+  dispose(): void;              // 销毁特效及其全部资源
+}
+```
+
+参数值类型刻意收窄为三种，保证能被 JSON 落盘和调试面板编辑：
+
+```typescript
+export type VfxParamValue = number | string | VfxColorValue;   // VfxColorValue = { r, g, b }
+export type VfxParamValues = Record<string, VfxParamValue>;
+```
+
+`create()` 返回 `{ root, dispose }` 是整个系统的核心契约：调用方**只能**通过这两个成员与特效交互——用 root 控制空间关系，用 dispose 结束生命周期，没有第三种通道。
+
+## 3. 特效包定义层（`src/assets/vfx/`）
+
+### 3.1 目录结构
+
+每个特效是一个自包含目录，以卡车尾气为例：
+
+```
+src/assets/vfx/effects/vehicle-exhaust-smoke/
+├── index.ts          # 特效实现：导出一个 VfxEffectPackage 对象
+├── vfx-params.json   # 调试面板调好后保存的参数（覆盖代码默认值）
+├── effect.json       # 元数据 manifest（id / 中文名 / 资源清单）
+└── assets/textures/  # 贴图资源（如 128x128 x 4 帧的烟雾图集）
+```
+
+### 3.2 注册表（`src/assets/vfx/index.ts`）
+
+新特效必须在注册表登记三处，之后即可在全项目按 ID 调用：
+
+```typescript
+// ① import 特效包对象和它的参数文件
+import { vehicleExhaustSmokeEffectPackage } from './effects/vehicle-exhaust-smoke';
+import vehicleExhaustSmokeParams from './effects/vehicle-exhaust-smoke/vfx-params.json';
+
+// ② 加入特效包数组
+export const VFX_EFFECT_PACKAGES: VfxEffectPackage[] = [
+  /* ... 其他特效 ... */
+  vehicleExhaustSmokeEffectPackage,
+];
+
+// ③ 登记落盘参数（key 为特效 ID）
+export const VFX_EFFECT_SAVED_PARAMS: VfxDebugOverrides = {
+  /* ... */
+  'vehicle-exhaust-smoke': sanitizeParamsFile(vehicleExhaustSmokeParams),
+};
+```
+
+模块加载时注册表自动把 `savedParams` 回写到每个包对象上，并生成按 ID 索引的 `VFX_EFFECT_PACKAGE_MAP`。
+
+### 3.3 统一渲染配置（`src/assets/vfx/rendering.ts`）
+
+- `VFX_RENDERING_GROUP_ID = 2`：所有特效默认走独立渲染组，与场景物体分层。
+- `configureVfxSpriteManager()` / `configureVfxParticleSystem()`：统一关闭深度写入等设置。特效实现内创建 SpriteManager / ParticleSystem 后必须调用，保证全部特效渲染行为一致。
+
+## 4. 服务层（`src/services/`）
+
+### 4.1 两个类的分工
+
+- **SceneVfxService**（门面，`src/services/SceneVfxService.ts`）：对外统一入口。构造时内部创建 EffectPackageService 并转发 `playEffectPackage()`。另外支持从 `scene.json` 的 `tuning.sceneVfx` 配置创建**场景级常驻粒子**（环境氛围类，与特效包系统并行存在，走 `initFromConfig()`）。
+- **EffectPackageService**（核心，`src/services/EffectPackageService.ts`）：真正执行查包、参数合并、创建、追踪、销毁。
+
+### 4.2 播放一个特效时发生了什么
+
+调用方只看到一个方法：
+
+```typescript
+playEffectPackage(
+  effectId: string,                              // 特效 ID
+  explicitParams?: Partial<VfxParamValues>,      // 运行时参数覆盖（只传需要改的）
+  spawnTransform?: VfxSpawnTransform | Vector3,  // 位置；或 { position, rotationY?, renderingGroupId? }
+): VfxEffectHandle | null
+```
+
+内部执行五步（摘自 EffectPackageService，有删减）：
+
+```typescript
+playEffectPackage(effectId, explicitParams?, spawnTransform?) {
+  // ① 查包：查不到打 warn 返回 null，不崩溃
+  const effectPackage = this.getEffectPackage(effectId);
+  if (!effectPackage) { console.warn(`Unknown VFX effect package: ${effectId}`); return null; }
+
+  // ② 参数合并（五层，后者覆盖前者，见 4.3）
+  const params = this.getMergedParams(effectId, explicitParams);
+
+  // ③ 建 root 节点，应用位置/朝向/生成偏移
+  const spawn = this.resolveSpawnTransform(effectPackage, params, spawnTransform);
+  const root = new TransformNode(`vfx_package_${effectId}`, this.scene);
+  root.position.copyFrom(spawn.position);
+  root.rotation.y = spawn.rotationY;
+
+  // ④ 调特效包的工厂方法
+  const handle = effectPackage.create({ scene: this.scene, root, /* position, rotationY, renderingGroupId, params */ });
+
+  // ⑤ 追踪 handle，并包装 dispose 使销毁时自动从追踪集合移除
+  this.activeHandles.add(handle);
+  const originalDispose = handle.dispose.bind(handle);
+  handle.dispose = () => {
+    this.activeHandles.delete(handle);
+    originalDispose();
+  };
+  return handle;
+}
+```
+
+`activeHandles: Set<VfxEffectHandle>` 是场景卸载时兜底清理的依据——`dispose()` 遍历销毁所有还活着的特效，杜绝泄漏。
+
+### 4.3 参数合并的五层优先级
+
+`getMergedParams()` 按以下顺序 `Object.assign`，**后者覆盖前者**：
+
+```
+① VFX_DEFAULT_GENERATION_PARAMS     生成偏移参数（__generation.offsetX/Y/Z，默认 0）
+② effectPackage.defaultParams       代码内默认值（全量兜底）
+③ effectPackage.savedParams         vfx-params.json（调试面板落盘的"美术定稿"）
+④ 运行时调试面板覆盖                  本次会话内临时调参
+⑤ explicitParams                    调用方传入（最高优先级）
+```
+
+实际效果：美术在调试面板里调好的参数自动生效（③），游戏逻辑只需要覆盖与上下文相关的少数参数（⑤，如喷烟方向），互不干扰。
+
+### 4.4 接线：服务的创建与注入
+
+启动链路（`src/core/Game.ts` → `src/gameplay/createProjectGameplay.ts`）：
+
+1. `Game.init()` 创建 `SceneVfxService` 并调 `initFromConfig()`；
+2. 服务实例放进 gameplay context；
+3. `createProjectGameplay.ts` 构造各 System 时以构造参数注入（CustomerTruckQueueSystem、UnlockSystem、WorkerAutomationSystem、PlayerFootstepDustSystem 等）；
+4. Game 对外也暴露一个 `playEffectPackage()` 便捷入口；
+5. `Game.dispose()` 时调用 `sceneVfxService.dispose()` 兜底清理。
+
+System 一律持有注入的服务实例，不自己 import 单例——便于测试和场景切换。
+
+## 5. 触发层：游戏逻辑如何播特效
+
+### 5.1 典型触发点
+
+| 特效 | 触发方（src/systems/ 下） | 模式 |
+|---|---|---|
+| `run-footstep-dust` 脚步灰尘 | PlayerFootstepDustSystem | 移速超阈值时周期触发 |
+| `vehicle-exhaust-smoke` 卡车尾气 | CustomerTruckQueueSystem | 持续型，挂载跟随 |
+| `player-upgrade` NPC 升级金光 | WorkerAutomationSystem | 一次性，参数来自 tuning 文件 |
+| `resource-collect-sparkles` 收集火花 | MoneyDropSystem | 一次性，全默认参数 |
+| `ground-tile-upgrade` 区域解锁 | UnlockSystem | 一次性，参数按区域尺寸动态计算 |
+
+### 5.2 一次性特效：最简调用
+
+钱币到达支付区时播收集火花（摘自 MoneyDropSystem）：
+
+```typescript
+this.sceneVfxService?.playEffectPackage(
+  'resource-collect-sparkles',
+  undefined,            // 不覆盖任何参数，全部用默认/落盘值
+  arrivalPosition,      // 直接传 Vector3 作为生成位置
+);
+// 不保留 handle：特效播完自动 dispose 自己
+```
+
+带参数覆盖的版本（摘自 PlayerFootstepDustSystem，玩家奔跑时的灰尘）：
+
+```typescript
+const handle = this.sceneVfxService.playEffectPackage(
+  'run-footstep-dust',
+  {
+    emitMode: 'timed',
+    lifetime: 0.18,
+    directionX, directionZ,        // 与移动方向相关，只能运行时算
+  },
+  { position, renderingGroupId },
+);
+```
+
+### 5.3 持续跟随型特效：reparent 模式
+
+这是持续型特效的标准写法，以卡车尾气为范例（摘自 CustomerTruckQueueSystem）。要点：先按世界坐标播放，再把返回的 `handle.root` 重新挂到目标节点下、改为局部偏移：
+
+```typescript
+private startExhaustSmoke(node: TransformNode): VfxEffectHandle | null {
+  const handle = this.sceneVfxService?.playEffectPackage(
+    'vehicle-exhaust-smoke',
+    { directionX: 0, directionZ: -1 },     // 只覆盖喷烟方向
+    {
+      position: node.getAbsolutePosition().add(EXHAUST_LOCAL_OFFSET),
+      rotationY: node.rotation.y,
+      renderingGroupId: resolveNodeRenderingGroupId(node, OFFSET),
+    },
+  ) ?? null;
+  if (!handle?.root) return handle;
+
+  handle.root.parent = node;                          // 关键：挂到卡车节点下
+  handle.root.position.copyFrom(EXHAUST_LOCAL_OFFSET); // 世界坐标 → 局部偏移
+  handle.root.rotation.y = 0;
+  return handle;
+}
+```
+
+之后卡车移动/转向，尾气自动跟随——特效内部每次发射烟团时用 `root.getWorldMatrix()` 把局部方向变换到世界空间，所以卡车转弯时喷烟方向也自动正确。特效完全不知道宿主的存在，这就是第 1 节说的"对宿主零感知"。
+
+调用方保留 handle，在宿主回收时负责销毁：
+
+```typescript
+private recycleTruck(truck: TruckRecord): void {
+  truck.exhaustHandle?.dispose();
+  truck.exhaustHandle = null;
+  /* ... 其他回收逻辑 ... */
+}
+```
+
+## 6. 特效内部实现模式
+
+以尾气（`src/assets/vfx/effects/vehicle-exhaust-smoke/index.ts`）为代表，一个特效包实现包含五个部分：
+
+### 6.1 参数接口与默认值
+
+```typescript
+interface VehicleExhaustSmokeParams extends VfxParamValues {
+  lifetimeMode: string;        // 'infinite' | 'duration'
+  scale: number;
+  color: VfxColorValue;
+  particleCount: number;
+  driftSpeed: number;
+  directionX: number;
+  directionZ: number;
+  /* ... 共 14 个参数 ... */
+}
+
+const DEFAULT_PARAMS: VehicleExhaustSmokeParams = {
+  lifetimeMode: 'infinite',
+  scale: 1.35,
+  particleCount: 82,
+  /* ... 全量默认值 ... */
+};
+```
+
+### 6.2 debugParams：调试面板控件即代码
+
+每个参数声明一个控件定义，调试面板据此自动生成 UI：
+
+```typescript
+debugParams: [
+  { key: 'lifetimeMode', label: '生命周期模式', kind: 'enum',
+    options: [{ value: 'infinite', label: '无限' }, { value: 'duration', label: '自定义时间' }] },
+  { key: 'scale', label: '整体缩放', kind: 'scale', min: 0.05, max: 8, step: 0.01 },
+  { key: 'color', label: '尾气颜色', kind: 'color' },
+  { key: 'particleCount', label: '粒子数量', kind: 'number', min: 1, max: 180, step: 1 },
+  /* ... */
+],
+```
+
+调完保存即落盘到该特效的 `vfx-params.json`，下次启动自动生效（参数合并第 ③ 层）。
+
+### 6.3 create()：工厂方法骨架
+
+```typescript
+create({ scene, root, position, renderingGroupId, params }) {
+  root.position.copyFrom(position).addInPlace(/* 初始高度偏移 */);
+  const smokeTrail = createExhaustSpriteTrail(scene, root, params, renderingGroupId);
+
+  // 'infinite' 模式不设定时器，依赖外部 dispose；'duration' 模式超时自动清理
+  const durationSeconds = readDurationSeconds(params);   // infinite → null
+  const disposeTimer = durationSeconds == null
+    ? 0
+    : window.setTimeout(() => disposeAll(), getDisposeDelaySeconds(params) * 1000);
+
+  return {
+    root,
+    dispose() { disposeAll(); },
+  };
+
+  function disposeAll() {
+    if (disposed) return;
+    disposed = true;
+    if (disposeTimer) window.clearTimeout(disposeTimer);
+    smokeTrail.dispose();   // 摘帧观察器、销毁全部 sprite 和 SpriteManager
+    root.dispose();
+  }
+}
+```
+
+### 6.4 每帧驱动与内部精灵池
+
+特效不依赖游戏的 tick，直接挂 Babylon 的帧回调自驱动：
+
+```typescript
+const observer = scene.onBeforeRenderObservable.add(() => {
+  const deltaSeconds = Math.min(0.05, scene.getEngine().getDeltaTime() / 1000);
+
+  // 按发射间隔从池里取空闲 sprite 生成新烟团
+  emitAccumulator += deltaSeconds;
+  while (emitAccumulator >= emitInterval) {
+    emitAccumulator -= emitInterval;
+    const state = findAvailableState(states);   // 找 active === false 的复用
+    if (!state) break;
+    spawnPuff(state, emissionIndex++);
+  }
+
+  // 更新所有活跃烟团：位移、旋转、放大、淡入淡出
+  for (const state of states) {
+    if (!state.active) continue;
+    state.age += deltaSeconds;
+    const t = Math.min(1, state.age / state.lifetime);
+    /* ... alpha = 淡入 × 淡出, size = base × (1 + t × 1.45) ... */
+    if (t >= 1) state.active = false;           // 寿命结束归还池子
+  }
+});
+```
+
+两个值得注意的实现约定：
+
+- **内部精灵池**：持续型特效一次性创建 `particleCount` 个 Sprite，用 `active` 标志循环复用，运行期间零分配。handle 层面没有池化（每次 play 都新建），但特效内部应当池化。另有 warm start：创建时先点燃几团烟，避免宿主出场瞬间特效是空的。
+- **确定性随机**：不用 `Math.random()`，用黄金分割步进序列 `sequence01(seed, axis)` 生成抖动，同样的输入产生同样的画面，便于回归对比。
+
+### 6.5 dispose：必须释放的清单
+
+```typescript
+function dispose(): void {
+  scene.onBeforeRenderObservable.remove(observer);   // ① 帧观察器
+  for (const state of states) state.sprite.dispose(); // ② 全部 sprite
+  manager.dispose();                                  // ③ SpriteManager（含贴图）
+}
+// 外层 disposeAll 再清掉定时器并 root.dispose()        // ④⑤
+```
+
+帧观察器、Sprite/ParticleSystem、SpriteManager、贴图、root 节点，五样缺一不可，否则泄漏。
+
+## 7. 生命周期：三条销毁路径
+
+1. **手动**：调用方持有 handle，宿主结束时 `handle.dispose()`（如卡车驶出地图回收时销毁尾气）。
+2. **超时**：一次性特效内部 `setTimeout` 自动清理；或调用方侧定时（如区域解锁特效 3.6 秒后清理）。
+3. **兜底**：`Game.dispose()` → `SceneVfxService.dispose()` → `EffectPackageService.dispose()` 遍历 `activeHandles` 全部销毁。
+
+由于服务层包装过 dispose（见 4.2 第⑤步），任何一条路径触发后 handle 都会从追踪集合自动移除，重复调用 dispose 也安全（特效内部有 `disposed` 标志防重入）。
+
+## 8. 配置与调参工作流
+
+- **专项 tuning 文件**（`src/config/` 下）：复杂特效的参数集中在独立配置文件，带默认值与 sanitize 校验函数，游戏逻辑取参后传入 `playEffectPackage()`。例如 NPC 升级特效（19 个参数）、区域解锁特效、生成缩放动画、资源收集特效各有一个 tuning 文件。
+- **场景级配置**：`scene.json` 的 `tuning.sceneVfx` 用于常驻环境粒子，由 `SceneVfxService.initFromConfig()` 加载，按 `effects → systems` 两级结构定义发射器位置与粒子系统。
+- **调试面板**（`src/debug/` 下）：
+  - 通用 VFX 面板：选任意特效包预览，按 `debugParams` 生成滑杆实时调参；
+  - 另有 NPC 升级、区域解锁两个专用面板；
+  - 会话内调参属于参数合并第 ④ 层；确认后落盘到特效包的 `vfx-params.json`（第 ③ 层），随代码提交。
+- **编辑器适配层**（`src/fps-game-editor-adapter/`）与特效系统基本解耦，无直接集成。
+
+## 9. 新增特效的标准步骤
+
+1. 在 `src/assets/vfx/effects/<effect-id>/` 创建目录：
+   - `index.ts` — 导出 `VfxEffectPackage` 对象：定义参数接口、`DEFAULT_PARAMS`、`debugParams`，实现 `create(context)` 返回 `{ root, dispose }`；
+   - `vfx-params.json` — 初始可只含生成偏移，后续由调试面板写入；
+   - `effect.json` — manifest 元数据；
+   - `assets/textures/` — 贴图。
+2. 在 `src/assets/vfx/index.ts` 登记三处：import、`VFX_EFFECT_PACKAGES`、`VFX_EFFECT_SAVED_PARAMS`（见 3.2 的代码示例）。
+3. 实现注意事项：
+   - SpriteManager / ParticleSystem 创建后调 `configureVfxSpriteManager` / `configureVfxParticleSystem`，渲染组用 `renderingGroupId ?? VFX_RENDERING_GROUP_ID`；
+   - 每帧逻辑挂 `scene.onBeforeRenderObservable`，dispose 时务必 remove；
+   - 持续型特效内部池化精灵；方向类参数用 `root.getWorldMatrix()` 变换，以支持 reparent 跟随；
+   - 随机数用确定性序列，不用 `Math.random()`；
+   - dispose 按 6.5 的清单释放全部资源，并加 `disposed` 标志防重入。
+4. 在目标 System 中通过注入的 `sceneVfxService.playEffectPackage()` 触发；持续跟随型按 5.3 的 reparent 模式写。
+5. 用通用 VFX 调试面板调参，确认后保存到 `vfx-params.json` 随代码提交。
+
+## 10. 已集成特效清单
+
+注册顺序见 `src/assets/vfx/index.ts` 的 `VFX_EFFECT_PACKAGES`：
+
+| 特效 ID | 说明 |
+|---|---|
+| `lumber-debris-scatter` | 木材碎片散落 |
+| `player-upgrade` | 玩家/NPC 升级金光 |
+| `run-footstep-dust` | 奔跑脚步灰尘 |
+| `tree-leaf-chop-burst` | 砍树叶子飞散 |
+| `tree-chop-dust` | 砍树烟尘 |
+| `building-upgrade` | 建筑升级 |
+| `character-entrance` | 角色入场 |
+| `lumber-cart-suction` | 木材车吸取 |
+| `resource-collect-sparkles` | 资源收集火花 |
+| `lumber_vehicle_wood_chips` | 运木车木屑 |
+| `tree_chop_dust_burst` | 砍树尘埃爆发 |
+| `wood_crusher_sawdust` | 粉碎机锯屑（manifest 版） |
+| `wood_cutter_sawdust` | 切割机锯屑（manifest 版） |
+| `lumber_vehicle_upgrade_aura` | 运木车升级光环 |
+| `lumber_vehicle_gear_spin` | 运木车齿轮旋转 |
+| `door_open_gold_flakes` | 开门金色碎片 |
+| `wood_peel_material_test` | 木材剥离材质测试 |
+| `vehicle-exhaust-smoke` | 小车尾气 |
+| `vehicle-upgrade` | 车辆升级 |
+| `conveyor-upgrade` | 传送带升级 |
+| `ground-tile-upgrade` | 地砖升级（区域解锁） |
+| `wood-crusher-sawdust` | 粉碎机锯屑 |
+| `wood-cutter-sawdust` | 切割机锯屑 |