@fps-games/vfx 0.1.1 → 0.3.3

package/packages/effects/run-footstep-dust/effect.json

@@ -1,183 +0,0 @@
-{
-  "schemaVersion": "build.particle/v1",
-  "id": "build.particle.run_footstep_dust",
-  "effectId": "run_footstep_dust",
-  "displayName": {
-    "en": "Run Footstep Dust",
-    "zh": "跑动脚步烟尘"
-  },
-  "kind": "runFootstepDust",
-  "runtime": {
-    "runtimeId": "runFootstepDust/v1",
-    "path": "assets/runtime/runFootstepDust.v1.js",
-    "entry": "createRunFootstepDustRuntime"
-  },
-  "assets": {
-    "runtime": [
-      {
-        "id": "run_footstep_dust_runtime",
-        "packagePath": "assets/runtime/runFootstepDust.v1.js"
-      }
-    ],
-    "source": [
-      {
-        "kind": "typescript",
-        "id": "run_footstep_dust_source_ts",
-        "packagePath": "source/src/effects/runFootstepDust.ts",
-        "sourcePath": "D:/project/loy_babylon_particle_test/src/effects/runFootstepDust.ts"
-      }
-    ]
-  },
-  "emitters": [
-    {
-      "name": "run_footstep_dust",
-      "enabled": true,
-      "deterministic": true,
-      "type": "ParticleSystem",
-      "capacity": 64,
-      "count": 6,
-      "frequency": 4.5,
-      "particleColor": "#ffffff",
-      "spread": 0.3,
-      "lifeTime": 0.42,
-      "speed": 0.56,
-      "particleSize": 0.18,
-      "effectScale": 1,
-      "trailOffset": 0.22,
-      "emissionDirection": {
-        "x": 1,
-        "y": 0.2,
-        "z": 0
-      },
-      "gravity": {
-        "x": 0,
-        "y": -0.08,
-        "z": 0
-      },
-      "origin": {
-        "x": 0,
-        "y": 0,
-        "z": 0
-      },
-      "runtime": {
-        "continuous": true,
-        "disposeOnComplete": false
-      }
-    }
-  ],
-  "parameters": [
-    {
-      "key": "count",
-      "label": "Count",
-      "type": "number",
-      "default": 6,
-      "min": 0,
-      "max": 999,
-      "step": 1,
-      "mapsTo": "emitters[0].count",
-      "note": "Particles emitted per dust burst behind the character."
-    },
-    {
-      "key": "frequency",
-      "label": "Frequency",
-      "type": "number",
-      "default": 4.5,
-      "min": 0,
-      "max": 30,
-      "step": 0.01,
-      "mapsTo": "emitters[0].frequency",
-      "note": "Dust bursts per second for continuous playback."
-    },
-    {
-      "key": "particleColor",
-      "label": "Color",
-      "type": "color",
-      "default": "#ffffff",
-      "mapsTo": "emitters[0].particleColor",
-      "note": "Base tint for the dust particles."
-    },
-    {
-      "key": "spread",
-      "label": "Spread",
-      "type": "number",
-      "default": 0.3,
-      "min": 0,
-      "max": 20,
-      "step": 0.01,
-      "mapsTo": "emitters[0].spread"
-    },
-    {
-      "key": "life",
-      "label": "Life",
-      "type": "number",
-      "default": 0.42,
-      "min": 0.01,
-      "max": 20,
-      "step": 0.01,
-      "mapsTo": "emitters[0].lifeTime"
-    },
-    {
-      "key": "speed",
-      "label": "Speed",
-      "type": "number",
-      "default": 0.56,
-      "min": 0,
-      "max": 20,
-      "step": 0.01,
-      "mapsTo": "emitters[0].speed"
-    },
-    {
-      "key": "size",
-      "label": "Size",
-      "type": "number",
-      "default": 1,
-      "min": 0,
-      "max": 20,
-      "step": 0.01,
-      "mapsTo": "emitters[0].particleSize",
-      "note": "Editor multiplies this by base particleSize 0.18."
-    },
-    {
-      "key": "scale",
-      "label": "Scale",
-      "type": "number",
-      "default": 1,
-      "min": 0.01,
-      "max": 20,
-      "step": 0.01,
-      "mapsTo": "emitters[0].effectScale"
-    },
-    {
-      "key": "dirX",
-      "label": "Dir X",
-      "type": "range",
-      "default": 100,
-      "min": -100,
-      "max": 100,
-      "mapsTo": "emitters[0].emissionDirection.x"
-    },
-    {
-      "key": "dirY",
-      "label": "Dir Y",
-      "type": "range",
-      "default": 20,
-      "min": 20,
-      "max": 120,
-      "mapsTo": "emitters[0].emissionDirection.y"
-    },
-    {
-      "key": "dirZ",
-      "label": "Dir Z",
-      "type": "range",
-      "default": 0,
-      "min": -100,
-      "max": 100,
-      "mapsTo": "emitters[0].emissionDirection.z"
-    }
-  ],
-  "notes": [
-    "Continuous Unity-style particle playback: the runtime emits deterministic cartoon dust puffs behind the character at the configured frequency.",
-    "Count controls particles per burst, not total lifetime particles.",
-    "Dust is spawned behind the emitter based on the current direction controls."
-  ]
-}

