@fps-games/vfx 0.1.1

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

@@ -0,0 +1,377 @@
+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/run-footstep-dust/vfx-params.json

@@ -0,0 +1,27 @@
+{
+  "__generation.offsetX": 0,
+  "__generation.offsetY": 0,
+  "__generation.offsetZ": 0,
+  "emitMode": "loop",
+  "lifetime": 2,
+  "emitInterval": 1,
+  "scale": 6,
+  "initialHeight": 1,
+  "color": {
+    "r": 0.9764705882352941,
+    "g": 0.9647058823529412,
+    "b": 0.8666666666666667
+  },
+  "opacity": 1,
+  "count": 9,
+  "frequency": 1,
+  "spread": 1,
+  "particleLife": 0.2,
+  "speed": 1,
+  "size": 1,
+  "trailOffset": 0,
+  "directionX": 1,
+  "directionZ": 0,
+  "lift": 0.2,
+  "gravity": 0.08
+}

package/packages/effects/space-shared.ts

@@ -0,0 +1,120 @@
+// 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); }