@fps-games/vfx 0.1.1

package/dist/manifestRuntimePackage.d.ts

@@ -0,0 +1,68 @@
+import { VfxEffectPackage } from './types';
+type LegacyTunableParamType = 'number' | 'color' | 'enum' | string;
+interface LegacyTunableTarget {
+    emitter: string;
+    property: string;
+    operator?: string;
+    defaultValue?: unknown;
+}
+interface LegacyTunableParam {
+    key: string;
+    label?: string;
+    labelEn?: string;
+    labelZh?: string;
+    type: LegacyTunableParamType;
+    default?: unknown;
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: Array<{
+        value: string;
+        label?: string;
+    }>;
+    target?: LegacyTunableTarget;
+    targets?: LegacyTunableTarget[];
+}
+interface LegacyEmitterConfig {
+    name: string;
+    enabled?: boolean;
+    runtime?: {
+        adapter?: string;
+        stopAfterSeconds?: number;
+        disposeOnComplete?: boolean;
+    };
+    [key: string]: unknown;
+}
+interface LegacyRuntimeAdapterConfig {
+    id: string;
+    entry: string;
+    moduleFormat?: string;
+    exports?: string[];
+}
+interface LegacyEffectManifest {
+    id?: string;
+    name?: {
+        en?: string;
+        zh?: string;
+    };
+    assets?: Record<string, unknown> | unknown[];
+    source?: unknown;
+    emitters?: LegacyEmitterConfig[];
+    runtime?: {
+        driver?: string;
+        adapters?: LegacyRuntimeAdapterConfig[];
+    };
+    tunableParams?: LegacyTunableParam[];
+    defaultParams?: Record<string, unknown>;
+    debug?: {
+        playAnchor?: string;
+        livePreview?: boolean;
+    };
+}
+export interface ManifestRuntimeEffectPackageOptions {
+    id: string;
+    manifest: LegacyEffectManifest;
+    assetUrls: Record<string, string>;
+}
+export declare function createManifestRuntimeEffectPackage(options: ManifestRuntimeEffectPackageOptions): VfxEffectPackage;
+export {};

package/dist/registry.d.ts

@@ -0,0 +1,20 @@
+import { VfxEffectPackage, VfxParamValues } from './types';
+export interface VfxRegistry {
+    getEffectPackage(effectId: string): VfxEffectPackage | undefined;
+    getEffectPackages(): VfxEffectPackage[];
+    savedParams: Record<string, Partial<VfxParamValues>>;
+}
+export interface BuildRegistryInput {
+    /** import.meta.glob('./effects/*\/index.ts', { eager: true }) 的结果 */
+    modules: Record<string, Record<string, unknown>>;
+    /** import.meta.glob('./effects/*\/vfx-params.json', { eager: true }) 的结果(可选) */
+    params?: Record<string, {
+        default: unknown;
+    } | unknown>;
+    /** 可选:判定某目录是否仅调试用(prod 构建剔除) */
+    isDebugOnly?: (dir: string) => boolean;
+    /** 可选:prod 标志,配合 isDebugOnly 过滤 */
+    prod?: boolean;
+}
+export declare function isVfxEffectPackage(value: unknown): value is VfxEffectPackage;
+export declare function buildRegistry(input: BuildRegistryInput): VfxRegistry;

package/dist/rendering.d.ts

@@ -0,0 +1,5 @@
+import { ParticleSystem } from '@babylonjs/core/Particles/particleSystem';
+import { SpriteManager } from '@babylonjs/core/Sprites/spriteManager';
+export declare const VFX_RENDERING_GROUP_ID = 2;
+export declare function configureVfxSpriteManager(manager: SpriteManager): void;
+export declare function configureVfxParticleSystem(system: ParticleSystem): void;

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+import { Scene } from '@babylonjs/core/scene';
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+export type VfxDebugAnchor = 'playerRight' | 'player';
+export type VfxParamValue = number | string | VfxColorValue;
+export type VfxParamValues = Record<string, VfxParamValue>;
+export interface VfxColorValue {
+    r: number;
+    g: number;
+    b: number;
+}
+export type VfxParamKind = 'number' | 'color' | 'enum' | 'opacity' | 'lifetime' | 'scale';
+export interface VfxParamDefinitionBase {
+    key: string;
+    label: string;
+    kind: VfxParamKind;
+    description?: string;
+}
+export interface VfxNumberParamDefinition extends VfxParamDefinitionBase {
+    kind: 'number' | 'opacity' | 'lifetime' | 'scale';
+    min?: number;
+    max?: number;
+    step?: number;
+}
+export interface VfxColorParamDefinition extends VfxParamDefinitionBase {
+    kind: 'color';
+}
+export interface VfxEnumParamOption {
+    value: string;
+    label: string;
+}
+export interface VfxEnumParamDefinition extends VfxParamDefinitionBase {
+    kind: 'enum';
+    options: VfxEnumParamOption[];
+}
+export type VfxParamDefinition = VfxNumberParamDefinition | VfxColorParamDefinition | VfxEnumParamDefinition;
+export interface VfxEffectPackageContext<PParams extends VfxParamValues = VfxParamValues> {
+    scene: Scene;
+    root: TransformNode;
+    position: Vector3;
+    rotationY: number;
+    renderingGroupId?: number;
+    params: PParams;
+}
+export interface VfxEffectHandle {
+    root: TransformNode;
+    ready?: Promise<void>;
+    dispose(): void;
+}
+export interface VfxEffectManifest {
+    id: string;
+    nameZh: string;
+    assets?: string[];
+    source?: string;
+}
+export interface VfxSpawnParamKeys {
+    offsetX?: string;
+    offsetY?: string;
+    offsetZ?: string;
+}
+export interface VfxSpawnTransform {
+    position?: Vector3;
+    rotationY?: number;
+    renderingGroupId?: number;
+}
+export interface VfxParamsFile {
+    schemaVersion: string;
+    effectId?: string;
+    updatedAt?: string | null;
+    params?: Partial<VfxParamValues>;
+}
+export interface VfxEffectPackage<PParams extends VfxParamValues = VfxParamValues> {
+    id: string;
+    nameZh: string;
+    manifest?: VfxEffectManifest;
+    defaultParams: PParams;
+    debugAnchor?: VfxDebugAnchor;
+    spawnParams?: VfxSpawnParamKeys;
+    savedParams?: Partial<VfxParamValues>;
+    debugParams: VfxParamDefinition[];
+    create(context: VfxEffectPackageContext<PParams>): VfxEffectHandle;
+}
+export type VfxDebugOverrides = Record<string, Partial<VfxParamValues>>;

package/docs/AUTHORING_EFFECTS.md

@@ -0,0 +1,297 @@
+# 如何制作一个 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 面板里能选到、能调、能播、能存。