@fps-games/vfx 0.1.1 → 0.3.2

package/dist/index.js

@@ -111,20 +111,24 @@ class EffectPackageService {
     const params = this.getMergedParams(effectId, explicitParams);
     if (!params) return null;
     const spawn = this.resolveSpawnTransform(effectPackage, params, spawnTransform);
+    warnMissingRequiredInputs(effectId, effectPackage.requiredInputs, spawn.inputs);
     const runtimeParams = stripSpawnParams(params, effectPackage.spawnParams);
     const root = new TransformNode(`vfx_package_${effectId}`, this.scene);
-    root.position.copyFrom(spawn.position);
-    root.rotation.y = spawn.rotationY;
+    applySpawnToRoot(root, spawn);
+    const worldPosition = root.getAbsolutePosition().clone();
     let handle;
     try {
       handle = effectPackage.create({
         scene: this.scene,
         root,
-        position: spawn.position.clone(),
+        position: worldPosition,
         rotationY: spawn.rotationY,
         renderingGroupId: spawn.renderingGroupId,
-        params: runtimeParams
+        params: runtimeParams,
+        scale: spawn.scale,
+        inputs: spawn.inputs
       });
+      applySpawnToRoot(root, spawn);
     } catch (error) {
       console.warn(`[EffectPackageService] effect "${effectId}" create() failed; skipped.`, error);
       try {
@@ -139,6 +143,9 @@ class EffectPackageService {
       this.activeHandles.delete(handle);
       originalDispose();
     };
+    handle.root.onDisposeObservable.addOnce(() => {
+      this.activeHandles.delete(handle);
+    });
     return handle;
   }
   dispose() {
@@ -157,26 +164,87 @@ class EffectPackageService {
   }
   resolveSpawnTransform(effectPackage, params, spawnTransform) {
     const normalized = normalizeSpawnTransform(spawnTransform);
-    const basePosition = normalized.position?.clone() ?? this.resolveDebugPosition(effectPackage);
-    const rotationY = readFiniteNumber(normalized.rotationY, 0);
+    const parent = normalized.parent ?? null;
+    const basePosition = normalized.position?.clone() ?? (parent != null ? new Vector3(0, 0, 0) : this.resolveDebugPosition(effectPackage));
+    const rotation = resolveRotation(normalized.rotation, normalized.rotationY);
+    const scale = resolveScale(normalized.scale);
+    const offsetIsLocal = normalized.offsetIsLocal ?? parent != null;
     const renderingGroupId = readOptionalFiniteNumber(normalized.renderingGroupId);
     const offset = readSpawnOffset(params, effectPackage.spawnParams);
-    if (offset.lengthSquared() <= 1e-7) {
-      return { position: basePosition, rotationY, renderingGroupId };
-    }
-    const cos = Math.cos(rotationY);
-    const sin = Math.sin(rotationY);
-    return {
-      position: basePosition.addInPlace(new Vector3(
+    let position = basePosition;
+    if (offset.lengthSquared() > 1e-7) {
+      const cos = Math.cos(rotation.y);
+      const sin = Math.sin(rotation.y);
+      position = basePosition.addInPlace(new Vector3(
         offset.x * cos - offset.z * sin,
         offset.y,
         offset.x * sin + offset.z * cos
-      )),
-      rotationY,
-      renderingGroupId
-    };
+      ));
+    }
+    return { position, rotation, rotationY: rotation.y, scale, parent, offsetIsLocal, renderingGroupId, inputs: normalizeInputs(normalized.inputs) };
+  }
+}
+function normalizeInputs(inputs) {
+  if (!inputs) return void 0;
+  const asFn = (v) => v == null ? void 0 : typeof v === "function" ? v : () => v;
+  const out = {};
+  if (inputs.aim != null) out.aim = asFn(inputs.aim);
+  if (inputs.normal != null) out.normal = asFn(inputs.normal);
+  if (inputs.endpoints) out.endpoints = inputs.endpoints.map((e) => asFn(e)).filter(Boolean);
+  if (inputs.target) out.target = inputs.target;
+  if (inputs.scalars) {
+    out.scalars = {};
+    for (const [k, v] of Object.entries(inputs.scalars)) {
+      const fn = asFn(v);
+      if (fn) out.scalars[k] = fn;
+    }
+  }
+  return out;
+}
+function warnMissingRequiredInputs(effectId, required, inputs) {
+  if (!required || required.length === 0) return;
+  const missing = required.filter((k) => {
+    const v = inputs ? inputs[k] : void 0;
+    return v == null || k === "endpoints" && Array.isArray(v) && v.length < 2;
+  });
+  if (missing.length > 0) {
+    console.warn(`[EffectPackageService] effect "${effectId}" 声明 requiredInputs [${missing.join(", ")}] 但未提供 → 可能静默降级。`);
   }
 }
+function applySpawnToRoot(root, spawn) {
+  if (spawn.parent) root.parent = spawn.parent;
+  root.rotation.copyFrom(spawn.rotation);
+  root.scaling.copyFrom(spawn.scale);
+  if (spawn.parent && !spawn.offsetIsLocal) {
+    root.computeWorldMatrix(true);
+    root.setAbsolutePosition(spawn.position);
+  } else {
+    root.position.copyFrom(spawn.position);
+  }
+  root.computeWorldMatrix(true);
+}
+function resolveRotation(rotation, rotationY) {
+  if (rotation) {
+    return new Vector3(
+      readFiniteNumber(rotation.x, 0),
+      readFiniteNumber(rotation.y, 0),
+      readFiniteNumber(rotation.z, 0)
+    );
+  }
+  return new Vector3(0, readFiniteNumber(rotationY, 0), 0);
+}
+function resolveScale(scale) {
+  if (scale == null) return new Vector3(1, 1, 1);
+  if (typeof scale === "number") {
+    const s2 = readFiniteNumber(scale, 1);
+    return new Vector3(s2, s2, s2);
+  }
+  return new Vector3(
+    readFiniteNumber(scale.x, 1),
+    readFiniteNumber(scale.y, 1),
+    readFiniteNumber(scale.z, 1)
+  );
+}
 function normalizeSpawnTransform(spawnTransform) {
   if (!spawnTransform) return {};
   if (spawnTransform instanceof Vector3) return { position: spawnTransform };

package/dist/types.d.ts

@@ -1,7 +1,27 @@
 import { Scene } from '@babylonjs/core/scene';
 import { Vector3 } from '@babylonjs/core/Maths/math.vector';
 import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
 export type VfxDebugAnchor = 'playerRight' | 'player';
+export type VfxInput<T> = T | (() => T);
+export type VfxInputKey = 'aim' | 'normal' | 'endpoints' | 'target';
+/** 调用方提供的 inputs(放在 VfxSpawnTransform.inputs)。 */
+export interface VfxEffectInputs {
+    aim?: VfxInput<Vector3>;
+    normal?: VfxInput<Vector3>;
+    endpoints?: Array<VfxInput<Vector3>>;
+    target?: AbstractMesh;
+    /** 运行时标量(throttle/intensity 等),值可静态或 provider;特效每帧读取做活改(G5)。 */
+    scalars?: Record<string, VfxInput<number>>;
+}
+/** create() 收到的、已归一化为访问器的 inputs(provider 与静态值都变成可调用的函数)。 */
+export interface VfxResolvedInputs {
+    aim?: () => Vector3;
+    normal?: () => Vector3;
+    endpoints?: Array<() => Vector3>;
+    target?: AbstractMesh;
+    scalars?: Record<string, () => number>;
+}
 export type VfxParamValue = number | string | VfxColorValue;
 export type VfxParamValues = Record<string, VfxParamValue>;
 export interface VfxColorValue {
@@ -41,11 +61,21 @@ export interface VfxEffectPackageContext<PParams extends VfxParamValues = VfxPar
     rotationY: number;
     renderingGroupId?: number;
     params: PParams;
+    /**
+     * 解析后的三轴缩放(来自 spawnTransform.scale,默认 (1,1,1))。
+     * root 的缩放由 service 写好;但**几何不挂 root 的 world/detached 特效**(粒子/抛物池/世界坐标 emitter)
+     * root.scaling 作用不到,须自行把 ctx.scale 乘进几何尺寸/初速(G3)。
+     */
+    scale: Vector3;
+    /** 运行时外部信息(已归一化为访问器)。link/target/定向武器/活改标量等按 required/optionalInputs 读取。 */
+    inputs?: VfxResolvedInputs;
 }
 export interface VfxEffectHandle {
     root: TransformNode;
     ready?: Promise<void>;
     dispose(): void;
+    /** 可选:运行时活改 params(无须 dispose+replay,避免重置缓动/可见闪)。声明即纳入契约(G5)。 */
+    update?(params: Partial<VfxParamValues>): void;
 }
 export interface VfxEffectManifest {
     id: string;
@@ -58,10 +88,34 @@ export interface VfxSpawnParamKeys {
     offsetY?: string;
     offsetZ?: string;
 }
+/** 欧拉角(弧度)/ 三轴缩放的纯数据三元组。 */
+export interface VfxVector3Like {
+    x: number;
+    y: number;
+    z: number;
+}
 export interface VfxSpawnTransform {
     position?: Vector3;
+    /**
+     * 兼容别名:绕 Y 轴旋转(弧度)。
+     * 若同时给了 `rotation`,以 `rotation` 为准;否则回退到 `rotationY`。
+     */
     rotationY?: number;
+    /** 完整欧拉角旋转(弧度);给了就覆盖 `rotationY`。 */
+    rotation?: VfxVector3Like;
+    /** 等比缩放(number)或三轴缩放;默认 1。 */
+    scale?: number | VfxVector3Like;
+    /** 挂载点节点;给了就把特效 root parent 到它(特效随之跟随)。 */
+    parent?: TransformNode;
+    /**
+     * position/rotation/scale 的坐标系解释:
+     * - 给了 `parent` 时默认 `true`:按相对 parent 的 **local** transform 解释;
+     * - 没给 `parent` 时默认 `false`:按 **世界坐标** 解释(保持现状行为)。
+     */
+    offsetIsLocal?: boolean;
     renderingGroupId?: number;
+    /** 运行时外部信息(瞄准点/法线/端点/目标 mesh);值可为静态或 provider(动态每帧取)。 */
+    inputs?: VfxEffectInputs;
 }
 export interface VfxParamsFile {
     schemaVersion: string;
@@ -69,6 +123,15 @@ export interface VfxParamsFile {
     updatedAt?: string | null;
     params?: Partial<VfxParamValues>;
 }
+/**
+ * 特效的放置本质(内禀标记)。决定系统/binding/面板怎么放它,不靠猜。见 docs/vfx-placement-design.md。
+ * - 'socket' local:挂对象命名挂点、随它走(parent + follow)。
+ * - 'world'  global:放世界某点、不跟随(fire-and-forget,可按法线定向)。
+ * - 'screen' global:屏幕/相机层(后处理/相机扰动/DOM 全屏),无 3D transform。
+ * - 'target' 改目标自身材质/渲染态,没有可 spawn 的 root。
+ * - 'link'   连 ≥2 个端点(每帧重建几何),单 parent 表达不了。
+ */
+export type VfxPlacement = 'socket' | 'world' | 'screen' | 'target' | 'link';
 export interface VfxEffectPackage<PParams extends VfxParamValues = VfxParamValues> {
     id: string;
     nameZh: string;
@@ -78,6 +141,23 @@ export interface VfxEffectPackage<PParams extends VfxParamValues = VfxParamValue
     spawnParams?: VfxSpawnParamKeys;
     savedParams?: Partial<VfxParamValues>;
     debugParams: VfxParamDefinition[];
+    /** 放置本质标记(默认 'world')。 */
+    placement?: VfxPlacement;
+    /** 声明**必需**的运行时 inputs(link 必须给 endpoints/aim、target 类必须给 target mesh);service 缺失时 warn。 */
+    requiredInputs?: VfxInputKey[];
+    /** 声明**可选**的运行时 inputs(给了就用、不给走默认,如定向武器的 aim:给了朝目标、不给走挂点朝向);不触发缺失 warn(G2)。 */
+    optionalInputs?: VfxInputKey[];
+    /**
+     * 几何空间:'local'=几何挂 root 子节点随它刚性变换;'world'=几何用世界坐标、root 仅作每帧采样源(拖尾)。
+     * 默认随 placement 推断('socket'→local,其余→world)。
+     */
+    geometrySpace?: 'local' | 'world';
+    /**
+     * 构建特效。**约定(G6):root 的 transform(position/rotation/scaling/parent)归 service 独占** ——
+     * service 在 create() 后会二次 `applySpawnToRoot` 覆盖,create 内写 `root.position/rotation/scaling` 会被静默清掉。
+     * 需要内部局部偏移(如抬升)请用 root 下的**子 TransformNode** 承载,或声明 `spawnParams.offsetY` 走 service 存活通道。
+     * 几何挂 root 子树即随挂载跟随;world/拖尾类几何走世界坐标、读 ctx.scale 缩放。
+     */
     create(context: VfxEffectPackageContext<PParams>): VfxEffectHandle;
 }
 export type VfxDebugOverrides = Record<string, Partial<VfxParamValues>>;

package/docs/INTEGRATION.md

@@ -0,0 +1,194 @@
+# 新项目集成 @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` |

package/docs/hit-flash-red-method.md

@@ -0,0 +1,155 @@
+# 方法:物体受击闪红(Hit Flash)
+
+> 给「**被击中的那个物体**」加一个受击瞬间染红 / 保持 / 淡回的反馈。供 coding agent 直接套用。
+> 移植自 axe_and_bear 的 `HitFlashService`(熊被斧子打到时整只变红)。
+
+## 它和普通特效的本质区别 —— 先读这段
+
+- 普通 VFX(爆炸、拖尾、命中爆闪)是 **在某个位置 spawn 一团东西**(粒子/网格),和被打的物体无关。
+- 受击闪红是 **修改被打物体自己的材质颜色**(`emissiveColor`)。它没有"自己的网格",寄生在目标身上。
+
+所以它**不是 `@fps/vfx` 的 `VfxEffectPackage`**(那个契约是 `create({position}) → 在该点生成`)。
+不要试图 `vfx add hit-flash`。正确做法是把下面这个工具类放进**宿主工程**,在你能拿到目标 mesh 的地方用它。
+
+## 原理(一句话)
+
+每个目标 mesh:**克隆一份材质**(防止污染共享材质)→ 存下原始 `emissiveColor` → 受击时把 emissive 插值到红色,`holdTime` 秒保持全红,`fadeTime` 秒线性淡回原色。
+
+```
+play()  ┌─ holdTime ─┐┌──── fadeTime ────┐
+红度 1.0 ████████████░░░░░░░░░░░░░░░░░░░░  → 回到原 emissive
+       命中                              结束
+```
+红度 `t` → `emissive = Lerp(原色, Lerp(原色, 红, flashStrength), t)`
+
+## 完整实现(复制即用)
+
+```ts
+// hit-flash.ts —— 放进宿主工程(不是 @fps/vfx)
+import { Color3 } from '@babylonjs/core/Maths/math.color';
+import type { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
+import type { Material } from '@babylonjs/core/Materials/material';
+import type { Scene } from '@babylonjs/core/scene';
+import type { Observer } from '@babylonjs/core/Misc/observable';
+
+export interface HitFlashOptions {
+  flashColor?: Color3;     // 闪光色,默认红 (1,0,0)
+  flashStrength?: number;  // 0..1,红色混入强度(1=完全替换),默认 1
+  holdTime?: number;       // 全红保持秒,默认 0.2
+  fadeTime?: number;       // 淡回原色秒,默认 0.1
+  emissiveBoost?: number;  // HDR 倍率:有 bloom/tonemapping 时调大(默认 3.4);无后处理用 1
+}
+
+interface FlashEntry { mat: Material & { emissiveColor?: Color3 }; original: Color3; }
+
+export class HitFlash {
+  private entries: FlashEntry[] = [];
+  private readonly flashColor: Color3;
+  private readonly flashStrength: number;
+  private readonly holdTime: number;
+  private readonly fadeTime: number;
+  private elapsed = 0;
+  private total = 0;
+  private observer: Observer<Scene> | null = null;
+
+  /** meshes:目标物体的所有可见 mesh(通常 root.getChildMeshes())。一个目标建一次,反复 play()。 */
+  constructor(meshes: AbstractMesh[], private readonly scene: Scene, opts: HitFlashOptions = {}) {
+    this.flashColor = (opts.flashColor ?? new Color3(1, 0, 0)).scale(opts.emissiveBoost ?? 3.4);
+    this.flashStrength = opts.flashStrength ?? 1;
+    this.holdTime = opts.holdTime ?? 0.2;
+    this.fadeTime = opts.fadeTime ?? 0.1;
+    for (const mesh of meshes) {
+      const src = mesh.material;
+      if (!src || !('emissiveColor' in src)) continue;
+      // 关键:克隆材质,否则会染红所有共用此材质的物体
+      const cloned = (src.clone(`${src.name}_hitflash`) ?? src) as FlashEntry['mat'];
+      mesh.material = cloned;
+      this.entries.push({ mat: cloned, original: (cloned.emissiveColor ?? Color3.Black()).clone() });
+    }
+  }
+
+  /** 每次受击调用。连续受击会刷新到峰值(不叠加爆掉)。 */
+  play(): void {
+    this.elapsed = 0;
+    this.total = this.holdTime + this.fadeTime;
+    if (!this.observer) {
+      this.observer = this.scene.onBeforeRenderObservable.add(() => this.update());
+    }
+    this.apply(1);
+  }
+
+  private update(): void {
+    this.elapsed += this.scene.getEngine().getDeltaTime() / 1000;
+    if (this.elapsed <= this.holdTime) {
+      this.apply(1);
+    } else if (this.elapsed < this.total) {
+      this.apply(Math.max(0, 1 - (this.elapsed - this.holdTime) / this.fadeTime));
+    } else {
+      this.apply(0);
+      this.detach();
+    }
+  }
+
+  private apply(t: number): void {
+    for (const e of this.entries) {
+      const target = Color3.Lerp(e.original, this.flashColor, this.flashStrength);
+      e.mat.emissiveColor = Color3.Lerp(e.original, target, t);
+    }
+  }
+
+  private detach(): void {
+    if (this.observer) { this.scene.onBeforeRenderObservable.remove(this.observer); this.observer = null; }
+  }
+
+  /** 目标销毁前调用:恢复原始 emissive + 移除 observer。 */
+  dispose(): void {
+    this.detach();
+    for (const e of this.entries) e.mat.emissiveColor = e.original;
+  }
+}
+```
+
+## 用法
+
+```ts
+// 1) 目标出生时建一次(传它所有可见 mesh)
+const flash = new HitFlash(bear.getChildMeshes(), scene, {
+  flashColor: new Color3(1, 0, 0),  // 红
+  holdTime: 0.2, fadeTime: 0.1,
+});
+
+// 2) 每次被打调用
+function onBearHit() {
+  bear.subHp(dmg);
+  flash.play();          // ← 闪红
+}
+
+// 3) 目标死亡/移除前
+flash.dispose();
+```
+
+## 参数怎么调影响什么
+
+| 参数 | 影响 |
+|---|---|
+| `flashColor` | 闪光颜色。红=受伤;白=普通受击;绿=治疗/buff |
+| `flashStrength` | 红色混入比例。1=峰值完全红;0.5=半红(保留原色感) |
+| `holdTime` | 全红保持时长。越大越"顿挫"/越重 |
+| `fadeTime` | 淡回时长。越大余韵越长越软 |
+| `emissiveBoost` | HDR 倍率。有 bloom/tonemapping 时调大让红更亮更艳(线性空间);无后处理设 1 |
+
+## 必须注意的坑(coding agent 重点看)
+
+1. **一定要克隆材质**。直接改 `mesh.material.emissiveColor` 会染红**所有共用这份材质的物体**(整片同模型一起变红)。上面构造里已 `clone()`。
+2. **用 `emissiveColor` 不是 `diffuseColor`/`albedoColor`**。自发光不受光照影响、像"发光"般醒目,且能吃 bloom;`StandardMaterial` 和 `PBRMaterial` 都有 `emissiveColor`。
+3. **存原色 + dispose 恢复**。目标原本可能就有 emissive(发光怪),必须存原值并在 dispose 时还原,否则残留。
+4. **重复受击**。`play()` 重置计时到峰值 → 连击是"刷新红光"而非叠加,不会爆白。
+5. **observer 生命周期**。淡出结束自动 `detach()`;目标销毁前务必 `dispose()` 移除残留 observer,避免泄漏与"对着已销毁材质写值"。
+6. **PBR + emissiveTexture**:若目标材质带自发光贴图,纯色 emissive 会与贴图相加;受击闪红一般可接受,介意的话可在 play 时临时把 `emissiveTexture` 置 null、dispose 时还原。
+7. **蒙皮/多子网格**:用 `root.getChildMeshes()` 把所有子网格都纳入,漏掉的部位不会变红。
+
+## 可选增强
+
+- **配合受击粒子**:闪红是"染目标",再在命中点叠一个 `@fps/vfx` 的 `monster-hit`(闪光+血)burst,就是完整受击反馈——两者正交,各管一层。
+- **击退/缩放抖动**:`play()` 时顺带给 root 一个轻微 scale punch(1.1→1.0)或位移,手感更冲。
+- **死亡白闪**:把 `flashColor` 设白、`holdTime/fadeTime` 拉长,即死亡瞬间的泛白。