@fps-games/vfx 0.1.1

package/packages/effects/lumber-cart-suction/index.ts

@@ -0,0 +1,399 @@
+import { Color3, Color4 } from '@babylonjs/core/Maths/math.color';
+import { Matrix, Vector3 } from '@babylonjs/core/Maths/math.vector';
+import { Constants } from '@babylonjs/core/Engines/constants';
+import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
+import { CreateTube } from '@babylonjs/core/Meshes/Builders/tubeBuilder';
+import { ParticleSystem } from '@babylonjs/core/Particles/particleSystem';
+import type { Mesh } from '@babylonjs/core/Meshes/mesh';
+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 manifest from './effect.json';
+
+const LUMBER_CART_SUCTION_RENDERING_GROUP_ID = 0;
+
+interface LumberCartSuctionParams extends VfxParamValues {
+  lifetime: number;
+  scale: number;
+  initialHeight: number;
+  color: VfxColorValue;
+  opacity: number;
+  ringCount: number;
+  forwardOffset: number;
+  suctionLength: number;
+  startRadius: number;
+  endRadius: number;
+  ringWidth: number;
+  suctionSpeed: number;
+  pulse: number;
+  flyingParticleCount: number;
+  flyingParticleSize: number;
+  flyingParticleSpeed: number;
+  flyingParticleDrift: number;
+  flyingParticleOuterOffset: number;
+  flyingParticleOpacity: number;
+  directionX: number;
+  directionZ: number;
+}
+
+interface RingBasis {
+  forward: Vector3;
+  side: Vector3;
+  up: Vector3;
+  mouth: Vector3;
+  length: number;
+  startRadius: number;
+  endRadius: number;
+  ringWidth: number;
+}
+
+const DEFAULT_PARAMS: LumberCartSuctionParams = {
+  lifetime: 1.8,
+  scale: 1,
+  initialHeight: 0.18,
+  color: { r: 1, g: 0.86, b: 0.42 },
+  opacity: 0.95,
+  ringCount: 5,
+  forwardOffset: 0.4,
+  suctionLength: 2.1,
+  startRadius: 0.62,
+  endRadius: 0.08,
+  ringWidth: 0.035,
+  suctionSpeed: 1.45,
+  pulse: 0.18,
+  flyingParticleCount: 42,
+  flyingParticleSize: 0.045,
+  flyingParticleSpeed: 4.2,
+  flyingParticleDrift: 0.22,
+  flyingParticleOuterOffset: 0.28,
+  flyingParticleOpacity: 0.74,
+  directionX: 1,
+  directionZ: 0,
+};
+
+export const lumberCartSuctionEffectPackage: VfxEffectPackage<LumberCartSuctionParams> = {
+  id: 'lumber-cart-suction',
+  nameZh: '收集车吸入圆环',
+  manifest,
+  defaultParams: DEFAULT_PARAMS,
+  debugAnchor: 'playerRight',
+  debugParams: [
+    { key: 'lifetime', label: '生命周期', kind: 'lifetime', min: 0.08, 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: 3, step: 0.01 },
+    { key: 'color', label: '圆环颜色', kind: 'color' },
+    { key: 'opacity', label: '透明度', kind: 'opacity', min: 0, max: 1, step: 0.01 },
+    { key: 'ringCount', label: '圆环数量', kind: 'number', min: 1, max: 16, step: 1 },
+    { key: 'forwardOffset', label: '车前偏移', kind: 'number', min: -1, max: 4, step: 0.01 },
+    { key: 'suctionLength', label: '吸入长度', kind: 'number', min: 0.1, max: 8, step: 0.01 },
+    { key: 'startRadius', label: '外圈半径', kind: 'number', min: 0.02, max: 4, step: 0.01 },
+    { key: 'endRadius', label: '入口半径', kind: 'number', min: 0.01, max: 2, step: 0.01 },
+    { key: 'ringWidth', label: '圆环粗细', kind: 'number', min: 0.005, max: 0.25, step: 0.001 },
+    { key: 'suctionSpeed', label: '吸入速度', kind: 'number', min: 0, max: 8, step: 0.01 },
+    { key: 'pulse', label: '收缩脉冲', kind: 'number', min: 0, max: 1, step: 0.01 },
+    { key: 'flyingParticleCount', label: '飞行粒子数量', kind: 'number', min: 0, max: 180, step: 1 },
+    { key: 'flyingParticleSize', label: '飞行粒子大小', kind: 'number', min: 0.005, max: 0.3, step: 0.001 },
+    { key: 'flyingParticleSpeed', label: '飞行粒子速度', kind: 'number', min: 0, max: 16, step: 0.01 },
+    { key: 'flyingParticleDrift', label: '飞行粒子散布', kind: 'number', min: 0, max: 1.5, step: 0.01 },
+    { key: 'flyingParticleOuterOffset', label: '飞行粒子外偏移', kind: 'number', min: -1, max: 2, step: 0.01 },
+    { key: 'flyingParticleOpacity', label: '飞行粒子透明度', kind: 'opacity', min: 0, max: 1, 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 },
+  ],
+  create({ scene, root, position, params }) {
+    root.position.copyFrom(position).addInPlace(new Vector3(0, params.initialHeight, 0));
+    const rings = createSuctionRings(scene, root, params);
+    let disposed = false;
+
+    rings.start();
+
+    return {
+      root,
+      dispose() {
+        disposeAll();
+      },
+    };
+
+    function disposeAll(): void {
+      if (disposed) return;
+      disposed = true;
+      rings.dispose();
+      root.dispose();
+    }
+  },
+};
+
+function createSuctionRings(scene: Scene, root: TransformNode, params: LumberCartSuctionParams): { start(): void; dispose(): void } {
+  const basis = createRingBasis(params);
+  const ringCount = Math.max(1, Math.round(params.ringCount));
+  const material = createRingMaterial(scene, params);
+  const particles = createFlyingParticleSystem(scene, root, params, basis);
+  const rings: Mesh[] = [];
+  let age = 0;
+  let observer: ReturnType<Scene['onBeforeRenderObservable']['add']> | null = null;
+  let disposed = false;
+
+  for (let index = 0; index < ringCount; index += 1) {
+    const progress = index / ringCount;
+    const ring = CreateTube(`lumber-cart-suction.ring.${index}`, {
+      path: buildRingPath(basis, progress, params.pulse),
+      radius: basis.ringWidth,
+      tessellation: 8,
+      updatable: true,
+    }, scene);
+    ring.parent = root;
+    ring.material = material;
+    ring.renderingGroupId = LUMBER_CART_SUCTION_RENDERING_GROUP_ID;
+    ring.isPickable = false;
+    rings.push(ring);
+  }
+
+  return { start, dispose };
+
+  function start(): void {
+    if (observer) return;
+    particles.start();
+    observer = scene.onBeforeRenderObservable.add(() => {
+      if (disposed) return;
+      const deltaSeconds = Math.min(0.05, scene.getEngine().getDeltaTime() / 1000);
+      age += deltaSeconds;
+
+      for (let index = 0; index < rings.length; index += 1) {
+        const progress = fract(age * Math.max(0, params.suctionSpeed) + index / rings.length);
+        CreateTube(`lumber-cart-suction.ring.${index}`, {
+          path: buildRingPath(basis, progress, params.pulse),
+          radius: basis.ringWidth,
+          tessellation: 8,
+          instance: rings[index],
+        }, scene);
+      }
+
+      const pulse = Math.sin(age * Math.max(0.1, params.suctionSpeed) * Math.PI * 2) * Math.max(0, params.pulse);
+      material.alpha = clamp01(params.opacity * (0.88 + pulse * 0.12));
+    });
+  }
+
+  function dispose(): void {
+    if (disposed) return;
+    disposed = true;
+    if (observer) scene.onBeforeRenderObservable.remove(observer);
+    observer = null;
+    for (const ring of rings) ring.dispose();
+    particles.stop();
+    particles.dispose(false);
+    material.dispose();
+  }
+}
+
+function createRingBasis(params: LumberCartSuctionParams): RingBasis {
+  const scale = Math.max(0.01, params.scale);
+  const forward = new Vector3(params.directionX, 0, params.directionZ);
+  if (forward.lengthSquared() < 0.0001) forward.set(1, 0, 0);
+  forward.normalize();
+
+  return {
+    forward,
+    side: new Vector3(-forward.z, 0, forward.x),
+    up: Vector3.Up(),
+    mouth: forward.scale(params.forwardOffset * scale),
+    length: Math.max(0.01, params.suctionLength * scale),
+    startRadius: Math.max(0.001, params.startRadius * scale),
+    endRadius: Math.max(0.001, params.endRadius * scale),
+    ringWidth: Math.max(0.002, params.ringWidth * scale),
+  };
+}
+
+function buildRingPath(basis: RingBasis, progress: number, pulse: number): Vector3[] {
+  const points: Vector3[] = [];
+  const segments = 72;
+  const eased = easeInCubic(clamp01(progress));
+  const distance = basis.length * (1 - eased);
+  const pulseScale = 1 + Math.sin(progress * Math.PI * 2) * Math.max(0, pulse) * 0.12;
+  const radius = lerp(basis.endRadius, basis.startRadius, 1 - eased) * pulseScale;
+  const center = basis.mouth.add(basis.forward.scale(distance));
+
+  for (let index = 0; index <= segments; index += 1) {
+    const angle = (index / segments) * Math.PI * 2;
+    points.push(
+      center
+        .add(basis.side.scale(Math.cos(angle) * radius))
+        .add(basis.up.scale(Math.sin(angle) * radius)),
+    );
+  }
+
+  return points;
+}
+
+function createRingMaterial(scene: Scene, params: LumberCartSuctionParams): StandardMaterial {
+  const material = new StandardMaterial('lumber-cart-suction.ring.material', scene);
+  const color = toColor3(params.color);
+  material.diffuseColor = color;
+  material.emissiveColor = color.scale(1.35);
+  material.alpha = params.opacity;
+  material.disableLighting = true;
+  material.backFaceCulling = false;
+  material.alphaMode = Constants.ALPHA_ADD;
+  return material;
+}
+
+function createFlyingParticleSystem(
+  scene: Scene,
+  root: TransformNode,
+  params: LumberCartSuctionParams,
+  basis: RingBasis,
+): ParticleSystem {
+  const scale = Math.max(0.01, params.scale);
+  const count = Math.max(0, Math.round(params.flyingParticleCount));
+  const speed = Math.max(0.01, params.flyingParticleSpeed * scale);
+  const particleLife = clampNumber(basis.length / speed, 0.18, 0.85);
+  const system = new ParticleSystem('lumber-cart-suction.flying-particles', Math.max(8, count * 2), scene);
+  const size = Math.max(0.001, params.flyingParticleSize * scale);
+  const color = params.color;
+  const opacity = clamp01(params.flyingParticleOpacity * params.opacity);
+
+  system.isLocal = false;
+  system.renderingGroupId = LUMBER_CART_SUCTION_RENDERING_GROUP_ID;
+  system.particleTexture = getFlyingParticleTexture(scene);
+  system.emitter = root as any;
+  system.emitRate = count / particleLife;
+  system.updateSpeed = 1 / 60;
+  system.minLifeTime = particleLife * 0.72;
+  system.maxLifeTime = particleLife * 1.12;
+  system.minSize = size * 0.72;
+  system.maxSize = size * 1.28;
+  system.minAngularSpeed = -4;
+  system.maxAngularSpeed = 4;
+  system.minEmitPower = 1;
+  system.maxEmitPower = 1;
+  system.gravity = Vector3.Zero();
+  system.blendMode = ParticleSystem.BLENDMODE_ADD;
+  system.color1 = tintColor(color, 1.5, opacity * 0.78);
+  system.color2 = tintColor(color, 2.1, opacity);
+  system.colorDead = tintColor(color, 0.8, 0);
+  system.addColorGradient(0, tintColor(color, 1.1, 0));
+  system.addColorGradient(0.2, tintColor(color, 2.2, opacity));
+  system.addColorGradient(0.72, tintColor(color, 1.55, opacity * 0.68));
+  system.addColorGradient(1, tintColor(color, 0.8, 0));
+  system.addSizeGradient(0, size * 0.46, size * 0.72);
+  system.addSizeGradient(0.22, size * 0.9, size * 1.28);
+  system.addSizeGradient(1, size * 0.18, size * 0.36);
+
+  system.startPositionFunction = (worldMatrix: Matrix, positionToUpdate: Vector3, _particle: Particle, isLocal: boolean) => {
+    const local = sampleFlyingParticlePosition(basis, params);
+    if (isLocal) positionToUpdate.copyFrom(local);
+    else Vector3.TransformCoordinatesToRef(local, worldMatrix, positionToUpdate);
+  };
+  system.startDirectionFunction = (worldMatrix: Matrix, directionToUpdate: Vector3, particle: Particle, isLocal: boolean) => {
+    const id = flyingParticleDirectionSequenceIndex;
+    flyingParticleDirectionSequenceIndex += 1;
+    const localPosition = particle.position.clone();
+    const localTarget = basis.mouth.add(
+      basis.side.scale((sequence01(id, 3) - 0.5) * basis.endRadius * 0.6),
+    ).addInPlace(
+      basis.up.scale((sequence01(id, 4) - 0.5) * basis.endRadius * 0.5),
+    );
+    const target = isLocal ? localTarget : Vector3.TransformCoordinates(localTarget, worldMatrix);
+    const direction = target.subtract(localPosition);
+    if (direction.lengthSquared() < 0.0001) {
+      const fallback = basis.forward.scale(-1);
+      if (isLocal) direction.copyFrom(fallback);
+      else Vector3.TransformNormalToRef(fallback, worldMatrix, direction);
+    }
+    else direction.normalize();
+
+    const drift = Math.max(0, params.flyingParticleDrift) * scale;
+    const localTangent = basis.side
+      .scale((sequence01(id, 5) - 0.5) * drift)
+      .addInPlace(basis.up.scale((sequence01(id, 6) - 0.5) * drift * 0.65));
+    const tangent = isLocal ? localTangent : Vector3.TransformNormal(localTangent, worldMatrix);
+    direction.scaleInPlace(speed * lerp(0.78, 1.28, sequence01(id, 7))).addInPlace(tangent);
+    directionToUpdate.copyFrom(direction);
+  };
+
+  return system;
+}
+
+function sampleFlyingParticlePosition(basis: RingBasis, params: LumberCartSuctionParams): Vector3 {
+  const id = flyingParticleSequenceIndex;
+  flyingParticleSequenceIndex += 1;
+  const scale = Math.max(0.01, params.scale);
+  const outerOffset = params.flyingParticleOuterOffset * scale;
+  const distanceRatio = lerp(0.68, 1.02, sequence01(id, 0));
+  const radiusRatio = lerp(0.38, 0.92, Math.sqrt(sequence01(id, 1)));
+  const angle = sequence01(id, 2) * Math.PI * 2;
+  const radius = lerp(basis.endRadius, basis.startRadius, clamp01(distanceRatio)) * radiusRatio;
+  return basis.mouth
+    .add(basis.forward.scale(basis.length * distanceRatio + outerOffset))
+    .addInPlace(basis.side.scale(Math.cos(angle) * radius))
+    .addInPlace(basis.up.scale(Math.sin(angle) * radius));
+}
+
+function getFlyingParticleTexture(scene: Scene): DynamicTexture {
+  const key = '__vfx_lumber_cart_suction_particle_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) return existing;
+
+  const texture = new DynamicTexture('lumber_cart_suction_particle_texture', { width: 64, height: 64 }, scene, true);
+  const context = texture.getContext() as unknown as CanvasRenderingContext2D;
+  context.clearRect(0, 0, 64, 64);
+  const dot = context.createRadialGradient(32, 32, 1, 32, 32, 30);
+  dot.addColorStop(0, 'rgba(255, 255, 255, 1)');
+  dot.addColorStop(0.48, 'rgba(255, 255, 255, 0.92)');
+  dot.addColorStop(0.78, 'rgba(255, 255, 255, 0.42)');
+  dot.addColorStop(1, 'rgba(255, 255, 255, 0)');
+  context.fillStyle = dot;
+  context.beginPath();
+  context.arc(32, 32, 30, 0, Math.PI * 2);
+  context.fill();
+  texture.hasAlpha = true;
+  texture.update(false);
+  metadata[key] = texture;
+  return texture;
+}
+
+function toColor3(color: VfxColorValue): Color3 {
+  return new Color3(clamp01(color.r), clamp01(color.g), clamp01(color.b));
+}
+
+function tintColor(color: VfxColorValue, brightness: number, alpha: number): Color4 {
+  return new Color4(
+    Math.max(0, color.r * brightness),
+    Math.max(0, color.g * brightness),
+    Math.max(0, color.b * brightness),
+    clamp01(alpha),
+  );
+}
+
+function lerp(min: number, max: number, t: number): number {
+  return min + (max - min) * t;
+}
+
+function clamp01(value: number): number {
+  return Math.min(1, Math.max(0, value));
+}
+
+function clampNumber(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function fract(value: number): number {
+  return value - Math.floor(value);
+}
+
+function easeInCubic(value: number): number {
+  const t = clamp01(value);
+  return t * t * t;
+}
+
+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);
+}
+
+let flyingParticleSequenceIndex = 0;
+let flyingParticleDirectionSequenceIndex = 2048;

