@zephyr3d/scene 0.9.24 → 0.9.26

package/dist/material/shader/helper.js

@@ -1,5 +1,5 @@
 import { Vector3, Vector4, Vector2, REVERSE_Z, DEPTH_FARTHEST, DEPTH_REDUCE_CLOSER, DEPTH_REDUCE_FARTHER } from '@zephyr3d/base';
-import { RENDER_PASS_TYPE_DEPTH, RENDER_PASS_TYPE_SHADOWMAP, RENDER_PASS_TYPE_OBJECT_COLOR, RENDER_PASS_TYPE_LIGHT, MaterialVaryingFlags, MORPH_WEIGHTS_VECTOR_COUNT, MORPH_TARGET_POSITION, MORPH_TARGET_NORMAL, MORPH_TARGET_TANGENT, MORPH_ATTRIBUTE_VECTOR_COUNT } from '../../values.js';
+import { RENDER_PASS_TYPE_DEPTH, RENDER_PASS_TYPE_SHADOWMAP, RENDER_PASS_TYPE_OBJECT_COLOR, RENDER_PASS_TYPE_LIGHT, MaterialVaryingFlags, MAX_SKIN_EXTRA_INFLUENCE_PAIRS, MORPH_WEIGHTS_VECTOR_COUNT, MORPH_TARGET_POSITION, MORPH_TARGET_NORMAL, MORPH_TARGET_TANGENT, MORPH_ATTRIBUTE_VECTOR_COUNT, LIGHT_TYPE_DIRECTIONAL } from '../../values.js';
 import { ProgramBuilder } from '@zephyr3d/device';
 import { decodeNormalizedFloatFromRGBA, linearToGamma } from '../../shaders/misc.js';
 import { getSamplerOptions, fetchSampler } from '../../utility/misc.js';
@@ -7,6 +7,7 @@ import { PHYSICAL_BAKE_EXPOSURE } from '../../utility/physical.js';
 import { getDevice } from '../../app/api.js';
 import { getDefaultAtmosphereParams, getAtmosphereParamsStruct } from '../../shaders/atmosphere.js';
 import { getDefaultHeightFogParams, getHeightFogParamsStruct, calculateFog } from '../../shaders/fog.js';
+import { getShadowReceiverNoL, getShadowReceiverBiasFactor } from '../../shadow/receiver_bias.js';
 
 const UNIFORM_NAME_LIGHT_BUFFER = 'Z_UniformLightBuffer';
 const UNIFORM_NAME_LIGHT_INDEX_TEXTURE = 'Z_UniformLightIndexTex';
@@ -32,11 +33,13 @@ const UNIFORM_NAME_INSTANCE_DATA_OFFSET = 'Z_UniformInstanceDataOffset';
 const UNIFORM_NAME_BONE_MATRICES = 'Z_UniformBoneMatrices';
 const UNIFORM_NAME_BONE_TEXTURE_SIZE = 'Z_UniformBoneTexSize';
 const UNIFORM_NAME_BONE_INV_BIND_MATRIX = 'Z_UniformBoneInvBindMatrix';
+const UNIFORM_NAME_SKIN_INFLUENCE_DATA = 'Z_UniformSkinInfluenceData';
+const UNIFORM_NAME_SKIN_INFLUENCE_INFO = 'Z_UniformSkinInfluenceInfo';
 const UNIFORM_NAME_MORPH_DATA = 'Z_UniformMorphData';
 const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
-/**
- * Helper shader functions for the builtin material system
- * @public
+/**
+ * Helper shader functions for the builtin material system
+ * @public
  */ class ShaderHelper {
     static BILLBOARD_SPHERICAL = 1;
     static BILLBOARD_SYLINDRAL = 2;
@@ -46,6 +49,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     /** @internal */ static SKIN_MATRIX_NAME = 'Z_SkinMatrix';
     static SKIN_PREV_MATRIX_NAME = 'Z_PrevSkinMatrix';
     static SKIN_BONE_OFFSET = 'Z_boneOffset';
+    static RESOLVED_VERTEX_NORMAL_NAME = 'Z_ResolvedVertexNormal';
     /** @internal */ static _drawableBindGroupLayouts = {};
     /** @internal */ static _lightUniformShadow = {
         sunDir: new Vector3(),
@@ -101,6 +105,12 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     static getBoneInvBindMatrixUniformName() {
         return UNIFORM_NAME_BONE_INV_BIND_MATRIX;
     }
+    static getSkinInfluenceDataUniformName() {
+        return UNIFORM_NAME_SKIN_INFLUENCE_DATA;
+    }
+    static getSkinInfluenceInfoUniformName() {
+        return UNIFORM_NAME_SKIN_INFLUENCE_INFO;
+    }
     static getMorphDataUniformName() {
         return UNIFORM_NAME_MORPH_DATA;
     }
@@ -129,25 +139,25 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         }
         return bindGroupLayout;
     }
-    /**
-   * Prepares the fragment shader which is going to be used in our material system
-   *
-   * @remarks
-   * This function will setup all nessesary uniforms acoording to the drawing context
-   *
-   * @param pb - The program builder
-   * @param ctx - The drawing context
+    /**
+   * Prepares the fragment shader which is going to be used in our material system
+   *
+   * @remarks
+   * This function will setup all nessesary uniforms acoording to the drawing context
+   *
+   * @param pb - The program builder
+   * @param ctx - The drawing context
    */ static prepareFragmentShader(pb, ctx) {
         this.setupGlobalUniforms(pb, ctx);
     }
-    /**
-   * Prepares the vertex shader which is going to be used in our material system
-   *
-   * @remarks
-   * This function will setup all nessesary uniforms according to the drawing context
-   *
-   * @param pb - The program builder
-   * @param ctx - The drawing context
+    /**
+   * Prepares the vertex shader which is going to be used in our material system
+   *
+   * @remarks
+   * This function will setup all nessesary uniforms according to the drawing context
+   *
+   * @param pb - The program builder
+   * @param ctx - The drawing context
    */ static prepareVertexShader(pb, ctx) {
         this.setupGlobalUniforms(pb, ctx);
         this.prepareVertexShaderCommon(pb, ctx);
@@ -183,10 +193,22 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 pb.vec4('directionCutoff'),
                 pb.mat4('viewMatrix'),
                 pb.vec4('depthBias'),
+                // Same slot the lighting pass exposes through getShadowImplParams. A
+                // caster normally has no use for it, but one that encodes something
+                // beyond depth - deep opacity map layers - needs the same parameters the
+                // receiver will decode with.
+                pb.vec4('implParams'),
                 pb.int('lightType')
             ]);
             scope.camera = cameraStruct().uniform(0);
             scope.light = lightStruct().uniform(0);
+            // Lets the shadow implementation add its own caster inputs. Only deep
+            // opacity maps use this, to read the frontmost depth its first pass wrote.
+            const shadowLight = ctx.renderPass.light;
+            const casterParams = shadowLight ? ctx.shadowMapInfo?.get(shadowLight) : null;
+            if (casterParams) {
+                casterParams.impl?.declareCasterUniforms(scope, casterParams);
+            }
         } else if (ctx.renderPass.type === RENDER_PASS_TYPE_DEPTH || ctx.renderPass.type === RENDER_PASS_TYPE_OBJECT_COLOR) {
             scope.camera = cameraStruct().uniform(0);
         } else if (ctx.renderPass.type === RENDER_PASS_TYPE_LIGHT) {
@@ -293,35 +315,37 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             }
         }
     }
-    /**
-   * This function checks if the shader needs to process skeletal animation.
-   *
-   * @param scope - Current shader scope
-   *
-   * @returns true if the shader needs to process skeletal animation, otherwise false.
+    /**
+   * This function checks if the shader needs to process skeletal animation.
+   *
+   * @param scope - Current shader scope
+   *
+   * @returns true if the shader needs to process skeletal animation, otherwise false.
    */ static hasSkinning(scope) {
         return !!scope[UNIFORM_NAME_BONE_MATRICES];
     }
-    /**
-   * This function checks if the shader needs to process morph target animation.
-   *
-   * @param scope - Current shader scope
-   *
-   * @returns true if the shader needs to process morph target animation, otherwise false.
+    /**
+   * This function checks if the shader needs to process morph target animation.
+   *
+   * @param scope - Current shader scope
+   *
+   * @returns true if the shader needs to process morph target animation, otherwise false.
    */ static hasMorphing(scope) {
         return !!scope[UNIFORM_NAME_MORPH_DATA];
     }
