@fps-games/engine 0.0.1-beta.1 → 0.0.1-beta.11

package/dist/babylon/renderer/shadows/planar-shadow-system.js

@@ -0,0 +1,1562 @@
+import { Constants } from '@babylonjs/core/Engines/constants.js';
+import { DirectionalLight } from '@babylonjs/core/Lights/directionalLight.js';
+import { Color3, Color4 } from '@babylonjs/core/Maths/math.color.js';
+import { Matrix, Vector3 } from '@babylonjs/core/Maths/math.vector.js';
+import { Material } from '@babylonjs/core/Materials/material.js';
+import { ShaderMaterial } from '@babylonjs/core/Materials/shaderMaterial.js';
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial.js';
+import { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh.js';
+import { InstancedMesh } from '@babylonjs/core/Meshes/instancedMesh.js';
+import { Mesh } from '@babylonjs/core/Meshes/mesh.js';
+import { VertexData } from '@babylonjs/core/Meshes/mesh.vertexData.js';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode.js';
+import { VertexBuffer } from '@babylonjs/core/Buffers/buffer.js';
+import { getPlanarShadowShaderAttributes, getPlanarShadowShaderSamplers, getPlanarShadowShaderUniforms, getPlanarShadowSkeletonDefines, PLANAR_SHADOW_SHADER_NAME, registerPlanarShadowShaders, } from './planar-shadow-shaders.js';
+import { DEFAULT_PLANAR_SHADOW_OPTIONS, } from './types.js';
+const PLANAR_SHADOW_ALPHA_INDEX = 4;
+const DEFAULT_SHADOW_DIRECTION = new Vector3(-0.3, -1, -0.2).normalize();
+const STANDARD_ALPHA_LUMINANCE_WEIGHTS = new Vector3(0.3, 0.59, 0.11);
+const PBR_ALPHA_LUMINANCE_WEIGHTS = new Vector3(0.2126, 0.7152, 0.0722);
+export function createPlanarShadowSystem(scene, directionalLight, options = {}) {
+    return new BabylonPlanarShadowSystem(scene, directionalLight, options);
+}
+class BabylonPlanarShadowSystem {
+    scene;
+    directionalLight;
+    options;
+    baseMaterial = null;
+    flatMaterial = null;
+    materials = new Set();
+    casters = new Map();
+    receivers = new Map();
+    syncObservers = new Map();
+    instancedBatches = new Map();
+    instancedEntriesByRoot = new Map();
+    renderObserver = null;
+    instancedBatchSyncObserver = null;
+    meshAddedObserver = null;
+    initialized = false;
+    casterPatterns = [];
+    resolvedPlaneNormal = Vector3.Up();
+    resolvedPlaneHeight = 0;
+    patternNameCache = null;
+    constructor(scene, directionalLight, options) {
+        this.scene = scene;
+        this.directionalLight = directionalLight;
+        this.options = resolvePlanarShadowOptions(options);
+        this.casterPatterns = [...this.options.casters.includePatterns];
+    }
+    initialize() {
+        if (this.initialized || !this.options.enabled)
+            return;
+        registerPlanarShadowShaders();
+        if (this.options.stencil.enabled)
+            this.setupStencil();
+        this.baseMaterial = this.createShadowMaterial();
+        this.materials.add(this.baseMaterial);
+        this.renderObserver = this.scene.onBeforeRenderObservable.add(() => this.updateUniforms());
+        this.instancedBatchSyncObserver = this.scene.onBeforeRenderObservable.add(() => this.syncInstancedBatches());
+        this.initialized = true;
+        this.refresh();
+    }
+    addCaster(mesh) {
+        const root = this.findCasterRoot(mesh);
+        if (!this.initialized || this.casters.has(root))
+            return false;
+        if (this.getInvalidShadowSourceReason(mesh))
+            return false;
+        const shadow = this.createShadowForNode(root);
+        if (!shadow)
+            return false;
+        this.casters.set(shadow.source, shadow);
+        return true;
+    }
+    removeCaster(mesh) {
+        const root = this.findCasterRoot(mesh);
+        this.disposeCaster(root);
+    }
+    addReceiver(mesh) {
+        this.registerReceiver(mesh, true);
+    }
+    registerReceiver(mesh, manual) {
+        if (!this.options.stencil.enabled || this.hasDisabledReceiver(mesh))
+            return;
+        const existing = this.receivers.get(mesh);
+        if (existing) {
+            existing.manual = existing.manual || manual;
+            return;
+        }
+        const originalRenderingGroup = mesh instanceof Mesh ? mesh.renderingGroupId : 0;
+        if (mesh instanceof Mesh)
+            mesh.renderingGroupId = this.options.stencil.receiverRenderingGroup;
+        const material = readMeshMaterial(mesh);
+        if (material?.stencil) {
+            const stencil = material.stencil;
+            stencil.enabled = true;
+            stencil.func = Constants.ALWAYS;
+            stencil.funcRef = 1;
+            stencil.funcMask = 0xff;
+            stencil.mask = 0xff;
+            stencil.opStencilDepthPass = Constants.REPLACE;
+            stencil.opStencilFail = Constants.KEEP;
+            stencil.opDepthFail = Constants.KEEP;
+        }
+        this.receivers.set(mesh, { mesh, originalRenderingGroup, material, manual });
+    }
+    removeReceiver(mesh) {
+        const info = this.receivers.get(mesh);
+        if (!info)
+            return;
+        if (mesh instanceof Mesh)
+            mesh.renderingGroupId = info.originalRenderingGroup;
+        if (info.material?.stencil)
+            info.material.stencil.enabled = false;
+        this.receivers.delete(mesh);
+    }
+    enableCasterAutoDetection(patterns) {
+        this.options = {
+            ...this.options,
+            casters: {
+                ...this.options.casters,
+                autoDetectAll: false,
+                includePatterns: [...patterns],
+            },
+        };
+        this.casterPatterns = [...patterns];
+        this.refresh();
+        this.ensureMeshObserver();
+    }
+    enableAutoDetectionForAll() {
+        this.options = {
+            ...this.options,
+            casters: {
+                ...this.options.casters,
+                autoDetectAll: true,
+            },
+        };
+        this.casterPatterns = [];
+        this.refresh();
+        this.ensureMeshObserver();
+    }
+    refresh() {
+        if (!this.initialized)
+            return;
+        const previousPatternNameCache = this.patternNameCache;
+        this.patternNameCache = new WeakMap();
+        try {
+            this.pruneDisposedCasters();
+            this.refreshReceivers();
+            if (this.options.casters.autoDetectAll || this.casterPatterns.length > 0) {
+                for (const mesh of this.scene.meshes)
+                    this.tryAutoAddCaster(mesh);
+            }
+            if (this.options.casters.autoDetectAll || this.casterPatterns.length > 0 || this.options.receivers.patterns.length > 0) {
+                this.ensureMeshObserver();
+            }
+        }
+        finally {
+            this.patternNameCache = previousPatternNameCache;
+        }
+    }
+    setOptions(options) {
+        const wasEnabled = this.options.enabled;
+        const requiredUniqueMaterials = this.requiresPerShadowMaterial();
+        const previousStrategy = this.options.projection.strategy;
+        this.options = resolvePlanarShadowOptions(options, this.options);
+        this.casterPatterns = [...this.options.casters.includePatterns];
+        const requiresUniqueMaterials = this.requiresPerShadowMaterial();
+        const strategyChanged = previousStrategy !== this.options.projection.strategy;
+        if (!wasEnabled && this.options.enabled)
+            this.initialize();
+        else if (wasEnabled && !this.options.enabled)
+            this.dispose();
+        else {
+            if (requiredUniqueMaterials !== requiresUniqueMaterials || strategyChanged)
+                this.rebuildCasters();
+            this.refresh();
+        }
+    }
+    getOptions() {
+        return cloneResolvedOptions(this.options);
+    }
+    getCasterCount() {
+        return this.casters.size;
+    }
+    getReceiverCount() {
+        return this.receivers.size;
+    }
+    getCasterDebugInfo() {
+        return [...this.casters.values()].map((info) => ({
+            sourceName: info.source.name,
+            sourceMeshNames: [...info.sourceMeshNames],
+            sourceMeshUniqueIds: [...info.sourceMeshUniqueIds],
+            shadowName: info.shadow.name,
+            strategy: info.strategy,
+            hasSkeleton: info.hasSkeleton,
+            projectedMeshCount: info.projectedMeshCount,
+            convexHullMeshCount: info.convexHullMeshCount,
+            alphaCutoutMeshCount: info.alphaCutoutMeshCount,
+            instancedCasterCount: info.instancedCasterCount,
+            batchMeshCount: info.batchMeshCount,
+            instancedBatchIds: [...info.instancedBatchIds],
+            instancedBatchNames: [...info.instancedBatchNames],
+            independentProjectedMeshCount: info.independentProjectedMeshCount,
+            visibleInstanceCount: info.visibleInstanceCount,
+            alphaCutoutChannels: [...info.alphaCutoutChannels],
+            alphaCutoutUvSets: [...info.alphaCutoutUvSets],
+            alphaCutoutLevels: [...info.alphaCutoutLevels],
+            alphaCutoutLuminanceWeights: info.alphaCutoutLuminanceWeights.map((weights) => ({
+                x: weights.x,
+                y: weights.y,
+                z: weights.z,
+            })),
+            fallbackReasons: [...info.fallbackReasons],
+            instancingFallbackReasons: [...info.instancingFallbackReasons],
+        }));
+    }
+    dispose() {
+        if (this.renderObserver) {
+            this.scene.onBeforeRenderObservable.remove(this.renderObserver);
+            this.renderObserver = null;
+        }
+        if (this.instancedBatchSyncObserver) {
+            this.scene.onBeforeRenderObservable.remove(this.instancedBatchSyncObserver);
+            this.instancedBatchSyncObserver = null;
+        }
+        if (this.meshAddedObserver) {
+            this.scene.onNewMeshAddedObservable.remove(this.meshAddedObserver);
+            this.meshAddedObserver = null;
+        }
+        for (const [mesh, observer] of [...this.syncObservers]) {
+            this.scene.onBeforeRenderObservable.remove(observer);
+            this.syncObservers.delete(mesh);
+        }
+        for (const mesh of [...this.casters.keys()])
+            this.disposeCaster(mesh);
+        for (const batch of [...this.instancedBatches.values()])
+            this.disposeInstancedBatch(batch);
+        for (const mesh of [...this.receivers.keys()])
+            this.removeReceiver(mesh);
+        for (const material of this.materials)
+            material.dispose();
+        this.materials.clear();
+        this.baseMaterial = null;
+        this.flatMaterial?.dispose();
+        this.flatMaterial = null;
+        this.initialized = false;
+    }
+    setupStencil() {
+        this.scene.getEngine().setStencilBuffer(true);
+        this.scene.setRenderingAutoClearDepthStencil(this.options.stencil.receiverRenderingGroup, true, false, true);
+        this.scene.setRenderingAutoClearDepthStencil(this.options.stencil.shadowRenderingGroup, false, false, false);
+    }
+    createShadowMaterial(defines = [], alphaCutout = null) {
+        const materialDefines = alphaCutout
+            ? [...defines, 'ALPHA_CUTOUT', ...(alphaCutout.layers[1] ? ['ALPHA_CUTOUT_SECONDARY'] : [])]
+            : defines;
+        const usesBoneTexture = materialDefines.includes('BONETEXTURE');
+        const usesBones = materialDefines.includes('BONE');
+        const material = new ShaderMaterial(`fps.planarShadow.${this.materials.size}`, this.scene, { vertex: PLANAR_SHADOW_SHADER_NAME, fragment: PLANAR_SHADOW_SHADER_NAME }, {
+            attributes: getPlanarShadowShaderAttributes(),
+            uniforms: getPlanarShadowShaderUniforms(),
+            samplers: getPlanarShadowShaderSamplers(),
+            defines: materialDefines,
+        });
+        material.backFaceCulling = false;
+        material.disableDepthWrite = true;
+        material.depthFunction = Constants.LEQUAL;
+        material.needAlphaBlending = () => true;
+        material.alphaMode = Constants.ALPHA_COMBINE;
+        material.onBindObservable.add((mesh) => {
+            if (mesh instanceof AbstractMesh)
+                this.bindShadowProjectionUniforms(material, mesh);
+            if (alphaCutout) {
+                const primary = alphaCutout.layers[0];
+                material.setTexture('shadowAlphaSampler', primary.texture);
+                material.setFloat('u_shadowAlphaCutoff', alphaCutout.cutoff);
+                bindPlanarShadowAlphaCutoutLayer(material, '', primary);
+                const secondary = alphaCutout.layers[1];
+                if (secondary)
+                    bindPlanarShadowAlphaCutoutLayer(material, '2', secondary);
+            }
+        });
+        if (usesBones) {
+            let lastBoundTexture = null;
+            let lastTextureWidth = 0;
+            material.onBindObservable.add((mesh) => {
+                if (!mesh?.skeleton)
+                    return;
+                const skeleton = mesh.skeleton;
+                skeleton.prepare();
+                if (usesBoneTexture) {
+                    const boneTexture = skeleton.getTransformMatrixTexture(mesh);
+                    if (!boneTexture)
+                        return;
+                    const textureWidth = boneTexture.getSize().width;
+                    if (boneTexture !== lastBoundTexture || textureWidth !== lastTextureWidth) {
+                        material.setTexture('boneSampler', boneTexture);
+                        material.setFloat('boneTextureWidth', textureWidth);
+                        lastBoundTexture = boneTexture;
+                        lastTextureWidth = textureWidth;
+                    }
+                }
+                else {
+                    const matrices = skeleton.getTransformMatrices(mesh);
+                    const effect = material.getEffect();
+                    if (matrices && effect)
+                        effect.setMatrices('mBones', matrices);
+                }
+            });
+        }
+        if (this.options.stencil.enabled && material.stencil) {
+            const stencil = material.stencil;
+            stencil.enabled = true;
+            stencil.func = Constants.EQUAL;
+            stencil.funcRef = 1;
+            stencil.funcMask = 0xff;
+            stencil.mask = 0xff;
+            stencil.opStencilDepthPass = Constants.INCR;
+            stencil.opStencilFail = Constants.KEEP;
+            stencil.opDepthFail = Constants.KEEP;
+            stencil.backFunc = stencil.func;
+            stencil.backOpStencilDepthPass = stencil.opStencilDepthPass;
+            stencil.backOpStencilFail = stencil.opStencilFail;
+            stencil.backOpDepthFail = stencil.opDepthFail;
+        }
+        return material;
+    }
+    getFlatShadowMaterial() {
+        if (this.flatMaterial)
+            return this.flatMaterial;
+        const material = new StandardMaterial(`fps.planarShadow.flat`, this.scene);
+        material.backFaceCulling = false;
+        material.disableLighting = true;
+        material.disableDepthWrite = true;
+        material.diffuseColor = Color3.Black();
+        material.emissiveColor = Color3.Black();
+        material.alpha = clamp01(this.options.appearance.color.a);
+        material.alphaMode = Constants.ALPHA_COMBINE;
+        if (this.options.stencil.enabled && material.stencil) {
+            const stencil = material.stencil;
+            stencil.enabled = true;
+            stencil.func = Constants.EQUAL;
+            stencil.funcRef = 1;
+            stencil.funcMask = 0xff;
+            stencil.mask = 0xff;
+            stencil.opStencilDepthPass = Constants.INCR;
+            stencil.opStencilFail = Constants.KEEP;
+            stencil.opDepthFail = Constants.KEEP;
+            stencil.backFunc = stencil.func;
+            stencil.backOpStencilDepthPass = stencil.opStencilDepthPass;
+            stencil.backOpStencilFail = stencil.opStencilFail;
+            stencil.backOpDepthFail = stencil.opDepthFail;
+        }
+        this.flatMaterial = material;
+        return material;
+    }
+    updateUniforms() {
+        if (this.materials.size === 0)
+            return;
+        const planeNormal = new Vector3(this.options.plane.normal.x, this.options.plane.normal.y, this.options.plane.normal.z).normalize();
+        const planeHeight = this.resolvePlaneHeight(planeNormal);
+        this.resolvedPlaneNormal = planeNormal;
+        this.resolvedPlaneHeight = planeHeight;
+        const lightDir = this.resolveShadowDirection();
+        const shadowColor = new Color4(clamp01(this.options.appearance.color.r), clamp01(this.options.appearance.color.g), clamp01(this.options.appearance.color.b), clamp01(this.options.appearance.color.a));
+        for (const material of this.materials) {
+            material.setVector3('u_lightDir', lightDir);
+            material.setVector3('u_planeNormal', planeNormal);
+            material.setVector3('u_shadowCenter', new Vector3(0, planeHeight, 0));
+            material.setFloat('u_planeHeight', planeHeight);
+            material.setFloat('u_planeBias', this.options.plane.bias);
+            material.setFloat('u_footprintScale', this.options.projection.footprintScale);
+            material.setColor4('u_shadowColor', shadowColor);
+        }
+        if (this.flatMaterial) {
+            const color = new Color3(shadowColor.r, shadowColor.g, shadowColor.b);
+            this.flatMaterial.diffuseColor = color;
+            this.flatMaterial.emissiveColor = color;
+            this.flatMaterial.alpha = shadowColor.a;
+        }
+    }
+    bindShadowProjectionUniforms(material, mesh) {
+        mesh.computeWorldMatrix(true);
+        const center = mesh.getBoundingInfo()?.boundingBox.centerWorld.clone() ?? Vector3.Zero();
+        const offset = Vector3.Dot(this.resolvedPlaneNormal, center) - this.resolvedPlaneHeight;
+        const projectedCenter = center.subtract(this.resolvedPlaneNormal.scale(offset));
+        material.setVector3('u_shadowCenter', projectedCenter);
+    }
+    requiresPerShadowMaterial() {
+        return Math.abs(this.options.projection.footprintScale - 1) > 1e-6;
+    }
+    resolvePlaneHeight(planeNormal) {
+        const fallbackHeight = this.options.plane.height;
+        if (this.options.plane.heightMode !== 'receiver')
+            return fallbackHeight;
+        let totalHeight = 0;
+        let receiverCount = 0;
+        for (const mesh of this.receivers.keys()) {
+            if (isDisposedNode(mesh))
+                continue;
+            mesh.computeWorldMatrix(true);
+            const vectorsWorld = mesh.getBoundingInfo()?.boundingBox?.vectorsWorld;
+            if (!vectorsWorld || vectorsWorld.length === 0)
+                continue;
+            let receiverSurfaceHeight = -Infinity;
+            for (const point of vectorsWorld) {
+                const height = Vector3.Dot(planeNormal, point);
+                if (Number.isFinite(height))
+                    receiverSurfaceHeight = Math.max(receiverSurfaceHeight, height);
+            }
+            if (!Number.isFinite(receiverSurfaceHeight))
+                continue;
+            totalHeight += receiverSurfaceHeight;
+            receiverCount += 1;
+        }
+        return receiverCount > 0 ? totalHeight / receiverCount : fallbackHeight;
+    }
+    resolveShadowDirection() {
+        const direction = this.directionalLight.direction;
+        if (direction?.lengthSquared?.() > 1e-6)
+            return direction.clone().normalize();
+        return DEFAULT_SHADOW_DIRECTION.clone();
+    }
+    refreshReceivers() {
+        if (!this.options.stencil.enabled)
+            return;
+        for (const [mesh, info] of [...this.receivers]) {
+            if (info.manual) {
+                if (this.hasDisabledReceiver(mesh) || this.matchesExcludePattern(mesh) || this.hasExcludedAncestor(mesh)) {
+                    this.removeReceiver(mesh);
+                }
+                continue;
+            }
+            if (!this.matchesReceiver(mesh))
+                this.removeReceiver(mesh);
+        }
+        for (const mesh of this.scene.meshes) {
+            if (this.matchesReceiver(mesh))
+                this.registerReceiver(mesh, false);
+        }
+    }
+    pruneDisposedCasters() {
+        for (const [root, info] of [...this.casters]) {
+            if (isDisposedNode(root) || isDisposedNode(info.shadow)) {
+                this.disposeCaster(root);
+            }
+        }
+    }
+    disposeCaster(root) {
+        const info = this.casters.get(root);
+        if (!info)
+            return;
+        const observer = this.syncObservers.get(root);
+        if (observer) {
+            this.scene.onBeforeRenderObservable.remove(observer);
+            this.syncObservers.delete(root);
+        }
+        this.removeInstancedEntriesForRoot(root);
+        if (info.independentProjectedMeshCount > 0 || info.convexHullMeshCount > 0) {
+            for (const shadowMesh of info.shadow.getChildMeshes(false)) {
+                if (shadowMesh instanceof Mesh
+                    && shadowMesh.material
+                    && shadowMesh.material !== this.baseMaterial
+                    && shadowMesh.material !== this.flatMaterial) {
+                    this.materials.delete(shadowMesh.material);
+                    shadowMesh.material.dispose();
+                }
+            }
+            info.shadow.dispose();
+        }
+        this.casters.delete(root);
+    }
+    removeInstancedEntriesForRoot(root) {
+        const entries = this.instancedEntriesByRoot.get(root);
+        if (!entries || entries.length === 0)
+            return;
+        const entriesByBatch = new Map();
+        for (const entry of entries) {
+            const batchEntries = entriesByBatch.get(entry.batchKey) ?? new Set();
+            batchEntries.add(entry);
+            entriesByBatch.set(entry.batchKey, batchEntries);
+        }
+        for (const [batchKey, batchEntries] of entriesByBatch) {
+            const batch = this.instancedBatches.get(batchKey);
+            if (!batch)
+                continue;
+            batch.entries = batch.entries.filter(candidate => !batchEntries.has(candidate));
+            batch.entries.forEach((candidate, index) => {
+                candidate.instanceIndex = index;
+            });
+            if (batch.entries.length === 0) {
+                this.disposeInstancedBatch(batch);
+            }
+            else {
+                this.markInstancedBatchBuffersDirty(batch);
+            }
+        }
+        this.instancedEntriesByRoot.delete(root);
+    }
+    disposeInstancedBatch(batch) {
+        this.instancedBatches.delete(batch.key);
+        batch.shadow.thinInstanceSetBuffer('shadowVisibility', null);
+        batch.shadow.thinInstanceSetBuffer('matrix', null);
+        if (batch.material !== this.baseMaterial) {
+            this.materials.delete(batch.material);
+            batch.material.dispose();
+        }
+        batch.shadow.dispose();
+    }
+    rebuildCasters() {
+        const roots = [...this.casters.keys()].filter((root) => !isDisposedNode(root));
+        for (const root of roots)
+            this.disposeCaster(root);
+        for (const root of roots)
+            this.addCaster(root);
+    }
+    tryAutoAddCaster(mesh) {
+        if (!this.initialized || this.casters.has(mesh))
+            return;
+        if (!this.options.casters.autoDetectAll && !this.matchesCasterPattern(mesh))
+            return;
+        if (!this.isValidShadowSource(mesh))
+            return;
+        const root = this.findCasterRoot(mesh);
+        if (this.isAlreadyCoveredByCaster(root))
+            return;
+        const shadow = this.createShadowForNode(root);
+        if (shadow)
+            this.casters.set(shadow.source, shadow);
+    }
+    ensureMeshObserver() {
+        if (this.meshAddedObserver)
+            return;
+        this.meshAddedObserver = this.scene.onNewMeshAddedObservable.add((mesh) => {
+            queueMicrotask(() => {
+                if (!this.initialized || mesh.isDisposed())
+                    return;
+                if (this.matchesReceiver(mesh))
+                    this.addReceiver(mesh);
+                this.tryAutoAddCaster(mesh);
+            });
+        });
+    }
+    createShadowForNode(root) {
+        const validMeshes = collectNodeMeshes(root).filter((mesh) => this.isValidShadowSource(mesh));
+        if (validMeshes.length === 0)
+            return null;
+        let shadowRoot = null;
+        const ensureShadowRoot = () => {
+            shadowRoot ??= new TransformNode(`${root.name}_planarShadowRoot`, this.scene);
+            return shadowRoot;
+        };
+        let hasSkeleton = false;
+        const pairs = [];
+        const instancedEntries = [];
+        const fallbackReasons = [];
+        const instancingFallbackReasons = [];
+        let sharedSkeleton = null;
+        let sharedMaterial = null;
+        for (const mesh of validMeshes) {
+            if (!(mesh instanceof Mesh) && !(mesh instanceof InstancedMesh))
+                continue;
+            const geometrySource = mesh instanceof InstancedMesh ? mesh.sourceMesh : mesh;
+            const strategy = this.options.projection.strategy;
+            const instancingEligibility = this.resolveInstancingEligibility(mesh);
+            if (instancingEligibility.eligible) {
+                const instanced = this.addInstancedShadowMesh(root, mesh, instancingEligibility);
+                if (instanced) {
+                    instancedEntries.push(instanced);
+                    continue;
+                }
+                instancingFallbackReasons.push(`${mesh.name}: instanced projected batch unavailable`);
+            }
+            else {
+                instancingFallbackReasons.push(`${mesh.name}: ${instancingEligibility.reason}`);
+            }
+            if (strategy !== 'convex-hull') {
+                const alphaCutout = instancingEligibility.alphaCutout;
+                const material = this.resolveShadowMaterial(geometrySource, sharedSkeleton, sharedMaterial, alphaCutout);
+                if (geometrySource.skeleton) {
+                    hasSkeleton = true;
+                    sharedSkeleton = geometrySource.skeleton;
+                    if (!alphaCutout)
+                        sharedMaterial = material;
+                }
+                const shadowMesh = material ? this.createProjectedShadowMesh(mesh, material) : null;
+                if (shadowMesh) {
+                    const alphaCutoutLayers = alphaCutout?.layers.filter((layer) => !!layer) ?? [];
+                    shadowMesh.parent = ensureShadowRoot();
+                    pairs.push({
+                        mode: 'projected-mesh',
+                        source: mesh,
+                        shadow: shadowMesh,
+                        alphaCutout: !!alphaCutout,
+                        alphaCutoutChannels: alphaCutoutLayers.map((layer) => layer.channel),
+                        alphaCutoutUvSets: alphaCutoutLayers.map((layer) => layer.coordinatesIndex),
+                        alphaCutoutLevels: alphaCutoutLayers.map((layer) => layer.level),
+                        alphaCutoutLuminanceWeights: alphaCutoutLayers.map((layer) => layer.luminanceWeights),
+                    });
+                    continue;
+                }
+                fallbackReasons.push(`${mesh.name}: projected mesh clone unavailable`);
+                if (strategy === 'projected-mesh')
+                    continue;
+            }
+            const shadowMesh = this.createHullShadowMesh(mesh);
+            if (shadowMesh) {
+                shadowMesh.parent = ensureShadowRoot();
+                pairs.push({
+                    mode: 'flat-hull',
+                    source: mesh,
+                    shadow: shadowMesh,
+                    alphaCutout: false,
+                    alphaCutoutChannels: [],
+                    alphaCutoutUvSets: [],
+                    alphaCutoutLevels: [],
+                    alphaCutoutLuminanceWeights: [],
+                });
+            }
+            else {
+                fallbackReasons.push(`${mesh.name}: convex hull geometry unavailable`);
+            }
+        }
+        if (pairs.length === 0 && instancedEntries.length === 0) {
+            this.removeInstancedEntriesForRoot(root);
+            return null;
+        }
+        if (pairs.length > 0 && shadowRoot) {
+            const sync = () => {
+                if (!shadowRoot || shadowRoot.isDisposed())
+                    return;
+                for (const pair of pairs) {
+                    if (pair.source.isDisposed() || pair.shadow.isDisposed())
+                        continue;
+                    if (pair.mode === 'flat-hull') {
+                        this.updateHullShadowMesh(pair.source, pair.shadow);
+                    }
+                    else {
+                        pair.shadow.setEnabled(pair.source.isEnabled());
+                        pair.shadow.isVisible = pair.source.isVisible;
+                        pair.source.computeWorldMatrix(true).decompose(pair.shadow.scaling, pair.shadow.rotationQuaternion, pair.shadow.position);
+                    }
+                }
+            };
+            sync();
+            const observer = this.scene.onBeforeRenderObservable.add(sync);
+            this.syncObservers.set(root, observer);
+        }
+        const instancedBatchKeys = uniqueStrings(instancedEntries.map((entry) => entry.batchKey));
+        const instancedBatchNames = uniqueStrings(instancedBatchKeys.map((key) => this.instancedBatches.get(key)?.shadow.name ?? ''));
+        const instancedAlphaCutoutLayers = instancedEntries.flatMap((entry) => {
+            const batch = this.instancedBatches.get(entry.batchKey);
+            return batch?.alphaCutout?.layers.filter((layer) => !!layer) ?? [];
+        });
+        const instancedAlphaCutoutMeshCount = instancedEntries.filter((entry) => {
+            const batch = this.instancedBatches.get(entry.batchKey);
+            return !!batch?.alphaCutout;
+        }).length;
+        const independentProjectedMeshCount = pairs.filter((pair) => pair.mode === 'projected-mesh').length;
+        const visibleInstanceCount = instancedEntries.filter((entry) => readPlanarShadowEffectiveVisibility(entry.source)).length;
+        return {
+            source: root,
+            shadow: shadowRoot ?? this.instancedBatches.get(instancedEntries[0]?.batchKey)?.shadow ?? root,
+            sourceMeshNames: uniqueStrings([
+                ...pairs.map((pair) => pair.source.name),
+                ...instancedEntries.map((entry) => entry.source.name),
+            ]),
+            sourceMeshUniqueIds: uniqueNumbers([
+                ...pairs.map((pair) => pair.source.uniqueId),
+                ...instancedEntries.map((entry) => entry.source.uniqueId),
+            ]),
+            hasSkeleton,
+            strategy: summarizePlanarShadowStrategy(pairs, instancedEntries.length),
+            projectedMeshCount: independentProjectedMeshCount + instancedBatchKeys.length,
+            convexHullMeshCount: pairs.filter((pair) => pair.mode === 'flat-hull').length,
+            alphaCutoutMeshCount: pairs.filter((pair) => pair.alphaCutout).length + instancedAlphaCutoutMeshCount,
+            instancedCasterCount: instancedEntries.length,
+            batchMeshCount: instancedBatchKeys.length,
+            instancedBatchIds: instancedBatchKeys,
+            instancedBatchNames,
+            independentProjectedMeshCount,
+            visibleInstanceCount,
+            alphaCutoutChannels: [
+                ...pairs.flatMap((pair) => pair.alphaCutoutChannels),
+                ...instancedAlphaCutoutLayers.map((layer) => layer.channel),
+            ],
+            alphaCutoutUvSets: [
+                ...pairs.flatMap((pair) => pair.alphaCutoutUvSets),
+                ...instancedAlphaCutoutLayers.map((layer) => layer.coordinatesIndex),
+            ],
+            alphaCutoutLevels: [
+                ...pairs.flatMap((pair) => pair.alphaCutoutLevels),
+                ...instancedAlphaCutoutLayers.map((layer) => layer.level),
+            ],
+            alphaCutoutLuminanceWeights: [
+                ...pairs.flatMap((pair) => pair.alphaCutoutLuminanceWeights),
+                ...instancedAlphaCutoutLayers.map((layer) => layer.luminanceWeights),
+            ],
+            fallbackReasons,
+            instancingFallbackReasons,
+        };
+    }
+    resolveInstancingEligibility(source) {
+        const geometrySource = source instanceof InstancedMesh ? source.sourceMesh : source;
+        const alphaCutout = resolvePlanarShadowAlphaCutout(geometrySource);
+        if (this.options.projection.strategy !== 'auto') {
+            return {
+                eligible: false,
+                reason: `projection strategy ${this.options.projection.strategy} bypasses instanced backend`,
+                alphaCutout,
+            };
+        }
+        if (this.requiresPerShadowMaterial()) {
+            return {
+                eligible: false,
+                reason: 'footprintScale requires per-caster projected material',
+                alphaCutout,
+            };
+        }
+        if (!geometrySource.geometry) {
+            return {
+                eligible: false,
+                reason: 'geometry unavailable',
+                alphaCutout,
+            };
+        }
+        if (geometrySource.skeleton) {
+            return {
+                eligible: false,
+                reason: 'skinned caster requires independent projected mesh',
+                alphaCutout,
+            };
+        }
+        if (geometrySource.morphTargetManager) {
+            return {
+                eligible: false,
+                reason: 'morph target caster requires independent projected mesh',
+                alphaCutout,
+            };
+        }
+        if (geometrySource.hasThinInstances) {
+            return {
+                eligible: false,
+                reason: 'source mesh thin instances require independent projected mesh',
+                alphaCutout,
+            };
+        }
+        const alphaSignature = createPlanarShadowInstancedAlphaCutoutSignature(alphaCutout);
+        if (!alphaSignature.signature) {
+            return {
+                eligible: false,
+                reason: alphaSignature.reason,
+                alphaCutout,
+            };
+        }
+        const geometryId = readPlanarShadowGeometryIdentity(geometrySource);
+        return {
+            eligible: true,
+            batchKey: [
+                'projected',
+                `geometry:${geometryId}`,
+                `alpha:${alphaSignature.signature}`,
+                `shadowGroup:${this.options.stencil.shadowRenderingGroup}`,
+                `stencil:${this.options.stencil.enabled ? 1 : 0}`,
+            ].join('|'),
+            geometrySource,
+            alphaCutout,
+            alphaCutoutSignature: alphaSignature.signature,
+        };
+    }
+    addInstancedShadowMesh(root, source, eligibility) {
+        const batch = this.getOrCreateInstancedBatch(eligibility);
+        if (!batch)
+            return null;
+        const entry = {
+            root,
+            source,
+            geometrySource: eligibility.geometrySource,
+            instanceIndex: batch.entries.length,
+            batchKey: eligibility.batchKey,
+        };
+        batch.entries.push(entry);
+        const entries = this.instancedEntriesByRoot.get(root) ?? [];
+        entries.push(entry);
+        this.instancedEntriesByRoot.set(root, entries);
+        this.markInstancedBatchBuffersDirty(batch);
+        return entry;
+    }
+    getOrCreateInstancedBatch(eligibility) {
+        const existing = this.instancedBatches.get(eligibility.batchKey);
+        if (existing)
+            return existing;
+        const material = this.resolveShadowMaterial(eligibility.geometrySource, null, null, eligibility.alphaCutout);
+        if (!material)
+            return null;
+        const shadow = this.createInstancedProjectedShadowMesh(eligibility.geometrySource, material);
+        if (!shadow) {
+            if (material !== this.baseMaterial) {
+                this.materials.delete(material);
+                material.dispose();
+            }
+            return null;
+        }
+        const batch = {
+            key: eligibility.batchKey,
+            shadow,
+            material,
+            geometrySource: eligibility.geometrySource,
+            alphaCutout: eligibility.alphaCutout,
+            entries: [],
+            matrixData: new Float32Array(0),
+            visibilityData: new Float32Array(0),
+            buffersDirty: true,
+        };
+        this.instancedBatches.set(batch.key, batch);
+        return batch;
+    }
+    createInstancedProjectedShadowMesh(geometrySource, material) {
+        const shadowMesh = geometrySource.clone(`${geometrySource.name}_planarShadowBatch`, null, true, false);
+        if (!shadowMesh)
+            return null;
+        shadowMesh.parent = null;
+        shadowMesh.position.setAll(0);
+        shadowMesh.rotation.setAll(0);
+        shadowMesh.scaling.setAll(1);
+        shadowMesh.rotationQuaternion = null;
+        shadowMesh.material = material;
+        shadowMesh.isPickable = false;
+        shadowMesh.receiveShadows = false;
+        shadowMesh.renderingGroupId = this.options.stencil.shadowRenderingGroup;
+        shadowMesh.alphaIndex = PLANAR_SHADOW_ALPHA_INDEX;
+        shadowMesh.renderOutline = false;
+        shadowMesh.renderOverlay = false;
+        shadowMesh.alwaysSelectAsActiveMesh = true;
+        shadowMesh.metadata = {
+            ...(shadowMesh.metadata && typeof shadowMesh.metadata === 'object' ? shadowMesh.metadata : {}),
+            disablePlanarShadow: true,
+            planarShadowInternal: true,
+            planarShadowInstancedBatch: true,
+        };
+        shadowMesh.thinInstanceSetBuffer('matrix', new Float32Array(0), 16, false);
+        shadowMesh.thinInstanceSetBuffer('shadowVisibility', new Float32Array(0), 1, false);
+        return shadowMesh;
+    }
+    rebuildInstancedBatchBuffers(batch) {
+        const instanceCount = batch.entries.length;
+        batch.matrixData = new Float32Array(instanceCount * 16);
+        batch.visibilityData = new Float32Array(instanceCount);
+        this.writeInstancedBatchData(batch);
+        batch.shadow.thinInstanceSetBuffer('matrix', batch.matrixData, 16, false);
+        batch.shadow.thinInstanceSetBuffer('shadowVisibility', batch.visibilityData, 1, false);
+        batch.shadow.thinInstanceCount = instanceCount;
+        batch.buffersDirty = false;
+        batch.shadow.isVisible = instanceCount > 0;
+    }
+    syncInstancedBatches() {
+        for (const batch of this.instancedBatches.values()) {
+            if (this.shouldRebuildInstancedBatchBuffers(batch)) {
+                this.rebuildInstancedBatchBuffers(batch);
+            }
+            else {
+                this.writeInstancedBatchData(batch);
+                batch.shadow.thinInstanceBufferUpdated('matrix');
+                batch.shadow.thinInstanceBufferUpdated('shadowVisibility');
+            }
+            batch.shadow.isVisible = batch.entries.length > 0 && batch.visibilityData.some(value => value >= 0.5);
+        }
+    }
+    markInstancedBatchBuffersDirty(batch) {
+        batch.buffersDirty = true;
+        batch.shadow.thinInstanceCount = batch.entries.length;
+    }
+    shouldRebuildInstancedBatchBuffers(batch) {
+        return batch.buffersDirty
+            || batch.matrixData.length !== batch.entries.length * 16
+            || batch.visibilityData.length !== batch.entries.length;
+    }
+    writeInstancedBatchData(batch) {
+        batch.entries.forEach((entry, index) => {
+            entry.instanceIndex = index;
+            if (entry.source.isDisposed()) {
+                Matrix.Identity().copyToArray(batch.matrixData, index * 16);
+                batch.visibilityData[index] = 0;
+                return;
+            }
+            entry.source.computeWorldMatrix(true);
+            entry.source.getWorldMatrix().copyToArray(batch.matrixData, index * 16);
+            batch.visibilityData[index] = readPlanarShadowEffectiveVisibility(entry.source) ? 1 : 0;
+        });
+        for (const [root, info] of this.casters) {
+            const entries = this.instancedEntriesByRoot.get(root);
+            if (!entries?.some((entry) => entry.batchKey === batch.key))
+                continue;
+            info.visibleInstanceCount = entries.filter((entry) => readPlanarShadowEffectiveVisibility(entry.source)).length;
+        }
+    }
+    resolveSkeletonShadowMaterial(geometrySource, sharedSkeleton, sharedMaterial) {
+        if (geometrySource.skeleton === sharedSkeleton && sharedMaterial)
+            return sharedMaterial;
+        const numBones = geometrySource.skeleton?.bones.length ?? 0;
+        const useTexture = !!this.scene.getEngine().getCaps().textureFloat && numBones > 4;
+        const hasExtra = geometrySource.isVerticesDataPresent('matricesIndicesExtra');
+        const material = this.createShadowMaterial(getPlanarShadowSkeletonDefines(numBones, useTexture, hasExtra));
+        this.materials.add(material);
+        return material;
+    }
+    resolveShadowMaterial(geometrySource, sharedSkeleton, sharedMaterial, alphaCutout = null) {
+        if (alphaCutout) {
+            const material = geometrySource.skeleton
+                ? this.createShadowMaterial(getPlanarShadowSkeletonDefines(geometrySource.skeleton?.bones.length ?? 0, !!this.scene.getEngine().getCaps().textureFloat && (geometrySource.skeleton?.bones.length ?? 0) > 4, geometrySource.isVerticesDataPresent('matricesIndicesExtra')), alphaCutout)
+                : this.createShadowMaterial([], alphaCutout);
+            this.materials.add(material);
+            return material;
+        }
+        if (this.requiresPerShadowMaterial()) {
+            const material = geometrySource.skeleton
+                ? this.createShadowMaterial(getPlanarShadowSkeletonDefines(geometrySource.skeleton?.bones.length ?? 0, !!this.scene.getEngine().getCaps().textureFloat && (geometrySource.skeleton?.bones.length ?? 0) > 4, geometrySource.isVerticesDataPresent('matricesIndicesExtra')))
+                : this.createShadowMaterial();
+            this.materials.add(material);
+            return material;
+        }
+        return geometrySource.skeleton
+            ? this.resolveSkeletonShadowMaterial(geometrySource, sharedSkeleton, sharedMaterial)
+            : this.baseMaterial;
+    }
+    createProjectedShadowMesh(source, material) {
+        const geometrySource = source instanceof InstancedMesh ? source.sourceMesh : source;
+        const shadowMesh = geometrySource.clone(`${source.name}_planarShadow`, null, true, false);
+        if (!shadowMesh)
+            return null;
+        if (geometrySource.skeleton) {
+            shadowMesh.skeleton = geometrySource.skeleton;
+            geometrySource.skeleton.prepare();
+        }
+        shadowMesh.material = material;
+        shadowMesh.isPickable = false;
+        shadowMesh.receiveShadows = false;
+        shadowMesh.renderingGroupId = this.options.stencil.shadowRenderingGroup;
+        shadowMesh.alphaIndex = PLANAR_SHADOW_ALPHA_INDEX;
+        shadowMesh.renderOutline = false;
+        shadowMesh.renderOverlay = false;
+        shadowMesh.metadata = {
+            ...(shadowMesh.metadata && typeof shadowMesh.metadata === 'object' ? shadowMesh.metadata : {}),
+            disablePlanarShadow: true,
+            planarShadowInternal: true,
+        };
+        if (!shadowMesh.rotationQuaternion)
+            shadowMesh.rotationQuaternion = shadowMesh.rotation.toQuaternion();
+        return shadowMesh;
+    }
+    createHullShadowMesh(source) {
+        const shadowMesh = new Mesh(`${source.name}_planarShadow`, this.scene);
+        shadowMesh.material = this.getFlatShadowMaterial();
+        shadowMesh.isPickable = false;
+        shadowMesh.receiveShadows = false;
+        shadowMesh.renderingGroupId = this.options.stencil.shadowRenderingGroup;
+        shadowMesh.alphaIndex = PLANAR_SHADOW_ALPHA_INDEX;
+        shadowMesh.renderOutline = false;
+        shadowMesh.renderOverlay = false;
+        shadowMesh.metadata = {
+            ...(shadowMesh.metadata && typeof shadowMesh.metadata === 'object' ? shadowMesh.metadata : {}),
+            disablePlanarShadow: true,
+            planarShadowInternal: true,
+        };
+        this.updateHullShadowMesh(source, shadowMesh);
+        return shadowMesh;
+    }
+    updateHullShadowMesh(source, shadowMesh) {
+        const geometry = buildPlanarShadowHullGeometry(source, {
+            lightDir: this.resolveShadowDirection(),
+            planeNormal: this.resolvedPlaneNormal,
+            planeHeight: this.resolvedPlaneHeight,
+            planeBias: this.options.plane.bias,
+            footprintScale: this.options.projection.footprintScale,
+        });
+        if (!geometry) {
+            shadowMesh.isVisible = false;
+            return;
+        }
+        const vertexData = new VertexData();
+        vertexData.positions = geometry.positions;
+        vertexData.indices = geometry.indices;
+        vertexData.normals = geometry.normals;
+        vertexData.applyToMesh(shadowMesh, true);
+        shadowMesh.isVisible = true;
+    }
+    isValidShadowSource(mesh) {
+        return this.getInvalidShadowSourceReason(mesh) === null;
+    }
+    getInvalidShadowSourceReason(mesh) {
+        if (isDisposedNode(mesh))
+            return 'source disposed';
+        if (!(mesh instanceof Mesh) && !(mesh instanceof InstancedMesh))
+            return 'source is not a mesh';
+        if (mesh instanceof Mesh && !mesh.geometry)
+            return 'geometry unavailable';
+        if (mesh instanceof InstancedMesh && !mesh.sourceMesh.geometry)
+            return 'instance source geometry unavailable';
+        if (hasDisablePlanarShadowMetadata(mesh))
+            return 'planar shadow disabled by metadata';
+        if (this.matchesExcludePattern(mesh))
+            return 'source matches exclude pattern';
+        if (this.hasExcludedAncestor(mesh))
+            return 'ancestor matches exclude or disabled pattern';
+        if (this.matchesReceiverPattern(mesh))
+            return 'source matches receiver pattern';
+        mesh.computeWorldMatrix(true);
+        const size = mesh.getBoundingInfo()?.boundingBox.extendSizeWorld;
+        if (!size)
+            return null;
+        const volume = size.x * size.y * size.z;
+        if (volume >= this.options.casters.minVolume)
+            return null;
+        const maxProjectedArea = Math.max(size.x * size.y, size.x * size.z, size.y * size.z);
+        return maxProjectedArea >= this.options.casters.minVolume
+            ? null
+            : `bounds below minVolume volume=${volume} maxProjectedArea=${maxProjectedArea}`;
+    }
+    findCasterRoot(mesh) {
+        let topmost = mesh;
+        let current = mesh.parent;
+        while (current) {
+            if (this.matchesRootBoundaryPattern(current) || hasDisablePlanarShadowMetadata(current))
+                break;
+            if (!(current instanceof AbstractMesh)) {
+                current = current.parent;
+                continue;
+            }
+            if (this.matchesExcludePattern(current))
+                break;
+            topmost = current;
+            current = current.parent;
+        }
+        return topmost;
+    }
+    matchesCasterPattern(mesh) {
+        return this.casterPatterns.some((pattern) => this.nodeOrAncestorNameIncludes(mesh, pattern));
+    }
+    matchesReceiver(mesh) {
+        return this.options.stencil.enabled
+            && !hasDisablePlanarShadowMetadata(mesh)
+            && !this.hasDisabledReceiver(mesh)
+            && !this.matchesExcludePattern(mesh)
+            && !this.hasExcludedAncestor(mesh)
+            && this.matchesReceiverPattern(mesh);
+    }
+    matchesReceiverPattern(mesh) {
+        return this.options.receivers.patterns.some((pattern) => this.nodeOrAncestorNameIncludes(mesh, pattern));
+    }
+    matchesExcludePattern(node) {
+        const name = node.name?.toLowerCase() ?? '';
+        return this.options.casters.excludePatterns.some((pattern) => pattern && name.includes(pattern.toLowerCase()));
+    }
+    matchesRootBoundaryPattern(node) {
+        const name = node.name?.toLowerCase() ?? '';
+        return this.options.casters.rootBoundaryPatterns.some((pattern) => pattern && name.includes(pattern.toLowerCase()));
+    }
+    hasExcludedAncestor(mesh) {
+        let current = mesh.parent;
+        while (current) {
+            if (this.matchesRootBoundaryPattern(current))
+                return false;
+            if (hasDisablePlanarShadowMetadata(current) || this.matchesExcludePattern(current))
+                return true;
+            current = current.parent;
+        }
+        return false;
+    }
+    hasDisabledReceiver(mesh) {
+        return hasDisabledPlanarShadowReceiver(mesh, node => this.matchesRootBoundaryPattern(node));
+    }
+    isAlreadyCoveredByCaster(node) {
+        if (this.casters.has(node))
+            return true;
+        let current = node.parent;
+        while (current) {
+            if (current instanceof AbstractMesh && this.casters.has(current))
+                return true;
+            current = current.parent;
+        }
+        for (const descendant of node.getChildMeshes(false)) {
+            if (this.casters.has(descendant))
+                return true;
+        }
+        return false;
+    }
+    nodeOrAncestorNameIncludes(mesh, pattern) {
+        const normalized = pattern.toLowerCase();
+        if (!normalized)
+            return false;
+        return this.readNodeAndAncestorNames(mesh).some(name => name.includes(normalized));
+    }
+    readNodeAndAncestorNames(mesh) {
+        const cache = this.patternNameCache;
+        const cached = cache?.get(mesh);
+        if (cached)
+            return cached;
+        const names = [];
+        let current = mesh;
+        const seen = new Set();
+        while (current && typeof current === 'object' && !seen.has(current)) {
+            seen.add(current);
+            const name = current.name;
+            if (typeof name === 'string')
+                names.push(name.toLowerCase());
+            current = current.parent;
+        }
+        cache?.set(mesh, names);
+        return names;
+    }
+}
+function buildPlanarShadowHullGeometry(source, options) {
+    const geometrySource = source instanceof InstancedMesh ? source.sourceMesh : source;
+    const positions = geometrySource.getVerticesData(VertexBuffer.PositionKind);
+    if (!positions || positions.length < 9)
+        return null;
+    const planeNormal = options.planeNormal.clone().normalize();
+    const lightDir = options.lightDir.clone().normalize();
+    const denom = Vector3.Dot(planeNormal, lightDir);
+    if (Math.abs(denom) < 1e-5)
+        return null;
+    source.computeWorldMatrix(true);
+    const worldMatrix = source.getWorldMatrix();
+    const projectedPoints = [];
+    for (let index = 0; index < positions.length; index += 3) {
+        const localPoint = new Vector3(Number(positions[index]), Number(positions[index + 1]), Number(positions[index + 2]));
+        const worldPoint = Vector3.TransformCoordinates(localPoint, worldMatrix);
+        const t = (options.planeHeight - Vector3.Dot(planeNormal, worldPoint)) / denom;
+        if (t < -1e-4)
+            continue;
+        const projectedPoint = worldPoint.add(lightDir.scale(Math.max(0, t)));
+        projectedPoints.push(projectedPoint);
+    }
+    if (projectedPoints.length < 3)
+        return null;
+    const scaleCenter = averageVector3(projectedPoints);
+    const footprintScale = Number.isFinite(options.footprintScale) ? Math.max(0, options.footprintScale) : 1;
+    const biasedPoints = projectedPoints.map((point) => {
+        const scaled = footprintScale === 1
+            ? point
+            : scaleCenter.add(point.subtract(scaleCenter).scale(footprintScale));
+        return scaled.add(planeNormal.scale(options.planeBias * 0.002));
+    });
+    const basis = buildPlaneBasis(planeNormal);
+    const points2d = dedupeHullPoints(biasedPoints.map((point) => ({
+        x: Vector3.Dot(point, basis.tangent),
+        y: Vector3.Dot(point, basis.bitangent),
+        point,
+    })));
+    if (points2d.length < 3)
+        return null;
+    const hull = buildConvexHull(points2d);
+    if (hull.length < 3)
+        return null;
+    const center = averageVector3(hull.map((point) => point.point));
+    const positionsOut = [center.x, center.y, center.z];
+    const normalsOut = [planeNormal.x, planeNormal.y, planeNormal.z];
+    for (const hullPoint of hull) {
+        positionsOut.push(hullPoint.point.x, hullPoint.point.y, hullPoint.point.z);
+        normalsOut.push(planeNormal.x, planeNormal.y, planeNormal.z);
+    }
+    const indicesOut = [];
+    for (let index = 1; index <= hull.length; index += 1) {
+        indicesOut.push(0, index, index === hull.length ? 1 : index + 1);
+    }
+    return {
+        positions: positionsOut,
+        indices: indicesOut,
+        normals: normalsOut,
+    };
+}
+function bindPlanarShadowAlphaCutoutLayer(material, suffix, layer) {
+    material.setFloat(`u_shadowAlphaLevel${suffix}`, layer.level);
+    material.setFloat(`u_shadowAlphaChannelMode${suffix}`, layer.channel === 'red' ? 2 : layer.channel === 'luminance' ? 1 : 0);
+    material.setVector3(`u_shadowAlphaLuminanceWeights${suffix}`, layer.luminanceWeights);
+    material.setFloat(`u_shadowAlphaUvSet${suffix}`, layer.coordinatesIndex);
+    material.setMatrix(`u_shadowAlphaMatrix${suffix}`, layer.texture.getTextureMatrix?.() ?? Matrix.Identity());
+    material.setTexture(`shadowAlphaSampler${suffix}`, layer.texture);
+}
+function createPlanarShadowInstancedAlphaCutoutSignature(alphaCutout) {
+    if (!alphaCutout)
+        return { signature: 'opaque', reason: '' };
+    const layers = alphaCutout.layers.filter((layer) => !!layer);
+    if (layers.length !== 1) {
+        return {
+            signature: null,
+            reason: 'multi-layer alpha cutout requires independent projected mesh',
+        };
+    }
+    const [layer] = layers;
+    const textureIdentity = readPlanarShadowTextureIdentity(layer.texture);
+    if (!textureIdentity) {
+        return {
+            signature: null,
+            reason: 'alpha cutout texture identity unavailable',
+        };
+    }
+    return {
+        signature: [
+            'cutout',
+            `texture:${textureIdentity}`,
+            `channel:${layer.channel}`,
+            `uv:${layer.coordinatesIndex}`,
+            `level:${formatPlanarShadowSignatureNumber(layer.level)}`,
+            `cutoff:${formatPlanarShadowSignatureNumber(alphaCutout.cutoff)}`,
+            `weights:${formatPlanarShadowSignatureNumber(layer.luminanceWeights.x)},${formatPlanarShadowSignatureNumber(layer.luminanceWeights.y)},${formatPlanarShadowSignatureNumber(layer.luminanceWeights.z)}`,
+            `matrix:${serializePlanarShadowTextureMatrix(layer.texture)}`,
+        ].join('|'),
+        reason: '',
+    };
+}
+function readPlanarShadowGeometryIdentity(mesh) {
+    const geometry = mesh.geometry;
+    const geometryUniqueId = geometry?.uniqueId;
+    if (typeof geometryUniqueId === 'number' && Number.isFinite(geometryUniqueId))
+        return `id:${geometryUniqueId}`;
+    if (typeof geometryUniqueId === 'string' && geometryUniqueId.length > 0)
+        return `id:${geometryUniqueId}`;
+    return `mesh:${mesh.uniqueId}`;
+}
+function readPlanarShadowTextureIdentity(texture) {
+    const record = texture;
+    if (typeof record.uniqueId === 'number' && Number.isFinite(record.uniqueId))
+        return `id:${record.uniqueId}`;
+    if (typeof record.uniqueId === 'string' && record.uniqueId.length > 0)
+        return `id:${record.uniqueId}`;
+    if (typeof record.uid === 'string' && record.uid.length > 0)
+        return `uid:${record.uid}`;
+    if (typeof record.url === 'string' && record.url.length > 0)
+        return `url:${record.url}`;
+    if (typeof record.name === 'string' && record.name.length > 0)
+        return `name:${record.name}`;
+    return null;
+}
+function serializePlanarShadowTextureMatrix(texture) {
+    const matrix = texture.getTextureMatrix?.() ?? Matrix.Identity();
+    return [...matrix.m].map(formatPlanarShadowSignatureNumber).join(',');
+}
+function formatPlanarShadowSignatureNumber(value) {
+    if (!Number.isFinite(value))
+        return '0';
+    return String(Math.round(value * 1000000) / 1000000);
+}
+function readPlanarShadowEffectiveVisibility(node) {
+    let current = node;
+    while (current) {
+        if (isDisposedNode(current))
+            return false;
+        if (current.isEnabled?.() === false)
+            return false;
+        if (current.isVisible === false)
+            return false;
+        if (typeof current.visibility === 'number' && current.visibility <= 0)
+            return false;
+        current = current.parent && typeof current.parent === 'object'
+            ? current.parent
+            : null;
+    }
+    return true;
+}
+function buildPlaneBasis(normal) {
+    const seed = Math.abs(Vector3.Dot(normal, Vector3.Up())) > 0.95
+        ? Vector3.Right()
+        : Vector3.Up();
+    const tangent = Vector3.Cross(seed, normal).normalize();
+    const bitangent = Vector3.Cross(normal, tangent).normalize();
+    return { tangent, bitangent };
+}
+function dedupeHullPoints(points) {
+    const seen = new Map();
+    for (const point of points) {
+        const key = `${Math.round(point.x * 100000)}:${Math.round(point.y * 100000)}`;
+        if (!seen.has(key))
+            seen.set(key, point);
+    }
+    return [...seen.values()];
+}
+function buildConvexHull(points) {
+    const sorted = [...points].sort((a, b) => (a.x === b.x ? a.y - b.y : a.x - b.x));
+    const lower = [];
+    for (const point of sorted) {
+        while (lower.length >= 2 && hullCross(lower[lower.length - 2], lower[lower.length - 1], point) <= 1e-7) {
+            lower.pop();
+        }
+        lower.push(point);
+    }
+    const upper = [];
+    for (let index = sorted.length - 1; index >= 0; index -= 1) {
+        const point = sorted[index];
+        while (upper.length >= 2 && hullCross(upper[upper.length - 2], upper[upper.length - 1], point) <= 1e-7) {
+            upper.pop();
+        }
+        upper.push(point);
+    }
+    lower.pop();
+    upper.pop();
+    return lower.concat(upper);
+}
+function hullCross(origin, a, b) {
+    return (a.x - origin.x) * (b.y - origin.y) - (a.y - origin.y) * (b.x - origin.x);
+}
+function averageVector3(points) {
+    const total = points.reduce((sum, point) => sum.addInPlace(point), Vector3.Zero());
+    return total.scale(1 / points.length);
+}
+function resolvePlanarShadowOptions(override, base = DEFAULT_PLANAR_SHADOW_OPTIONS) {
+    return {
+        enabled: override.enabled ?? base.enabled,
+        plane: {
+            ...base.plane,
+            ...override.plane,
+            heightMode: readPlaneHeightMode(override.plane?.heightMode, base.plane.heightMode),
+        },
+        appearance: {
+            color: { ...base.appearance.color, ...override.appearance?.color },
+        },
+        direction: { mode: 'follow-light' },
+        projection: {
+            footprintScale: readNonNegativeFiniteNumber(override.projection?.footprintScale, base.projection.footprintScale),
+            strategy: readPlanarShadowProjectionStrategy(override.projection?.strategy, base.projection.strategy),
+        },
+        stencil: {
+            enabled: override.stencil?.enabled ?? base.stencil.enabled,
+            receiverRenderingGroup: override.stencil?.receiverRenderingGroup ?? base.stencil.receiverRenderingGroup,
+            shadowRenderingGroup: override.stencil?.shadowRenderingGroup ?? base.stencil.shadowRenderingGroup,
+        },
+        casters: {
+            autoDetectAll: override.casters?.autoDetectAll ?? base.casters.autoDetectAll,
+            includePatterns: override.casters?.includePatterns ? [...override.casters.includePatterns] : [...base.casters.includePatterns],
+            excludePatterns: override.casters?.excludePatterns ? [...override.casters.excludePatterns] : [...base.casters.excludePatterns],
+            rootBoundaryPatterns: override.casters?.rootBoundaryPatterns
+                ? [...override.casters.rootBoundaryPatterns]
+                : [...base.casters.rootBoundaryPatterns],
+            minVolume: override.casters?.minVolume ?? base.casters.minVolume,
+        },
+        receivers: {
+            patterns: override.receivers?.patterns ? [...override.receivers.patterns] : [...base.receivers.patterns],
+        },
+        debug: override.debug ?? base.debug,
+    };
+}
+function summarizePlanarShadowStrategy(pairs, instancedProjectedCount = 0) {
+    const projectedCount = pairs.filter((pair) => pair.mode === 'projected-mesh').length + instancedProjectedCount;
+    const hullCount = pairs.filter((pair) => pair.mode === 'flat-hull').length;
+    if (projectedCount > 0 && hullCount === 0)
+        return 'projected-mesh';
+    if (hullCount > 0 && projectedCount === 0)
+        return 'convex-hull';
+    return 'auto';
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter(value => value.length > 0))];
+}
+function uniqueNumbers(values) {
+    return [...new Set(values.filter(value => Number.isFinite(value)))];
+}
+function readPlanarShadowProjectionStrategy(value, fallback) {
+    return value === 'auto' || value === 'projected-mesh' || value === 'convex-hull'
+        ? value
+        : fallback;
+}
+function cloneResolvedOptions(options) {
+    return resolvePlanarShadowOptions(options);
+}
+function readPlaneHeightMode(value, fallback) {
+    return value === 'fixed' || value === 'receiver'
+        ? value
+        : fallback === 'fixed' || fallback === 'receiver'
+            ? fallback
+            : 'receiver';
+}
+function collectNodeMeshes(root) {
+    const meshes = root.getChildMeshes(false);
+    if (root instanceof Mesh || root instanceof InstancedMesh)
+        meshes.unshift(root);
+    return meshes;
+}
+function hasDisablePlanarShadowMetadata(node) {
+    const metadata = node.metadata;
+    return !!metadata
+        && typeof metadata === 'object'
+        && (metadata.disablePlanarShadow === true
+            || metadata.planarShadowInternal === true);
+}
+function hasDisabledPlanarShadowReceiver(node, isRootBoundary) {
+    let current = node;
+    while (current) {
+        if (readEditorProjectionShadowReceive(current) === 'none')
+            return true;
+        current = current.parent instanceof AbstractMesh && !isRootBoundary(current.parent)
+            ? current.parent
+            : null;
+    }
+    return false;
+}
+function readEditorProjectionShadowReceive(node) {
+    const metadata = node.metadata;
+    if (!metadata || typeof metadata !== 'object')
+        return undefined;
+    const editorProjection = metadata.editorProjection;
+    if (!editorProjection || typeof editorProjection !== 'object')
+        return undefined;
+    const shadow = editorProjection.shadow;
+    if (!shadow || typeof shadow !== 'object')
+        return undefined;
+    return shadow.receive;
+}
+function isDisposedNode(node) {
+    return typeof node.isDisposed === 'function' && node.isDisposed();
+}
+function readNonNegativeFiniteNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+function readMeshMaterial(mesh) {
+    const material = mesh.material;
+    return material && typeof material === 'object'
+        ? material
+        : null;
+}
+function resolvePlanarShadowAlphaCutout(mesh) {
+    return findAlphaCutout(mesh.material);
+}
+function findAlphaCutout(material) {
+    if (!material || typeof material !== 'object')
+        return null;
+    const record = material;
+    const cutoff = readAlphaCutoff(record.alphaCutOff ?? record.alphaCutoff);
+    const geometryOpacityTexture = readBaseTexture(record.geometryOpacityTexture);
+    if (geometryOpacityTexture && materialUsesOpacityAlpha(record)) {
+        const layer = createPlanarShadowAlphaCutoutLayer(geometryOpacityTexture, 'red', PBR_ALPHA_LUMINANCE_WEIGHTS);
+        return layer ? {
+            cutoff,
+            layers: [layer],
+        } : null;
+    }
+    const surfaceLayer = resolvePlanarShadowSurfaceAlphaLayer(record);
+    const opacityTexture = readBaseTexture(record.opacityTexture);
+    if (opacityTexture && materialUsesOpacityAlpha(record)) {
+        const opacityLayer = createPlanarShadowAlphaCutoutLayer(opacityTexture, opacityTexture.getAlphaFromRGB ? 'luminance' : 'alpha', resolveOpacityLuminanceWeights(record));
+        if (!opacityLayer)
+            return surfaceLayer ? { cutoff, layers: [surfaceLayer] } : null;
+        return {
+            cutoff,
+            layers: surfaceLayer ? [opacityLayer, surfaceLayer] : [opacityLayer],
+        };
+    }
+    if (surfaceLayer)
+        return { cutoff, layers: [surfaceLayer] };
+    const subMaterials = Array.isArray(record.subMaterials) ? record.subMaterials : [];
+    for (const subMaterial of subMaterials) {
+        const resolved = findAlphaCutout(subMaterial);
+        if (resolved)
+            return resolved;
+    }
+    return null;
+}
+function resolvePlanarShadowSurfaceAlphaLayer(material) {
+    const albedoTexture = readBaseTexture(material.albedoTexture);
+    if (albedoTexture && materialUsesAlbedoAlpha(material, albedoTexture)) {
+        return createPlanarShadowAlphaCutoutLayer(albedoTexture, 'alpha', STANDARD_ALPHA_LUMINANCE_WEIGHTS, 1);
+    }
+    const diffuseTexture = readBaseTexture(material.diffuseTexture);
+    if (diffuseTexture && materialUsesDiffuseAlpha(material, diffuseTexture)) {
+        return createPlanarShadowAlphaCutoutLayer(diffuseTexture, 'alpha', STANDARD_ALPHA_LUMINANCE_WEIGHTS, 1);
+    }
+    const baseColorTexture = readBaseTexture(material.baseColorTexture);
+    if (baseColorTexture && materialUsesBaseAlpha(material, baseColorTexture)) {
+        return createPlanarShadowAlphaCutoutLayer(baseColorTexture, 'alpha', STANDARD_ALPHA_LUMINANCE_WEIGHTS, 1);
+    }
+    const baseTexture = readBaseTexture(material.baseTexture);
+    if (baseTexture && materialUsesBaseAlpha(material, baseTexture)) {
+        return createPlanarShadowAlphaCutoutLayer(baseTexture, 'alpha', STANDARD_ALPHA_LUMINANCE_WEIGHTS, 1);
+    }
+    return null;
+}
+function createPlanarShadowAlphaCutoutLayer(texture, channel, luminanceWeights, level = readTextureLevel(texture)) {
+    const coordinatesIndex = readSupportedTextureCoordinatesIndex(texture);
+    return coordinatesIndex == null
+        ? null
+        : {
+            texture,
+            channel,
+            coordinatesIndex,
+            level,
+            luminanceWeights,
+        };
+}
+function readBaseTexture(value) {
+    return value && typeof value === 'object' && typeof value.getClassName === 'function'
+        ? value
+        : null;
+}
+function readSupportedTextureCoordinatesIndex(texture) {
+    return texture.coordinatesIndex === 0
+        || texture.coordinatesIndex === 1
+        || texture.coordinatesIndex === 2
+        || texture.coordinatesIndex === 3
+        || texture.coordinatesIndex === 4
+        || texture.coordinatesIndex === 5
+        ? texture.coordinatesIndex
+        : null;
+}
+function readTextureLevel(texture) {
+    return typeof texture.level === 'number' && Number.isFinite(texture.level) ? Math.max(0, texture.level) : 1;
+}
+function resolveOpacityLuminanceWeights(material) {
+    const className = typeof material.getClassName === 'function'
+        ? String(material.getClassName.call(material))
+        : '';
+    return className.includes('PBR') ? PBR_ALPHA_LUMINANCE_WEIGHTS : STANDARD_ALPHA_LUMINANCE_WEIGHTS;
+}
+function materialUsesDiffuseAlpha(material, texture) {
+    return materialAllowsTextureAlpha(material)
+        && texture.hasAlpha === true
+        && (material.useAlphaFromDiffuseTexture === true || materialUsesTextureAlpha(material, texture));
+}
+function materialUsesAlbedoAlpha(material, texture) {
+    return materialAllowsTextureAlpha(material)
+        && texture.hasAlpha === true
+        && (material.useAlphaFromAlbedoTexture === true || materialUsesTextureAlpha(material, texture));
+}
+function materialUsesBaseAlpha(material, texture) {
+    return materialAllowsTextureAlpha(material)
+        && texture.hasAlpha === true
+        && (material.useAlphaFromBaseColorTexture === true
+            || material._useAlphaFromBaseColorTexture === true
+            || materialUsesTextureAlpha(material, texture));
+}
+function materialUsesTextureAlpha(material, texture) {
+    if (texture.hasAlpha !== true)
+        return false;
+    const needAlphaTesting = material.needAlphaTesting;
+    if (typeof needAlphaTesting === 'function' && needAlphaTesting.call(material) === true)
+        return true;
+    return material.transparencyMode === Material.MATERIAL_ALPHATEST
+        || material.transparencyMode === Material.MATERIAL_ALPHATESTANDBLEND;
+}
+function materialUsesOpacityAlpha(material) {
+    if (material.transparencyMode === Material.MATERIAL_OPAQUE)
+        return false;
+    const needAlphaTesting = material.needAlphaTesting;
+    if (typeof needAlphaTesting === 'function' && needAlphaTesting.call(material) === true)
+        return true;
+    const needAlphaBlending = material.needAlphaBlending;
+    if (typeof needAlphaBlending === 'function' && needAlphaBlending.call(material) === true)
+        return true;
+    return material.transparencyMode === Material.MATERIAL_ALPHATEST
+        || material.transparencyMode === Material.MATERIAL_ALPHABLEND
+        || material.transparencyMode === Material.MATERIAL_ALPHATESTANDBLEND;
+}
+function materialAllowsTextureAlpha(material) {
+    return material.transparencyMode !== Material.MATERIAL_OPAQUE;
+}
+function readAlphaCutoff(value) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.min(1, Math.max(0, value))
+        : 0.1;
+}
+function clamp01(value) {
+    return Math.min(1, Math.max(0, value));
+}
+//# sourceMappingURL=planar-shadow-system.js.map