package/packages/effects/lumber-cart-suction/vfx-params.json

@@ -0,0 +1,30 @@
+{
+  "__generation.offsetX": 0,
+  "__generation.offsetY": 0,
+  "__generation.offsetZ": 0,
+  "lifetime": 999,
+  "scale": 2,
+  "initialHeight": 0.25,
+  "color": {
+    "r": 1,
+    "g": 1,
+    "b": 1
+  },
+  "opacity": 0.88,
+  "ringCount": 5,
+  "forwardOffset": 0.72,
+  "suctionLength": 1.65,
+  "startRadius": 0.72,
+  "endRadius": 0.08,
+  "ringWidth": 0.01,
+  "suctionSpeed": 1.45,
+  "pulse": 0.16,
+  "flyingParticleCount": 20,
+  "flyingParticleSize": 0.1,
+  "flyingParticleSpeed": 4.2,
+  "flyingParticleDrift": 0.22,
+  "flyingParticleOuterOffset": 0.5,
+  "flyingParticleOpacity": 0.74,
+  "directionX": 0,
+  "directionZ": 1
+}

package/packages/effects/lumber-debris-scatter/assets/models/lumber_prop_model.glb.versions/.active

@@ -0,0 +1 @@
+1781589063890_upload

package/packages/effects/lumber-debris-scatter/assets/runtime/solidParticleScatter.v1.js

