@fps-games/vfx 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -12,6 +12,14 @@
 
 <!-- release.mjs 在此行下方插入新版本区块 -->
 
+## v0.3.3 — 2026-06-30
+
+### 改动
+- fix(npm): exclude source and previews from package
+
+### 特效
+- 无新增 / 删除(仍 37 个)。
+
 ## v0.3.2 — 2026-06-30
 
 ### 改动

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fps-games/vfx",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "type": "module",
   "description": "Shared VFX library for Playable projects: engine-injected effect packages + runtime. Project-pure (no imports of host project code).",
   "publishConfig": {
@@ -21,9 +21,10 @@
   },
   "files": [
     "dist",
-    "tooling",
-    "packages",
-    "docs",
+    "tooling/vfx-cli.mjs",
+    "tooling/vfx-package-resolution.mjs",
+    "packages/effects/*/vfx-params.json",
+    "README.md",
     "CHANGELOG.md",
     "index.json"
   ],

package/tooling/vfx-cli.mjs

@@ -17,6 +17,9 @@ import { fileURLToPath } from 'node:url';
 const LIB_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const LIB_EFFECTS = join(LIB_ROOT, 'packages', 'effects');
 const LIB_VERSION = (() => { try { return JSON.parse(readFileSync(join(LIB_ROOT, 'package.json'), 'utf8')).version; } catch { return '0.0.0'; } })();
+const LIB_INDEX = (() => {
+  try { return JSON.parse(readFileSync(join(LIB_ROOT, 'index.json'), 'utf8')); } catch { return null; }
+})();
 
 const [, , cmd, ...rest] = process.argv;
 const VALUED_FLAGS = new Set(['--project', '--to']); // 这些 flag 后跟一个值,值不算 positional
@@ -33,10 +36,14 @@ const force = flags.has('--force');
 
 // ── 通用 ──────────────────────────────────────────────────────────────────────
 function libEffectIds() {
+  if (Array.isArray(LIB_INDEX?.effects)) return LIB_INDEX.effects.map((e) => e.id).filter(Boolean);
   return readdirSync(LIB_EFFECTS).filter((e) => {
     try { return statSync(join(LIB_EFFECTS, e)).isDirectory() && existsSync(join(LIB_EFFECTS, e, 'index.ts')); } catch { return false; }
   });
 }
+function hasLibEffect(id) {
+  return libEffectIds().includes(id) || existsSync(join(LIB_EFFECTS, id, 'vfx-params.json'));
+}
 function stub(id) {
   return `// @fps/vfx re-export 桩(代码/资源在包内;本地仅 vfx-params.json + 此桩)。\nexport * from '@fps/vfx/effects/${id}';\n`;
 }