-    /**
-   * Calculate skinning matrix for current vertex
-   *
-   * @param scope - Current shader scope
-   *
-   * @returns Skinning matrix for current vertex, or null if there is not skeletal animation
+    /**
+   * Calculate skinning matrix for current vertex
+   *
+   * @param scope - Current shader scope
+   *
+   * @returns Skinning matrix for current vertex, or null if there is not skeletal animation
    */ static calculateSkinMatrix(scope) {
         if (!this.hasSkinning(scope)) {
             return null;
         }
         const pb = scope.$builder;
+        const isWebGL = pb.getDevice().type === 'webgl';
+        const supportsTextureLoad = !isWebGL;
         const funcNameGetBoneMatrixFromTexture = 'Z_getBoneMatrixFromTexture';
         pb.func(funcNameGetBoneMatrixFromTexture, [
             pb.int('boneIndex')
@@ -354,6 +378,33 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             this.$l.m2 = scope.$g[funcNameGetBoneMatrixFromTexture](pb.int(blendIndices[2]));
             this.$l.m3 = scope.$g[funcNameGetBoneMatrixFromTexture](pb.int(blendIndices[3]));
             this.$l.m = pb.add(pb.mul(this.m0, blendWeights.x), pb.mul(this.m1, blendWeights.y), pb.mul(this.m2, blendWeights.z), pb.mul(this.m3, blendWeights.w));
+            this.$l.skinInfo = this[UNIFORM_NAME_SKIN_INFLUENCE_INFO];
+            this.$if(pb.greaterThan(this.skinInfo.z, 4), function() {
+                this.$l.vertexIndex = isWebGL ? pb.int(scope.$inputs.zFakeVertexID) : pb.int(scope.$builtins.vertexIndex);
+                this.$l.texWidth = pb.int(this.skinInfo.x);
+                this.$l.pairCount = pb.int(this.skinInfo.w);
+                this.$for(pb.int('pairIndex'), 0, MAX_SKIN_EXTRA_INFLUENCE_PAIRS, function() {
+                    this.$if(pb.greaterThanEqual(this.pairIndex, this.pairCount), function() {
+                        this.$break();
+                    });
+                    this.$l.pixelIndex = pb.add(pb.mul(this.vertexIndex, this.pairCount), this.pairIndex);
+                    this.$l.xIndex = pb.mod(this.pixelIndex, this.texWidth);
+                    this.$l.yIndex = pb.div(this.pixelIndex, this.texWidth);
+                    if (supportsTextureLoad) {
+                        this.$l.extra = pb.textureLoad(this[UNIFORM_NAME_SKIN_INFLUENCE_DATA], pb.ivec2(this.xIndex, this.yIndex), 0);
+                    } else {
+                        this.$l.u = pb.div(pb.add(pb.float(this.xIndex), 0.5), this.skinInfo.x);
+                        this.$l.v = pb.div(pb.add(pb.float(this.yIndex), 0.5), this.skinInfo.y);
+                        this.$l.extra = pb.textureSampleLevel(this[UNIFORM_NAME_SKIN_INFLUENCE_DATA], pb.vec2(this.u, this.v), 0);
+                    }
+                    this.$if(pb.greaterThan(this.extra.y, 0), function() {
+                        this.m = pb.add(this.m, pb.mul(scope.$g[funcNameGetBoneMatrixFromTexture](pb.int(this.extra.x)), this.extra.y));
+                    });
+                    this.$if(pb.greaterThan(this.extra.w, 0), function() {
+                        this.m = pb.add(this.m, pb.mul(scope.$g[funcNameGetBoneMatrixFromTexture](pb.int(this.extra.z)), this.extra.w));
+                    });
+                });
+            });
             this.$return(pb.mul(invBindMatrix, this.m));
         });
         return scope.$g[funcNameGetSkinningMatrix]();
@@ -389,7 +440,8 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                         });
                         this.$l.weight = morphInfo.at(pb.add(1, this.i)).at(this.j);
                         this.$if(pb.notEqual(this.weight, 0), function() {
-                            this.$l.pixelIndex = pb.float(pb.add(this.offset, pb.mul(this.index, this.numVertices), this.vertexIndex));
+                            this.$l.targetIndex = pb.int(morphInfo.at(pb.add(1 + MORPH_WEIGHTS_VECTOR_COUNT, this.i)).at(this.j));
+                            this.$l.pixelIndex = pb.float(pb.add(this.offset, pb.mul(this.targetIndex, this.numVertices), this.vertexIndex));
                             this.$l.xIndex = pb.mod(this.pixelIndex, this.texWidth);
                             this.$l.yIndex = pb.floor(pb.div(this.pixelIndex, this.texWidth));
                             this.$l.u = pb.div(pb.add(this.xIndex, 0.5), this.texWidth);
@@ -405,7 +457,8 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                     this.$l.j = pb.compAnd(this.t, 3);
                     this.$l.weight = morphInfo.at(pb.add(1, this.i)).at(this.j);
                     this.$if(pb.notEqual(this.weight, 0), function() {
-                        this.$l.pixelIndex = pb.float(pb.add(this.offset, pb.mul(this.t, this.numVertices), this.vertexIndex));
+                        this.$l.targetIndex = pb.int(morphInfo.at(pb.add(1 + MORPH_WEIGHTS_VECTOR_COUNT, this.i)).at(this.j));
+                        this.$l.pixelIndex = pb.float(pb.add(this.offset, pb.mul(this.targetIndex, this.numVertices), this.vertexIndex));
                         this.$l.xIndex = pb.mod(this.pixelIndex, this.texWidth);
                         this.$l.yIndex = pb.floor(pb.div(this.pixelIndex, this.texWidth));
                         this.$l.u = pb.div(pb.add(this.xIndex, 0.5), this.texWidth);
@@ -417,17 +470,166 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             }
             this.$return(this.value);
         });
-        const pos = 1 + MORPH_WEIGHTS_VECTOR_COUNT + (attrib >> 2);
+        const pos = 1 + MORPH_WEIGHTS_VECTOR_COUNT * 2 + (attrib >> 2);
         const comp = attrib & 3;
         const offset = scope[this.getMorphInfoUniformName()][pos][comp];
         return scope[funcName](pb.int(offset));
     }