package/packages/effects/run-footstep-dust/index.ts

@@ -1,377 +0,0 @@
-import { Color4 } from '@babylonjs/core/Maths/math.color';
-import { Matrix, Vector3 } from '@babylonjs/core/Maths/math.vector';
-import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
-import { ParticleSystem } from '@babylonjs/core/Particles/particleSystem';
-import type { Particle } from '@babylonjs/core/Particles/particle';
-import type { Scene } from '@babylonjs/core/scene';
-import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
-import type { VfxColorValue, VfxEffectPackage, VfxParamValues } from '../../types';
-import { VFX_RENDERING_GROUP_ID } from '../../rendering';
-import sourceManifest from './effect.json';
-
-const RUN_FOOTSTEP_DUST_RENDERING_GROUP_ID = VFX_RENDERING_GROUP_ID;
-
-interface RunFootstepDustParams extends VfxParamValues {
-  emitMode: string;
-  lifetime: number;
-  scale: number;
-  initialHeight: number;
-  color: VfxColorValue;
-  opacity: number;
-  count: number;
-  frequency: number;
-  emitInterval: number;
-  spread: number;
-  particleLife: number;
-  speed: number;
-  size: number;
-  trailOffset: number;
-  directionX: number;
-  directionZ: number;
-  lift: number;
-  gravity: number;
-}
-
-interface SourceEmitter {
-  capacity?: unknown;
-  count?: unknown;
-  frequency?: unknown;
-  particleColor?: unknown;
-  spread?: unknown;
-  lifeTime?: unknown;
-  speed?: unknown;
-  particleSize?: unknown;
-  effectScale?: unknown;
-  trailOffset?: unknown;
-  emissionDirection?: { x?: unknown; y?: unknown; z?: unknown };
-  gravity?: { y?: unknown };
-}
-
-const SOURCE_EMITTER = readSourceEmitter();
-const BASE_PARTICLE_SIZE = readNumber(SOURCE_EMITTER.particleSize, 0.18);
-const EFFECT_MANIFEST = {
-  id: 'build.particle.run_footstep_dust',
-  nameZh: '跑动脚步烟尘',
-  assets: [
-    'assets/runtime/runFootstepDust.v1.js',
-  ],
-  source: 'run_footstep_dust.json',
-};
-
-const DEFAULT_PARAMS: RunFootstepDustParams = {
-  emitMode: 'timed',
-  lifetime: 1.35,
-  scale: readNumber(SOURCE_EMITTER.effectScale, 1),
-  initialHeight: 0.04,
-  color: readColor(SOURCE_EMITTER.particleColor, { r: 1, g: 1, b: 1 }),
-  opacity: 1,
-  count: readNumber(SOURCE_EMITTER.count, 6),
-  frequency: readNumber(SOURCE_EMITTER.frequency, 4.5),
-  emitInterval: 1 / Math.max(0.01, readNumber(SOURCE_EMITTER.frequency, 4.5)),
-  spread: readNumber(SOURCE_EMITTER.spread, 0.3),
-  particleLife: readNumber(SOURCE_EMITTER.lifeTime, 0.42),
-  speed: readNumber(SOURCE_EMITTER.speed, 0.56),
-  size: 1,
-  trailOffset: readNumber(SOURCE_EMITTER.trailOffset, 0.22),
-  directionX: readNumber(SOURCE_EMITTER.emissionDirection?.x, 1),
-  directionZ: readNumber(SOURCE_EMITTER.emissionDirection?.z, 0),
-  lift: readNumber(SOURCE_EMITTER.emissionDirection?.y, 0.2),
-  gravity: Math.abs(readNumber(SOURCE_EMITTER.gravity?.y, -0.08)),
-};
-
-export const runFootstepDustEffectPackage: VfxEffectPackage<RunFootstepDustParams> = {
-  id: 'run-footstep-dust',
-  nameZh: '跑动脚步烟尘',
-  manifest: EFFECT_MANIFEST,
-  defaultParams: DEFAULT_PARAMS,
-  debugAnchor: 'player',
-  debugParams: [
-    {
-      key: 'emitMode',
-      label: '发射模式',
-      kind: 'enum',
-      options: [
-        { value: 'loop', label: '持续发射' },
-        { value: 'timed', label: '自定义时间' },
-      ],
-    },
-    { key: 'lifetime', label: '生命周期', kind: 'lifetime', min: 0.08, max: 6, step: 0.01 },
-    { key: 'emitInterval', label: '发射间隔', kind: 'number', min: 0.01, max: 5, step: 0.01 },
-    { key: 'scale', label: '整体缩放', kind: 'scale', min: 0.05, max: 6, step: 0.01 },
-    { key: 'initialHeight', label: '初始高度', kind: 'number', min: -0.5, max: 2, step: 0.01 },
-    { key: 'color', label: '烟尘颜色', kind: 'color' },
-    { key: 'opacity', label: '透明度', kind: 'opacity', min: 0, max: 1, step: 0.01 },
-    { key: 'count', label: '每步粒子数', kind: 'number', min: 0, max: 80, step: 1 },
-    { key: 'frequency', label: '脚步频率', kind: 'number', min: 0, max: 20, step: 0.01 },
-    { key: 'spread', label: '散开范围', kind: 'number', min: 0, max: 4, step: 0.01 },
-    { key: 'particleLife', label: '单粒生命周期', kind: 'number', min: 0.04, max: 3, step: 0.01 },
-    { key: 'speed', label: '飘散速度', kind: 'number', min: 0, max: 5, step: 0.01 },
-    { key: 'size', label: '烟尘大小', kind: 'number', min: 0.05, max: 6, step: 0.01 },
-    { key: 'trailOffset', label: '身后偏移', kind: 'number', min: 0, max: 2, step: 0.01 },
-    { key: 'directionX', label: '方向 X', kind: 'number', min: -1, max: 1, step: 0.01 },
-    { key: 'directionZ', label: '方向 Z', kind: 'number', min: -1, max: 1, step: 0.01 },
-    { key: 'lift', label: '上扬力度', kind: 'number', min: 0, max: 2, step: 0.01 },
-    { key: 'gravity', label: '下沉重力', kind: 'number', min: 0, max: 3, step: 0.01 },
-  ],
-  create({ scene, root, position, renderingGroupId, params }) {
-    root.position.copyFrom(position).addInPlace(new Vector3(0, params.initialHeight, 0));
-    const system = createFootstepDustSystem(scene, root, params, renderingGroupId);
-    const runner = createStepEmitter(scene, system, params);
-    let disposed = false;
-    let stopTimer: number | null = null;
-    let disposeTimer: number | null = null;
-
-    system.start();
-    runner.start();
-
-    if (readEmitMode(params.emitMode) === 'timed') {
-      stopTimer = window.setTimeout(() => runner.stop(), Math.max(0.01, params.lifetime) * 1000);
-      disposeTimer = window.setTimeout(
-        () => disposeAll(),
-        Math.max(0.05, params.lifetime + params.particleLife + 0.25) * 1000,
-      );
-    }
-
-    return {
-      root,
-      dispose() {
-        disposeAll();
-      },
-    };
-
-    function disposeAll(): void {
-      if (disposed) return;
-      disposed = true;
-      if (stopTimer !== null) window.clearTimeout(stopTimer);
-      if (disposeTimer !== null) window.clearTimeout(disposeTimer);
-      runner.dispose();
-      system.dispose(false);
-      root.dispose();
-    }
-  },
-};
-
-function createFootstepDustSystem(
-  scene: Scene,
-  root: TransformNode,
-  params: RunFootstepDustParams,
-  renderingGroupId?: number,
-): ParticleSystem {
-  const count = Math.max(0, Math.round(params.count));
-  const capacity = Math.max(48, Math.round(readNumber(SOURCE_EMITTER.capacity, count * Math.max(6, params.frequency * params.particleLife * 3))));
-  const system = new ParticleSystem('run-footstep-dust', capacity, scene);
-  const effectScale = Math.max(0.01, params.scale);
-  const particleSize = Math.max(0.001, BASE_PARTICLE_SIZE * params.size * effectScale);
-  const dustColor = params.color;
-  const movementDirection = new Vector3(params.directionX, 0, params.directionZ);
-
-  if (movementDirection.lengthSquared() < 0.0001) movementDirection.set(1, 0, 0);
-  movementDirection.normalize();
-
-  const sideDirection = new Vector3(-movementDirection.z, 0, movementDirection.x);
-  const backwardDirection = movementDirection.scale(-1);
-  const spread = Math.max(0, params.spread) * effectScale;
-  const speed = Math.max(0, params.speed) * effectScale;
-  const trailOffset = Math.max(0, params.trailOffset) * effectScale;
-
-  system.renderingGroupId = renderingGroupId ?? RUN_FOOTSTEP_DUST_RENDERING_GROUP_ID;
-  system.particleTexture = getFootstepDustTexture(scene);
-  system.emitter = root as any;
-  system.emitRate = 0;
-  system.manualEmitCount = 0;
-  system.updateSpeed = 1 / 60;
-  system.minLifeTime = Math.max(0.03, params.particleLife);
-  system.maxLifeTime = Math.max(system.minLifeTime, params.particleLife);
-  system.minSize = particleSize;
-  system.maxSize = particleSize;
-  system.minEmitPower = speed;
-  system.maxEmitPower = speed;
-  system.minAngularSpeed = 0;
-  system.maxAngularSpeed = 0;
-  system.gravity = new Vector3(0, -Math.max(0, params.gravity) * effectScale, 0);
-  system.blendMode = ParticleSystem.BLENDMODE_STANDARD;
-  system.color1 = tintColor(dustColor, 1.04, 0.58 * params.opacity);
-  system.color2 = tintColor(dustColor, 0.78, 0.4 * params.opacity);
-  system.colorDead = tintColor(dustColor, 0.52, 0);
-  system.addColorGradient(0, tintColor(dustColor, 1.04, 0));
-  system.addColorGradient(0.12, tintColor(dustColor, 1.04, 0.6 * params.opacity));
-  system.addColorGradient(0.58, tintColor(dustColor, 0.86, 0.42 * params.opacity));
-  system.addColorGradient(1, tintColor(dustColor, 0.58, 0));
-  system.addSizeGradient(0, particleSize * 0.5);
-  system.addSizeGradient(0.28, particleSize * 1.18);
-  system.addSizeGradient(0.72, particleSize * 1.65);
-  system.addSizeGradient(1, particleSize * 1.95);
-  system.addVelocityGradient(0, 1);
-  system.addVelocityGradient(0.35, 0.34);
-  system.addVelocityGradient(1, 0.03);
-  system.addDragGradient(0, 0.85);
-  system.addDragGradient(1, 1.9);
-
-  let positionIndex = 0;
-  let directionIndex = 0;
-  system.startPositionFunction = (worldMatrix: Matrix, positionToUpdate: Vector3, _particle: Particle, isLocal: boolean) => {
-    const index = positionIndex;
-    positionIndex += 1;
-    const sideJitter = (sequence01(index, 1) - 0.5) * spread * 0.55;
-    const backwardJitter = sequence01(index, 2) * spread * 0.75;
-    const lift = sequence01(index, 3) * 0.012 * effectScale;
-    const x = backwardDirection.x * (trailOffset + backwardJitter) + sideDirection.x * sideJitter;
-    const z = backwardDirection.z * (trailOffset + backwardJitter) + sideDirection.z * sideJitter;
-    if (isLocal) positionToUpdate.set(x, lift, z);
-    else Vector3.TransformCoordinatesFromFloatsToRef(x, lift, z, worldMatrix, positionToUpdate);
-  };
-  system.startDirectionFunction = (worldMatrix: Matrix, directionToUpdate: Vector3, _particle: Particle, isLocal: boolean) => {
-    const index = directionIndex;
-    directionIndex += 1;
-    const backward = backwardDirection.scale(0.28 + sequence01(index, 4) * 0.26);
-    const sideways = sideDirection.scale((sequence01(index, 5) - 0.5) * 0.28);
-    const x = backward.x + sideways.x;
-    const y = Math.max(0, params.lift) * (0.4 + sequence01(index, 6) * 0.5);
-    const z = backward.z + sideways.z;
-    if (isLocal) directionToUpdate.set(x, y, z);
-    else Vector3.TransformNormalFromFloatsToRef(x, y, z, worldMatrix, directionToUpdate);
-  };
-
-  return system;
-}
-
-function createStepEmitter(scene: Scene, system: ParticleSystem, params: RunFootstepDustParams): { start(): void; stop(): void; dispose(): void } {
-  let observer: ReturnType<Scene['onBeforeRenderObservable']['add']> | null = null;
-  let timeToNextStep = 0;
-  const particlesPerStep = Math.max(0, Math.round(params.count));
-  const emitMode = readEmitMode(params.emitMode);
-  const interval = emitMode === 'loop'
-    ? Math.max(0.01, readNumber(params.emitInterval, DEFAULT_PARAMS.emitInterval))
-    : params.frequency > 0 ? 1 / params.frequency : Number.POSITIVE_INFINITY;
-
-  return { start, stop, dispose: stop };
-
-  function start(): void {
-    if (observer) return;
-    observer = scene.onBeforeRenderObservable.add(() => {
-      if (particlesPerStep <= 0 || !Number.isFinite(interval)) return;
-      timeToNextStep -= scene.getEngine().getDeltaTime() / 1000;
-      while (timeToNextStep <= 0) {
-        system.manualEmitCount += particlesPerStep;
-        timeToNextStep += interval;
-      }
-    });
-  }
-
-  function stop(): void {
-    if (observer) scene.onBeforeRenderObservable.remove(observer);
-    observer = null;
-    system.stop();
-  }
-}
-
-function readEmitMode(value: string): 'loop' | 'timed' {
-  return value === 'loop' || value === '持续发射' ? 'loop' : 'timed';
-}
-
-function getFootstepDustTexture(scene: Scene): DynamicTexture {
-  const key = '__vfx_run_footstep_dust_texture';
-  const metadata = scene.metadata && typeof scene.metadata === 'object' ? scene.metadata as Record<string, unknown> : {};
-  scene.metadata = metadata;
-  const existing = metadata[key] as DynamicTexture | undefined;
-  if (existing && !isTextureDisposed(existing)) return existing;
-  if (existing && isTextureDisposed(existing)) delete metadata[key];
-
-  const texture = new DynamicTexture('run_footstep_dust_texture', { width: 128, height: 128 }, scene, true);
-  const context = texture.getContext();
-  context.clearRect(0, 0, 128, 128);
-  for (const puff of [
-    { x: 48, y: 69, radius: 34, alpha: 0.72 },
-    { x: 70, y: 60, radius: 31, alpha: 0.64 },
-    { x: 86, y: 76, radius: 27, alpha: 0.5 },
-  ]) {
-    const shadow = context.createRadialGradient(puff.x, puff.y + 2, puff.radius * 0.22, puff.x, puff.y + 2, puff.radius + 5);
-    shadow.addColorStop(0, `rgba(86, 78, 64, ${puff.alpha * 0.22})`);
-    shadow.addColorStop(1, 'rgba(86, 78, 64, 0)');
-    context.fillStyle = shadow;
-    context.beginPath();
-    context.arc(puff.x, puff.y + 2, puff.radius + 5, 0, Math.PI * 2);
-    context.fill();
-  }
-  for (const puff of [
-    { x: 48, y: 69, radius: 34, alpha: 0.72 },
-    { x: 70, y: 60, radius: 31, alpha: 0.64 },
-    { x: 86, y: 76, radius: 27, alpha: 0.5 },
-  ]) {
-    const core = context.createRadialGradient(puff.x, puff.y, puff.radius * 0.12, puff.x, puff.y, puff.radius);
-    core.addColorStop(0, `rgba(255, 255, 255, ${puff.alpha})`);
-    core.addColorStop(0.58, `rgba(235, 229, 210, ${puff.alpha * 0.52})`);
-    core.addColorStop(1, 'rgba(220, 212, 188, 0)');
-    context.fillStyle = core;
-    context.beginPath();
-    context.arc(puff.x, puff.y, puff.radius, 0, Math.PI * 2);
-    context.fill();
-  }
-  texture.hasAlpha = true;
-  texture.update(false);
-  metadata[key] = texture;
-  texture.onDisposeObservable.addOnce(() => {
-    if (metadata[key] === texture) delete metadata[key];
-  });
-  return texture;
-}
-
-function readSourceEmitter(): SourceEmitter {
-  const source = sourceManifest as { emitters?: SourceEmitter[] };
-  return source.emitters?.[0] ?? {};
-}
-
-function isTextureDisposed(texture: DynamicTexture): boolean {
-  return Boolean((texture as { isDisposed?: () => boolean }).isDisposed?.());
-}
-
-function readColor(value: unknown, fallback: VfxColorValue): VfxColorValue {
-  if (typeof value === 'string') {
-    const match = /^#?([0-9a-f]{6})$/i.exec(value);
-    if (match) {
-      const hex = match[1];
-      return {
-        r: parseInt(hex.slice(0, 2), 16) / 255,
-        g: parseInt(hex.slice(2, 4), 16) / 255,
-        b: parseInt(hex.slice(4, 6), 16) / 255,
-      };
-    }
-  }
-  if (value && typeof value === 'object' && !Array.isArray(value)) {
-    const color = value as Partial<VfxColorValue>;
-    return {
-      r: readNumber(color.r, fallback.r),
-      g: readNumber(color.g, fallback.g),
-      b: readNumber(color.b, fallback.b),
-    };
-  }
-  return fallback;
-}
-
-function tintColor(color: VfxColorValue, brightness: number, alpha: number): Color4 {
-  return new Color4(
-    clamp01(color.r * brightness),
-    clamp01(color.g * brightness),
-    clamp01(color.b * brightness),
-    clamp01(alpha),
-  );
-}
-
-function readNumber(value: unknown, fallback: number): number {
-  const next = Number(value);
-  return Number.isFinite(next) ? next : fallback;
-}
-
-function clamp01(value: number): number {
-  return Math.min(1, Math.max(0, value));
-}
-
-function fract(value: number): number {
-  return value - Math.floor(value);
-}
-
-function sequence01(index: number, axis: number): number {
-  if (index === 0) return 0.5;
-  const strides = [0.618033988749895, 0.414213562373095, 0.732050807568877, 0.324717957244746, 0.754877666246693, 0.569840290998053];
-  return fract(0.5 + index * strides[axis % strides.length] + axis * 0.173205080756888);
-}

