@fps-games/editor 0.1.5-beta.5 → 0.1.7-beta.1

package/node_modules/@fps-games/editor-babylon/dist/shadow-preview-controller.js

@@ -1,13 +1,19 @@
 import { createBlobShadowSystem, createPlanarShadowSystem, collectStaticProjectedShadowBakeRoots, createStaticProjectedShadowArtifactSystem, createStaticProjectedShadowBakeHashes, } from '@fps-games/babylon-renderer';
+import { ShadowGenerator } from '@babylonjs/core/Lights/Shadows/shadowGenerator.js';
 const PLANAR_PREVIEW_ROOT_BOUNDARY_PATTERNS = ['root', 'scene_builder_root'];
+const SHADOW_DEBUG_STORAGE_KEY = 'fps.shadow.debug';
 export function createBabylonEditorShadowPreviewController(options) {
     let currentOptions = normalizeShadowPreviewOptions(options.options);
     let blobSystem = null;
     let staticSystem = null;
     let planarSystem = null;
     let planarLight = null;
+    let dynamicGenerator = null;
+    let dynamicLight = null;
+    let dynamicMapSize = 0;
     const blobCasters = new Set();
     const planarCasters = new Set();
+    const dynamicCasters = new Set();
     const disposeBlob = () => {
         blobSystem?.dispose();
         blobSystem = null;
@@ -23,6 +29,16 @@ export function createBabylonEditorShadowPreviewController(options) {
         staticSystem?.dispose();
         staticSystem = null;
     };
+    const disposeDynamic = () => {
+        dynamicGenerator?.dispose();
+        dynamicGenerator = null;
+        dynamicLight = null;
+        dynamicMapSize = 0;
+        dynamicCasters.clear();
+        for (const mesh of readSceneMeshes(options.scene)) {
+            setPreviewMeshReceiveShadows(mesh, false);
+        }
+    };
     const syncBlob = () => {
         const blobOptions = currentOptions.blob;
         if (!blobOptions || blobOptions.enabled === false) {
@@ -80,18 +96,82 @@ export function createBabylonEditorShadowPreviewController(options) {
         const meshes = readSceneMeshes(options.scene);
         const nextBlobCasters = new Set();
         const nextPlanarCasters = new Set();
+        const nextDynamicCasters = new Set();
+        const nextDynamicReceivers = new Set();
         for (const mesh of meshes) {
             const mode = resolvePreviewMeshShadowMode(mesh, currentOptions.defaultMode ?? 'none');
+            if (!canRenderPreviewShadowCaster(mesh, mode, meshes))
+                continue;
             if (mode === 'blob' && blobSystem)
                 nextBlobCasters.add(mesh);
             if (mode === 'planar' && planarSystem)
                 nextPlanarCasters.add(mesh);
+            if (mode === 'dynamic')
+                nextDynamicCasters.add(mesh);
         }
+        for (const mesh of meshes) {
+            if (isPreviewShadowReceiver(mesh, meshes))
+                nextDynamicReceivers.add(mesh);
+        }
+        logShadowDebug('preview.routes', {
+            blobCasters: [...nextBlobCasters].map(readShadowPreviewMeshDebugName),
+            planarCasters: [...nextPlanarCasters].map(readShadowPreviewMeshDebugName),
+            dynamicCasters: [...nextDynamicCasters].map(readShadowPreviewMeshDebugName),
+            dynamicReceivers: [...nextDynamicReceivers].map(readShadowPreviewMeshDebugName),
+        });
+        syncDynamic(nextDynamicReceivers);
         syncDynamicShadowCasters(blobSystem, blobCasters, nextBlobCasters);
         syncDynamicShadowCasters(planarSystem, planarCasters, nextPlanarCasters);
+        syncBabylonDynamicShadowCasters(dynamicGenerator, dynamicCasters, nextDynamicCasters);
+        for (const mesh of meshes) {
+            setPreviewMeshReceiveShadows(mesh, false);
+        }
+        if (dynamicGenerator) {
+            for (const mesh of nextDynamicReceivers) {
+                setPreviewMeshReceiveShadows(mesh, true);
+            }
+        }
         blobSystem?.refresh();
         planarSystem?.refresh();
     };
+    const syncDynamic = (receivers) => {
+        const meshes = readSceneMeshes(options.scene);
+        const dynamicCasters = meshes.filter(mesh => {
+            const mode = resolvePreviewMeshShadowMode(mesh, currentOptions.defaultMode ?? 'none');
+            return mode === 'dynamic' && canRenderPreviewShadowCaster(mesh, mode, meshes);
+        });
+        if (dynamicCasters.length === 0) {
+            disposeDynamic();
+            return;
+        }
+        const light = resolveDynamicDirectionalLight(options.projection, dynamicCasters, currentOptions);
+        if (!light) {
+            disposeDynamic();
+            return;
+        }
+        const mapSize = resolveDynamicShadowMapSize(dynamicCasters);
+        if (!dynamicGenerator || dynamicLight !== light || dynamicMapSize !== mapSize) {
+            disposeDynamic();
+            dynamicLight = light;
+            dynamicMapSize = mapSize;
+            dynamicGenerator = new ShadowGenerator(mapSize, light);
+            configureDynamicShadowGeneratorFilter(dynamicGenerator);
+            dynamicGenerator.setDarkness(resolveDynamicShadowDarkness(dynamicCasters));
+            dynamicGenerator.bias = resolveDynamicShadowBias(dynamicCasters);
+            dynamicGenerator.normalBias = resolveDynamicShadowNormalBias(dynamicCasters);
+            if (options.scene)
+                options.scene.shadowsEnabled = true;
+            configureDirectionalLightShadowFrustum(light, currentOptions, dynamicCasters, [...receivers]);
+            logShadowDebug('preview.dynamic.created', createDynamicShadowDebugSnapshot(light, dynamicGenerator, dynamicCasters, [...receivers]));
+            return;
+        }
+        configureDynamicShadowGeneratorFilter(dynamicGenerator);
+        dynamicGenerator.setDarkness(resolveDynamicShadowDarkness(dynamicCasters));
+        dynamicGenerator.bias = resolveDynamicShadowBias(dynamicCasters);
+        dynamicGenerator.normalBias = resolveDynamicShadowNormalBias(dynamicCasters);
+        configureDirectionalLightShadowFrustum(light, currentOptions, dynamicCasters, [...receivers]);
+        logShadowDebug('preview.dynamic.updated', createDynamicShadowDebugSnapshot(light, dynamicGenerator, dynamicCasters, [...receivers]));
+    };
     syncRoutes();
     return {
         setOptions(nextOptions) {
@@ -112,6 +192,18 @@ export function createBabylonEditorShadowPreviewController(options) {
             }
             disposeStatic();
         },
+        getDebugInfo() {
+            return {
+                planar: {
+                    enabled: !!planarSystem,
+                    casterCount: planarCasters.size,
+                    casters: (planarSystem?.getCasterDebugInfo() ?? []).map(info => ({
+                        ...info,
+                        ...readPlanarShadowSourceNodeInfo(info, options.scene),
+                    })),
+                },
+            };
+        },
         refresh() {
             syncRoutes();
         },
@@ -119,12 +211,14 @@ export function createBabylonEditorShadowPreviewController(options) {
             disposeBlob();
             disposeStatic();
             disposePlanar();
+            disposeDynamic();
             syncRoutes();
         },
         dispose() {
             disposeBlob();
             disposeStatic();
             disposePlanar();
+            disposeDynamic();
         },
     };
 }
@@ -216,11 +310,42 @@ function syncDynamicShadowCasters(system, current, next) {
     }
     for (const mesh of next) {
         if (!current.has(mesh)) {
-            system.addCaster(mesh);
+            const added = system.addCaster(mesh);
+            if (added !== false)
+                current.add(mesh);
+        }
+    }
+}
+function syncBabylonDynamicShadowCasters(generator, current, next) {
+    for (const mesh of [...current]) {
+        if (!next.has(mesh)) {
+            generator?.removeShadowCaster(mesh, true);
+            current.delete(mesh);
+        }
+    }
+    if (!generator) {
+        current.clear();
+        return;
+    }
+    for (const mesh of next) {
+        if (!current.has(mesh)) {
+            generator.addShadowCaster(mesh, true);
             current.add(mesh);
         }
     }
 }
+function setPreviewMeshReceiveShadows(mesh, receive) {
+    if (!isBabylonInstancedMesh(mesh)) {
+        mesh.receiveShadows = receive;
+    }
+    const sourceMesh = mesh.sourceMesh;
+    if (sourceMesh && sourceMesh !== mesh && !isBabylonInstancedMesh(sourceMesh)) {
+        sourceMesh.receiveShadows = receive;
+    }
+}
+function isBabylonInstancedMesh(mesh) {
+    return mesh.getClassName?.() === 'InstancedMesh';
+}
 function readSceneMeshes(scene) {
     return Array.isArray(scene?.meshes) ? scene.meshes : [];
 }
@@ -242,12 +367,427 @@ function readPreviewDefaultMode(value) {
 function readProjectionShadowMode(mesh) {
     for (const node of walkNodeAndParents(mesh)) {
         const editorProjection = readEditorProjectionMetadata(node);
-        const mode = editorProjection?.shadowMode;
-        if (mode === 'default' || mode === 'none' || mode === 'blob' || mode === 'static' || mode === 'planar' || mode === 'dynamic')
+        const shadowPlanMode = readProjectionShadowPlanPreviewMode(editorProjection?.shadowPlan);
+        if (shadowPlanMode)
+            return shadowPlanMode;
+        const shadowMode = readProjectionShadowSettingsPreviewMode(editorProjection?.shadow);
+        if (shadowMode)
+            return shadowMode;
+        const mode = readLegacyProjectionShadowMode(editorProjection?.shadowMode);
+        if (mode)
             return mode;
     }
     return null;
 }
+function readProjectionShadowPlanPreviewMode(value) {
+    const plan = readObject(value);
+    if (!plan)
+        return null;
+    const backend = plan.backend;
+    if (backend === 'none')
+        return 'none';
+    if (backend === 'blob')
+        return 'blob';
+    if (backend === 'static-baked')
+        return 'static';
+    if (backend === 'projected')
+        return 'planar';
+    if (backend === 'dynamic-map')
+        return 'dynamic';
+    return readProjectionShadowSettingsPreviewMode({ mode: plan.mode });
+}
+function readProjectionShadowPlan(mesh) {
+    for (const node of walkNodeAndParents(mesh)) {
+        const plan = readObject(readEditorProjectionMetadata(node)?.shadowPlan);
+        if (plan)
+            return plan;
+    }
+    return null;
+}
+function readProjectionShadowSettings(mesh) {
+    for (const node of walkNodeAndParents(mesh)) {
+        const shadow = readObject(readEditorProjectionMetadata(node)?.shadow);
+        if (shadow)
+            return shadow;
+    }
+    return null;
+}
+function readProjectionNodeIds(mesh) {
+    const ids = [];
+    for (const node of walkNodeAndParents(mesh)) {
+        const projection = readEditorProjectionMetadata(node);
+        const nodeId = projection?.nodeId;
+        const rootNodeId = projection?.rootNodeId;
+        if (typeof nodeId === 'string' && !ids.includes(nodeId))
+            ids.push(nodeId);
+        if (typeof rootNodeId === 'string' && !ids.includes(rootNodeId))
+            ids.push(rootNodeId);
+    }
+    return ids;
+}
+function canRenderPreviewShadowCaster(mesh, mode, meshes) {
+    if (mode !== 'blob' && mode !== 'planar' && mode !== 'dynamic')
+        return true;
+    const plan = readProjectionShadowPlan(mesh);
+    if (!plan)
+        return meshes.some(candidate => isPreviewShadowReceiver(candidate, meshes));
+    const receiverIds = readShadowPlanReceiverIds(plan);
+    if (receiverIds.length === 0)
+        return false;
+    const receiverIdSet = new Set(receiverIds);
+    return meshes.some(candidate => {
+        if (!isPreviewShadowReceiver(candidate, meshes))
+            return false;
+        return readProjectionNodeIds(candidate).some(nodeId => receiverIdSet.has(nodeId));
+    });
+}
+function isPreviewShadowReceiver(mesh, meshes) {
+    if (mesh.isDisposed?.() || hasGeneratedShadowDisabled(mesh))
+        return false;
+    const receive = readProjectionShadowSettings(mesh)?.receive;
+    if (receive === 'none')
+        return false;
+    if (receive === 'enabled' || receive === 'auto')
+        return true;
+    const receiverNodeIds = readProjectionNodeIds(mesh);
+    if (receiverNodeIds.length === 0)
+        return false;
+    return meshes.some(candidate => {
+        const mode = resolvePreviewMeshShadowMode(candidate, 'none');
+        if (mode !== 'blob' && mode !== 'planar' && mode !== 'dynamic')
+            return false;
+        const receiverIds = readShadowPlanReceiverIds(readProjectionShadowPlan(candidate));
+        return receiverNodeIds.some(nodeId => receiverIds.includes(nodeId));
+    });
+}
+function readShadowPlanReceiverIds(plan) {
+    return Array.isArray(plan?.receiverIds)
+        ? plan.receiverIds.filter((entry) => typeof entry === 'string')
+        : [];
+}
+function resolveDynamicDirectionalLight(projection, casters, options) {
+    for (const caster of casters) {
+        const lightId = readProjectionShadowPlan(caster)?.lightId;
+        if (typeof lightId !== 'string')
+            continue;
+        const light = resolveDirectionalLight(projection, lightId);
+        if (light)
+            return light;
+    }
+    const planarLightId = options.planar
+        ? options.planar.directionalLightNodeId ?? null
+        : null;
+    return resolveDirectionalLight(projection, planarLightId);
+}
+function createDynamicShadowDebugSnapshot(light, generator, casters, receivers) {
+    return {
+        light: {
+            name: light.name,
+            id: light.id,
+            position: toPlainVec3(light.position),
+            direction: toPlainVec3(light.direction),
+            orthoLeft: light.orthoLeft,
+            orthoRight: light.orthoRight,
+            orthoTop: light.orthoTop,
+            orthoBottom: light.orthoBottom,
+            shadowMinZ: light.shadowMinZ,
+            shadowMaxZ: light.shadowMaxZ,
+            autoUpdateExtends: light.autoUpdateExtends,
+        },
+        generator: generator
+            ? {
+                mapSize: generator.getShadowMap?.()?.getSize?.(),
+                darkness: generator.getDarkness?.(),
+                bias: generator.bias,
+                normalBias: generator.normalBias,
+                useBlurExponentialShadowMap: generator.useBlurExponentialShadowMap,
+                useKernelBlur: generator.useKernelBlur,
+                blurKernel: generator.blurKernel,
+                renderList: (generator.getShadowMap?.()?.renderList ?? []).map(readShadowPreviewMeshDebugName),
+            }
+            : null,
+        casters: casters.map(mesh => ({
+            name: readShadowPreviewMeshDebugName(mesh),
+            bounds: readMeshWorldBounds(mesh),
+        })),
+        receivers: receivers.map(mesh => ({
+            name: readShadowPreviewMeshDebugName(mesh),
+            receiveShadows: mesh.receiveShadows,
+            bounds: readMeshWorldBounds(mesh),
+        })),
+    };
+}
+function resolveDynamicShadowMapSize(casters) {
+    return clampDynamicShadowResolution(Math.max(0, ...casters.map(caster => readShadowPlanNumber(caster, 'resolution'))));
+}
+function configureDynamicShadowGeneratorFilter(generator) {
+    generator.useBlurExponentialShadowMap = false;
+    generator.useKernelBlur = false;
+    generator.usePercentageCloserFiltering = true;
+    generator.filteringQuality = ShadowGenerator.QUALITY_HIGH;
+}
+function resolveDynamicShadowDarkness(casters) {
+    const opacity = Math.max(0, ...casters.map(caster => readShadowPlanNumber(caster, 'opacity')));
+    return Math.min(1, Math.max(0, 1 - (Number.isFinite(opacity) && opacity > 0 ? opacity : 0.42)));
+}
+function resolveDynamicShadowBias(casters) {
+    const values = casters.map(caster => readShadowPlanNumber(caster, 'bias')).filter(Number.isFinite);
+    return values.length > 0 ? Math.min(...values) : 0.0005;
+}
+function resolveDynamicShadowNormalBias(casters) {
+    const value = Math.max(0, ...casters.map(caster => readShadowPlanNumber(caster, 'normalBias')));
+    return Number.isFinite(value) && value > 0 ? value : 0.02;
+}
+function readShadowPlanNumber(caster, key) {
+    const params = readObject(readProjectionShadowPlan(caster)?.params);
+    const value = params?.[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : Number.NaN;
+}
+function clampDynamicShadowResolution(value) {
+    if (value >= 4096)
+        return 4096;
+    if (value >= 2048)
+        return 2048;
+    if (value >= 1024)
+        return 1024;
+    return 512;
+}
+function configureDirectionalLightShadowFrustum(light, options, casters = [], receivers = []) {
+    const dynamicBounds = createDynamicShadowFrustumBounds(casters, receivers, light.direction);
+    if (dynamicBounds) {
+        const maxExtent = Math.max(dynamicBounds.size.x, dynamicBounds.size.y, dynamicBounds.size.z);
+        const padding = Math.max(2, maxExtent * 0.25);
+        const halfSize = Math.max(4, maxExtent * 0.5 + padding);
+        const direction = normalizeVec3(light.direction) ?? { x: 0, y: -1, z: 0 };
+        const distance = Math.max(16, maxExtent + padding * 3);
+        setMutableVec3(light.position, {
+            x: dynamicBounds.center.x - direction.x * distance,
+            y: dynamicBounds.center.y - direction.y * distance,
+            z: dynamicBounds.center.z - direction.z * distance,
+        });
+        light.autoUpdateExtends = false;
+        light.orthoLeft = -halfSize;
+        light.orthoRight = halfSize;
+        light.orthoTop = halfSize;
+        light.orthoBottom = -halfSize;
+        light.shadowMinZ = 0.1;
+        light.shadowMaxZ = Math.max(32, distance + maxExtent + padding);
+        return;
+    }
+    const planar = options.planar || null;
+    const shadowOrtho = readObject(planar?.shadowOrtho);
+    light.orthoLeft = readFiniteNumber(shadowOrtho?.left, -20);
+    light.orthoRight = readFiniteNumber(shadowOrtho?.right, 20);
+    light.orthoTop = readFiniteNumber(shadowOrtho?.top, 20);
+    light.orthoBottom = readFiniteNumber(shadowOrtho?.bottom, -20);
+    light.shadowMinZ = 1;
+    light.shadowMaxZ = 80;
+}
+function createDynamicShadowFrustumBounds(casters, receivers, lightDirection) {
+    const direction = normalizeVec3(lightDirection);
+    const points = [];
+    const casterBounds = casters.map(readMeshWorldBounds).filter((entry) => Boolean(entry));
+    const receiverBounds = receivers.map(readMeshWorldBounds).filter((entry) => Boolean(entry));
+    for (const bounds of casterBounds) {
+        points.push(...getBoundsCorners(bounds));
+        if (direction) {
+            for (const receiver of receiverBounds) {
+                points.push(...projectBoundsOntoReceiver(bounds, receiver, direction));
+            }
+        }
+    }
+    if (points.length === 0)
+        return null;
+    const min = {
+        x: Math.min(...points.map(point => point.x)),
+        y: Math.min(...points.map(point => point.y)),
+        z: Math.min(...points.map(point => point.z)),
+    };
+    const max = {
+        x: Math.max(...points.map(point => point.x)),
+        y: Math.max(...points.map(point => point.y)),
+        z: Math.max(...points.map(point => point.z)),
+    };
+    const center = {
+        x: (min.x + max.x) / 2,
+        y: (min.y + max.y) / 2,
+        z: (min.z + max.z) / 2,
+    };
+    const size = {
+        x: max.x - min.x,
+        y: max.y - min.y,
+        z: max.z - min.z,
+    };
+    return { min, max, center, size };
+}
+function readMeshWorldBounds(mesh) {
+    try {
+        mesh.computeWorldMatrix?.(true);
+        const box = mesh.getBoundingInfo?.()?.boundingBox;
+        const min = box?.minimumWorld;
+        const max = box?.maximumWorld;
+        if (!isFiniteVec3(min) || !isFiniteVec3(max))
+            return null;
+        return {
+            min: { x: min.x, y: min.y, z: min.z },
+            max: { x: max.x, y: max.y, z: max.z },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function getBoundsCorners(bounds) {
+    const { min, max } = bounds;
+    return [
+        { x: min.x, y: min.y, z: min.z },
+        { x: min.x, y: min.y, z: max.z },
+        { x: min.x, y: max.y, z: min.z },
+        { x: min.x, y: max.y, z: max.z },
+        { x: max.x, y: min.y, z: min.z },
+        { x: max.x, y: min.y, z: max.z },
+        { x: max.x, y: max.y, z: min.z },
+        { x: max.x, y: max.y, z: max.z },
+    ];
+}
+function projectBoundsOntoReceiver(caster, receiver, direction) {
+    if (Math.abs(direction.y) < 0.00001)
+        return [];
+    const receiverY = receiver.max.y;
+    return getBoundsCorners(caster).map(point => {
+        const t = (receiverY - point.y) / direction.y;
+        if (!Number.isFinite(t))
+            return null;
+        const clampedT = Math.max(0, t);
+        return {
+            x: point.x + direction.x * clampedT,
+            y: receiverY,
+            z: point.z + direction.z * clampedT,
+        };
+    }).filter((entry) => Boolean(entry));
+}
+function normalizeVec3(value) {
+    if (!isFiniteVec3(value))
+        return null;
+    const length = Math.hypot(value.x, value.y, value.z);
+    if (!Number.isFinite(length) || length < 0.00001)
+        return null;
+    return { x: value.x / length, y: value.y / length, z: value.z / length };
+}
+function isFiniteVec3(value) {
+    const vec = value;
+    return Boolean(vec)
+        && typeof vec?.x === 'number'
+        && typeof vec?.y === 'number'
+        && typeof vec?.z === 'number'
+        && Number.isFinite(vec.x)
+        && Number.isFinite(vec.y)
+        && Number.isFinite(vec.z);
+}
+function setMutableVec3(target, value) {
+    if (!target)
+        return;
+    if (typeof target.set === 'function') {
+        target.set(value.x, value.y, value.z);
+        return;
+    }
+    target.x = value.x;
+    target.y = value.y;
+    target.z = value.z;
+}
+function readShadowPreviewMeshDebugName(mesh) {
+    const projection = readEditorProjectionMetadata(mesh);
+    const nodeId = typeof projection?.nodeId === 'string' ? projection.nodeId : null;
+    const name = typeof mesh.name === 'string' ? mesh.name : '<unnamed>';
+    return nodeId ? `${name}#${nodeId}` : name;
+}
+function readPlanarShadowSourceNodeInfo(info, scene) {
+    const nodeIds = new Set();
+    const sourceMeshUniqueIds = new Set(info.sourceMeshUniqueIds ?? []);
+    const sourceMeshNames = new Set(info.sourceMeshNames ?? []);
+    const hasSourceMeshIdentity = sourceMeshUniqueIds.size > 0;
+    for (const mesh of readSceneMeshes(scene)) {
+        const uniqueId = typeof mesh.uniqueId === 'number' ? mesh.uniqueId : null;
+        const matched = hasSourceMeshIdentity
+            ? uniqueId !== null && sourceMeshUniqueIds.has(uniqueId)
+            : mesh.name === info.sourceName || sourceMeshNames.has(mesh.name ?? '');
+        if (!matched) {
+            continue;
+        }
+        const projection = readEditorProjectionMetadata(mesh);
+        const nodeId = typeof projection?.nodeId === 'string' ? projection.nodeId : null;
+        if (nodeId)
+            nodeIds.add(nodeId);
+    }
+    const sourceNodeIds = [...nodeIds];
+    return {
+        ...(sourceNodeIds[0] ? { sourceNodeId: sourceNodeIds[0] } : {}),
+        ...(sourceNodeIds.length > 0 ? { sourceNodeIds } : {}),
+    };
+}
+function toPlainVec3(value) {
+    return isFiniteVec3(value) ? { x: value.x, y: value.y, z: value.z } : null;
+}
+function logShadowDebug(event, details) {
+    if (!isShadowDebugLoggingEnabled())
+        return;
+    try {
+        console.info('[fps-shadow-debug]', event, `json=${stringifyShadowDebugDetails(details)}`, details);
+    }
+    catch {
+        // Debug logging must never affect rendering.
+    }
+}
+function stringifyShadowDebugDetails(details) {
+    try {
+        return JSON.stringify(details);
+    }
+    catch {
+        return '{"error":"shadowDebugDetailsNotSerializable"}';
+    }
+}
+function isShadowDebugLoggingEnabled() {
+    const global = globalThis;
+    if (global.__FPS_SHADOW_DEBUG__ === true)
+        return true;
+    const env = global.process?.env?.FPS_SHADOW_DEBUG;
+    if (env === '1' || env === 'true')
+        return true;
+    try {
+        const search = global.location?.search ?? '';
+        if (/(?:[?&])fpsShadowDebug(?:=1|=true|&|$)/.test(search))
+            return true;
+    }
+    catch { }
+    try {
+        const stored = global.localStorage?.getItem?.(SHADOW_DEBUG_STORAGE_KEY);
+        return stored === '1' || stored === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+function readFiniteNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function readProjectionShadowSettingsPreviewMode(value) {
+    const shadow = readObject(value);
+    if (!shadow)
+        return null;
+    const mode = shadow.mode;
+    if (mode === 'inherit' || mode === 'auto' || mode === 'default')
+        return null;
+    if (mode === 'projected')
+        return 'planar';
+    if (mode === 'none' || mode === 'blob' || mode === 'static' || mode === 'dynamic')
+        return mode;
+    return null;
+}
+function readLegacyProjectionShadowMode(value) {
+    return value === 'default' || value === 'none' || value === 'blob' || value === 'static' || value === 'planar' || value === 'dynamic'
+        ? value
+        : null;
+}
 function hasGeneratedShadowDisabled(mesh) {
     for (const node of walkNodeAndParents(mesh)) {
         const metadata = readObject(node.metadata);