@fps-games/editor 0.1.8-beta.2 → 0.1.8-beta.4

package/node_modules/@fps-games/babylon-renderer/dist/shadows/planar-shadow-system.js

@@ -30,12 +30,16 @@ class BabylonPlanarShadowSystem {
         this.casters = new Map();
         this.receivers = new Map();
         this.syncObservers = new Map();
+        this.instancedBatches = new Map();
+        this.instancedEntriesByRoot = new Map();
         this.renderObserver = null;
+        this.instancedBatchSyncObserver = null;
         this.meshAddedObserver = null;
         this.initialized = false;
         this.casterPatterns = [];
         this.resolvedPlaneNormal = Vector3.Up();
         this.resolvedPlaneHeight = 0;
+        this.patternNameCache = null;
         this.options = resolvePlanarShadowOptions(options);
         this.casterPatterns = [...this.options.casters.includePatterns];
     }
@@ -48,6 +52,7 @@ class BabylonPlanarShadowSystem {
         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();
     }
@@ -55,7 +60,7 @@ class BabylonPlanarShadowSystem {
         const root = this.findCasterRoot(mesh);
         if (!this.initialized || this.casters.has(root))
             return false;
-        if (!this.isValidShadowSource(mesh))
+        if (this.getInvalidShadowSourceReason(mesh))
             return false;
         const shadow = this.createShadowForNode(root);
         if (!shadow)
@@ -133,12 +138,21 @@ class BabylonPlanarShadowSystem {
     refresh() {
         if (!this.initialized)
             return;
-        this.pruneDisposedCasters();
-        this.refreshReceivers();
-        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();
+        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) {
@@ -179,6 +193,12 @@ class BabylonPlanarShadowSystem {
             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],
@@ -188,6 +208,7 @@ class BabylonPlanarShadowSystem {
                 z: weights.z,
             })),
             fallbackReasons: [...info.fallbackReasons],
+            instancingFallbackReasons: [...info.instancingFallbackReasons],
         }));
     }
     dispose() {
@@ -195,6 +216,10 @@ class BabylonPlanarShadowSystem {
             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;
@@ -205,6 +230,8 @@ class BabylonPlanarShadowSystem {
         }
         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)
@@ -425,18 +452,58 @@ class BabylonPlanarShadowSystem {
             this.scene.onBeforeRenderObservable.remove(observer);
             this.syncObservers.delete(root);
         }
-        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();
+        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();
         }