+    /**
+   * Normalize a morphed direction without allowing cancellation between
+   * multiple morph targets to turn a valid base direction into NaN/noise.
+   *
+   * Morph normal/tangent data is additive. When two targets cancel the base
+   * direction, the zero-length result is not a meaningful direction, so the
+   * authored vertex direction is the least surprising fallback.
+   * @internal
+   */ static defineNormalizeMorphedDirection(scope) {
+        const pb = scope.$builder;
+        const funcName = 'Z_normalizeMorphedDirection';
+        pb.func(funcName, [
+            pb.vec3('base'),
+            pb.vec3('delta')
+        ], function() {
+            this.$l.morphed = pb.add(this.base, this.delta);
+            this.$l.lengthSquared = pb.dot(this.morphed, this.morphed);
+            this.$if(pb.greaterThan(this.lengthSquared, 1e-6), function() {
+                this.$return(pb.mul(this.morphed, pb.inverseSqrt(this.lengthSquared)));
+            });
+            this.$l.baseLengthSquared = pb.dot(this.base, this.base);
+            this.$if(pb.greaterThan(this.baseLengthSquared, 1e-6), function() {
+                this.$return(pb.mul(this.base, pb.inverseSqrt(this.baseLengthSquared)));
+            });
+            this.$return(pb.vec3(0, 0, 1));
+        });
+        return funcName;
+    }
+    /**
+   * Mixes morph directions according to the amount of positional deformation
+   * contributed by each active target. This avoids letting a target with a
+   * large authored normal delta dominate a target that actually moves the
+   * surface much farther at the current vertex.
+   *
+   * The additive result remains the fallback for assets without position
+   * morph data, and for vertices whose position deltas are all zero.
+   * @internal
+   */ static calculateMorphDirectionByDisplacement(scope, base, attrib) {
+        const pb = scope.$builder;
+        const isWebGL1 = pb.getDevice().type === 'webgl';
+        if (pb.shaderKind !== 'vertex') {
+            throw new Error(`ShaderHelper.calculateMorphDirectionByDisplacement(): must be called at vertex stage`);
+        }
+        const that = this;
+        const funcName = 'Z_calculateMorphDirectionByDisplacement';
+        const normalizeName = this.defineNormalizeMorphedDirection(scope);
+        pb.func(funcName, [
+            pb.vec3('base'),
+            pb.int('directionOffset'),
+            pb.int('positionOffset')
+        ], function() {
+            this.$l.vertexIndex = isWebGL1 ? pb.int(scope.$inputs.zFakeVertexID) : pb.int(scope.$builtins.vertexIndex);
+            const morphInfo = scope[that.getMorphInfoUniformName()];
+            this.$l.metaData = pb.ivec4(morphInfo[0]);
+            this.$l.texWidth = pb.float(this.metaData.x);
+            this.$l.texHeight = pb.float(this.metaData.y);
+            this.$l.numVertices = this.metaData.z;
+            this.$l.numTargets = this.metaData.w;
+            this.$l.directionDelta = pb.vec3(0);
+            this.$l.weightedDirection = pb.vec3(0);
+            this.$l.weightSum = pb.float(0);
+            const accumulateTarget = (targetScope)=>{
+                targetScope.$if(pb.notEqual(targetScope.weight, 0), function() {
+                    this.$l.targetIndex = pb.int(targetScope['targetIndex']);
+                    this.$l.positionValue = pb.vec3(0);
+                    this.$l.directionValue = pb.vec3(0);
+                    this.$if(pb.greaterThanEqual(targetScope['directionOffset'], 0), function() {
+                        this.$l.pixelIndex = pb.float(pb.add(targetScope['directionOffset'], pb.mul(this.targetIndex, targetScope['numVertices']), targetScope['vertexIndex']));
+                        this.$l.xIndex = pb.mod(this.pixelIndex, targetScope['texWidth']);
+                        this.$l.yIndex = pb.floor(pb.div(this.pixelIndex, targetScope['texWidth']));
+                        this.$l.u = pb.div(pb.add(this.xIndex, 0.5), targetScope['texWidth']);
+                        this.$l.v = pb.div(pb.add(this.yIndex, 0.5), targetScope['texHeight']);
+                        this.directionValue = pb.textureSampleLevel(scope[that.getMorphDataUniformName()], pb.vec2(this.u, this.v), 0).xyz;
+                    });
+                    this.$if(pb.greaterThanEqual(targetScope['positionOffset'], 0), function() {
+                        this.$l.pixelIndex = pb.float(pb.add(targetScope['positionOffset'], pb.mul(this.targetIndex, targetScope['numVertices']), targetScope['vertexIndex']));
+                        this.$l.xIndex = pb.mod(this.pixelIndex, targetScope['texWidth']);
+                        this.$l.yIndex = pb.floor(pb.div(this.pixelIndex, targetScope['texWidth']));
+                        this.$l.u = pb.div(pb.add(this.xIndex, 0.5), targetScope['texWidth']);
+                        this.$l.v = pb.div(pb.add(this.yIndex, 0.5), targetScope['texHeight']);
+                        this.positionValue = pb.textureSampleLevel(scope[that.getMorphDataUniformName()], pb.vec2(this.u, this.v), 0).xyz;
+                    });
+                    this.directionDelta = pb.add(this.directionDelta, pb.mul(this.directionValue, targetScope.weight));
+                    this.$l.targetDirection = scope.$g[normalizeName](this.base, pb.mul(this.directionValue, targetScope.weight));
+                    this.$l.displacementWeight = pb.mul(pb.abs(targetScope.weight), pb.sqrt(pb.dot(this.positionValue, this.positionValue)));
+                    this.weightedDirection = pb.add(this.weightedDirection, pb.mul(this.targetDirection, this.displacementWeight));
+                    this.weightSum = pb.add(this.weightSum, this.displacementWeight);
+                });
+            };
+            if (isWebGL1) {
+                this.$for(pb.int('i'), 0, MORPH_WEIGHTS_VECTOR_COUNT, function() {
+                    this.$for(pb.int('j'), 0, 4, function() {
+                        this.$l.index = pb.add(pb.mul(this.i, 4), this.j);
+                        this.$if(pb.greaterThanEqual(this.index, this.numTargets), function() {
+                            this.$break();
+                        });
+                        this.$l.weight = morphInfo.at(pb.add(1, this.i)).at(this.j);
+                        this.$l.targetIndex = pb.int(morphInfo.at(pb.add(1 + MORPH_WEIGHTS_VECTOR_COUNT, this.i)).at(this.j));
+                        accumulateTarget(this);
+                    });
+                });
+            } else {
+                this.$for(pb.int('t'), 0, this.numTargets, function() {
+                    this.$l.i = pb.sar(this.t, 2);
+                    this.$l.j = pb.compAnd(this.t, 3);
+                    this.$l.weight = morphInfo.at(pb.add(1, this.i)).at(this.j);
+                    this.$l.targetIndex = pb.int(morphInfo.at(pb.add(1 + MORPH_WEIGHTS_VECTOR_COUNT, this.i)).at(this.j));
+                    accumulateTarget(this);
+                });
+            }
+            this.$l.fallback = scope.$g[normalizeName](this.base, this.directionDelta);
+            this.$if(pb.lessThan(this.weightSum, 1e-6), function() {
+                this.$return(this.fallback);
+            });
+            this.$l.weightedLengthSquared = pb.dot(this.weightedDirection, this.weightedDirection);
+            this.$if(pb.greaterThan(this.weightedLengthSquared, 1e-6), function() {
+                this.$return(pb.mul(this.weightedDirection, pb.inverseSqrt(this.weightedLengthSquared)));
+            });
+            this.$return(this.fallback);
+        });
+        const directionPos = 1 + MORPH_WEIGHTS_VECTOR_COUNT * 2 + (attrib >> 2);
+        const directionComp = attrib & 3;
+        const positionPos = 1 + MORPH_WEIGHTS_VECTOR_COUNT * 2 + (MORPH_TARGET_POSITION >> 2);
+        const positionComp = MORPH_TARGET_POSITION & 3;
+        const morphInfo = scope[this.getMorphInfoUniformName()];
+        return scope.$g[funcName](base.xyz, pb.int(morphInfo[directionPos][directionComp]), pb.int(morphInfo[positionPos][positionComp]));
+    }
+    /** @internal */ static orthogonalizeMorphedTangent(scope, normal, tangent) {
+        const pb = scope.$builder;
+        const funcName = 'Z_orthogonalizeMorphedTangent';
+        pb.func(funcName, [
+            pb.vec3('normal'),
+            pb.vec3('tangent')
+        ], function() {
+            this.$l.normalLengthSquared = pb.dot(this.normal, this.normal);
+            this.$if(pb.greaterThan(this.normalLengthSquared, 1e-6), function() {
+                this.$l.n = pb.mul(this.normal, pb.inverseSqrt(this.normalLengthSquared));
+                this.$l.projected = pb.sub(this.tangent, pb.mul(this.n, pb.dot(this.n, this.tangent)));
+                this.$l.tangentLengthSquared = pb.dot(this.projected, this.projected);
+                this.$if(pb.greaterThan(this.tangentLengthSquared, 1e-6), function() {
+                    this.$return(pb.mul(this.projected, pb.inverseSqrt(this.tangentLengthSquared)));
+                });
+            });
+            this.$return(this.tangent);
+        });
+        return scope.$g[funcName](normal.xyz, tangent.xyz);
+    }
     /** @internal */ static prepareSkinAnimation(scope) {
         if (!this.hasSkinning(scope)) {
             return;
         }
         const that = this;
         const pb = scope.$builder;
+        const isWebGL = pb.getDevice().type === 'webgl';
+        const supportsTextureLoad = !isWebGL;
         const funcNameGetBoneMatrixFromTexture = 'Z_getBoneMatrixFromTexture';
         pb.func(funcNameGetBoneMatrixFromTexture, [
             pb.float('boneIndex'),
@@ -461,6 +663,33 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             this.$l.m2 = scope.$g[funcNameGetBoneMatrixFromTexture](blendIndices[2], this.boneOffset);
             this.$l.m3 = scope.$g[funcNameGetBoneMatrixFromTexture](blendIndices[3], this.boneOffset);
             this.$l.m = pb.add(pb.mul(this.m0, blendWeights.x), pb.mul(this.m1, blendWeights.y), pb.mul(this.m2, blendWeights.z), pb.mul(this.m3, blendWeights.w));
+            this.$l.skinInfo = this[UNIFORM_NAME_SKIN_INFLUENCE_INFO];
+            this.$if(pb.greaterThan(this.skinInfo.z, 4), function() {
+                this.$l.vertexIndex = isWebGL ? pb.int(scope.$inputs.zFakeVertexID) : pb.int(scope.$builtins.vertexIndex);
+                this.$l.texWidth = pb.int(this.skinInfo.x);
+                this.$l.pairCount = pb.int(this.skinInfo.w);
+                this.$for(pb.int('pairIndex'), 0, MAX_SKIN_EXTRA_INFLUENCE_PAIRS, function() {
+                    this.$if(pb.greaterThanEqual(this.pairIndex, this.pairCount), function() {
+                        this.$break();
+                    });
+                    this.$l.pixelIndex = pb.add(pb.mul(this.vertexIndex, this.pairCount), this.pairIndex);
+                    this.$l.xIndex = pb.mod(this.pixelIndex, this.texWidth);
+                    this.$l.yIndex = pb.div(this.pixelIndex, this.texWidth);
+                    if (supportsTextureLoad) {
+                        this.$l.extra = pb.textureLoad(this[UNIFORM_NAME_SKIN_INFLUENCE_DATA], pb.ivec2(this.xIndex, this.yIndex), 0);
+                    } else {
+                        this.$l.u = pb.div(pb.add(pb.float(this.xIndex), 0.5), this.skinInfo.x);
+                        this.$l.v = pb.div(pb.add(pb.float(this.yIndex), 0.5), this.skinInfo.y);
+                        this.$l.extra = pb.textureSampleLevel(this[UNIFORM_NAME_SKIN_INFLUENCE_DATA], pb.vec2(this.u, this.v), 0);
+                    }
+                    this.$if(pb.greaterThan(this.extra.y, 0), function() {
+                        this.m = pb.add(this.m, pb.mul(scope.$g[funcNameGetBoneMatrixFromTexture](this.extra.x, this.boneOffset), this.extra.y));
+                    });
+                    this.$if(pb.greaterThan(this.extra.w, 0), function() {
+                        this.m = pb.add(this.m, pb.mul(scope.$g[funcNameGetBoneMatrixFromTexture](this.extra.z, this.boneOffset), this.extra.w));
+                    });
+                });
+            });
             this.$return(pb.mul(invBindMatrix, this.m));
         });
         const motionVector = !!this.getUnjitteredViewProjectionMatrix(scope);
@@ -471,12 +700,12 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             scope.$l[that.SKIN_PREV_MATRIX_NAME] = scope[funcNameGetSkinningMatrix](scope[that.SKIN_BONE_OFFSET].y);
         }
     }
-    /**
-   * Calculates the vertex position of type vec3 in object space
-   *
-   * @param scope - Current shader scope
-   * @param skinMatrix - The skinning matrix if there is skeletal animation, otherwise null
-   * @returns The calculated vertex position in object space, or null if pos is null
+    /**
+   * Calculates the vertex position of type vec3 in object space
+   *
+   * @param scope - Current shader scope
+   * @param skinMatrix - The skinning matrix if there is skeletal animation, otherwise null
+   * @returns The calculated vertex position in object space, or null if pos is null
    */ static resolveVertexPosition(scope) {
         const pb = scope.$builder;
         if (pb.shaderKind !== 'vertex') {
@@ -518,12 +747,12 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         });
         return scope[that.SKIN_MATRIX_NAME] && scope[that.SKIN_PREV_MATRIX_NAME] ? scope.Z_resolveVertexPosition(scope[that.SKIN_MATRIX_NAME], scope[that.SKIN_PREV_MATRIX_NAME]) : scope[that.SKIN_MATRIX_NAME] ? scope.Z_resolveVertexPosition(scope[that.SKIN_MATRIX_NAME]) : scope.Z_resolveVertexPosition();
     }
-    /**
-   * Resolve motion vector
-   *
-   * @param scope - Current shader scope
-   * @param worldPos - Current object position in world space
-   * @param prevWorldPos - Previous object position in world space
+    /**
+   * Resolve motion vector
+   *
+   * @param scope - Current shader scope
+   * @param worldPos - Current object position in world space
+   * @param prevWorldPos - Previous object position in world space
    */ static resolveMotionVector(scope, worldPos, prevWorldPos) {
         const that = this;
         const pb = scope.$builder;
@@ -534,13 +763,26 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             scope.$outputs.zMotionVectorPosPrev = pb.mul(prevUnjitteredVPMatrix, pb.vec4(prevWorldPos.xyz, 1));
         }
     }
