@fps-games/vfx 0.1.1 → 0.3.3

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/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.3",
   "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": {
@@ -18,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"
   ],
@@ -38,6 +42,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/effects/treasure-attention/vfx-params.json

@@ -0,0 +1,49 @@
+{
+  "schemaVersion": "vfx-params/1.0",
+  "effectId": "treasure-attention",
+  "params": {
+    "radius": 1.15,
+    "yOffset": 0.05,
+    "height": 1.35,
+    "rays": 9,
+    "rayWidth": 0.34,
+    "spinSpeed": 0.85,
+    "color": {
+      "r": 1,
+      "g": 0.9,
+      "b": 0.22
+    },
+    "auraColor": {
+      "r": 1,
+      "g": 0.82,
+      "b": 0.18
+    },
+    "ringColor": {
+      "r": 1,
+      "g": 0.95,
+      "b": 0.38
+    },
+    "rayColor": {
+      "r": 1,
+      "g": 0.76,
+      "b": 0.12
+    },
+    "beamColor": {
+      "r": 1,
+      "g": 0.92,
+      "b": 0.32
+    },
+    "opacity": 1,
+    "auraOpacity": 0.82,
+    "ringOpacity": 0.95,
+    "beamOpacity": 0.68,
+    "particleRate": 42,
+    "particleLife": 0.82,
+    "sparkleMinSize": 0.045,
+    "sparkleMaxSize": 0.13,
+    "riseSpeed": 0.72,
+    "drift": 0.12,
+    "bloomIntensity": 0.55,
+    "bloomKernelSize": 32
+  }
+}

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');