@fps-games/vfx 0.1.1

package/index.json

@@ -0,0 +1,381 @@
+{
+  "schemaVersion": "vfx-index/1.0",
+  "count": 36,
+  "effects": [
+    {
+      "id": "build.particle.lumber_debris_scatter",
+      "dir": "lumber-debris-scatter",
+      "nameZh": "lumber-debris-scatter",
+      "kind": "code",
+      "category": "build",
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/lumber-debris-scatter"
+    },
+    {
+      "id": "build.particle.run_footstep_dust",
+      "dir": "run-footstep-dust",
+      "nameZh": "run-footstep-dust",
+      "kind": "code",
+      "category": "build",
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/run-footstep-dust"
+    },
+    {
+      "id": "build.particle.tree_leaf_chop_burst",
+      "dir": "tree-leaf-chop-burst",
+      "nameZh": "tree-leaf-chop-burst",
+      "kind": "code",
+      "category": "build",
+      "tags": [
+        "babylon",
+        "particle",
+        "tree",
+        "leaf",
+        "chop",
+        "burst"
+      ],
+      "media": {},
+      "path": "packages/effects/tree-leaf-chop-burst"
+    },
+    {
+      "id": "building-upgrade",
+      "dir": "building-upgrade",
+      "nameZh": "建筑升级金光",
+      "kind": "code",
+      "category": "building-upgrade",
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/building-upgrade"
+    },
+    {
+      "id": "character-entrance",
+      "dir": "character-entrance",
+      "nameZh": "人物登场光柱",
+      "kind": "code",
+      "category": "character-entrance",
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/character-entrance"
+    },
+    {
+      "id": "coin-burst",
+      "dir": "coin-burst",
+      "nameZh": "coin-burst",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/coin-burst"
+    },
+    {
+      "id": "comet-trail-flame",
+      "dir": "comet-trail-flame",
+      "nameZh": "comet-trail-flame",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/comet-trail-flame"
+    },
+    {
+      "id": "conveyor-upgrade",
+      "dir": "conveyor-upgrade",
+      "nameZh": "传送带升级光效",
+      "kind": "code",
+      "category": "conveyor-upgrade",
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/conveyor-upgrade"
+    },
+    {
+      "id": "debris-smoke",
+      "dir": "debris-smoke",
+      "nameZh": "debris-smoke",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/debris-smoke"
+    },
+    {
+      "id": "door_open_gold_flakes",
+      "dir": "door_open_gold_flakes",
+      "nameZh": "door_open_gold_flakes",
+      "kind": "data",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/door_open_gold_flakes"
+    },
+    {
+      "id": "electric-arc",
+      "dir": "electric-arc",
+      "nameZh": "electric-arc",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/electric-arc"
+    },
+    {
+      "id": "energy-shield",
+      "dir": "energy-shield",
+      "nameZh": "半球玻璃罩",
+      "kind": "code",
+      "category": "energy-shield",
+      "tags": [
+        "hemisphere",
+        "glass",
+        "dome",
+        "bloom",
+        "shader",
+        "marble",
+        "flow"
+      ],
+      "media": {},
+      "path": "packages/effects/energy-shield"
+    },
+    {
+      "id": "explosion",
+      "dir": "explosion",
+      "nameZh": "explosion",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/explosion"
+    },
+    {
+      "id": "ground-tile-upgrade",
+      "dir": "ground-tile-upgrade",
+      "nameZh": "地块升级光效",
+      "kind": "code",
+      "category": "ground-tile-upgrade",
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/ground-tile-upgrade"
+    },
+    {
+      "id": "hit-flash",
+      "dir": "hit-flash",
+      "nameZh": "hit-flash",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/hit-flash"
+    },
+    {
+      "id": "laser-beam",
+      "dir": "laser-beam",
+      "nameZh": "laser-beam",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/laser-beam"
+    },
+    {
+      "id": "lumber_vehicle_gear_spin",
+      "dir": "lumber_vehicle_gear_spin",
+      "nameZh": "lumber_vehicle_gear_spin",
+      "kind": "data",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/lumber_vehicle_gear_spin"
+    },
+    {
+      "id": "lumber_vehicle_upgrade_aura",
+      "dir": "lumber_vehicle_upgrade_aura",
+      "nameZh": "lumber_vehicle_upgrade_aura",
+      "kind": "data",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/lumber_vehicle_upgrade_aura"
+    },
+    {
+      "id": "lumber_vehicle_wood_chips",
+      "dir": "lumber_vehicle_wood_chips",
+      "nameZh": "lumber_vehicle_wood_chips",
+      "kind": "data",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/lumber_vehicle_wood_chips"
+    },
+    {
+      "id": "lumber-cart-suction",
+      "dir": "lumber-cart-suction",
+      "nameZh": "收集车吸入圆环",
+      "kind": "code",
+      "category": "lumber-cart-suction",
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/lumber-cart-suction"
+    },
+    {
+      "id": "monster-hit",
+      "dir": "monster-hit",
+      "nameZh": "monster-hit",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/monster-hit"
+    },
+    {
+      "id": "player-upgrade",
+      "dir": "player-upgrade",
+      "nameZh": "人物升级光效",
+      "kind": "code",
+      "category": "player-upgrade",
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/player-upgrade"
+    },
+    {
+      "id": "pulse-laser-volley",
+      "dir": "pulse-laser-volley",
+      "nameZh": "pulse-laser-volley",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/pulse-laser-volley"
+    },
+    {
+      "id": "resource-collect-sparkles",
+      "dir": "resource-collect-sparkles",
+      "nameZh": "资源持续收集圆点",
+      "kind": "code",
+      "category": "resource-collect-sparkles",
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/resource-collect-sparkles"
+    },
+    {
+      "id": "thruster-flame",
+      "dir": "thruster-flame",
+      "nameZh": "thruster-flame",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/thruster-flame"
+    },
+    {
+      "id": "tree_chop_dust_burst",
+      "dir": "tree_chop_dust_burst",
+      "nameZh": "tree_chop_dust_burst",
+      "kind": "data",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/tree_chop_dust_burst"
+    },
+    {
+      "id": "tree-chop-dust",
+      "dir": "tree-chop-dust",
+      "nameZh": "砍树烟尘",
+      "kind": "code",
+      "category": "tree-chop-dust",
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/tree-chop-dust"
+    },
+    {
+      "id": "ufo-thread-flame",
+      "dir": "ufo-thread-flame",
+      "nameZh": "ufo-thread-flame",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/ufo-thread-flame"
+    },
+    {
+      "id": "vehicle-exhaust-smoke",
+      "dir": "vehicle-exhaust-smoke",
+      "nameZh": "小车尾气",
+      "kind": "code",
+      "category": "vehicle-exhaust-smoke",
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/vehicle-exhaust-smoke"
+    },
+    {
+      "id": "vehicle-upgrade",
+      "dir": "vehicle-upgrade",
+      "nameZh": "小车升级光效",
+      "kind": "code",
+      "category": "vehicle-upgrade",
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/vehicle-upgrade"
+    },
+    {
+      "id": "weapon-trail",
+      "dir": "weapon-trail",
+      "nameZh": "weapon-trail",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/weapon-trail"
+    },
+    {
+      "id": "wood_crusher_sawdust",
+      "dir": "wood_crusher_sawdust",
+      "nameZh": "wood_crusher_sawdust",
+      "kind": "data",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/wood_crusher_sawdust"
+    },
+    {
+      "id": "wood_cutter_sawdust",
+      "dir": "wood_cutter_sawdust",
+      "nameZh": "wood_cutter_sawdust",
+      "kind": "data",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/wood_cutter_sawdust"
+    },
+    {
+      "id": "wood_peel_material_test",
+      "dir": "wood_peel_material_test",
+      "nameZh": "wood_peel_material_test",
+      "kind": "data",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/wood_peel_material_test"
+    },
+    {
+      "id": "wood-crusher-sawdust",
+      "dir": "wood-crusher-sawdust",
+      "nameZh": "wood-crusher-sawdust",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/wood-crusher-sawdust"
+    },
+    {
+      "id": "wood-cutter-sawdust",
+      "dir": "wood-cutter-sawdust",
+      "nameZh": "wood-cutter-sawdust",
+      "kind": "code",
+      "category": null,
+      "tags": [],
+      "media": {},
+      "path": "packages/effects/wood-cutter-sawdust"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@fps-games/vfx",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Shared VFX library for Playable projects: engine-injected effect packages + runtime. Project-pure (no imports of host project code).",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./effects/*": {
+      "types": "./dist/effects/*/index.d.ts",
+      "import": "./dist/effects/*/index.js"
+    },
+    "./vite": "./tooling/vfx-package-resolution.mjs"
+  },
+  "files": [
+    "dist",
+    "tooling",
+    "packages",
+    "docs",
+    "CHANGELOG.md",
+    "index.json"
+  ],
+  "peerDependencies": {
+    "@babylonjs/core": "^8.0.0",
+    "@babylonjs/loaders": "^8.0.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "validate:boundary": "node tooling/validate-boundary.mjs",
+    "validate:effects": "node tooling/validate-effects.mjs",
+    "check:dist": "node tooling/check-dist-runtime.mjs",
+    "validate": "node tooling/validate.mjs",
+    "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",
+    "release": "node scripts/release.mjs"
+  },
+  "//": "分发=git tag + 提交 dist(做法A):发版前 pnpm build → 提交 dist/ → git tag。消费端 import '@fps/vfx' 解析到 dist;本地开发可用 FPS_VFX_LIBRARY_REPO 切回源码 alias。",
+  "devDependencies": {
+    "@babylonjs/core": "^8.56.2",
+    "@babylonjs/loaders": "^8.56.2",
+    "typescript": "^6.0.3",
+    "vite": "^5.4.21",
+    "vite-plugin-dts": "^5.0.3"
+  }
+}