-    /**
-   * Calculates the normal vector of type vec3 in object space
-   *
-   * @param scope - Current shader scope
-   * @param normal - Vertex normal input, must be type of vec3, null if no vertex normal input
-   * @param skinMatrix - The skinning matrix if there is skeletal animation, otherwise null
-   * @returns The calculated normal vector in object space, or null if normal is null
+    /**
+   * Gets the skinning matrix in the vertex shader, if the mesh being drawn is skinned.
+   *
+   * @remarks
+   * Lets a material apply the same skinning transform to its own uniform-supplied
+   * object-space vectors that {@link ShaderHelper.resolveVertexNormal} applies to
+   * the normal attribute, so such vectors stay attached to the deforming mesh.
+   *
+   * @param scope - Current shader scope, must be vertex stage
+   * @returns The skinning matrix of type mat4, or null when the mesh is not skinned
+   */ static getSkinMatrix(scope) {
+        return scope[this.SKIN_MATRIX_NAME] ?? null;
+    }
+    /**
+   * Calculates the normal vector of type vec3 in object space
+   *
+   * @param scope - Current shader scope
+   * @param normal - Vertex normal input, must be type of vec3, null if no vertex normal input
+   * @param skinMatrix - The skinning matrix if there is skeletal animation, otherwise null
+   * @returns The calculated normal vector in object space, or null if normal is null
    */ static resolveVertexNormal(scope, normal) {
         const pb = scope.$builder;
         if (pb.shaderKind !== 'vertex') {
@@ -550,6 +792,10 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         if (!funcScope || !funcScope.$isMain()) {
             throw new Error(`ShaderHelper.resolveVertexNormal(): must be called at entry function`);
         }
+        const useVertexAttrib = !normal;
+        if (useVertexAttrib && scope[this.RESOLVED_VERTEX_NORMAL_NAME]) {
+            return scope[this.RESOLVED_VERTEX_NORMAL_NAME];
+        }
         if (!normal) {
             if (!scope.$getVertexAttrib('normal')) {
                 scope.$inputs.Z_normal = pb.vec3().attrib('normal');
@@ -557,21 +803,25 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             normal = scope.$getVertexAttrib('normal');
         }
         if (this.hasMorphing(scope)) {
-            normal = pb.normalize(pb.add(normal, this.calculateMorphDelta(scope, MORPH_TARGET_NORMAL).xyz));
+            normal = this.calculateMorphDirectionByDisplacement(scope, normal, MORPH_TARGET_NORMAL);
         }
+        let resolvedNormal = normal;
         if (scope[this.SKIN_MATRIX_NAME]) {
-            return pb.mul(scope[this.SKIN_MATRIX_NAME], pb.vec4(normal, 0)).xyz;
-        } else {
-            return normal;
+            resolvedNormal = pb.mul(scope[this.SKIN_MATRIX_NAME], pb.vec4(normal, 0)).xyz;
         }
-    }
-    /**
-   * Calculates the tangent vector of type vec3 in object space
-   *
-   * @param scope - Current shader scope
-   * @param tangent - Vertex tangent input, must be type of vec4, null if no vertex tangent input
-   * @param skinMatrix - The skinning matrix if there is skeletal animation, otherwise null
-   * @returns The calculated tangent vector of type vec4 in object space, or null if tangent is null
+        if (useVertexAttrib) {
+            scope.$l[this.RESOLVED_VERTEX_NORMAL_NAME] = resolvedNormal;
+            resolvedNormal = scope[this.RESOLVED_VERTEX_NORMAL_NAME];
+        }
+        return resolvedNormal;
+    }
+    /**
+   * Calculates the tangent vector of type vec3 in object space
+   *
+   * @param scope - Current shader scope
+   * @param tangent - Vertex tangent input, must be type of vec4, null if no vertex tangent input
+   * @param skinMatrix - The skinning matrix if there is skeletal animation, otherwise null
+   * @returns The calculated tangent vector of type vec4 in object space, or null if tangent is null
    */ static resolveVertexTangent(scope, tangent) {
         const pb = scope.$builder;
         if (pb.shaderKind !== 'vertex') {
@@ -588,26 +838,29 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             tangent = scope.$getVertexAttrib('tangent');
         }
         if (this.hasMorphing(scope)) {
-            tangent = pb.normalize(pb.add(tangent, pb.vec4(this.calculateMorphDelta(scope, MORPH_TARGET_TANGENT).xyz, 0)));
+            tangent = pb.vec4(this.calculateMorphDirectionByDisplacement(scope, tangent.xyz, MORPH_TARGET_TANGENT), tangent.w);
         }
         if (scope[this.SKIN_MATRIX_NAME]) {
-            return pb.vec4(pb.mul(scope[this.SKIN_MATRIX_NAME], pb.vec4(tangent.xyz, 0)).xyz, tangent.w);
-        } else {
-            return tangent;
+            tangent = pb.vec4(pb.mul(scope[this.SKIN_MATRIX_NAME], pb.vec4(tangent.xyz, 0)).xyz, tangent.w);
+        }
+        if (this.hasMorphing(scope) && scope.$getVertexAttrib('normal')) {
+            const resolvedNormal = scope[this.RESOLVED_VERTEX_NORMAL_NAME] ?? this.resolveVertexNormal(scope);
+            tangent = pb.vec4(this.orthogonalizeMorphedTangent(scope, resolvedNormal, tangent.xyz), tangent.w);
         }
+        return tangent;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the world matrix of current object to be drawn
-   * @param scope - Current shader scope
-   * @returns The world matrix of current object to be drawn
+    /**
+   * Gets the uniform variable of type mat4 which holds the world matrix of current object to be drawn
+   * @param scope - Current shader scope
+   * @returns The world matrix of current object to be drawn
    */ static getWorldMatrix(scope) {
         const pb = scope.$builder;
         return scope[UNIFORM_NAME_WORLD_MATRIX] ?? pb.mat4(this.getInstancedUniform(scope, 0), this.getInstancedUniform(scope, 1), this.getInstancedUniform(scope, 2), this.getInstancedUniform(scope, 3));
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the world matrix at previous frame of current object to be drawn
-   * @param scope - Current shader scope
-   * @returns The world matrix at previous frame of current object to be drawn
+    /**
+   * Gets the uniform variable of type mat4 which holds the world matrix at previous frame of current object to be drawn
+   * @param scope - Current shader scope
+   * @returns The world matrix at previous frame of current object to be drawn
    */ static getPrevWorldMatrix(scope) {
         const pb = scope.$builder;
         const that = this;
@@ -638,28 +891,28 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             return scope.Z_getPrevWorldMatrix(framestamp);
         }
     }
-    /**
-   * Gets the instance uniform value of type vec4 by uniform index
-   * @param scope - Current shader scope
-   * @returns instance uniform value
+    /**
+   * Gets the instance uniform value of type vec4 by uniform index
+   * @param scope - Current shader scope
+   * @returns instance uniform value
    */ static getInstancedUniform(scope, uniformIndex) {
         const pb = scope.$builder;
         return scope[UNIFORM_NAME_INSTANCE_DATA].at(pb.add(pb.mul(scope[UNIFORM_NAME_INSTANCE_DATA_STRIDE], pb.uint(scope.$builtins.instanceIndex)), scope[UNIFORM_NAME_INSTANCE_DATA_OFFSET], pb.uint(uniformIndex)));
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the normal matrix of current object to be drawn
-   *
-   * @param scope - Current shader scope
-   * @returns The normal matrix of current object to be drawn
+    /**
+   * Gets the uniform variable of type mat4 which holds the normal matrix of current object to be drawn
+   *
+   * @param scope - Current shader scope
+   * @returns The normal matrix of current object to be drawn
    */ static getNormalMatrix(scope) {
         return this.getWorldMatrix(scope);
     }
-    /**
-   * Vertex shader drawable stuff
-   *
-   * @param scope - Current shader scope
-   * @param skinning - true if skinning is used, otherwise false.
-   * @param instanced - true if instancing is used, otherwise false.
+    /**
+   * Vertex shader drawable stuff
+   *
+   * @param scope - Current shader scope
+   * @param skinning - true if skinning is used, otherwise false.
+   * @param instanced - true if instancing is used, otherwise false.
    */ static vertexShaderDrawableStuff(scope, skinning, morphing, instanced) {
         const pb = scope.$builder;
         if (instanced) {
@@ -676,10 +929,12 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             scope[UNIFORM_NAME_BONE_MATRICES] = pb.tex2D().uniform(1).sampleType('unfilterable-float');
             scope[UNIFORM_NAME_BONE_INV_BIND_MATRIX] = pb.mat4().uniform(1);
             scope[UNIFORM_NAME_BONE_TEXTURE_SIZE] = pb.vec2().uniform(1);
+            scope[UNIFORM_NAME_SKIN_INFLUENCE_DATA] = pb.tex2D().uniform(1).sampleType('unfilterable-float');
+            scope[UNIFORM_NAME_SKIN_INFLUENCE_INFO] = pb.vec4().uniform(1);
         }
         if (morphing) {
             scope[UNIFORM_NAME_MORPH_DATA] = pb.tex2D().uniform(1).sampleType('unfilterable-float');
-            scope[UNIFORM_NAME_MORPH_INFO] = pb.vec4[1 + MORPH_WEIGHTS_VECTOR_COUNT + MORPH_ATTRIBUTE_VECTOR_COUNT]().uniformBuffer(1);
+            scope[UNIFORM_NAME_MORPH_INFO] = pb.vec4[1 + MORPH_WEIGHTS_VECTOR_COUNT * 2 + MORPH_ATTRIBUTE_VECTOR_COUNT]().uniformBuffer(1);
         }
     }
     /** @internal */ static prepareVertexShaderCommon(pb, ctx) {
@@ -735,8 +990,10 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 directionCutoff: light.directionAndCutoff,
                 viewMatrix: light.viewMatrix,
                 depthBias: shadowMapParams.depthBiasValues[0],
+                implParams: shadowMapParams.impl.getParams(this._lightUniformShadow.implParams),
                 lightType: light.lightType
             });
+            shadowMapParams.impl?.applyCasterUniforms(bindGroup, shadowMapParams);
         }
     }
     /** @internal */ static setFogUniforms(bindGroup, withAerialPerspective, fogType, additive, atmosphereParams, heightFogParams, aerialPerspectiveLUT, skyDistantLightLUT) {
@@ -749,57 +1006,57 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         bindGroup.setTexture(UNIFORM_NAME_AERIALPERSPECTIVE_LUT, aerialPerspectiveLUT);
         bindGroup.setTexture(UNIFORM_NAME_SKYDISTANTLIGHT_LUT, skyDistantLightLUT);
     }
-    /**
-   * @internal
-   *
-   * Camera pre-exposure factor for scene-linear lighting quantities.
-   *
-   * @remarks
-   * Physical lighting authors light intensities in photometric units (lux, candela, cd/m²), whose
-   * magnitudes (~1e5 for daylight) neither fit an rgba16f render target nor leave usable headroom
-   * for specular highlights. Following Filament, the camera exposure is folded into every light
-   * quantity on the CPU so the HDR target stays near 1.0 and downstream passes need no unit
-   * awareness. Legacy returns 1 so its uploads stay byte-identical.
+    /**
+   * @internal
+   *
+   * Camera pre-exposure factor for scene-linear lighting quantities.
+   *
+   * @remarks
+   * Physical lighting authors light intensities in photometric units (lux, candela, cd/m²), whose
+   * magnitudes (~1e5 for daylight) neither fit an rgba16f render target nor leave usable headroom
+   * for specular highlights. Following Filament, the camera exposure is folded into every light
+   * quantity on the CPU so the HDR target stays near 1.0 and downstream passes need no unit
+   * awareness. Legacy returns 1 so its uploads stay byte-identical.
    */ static getPreExposure(ctx) {
         return ctx.scene.lightingMode === 'physical' ? ctx.camera.exposure : 1;
     }
-    /**
-   * @internal
-   *
-   * Light color/intensity vector with the camera pre-exposure folded into the intensity component.
-   *
-   * @remarks
-   * Only the intensity (`w`) is scaled; the color stays untouched, matching Filament's
-   * `FScene::prepareDynamicLights`. The light's own cached vector is never mutated because it is
-   * shared across every camera rendering the scene.
+    /**
+   * @internal
+   *
+   * Light color/intensity vector with the camera pre-exposure folded into the intensity component.
+   *
+   * @remarks
+   * Only the intensity (`w`) is scaled; the color stays untouched, matching Filament's
+   * `FScene::prepareDynamicLights`. The light's own cached vector is never mutated because it is
+   * shared across every camera rendering the scene.
    */ static getPreExposedColorIntensity(light, ctx, out) {
         const src = light.diffuseAndIntensity;
         const result = out ?? new Vector4();
         result.setXYZW(src.x, src.y, src.z, src.w * this.getPreExposure(ctx));
         return result;
     }
-    /**
-   * @internal
-   *
-   * Environment lighting scale uploaded as `light.envLightStrength`.
-   *
-   * @remarks
-   * Legacy uses the unitless {@link EnvLightWrapper.strength}.
-   *
-   * Physical returns the ratio that converts the cached sky bake from its fixed storage exposure
-   * (`SkyRenderer.PHYSICAL_BAKE_EXPOSURE`) to the live camera exposure. Every environment source is
-   * normalized into that one space before it reaches the IBL -- the scattering atmosphere emits
-   * photometric luminance, authored 0..1 skyboxes/panoramas are lifted by
-   * {@link EnvLightWrapper.intensity} -- so no pass consuming `envLightStrength` has to know the
-   * sky type.
-   *
-   * The bake cannot simply hold raw cd/m²: the environment cubemap is `rg11b10uf`/`rgba16f` and a
-   * daylight sun overflows it to Inf, which `prefilterCubemap` then spreads across the whole IBL.
-   *
-   * {@link EnvLightWrapper.strength} multiplies the result in both modes. It is the only per-frame
-   * dimmer for environment lighting: the photometric `intensity` reaches the image solely through
-   * the cached bake, and a `scatter` sky does not even consult it (its brightness comes from the
-   * sun), so without this factor there would be no way to turn the IBL down without re-baking.
+    /**
+   * @internal
+   *
+   * Environment lighting scale uploaded as `light.envLightStrength`.
+   *
+   * @remarks
+   * Legacy uses the unitless {@link EnvLightWrapper.strength}.
+   *
+   * Physical returns the ratio that converts the cached sky bake from its fixed storage exposure
+   * (`SkyRenderer.PHYSICAL_BAKE_EXPOSURE`) to the live camera exposure. Every environment source is
+   * normalized into that one space before it reaches the IBL -- the scattering atmosphere emits
+   * photometric luminance, authored 0..1 skyboxes/panoramas are lifted by
+   * {@link EnvLightWrapper.intensity} -- so no pass consuming `envLightStrength` has to know the
+   * sky type.
+   *
+   * The bake cannot simply hold raw cd/m²: the environment cubemap is `rg11b10uf`/`rgba16f` and a
+   * daylight sun overflows it to Inf, which `prefilterCubemap` then spreads across the whole IBL.
+   *
+   * {@link EnvLightWrapper.strength} multiplies the result in both modes. It is the only per-frame
+   * dimmer for environment lighting: the photometric `intensity` reaches the image solely through
+   * the cached bake, and a `scatter` sky does not even consult it (its brightness comes from the
+   * sun), so without this factor there would be no way to turn the IBL down without re-baking.
    */ static getEnvLightLuminance(ctx) {
         const env = ctx.env;
         if (!env) {
@@ -862,174 +1119,174 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             ctx.env.light.envLight.updateBindGroup(bindGroup, ctx);
         }
     }
-    /**
-   * Gets the uniform variable of type float which holds the strength of the environment light
-   *
-   * @remarks
-   * This function can only be used in the fragment shader
-   *
-   * @param scope - Current shader scope
-   * @returns The uniform variable of which presents the strength of the environment light
+    /**
+   * Gets the uniform variable of type float which holds the strength of the environment light
+   *
+   * @remarks
+   * This function can only be used in the fragment shader
+   *
+   * @param scope - Current shader scope
+   * @returns The uniform variable of which presents the strength of the environment light
    */ static getEnvLightStrength(scope) {
         return scope.light.envLightStrength;
     }
-    /**
-   * Gets the uniform variable of type float which holds the specular strength of the environment light
-   *
-   * @remarks
-   * This function can only be used in the fragment shader
-   *
-   * @param scope - Current shader scope
-   * @returns The uniform variable which presents the specular strength of the environment light
+    /**
+   * Gets the uniform variable of type float which holds the specular strength of the environment light
+   *
+   * @remarks
+   * This function can only be used in the fragment shader
+   *
+   * @param scope - Current shader scope
+   * @returns The uniform variable which presents the specular strength of the environment light
    */ static getEnvLightSpecularStrength(scope) {
         return scope.light.envLightSpecularStrength ?? scope.$builder.float(1);
     }
-    /**
-   * Gets current scene color texture
-   * @param scope - Current shader scope
-   * @returns current scene color texture
+    /**
+   * Gets current scene color texture
+   * @param scope - Current shader scope
+   * @returns current scene color texture
    */ static getSceneColorTexture(scope) {
         return scope[UNIFORM_NAME_SCENE_COLOR_MAP];
     }
-    /**
-   * Gets the size of current scene color texture
-   * @param scope - Current shader scope
-   * @returns The size of current scene color texture
+    /**
+   * Gets the size of current scene color texture
+   * @param scope - Current shader scope
+   * @returns The size of current scene color texture
    */ static getSceneColorTextureSize(scope) {
         return scope[UNIFORM_NAME_SCENE_COLOR_MAP_SIZE];
     }
-    /**
-   * Gets current linear depth texture
-   * @param scope - Current shader scope
-   * @returns current linear depth texture
+    /**
+   * Gets current linear depth texture
+   * @param scope - Current shader scope
+   * @returns current linear depth texture
    */ static getLinearDepthTexture(scope) {
         return scope[UNIFORM_NAME_LINEAR_DEPTH_MAP];
     }
-    /**
-   * Gets the size of current linear depth texture
-   * @param scope - Current shader scope
-   * @returns The size of current linear depth texture
+    /**
+   * Gets the size of current linear depth texture
+   * @param scope - Current shader scope
+   * @returns The size of current linear depth texture
    */ static getLinearDepthTextureSize(scope) {
         return scope[UNIFORM_NAME_LINEAR_DEPTH_MAP_SIZE];
     }
-    /**
-   * Gets current HiZ depth texture
-   * @param scope - Current shader scope
-   * @returns current HiZ depth texture
+    /**
+   * Gets current HiZ depth texture
+   * @param scope - Current shader scope
+   * @returns current HiZ depth texture
    */ static getHiZDepthTexture(scope) {
         return scope[UNIFORM_NAME_HIZ_DEPTH_MAP];
     }
-    /**
-   * Gets the size of current HiZ depth texture
-   * @param scope - Current shader scope
-   * @returns The size of current HiZ depth texture
+    /**
+   * Gets the size of current HiZ depth texture
+   * @param scope - Current shader scope
+   * @returns The size of current HiZ depth texture
    */ static getHiZDepthTextureSize(scope) {
         return scope[UNIFORM_NAME_HIZ_DEPTH_MAP_INFO].xy;
     }
-    /**
-   * Gets the mipmap levels count of current HiZ depth texture
-   * @param scope - Current shader scope
-   * @returns The mipmap levels count of current HiZ depth texture
+    /**
+   * Gets the mipmap levels count of current HiZ depth texture
+   * @param scope - Current shader scope
+   * @returns The mipmap levels count of current HiZ depth texture
    */ static getHiZDepthTextureMipLevelCount(scope) {
         return scope[UNIFORM_NAME_HIZ_DEPTH_MAP_INFO].z;
     }
-    /**
-   * Gets current baked skybox texture
-   * @param scope - Current shader scope
-   * @returns current baked skybox texture
+    /**
+   * Gets current baked skybox texture
+   * @param scope - Current shader scope
+   * @returns current baked skybox texture
    */ static getBakedSkyTexture(scope) {
         return scope[UNIFORM_NAME_BAKED_SKY_MAP];
     }
-    /**
-   * Samples the baked sky cubemap in the same pre-exposed space as the scene color buffer.
-   *
-   * @remarks
-   * The bake is cached and therefore exposure-independent, stored at the fixed
-   * `PHYSICAL_BAKE_EXPOSURE`. Anything that blends it against already-pre-exposed lit color (water
-   * reflection, blueprint sky lookups) must first convert it to the live exposure.
-   * `envLightStrength` carries exactly that ratio in physical mode, and the legacy environment
-   * strength (its established meaning) otherwise.
-   *
-   * @param scope - Current shader scope
-   * @param direction - Sampling direction
-   * @returns Pre-exposed sky radiance
+    /**
+   * Samples the baked sky cubemap in the same pre-exposed space as the scene color buffer.
+   *
+   * @remarks
+   * The bake is cached and therefore exposure-independent, stored at the fixed
+   * `PHYSICAL_BAKE_EXPOSURE`. Anything that blends it against already-pre-exposed lit color (water
+   * reflection, blueprint sky lookups) must first convert it to the live exposure.
+   * `envLightStrength` carries exactly that ratio in physical mode, and the legacy environment
+   * strength (its established meaning) otherwise.
+   *
+   * @param scope - Current shader scope
+   * @param direction - Sampling direction
+   * @returns Pre-exposed sky radiance
    */ static sampleBakedSkyPreExposed(scope, direction) {
         const pb = scope.$builder;
         return pb.mul(pb.textureSampleLevel(this.getBakedSkyTexture(scope), direction, 0).rgb, this.getEnvLightStrength(scope));
     }
-    /**
-   * Gets the camera pre-exposure factor.
-   *
-   * @remarks
-   * The multiplier every photometric quantity is scaled by before it reaches the HDR target. 1 in
-   * legacy. Use it for material-authored emitters (emissive), which are not covered by the CPU-side
-   * light pre-exposure.
-   *
-   * @param scope - Current shader scope
-   * @returns The pre-exposure factor
+    /**
+   * Gets the camera pre-exposure factor.
+   *
+   * @remarks
+   * The multiplier every photometric quantity is scaled by before it reaches the HDR target. 1 in
+   * legacy. Use it for material-authored emitters (emissive), which are not covered by the CPU-side
+   * light pre-exposure.
+   *
+   * @param scope - Current shader scope
+   * @returns The pre-exposure factor
    */ static getPreExposureUniform(scope) {
         return scope.camera.preExposure;
     }
-    /**
-   * Gets the elapsed time in seconds
-   * @param scope - Current shader scope
-   * @returns The elapsed time in seconds
+    /**
+   * Gets the elapsed time in seconds
+   * @param scope - Current shader scope
+   * @returns The elapsed time in seconds
    */ static getElapsedTime(scope) {
         return scope.camera.elapsedTime;
     }
-    /**
-   * Gets the elapsed time since last frame in seconds
-   * @param scope - Current shader scope
-   * @returns The elapsed time since last frame in seconds
+    /**
+   * Gets the elapsed time since last frame in seconds
+   * @param scope - Current shader scope
+   * @returns The elapsed time since last frame in seconds
    */ static getElapsedTimeFrame(scope) {
         return scope.camera.frameDeltaTime;
     }
-    /**
-   * Gets the uniform variable of type vec3 which holds the camera position
-   * @param scope - Current shader scope
-   * @returns The camera position
+    /**
+   * Gets the uniform variable of type vec3 which holds the camera position
+   * @param scope - Current shader scope
+   * @returns The camera position
    */ static getCameraPosition(scope) {
         return scope.camera.position.xyz;
     }
-    /**
-   * Gets the uniform variable of type float which holds the roughness factor
-   * @param scope - Current shader scope
-   * @returns The roughness factor
+    /**
+   * Gets the uniform variable of type float which holds the roughness factor
+   * @param scope - Current shader scope
+   * @returns The roughness factor
    */ static getCameraRoughnessFactor(scope) {
         return scope.camera.roughnessFactor;
     }
-    /**
-   * Gets framebuffer size for rendering
-   * @param scope - Current shader scope
-   * @returns The roughness factor
+    /**
+   * Gets framebuffer size for rendering
+   * @param scope - Current shader scope
+   * @returns The roughness factor
    */ static getRenderSize(scope) {
         return scope.camera.renderSize;
     }
-    /**
-   * Gets the uniform variable of type uint which holds the framestamp
-   * @param scope - Current shader scope
-   * @returns The framestamp
+    /**
+   * Gets the uniform variable of type uint which holds the framestamp
+   * @param scope - Current shader scope
+   * @returns The framestamp
    */ static getFramestamp(scope) {
         return scope.camera.framestamp;
     }
-    /**
-   * Gets the clip plane flag
-   * @param scope - Current shader scope
-   * @returns A float value of 1 indices the clip plane presents, otherwise 0
+    /**
+   * Gets the clip plane flag
+   * @param scope - Current shader scope
+   * @returns A float value of 1 indices the clip plane presents, otherwise 0
    */ static getCameraClipPlaneFlag(scope) {
         return scope.camera.position.w;
     }
-    /**
-   * Gets the clip plane
-   * @param scope - Current shader scope
-   * @returns A vec4 presents the clip plane
+    /**
+   * Gets the clip plane
+   * @param scope - Current shader scope
+   * @returns A vec4 presents the clip plane
    */ static getCameraClipPlane(scope) {
         return scope.camera.clipPlane;
     }
-    /**
-   * Gets the uniform variable of type vec4 which holds the camera parameters
-   * @param scope - Current shader scope
-   * @returns The camera parameters
+    /**
+   * Gets the uniform variable of type vec4 which holds the camera parameters
+   * @param scope - Current shader scope
+   * @returns The camera parameters
    */ static getCameraParams(scope) {
         return scope.camera.params;
     }
@@ -1039,36 +1296,36 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     /** @internal */ static getCountParams(scope) {
         return scope.light.countParams;
     }
-    /**
-   * Number of shadow-casting lights at the head of the clustered light buffer.
-   * Only defined on the screen-space shadow mask path (ctx.screenSpaceShadowMask);
-   * a clustered light whose buffer index is `<= N` samples the shadow mask.
-   * @internal
+    /**
+   * Number of shadow-casting lights at the head of the clustered light buffer.
+   * Only defined on the screen-space shadow mask path (ctx.screenSpaceShadowMask);
+   * a clustered light whose buffer index is `<= N` samples the shadow mask.
+   * @internal
    */ static getNumShadowLights(scope) {
         return scope.light.numShadowLights;
     }
-    /**
-   * Cluster shadow-mask mode for the current queue: 1 = sample the opaque shadow
-   * mask for shadow lights; 0 = skip shadow lights (they are lit inline by the
-   * additive passes, used for the transparent queue). Only defined on the
-   * screen-space shadow mask path.
-   * @internal
+    /**
+   * Cluster shadow-mask mode for the current queue: 1 = sample the opaque shadow
+   * mask for shadow lights; 0 = skip shadow lights (they are lit inline by the
+   * additive passes, used for the transparent queue). Only defined on the
+   * screen-space shadow mask path.
+   * @internal
    */ static getShadowMaskMode(scope) {
         return scope[UNIFORM_NAME_SHADOW_MASK_MODE];
     }
-    /**
-   * Bind the per-queue cluster shadow-mask mode. Call in the clustered light pass
-   * only when the screen-space shadow mask path is active.
-   * @internal
+    /**
+   * Bind the per-queue cluster shadow-mask mode. Call in the clustered light pass
+   * only when the screen-space shadow mask path is active.
+   * @internal
    */ static setShadowMaskMode(bindGroup, sampleMask) {
         bindGroup.setValue(UNIFORM_NAME_SHADOW_MASK_MODE, sampleMask ? 1 : 0);
     }
-    /**
-   * Lazily-created 1x1x1 rgba8unorm array texture used as the shadow-mask binding
-   * fallback when the screen-space shadow mask path is enabled but no mask was
-   * produced this frame (no shadow-casting lights). It is never sampled in that
-   * case, but the declared uniform still requires a valid binding.
-   * @internal
+    /**
+   * Lazily-created 1x1x1 rgba8unorm array texture used as the shadow-mask binding
+   * fallback when the screen-space shadow mask path is enabled but no mask was
+   * produced this frame (no shadow-casting lights). It is never sampled in that
+   * case, but the declared uniform still requires a valid binding.
+   * @internal
    */ static getDummyShadowMask(device) {
         let tex = this._dummyShadowMask;
         if (!tex || tex.disposed) {
@@ -1083,22 +1340,22 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     /** @internal */ static getClusteredLightIndexTexture(scope) {
         return scope[UNIFORM_NAME_LIGHT_INDEX_TEXTURE];
     }
-    /**
-   * Clustered shadow factor for a light, in `[0,1]` (1 = fully lit).
-   *
-   * - Lights whose clustered buffer index is greater than `numShadowLights` are not
-   *   shadow-casters and return 1.0.
-   * - Shadow-casting lights on the opaque queue (shadow mask mode 1) return the
-   *   screen-space mask value. Layer/channel are derived from the zero-based light
-   *   ordinal `s = index-1`: `layer = s >> 2`, `channel = s & 3`, matching the
-   *   ShadowMaskPass packing.
-   * - Shadow-casting lights on a transparent queue (mode 0) return 0: their clustered
-   *   contribution is suppressed because they are lit inline by the additive passes,
-   *   where shadows are sampled at the true (transparent) surface depth rather than
-   *   from the opaque-depth mask.
-   *
-   * Only valid on the screen-space shadow mask path (ctx.screenSpaceShadowMask).
-   * @internal
+    /**
+   * Clustered shadow factor for a light, in `[0,1]` (1 = fully lit).
+   *
+   * - Lights whose clustered buffer index is greater than `numShadowLights` are not
+   *   shadow-casters and return 1.0.
+   * - Shadow-casting lights on the opaque queue (shadow mask mode 1) return the
+   *   screen-space mask value. Layer/channel are derived from the zero-based light
+   *   ordinal `s = index-1`: `layer = s >> 2`, `channel = s & 3`, matching the
+   *   ShadowMaskPass packing.
+   * - Shadow-casting lights on a transparent queue (mode 0) return 0: their clustered
+   *   contribution is suppressed because they are lit inline by the additive passes,
+   *   where shadows are sampled at the true (transparent) surface depth rather than
+   *   from the opaque-depth mask.
+   *
+   * Only valid on the screen-space shadow mask path (ctx.screenSpaceShadowMask).
+   * @internal
    */ static sampleShadowMask(scope, lightIndex) {
         const pb = scope.$builder;
         const that = this;
@@ -1125,87 +1382,87 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         });
         return pb.getGlobalScope()[funcName](lightIndex);
     }
-    /**
-   * Gets the uniform variable that contains atmosphere parameters
-   * @param scope - Current shader scope
-   * @returns The atmosphere parameters
+    /**
+   * Gets the uniform variable that contains atmosphere parameters
+   * @param scope - Current shader scope
+   * @returns The atmosphere parameters
    */ static getAtmosphereParams(scope) {
         return scope.fog.atmosphereParams;
     }
-    /**
-   * Gets the aerial perspective LUT
-   * @param scope - Current shader scope
-   * @returns The aerial perspective LUT texture
+    /**
+   * Gets the aerial perspective LUT
+   * @param scope - Current shader scope
+   * @returns The aerial perspective LUT texture
    */ static getAerialPerspectiveLUT(scope) {
         return scope[UNIFORM_NAME_AERIALPERSPECTIVE_LUT];
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the view projection matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The view projection matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the view projection matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The view projection matrix of current camera
    */ static getViewProjectionMatrix(scope) {
         return scope.camera.viewProjectionMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the inversed view projection matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The inversed view projection matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the inversed view projection matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The inversed view projection matrix of current camera
    */ static getInvViewProjectionMatrix(scope) {
         return scope.camera.invViewProjectionMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the projection matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The projection matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the projection matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The projection matrix of current camera
    */ static getProjectionMatrix(scope) {
         return scope.camera.projectionMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the inversed projection matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The inversed projection matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the inversed projection matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The inversed projection matrix of current camera
    */ static getInvProjectionMatrix(scope) {
         return scope.camera.invProjectionMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the unjittered view projection matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The unjittered view projection matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the unjittered view projection matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The unjittered view projection matrix of current camera
    */ static getUnjitteredViewProjectionMatrix(scope) {
         return scope.camera.unjitteredVPMatrix;
     }
-    /**
-   * Gets the uniform variable of type vec2 which holds the jitter value of the projection matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The jitter value of projection matrix of current camera
+    /**
+   * Gets the uniform variable of type vec2 which holds the jitter value of the projection matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The jitter value of projection matrix of current camera
    */ static getProjectionMatrixJitterValue(scope) {
         return scope.camera.jitterValue;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the jittered inversed view-projection matrix
-   * @param scope - Current shader scope
-   * @returns The jittered inversed view-projection matrix
+    /**
+   * Gets the uniform variable of type mat4 which holds the jittered inversed view-projection matrix
+   * @param scope - Current shader scope
+   * @returns The jittered inversed view-projection matrix
    */ static getJitteredInvVPMatrix(scope) {
         return scope.camera.jitteredInvVPMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the unjittered view projection at previous frame matrix of current camera
-   * @param scope - Current shader scope
-   * @returns The unjittered view projection matrix at previous frame of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the unjittered view projection at previous frame matrix of current camera
+   * @param scope - Current shader scope
+   * @returns The unjittered view projection matrix at previous frame of current camera
    */ static getPrevUnjitteredViewProjectionMatrix(scope) {
         return scope.camera.prevUnjitteredVPMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the view matrix of current camera (world space to camera space)
-   * @param scope - Current shader scope
-   * @returns The view matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the view matrix of current camera (world space to camera space)
+   * @param scope - Current shader scope
+   * @returns The view matrix of current camera
    */ static getViewMatrix(scope) {
         return scope.camera.viewMatrix;
     }
-    /**
-   * Gets the uniform variable of type mat4 which holds the inv-view matrix of current camera (camera space to world space)
-   * @param scope - Current shader scope
-   * @returns The inv-view matrix of current camera
+    /**
+   * Gets the uniform variable of type mat4 which holds the inv-view matrix of current camera (camera space to world space)
+   * @param scope - Current shader scope
+   * @returns The inv-view matrix of current camera
    */ static getInvViewMatrix(scope) {
         return scope.camera.worldMatrix;
     }
@@ -1259,20 +1516,20 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     /** @internal */ static getLightExtra(scope, lightIndex) {
         return scope[UNIFORM_NAME_LIGHT_BUFFER].at(scope.$builder.add(scope.$builder.mul(lightIndex, 4), 3));
     }
-    /**
-   * Sets the clip space position in vertex shader
-   *
-   * @remarks
-   * Use this function instead of using
-   * <pre>
-   * // Do not use this
-   * this.$builtins.position = some_value;
-   * // Use this
-   * ShaderFramework.setClipSpacePosition(some_value);
-   * </pre>,
-   *
-   * @param scope - Current shader scope
-   * @param pos - The clip space position to be set
+    /**
+   * Sets the clip space position in vertex shader
+   *
+   * @remarks
+   * Use this function instead of using
+   * <pre>
+   * // Do not use this
+   * this.$builtins.position = some_value;
+   * // Use this
+   * ShaderFramework.setClipSpacePosition(some_value);
+   * </pre>,
+   *
+   * @param scope - Current shader scope
+   * @param pos - The clip space position to be set
    */ static setClipSpacePosition(scope, pos) {
         const pb = scope.$builder;
         const cameraParams = this.getCameraParams(scope);
@@ -1282,27 +1539,76 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             scope.$builtins.position = pos;
         }
     }
-    /**
-   * Get shadow map uniform value
-   *
-   * @param scope - Shader scope
-   * @returns The shadow map texture uniform
+    /**
+   * Get shadow map uniform value
+   *
+   * @param scope - Shader scope
+   * @returns The shadow map texture uniform
    */ static getShadowMap(scope) {
         return scope[UNIFORM_NAME_SHADOW_MAP];
     }
-    /**
-   * Calculates shadow of current fragment
-   *
-   * @param scope - Shader scope
-   * @param NoL - NdotL vector
-   * @returns Shadow of current fragment, 1 means no shadow and 0 means full shadowed.
-   */ static calculateShadow(scope, worldPos, NoL, ctx) {
+    /**
+   * Per-cascade scale for both bias terms.
+   *
+   * @remarks
+   * Only `depthBiasValues[0]` is uploaded; every cascade's value is recovered by
+   * multiplying with this ratio. It is derived from the `.x` components, but
+   * since `.x` and the normal offset `.y` are both proportional to the cascade's
+   * texel world size, the same ratio applies to either.
+   * @internal
+   */ static getShadowCascadeBiasScale(scope, split) {
+        const pb = scope.$builder;
+        const splitFlags = pb.vec4(pb.float(pb.equal(split, 0)), pb.float(pb.equal(split, 1)), pb.float(pb.equal(split, 2)), pb.float(pb.equal(split, 3)));
+        return pb.dot(this.getDepthBiasScales(scope), splitFlags);
+    }
+    /**
+   * Moves the receiver along its normal before the shadow lookup.
+   *
+   * @remarks
+   * Grazing-angle self-shadowing cannot be fixed with a depth bias: the depth
+   * spanned by one shadow texel is `texelWorldSize * tan(theta)`, which diverges
+   * as NdotL approaches zero. Offsetting the sample position sideways moves it
+   * out of the offending texel instead, and the required distance is bounded.
+   *
+   * `depthBiasValues.y` carries the world-space distance of one `normalBias`
+   * unit (see `ShadowMapper.calcDepthBiasParams`).
+   * @internal
+   */ static applyShadowNormalOffset(lightType, scope, worldPos, worldNormal, NdotL, cascadeScale) {
+        const pb = scope.$builder;
+        const depthBiasParam = this.getDepthBiasValues(scope);
+        const receiverNoL = getShadowReceiverNoL(scope, NdotL, lightType);
+        // sin(theta): 0 when facing the light, 1 at grazing incidence.
+        const sinTheta = pb.sqrt(pb.clamp(pb.sub(1, pb.mul(receiverNoL, receiverNoL)), 0, 1));
+        let offset = pb.mul(depthBiasParam.y, getShadowReceiverBiasFactor(scope), sinTheta);
+        if (cascadeScale) {
+            offset = pb.mul(offset, cascadeScale);
+        }
+        if (lightType !== LIGHT_TYPE_DIRECTIONAL) {
+            // Perspective shadow cameras: one texel covers more world space further
+            // from the light. depthBiasValues.w is the far/near footprint ratio.
+            const posRange = this.getLightPositionAndRangeForShadow(scope);
+            const linearDepth = pb.clamp(pb.div(pb.distance(worldPos, posRange.xyz), pb.max(posRange.w, 1e-6)), 0, 1);
+            offset = pb.mul(offset, pb.mix(1, depthBiasParam.w, linearDepth));
+        }
+        // Guard against a degenerate interpolated normal rather than normalize()ing
+        // a possibly-zero vector into NaN.
+        const unitNormal = pb.mul(worldNormal, pb.div(1, pb.max(pb.length(worldNormal), 1e-6)));
+        return pb.add(worldPos, pb.mul(unitNormal, offset));
+    }
+    /**
+   * Calculates shadow of current fragment
+   *
+   * @param scope - Shader scope
+   * @param NoL - NdotL vector
+   * @returns Shadow of current fragment, 1 means no shadow and 0 means full shadowed.
+   */ static calculateShadow(scope, worldPos, worldNormal, NoL, ctx) {
         const pb = scope.$builder;
         const that = this;
         const shadowMapParams = ctx.shadowMapInfo.get(ctx.currentShadowLight);
         const funcName = 'Z_calculateShadow';
         pb.func(funcName, [
             pb.vec3('worldPos'),
+            pb.vec3('worldNormal'),
             pb.float('NoL')
         ], function() {
             if (shadowMapParams.numShadowCascades > 1) {
@@ -1313,18 +1619,21 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 this.$l.comparison = pb.vec4(pb.greaterThan(pb.vec4(this.linearDepth), this.splitDistances));
                 this.$l.cascadeFlags = pb.vec4(pb.float(pb.greaterThan(this.shadowCascades, 0)), pb.float(pb.greaterThan(this.shadowCascades, 1)), pb.float(pb.greaterThan(this.shadowCascades, 2)), pb.float(pb.greaterThan(this.shadowCascades, 3)));
                 this.$l.split = pb.int(pb.dot(this.comparison, this.cascadeFlags));
+                // Normal offset bias: move the receiver out of the shadow texel that
+                // would self-occlude it before projecting into shadow space. Scaled per
+                // cascade, because each cascade has its own texel world size.
+                this.$l.biasedPos = that.applyShadowNormalOffset(shadowMapParams.lightType, this, this.worldPos, this.worldNormal, this.NoL, that.getShadowCascadeBiasScale(this, this.split));
                 if (ctx.device.type === 'webgl') {
                     this.$l.shadowVertex = pb.vec4();
                     this.$for(pb.int('cascade'), 0, 4, function() {
                         this.$if(pb.equal(this.cascade, this.split), function() {
-                            this.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.worldPos, 1), this.cascade);
+                            this.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.biasedPos, 1), this.cascade);
                             this.$break();
                         });
                     });
                 } else {
-                    this.$l.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.worldPos, 1), this.split);
+                    this.$l.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.biasedPos, 1), this.split);
                 }
-                const shadowMapParams = ctx.shadowMapInfo.get(ctx.currentShadowLight);
                 this.$l.shadow = shadowMapParams.impl.computeShadowCSM(shadowMapParams, this, this.shadowVertex, this.NoL, this.split);
                 this.shadow = pb.clamp(this.shadow, 0, 1);
                 this.$l.shadowDistance = that.getShadowCameraParams(scope).w;
@@ -1336,8 +1645,9 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 });
                 this.$return(this.shadow);
             } else {
-                this.$l.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.worldPos, 1));
-                const shadowMapParams = ctx.shadowMapInfo.get(ctx.currentShadowLight);
+                // Normal offset bias - see the cascaded branch above.
+                this.$l.biasedPos = that.applyShadowNormalOffset(shadowMapParams.lightType, this, this.worldPos, this.worldNormal, this.NoL);
+                this.$l.shadowVertex = that.calculateShadowSpaceVertex(this, pb.vec4(this.biasedPos, 1));
                 this.$l.shadow = shadowMapParams.impl.computeShadow(shadowMapParams, this, this.shadowVertex, this.NoL);
                 this.shadow = pb.clamp(this.shadow, 0, 1);
                 this.$l.shadowDistance = that.getShadowCameraParams(scope).w;
@@ -1347,7 +1657,7 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 this.$return(this.shadow);
             }
         });
