@fps-games/vfx 0.1.1 → 0.3.2

package/docs/vfx-placement-design.md

@@ -0,0 +1,164 @@
+# VFX 放置系统设计(定稿)
+
+> 把"特效怎么被放置/触发"从隐式实现升为**显式契约**。结论来自 #9 的挂载/attach 设计 + "只挂点是否充分"的对抗式反证(#9 评论)。
+> 核心裁决:**挂点(socket)是默认主路径,但不是唯一**;每个特效用一个 `placement` 标记声明它的放置本质,binding 按标记提供对应输入。
+
+## 1. 核心原则
+
+1. **放置基元是 position**(必要时 + 法线 / + 第二端点),`socket-follow` 只是其中一个特例;**不要反过来把 position 当"挂点的壳"**。
+2. **每个特效声明 `placement` 标记**(它的放置本质,内禀属性)。系统/binding/面板**读标记决定怎么放**,不靠猜。
+3. **socket 与动态坐标都只是"位置来源"**:一个来自数据(prefab 上的命名挂点),一个来自触发事件(运行时算出的世界坐标)。Director 用同一套"取位置 → 放特效",只是取法不同。
+4. **错误挡在运行时之前**:placement 与 binding 的匹配在构建/编辑期校验(guardrail),不到运行时才炸。
+
+## 2. `placement` 标记(特效级,内禀)
+
+```ts
+type VfxPlacement =
+  | 'socket'   // local:挂对象的命名挂点、随它走(parent + follow)
+  | 'world'    // global:放在世界某点、不跟随(fire-and-forget,可带法线定向)
+  | 'screen'   // global:屏幕/相机层(后处理 pass / 相机扰动 / DOM 全屏),无 3D transform
+  | 'target'   // 改目标自身材质/渲染态(给 targetMesh + 时序),没有可 spawn 的 root
+  | 'link';    // 连 ≥2 个端点(每帧重建几何),单 parent 表达不了
+```
+
+### `socket` 的朝向子类(创作/集成需区分)
+
+挂点不仅是"位置",对部分特效**朝向也是语义**:
+
+| 子类 | 朝向是否关键 | 还需目标? | 例 |
+|---|---|---|---|
+| **位置型** | 否(只要位置) | 否 | energy-shield、各 upgrade 光环、跟随 DoT |
+| **朝向型** | 是(挂点 +Z/-Z = 喷射方向) | 否 | thruster-flame(+Z 朝机尾)、ufo-thread-flame(-Z)、comet-trail |
+| **定向武器** | 是(挂点 +Z = 发射方向) | **是**(炮口朝目标) | pulse-laser-volley(沿 +Z 齐射)、laser-beam(link,A→B) |
+
+→ 集成/测试时:朝向型必须把挂点朝向摆对;定向武器还要在场景里给一个**目标**,炮口朝它(否则乱喷)。`laser-beam` 因有真实第二端点归 `link`;`pulse-laser-volley` 是"socket + 发射方向",目标只决定方向/射程(targetDistance),不追踪第二实体。
+
+辅助标志(不是第六种空间,而是 socket/world 的机制修饰):
+```ts
+interface VfxPlacementMeta {
+  placement: VfxPlacement;
+  // 几何空间:'local'=挂 root 子节点随它刚性变换;'world'=几何用世界坐标、root 仅作每帧采样源(拖尾)
+  geometrySpace?: 'local' | 'world';
+  // 实例化宿主要挂真 spawn 特效时:'matrix-follow'=建跟随 instance world matrix 的临时锚;'de-instance'=先物化成 standalone mesh
+  instancing?: 'none' | 'matrix-follow' | 'de-instance';
+}
+```
+
+| 标记 | local/global | 需要挂点 | 怎么放 | 典型特效 |
+|---|---|---|---|---|
+| `socket` | local | ✅ 一个挂点 | parent 到 socket,场景图跟随 | thruster-flame、energy-shield、弹体拖尾、跟随敌人的 DoT |
+| `world` | global | ❌ 一个世界坐标 | 在该点 spawn、不跟随、自销;可按法线定向 | monster-hit、explosion、run-footstep-dust、落点圈、telegraph |
+| `screen` | global | ❌ | 后处理参数 / 相机扰动 / DOM 全屏 / worldToScreen | vignette、死亡白屏闪、镜头抖、金币飞 HUD |
+| `target` | — | ❌ 一个目标 mesh | 改宿主自身材质 emissive/渲染态(tween) | hit-flash(染红)、dissolve、freeze、区域高亮 |
+| `link` | global | ❌ ≥2 端点 | 每帧按两端重建几何 | laser-beam(A→B)、链式闪电、resource-collect(from→target)、tether |
+
+## 3. 位置来源(binding 级)
+
+binding 不假定一个 `socket`,而是显式声明位置来源:
+
+```ts
+type VfxPositionSource =
+  | { kind: 'socket'; target: string; socket: string }          // 静态:prefab 上命名挂点(随对象走)
+  | { kind: 'event'; field: string }                            // 动态:从触发事件 ctx 取世界坐标
+  | { kind: 'world'; position: Vec3 }                           // 固定世界坐标(静态场景特效)
+  | { kind: 'link'; from: VfxPositionSource; to: VfxPositionSource } // 双端点(各可 socket/event)
+  | { kind: 'screen' }                                          // 无 3D 位置
+  | { kind: 'target'; field: string };                          // 目标 mesh(从 ctx 取)
+```
+
+**动态坐标类(`world`)的标准处理**:位置由**触发事件携带**(检测到事件的游戏逻辑本就算出来了),不存 socket、不建锚点:
+```ts
+// 游戏逻辑(已有命中点):
+vfx.emit('enemy.hit', { at: hitPoint, normal: hitNormal });
+```
+```jsonc
+// binding:
+{ "trigger": "enemy.hit", "effect": "monster-hit",
+  "placement": "world",
+  "positionSource": { "kind": "event", "field": "at" },
+  "alignTo": "normal",          // 可选:按法线定向(贴花/冲击波)
+  "lifecycle": "oneshot" }      // 播完自销,不 parent → 零锚点生命周期 → 不会泄漏
+```
+→ **不 parent、不建临时锚点**,这是最简、最不易 bug 的情形(不是最复杂)。
+
+## 3.5 inputs 通道(运行时外部信息)
+
+`position`/`rotation` 解决"挂哪、朝哪",但**激光的瞄准点、贴花的法线、链式的多端点、染红的目标 mesh** 这类**运行时外部信息**装不进 position+params。把三者分开:
+
+| | 是什么 | 谁提供 | 何时定 |
+|---|---|---|---|
+| placement/transform | 挂哪、位置、朝向 | 挂点/事件 | 放置时 |
+| **params** | 可调外观旋钮(颜色/长度/速度) | 美术 | **设计期**,存 vfx-params.json |
+| **inputs** | 运行时外部上下文(瞄准点/法线/端点/目标) | **游戏逻辑** | **运行时**,常**动态** |
+
+> ⚠️ laser 现把 `targetDistance` 塞进 params 是 hack——真瞄准点是运行时外部信息,应迁到 `inputs.aim`。
+
+**播放接口**(签名不变,spawn 里加 inputs 通道):
+```ts
+playEffectPackage(id, params, {
+  parent?, position?, rotation?, scale?, offsetIsLocal?,   // 放置
+  inputs?: {                                               // 外部信息
+    aim?:       Vector3 | (() => Vector3);    // 瞄准点(激光/定向)
+    normal?:    Vector3 | (() => Vector3);    // 表面法线(贴花/冲击)
+    endpoints?: Array<Vector3 | (() => Vector3)>;  // link/链式(≥2 端点)
+    target?:    AbstractMesh;                  // target-material 类
+  },
+})
+```
+- 特效契约声明 `requiredInputs: ('aim'|'normal'|'endpoints'|'target')[]` → **构建期校验**(link 必须给 endpoints/aim;target 类必须给 target mesh;漏了即红)。
+- **`value | (() => value)`**:静态值 or provider——移动目标用 provider **每帧追**。
+- create() 收到的 inputs 已**归一化为访问器**(`inputs.aim()` 总可调用)。
+- 词汇表**小而固定**(覆盖 §2 的 5 模式),不是任意 blob → 通用 + 类型安全。对齐引擎:Niagara *User Parameters* / VFX Graph *Exposed Properties* / GAS *GameplayCueParameters*。
+
+**laser 迁移示例**:
+```ts
+// 现状 hack:只能朝正前方固定距离
+beamRoot.scaling.z = params.targetDistance;
+// 迁移后:placement:'link', requiredInputs:['aim']
+create({ root, params, inputs }) {
+  scene.onBeforeRenderObservable.add(() => {
+    const tgt = inputs.aim();                      // 每帧取(可动态)
+    beamRoot.scaling.z = tgt.subtract(root.getAbsolutePosition()).length();  // 束长=到目标距离
+    root.lookAt(tgt);                              // 朝目标
+  });
+}
+// 调用:静态 { inputs:{ aim: towerPos } } / 动态 { inputs:{ aim: () => enemy.getWorldPosition() } }
+```
+**契约改动(已实现)**:`VfxSpawnTransform.inputs`、`VfxEffectPackageContext.inputs`(归一化访问器)、`VfxEffectPackage.requiredInputs`。首批迁移:laser-beam、pulse-laser-volley。
+
+## 4. Binding schema(Director 读它 spawn)
+
+```jsonc
+{
+  "trigger": "enemy.hit",                 // 语义事件(或 entity.spawned 等生命周期)
+  "effect": "monster-hit",                // 特效 id
+  "placement": "world",                   // 与特效的 placement 标记一致(校验)
+  "positionSource": { "kind": "event", "field": "at" },
+  "params": { "bloodCount": 24 },         // 该实例的参数(override,见多实例)
+  "lifecycle": "oneshot",                 // oneshot 自销 / follow 随宿主生灭
+  "alignTo": "normal"                     // 可选
+}
+```
+多实例(一对多)= 多条 binding 或一条带 instances 数组,每条带自己的 positionSource + params(见 #9 评论"每实例独立参数")。
+
+## 5. 校验规则(guardrail,构建/编辑期)
+
+- `placement: 'socket'` → positionSource 必须是 `socket`(或 `event` 提供 node);否则报错。
+- `placement: 'world'` → positionSource 必须给得出世界坐标(`event`/`world`/`socket`)。
+- `placement: 'link'` → positionSource 必须是 `link`(两端齐全)。
+- `placement: 'screen'/'target'` → 不得有 socket/position;`target` 必须给 targetMesh 来源。
+- 每条 binding 的 `effect` id、`socket` 名(对真实 prefab)、`trigger` 名都校验存在 → 拼错/挂点删了**构建即红**。
+- trigger / effect id 用生成的联合类型,编译器先挡一道。
+
+## 6. 落地分期
+
+- **P0**(已在 feat/spawn-attach-p0 / PR #10):完整旋转+缩放+可选挂载 spawn transform;双偏移修复(root 摆放归 service 独占)。
+- **P1**(本分支):给契约加 `placement` 标记 + 给现有特效标注;`world` 类的"事件携带坐标 + 自销"路径;校验规则。
+- **P2**:Director + binding 表(声明式 trigger→effect→placement→params);socket/de-instance 解析层;`link`/`screen`/`target` 的放置实现。
+- **P3**:调试面板按 placement 标记路由 + 每特效真实 GLB 测试场景。
+
+## 7. 反模式(别做)
+1. 别把世界空间拖尾/动态命中点/双锚点/屏幕后处理/改材质**硬塞进挂点模型**——撑破模型、把 bug 赶进运行时临时锚点。
+2. `world` 类**别建临时锚点节点**——直接在事件携带的坐标 spawn、自销,零锚点。
+3. 别让每个 adapter 各自实现放置——收敛进 Director + 解析层。
+4. 别运行时热翻转 placement——创作期决策。

package/index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "vfx-index/1.0",
-  "count": 36,
+  "count": 37,
   "effects": [
     {
       "id": "build.particle.lumber_debris_scatter",
@@ -267,6 +267,24 @@
       "media": {},
       "path": "packages/effects/thruster-flame"
     },
+    {
+      "id": "treasure-attention",
+      "dir": "treasure-attention",
+      "nameZh": "宝藏注意力光效",
+      "kind": "code",
+      "category": "treasure-attention",
+      "tags": [
+        "treasure",
+        "attention",
+        "pickup",
+        "gold",
+        "sparkle",
+        "aura",
+        "ring"
+      ],
+      "media": {},
+      "path": "packages/effects/treasure-attention"
+    },
     {
       "id": "tree_chop_dust_burst",
       "dir": "tree_chop_dust_burst",

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@fps-games/vfx",
-  "version": "0.1.1",
+  "version": "0.3.2",
   "type": "module",
   "description": "Shared VFX library for Playable projects: engine-injected effect packages + runtime. Project-pure (no imports of host project code).",
+  "publishConfig": {
+    "access": "public"
+  },
   "types": "./dist/index.d.ts",
   "module": "./dist/index.js",
   "exports": {
@@ -38,6 +41,7 @@
     "test:guardrails": "node tooling/test-guardrails.mjs",
     "generate:index": "node tooling/generate-index.mjs",
     "demo:energy-shield": "vite demo/energy-shield --host 127.0.0.1",
+    "demo:treasure-attention": "vite demo/treasure-attention --host 127.0.0.1",
     "release": "node scripts/release.mjs"
   },
   "//": "分发=git tag + 提交 dist(做法A):发版前 pnpm build → 提交 dist/ → git tag。消费端 import '@fps/vfx' 解析到 dist;本地开发可用 FPS_VFX_LIBRARY_REPO 切回源码 alias。",

package/packages/EffectPackageService.ts

@@ -7,9 +7,12 @@ import type {
   VfxColorValue,
   VfxDebugAnchor,
   VfxEffectHandle,
+  VfxEffectInputs,
   VfxEffectPackage,
+  VfxInputKey,
   VfxParamValue,
   VfxParamValues,
+  VfxResolvedInputs,
   VfxSpawnParamKeys,
   VfxSpawnTransform,
 } from './types';
@@ -85,20 +88,28 @@ export class EffectPackageService {
     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);
+    // 世界位置(挂到 parent 后即为绝对世界坐标):保证世界空间特效(如拖尾)起点正确。
+    const worldPosition = root.getAbsolutePosition().clone();
     let handle: VfxEffectHandle;
     try {
       handle = effectPackage.create({
         scene: this.scene,
         root,
-        position: spawn.position.clone(),
+        position: worldPosition,
         rotationY: spawn.rotationY,
         renderingGroupId: spawn.renderingGroupId,
         params: runtimeParams,
+        scale: spawn.scale,
+        inputs: spawn.inputs,
       });
+      // root 的摆放归 service 独占。许多特效在 create() 里会写 `root.position.copyFrom(position)`
+      // (用世界坐标),挂到 parent 时会与 local offset 冲突 → 双偏移。这里在 create() 之后
+      // 重新断言一次 root transform,覆盖回 spawn 的正确值(无 parent 时为同值,无副作用)。
+      applySpawnToRoot(root, spawn);
     } catch (error) {
       // 错误兜底:单个坏包不得崩掉整个场景(plan §7)
       console.warn(`[EffectPackageService] effect "${effectId}" create() failed; skipped.`, error);
@@ -111,6 +122,9 @@ export class EffectPackageService {
       this.activeHandles.delete(handle);
       originalDispose();
     };
+    // G4/M4:很多特效内部用 scheduleLifetime 自销,直接 dispose root(绕过上面 wrap 的 handle.dispose),
+    // 会让 activeHandles 残留已死 handle。监听 root 销毁 → 任何路径销毁都清理(自销/手动皆覆盖)。
+    handle.root.onDisposeObservable.addOnce(() => { this.activeHandles.delete(handle); });
     return handle;
   }
 
@@ -134,27 +148,119 @@ export class EffectPackageService {
     effectPackage: VfxEffectPackage,
     params: VfxParamValues,
     spawnTransform?: VfxSpawnTransform | Vector3,
-  ): Required<Pick<VfxSpawnTransform, 'position' | 'rotationY'>> & Pick<VfxSpawnTransform, 'renderingGroupId'> {
+  ): ResolvedSpawnTransform {
     const normalized = normalizeSpawnTransform(spawnTransform);
-    const basePosition = normalized.position?.clone() ?? this.resolveDebugPosition(effectPackage);
-    const rotationY = readFiniteNumber(normalized.rotationY, 0);
+    const parent = normalized.parent ?? null;
+    // 有 parent(挂载)时默认落在挂点 (0,0,0) local;无 parent 时才回退到 debug 锚点(预览用)。
+    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);
+    // 默认坐标系:给了 parent → local;没给 → 世界(保持现状)。
+    const offsetIsLocal = normalized.offsetIsLocal ?? parent != null;
     const renderingGroupId = readOptionalFiniteNumber(normalized.renderingGroupId);
     const offset = readSpawnOffset(params, effectPackage.spawnParams);
-    if (offset.lengthSquared() <= 0.0000001) {
-      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() > 0.0000001) {
+      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) };
+  }
+}
+
+// 把调用方的 inputs(值 or provider)归一化为访问器:create() 里 inputs.aim() 总可调用(动态目标每帧取)。
+function normalizeInputs(inputs?: VfxEffectInputs): VfxResolvedInputs | undefined {
+  if (!inputs) return undefined;
+  const asFn = <T>(v: T | (() => T) | undefined): (() => T) | undefined =>
+    v == null ? undefined : (typeof v === 'function' ? v as () => T : () => v);
+  const out: VfxResolvedInputs = {};
+  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;
+}
+
+// G2:特效声明 requiredInputs 但调用方未提供对应 inputs → 警告(漏接静默降级很难查)。optionalInputs 不在此列。
+function warnMissingRequiredInputs(effectId: string, required: VfxInputKey[] | undefined, inputs: VfxResolvedInputs | undefined): void {
+  if (!required || required.length === 0) return;
+  const missing = required.filter((k) => {
+    const v = inputs ? (inputs as Record<string, unknown>)[k] : undefined;
+    return v == null || (k === 'endpoints' && Array.isArray(v) && v.length < 2);
+  });
+  if (missing.length > 0) {
+    console.warn(`[EffectPackageService] effect "${effectId}" 声明 requiredInputs [${missing.join(', ')}] 但未提供 → 可能静默降级。`);
+  }
+}
+
+interface ResolvedSpawnTransform {
+  /** 按 offsetIsLocal 解释的位置:local(相对 parent)或世界坐标。 */
+  position: Vector3;
+  /** 完整欧拉角旋转(弧度)。 */
+  rotation: Vector3;
+  /** 有效 Y 轴旋转(弧度),透传给 create() 上下文(向后兼容)。 */
+  rotationY: number;
+  /** 三轴缩放。 */
+  scale: Vector3;
+  parent: TransformNode | null;
+  offsetIsLocal: boolean;
+  renderingGroupId?: number;
+  inputs?: VfxResolvedInputs;
+}
+
+// 把解析后的 spawn transform 落到 root 节点上。
+//  - 没给 parent:position/rotation/scale 即世界坐标(无 parent 时 local == world),与现状一致。
+//  - 给了 parent + offsetIsLocal(默认):写到 root 的 local transform(随 parent 跟随)。
+//  - 给了 parent + offsetIsLocal=false:position 按绝对世界坐标落位;rotation/scale 仍按 local 应用。
+function applySpawnToRoot(root: TransformNode, spawn: ResolvedSpawnTransform): void {
+  if (spawn.parent) root.parent = spawn.parent;
+  root.rotation.copyFrom(spawn.rotation);
+  root.scaling.copyFrom(spawn.scale);
+  if (spawn.parent && !spawn.offsetIsLocal) {
+    // 需要先有 parent 的世界矩阵,才能把世界坐标反解成 local。
+    root.computeWorldMatrix(true);
+    root.setAbsolutePosition(spawn.position);
+  } else {
+    root.position.copyFrom(spawn.position);
   }
+  root.computeWorldMatrix(true);
+}
+
+function resolveRotation(rotation: VfxSpawnTransform['rotation'], rotationY: unknown): Vector3 {
+  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: VfxSpawnTransform['scale']): Vector3 {
+  if (scale == null) return new Vector3(1, 1, 1);
+  if (typeof scale === 'number') {
+    const s = readFiniteNumber(scale, 1);
+    return new Vector3(s, s, s);
+  }
+  return new Vector3(
+    readFiniteNumber(scale.x, 1),
+    readFiniteNumber(scale.y, 1),
+    readFiniteNumber(scale.z, 1),
+  );
 }
 
 function normalizeSpawnTransform(spawnTransform?: VfxSpawnTransform | Vector3): VfxSpawnTransform {

package/packages/effects/coin-burst/index.ts

@@ -13,14 +13,17 @@ const DEFAULT_PARAMS: CoinBurstParams = { count: 6 };
 export const coinBurstEffectPackage: VfxEffectPackage<CoinBurstParams> = {
   id: 'coin-burst',
   nameZh: '金币爆出',
+  placement: 'world',
   debugAnchor: 'playerRight',
   defaultParams: DEFAULT_PARAMS,
   debugParams: [
     { key: 'count', label: '金币数量', kind: 'number', min: 0, max: 20, step: 1 },
   ],
 
-  create({ scene, root, position, params }) {
+  create({ scene, root, position, params, scale, renderingGroupId }) {
     root.position.copyFrom(position);
+    // 金币是世界坐标抛物(不挂 root),root.scaling 作用不到 → 自行用 ctx.scale 缩放尺寸/抛撒/重力(G3/M6)。
+    const s = scale ? scale.x : 1;
     const pool = new FlyerPool(scene);
     const coinMat = new StandardMaterial('vfx_coin_mat', scene);
     coinMat.diffuseColor = new Color3(1, 0.78, 0.1);
@@ -28,8 +31,10 @@ export const coinBurstEffectPackage: VfxEffectPackage<CoinBurstParams> = {
     coinMat.specularColor = new Color3(1, 0.9, 0.4);
     for (let i = 0; i < Math.round(params.count); i++) {
       const c = CreateCylinder('vfx_coin', { diameter: 0.8, height: 0.12, tessellation: 18 }, scene);
+      c.scaling.setAll(s);
+      c.renderingGroupId = renderingGroupId ?? 0;   // M7:补全分组(全库约定)
       c.rotation.x = Math.random() * Math.PI; c.material = coinMat;
-      pool.spawn(c, position, new Vector3((Math.random() - 0.5) * 6, Math.random() * 6 + 4, (Math.random() - 0.5) * 6), 9, 1.9);
+      pool.spawn(c, position, new Vector3((Math.random() - 0.5) * 6 * s, (Math.random() * 6 + 4) * s, (Math.random() - 0.5) * 6 * s), 9 * s, 1.9);
     }
     let disposed = false;
     const disposeTimer = window.setTimeout(() => disposeAll(), 2300);

package/packages/effects/comet-trail-flame/index.ts

@@ -53,6 +53,7 @@ function excludeFromGlow(scene: Scene, mesh: AbstractMesh): void {
 export const cometTrailFlameEffectPackage: VfxEffectPackage<CometTrailFlameParams> = {
   id: 'comet-trail-flame',
   nameZh: '拖尾火焰',
+  placement: 'socket',
   debugAnchor: 'player',
   defaultParams: DEFAULT_PARAMS,
   debugParams: [
@@ -63,7 +64,7 @@ export const cometTrailFlameEffectPackage: VfxEffectPackage<CometTrailFlameParam
     { key: 'tint', label: '火焰色', kind: 'color' },
   ],
 
-  create({ scene, root, position, rotationY, params }) {
+  create({ scene, root, position, rotationY, params, renderingGroupId }) {
     root.position.copyFrom(position);
     root.rotation.y = rotationY;
 
@@ -81,7 +82,7 @@ export const cometTrailFlameEffectPackage: VfxEffectPackage<CometTrailFlameParam
     trailRoot.scaling.z = params.length;
     const a = createTrailPlaneGeo('vfx_trail_a', params.width, 'x', scene);
     const b = createTrailPlaneGeo('vfx_trail_b', params.width, 'y', scene);
-    for (const m of [a, b]) { m.material = mat; m.isPickable = false; m.parent = trailRoot; excludeFromGlow(scene, m); }
+    for (const m of [a, b]) { m.material = mat; m.isPickable = false; m.parent = trailRoot; m.renderingGroupId = renderingGroupId ?? 0; excludeFromGlow(scene, m); }
 
     let t = 0;
     const observer = scene.onBeforeRenderObservable.add(() => {

package/packages/effects/debris-smoke/index.ts

@@ -49,6 +49,7 @@ function loadRockTemplates(scene: Scene): Promise<Mesh[]> {
 export const debrisSmokeEffectPackage: VfxEffectPackage<DebrisSmokeParams> = {
   id: 'debris-smoke',
   nameZh: '碎石烟雾',
+  placement: 'world',
   debugAnchor: 'playerRight',
   defaultParams: DEFAULT_PARAMS,
   debugParams: [

package/packages/effects/electric-arc/index.ts

@@ -18,6 +18,7 @@ const DEFAULT_PARAMS: ElectricArcParams = { radius: 1.2, rate: 48, duration: 0.5
 export const electricArcEffectPackage: VfxEffectPackage<ElectricArcParams> = {
   id: 'electric-arc',
   nameZh: '受击电弧',
+  placement: 'world',
   debugAnchor: 'playerRight',
   defaultParams: DEFAULT_PARAMS,
   debugParams: [

package/packages/effects/energy-shield/index.ts

@@ -226,6 +226,7 @@ void main(void) {
 export const energyShieldEffectPackage: VfxEffectPackage<EnergyShieldParams> = {
   id: 'energy-shield',
   nameZh: '半球玻璃罩',
+  placement: 'socket',
   defaultParams: DEFAULT_PARAMS,
   debugAnchor: 'player',
   manifest: {

package/packages/effects/explosion/index.ts

@@ -37,6 +37,7 @@ interface Flash { mesh: Mesh; mat: StandardMaterial; from: number; to: number; l
 export const explosionEffectPackage: VfxEffectPackage<ExplosionParams> = {
   id: 'explosion',
   nameZh: '爆炸',
+  placement: 'world',
   debugAnchor: 'playerRight',
   defaultParams: DEFAULT_PARAMS,
   debugParams: [
@@ -94,7 +95,7 @@ export const explosionEffectPackage: VfxEffectPackage<ExplosionParams> = {
         const f = flashes[i]; f.life += dt; const k = Math.min(1, f.life / f.maxLife);
         f.mesh.scaling.setAll(f.from + (f.to - f.from) * Math.sqrt(k));
         f.mat.alpha = 1 - k;
-        if (k >= 1) { f.mesh.dispose(); f.mat.dispose(); flashes.splice(i, 1); }
+        if (k >= 1) { f.mesh.dispose(); f.mat.dispose(false, true); flashes.splice(i, 1); }
       }
     });
 
@@ -104,7 +105,7 @@ export const explosionEffectPackage: VfxEffectPackage<ExplosionParams> = {
       if (disposed) return; disposed = true;
       window.clearTimeout(disposeTimer);
       scene.onBeforeRenderObservable.remove(observer as Observer<Scene>);
-      for (const f of flashes) { f.mesh.dispose(); f.mat.dispose(); }
+      for (const f of flashes) { f.mesh.dispose(); f.mat.dispose(false, true); }
       flashes.length = 0;
       sparksPs.dispose(); embersPs.dispose();
       root.dispose();

package/packages/effects/hit-flash/index.ts

@@ -28,9 +28,18 @@ function makeFlareTexture(scene: Scene, inner = '255,255,255', outer = '90,160,2
   return dt;
 }
 
+// 贴图内容恒定:按 scene 缓存共享,免每发命中重建+GPU 上传(M2)。
+const flareByScene = new WeakMap<Scene, DynamicTexture>();
+function getFlareTexture(scene: Scene): DynamicTexture {
+  let dt = flareByScene.get(scene);
+  if (!dt || (dt as { isDisposed?: boolean }).isDisposed) { dt = makeFlareTexture(scene); flareByScene.set(scene, dt); }
+  return dt;
+}
+
 export const hitFlashEffectPackage: VfxEffectPackage<HitFlashParams> = {
   id: 'hit-flash',
   nameZh: '命中蓝白爆闪',
+  placement: 'world',
   debugAnchor: 'playerRight',
   defaultParams: DEFAULT_PARAMS,
   debugParams: [
@@ -41,9 +50,8 @@ export const hitFlashEffectPackage: VfxEffectPackage<HitFlashParams> = {
 
   create({ scene, root, position, params }) {
     root.position.copyFrom(position);
-    const flareTex = makeFlareTexture(scene);
     const ps = new ParticleSystem('vfx_hit_ps', 400, scene);
-    ps.particleTexture = flareTex;
+    ps.particleTexture = getFlareTexture(scene);
     ps.emitter = position.clone();
     ps.minEmitBox = new Vector3(-0.1, -0.1, -0.1); ps.maxEmitBox = new Vector3(0.1, 0.1, 0.1);
     ps.direction1 = new Vector3(-1, -1, -1); ps.direction2 = new Vector3(1, 1, 1);
@@ -62,7 +70,7 @@ export const hitFlashEffectPackage: VfxEffectPackage<HitFlashParams> = {
     function disposeAll(): void {
       if (disposed) return; disposed = true;
       window.clearTimeout(disposeTimer);
-      ps.dispose(); flareTex.dispose(); root.dispose();
+      ps.dispose(false); root.dispose();   // dispose(false):共享缓存纹理不随实例销毁
     }
     return { root, dispose() { disposeAll(); } };
   },

package/packages/effects/laser-beam-factory.ts

@@ -7,6 +7,8 @@ import { CreatePlane } from '@babylonjs/core/Meshes/Builders/planeBuilder';
 import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
 import { Texture } from '@babylonjs/core/Materials/Textures/texture';
 import { Color3 } from '@babylonjs/core/Maths/math.color';
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import { Space } from '@babylonjs/core/Maths/math.axis';
 import { Constants } from '@babylonjs/core/Engines/constants';
 import type { Scene } from '@babylonjs/core/scene';
 import type { VfxEffectPackage, VfxParamValues } from '../types';
@@ -43,7 +45,9 @@ function createBeamPlaneGeo(name: string, width: number, axis: 'x' | 'y', scene:
 export function createLaserBeamEffectPackage(id: string, nameZh: string, core: LaserCoreDefaults): VfxEffectPackage<LaserBeamParams> {
   const defaultParams = { ...LIFETIME_DEFAULTS, ...core } as LaserBeamParams;
   return {
-    id, nameZh, defaultParams, debugAnchor: 'playerRight',
+    // 定向武器 = socket 起点(parent 到炮口)+ aim 终点(optionalInputs)。geometrySpace local(束几何挂 root)。
+    // 'link' 留给真·多端点特效(本特效只有单 aim 终点,非 link)。见 #9-A。
+    id, nameZh, defaultParams, debugAnchor: 'playerRight', placement: 'socket', geometrySpace: 'local', optionalInputs: ['aim'],
     debugParams: [
       ...LIFETIME_DEBUG_PARAMS,
       { key: 'width', label: '束宽', kind: 'scale', min: 0.05, max: 2, step: 0.01 },
@@ -51,7 +55,7 @@ export function createLaserBeamEffectPackage(id: string, nameZh: string, core: L
       { key: 'laserSpeed', label: '纹理流速', kind: 'number', min: 0, max: 20, step: 0.5 },
       { key: 'targetDistance', label: '目标距离', kind: 'number', min: 2, max: 40, step: 0.5 },
     ],
-    create({ scene, root, position, rotationY, params }) {
+    create({ scene, root, position, rotationY, params, inputs }) {
       root.position.copyFrom(position);
       root.rotation.y = rotationY;
       const { width, intensity } = params;
@@ -100,7 +104,14 @@ export function createLaserBeamEffectPackage(id: string, nameZh: string, core: L
       const observer = scene.onBeforeRenderObservable.add(() => {
         const dt = Math.min(scene.getEngine().getDeltaTime() / 1000, 0.05);
         time += dt;
-        const dist = params.targetDistance;
+        // 有 inputs.aim:朝目标(束长=到目标距离);无 aim:回退正前方 targetDistance(预览)。
+        let dist = params.targetDistance;
+        if (inputs?.aim) {
+          const tgt = inputs.aim();
+          dist = Vector3.Distance(root.getAbsolutePosition(), tgt);
+          // Space.WORLD:root 挂在挂点上(有父节点),lookAt 默认按 LOCAL 解释目标点,必须显式 WORLD。
+          root.lookAt(tgt, 0, 0, 0, Space.WORLD);
+        }
         beamRoot.scaling.z = dist;
         const tiles = Math.max(1, dist / segLen);
         (arcMat.emissiveTexture as Texture).uScale = tiles; (arcMat.opacityTexture as Texture).uScale = tiles;

package/packages/effects/lumber_vehicle_upgrade_aura/index.ts

@@ -9,3 +9,5 @@ export const lumberVehicleUpgradeAuraEffectPackage = createManifestRuntimeEffect
     'assets/runtime/upgradeAura.v1.js': runtimeUrl,
   },
 });
+// 升级光环挂载具、随它走
+lumberVehicleUpgradeAuraEffectPackage.placement = 'socket';

package/packages/effects/monster-hit/index.ts

@@ -21,7 +21,7 @@ interface MonsterHitParams extends VfxParamValues {
 const DEFAULT_PARAMS: MonsterHitParams = {
   flashCount: 16, flashSize: 1, flashLength: 1, flashBright: 2, flashColor: { r: 1, g: 0.92, b: 0.5 },
   bloodCount: 20, bloodSize: 0.3, bloodGravity: 6, bloodColor: { r: 1, g: 0, b: 0 },
-  height: 1.4,
+  height: 0,
 };
 
 // 程序化贴图(按场景缓存,随场景存活,不在 effect dispose 里销毁)
@@ -45,6 +45,7 @@ function c4(c: VfxColorValue, m = 1, a = 1): Color4 { return new Color4(c.r * m,
 export const monsterHitEffectPackage: VfxEffectPackage<MonsterHitParams> = {
   id: 'monster-hit',
   nameZh: '怪物受击',
+  placement: 'world',
   debugAnchor: 'playerRight',
   defaultParams: DEFAULT_PARAMS,
   debugParams: [