@@ -0,0 +1,236 @@
+export const runtimeId = "solidParticleScatter/v1";
+
+export const runtimeContract = {
+  runtimeId,
+  kind: "solidParticleScatter",
+  fields: {
+    count: "Number of lumber pieces emitted per burst.",
+    scatterMode: "vertical drops pieces downward; radial throws pieces from the emitter center outward.",
+    outwardAngleDegrees: "Radial scatter fan angle in degrees, used only when scatterMode is radial.",
+    scatterGravity: "Higher values pull pieces down sooner and reduce hang time.",
+    rotationStrength: "Deterministic random rotation around each lumber piece center, not around the emitter.",
+    effectScale: "Overall spatial scale for piece size, travel distance, and spawn height.",
+  },
+};
+
+function num(value, fallback = 0) {
+  const next = Number(value);
+  return Number.isFinite(next) ? next : fallback;
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function fract(value) {
+  return value - Math.floor(value);
+}
+
+function sequence01(index, axis) {
+  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);
+}
+
+function bounceOut(t) {
+  const n1 = 7.5625;
+  const d1 = 2.75;
+  if (t < 1 / d1) return n1 * t * t;
+  if (t < 2 / d1) {
+    const next = t - 1.5 / d1;
+    return n1 * next * next + 0.75;
+  }
+  if (t < 2.5 / d1) {
+    const next = t - 2.25 / d1;
+    return n1 * next * next + 0.9375;
+  }
+  const next = t - 2.625 / d1;
+  return n1 * next * next + 0.984375;
+}
+
+function lerp(start, end, t) {
+  return start + (end - start) * t;
+}
+
+function readVec(BABYLON, value, fallback = new BABYLON.Vector3(0, 0, 0)) {
+  if (!value) return fallback;
+  return new BABYLON.Vector3(num(value.x, fallback.x), num(value.y, fallback.y), num(value.z, fallback.z));
+}
+
+function splitUrl(url) {
+  const slashIndex = url.lastIndexOf("/");
+  if (slashIndex < 0) return { rootUrl: "", fileName: url };
+  return { rootUrl: url.slice(0, slashIndex + 1), fileName: url.slice(slashIndex + 1) };
+}
+
+function createFallbackSourceMesh(BABYLON, scene, name) {
+  const source = BABYLON.MeshBuilder.CreateBox(name, { width: 0.22, height: 0.16, depth: 0.82 }, scene);
+  source.isVisible = false;
+  source.setEnabled(false);
+  return source;
+}
+
+async function loadSourceMesh(BABYLON, scene, emitter, urlForPackagePath) {
+  const modelPath = emitter.modelPath;
+  if (!modelPath || !BABYLON.SceneLoader) {
+    return createFallbackSourceMesh(BABYLON, scene, `${emitter.name || "lumber_debris_scatter"}Source`);
+  }
+
+  try {
+    const modelUrl = urlForPackagePath ? urlForPackagePath(modelPath) : modelPath;
+    const { rootUrl, fileName } = splitUrl(modelUrl);
+    const result = await BABYLON.SceneLoader.ImportMeshAsync("", rootUrl, fileName, scene);
+    const meshes = result.meshes.filter((mesh) => mesh instanceof BABYLON.Mesh && mesh.getTotalVertices() > 0);
+    if (!meshes.length) throw new Error(`No mesh was found in ${modelPath}.`);
+    const source = meshes.length === 1 ? meshes[0] : BABYLON.Mesh.MergeMeshes(meshes, true, true, undefined, false, true);
+    if (!source) throw new Error(`Unable to merge meshes from ${modelPath}.`);
+    source.name = `${emitter.name || "lumber_debris_scatter"}ModelSource`;
+    source.isVisible = false;
+    source.setEnabled(false);
+    source.refreshBoundingInfo();
+    const size = source.getBoundingInfo().boundingBox.extendSize.scale(2);
+    const maxDimension = Math.max(size.x, size.y, size.z, 0.0001);
+    source.scaling.scaleInPlace(0.82 / maxDimension);
+    source.rotationQuaternion = null;
+    source.refreshBoundingInfo();
+    return source;
+  } catch (error) {
+    console.warn("Unable to load lumber debris model; using box fallback.", error);
+    return createFallbackSourceMesh(BABYLON, scene, `${emitter.name || "lumber_debris_scatter"}Source`);
+  }
+}
+
+function createState(BABYLON, index, count, origin, emitter) {
+  const effectScale = Math.max(0.01, num(emitter.effectScale, 1));
+  const resourceScale = Math.max(0.01, num(emitter.resourceScale, 1));
+  const speedScale = Math.max(0.1, num(emitter.speedScale, 1));
+  const duration = Math.max(0.08, num(emitter.duration, 0.74)) / speedScale;
+  const interval = Math.max(0, num(emitter.intervalMs, 18)) / 1000;
+  const mode = emitter.scatterMode === "vertical" ? "vertical" : "radial";
+  const spread = Math.max(0, num(emitter.spread, 0.88)) * effectScale;
+  const gravity = Math.max(0.05, num(emitter.scatterGravity, 1));
+  const rotationStrength = Math.max(0, num(emitter.rotationStrength, 1));
+  const outwardAngleRadians = clamp(num(emitter.outwardAngleDegrees, 240), 0, 360) * (Math.PI / 180);
+  const emissionDirection = readVec(BABYLON, emitter.emissionDirection, new BABYLON.Vector3(1, 0, 0));
+
+  const angleSeed = sequence01(index, 0);
+  const radiusSeed = Math.sqrt(sequence01(index, 1));
+  const sideSeed = sequence01(index, 2) < 0.5 ? -1 : 1;
+  emissionDirection.y = 0;
+  if (emissionDirection.lengthSquared() < 0.0001) emissionDirection.set(1, 0, 0);
+  emissionDirection.normalize();
+
+  const baseAngle = Math.atan2(emissionDirection.z, emissionDirection.x);
+  const radialAngle = mode === "radial" ? baseAngle + (angleSeed - 0.5) * outwardAngleRadians : angleSeed * Math.PI * 2;
+  const scatterRadius = spread * (0.35 + radiusSeed * 0.65);
+  const localX = Math.cos(radialAngle) * scatterRadius;
+  const localZ = Math.sin(radialAngle) * scatterRadius;
+  const startPos = mode === "radial"
+    ? new BABYLON.Vector3(origin.x + emissionDirection.x * spread * 0.08, origin.y + 0.34 * effectScale, origin.z + emissionDirection.z * spread * 0.08)
+    : new BABYLON.Vector3(origin.x + localX * 0.52, origin.y + (0.72 + sequence01(index, 3) * 0.24) * effectScale, origin.z + localZ * 0.52);
+  const targetPos = mode === "radial"
+    ? new BABYLON.Vector3(origin.x + localX, origin.y, origin.z + localZ)
+    : new BABYLON.Vector3(origin.x + localX * 0.52, origin.y, origin.z + localZ * 0.52);
+  const rotationBase = Math.PI * 2 * rotationStrength;
+
+  return {
+    active: index < count,
+    startPos,
+    targetPos,
+    startRotation: new BABYLON.Vector3((sequence01(index, 4) - 0.5) * rotationBase, (sequence01(index, 5) - 0.5) * rotationBase, (sequence01(index, 6) - 0.5) * rotationBase),
+    rotationDelta: new BABYLON.Vector3(sideSeed * (2.6 + sequence01(index, 7) * 2.2) * rotationStrength, (sequence01(index, 8) - 0.5) * 7.2 * rotationStrength, sideSeed * (1.7 + sequence01(index, 9) * 2.8) * rotationStrength),
+    duration: duration * (0.88 + sequence01(index, 10) * 0.18),
+    elapsed: -index * interval,
+    gravity,
+    scale: resourceScale * effectScale * (0.68 + sequence01(index, 11) * 0.24),
+  };
+}
+
+export async function createSolidParticleScatterRuntime({ BABYLON, scene, emitter, urlForPackagePath, shouldStart = false }) {
+  if (!BABYLON) throw new Error("createSolidParticleScatterRuntime requires BABYLON.");
+  if (!scene) throw new Error("createSolidParticleScatterRuntime requires scene.");
+  if (!emitter) throw new Error("createSolidParticleScatterRuntime requires emitter.");
+
+  const count = Math.max(0, Math.round(num(emitter.count ?? emitter.particleCount, 18)));
+  const capacity = Math.max(8, Math.round(num(emitter.capacity, count)));
+  const origin = readVec(BABYLON, emitter.origin, BABYLON.Vector3.Zero());
+  const sps = new BABYLON.SolidParticleSystem(emitter.name || "lumber_debris_scatter", scene, { updatable: true, isPickable: false });
+  const source = await loadSourceMesh(BABYLON, scene, emitter, urlForPackagePath);
+  sps.addShape(source, capacity);
+  source.dispose();
+
+  const mesh = sps.buildMesh();
+  mesh.isPickable = false;
+  mesh.alwaysSelectAsActiveMesh = true;
+  const material = new BABYLON.StandardMaterial(`${emitter.name || "lumber_debris_scatter"}Material`, scene);
+  material.diffuseColor = new BABYLON.Color3(0.52, 0.31, 0.13);
+  material.emissiveColor = new BABYLON.Color3(0.08, 0.045, 0.02);
+  material.specularColor = BABYLON.Color3.Black();
+  mesh.material = material;
+
+  const states = Array.from({ length: capacity }, (_, index) => createState(BABYLON, index, count, origin, emitter));
+  let activeCount = Math.min(count, capacity);
+  let elapsed = 0;
+  let started = false;
+  const disposeAfter = Math.max(...states.map((state) => Math.max(0, -state.elapsed) + state.duration), 0) + 0.35;
+
+  sps.updateParticle = (particle) => {
+    const state = states[particle.idx];
+    if (!state?.active || state.elapsed < 0) {
+      particle.position.set(0, -9999, 0);
+      particle.scaling.set(0, 0, 0);
+      return particle;
+    }
+    const t = clamp(state.elapsed / state.duration, 0, 1);
+    const horizontalT = bounceOut(t);
+    const gravityT = 1 - Math.pow(1 - t, 1 + state.gravity * 1.15);
+    const lift = Math.sin(Math.PI * t) * (0.32 / Math.max(0.25, state.gravity));
+    particle.position.set(lerp(state.startPos.x, state.targetPos.x, horizontalT), lerp(state.startPos.y, state.targetPos.y, gravityT) + lift, lerp(state.startPos.z, state.targetPos.z, horizontalT));
+    particle.rotation.set(state.startRotation.x + state.rotationDelta.x * t, state.startRotation.y + state.rotationDelta.y * t, state.startRotation.z + state.rotationDelta.z * t);
+    particle.scaling.set(state.scale, state.scale, state.scale);
+    return particle;
+  };
+  sps.setParticles();
+
+  let observer = null;
+  const start = () => {
+    if (started) return;
+    started = true;
+    observer = scene.onBeforeRenderObservable.add(() => {
+      const deltaTime = scene.getEngine().getDeltaTime() / 1000;
+      elapsed += deltaTime;
+      for (const state of states) {
+        if (!state.active) continue;
+        state.elapsed += deltaTime;
+        if (state.elapsed >= state.duration) {
+          state.active = false;
+          activeCount = Math.max(0, activeCount - 1);
+        }
+      }
+      sps.setParticles();
+      if (activeCount <= 0 && elapsed >= disposeAfter) preview.dispose();
+    });
+  };
+
+  const preview = {
+    start,
+    stop: () => {
+      if (observer) scene.onBeforeRenderObservable.remove(observer);
+      observer = null;
+      started = false;
+    },
+    dispose: () => {
+      if (observer) scene.onBeforeRenderObservable.remove(observer);
+      observer = null;
+      sps.dispose();
+      material.dispose();
+    },
+    isStarted: () => started,
+    duration: disposeAfter,
+    mesh,
+    sps,
+  };
+
+  if (shouldStart) start();
+  return preview;
+}