-        return pb.getGlobalScope()[funcName](worldPos, NoL);
+        return pb.getGlobalScope()[funcName](worldPos, worldNormal, NoL);
     }
     static applyFog(scope, worldPos, color, ctx) {
         const pb = scope.$builder;
@@ -1371,13 +1681,13 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             scope[funcName](worldPos, color);
         }
     }
-    /**
-   * Calculates the non-linear depth from linear depth
-   *
-   * @param scope - Current shader scope
-   * @param depth - The linear depth
-   * @param nearFar - A vector that contains the near clip plane in x component and the far clip plane in y component
-   * @returns The calculated non-linear depth
+    /**
+   * Calculates the non-linear depth from linear depth
+   *
+   * @param scope - Current shader scope
+   * @param depth - The linear depth
+   * @param nearFar - A vector that contains the near clip plane in x component and the far clip plane in y component
+   * @returns The calculated non-linear depth
    */ static linearDepthToNonLinear(scope, depth, nearFar) {
         const pb = scope.$builder;
         nearFar = nearFar ?? this.getCameraParams(scope);
@@ -1386,13 +1696,13 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         }
         return pb.div(pb.sub(nearFar.y, pb.div(pb.mul(nearFar.x, nearFar.y), depth)), pb.sub(nearFar.y, nearFar.x));
     }