package/packages/EffectPackageService.ts

@@ -0,0 +1,240 @@
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import type { Scene } from '@babylonjs/core/scene';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { VFX_DEFAULT_GENERATION_PARAMS, VFX_GENERATION_PARAM_KEYS } from './generation';
+import type { VfxRegistry } from './registry';
+import type {
+  VfxColorValue,
+  VfxDebugAnchor,
+  VfxEffectHandle,
+  VfxEffectPackage,
+  VfxParamValue,
+  VfxParamValues,
+  VfxSpawnParamKeys,
+  VfxSpawnTransform,
+} from './types';
+
+export interface EffectPackageServiceOptions {
+  /** 注入的注册表(由项目侧 glob + buildRegistry 构建);库不直接引用项目注册表 */
+  registry: VfxRegistry;
+  getDebugAnchorPosition?: (anchor: VfxDebugAnchor) => Vector3 | null;
+}
+
+const DEFAULT_SPAWN_PARAM_KEYS: Required<Pick<VfxSpawnParamKeys, 'offsetX' | 'offsetY' | 'offsetZ'>> = {
+  offsetX: VFX_GENERATION_PARAM_KEYS.offsetX,
+  offsetY: VFX_GENERATION_PARAM_KEYS.offsetY,
+  offsetZ: VFX_GENERATION_PARAM_KEYS.offsetZ,
+};
+
+export class EffectPackageService {
+  private readonly scene: Scene;
+  private readonly registry: VfxRegistry;
+  private readonly getDebugAnchorPosition?: (anchor: VfxDebugAnchor) => Vector3 | null;
+  private readonly activeHandles = new Set<VfxEffectHandle>();
+  private readonly savedParams: Record<string, Partial<VfxParamValues>>;
+
+  constructor(scene: Scene, options: EffectPackageServiceOptions) {
+    this.scene = scene;
+    this.registry = options.registry;
+    this.getDebugAnchorPosition = options.getDebugAnchorPosition;
+    this.savedParams = cloneOverrideMap(options.registry.savedParams);
+  }
+
+  getEffectPackages(): VfxEffectPackage[] {
+    return this.registry.getEffectPackages();
+  }
+
+  getEffectPackage(effectId: string): VfxEffectPackage | undefined {
+    return this.registry.getEffectPackage(effectId);
+  }
+
+  getMergedParams(effectId: string, explicitParams?: Partial<VfxParamValues>): VfxParamValues | null {
+    const effectPackage = this.getEffectPackage(effectId);
+    if (!effectPackage) return null;
+    return mergeVfxParams(
+      VFX_DEFAULT_GENERATION_PARAMS,
+      effectPackage.defaultParams,
+      effectPackage.savedParams,
+      this.savedParams[effectId],
+      explicitParams,
+    );
+  }
+
+  getDebugOverride(effectId: string): Partial<VfxParamValues> {
+    return cloneParams(this.savedParams[effectId]);
+  }
+
+  setDebugOverride(effectId: string, params: Partial<VfxParamValues>): void {
+    this.savedParams[effectId] = cloneParams(params);
+    const effectPackage = this.getEffectPackage(effectId);
+    if (effectPackage) effectPackage.savedParams = cloneParams(params);
+  }
+
+  playEffectPackage(
+    effectId: string,
+    explicitParams?: Partial<VfxParamValues>,
+    spawnTransform?: VfxSpawnTransform | Vector3,
+  ): VfxEffectHandle | null {
+    const effectPackage = this.getEffectPackage(effectId);
+    if (!effectPackage) {
+      console.warn(`[EffectPackageService] Unknown VFX effect package: ${effectId}`);
+      return null;
+    }
+
+    const params = this.getMergedParams(effectId, explicitParams);
+    if (!params) return null;
+
+    const spawn = this.resolveSpawnTransform(effectPackage, params, spawnTransform);
+    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;
+    let handle: VfxEffectHandle;
+    try {
+      handle = effectPackage.create({
+        scene: this.scene,
+        root,
+        position: spawn.position.clone(),
+        rotationY: spawn.rotationY,
+        renderingGroupId: spawn.renderingGroupId,
+        params: runtimeParams,
+      });
+    } catch (error) {
+      // 错误兜底:单个坏包不得崩掉整个场景(plan §7)
+      console.warn(`[EffectPackageService] effect "${effectId}" create() failed; skipped.`, error);
+      try { root.dispose(); } catch { /* ignore */ }
+      return null;
+    }
+    this.activeHandles.add(handle);
+    const originalDispose = handle.dispose.bind(handle);
+    handle.dispose = () => {
+      this.activeHandles.delete(handle);
+      originalDispose();
+    };
+    return handle;
+  }
+
+  dispose(): void {
+    for (const handle of this.activeHandles) {
+      handle.dispose();
+    }
+    this.activeHandles.clear();
+  }
+
+  private resolveDebugPosition(effectPackage: VfxEffectPackage): Vector3 {
+    const anchor = effectPackage.debugAnchor ?? 'playerRight';
+    const anchorPosition = this.getDebugAnchorPosition?.(anchor);
+    if (anchorPosition) return anchorPosition.clone();
+    const cameraTarget = (this.scene.activeCamera as any)?.target as Vector3 | undefined;
+    if (cameraTarget?.clone) return cameraTarget.clone().addInPlace(new Vector3(1.2, 0, 0));
+    return new Vector3(0, 0, 0);
+  }
+
+  private resolveSpawnTransform(
+    effectPackage: VfxEffectPackage,
+    params: VfxParamValues,
+    spawnTransform?: VfxSpawnTransform | Vector3,
+  ): Required<Pick<VfxSpawnTransform, 'position' | 'rotationY'>> & Pick<VfxSpawnTransform, 'renderingGroupId'> {
+    const normalized = normalizeSpawnTransform(spawnTransform);
+    const basePosition = normalized.position?.clone() ?? this.resolveDebugPosition(effectPackage);
+    const rotationY = readFiniteNumber(normalized.rotationY, 0);
+    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(
+        offset.x * cos - offset.z * sin,
+        offset.y,
+        offset.x * sin + offset.z * cos,
+      )),
+      rotationY,
+      renderingGroupId,
+    };
+  }
+}
+
+function normalizeSpawnTransform(spawnTransform?: VfxSpawnTransform | Vector3): VfxSpawnTransform {
+  if (!spawnTransform) return {};
+  if (spawnTransform instanceof Vector3) return { position: spawnTransform };
+  return spawnTransform;
+}
+
+function readSpawnOffset(params: VfxParamValues, spawnParams?: VfxSpawnParamKeys): Vector3 {
+  const keys = resolveSpawnParamKeys(spawnParams);
+  return new Vector3(
+    readParamNumber(params[keys.offsetX ?? ''], 0),
+    readParamNumber(params[keys.offsetY ?? ''], 0),
+    readParamNumber(params[keys.offsetZ ?? ''], 0),
+  );
+}
+
+function stripSpawnParams(params: VfxParamValues, spawnParams?: VfxSpawnParamKeys): VfxParamValues {
+  const result = cloneParams(params) as VfxParamValues;
+  const keys = resolveSpawnParamKeys(spawnParams);
+  for (const key of [keys.offsetX, keys.offsetY, keys.offsetZ]) {
+    if (key) delete result[key];
+  }
+  return result;
+}
+
+function resolveSpawnParamKeys(spawnParams?: VfxSpawnParamKeys): VfxSpawnParamKeys {
+  return spawnParams ?? DEFAULT_SPAWN_PARAM_KEYS;
+}
+
+function readParamNumber(value: VfxParamValue | undefined, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+function readFiniteNumber(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+function readOptionalFiniteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function mergeVfxParams(
+  ...sources: Array<Partial<VfxParamValues> | undefined>
+): VfxParamValues {
+  const result: Partial<VfxParamValues> = {};
+  for (const source of sources) {
+    Object.assign(result, cloneParams(source));
+  }
+  return result as VfxParamValues;
+}
+
+function cloneParams(value: Partial<VfxParamValues> | undefined): Partial<VfxParamValues> {
+  if (!value) return {};
+  const result: Partial<VfxParamValues> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (item === undefined) continue;
+    result[key] = cloneParamValue(item);
+  }
+  return result;
+}
+
+function cloneOverrideMap(value: Record<string, Partial<VfxParamValues>>): Record<string, Partial<VfxParamValues>> {
+  const result: Record<string, Partial<VfxParamValues>> = {};
+  for (const [effectId, params] of Object.entries(value)) {
+    result[effectId] = cloneParams(params);
+  }
+  return result;
+}
+
+function cloneParamValue(value: VfxParamValue): VfxParamValue {
+  if (isColorValue(value)) return { ...value };
+  return value;
+}
+
+function isColorValue(value: unknown): value is VfxColorValue {
+  return !!value
+    && typeof value === 'object'
+    && !Array.isArray(value)
+    && typeof (value as VfxColorValue).r === 'number'
+    && typeof (value as VfxColorValue).g === 'number'
+    && typeof (value as VfxColorValue).b === 'number';
+}