@fps-games/vfx 0.1.1 → 0.3.3

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

@@ -1,780 +0,0 @@
-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;
-}