-    /**
-   * Calculates the linear depth from non-linear depth
-   *
-   * @param scope - Current shader scope
-   * @param depth - The non-linear depth
-   * @param nearFar - A vector that contains the near clip plane in x component and the far clip plane in y component
-   * @returns The calculated linear depth
+    /**
+   * Calculates the linear depth from non-linear depth
+   *
+   * @param scope - Current shader scope
+   * @param depth - The non-linear depth
+   * @param nearFar - A vector that contains the near clip plane in x component and the far clip plane in y component
+   * @returns The calculated linear depth
    */ static nonLinearDepthToLinear(scope, depth, nearFar) {
         const pb = scope.$builder;
         nearFar = nearFar ?? this.getCameraParams(scope);
@@ -1401,13 +1711,13 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         }
         return pb.div(pb.mul(nearFar.x, nearFar.y), pb.mix(nearFar.y, nearFar.x, depth));
     }
-    /**
-   * Calculates the normalized linear depth from non-linear depth
-   *
-   * @param scope - Current shader scope
-   * @param depth - The non-linear depth
-   * @param nearFar - A vector that contains the near clip plane in x component and the far clip plane in y component
-   * @returns The calculated normalized linear depth
+    /**
+   * Calculates the normalized linear depth from non-linear depth
+   *
+   * @param scope - Current shader scope
+   * @param depth - The non-linear depth
+   * @param nearFar - A vector that contains the near clip plane in x component and the far clip plane in y component
+   * @returns The calculated normalized linear depth
    */ static nonLinearDepthToLinearNormalized(scope, depth, nearFar) {
         const pb = scope.$builder;
         nearFar = nearFar ?? this.getCameraParams(scope);
@@ -1416,19 +1726,19 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         }
         return pb.div(nearFar.x, pb.mix(nearFar.y, nearFar.x, depth));
     }
