@fps-games/vfx 0.1.1

package/packages/effects/lumber-debris-scatter/index.ts

@@ -0,0 +1,780 @@
+import { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
+import { Color3 } from '@babylonjs/core/Maths/math.color';
+import { PBRMaterial } from '@babylonjs/core/Materials/PBR/pbrMaterial';
+import type { BaseTexture } from '@babylonjs/core/Materials/Textures/baseTexture';
+import type { Material } from '@babylonjs/core/Materials/material';
+import { Mesh } from '@babylonjs/core/Meshes/mesh';
+import { CreateBox } from '@babylonjs/core/Meshes/Builders/boxBuilder';
+import { SceneLoader } from '@babylonjs/core/Loading/sceneLoader';
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import type { Scene } from '@babylonjs/core/scene';
+// 精简 glTF loader:只注册 2.0 核心加载器,不引入扩展(尤其避免 EXT_meshopt_compression
+// 把 MeshoptDecoder 拉进包——本特效的 GLB 是 plain、零扩展,核心加载器即可)。
+import '@babylonjs/loaders/glTF/2.0/glTFLoader';
+import type { VfxEffectPackage, VfxParamValues } from '../../types';
+import { VFX_RENDERING_GROUP_ID } from '../../rendering';
+import sourceManifest from './effect.json';
+
+type LumberDebrisScatterMode = 'vertical' | 'radial';
+
+const USE_SHARED_SCENE_MATERIAL_FOR_DEBRIS = 'useSharedSceneMaterialForDebris';
+// 模型自带在包内 assets/models/(库纯净契约:不依赖项目资产注册)
+
+interface LumberDebrisScatterParams extends VfxParamValues {
+  lifetime: number;
+  scale: number;
+  initialHeight: number;
+  count: number;
+  spread: number;
+  speed: number;
+  size: number;
+  sizeX: number;
+  sizeY: number;
+  sizeZ: number;
+  scatterShape: LumberDebrisScatterMode;
+  outwardAngle: number;
+  scatterGravity: number;
+  rotationStrength: number;
+}
+
+interface LumberDebrisPieceState {
+  active: boolean;
+  startPos: Vector3;
+  targetPos: Vector3;
+  startRotation: Vector3;
+  rotationDelta: Vector3;
+  duration: number;
+  elapsed: number;
+  gravity: number;
+  scale: number;
+  scaleAxes: Vector3;
+}
+
+interface LumberDebrisScatterOptions {
+  count: number;
+  capacity: number;
+  effectScale: number;
+  resourceScale: number;
+  resourceScaleAxes: Vector3;
+  initialHeight: number;
+  spread: number;
+  duration: number;
+  speedScale: number;
+  intervalMs: number;
+  emissionDirection: Vector3;
+  scatterMode: LumberDebrisScatterMode;
+  scatterGravity: number;
+  rotationStrength: number;
+  outwardAngleDegrees: number;
+  renderingGroupId?: number;
+}
+
+import MODEL_URL from './assets/models/lumber_prop_model.glb?url';
+const SOURCE_EMITTER = readSourceEmitter();
+const cachedModelSourceByScene = new WeakMap<Scene, Promise<Mesh>>();
+
+const DEFAULT_PARAMS: LumberDebrisScatterParams = {
+  lifetime: readNumber(SOURCE_EMITTER.duration, 0.86),
+  scale: readNumber(SOURCE_EMITTER.effectScale, 1),
+  initialHeight: 0.42,
+  count: readNumber(SOURCE_EMITTER.count, 18),
+  spread: readNumber(SOURCE_EMITTER.spread, 0.78),
+  speed: readNumber(SOURCE_EMITTER.speedScale, 1),
+  size: readNumber(SOURCE_EMITTER.resourceScale, 1),
+  sizeX: 1,
+  sizeY: 1,
+  sizeZ: 1,
+  scatterShape: SOURCE_EMITTER.scatterMode === 'vertical' ? 'vertical' : 'radial',
+  outwardAngle: readNumber(SOURCE_EMITTER.outwardAngleDegrees, 240),
+  scatterGravity: readNumber(SOURCE_EMITTER.scatterGravity, 1),
+  rotationStrength: readNumber(SOURCE_EMITTER.rotationStrength, 0.85),
+};
+
+export const lumberDebrisScatterEffectPackage: VfxEffectPackage<LumberDebrisScatterParams> = {
+  id: 'lumber-debris-scatter',
+  nameZh: '木材碎块散落',
+  manifest: {
+    id: 'build.particle.lumber_debris_scatter',
+    nameZh: '木材碎块散落',
+    assets: ['imported/asset_0ec63a18aa2d4b12a9b4ca5dff6416e7.glb'],
+    source: 'lumber_debris_scatter.json',
+  },
+  defaultParams: DEFAULT_PARAMS,
+  debugAnchor: 'playerRight',
+  debugParams: [
+    { key: 'lifetime', label: '生命周期', kind: 'lifetime', min: 0.08, max: 6, step: 0.01 },
+    { key: 'scale', label: '整体缩放', kind: 'scale', min: 0.01, max: 20, step: 0.01 },
+    { key: 'initialHeight', label: '初始高度', kind: 'number', min: 0, max: 6, step: 0.01 },
+    { key: 'count', label: '碎块数量', kind: 'number', min: 1, max: 90, step: 1 },
+    { key: 'spread', label: '扩散幅度', kind: 'number', min: 0, max: 20, step: 0.01 },
+    { key: 'speed', label: '播放速度', kind: 'number', min: 0.1, max: 20, step: 0.01 },
+    { key: 'size', label: '碎块大小', kind: 'number', min: 0.01, max: 20, step: 0.01 },
+    { key: 'sizeX', label: '木头X缩放', kind: 'number', min: 0.01, max: 20, step: 0.01 },
+    { key: 'sizeY', label: '木头Y缩放', kind: 'number', min: 0.01, max: 20, step: 0.01 },
+    { key: 'sizeZ', label: '木头Z缩放', kind: 'number', min: 0.01, max: 20, step: 0.01 },
+    {
+      key: 'scatterShape',
+      label: '散落形态',
+      kind: 'enum',
+      options: [
+        { value: 'radial', label: '中心外扩' },
+        { value: 'vertical', label: '垂直下落' },
+      ],
+    },
+    { key: 'outwardAngle', label: '外扩角度', kind: 'number', min: 0, max: 360, step: 0.1 },
+    { key: 'scatterGravity', label: '下落重力', kind: 'number', min: 0.01, max: 20, step: 0.01 },
+    { key: 'rotationStrength', label: '旋转强度', kind: 'number', min: 0, max: 20, step: 0.01 },
+  ],
+  create({ scene, root, position, renderingGroupId, params }) {
+    root.position.copyFrom(position);
+    let disposed = false;
+    let effect: LumberDebrisScatterEffect | null = null;
+    const disposeTimer = window.setTimeout(() => disposeAll(), getDisposeDelaySeconds(params) * 1000);
+
+    const ready = emitLumberDebrisScatterFromModel(scene, position, toScatterOptions(params, renderingGroupId))
+      .then((createdEffect) => {
+        if (disposed) {
+          createdEffect.dispose();
+          return;
+        }
+        effect = createdEffect;
+      })
+      .catch((error) => {
+        console.warn('[VFX] Failed to warm lumber debris scatter.', error);
+      });
+
+    return {
+      root,
+      ready,
+      dispose() {
+        disposeAll();
+      },
+    };
+
+    function disposeAll(): void {
+      if (disposed) return;
+      disposed = true;
+      window.clearTimeout(disposeTimer);
+      effect?.dispose();
+      effect = null;
+      root.dispose();
+    }
+  },
+};
+
+class LumberDebrisScatterEffect {
+  private readonly sourceTemplate: Mesh;
+  private readonly debrisMeshes: Mesh[] = [];
+  private readonly material: Material;
+  private readonly ownsMaterial: boolean;
+  private readonly ownsSourceTemplate: boolean;
+  private readonly baseScaling: Vector3;
+  private readonly states: LumberDebrisPieceState[] = [];
+  private readonly observer;
+  private elapsed = 0;
+  private activeCount = 0;
+  private disposed = false;
+  private readonly disposeAfter: number;
+
+  constructor(
+    private readonly scene: Scene,
+    origin: Vector3,
+    options: LumberDebrisScatterOptions,
+    sourceMesh?: Mesh,
+    ownsSourceTemplate = true,
+  ) {
+    const count = Math.max(0, Math.round(options.count));
+    const capacity = Math.max(8, Math.round(options.capacity));
+    const effectScale = Math.max(0.01, options.effectScale);
+    const resourceScale = Math.max(0.01, options.resourceScale);
+    const resourceScaleAxes = new Vector3(
+      Math.max(0.01, options.resourceScaleAxes.x),
+      Math.max(0.01, options.resourceScaleAxes.y),
+      Math.max(0.01, options.resourceScaleAxes.z),
+    );
+    const duration = Math.max(0.08, options.duration) / Math.max(0.1, options.speedScale);
+    const interval = Math.max(0, options.intervalMs) / 1000;
+    const spread = Math.max(0, options.spread) * effectScale;
+    const initialHeight = Math.max(0, options.initialHeight) * effectScale;
+    const gravity = Math.max(0.05, options.scatterGravity);
+    const rotationStrength = Math.max(0, options.rotationStrength);
+    const outwardAngleRadians = clamp(options.outwardAngleDegrees, 0, 360) * (Math.PI / 180);
+
+    const source = sourceMesh ?? createFallbackSourceMesh(scene, 'lumber_debris_scatter_source');
+    const sourceMaterial = source.material;
+    const materialBinding = createDebrisMaterialBinding(scene, sourceMaterial, shouldUseSharedSceneMaterial(source));
+    this.material = materialBinding.material;
+    this.ownsMaterial = materialBinding.ownsMaterial;
+    this.sourceTemplate = source;
+    this.ownsSourceTemplate = ownsSourceTemplate;
+    this.baseScaling = source.scaling.clone();
+
+    for (let index = 0; index < capacity; index += 1) {
+      const mesh = createDebrisPieceMesh(source, this.material, index, options.renderingGroupId);
+      if (!mesh) continue;
+      this.debrisMeshes.push(mesh);
+      this.states.push(createDebrisPieceState(index, count, origin, {
+        duration,
+        effectScale,
+        gravity,
+        initialHeight,
+        interval,
+        mode: options.scatterMode,
+        resourceScale,
+        resourceScaleAxes,
+        rotationStrength,
+        spread,
+        outwardAngleRadians,
+        emissionDirection: options.emissionDirection,
+      }));
+    }
+
+    this.activeCount = this.states.filter((state) => state.active).length;
+    this.disposeAfter = duration + interval * Math.max(0, count - 1) + 0.35;
+    this.updateDebrisMeshes();
+    this.observer = scene.onBeforeRenderObservable.add(() => this.update());
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.scene.onBeforeRenderObservable.remove(this.observer);
+    for (const mesh of this.debrisMeshes) mesh.dispose();
+    this.debrisMeshes.length = 0;
+    if (this.ownsSourceTemplate) this.sourceTemplate.dispose();
+    if (this.ownsMaterial) this.material.dispose();
+  }
+
+  private update(): void {
+    if (this.disposed) return;
+    const deltaTime = this.scene.getEngine().getDeltaTime() / 1000;
+    this.elapsed += deltaTime;
+    for (const state of this.states) {
+      if (!state.active) continue;
+      state.elapsed += deltaTime;
+      if (state.elapsed >= state.duration) {
+        state.active = false;
+        this.activeCount = Math.max(0, this.activeCount - 1);
+      }
+    }
+    this.updateDebrisMeshes();
+    if (this.activeCount <= 0 && this.elapsed >= this.disposeAfter) this.dispose();
+  }
+
+  private updateDebrisMeshes(): void {
+    for (let index = 0; index < this.debrisMeshes.length; index += 1) {
+      const mesh = this.debrisMeshes[index];
+      const state = this.states[index];
+      if (!state?.active || state.elapsed < 0) {
+        mesh.isVisible = false;
+        mesh.scaling.set(0, 0, 0);
+        continue;
+      }
+
+      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));
+
+      mesh.isVisible = true;
+      mesh.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),
+      );
+      mesh.rotation.set(
+        state.startRotation.x + state.rotationDelta.x * t,
+        state.startRotation.y + state.rotationDelta.y * t,
+        state.startRotation.z + state.rotationDelta.z * t,
+      );
+      mesh.scaling.set(
+        this.baseScaling.x * state.scale * state.scaleAxes.x,
+        this.baseScaling.y * state.scale * state.scaleAxes.y,
+        this.baseScaling.z * state.scale * state.scaleAxes.z,
+      );
+    }
+  }
+}
+
+function createDebrisPieceMesh(source: Mesh, material: Material, index: number, renderingGroupId?: number): Mesh | null {
+  const mesh = source.clone(`lumber_debris_scatter_piece_${index}`, null, false);
+  if (!mesh) return null;
+  mesh.parent = null;
+  mesh.rotationQuaternion = null;
+  mesh.material = material;
+  mesh.isPickable = false;
+  mesh.alwaysSelectAsActiveMesh = true;
+  mesh.isVisible = false;
+  mesh.setEnabled(true);
+  copyDebrisMeshRenderState(mesh, source, renderingGroupId);
+  mesh.metadata = {
+    ...((mesh.metadata as Record<string, unknown> | null) ?? {}),
+    disablePlanarShadow: true,
+    disablePostOutlineDepth: true,
+  };
+  return mesh;
+}
+
+async function emitLumberDebrisScatterFromModel(
+  scene: Scene,
+  origin: Vector3,
+  options: LumberDebrisScatterOptions,
+): Promise<LumberDebrisScatterEffect> {
+  try {
+    const source = await getCachedLumberSourceMesh(scene);
+    return new LumberDebrisScatterEffect(scene, origin, options, source, false);
+  } catch (error) {
+    console.warn('[VFX] Unable to load lumber debris model; trying scene wood source.', error);
+    const sceneSource = createSceneWoodSourceMesh(scene);
+    if (sceneSource) return new LumberDebrisScatterEffect(scene, origin, options, sceneSource);
+
+    console.warn('[VFX] Unable to find scene wood source; using box fallback.');
+    return new LumberDebrisScatterEffect(scene, origin, options);
+  }
+}
+
+function getCachedLumberSourceMesh(scene: Scene): Promise<Mesh> {
+  const existing = cachedModelSourceByScene.get(scene);
+  if (existing) return existing;
+  const promise = loadLumberSourceMesh(scene, MODEL_URL, 'lumber_debris_scatter_model_source')
+    .catch((error) => {
+      cachedModelSourceByScene.delete(scene);
+      throw error;
+    });
+  cachedModelSourceByScene.set(scene, promise);
+  return promise;
+}
+
+function createSceneWoodSourceMesh(scene: Scene): Mesh | null {
+  const sourceMesh = findSceneWoodMesh(scene);
+  if (!sourceMesh) return null;
+  const clone = sourceMesh.clone('lumber_debris_scatter_scene_source', null, false);
+  if (!clone) return null;
+  clone.parent = null;
+  clone.position.set(0, 0, 0);
+  clone.rotation.set(0, 0, 0);
+  clone.rotationQuaternion = null;
+  clone.material = sourceMesh.material;
+  clone.metadata = {
+    ...((clone.metadata as Record<string, unknown> | null) ?? {}),
+    [USE_SHARED_SCENE_MATERIAL_FOR_DEBRIS]: true,
+  };
+  normalizeLumberSourceMesh(clone);
+  clone.isVisible = false;
+  clone.setEnabled(false);
+  return clone;
+}
+
+function findSceneWoodMesh(scene: Scene): Mesh | null {
+  const sceneWoodCandidates = scene.meshes.filter((mesh) => !isVfxGeneratedMesh(mesh));
+  const namedWoodMesh = findPreferredRenderableMesh(sceneWoodCandidates.filter((mesh) => isSceneSingleWoodMesh(mesh)));
+  if (namedWoodMesh) return namedWoodMesh;
+
+  // 库纯净契约:不引用项目 gameplay 配置的节点 id;退化为按名称启发式查找(见下方 woodFallback)。
+  const ids: string[] = [];
+  for (const id of ids) {
+    const root = scene.transformNodes.find((node) => isExactAssetNodeMatch(node.id, id) || isExactAssetNodeMatch(node.name, id));
+    const mesh = root ? findPreferredRenderableMesh(root.getChildMeshes(false).filter((item) => !isVfxGeneratedMesh(item))) : findPreferredRenderableMesh(
+      sceneWoodCandidates.filter((item) => isExactAssetNodeMatch(item.id, id) || isExactAssetNodeMatch(item.name, id)),
+    );
+    if (mesh) return mesh;
+  }
+  const woodFallback = findPreferredRenderableMesh(sceneWoodCandidates.filter((mesh) => /wood|lumber|\u6728\u6750|\u6574\u6346/i.test(`${mesh.name} ${mesh.id}`)));
+  if (woodFallback) return woodFallback;
+  return findPreferredRenderableMesh(sceneWoodCandidates.filter((mesh) => /wood|lumber|木材|整捆/i.test(`${mesh.name} ${mesh.id}`)));
+}
+
+function isExactAssetNodeMatch(value: string, assetId: string): boolean {
+  return value === assetId || value.startsWith(`${assetId}_`) || value.startsWith(`${assetId}:`);
+}
+
+function findPreferredRenderableMesh(meshes: AbstractMesh[]): Mesh | null {
+  const renderableMeshes = meshes.filter(isRenderableMesh);
+  const rankedWoodMeshes = renderableMeshes
+    .map((mesh) => ({ mesh, score: getSceneWoodMeshScore(mesh) }))
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  return rankedWoodMeshes.find(({ mesh }) => Boolean(mesh.material) && mesh.isEnabled() && mesh.isVisible)?.mesh
+    ?? rankedWoodMeshes.find(({ mesh }) => Boolean(mesh.material))?.mesh
+    ?? renderableMeshes.find((mesh) => Boolean(mesh.material) && mesh.isEnabled() && mesh.isVisible)
+    ?? renderableMeshes.find((mesh) => Boolean(mesh.material))
+    ?? renderableMeshes[0]
+    ?? null;
+}
+
+function getSceneWoodMeshScore(mesh: AbstractMesh): number {
+  const meshText = `${mesh.name} ${mesh.id}`;
+  const material = mesh.material;
+  const materialText = `${material?.name ?? ''} ${material?.id ?? ''}`;
+  const textureText = [
+    readMaterialTexture(material, 'albedoTexture'),
+    readMaterialTexture(material, 'diffuseTexture'),
+  ].map(readTextureSearchText).join(' ');
+  const combinedText = `${meshText} ${materialText} ${textureText}`;
+
+  let score = 0;
+  if (isSceneSingleWoodMesh(mesh)) score += 10;
+  if (/单根|單根|single/i.test(combinedText)) score += 8;
+  if (/木材|wood|lumber/i.test(combinedText)) score += 4;
+  if (/pipe|stack|整捆|bundle/i.test(materialText)) score -= 6;
+  if (material) score += 2;
+  if (mesh.isEnabled() && mesh.isVisible) score += 1;
+  return score;
+}
+
+function readTextureSearchText(texture: BaseTexture | null): string {
+  const textureData = texture as (BaseTexture & { url?: string }) | null;
+  return `${textureData?.name ?? ''} ${textureData?.url ?? ''}`;
+}
+
+function isSceneSingleWoodMesh(mesh: AbstractMesh): boolean {
+  if (/wood|lumber|\u6728\u6750|\u5355\u6839/i.test(`${mesh.name} ${mesh.id}`)) return true;
+  return /wood|lumber|木材|單根|单根/i.test(`${mesh.name} ${mesh.id}`);
+}
+
+function isVfxGeneratedMesh(mesh: AbstractMesh): boolean {
+  let current: { name?: string; id?: string; parent?: unknown } | null = mesh;
+  while (current) {
+    const name = `${current.name} ${current.id}`;
+    if (
+      name.includes('vfx_package_')
+      || name.includes('lumber-cart-suction')
+      || name.includes('lumber_debris_scatter')
+    ) {
+      return true;
+    }
+    current = current.parent && typeof current.parent === 'object'
+      ? current.parent as { name?: string; id?: string; parent?: unknown }
+      : null;
+  }
+  return false;
+}
+
+async function loadLumberSourceMesh(scene: Scene, modelUrl: string, name: string): Promise<Mesh> {
+  // 内联后 modelUrl 可能是 base64 data URI(含 '/',不可按斜杠切分):整串作 fileName + 显式 .glb 插件
+  const isDataUri = modelUrl.startsWith('data:');
+  const lastSlash = isDataUri ? -1 : modelUrl.lastIndexOf('/');
+  const rootUrl = lastSlash >= 0 ? modelUrl.slice(0, lastSlash + 1) : '';
+  const fileName = lastSlash >= 0 ? modelUrl.slice(lastSlash + 1) : modelUrl;
+  const result = await SceneLoader.ImportMeshAsync('', rootUrl, fileName, scene, undefined, '.glb');
+  const meshes = result.meshes.filter(isRenderableMesh);
+  if (meshes.length === 0) throw new Error(`No mesh was found in ${modelUrl}.`);
+
+  const source = meshes.length === 1
+    ? meshes[0]
+    : Mesh.MergeMeshes(meshes, true, true, undefined, false, true);
+  if (!source) throw new Error(`Unable to merge meshes from ${modelUrl}.`);
+
+  source.name = name;
+  source.isVisible = false;
+  source.setEnabled(false);
+  source.rotationQuaternion = null;
+  source.metadata = {
+    ...((source.metadata as Record<string, unknown> | null) ?? {}),
+    [USE_SHARED_SCENE_MATERIAL_FOR_DEBRIS]: true,
+  };
+  normalizeLumberSourceMesh(source);
+  return source;
+}
+
+function normalizeLumberSourceMesh(source: Mesh): void {
+  source.refreshBoundingInfo(true);
+  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.refreshBoundingInfo(true);
+}
+
+function createFallbackSourceMesh(scene: Scene, name: string): Mesh {
+  const source = CreateBox(name, {
+    width: 0.22,
+    height: 0.16,
+    depth: 0.82,
+  }, scene);
+  source.isVisible = false;
+  source.setEnabled(false);
+  return source;
+}
+
+function createFallbackMaterial(scene: Scene): PBRMaterial {
+  const material = new PBRMaterial('lumber_debris_scatter_material', scene);
+  material.albedoColor = new Color3(0.52, 0.31, 0.13);
+  material.emissiveColor = Color3.Black();
+  material.metallic = 0;
+  material.roughness = 0.92;
+  material.environmentIntensity = 1.15;
+  material.directIntensity = 1;
+  material.unlit = false;
+  return material;
+}
+
+interface DebrisMaterialBinding {
+  material: Material;
+  ownsMaterial: boolean;
+}
+
+function createDebrisMaterialBinding(
+  scene: Scene,
+  sourceMaterial: Material | null,
+  useSharedSceneMaterial: boolean,
+): DebrisMaterialBinding {
+  if (useSharedSceneMaterial && sourceMaterial) {
+    return { material: sourceMaterial, ownsMaterial: false };
+  }
+
+  return {
+    material: createDebrisMaterialFromSceneMaterial(scene, sourceMaterial),
+    ownsMaterial: true,
+  };
+}
+
+function shouldUseSharedSceneMaterial(mesh: Mesh): boolean {
+  return Boolean((mesh.metadata as Record<string, unknown> | null)?.[USE_SHARED_SCENE_MATERIAL_FOR_DEBRIS]);
+}
+
+function createDebrisMaterialFromSceneMaterial(scene: Scene, sourceMaterial: Material | null): Material {
+  if (sourceMaterial instanceof PBRMaterial) {
+    const cloned = sourceMaterial.clone(`lumber_debris_scatter_material_from_${sourceMaterial.name || sourceMaterial.id}`);
+    if (cloned instanceof PBRMaterial) {
+      configureDebrisPbrMaterial(cloned, sourceMaterial);
+      return cloned;
+    }
+  }
+
+  const material = createFallbackMaterial(scene);
+  if (sourceMaterial) material.name = `lumber_debris_scatter_material_from_${sourceMaterial.name || sourceMaterial.id}`;
+  configureDebrisPbrMaterial(material, sourceMaterial);
+  return material;
+}
+
+function readMaterialColor(material: Material | null, key: string): Color3 | null {
+  const value = readMaterialProperty(material, key);
+  if (value instanceof Color3) return value;
+  if (!value || typeof value !== 'object') return null;
+  const colorLike = value as Record<string, unknown>;
+  const r = readFiniteNumber(colorLike.r) ?? readFiniteNumber(colorLike._r);
+  const g = readFiniteNumber(colorLike.g) ?? readFiniteNumber(colorLike._g);
+  const b = readFiniteNumber(colorLike.b) ?? readFiniteNumber(colorLike._b);
+  return r == null || g == null || b == null ? null : new Color3(r, g, b);
+}
+
+function readMaterialTexture(material: Material | null, key: string): BaseTexture | null {
+  const value = readMaterialProperty(material, key);
+  return value && typeof value === 'object' ? value as BaseTexture : null;
+}
+
+function readMaterialNumber(material: Material | null, key: string, fallback: number): number {
+  const value = readMaterialProperty(material, key);
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+function readMaterialProperty(material: Material | null, key: string): unknown {
+  return material && key in material ? (material as unknown as Record<string, unknown>)[key] : undefined;
+}
+
+function configureDebrisPbrMaterial(material: PBRMaterial, sourceMaterial: Material | null): void {
+  const albedoTexture = readMaterialTexture(sourceMaterial, 'albedoTexture')
+    ?? readMaterialTexture(sourceMaterial, 'diffuseTexture');
+  if (albedoTexture && 'gammaSpace' in albedoTexture) albedoTexture.gammaSpace = true;
+  const albedoColor = readMaterialColor(sourceMaterial, 'albedoColor')
+    ?? readMaterialColor(sourceMaterial, 'diffuseColor');
+  material.albedoTexture = albedoTexture;
+  material.albedoColor = albedoTexture
+    ? (albedoColor && !isNearlyBlack(albedoColor) ? albedoColor.clone() : Color3.White())
+    : (albedoColor && !isNearlyBlack(albedoColor) ? albedoColor.clone() : new Color3(0.52, 0.31, 0.13));
+
+  material.emissiveTexture = null;
+  material.emissiveColor = material.albedoColor.clone();
+
+  material.alpha = readMaterialNumber(sourceMaterial, 'alpha', 1);
+  material.backFaceCulling = sourceMaterial?.backFaceCulling ?? false;
+  material.metallic = readMaterialNumber(sourceMaterial, 'metallic', 0);
+  material.roughness = readMaterialNumber(sourceMaterial, 'roughness', 0.92);
+  material.environmentIntensity = 0;
+  material.directIntensity = 0;
+  disableMaterialVertexColor(material);
+  material.unlit = true;
+}
+
+function readFiniteNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function disableMaterialVertexColor(material: Material): void {
+  const materialFlags = material as unknown as Record<string, unknown>;
+  materialFlags.useVertexColor = false;
+  materialFlags.useVertexColors = false;
+  materialFlags.useVertexAlpha = false;
+  materialFlags.useVertexAlphas = false;
+}
+
+function copyDebrisMeshRenderState(mesh: Mesh, source: Mesh, renderingGroupId?: number): void {
+  mesh.layerMask = source.layerMask;
+  mesh.renderingGroupId = renderingGroupId ?? Math.max(source.renderingGroupId, VFX_RENDERING_GROUP_ID);
+}
+
+function isNearlyBlack(color: Color3): boolean {
+  return color.r + color.g + color.b < 0.045;
+}
+
+function createDebrisPieceState(
+  index: number,
+  count: number,
+  origin: Vector3,
+  options: {
+    duration: number;
+    effectScale: number;
+    gravity: number;
+    initialHeight: number;
+    interval: number;
+    mode: LumberDebrisScatterMode;
+    resourceScale: number;
+    resourceScaleAxes: Vector3;
+    rotationStrength: number;
+    spread: number;
+    outwardAngleRadians: number;
+    emissionDirection: Vector3;
+  },
+): LumberDebrisPieceState {
+  const active = index < count;
+  const angleSeed = sequence01(index, 0);
+  const radiusSeed = Math.sqrt(sequence01(index, 1));
+  const sideSeed = sequence01(index, 2) < 0.5 ? -1 : 1;
+  const normalizedDirection = options.emissionDirection.clone();
+  normalizedDirection.y = 0;
+  if (normalizedDirection.lengthSquared() < 0.0001) normalizedDirection.set(1, 0, 0);
+  normalizedDirection.normalize();
+
+  const baseAngle = Math.atan2(normalizedDirection.z, normalizedDirection.x);
+  const radialAngle = options.mode === 'radial'
+    ? baseAngle + (angleSeed - 0.5) * options.outwardAngleRadians
+    : angleSeed * Math.PI * 2;
+  const scatterRadius = options.spread * (0.35 + radiusSeed * 0.65);
+  const localX = Math.cos(radialAngle) * scatterRadius;
+  const localZ = Math.sin(radialAngle) * scatterRadius;
+
+  const startPos = options.mode === 'radial'
+    ? new Vector3(
+      origin.x + normalizedDirection.x * options.spread * 0.08,
+      origin.y + options.initialHeight,
+      origin.z + normalizedDirection.z * options.spread * 0.08,
+    )
+    : new Vector3(
+      origin.x + localX * 0.52,
+      origin.y + options.initialHeight + sequence01(index, 3) * 0.24 * options.effectScale,
+      origin.z + localZ * 0.52,
+    );
+  const targetPos = options.mode === 'radial'
+    ? new Vector3(origin.x + localX, origin.y, origin.z + localZ)
+    : new Vector3(origin.x + localX * 0.52, origin.y, origin.z + localZ * 0.52);
+  const rotationBase = Math.PI * 2 * options.rotationStrength;
+
+  return {
+    active,
+    startPos,
+    targetPos,
+    startRotation: new Vector3(
+      (sequence01(index, 4) - 0.5) * rotationBase,
+      (sequence01(index, 5) - 0.5) * rotationBase,
+      (sequence01(index, 6) - 0.5) * rotationBase,
+    ),
+    rotationDelta: new Vector3(
+      sideSeed * (2.6 + sequence01(index, 7) * 2.2) * options.rotationStrength,
+      (sequence01(index, 8) - 0.5) * 7.2 * options.rotationStrength,
+      sideSeed * (1.7 + sequence01(index, 9) * 2.8) * options.rotationStrength,
+    ),
+    duration: options.duration * (0.88 + sequence01(index, 10) * 0.18),
+    elapsed: -index * options.interval,
+    gravity: options.gravity,
+    scale: options.resourceScale * options.effectScale * (0.68 + sequence01(index, 11) * 0.24),
+    scaleAxes: options.resourceScaleAxes.clone(),
+  };
+}
+
+function toScatterOptions(params: LumberDebrisScatterParams, renderingGroupId?: number): LumberDebrisScatterOptions {
+  return {
+    count: params.count,
+    capacity: Math.max(readNumber(SOURCE_EMITTER.capacity, params.count), params.count),
+    effectScale: params.scale,
+    resourceScale: params.size,
+    resourceScaleAxes: new Vector3(
+      readNumber(params.sizeX, 1),
+      readNumber(params.sizeY, 1),
+      readNumber(params.sizeZ, 1),
+    ),
+    initialHeight: params.initialHeight,
+    spread: params.spread,
+    duration: params.lifetime,
+    speedScale: params.speed,
+    intervalMs: readNumber(SOURCE_EMITTER.intervalMs, 18),
+    emissionDirection: new Vector3(1, 0.35, 0),
+    scatterMode: params.scatterShape === 'vertical' ? 'vertical' : 'radial',
+    scatterGravity: params.scatterGravity,
+    rotationStrength: params.rotationStrength,
+    outwardAngleDegrees: params.outwardAngle,
+    renderingGroupId,
+  };
+}
+
+function getDisposeDelaySeconds(params: LumberDebrisScatterParams): number {
+  const duration = Math.max(0.08, params.lifetime) / Math.max(0.1, params.speed);
+  const interval = Math.max(0, readNumber(SOURCE_EMITTER.intervalMs, 18)) / 1000;
+  return duration + interval * Math.max(0, Math.round(params.count) - 1) + 0.55;
+}
+
+function readSourceEmitter(): Record<string, unknown> {
+  const manifest = sourceManifest as { emitters?: Array<Record<string, unknown>> };
+  return manifest.emitters?.[0] ?? {};
+}
+
+function isRenderableMesh(mesh: AbstractMesh): mesh is Mesh {
+  return mesh instanceof Mesh && mesh.getTotalVertices() > 0 && !isPlanarShadowMesh(mesh);
+}
+
+function isPlanarShadowMesh(mesh: AbstractMesh): boolean {
+  const metadata = mesh.metadata as { planarShadowInternal?: unknown; disablePlanarShadow?: unknown } | null;
+  if (metadata?.planarShadowInternal === true) return true;
+  if (mesh.name.includes('_planarShadow') || mesh.id.includes('_planarShadow')) return true;
+  const materialName = `${mesh.material?.name ?? ''} ${mesh.material?.id ?? ''}`;
+  return /fps\.planarShadow/i.test(materialName);
+}
+
+function readNumber(value: unknown, fallback: number): number {
+  const next = Number(value);
+  return Number.isFinite(next) ? next : fallback;
+}
+
+function clamp(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 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);
+}
+
+function bounceOut(t: number): number {
+  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: number, end: number, t: number): number {
+  return start + (end - start) * t;
+}