-        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)
@@ -447,10 +514,10 @@ class BabylonPlanarShadowSystem {
     tryAutoAddCaster(mesh) {
         if (!this.initialized || this.casters.has(mesh))
             return;
-        if (!this.isValidShadowSource(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;
@@ -475,10 +542,16 @@ class BabylonPlanarShadowSystem {
         const validMeshes = collectNodeMeshes(root).filter((mesh) => this.isValidShadowSource(mesh));
         if (validMeshes.length === 0)
             return null;
-        const shadowRoot = new TransformNode(`${root.name}_planarShadowRoot`, this.scene);
+        let shadowRoot = null;
+        const ensureShadowRoot = () => {
+            shadowRoot ?? (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) {
@@ -486,8 +559,20 @@ class BabylonPlanarShadowSystem {
                 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 = resolvePlanarShadowAlphaCutout(geometrySource);
+                const alphaCutout = instancingEligibility.alphaCutout;
                 const material = this.resolveShadowMaterial(geometrySource, sharedSkeleton, sharedMaterial, alphaCutout);
                 if (geometrySource.skeleton) {
                     hasSkeleton = true;
@@ -498,7 +583,7 @@ class BabylonPlanarShadowSystem {
                 const shadowMesh = material ? this.createProjectedShadowMesh(mesh, material) : null;
                 if (shadowMesh) {
                     const alphaCutoutLayers = alphaCutout?.layers.filter((layer) => !!layer) ?? [];
-                    shadowMesh.parent = shadowRoot;
+                    shadowMesh.parent = ensureShadowRoot();
                     pairs.push({
                         mode: 'projected-mesh',
                         source: mesh,
@@ -517,7 +602,7 @@ class BabylonPlanarShadowSystem {
             }
             const shadowMesh = this.createHullShadowMesh(mesh);
             if (shadowMesh) {
-                shadowMesh.parent = shadowRoot;
+                shadowMesh.parent = ensureShadowRoot();
                 pairs.push({
                     mode: 'flat-hull',
                     source: mesh,
@@ -533,46 +618,279 @@ class BabylonPlanarShadowSystem {
                 fallbackReasons.push(`${mesh.name}: convex hull geometry unavailable`);
             }
         }
-        if (pairs.length === 0) {
-            shadowRoot.dispose();
+        if (pairs.length === 0 && instancedEntries.length === 0) {
+            this.removeInstancedEntriesForRoot(root);
             return null;
         }
-        const sync = () => {
-            if (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);
+        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);
+            };
+            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,
-            sourceMeshNames: uniqueStrings(pairs.map((pair) => pair.source.name)),
-            sourceMeshUniqueIds: uniqueNumbers(pairs.map((pair) => pair.source.uniqueId)),
+            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),
-            projectedMeshCount: pairs.filter((pair) => pair.mode === 'projected-mesh').length,
+            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,
-            alphaCutoutChannels: pairs.flatMap((pair) => pair.alphaCutoutChannels),
-            alphaCutoutUvSets: pairs.flatMap((pair) => pair.alphaCutoutUvSets),
-            alphaCutoutLevels: pairs.flatMap((pair) => pair.alphaCutoutLevels),
-            alphaCutoutLuminanceWeights: pairs.flatMap((pair) => pair.alphaCutoutLuminanceWeights),
+            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;
@@ -664,29 +982,36 @@ class BabylonPlanarShadowSystem {
         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 false;
+            return 'source is not a mesh';
         if (mesh instanceof Mesh && !mesh.geometry)
-            return false;
+            return 'geometry unavailable';
         if (mesh instanceof InstancedMesh && !mesh.sourceMesh.geometry)
-            return false;
-        if (!mesh.isVisible || !mesh.isEnabled())
-            return false;
+            return 'instance source geometry unavailable';
         if (hasDisablePlanarShadowMetadata(mesh))
-            return false;
-        if (this.matchesExcludePattern(mesh) || this.hasExcludedAncestor(mesh))
-            return false;
+            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 false;
+            return 'source matches receiver pattern';
         mesh.computeWorldMatrix(true);
         const size = mesh.getBoundingInfo()?.boundingBox.extendSizeWorld;
         if (!size)
-            return true;
+            return null;
         const volume = size.x * size.y * size.z;
         if (volume >= this.options.casters.minVolume)
-            return true;
+            return null;
         const maxProjectedArea = Math.max(size.x * size.y, size.x * size.z, size.y * size.z);
-        return maxProjectedArea >= this.options.casters.minVolume;
+        return maxProjectedArea >= this.options.casters.minVolume
+            ? null
+            : `bounds below minVolume volume=${volume} maxProjectedArea=${maxProjectedArea}`;
     }
     findCasterRoot(mesh) {
         let topmost = mesh;
@@ -706,7 +1031,7 @@ class BabylonPlanarShadowSystem {
         return topmost;
     }
     matchesCasterPattern(mesh) {
-        return this.casterPatterns.some((pattern) => nodeOrAncestorNameIncludes(mesh, pattern));
+        return this.casterPatterns.some((pattern) => this.nodeOrAncestorNameIncludes(mesh, pattern));
     }
     matchesReceiver(mesh) {
         return this.options.stencil.enabled
@@ -717,7 +1042,7 @@ class BabylonPlanarShadowSystem {
             && this.matchesReceiverPattern(mesh);
     }
     matchesReceiverPattern(mesh) {
-        return this.options.receivers.patterns.some((pattern) => nodeOrAncestorNameIncludes(mesh, pattern));
+        return this.options.receivers.patterns.some((pattern) => this.nodeOrAncestorNameIncludes(mesh, pattern));
     }
     matchesExcludePattern(node) {
         const name = node.name?.toLowerCase() ?? '';
@@ -742,12 +1067,44 @@ class BabylonPlanarShadowSystem {
         return hasDisabledPlanarShadowReceiver(mesh, node => this.matchesRootBoundaryPattern(node));
     }
     isAlreadyCoveredByCaster(node) {
-        for (const caster of this.casters.keys()) {
-            if (caster === node || isDescendantOf(node, caster) || isDescendantOf(caster, 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;
@@ -817,6 +1174,87 @@ function bindPlanarShadowAlphaCutoutLayer(material, suffix, layer) {
     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()
@@ -898,8 +1336,8 @@ function resolvePlanarShadowOptions(override, base = DEFAULT_PLANAR_SHADOW_OPTIO
         debug: override.debug ?? base.debug,
     };
 }
-function summarizePlanarShadowStrategy(pairs) {
-    const projectedCount = pairs.filter((pair) => pair.mode === 'projected-mesh').length;
+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';
@@ -934,27 +1372,6 @@ function collectNodeMeshes(root) {
         meshes.unshift(root);
     return meshes;
 }
-function nodeOrAncestorNameIncludes(mesh, pattern) {
-    const normalized = pattern.toLowerCase();
-    if (mesh.name.toLowerCase().includes(normalized))
-        return true;
-    let current = mesh.parent;
-    while (current) {
-        if (current.name?.toLowerCase().includes(normalized))
-            return true;
-        current = current.parent;
-    }
-    return false;
-}
-function isDescendantOf(node, ancestor) {
-    let current = node.parent;
-    while (current) {
-        if (current === ancestor)
-            return true;
-        current = current.parent;
-    }
-    return false;
-}
 function hasDisablePlanarShadowMetadata(node) {
     const metadata = node.metadata;
     return !!metadata