-    /**
-   * Converts normalized linear depth back to device non-linear depth.
-   *
-   * @remarks
-   * The normalized linear depth convention (range [near/far, 1] with 1 at
-   * the far plane, as produced by {@link ShaderHelper.nonLinearDepthToLinearNormalized})
-   * is independent of the engine depth convention; only the mapping to
-   * device depth flips under reverse-Z.
-   *
-   * @param scope - Current shader scope
-   * @param depth - The normalized linear depth
-   * @param nearFar - A vector that contains the near clip plane in x component and the far clip plane in y component
-   * @returns The device non-linear depth
+    /**
+   * Converts normalized linear depth back to device non-linear depth.
+   *
+   * @remarks
+   * The normalized linear depth convention (range [near/far, 1] with 1 at
+   * the far plane, as produced by {@link ShaderHelper.nonLinearDepthToLinearNormalized})
+   * is independent of the engine depth convention; only the mapping to
+   * device depth flips under reverse-Z.
+   *
+   * @param scope - Current shader scope
+   * @param depth - The normalized linear depth
+   * @param nearFar - A vector that contains the near clip plane in x component and the far clip plane in y component
+   * @returns The device non-linear depth
    */ static linearNormalizedToNonLinearDepth(scope, depth, nearFar) {
         const pb = scope.$builder;
         nearFar = nearFar ?? this.getCameraParams(scope);
@@ -1437,65 +1747,65 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         }
         return pb.div(pb.sub(pb.div(nearFar.x, depth), nearFar.y), pb.sub(nearFar.x, nearFar.y));
     }
