@fps-games/vfx 0.3.2 → 0.3.4

package/docs/INTEGRATION.md

@@ -1,194 +0,0 @@
-# 新项目集成 @fps/vfx(集成指南)
-
-> 面向**新游戏项目**:如何消费 `@fps/vfx` 包、装配特效、在游戏逻辑里播放(含挂载/瞄准)。
-> 代码片段均摘自真实消费方 `pa_template`(`/Users/admin/Code/FPS/pa_template`)。
-> 写特效(作者侧)看 [`AUTHORING_EFFECTS.md`](./AUTHORING_EFFECTS.md);放置/inputs 设计看 [`vfx-placement-design.md`](./vfx-placement-design.md)。
-
-消费模型 = **"模型 C"**:runtime + 类型来自 `@fps/vfx` 包;本地 effect 经 `import.meta.glob` 装配注册表。库走 **"做法A"** 发布:dist 已提交进 git 仓库并打 tag,消费端 `npm install` 直接 clone 拿到成品 dist,**无需 build/registry/postinstall**。
-
----
-
-## 1. 消费 `@fps/vfx`(装包 + 构建配置)
-
-### 1.1 加依赖(package.json)
-```jsonc
-"dependencies": {
-  "@babylonjs/core": "8.52.1",
-  "@babylonjs/loaders": "8.52.1",
-  "@fps/vfx": "git+ssh://git@github.com/forge-play-studio/fps-vfx-library.git#v0.3.0"
-}
-```
-- `#vX.Y.Z` tag 即版本锁。`npm install` 把仓库 clone 进 `node_modules/@fps/vfx`,包的 `exports` 指向已提交的 `dist/index.js` + `dist/index.d.ts` + `dist/effects/*`。
-- **peerDependencies**:`@babylonjs/core ^8` + `@babylonjs/loaders ^8`,项目自带即可。
-
-### 1.2 TypeScript(零配置)
-`tsconfig.json` 用 `moduleResolution: "bundler"` 即可解析包的 `exports`/`types`,**不用给 @fps/vfx 配 paths**。
-
-### 1.3 Vite(三件事)
-```ts
-// ① Babylon 去重为单实例(否则特效与场景用不同 Babylon → 渲染/类型错乱)
-resolve: { dedupe: ['@babylonjs/core', '@babylonjs/loaders', '@babylonjs/inspector'] },
-
-// ② ⭐必做:@fps/vfx 加进构建白名单,否则 `npm run build` 直接 throw
-//    (pa_template 用了 build-only 的 thirdPartyWhitelistPlugin;dev/serve 不受影响 → 最易漏)
-const allowedThirdPartyPackages = ['@babylonjs/core', '@babylonjs/loaders', '@fps/vfx', /* ... */];
-
-// ③ 单文件打包:dist 含动态 import 的 runtime chunks,这两项把它们内联进单 HTML,无需 copy
-build: { rollupOptions: { output: { inlineDynamicImports: true } } },  // + viteSingleFile()
-```
-**不需要**给 @fps/vfx 配 alias / optimizeDeps / copy —— 走 Vite 默认 node 解析到 dist,dev 与 prod 一致。
-
----
-
-## 2. 装配注册表(模型 C)
-
-新建 `src/assets/vfx/index.ts`(barrel,~12 行,新项目几乎一字不改):
-```ts
-// VFX registry barrel —— 消费 @fps/vfx(模型 C)。glob 扫本地 effects 桩;runtime/类型来自包。
-import { buildRegistry, type VfxRegistry } from '@fps/vfx';
-
-export * from '@fps/vfx';   // 透传库的全部类型/runtime → 业务侧统一从 '../assets/vfx' 取,不直接 import 包
-
-const modules = import.meta.glob('./effects/*/index.ts', { eager: true }) as Record<string, Record<string, unknown>>;
-const params  = import.meta.glob('./effects/*/vfx-params.json', { eager: true }) as Record<string, { default: unknown }>;
-
-export const VFX_REGISTRY: VfxRegistry = buildRegistry({ modules, params });
-```
-
-### 2.1 opt-in 一个特效 = 建一个本地桩
-> ⚠️ **glob 只扫本地 `src/assets/vfx/effects/*`;库 dist 里几十个预制特效不会自动进注册表。** 每个要用的特效都得建一个本地桩(哪怕只一行 re-export)。模板出厂 `effects/` 只有 `.gitkeep`,所以 **VFX_REGISTRY 默认是空的**。
-
-```ts
-// src/assets/vfx/effects/thruster-flame/index.ts —— opt-in 库内预制特效(库 exports 子路径 ./effects/*)
-export { thrusterFlameEffectPackage } from '@fps/vfx/effects/thruster-flame';
-```
-- (可选)同目录放 `vfx-params.json`(`{ schemaVersion:'vfx-params/1.0', effectId, updatedAt, params }`)作该特效的 `savedParams` 覆写。
-- 也可在本地桩里写**项目自有特效**(完整 `VfxEffectPackage`,见 AUTHORING_EFFECTS.md)。
-- 坑:两个桩 re-export 同一 `pkg.id` → buildRegistry **直接 throw**(duplicate id)。
-
----
-
-## 3. 接线服务(唯一接线点)
-
-`src/services/SceneVfxService.ts`(项目自有薄封装,**不在库里**):
-```ts
-import { EffectPackageService } from '@fps/vfx';
-import { VFX_REGISTRY, type VfxSpawnTransform, type VfxParamValues } from '../assets/vfx';
-
-export class SceneVfxService {
-  private effectPackageService: EffectPackageService;
-  constructor(scene: Scene, options: SceneVfxServiceOptions = {}) {
-    this.effectPackageService = new EffectPackageService(scene, {
-      registry: VFX_REGISTRY,                                   // ← 注入本地装配的注册表
-      getDebugAnchorPosition: options.getDebugAnchorPosition,   // ← 调试锚点(可选;不传则锚点跟随不可用)
-    });
-  }
-  getEffectPackageService() { return this.effectPackageService; }
-  playEffectPackage(id: string, params, spawnTransform) { return this.effectPackageService.playEffectPackage(id, params, spawnTransform); }
-  dispose() { this.effectPackageService.dispose(); }
-}
-```
-
-`src/core/Game.ts`(创建 + 暴露门面):
-```ts
-// init():在 entities/zone 之后、gameplay modules 之前创建(gameplay 工厂依赖它非空)
-this.sceneVfxService = new SceneVfxService(this.scene);
-
-// 对外播放门面(游戏逻辑/面板都只认这个,不直接碰 EffectPackageService)
-playEffectPackage(id: string, params: Partial<VfxParamValues> = {}, spawnTransform?: VfxSpawnTransform | Vector3) {
-  return this.sceneVfxService?.playEffectPackage(id, params, spawnTransform) ?? null;
-}
-getEffectPackageService() { return this.sceneVfxService?.getEffectPackageService() ?? null; }
-
-// dispose():this.sceneVfxService?.dispose();
-```
-gameplay 模块经 `createProjectGameplayRuntime({ ..., sceneVfxService })` 注入拿到入口。
-
----
-
-## 4. 播放特效
-
-`playEffectPackage(effectId, params, spawnTransform)` 返回 `VfxEffectHandle = { root, ready?, dispose() }`。**生命周期由调用方管**。
-
-### 4.1 一次性(one-shot)
-```ts
-const h = game.playEffectPackage('explosion', {}, { position: hitPoint });
-// 自销型特效播完自己消;若要确保清理:
-await h?.ready; /* ...用完... */ h?.dispose();
-```
-
-### 4.2 持续 / 可重播(单例预览)
-```ts
-previewHandle?.dispose();                                   // 重播前先 dispose 旧的,否则泄漏多份 root
-previewHandle = game.playEffectPackage(id, params);
-```
-
-### 4.3 放置(placement)——**需 @fps/vfx ≥ v0.2.0**
-> v0.1.1 的 `spawnTransform` 只有 `{ position?, rotationY?, renderingGroupId? }`(世界坐标老式范式)。
-> PR #12 合并发版后,`spawnTransform` 扩展为下面这套,并按特效的 `placement` 标记放置:
-
-```ts
-type VfxSpawnTransform = {
-  position?, rotationY?, rotation?, scale?, renderingGroupId?,
-  parent?: TransformNode,      // 挂载点:特效 root parent 到它 → 经场景图自动跟随
-  offsetIsLocal?: boolean,
-  inputs?: {                   // 运行时外部信息(瞄准点/法线/端点/目标);值可静态或 provider(动态每帧取)
-    aim?, normal?, endpoints?, target?, scalars?
-  },
-};
-```
-
-按特效的 `placement`(socket / world / link / target / screen,见 vfx-placement-design.md):
-```ts
-// socket:挂到对象的命名挂点,随它走
-game.playEffectPackage('thruster-flame', {}, { parent: engineSocket, offsetIsLocal: true });
-
-// world:在运行时算出的世界点 spawn,不跟随(命中/爆炸/落点)
-game.playEffectPackage('monster-hit', {}, { position: hitPoint });
-
-// 定向武器(laser/pulse):socket 起点 + inputs.aim 终点(provider 追移动目标)
-game.playEffectPackage('laser-beam', {}, {
-  parent: muzzle, offsetIsLocal: true,
-  inputs: { aim: () => enemy.getAbsolutePosition() },   // 动态目标每帧取
-});
-```
-> ⚠️ v0.1.1(及之前)**没有 parent 挂载**。要让特效跟随移动目标,只能自己持有 handle、每帧手写 `handle.root.position = target.position`。升级到 ≥v0.2.0 后改用 `parent`(场景图自动跟随),并用 `inputs.aim` 取代手动追瞄。
-
----
-
-## 5. 调试面板(可选)
-```ts
-// runtime-debug-bootstrap.ts
-runtimePanels.use(mountRuntimeVfxDebugPanel({ root, getGame }));
-```
-- 面板经 `getGame().getEffectPackageService().getEffectPackages()` 拉特效列表;`getMergedParams(id)` 拉合并默认值填草稿。
-- 保存:POST dev server `/__vfx_debug_overrides {effectId, params}` → 落盘 `src/assets/vfx/effects/<id>/vfx-params.json` + `setDebugOverride(id, params)` 即时生效后 reload(生产无此路由)。
-- VFX_REGISTRY 为空时面板自动隐藏(列表为空)。
-
----
-
-## 6. 升级 @fps/vfx 版本
-1. **库侧(做法A)**:`pnpm release -- <patch|minor|major>` 一条龙(gate → bump → CHANGELOG → 提交 dist → tag → push)。
-2. **消费侧**:改 `package.json` 的 `#vX.Y.Z` → `npm install`(git 依赖有时需先删 `node_modules/@fps/vfx` 再装才 clone 到新 tag)→ `npm run build` 验白名单与打包。
-3. 详见 `vfx-library-maintenance` skill。
-
----
-
-## 7. 常见坑(checklist)
-- [ ] **`@fps/vfx` 没进 vite 白名单** → dev 能跑、`npm run build` 直接 throw(最易漏)。
-- [ ] **Babylon 没 dedupe** → 特效与场景用不同 Babylon 实例,渲染/类型错乱。
-- [ ] **以为装了包就有特效** → 错,glob 只扫本地 `effects/*`,每个特效都要建本地桩。
-- [ ] **两个桩 re-export 同一 id** → buildRegistry throw。
-- [ ] **业务侧直接 import '@fps/vfx' 类型** → 应统一从 `'../assets/vfx'`(barrel `export *` 透传),保持单一出口。
-- [ ] **持续特效不 dispose 旧 handle 就重播** → 泄漏多份 root。
-- [ ] **想要挂载/瞄准却在旧版** → 升级到 ≥v0.2.0。
-
-## 8. 参考真实文件(pa_template)
-| 切面 | 文件 |
-|---|---|
-| 依赖 | `package.json`(`@fps/vfx` git tag) |
-| vite | `vite.config.ts`(dedupe / 白名单 / inlineDynamicImports) |
-| 注册表 | `src/assets/vfx/index.ts` + `effects/<id>/index.ts` 桩 |
-| 服务接线 | `src/services/SceneVfxService.ts` + `src/core/Game.ts` |
-| 播放范式 | `SceneVfxService.warmupEffectPackage`(one-shot)、`runtime-vfx-debug-panel.ts playPreviewNow`(可重播) |
-| 调试面板 | `src/debug/runtime-vfx-debug-panel.ts` |