package/packages/effects/space-shared.ts

@@ -1,120 +0,0 @@
-// babylon-laser 移植系列的共享工具(被拆分后的各 space 特效复用)。
-// 非 effect(无 index.ts,glob `*/index.ts` 不会当特效加载);各特效 index.ts 经 `../space-shared` 引用。
-import { ParticleSystem } from '@babylonjs/core/Particles/particleSystem';
-import { Texture } from '@babylonjs/core/Materials/Textures/texture';
-import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
-import { Color4 } from '@babylonjs/core/Maths/math.color';
-import { Vector3 } from '@babylonjs/core/Maths/math.vector';
-import type { Mesh } from '@babylonjs/core/Meshes/mesh';
-import type { Scene } from '@babylonjs/core/scene';
-import type { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
-import type { Observer } from '@babylonjs/core/Misc/observable';
-import type { VfxColorValue, VfxParamDefinition } from '../types';
-
-// ── 通用「生命周期模式」(无限循环 / 自定义时长),对齐 lumber 系列的约定 ──────────
-export const LIFETIME_DEBUG_PARAMS: VfxParamDefinition[] = [
-  { key: 'lifetimeMode', label: '生命周期模式', kind: 'enum', options: [
-    { value: 'infinite', label: '无限' }, { value: 'duration', label: '自定义时间' },
-  ] },
-  { key: 'lifetime', label: '自定义时长', kind: 'lifetime', min: 0.1, max: 30, step: 0.01 },
-];
-export const LIFETIME_DEFAULTS: { lifetimeMode: string; lifetime: number } = { lifetimeMode: 'infinite', lifetime: 2 };
-// mode='duration' 时 N 秒后调 dispose;返回定时器 id(0=未排程),由 dispose 里 clearTimeout。
-export function scheduleLifetime(params: { lifetimeMode?: string; lifetime?: number }, dispose: () => void): number {
-  if (params.lifetimeMode === 'duration') return window.setTimeout(dispose, Math.max(0.05, params.lifetime ?? 2) * 1000);
-  return 0;
-}
-
-// 把网格从场景里任何 GlowLayer 排除(ctx 不带 glow 引用,自查 scene.effectLayers)
-export function excludeFromGlow(scene: Scene, mesh: AbstractMesh): void {
-  for (const layer of scene.effectLayers ?? []) {
-    const add = (layer as unknown as { addExcludedMesh?: (m: AbstractMesh) => void }).addExcludedMesh;
-    if (typeof add === 'function') add.call(layer, mesh);
-  }
-}
-
-// 程序径向光斑(命中爆闪 / 激光两端光球用)
-export function makeFlareTexture(scene: Scene, name = 'vfx_flare', inner = '255,255,255', outer = '90,160,255'): DynamicTexture {
-  const dt = new DynamicTexture(name, 128, scene, false);
-  const ctx = dt.getContext();
-  const g = ctx.createRadialGradient(64, 64, 0, 64, 64, 64);
-  g.addColorStop(0, `rgba(${inner},1)`);
-  g.addColorStop(0.35, `rgba(${outer},0.55)`);
-  g.addColorStop(1, `rgba(${outer},0)`);
-  ctx.clearRect(0, 0, 128, 128);
-  ctx.fillStyle = g; ctx.fillRect(0, 0, 128, 128);
-  dt.update(); dt.hasAlpha = true;
-  return dt;
-}
-
-// 爆发型粒子工厂(emitRate=0 常驻,靠 manualEmitCount 单帧脉冲)
-export interface BurstPSOptions {
-  cap: number; sheet?: [number, number, number];
-  size: [number, number]; life: [number, number]; power: [number, number];
-  gravity: Vector3; blend: number; c1: Color4; c2: Color4; cd: Color4;
-}
-export function makeBurstPS(name: string, scene: Scene, texUrl: string, opts: BurstPSOptions): ParticleSystem {
-  const ps = new ParticleSystem(name, opts.cap, scene, null, !!opts.sheet);
-  ps.particleTexture = new Texture(texUrl, scene);
-  ps.particleTexture.hasAlpha = true;
-  ps.emitter = new Vector3(0, 0, 0);
-  ps.minEmitBox = new Vector3(0, 0, 0); ps.maxEmitBox = new Vector3(0, 0, 0);
-  ps.direction1 = new Vector3(-1, -1, -1); ps.direction2 = new Vector3(1, 1, 1);
-  ps.minInitialRotation = -Math.PI; ps.maxInitialRotation = Math.PI;
-  ps.minSize = opts.size[0]; ps.maxSize = opts.size[1];
-  ps.minLifeTime = opts.life[0]; ps.maxLifeTime = opts.life[1];
-  ps.minEmitPower = opts.power[0]; ps.maxEmitPower = opts.power[1];
-  ps.gravity = opts.gravity;
-  ps.color1 = opts.c1; ps.color2 = opts.c2; ps.colorDead = opts.cd;
-  ps.blendMode = opts.blend;
-  ps.emitRate = 0;
-  if (opts.sheet) {
-    ps.spriteCellWidth = opts.sheet[0]; ps.spriteCellHeight = opts.sheet[1];
-    ps.startSpriteCellID = 0; ps.endSpriteCellID = opts.sheet[2] - 1; ps.spriteCellChangeSpeed = 1;
-  }
-  ps.start();
-  return ps;
-}
-
-// 抛物 flyer 池(碎石/金币):重力抛物 + 随机自转 + 末段缩小 + 寿命到回收。自维护 onBeforeRender。
-interface Flyer { mesh: Mesh; vel: Vector3; spin: Vector3; life: number; maxLife: number; gravity: number; base: number; }
-export class FlyerPool {
-  private readonly flyers: Flyer[] = [];
-  private readonly observer: Observer<Scene>;
-  private disposed = false;
-  constructor(private readonly scene: Scene) {
-    this.observer = scene.onBeforeRenderObservable.add(() => this.update()) as Observer<Scene>;
-  }
-  spawn(mesh: Mesh, origin: Vector3, vel: Vector3, gravity: number, maxLife: number): void {
-    mesh.position.copyFrom(origin);
-    mesh.isPickable = false;
-    this.flyers.push({
-      mesh, vel, gravity, maxLife, life: 0, base: mesh.scaling.x || 1,
-      spin: new Vector3((Math.random() - 0.5) * 8, (Math.random() - 0.5) * 8, (Math.random() - 0.5) * 8),
-    });
-  }
-  get activeCount(): number { return this.flyers.length; }
-  private update(): void {
-    if (this.disposed) return;
-    const dt = Math.min(this.scene.getEngine().getDeltaTime() / 1000, 0.05);
-    for (let i = this.flyers.length - 1; i >= 0; i--) {
-      const f = this.flyers[i]; f.life += dt;
-      f.vel.y -= f.gravity * dt;
-      f.mesh.position.addInPlace(f.vel.scale(dt));
-      f.mesh.rotation.x += f.spin.x * dt; f.mesh.rotation.y += f.spin.y * dt; f.mesh.rotation.z += f.spin.z * dt;
-      if (f.life > f.maxLife * 0.7) {
-        const k = Math.max(0.001, 1 - (f.life - f.maxLife * 0.7) / (f.maxLife * 0.3));
-        f.mesh.scaling.setAll(f.base * k);
-      }
-      if (f.life >= f.maxLife) { f.mesh.dispose(); this.flyers.splice(i, 1); }
-    }
-  }
-  dispose(): void {
-    if (this.disposed) return; this.disposed = true;
-    this.scene.onBeforeRenderObservable.remove(this.observer);
-    for (const f of this.flyers) f.mesh.dispose();
-    this.flyers.length = 0;
-  }
-}
-
-export function colorVec4(c: VfxColorValue, a = 1): Color4 { return new Color4(c.r, c.g, c.b, a); }