-    /**
-   * Maps a device depth value to the canonical clip-space z coordinate
-   * (GL [-1,1] under standard-Z, zero-to-one under reverse-Z), suitable for
-   * unprojection with the engine's inverse projection matrices.
-   *
-   * @param scope - Current shader scope
-   * @param depth - The device depth value
-   * @returns The canonical clip-space z
+    /**
+   * Maps a device depth value to the canonical clip-space z coordinate
+   * (GL [-1,1] under standard-Z, zero-to-one under reverse-Z), suitable for
+   * unprojection with the engine's inverse projection matrices.
+   *
+   * @param scope - Current shader scope
+   * @param depth - The device depth value
+   * @returns The canonical clip-space z
    */ static deviceDepthToClipZ(scope, depth) {
         const pb = scope.$builder;
         return REVERSE_Z ? depth : pb.sub(pb.mul(depth, 2), 1);
     }
-    /**
-   * Clip-space z that places a vertex exactly on the far plane (sky domes,
-   * background geometry).
-   *
-   * @param scope - Current shader scope
-   * @param w - The clip-space w coordinate of the vertex
-   * @returns The clip-space z value for the far plane
+    /**
+   * Clip-space z that places a vertex exactly on the far plane (sky domes,
+   * background geometry).
+   *
+   * @param scope - Current shader scope
+   * @param w - The clip-space w coordinate of the vertex
+   * @returns The clip-space z value for the far plane
    */ static farthestClipZ(scope, w) {
         return REVERSE_Z ? 0 : w;
     }
-    /**
-   * Tests whether a device depth value equals the cleared (farthest) depth,
-   * i.e. no geometry was rendered at this position.
-   *
-   * @param scope - Current shader scope
-   * @param depth - The device depth value
-   * @returns Boolean expression, true for background pixels
+    /**
+   * Tests whether a device depth value equals the cleared (farthest) depth,
+   * i.e. no geometry was rendered at this position.
+   *
+   * @param scope - Current shader scope
+   * @param depth - The device depth value
+   * @returns Boolean expression, true for background pixels
    */ static isFarthestDepth(scope, depth) {
         return scope.$builder.equal(depth, DEPTH_FARTHEST);
     }
-    /**
-   * Selects the closer of two device depth values.
-   *
-   * @param scope - Current shader scope
-   * @param a - First device depth value
-   * @param b - Second device depth value
-   * @returns The value closer to the camera
+    /**
+   * Selects the closer of two device depth values.
+   *
+   * @param scope - Current shader scope
+   * @param a - First device depth value
+   * @param b - Second device depth value
+   * @returns The value closer to the camera
    */ static closerDepth(scope, a, b) {
         return scope.$builder[DEPTH_REDUCE_CLOSER](a, b);
     }
-    /**
-   * Selects the farther of two device depth values.
-   *
-   * @param scope - Current shader scope
-   * @param a - First device depth value
-   * @param b - Second device depth value
-   * @returns The value farther from the camera
+    /**
+   * Selects the farther of two device depth values.
+   *
+   * @param scope - Current shader scope
+   * @param a - First device depth value
+   * @param b - Second device depth value
+   * @returns The value farther from the camera
    */ static fartherDepth(scope, a, b) {
         return scope.$builder[DEPTH_REDUCE_FARTHER](a, b);
     }
-    /**
-   * Sample linear depth from linear depth texture
-   * @param scope - Current shader scope
-   * @param tex - The linear depth texture
-   * @param uv - The uv coordinates
-   * @param level - The mipmap level to sample
-   * @returns Linear depth value
+    /**
+   * Sample linear depth from linear depth texture
+   * @param scope - Current shader scope
+   * @param tex - The linear depth texture
+   * @param uv - The uv coordinates
+   * @param level - The mipmap level to sample
+   * @returns Linear depth value
    */ static sampleLinearDepth(scope, tex, uv, level) {
         const pb = scope.$builder;
         const depth = pb.textureSampleLevel(tex, uv, level);
@@ -1517,23 +1827,23 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         });
         return scope.zSamplePositionFromDepth(uv, cameraNearFar, mat);
     }
-    /**
-   * Sample linear depth from linear depth texture with backface
-   * @param scope - Current shader scope
-   * @param tex - The linear depth texture
-   * @param uv - The uv coordinates
-   * @param level - The mipmap level to sample
-   * @returns Linear depth value
+    /**
+   * Sample linear depth from linear depth texture with backface
+   * @param scope - Current shader scope
+   * @param tex - The linear depth texture
+   * @param uv - The uv coordinates
+   * @param level - The mipmap level to sample
+   * @returns Linear depth value
    */ static sampleLinearDepthWithBackface(scope, tex, uv, level) {
         const pb = scope.$builder;
         return pb.textureSampleLevel(tex, uv, level).rg;
     }
-    /**
-   * Transform color to sRGB color space if nessesary
-   *
-   * @param scope - Current shader scope
-   * @param outputColor - The color to be transformed
-   * @returns The transformed color
+    /**
+   * Transform color to sRGB color space if nessesary
+   *
+   * @param scope - Current shader scope
+   * @param outputColor - The color to be transformed
+   * @returns The transformed color
    */ static encodeColorOutput(scope, outputColor) {
         const pb = scope.$builder;
         const that = this;