@@ -111,7 +118,7 @@ function changelogRange(fromVersion, toVersion) {
 
 // ── add ───────────────────────────────────────────────────────────────────────
 function add(id) {
-  if (!existsSync(join(LIB_EFFECTS, id))) { console.error(`✗ 库中无特效 "${id}"。可用:run "list"。`); process.exit(1); }
+  if (!hasLibEffect(id)) { console.error(`✗ 库中无特效 "${id}"。可用:run "list"。`); process.exit(1); }
   const destDir = join(effectsDestDir(), id);
   const stubPath = join(destDir, 'index.ts');
   const paramsPath = join(destDir, 'vfx-params.json');

package/docs/AUTHORING_EFFECTS.md

@@ -1,297 +0,0 @@
-# 如何制作一个 VFX 特效(@fps/vfx 作者指南)
-
-面向在 `fps-vfx-library` 里**新增/修改特效**的人(human 或 coding agent)。读完你能从零写出一个能被项目导入、能在 DEV 调试面板里调参的特效。
-
-配套:运行手册见 `.claude/skills/vfx-library-maintenance/`;库总设计见 issue #1 / `docs/VFX_LIBRARY_PLAN.md`;参数运转的代码细节见本文 §5。
-
----
-
-## 0. 核心概念:一个特效 = 一个 `VfxEffectPackage`
-
-每个特效是 `packages/effects/<dir>/index.ts` 导出的一个对象,实现 `VfxEffectPackage`(定义在 `packages/types.ts`):
-
-```ts
-interface VfxEffectPackage<P> {
-  id: string;                 // 全局唯一 id
-  nameZh: string;             // 中文名(面板下拉显示)
-  defaultParams: P;           // 参数默认值(运行时真正用的数据)
-  debugParams: VfxParamDefinition[];  // 参数的 UI 描述(面板照它建控件)
-  create(ctx): VfxEffectHandle;       // 唯一入口:用 ctx + params 在场景里建出特效
-  debugAnchor?: 'playerRight' | 'player';  // 面板里默认 spawn 锚点
-  manifest?: VfxEffectManifest;            // 可选:检索元数据
-  spawnParams?, savedParams?;              // 可选:见 §5
-}
-```
-
-宿主(项目)只通过 `playEffectPackage(id, params, transform)` 触发它;特效拿到 `ctx`(scene/root/position/params)自给自足地建粒子/网格。**特效绝不 import 项目代码**(纯净契约,§7)。
-
-**两类实现**:
-- **code 类**(逃生舱):`index.ts` 手写 `create()`,直接用 Babylon `ParticleSystem`/`Sprite`/`Mesh`。适合复杂、跟随、mesh/GLB 特效。**本指南主讲这类。**
-- **data 类**(数据驱动):`index.ts` 是薄包装,调工厂 `createManifestRuntimeEffectPackage` 读 manifest JSON。适合标准粒子、AI 可生成。见 §6。
-
----
-
-## 1. 五分钟:一个最小 code 特效
-
-目录:`packages/effects/ember-sparks/`
-
-```
-ember-sparks/
-├── index.ts                         # 特效本体
-├── vfx-params.json                  # 调参种子(项目会拷走并各自调)
-└── assets/textures/ember_spark.png  # 贴图(经 ?url 打包内联)
-```
-
-`index.ts`:
-
-```ts
-import { Color4 } from '@babylonjs/core/Maths/math.color';
-import { ParticleSystem } from '@babylonjs/core/Particles/particleSystem';
-import { Texture } from '@babylonjs/core/Materials/Textures/texture';
-import type { VfxColorValue, VfxEffectPackage, VfxParamValues } from '../../types';
-import { VFX_RENDERING_GROUP_ID } from '../../rendering';
-import sparkTextureUrl from './assets/textures/ember_spark.png?url';   // ✅ 资源用 ?url
-
-// 1) 参数类型 + 默认值
-interface EmberSparksParams extends VfxParamValues {
-  lifetime: number;     // 特效整体存活秒数
-  count: number;        // 粒子数
-  size: number;         // 粒子大小
-  speed: number;        // 飞散速度
-  color: VfxColorValue; // 颜色 {r,g,b}(0..1)
-}
-
-const DEFAULT_PARAMS: EmberSparksParams = {
-  lifetime: 1.2, count: 60, size: 0.12, speed: 3, color: { r: 1, g: 0.6, b: 0.15 },
-};
-
-export const emberSparksEffectPackage: VfxEffectPackage<EmberSparksParams> = {
-  id: 'ember-sparks',
-  nameZh: '火星迸射',
-  defaultParams: DEFAULT_PARAMS,
-  debugAnchor: 'playerRight',
-
-  // 2) 面板控件:每条 = 一个旋钮。key 必须与 defaultParams / create() 读取的 key 一致(见 §4)
-  debugParams: [
-    { key: 'lifetime', label: '存活时长', kind: 'lifetime', min: 0.2, max: 5,  step: 0.1  },
-    { key: 'count',    label: '粒子数',   kind: 'number',   min: 1,   max: 300, step: 1    },
-    { key: 'size',     label: '粒子大小', kind: 'scale',    min: 0.01,max: 2,   step: 0.01 },
-    { key: 'speed',    label: '飞散速度', kind: 'number',   min: 0,   max: 20,  step: 0.1  },
-    { key: 'color',    label: '颜色',     kind: 'color' },
-  ],
-
-  // 3) create:用 ctx + params 建特效。每个 params.<key> 来自五层合并后的最终值
-  create({ scene, root, position, renderingGroupId, params }) {
-    root.position.copyFrom(position);
-    const ps = new ParticleSystem('ember_sparks', Math.ceil(params.count), scene);
-    ps.particleTexture = new Texture(sparkTextureUrl, scene);
-    ps.emitter = root;                      // 挂在 root 上 → 宿主 reparent root 即可跟随物体
-    ps.minSize = ps.maxSize = params.size;
-    ps.minEmitPower = params.speed * 0.5;
-    ps.maxEmitPower = params.speed;
-    ps.color1 = new Color4(params.color.r, params.color.g, params.color.b, 1);
-    ps.emitRate = params.count / params.lifetime;
-    ps.renderingGroupId = renderingGroupId ?? VFX_RENDERING_GROUP_ID;  // ✅ 用库常量,别写 magic number
-    ps.start();
-
-    const stopTimer = window.setTimeout(() => ps.stop(), params.lifetime * 1000);
-    // 4) 必须返回 handle:root + dispose(清理一切,别漏 timer/observer/system)
-    return {
-      root,
-      dispose() { window.clearTimeout(stopTimer); ps.dispose(); root.dispose(); },
-    };
-  },
-};
-```
-
-`vfx-params.json`(种子,项目会拷走并各自调;`params` 里只放想覆盖默认值的项,空也行):
-
-```json
-{ "schemaVersion": "vfx-params/1.0", "effectId": "ember-sparks", "params": {} }
-```
-
-校验 + 自测:
-
-```bash
-node tooling/validate-effects.mjs --effect ember-sparks   # 单个特效快速 lint
-pnpm validate                                             # 全量(含 build + dist 扫描)
-```
-
-装进一个项目试调:`node node_modules/@fps/vfx/tooling/vfx-cli.mjs add ember-sparks --project .` → `pnpm dev` → 右下 **VFX** 按钮 → 选「火星迸射」→ 调参 → 播放/保存。
-
----
-
-## 2. `create(ctx)` 契约
-
-`ctx`(`VfxEffectPackageContext`)给你:
-
-| 字段 | 含义 |
-|---|---|
-| `scene` | Babylon `Scene` |
-| `root` | 已建好的 `TransformNode`,已放到 spawn 位置;**把特效挂在它下面**,宿主 reparent 它即可跟随 |
-| `position` | spawn 世界坐标(= `root.position` 的副本) |
-| `rotationY` | spawn 朝向 |
-| `renderingGroupId` | 渲染组(可选;没有就用 `VFX_RENDERING_GROUP_ID`) |
-| `params` | **五层合并后的最终参数**(见 §5),按 key 读 |
-
-返回 `VfxEffectHandle`:
-
-```ts
-interface VfxEffectHandle {
-  root: TransformNode;
-  ready?: Promise<void>;   // 异步加载(GLB/贴图)时返回它;宿主可 await(warmup 用),别漏
-  dispose(): void;         // 清理一切:粒子系统 / observer / setTimeout / mesh / root.dispose()
-}
-```
-
-规则:
-- **跟随型特效用 code 类**,把发射器挂 `root`,宿主 reparent root 即跟随(`root.getWorldMatrix()`)。data 类一次性定位、不跟随。
-- **异步加载**(GLB、贴图)→ 把加载 promise 放 `ready`,且 `dispose` 要能在加载未完成时也安全清理(置 `disposed` 标志)。参考 `lumber-debris-scatter`。
-- `create()` 内部抛错不会崩场景(service 有 try/catch 兜底),但**别把资源泄漏在错误路径**。
-
----
-
-## 3. `debugParams` 是什么、面板怎么用它
-
-`debugParams` 是**参数的 UI 描述**;DEV 调试面板**照它自动生成控件**(`runtime-vfx-debug-panel.ts` 读 `effectPackage.debugParams`,一条 = 一个旋钮)。你不用写任何面板代码——声明即出控件。
-
-每条是一个 `VfxParamDefinition`:
-
-| `kind` | 面板控件 | 额外字段 | 值类型 |
-|---|---|---|---|
-| `number` | 数字输入框 | `min` / `max` / `step` | `number` |
-| `lifetime` | 数字框(语义=时长) | `min` / `max` / `step` | `number` |
-| `scale` | 数字框(语义=缩放) | `min` / `max` / `step` | `number` |
-| `opacity` | 数字框(语义=透明度) | `min` / `max` / `step` | `number` |
-| `color` | 取色器 | — | `{ r, g, b }`(0..1) |
-| `enum` | 下拉 | `options: [{value,label}]` | `string` |
-
-公共字段:`key`(必填,见 §4)、`label`(中文标签)、`description?`。
-
-```ts
-{ key: 'scatterShape', label: '散落形态', kind: 'enum',
-  options: [ { value: 'radial', label: '中心外扩' }, { value: 'vertical', label: '垂直下落' } ] }
-```
-
-> 不想暴露到面板的内部参数:放 `defaultParams` 但**不放** `debugParams` 即可(常见且允许)。反过来不行——见 §4。
-
----
-
-## 4. ⭐ key 一致性:面板↔参数靠 `key` 字符串对齐
-
-三处用**同一个 key 串**起来:
-
-```
-debugParams[i].key  ←→  defaultParams[key]  ←→  create() 里读的 params[key]
-```
-
-- 面板把旋钮的值写进 `params[key]`;`create()` 用 `params[key]` 去设粒子属性。key 对不上 → **旋钮调了没反应**。
-- 硬规则(guardrail 强制):**每个 `debugParams[].key` 必须在 `defaultParams` 里有默认值**。`validate-effects.mjs` 会静态检查;拼错 key(如 `partcileCount`)会被拦下:
-  ```
-  [参数] debugParams 旋钮 [partcileCount] 在 defaultParams 里没有对应默认值 → 面板调它不生效…
-  ```
-- 反向(`defaultParams` 有、`debugParams` 没有)= 内部参数,允许(不强制每个值都给旋钮)。
-- 你在 `create()` 里读哪些 `params.<key>`,就应该在 `defaultParams` 给默认值;想让人调的,再加进 `debugParams`。
-
----
-
-## 5. 参数怎么运转(五层合并)
-
-`playEffectPackage(id, explicitParams, transform)`(`EffectPackageService.ts`)按顺序合并 5 层,**后面的盖前面的**,得到最终 `params` 传给 `create()`:
-
-```
-1. 生成默认(spawn 位置偏移 offsetX/Y/Z)
-2. defaultParams          —— 你在库里写的默认值
-3. savedParams            —— 项目的 vfx-params.json(经 buildRegistry 注入)
-4. 运行时 override         —— 面板调参时 setDebugOverride 实时写的
-5. explicitParams         —— 调用方临时传的(gameplay 触发时算的动态值)
-```
-
-含义:
-- **面板调参 = 第 4 层**;点「保存」→ 写回项目 `effects/<id>/vfx-params.json`(第 3 层)→ 下次加载即新默认。
-- **库代码不被改**(模型 C:代码在 `@fps/vfx` 包,调参在项目的 `vfx-params.json`)。
-- **面板调好的值,游戏正式跑也生效**——gameplay 的 system 触发也走同一条合并。
-
-调参面板的存盘端点(DEV):面板「保存」→ `POST /__debug_panel_config?file=effects/<id>/vfx-params.json`(vite 中间件落盘,只写 `params`)。
-
----
-
-## 6. data 类特效(manifest + 工厂)
-
-标准粒子可以不手写 `create()`,改用工厂读 manifest:
-
-```ts
-// packages/effects/spark_puff/index.ts
-import manifest from './spark_puff.json';                          // vfx-effect-package 格式(emitters + tunableParams)
-import runtimeUrl from './assets/runtime/particleEmitter.v1.js?url'; // 引擎适配器,?url 注入
-import texUrl from './assets/textures/spark.png?url';
-import { createManifestRuntimeEffectPackage } from '../../manifestRuntimePackage';
-
-export const sparkPuffEffectPackage = createManifestRuntimeEffectPackage({
-  id: 'spark_puff',
-  manifest,
-  assetUrls: {
-    'assets/runtime/particleEmitter.v1.js': runtimeUrl,
-    'assets/textures/spark.png': texUrl,
-  },
-});
-```
-
-- `defaultParams` / `debugParams` / `nameZh` 由**工厂从 manifest 的 `tunableParams` 生成**(所以 data 类 index.ts 里看不到它们字面量,key 检查也跳过)。
-- 双发射器(dust + 碎屑)有专用工厂 `createWoodSawdustEffectPackage`(见 `wood-crusher-sawdust`)。
-- data 类**一次性定位、不跟随**;要跟随用 code 类。
-
----
-
-## 7. 硬约束:库纯净契约(违反会被 guardrail 拦)
-
-1. **不 import 任何项目代码**。只允许 `@babylonjs/*`、库内相对路径(`../../types`/`../../rendering`)、自身资源。特效↔宿主唯一通道 = `create(ctx)`。
-2. **资源自带**:贴图/GLB/runtime-js 放包内,`import x from './assets/…?url'`。**禁 `new URL(…, import.meta.url)`**(库 build 不内联它)。
-3. **glTF 只用核心 loader**:`import '@babylonjs/loaders/glTF/2.0/glTFLoader'`。**禁全量 barrel**(`@babylonjs/loaders` / `…/glTF`)——会把 `MeshoptDecoder` 拉进 consumer 包,违反 Playable 策略(#2 v0.1.1)。GLB 必须 plain(零扩展)。见 `lumber-debris-scatter`。
-4. **配置参数化**:任何"配置值"做成 `defaultParams`/`debugParams`,经 `params` 传入。
-5. **渲染组用常量** `VFX_RENDERING_GROUP_ID`,别写 magic number。
-
----
-
-## 8. 工作流:校验 → 安装 → 发版
-
-```bash
-# 作者本地(改完特效):
-node tooling/validate-effects.mjs --effect <id>   # 单特效快速 lint
-pnpm validate                                     # 全量 guardrail(boundary+lint+typecheck+build+dist)
-pnpm test:guardrails                              # guardrail 回归
-
-# 在某项目里调试:
-node node_modules/@fps/vfx/tooling/vfx-cli.mjs add <id> --project .   # 装桩+种子params
-pnpm dev   # → VFX 面板调参/保存
-
-# 发版(让消费方拿到新特效):
-pnpm release -- minor --dry-run   # 预演(新增特效=minor)
-pnpm release -- minor             # gate→bump→index/CHANGELOG→提交dist→tag→push
-```
-
----
-
-## 9. 常见坑
-
-| 坑 | 现象 | 修 |
-|---|---|---|
-| 全量 glTF loader | prod 构建被 meshopt 检查卡住 | 用 `@babylonjs/loaders/glTF/2.0/glTFLoader` |
-| `new URL(...)` 引资源 | 库 build 后资源丢失 | 改 `import x from './…?url'` |
-| debugParams key 拼错 | 面板旋钮调了没反应 | key 对齐 defaultParams(guardrail 会拦) |
-| 想跟随却用了 data 类 | 特效不跟物体 | 用 code 类,挂 `root`,宿主 reparent |
-| `dispose` 漏清理 | 切场景/重复播泄漏 | dispose 清 system/observer/timer/mesh/root |
-| 异步加载没给 `ready` | warmup 时机错乱 | 返回 handle 时带 `ready: Promise` |
-| 引用项目模块 | boundary 报错 | 改成 ctx 注入 / 自带资源 |
-
----
-
-## 10. 提交前 checklist
-
-- [ ] `packages/effects/<dir>/index.ts` 导出 `VfxEffectPackage`(`id`/`nameZh`/`defaultParams`/`debugParams`/`create`)。
-- [ ] 资源在 `assets/` 下,经 `?url` 引;GLB 用核心 loader。
-- [ ] `debugParams` 每个 `key` 都在 `defaultParams`(面板↔参数对齐)。
-- [ ] `create()` 用 `ctx` + `params`,不 import 项目;`dispose()` 清理彻底。
-- [ ] 有 `vfx-params.json` 种子(合法 JSON)。
-- [ ] `pnpm validate` + `pnpm test:guardrails` 全绿。
-- [ ] DEV 面板里能选到、能调、能播、能存。

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` |