@fps-games/vfx

Babylon.js 共享 VFX 特效库。导入即用 + 项目内调试面板。消费模型 = 模型 C(runtime/类型来自包,本地 import.meta.glob 装配注册表);发布 = 做法A(dist 提交进 git + tag,消费端 clone 即用,无需 build)。

文档入口

| 我要… | 看 | |---|---| | 新项目集成特效(消费包、装配、播放、挂载、瞄准) | docs/INTEGRATION.md | | 制作一个新特效(作者侧:create 契约、debugParams、guardrail) | docs/AUTHORING_EFFECTS.md | | 放置系统设计(placement 标记 / inputs 通道 / 挂载 / binding) | docs/vfx-placement-design.md | | 架构 / 计划 | docs/VFX_LIBRARY_ARCHITECTURE_chatgpt.md、docs/VFX_LIBRARY_PLAN.md |

30 秒上手(消费方)

// package.json —— git tag 即版本锁
"@fps-games/vfx": "^0.3.4"

// src/assets/vfx/index.ts —— 装配注册表(模型 C)
import { buildRegistry, type VfxRegistry } from '@fps-games/vfx';
export * from '@fps-games/vfx';
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 });

// 接线 + 播放
const svc = new EffectPackageService(scene, { registry: VFX_REGISTRY });
svc.playEffectPackage('thruster-flame', {}, { parent: engineSocket, offsetIsLocal: true });

⚠️ 三个最易漏:① @fps-games/vfx 要加进 vite 构建白名单;② Babylon 要 resolve.dedupe;③ glob 只扫本地 effects/*,每个要用的特效都得建本地桩(re-export 库内预制即可)。详见 INTEGRATION.md。

开发

pnpm validate   # 契约 / 特效 lint / typecheck / build / dist 禁运行时
pnpm build      # 生成 dist(发版前)