@zephyr3d/scene 0.9.25 → 0.9.27

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';
@@ -16,6 +17,28 @@ const UNIFORM_NAME_SKYDISTANTLIGHT_LUT = 'Z_UniformSkyDistantLightLUT';
 const UNIFORM_NAME_SHADOW_MAP = 'Z_UniformShadowMap';
 const UNIFORM_NAME_SHADOW_MASK = 'Z_UniformShadowMask';
 const UNIFORM_NAME_SHADOW_MASK_MODE = 'Z_UniformShadowMaskMode';
+const UNIFORM_NAME_CAUSTIC_MAP = 'Z_UniformCausticMap';
+const UNIFORM_NAME_CAUSTIC_HEIGHT_MAP = 'Z_UniformCausticHeightMap';
+/**
+ * Offset added to a surface height before it is stored in the caustic height
+ * map, so that a cleared texel - no surface on that ray - is distinguishable
+ * from a surface at the rest level. A ray with no water on it must read as
+ * dry, not as submerged under a flat surface: on the down-sun side of a
+ * footprint edge, a receiver below the rest level but above a trough would
+ * otherwise be lit through water that is not there. Eight keeps troughs down
+ * to seven metres positive and leaves half floats millimetre precision.
+ * @internal
+ */ const CAUSTIC_HEIGHT_BIAS = 8;
+/**
+ * Water bodies that can cast caustics into one map.
+ *
+ * They share the map and the slice, so this is not a limit on how much water a
+ * scene may hold - only on how many separate surfaces the receiver will test
+ * itself against, which it does per fragment. Four covers a lake with a couple
+ * of pools beside it; beyond that the renderer keeps the largest four, which
+ * are the ones a viewer is most likely to be standing over.
+ */ const MAX_CAUSTIC_WATERS = 4;
+const UNIFORM_NAME_CAUSTIC_PARAMS = 'Z_UniformCausticParams';
 const UNIFORM_NAME_LINEAR_DEPTH_MAP = 'Z_UniformLinearDepth';
 const UNIFORM_NAME_LINEAR_DEPTH_MAP_SIZE = 'Z_UniformLinearDepthSize';
 const UNIFORM_NAME_SCENE_COLOR_MAP = 'Z_UniformSceneColor';
@@ -32,6 +55,8 @@ 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';
 /**
@@ -46,6 +71,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 +127,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;
     }
@@ -183,10 +215,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) {
@@ -272,6 +316,9 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 }
                 scope[UNIFORM_NAME_SHADOW_MAP] = tex.uniform(0);
             }
+            if (this.usesWaterCaustics(ctx)) {
+                this.declareWaterCausticUniforms(pb);
+            }
             if (ctx.drawEnvLight) {
                 ctx.env.light.envLight.initShaderBindings(pb, ctx);
             }
@@ -282,8 +329,18 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
                 scope[UNIFORM_NAME_LINEAR_DEPTH_MAP_SIZE] = pb.vec2().uniform(0);
             }
             if (ctx.sceneColorTexture) {
-                // Scene color copy: single mip level
-                scope[UNIFORM_NAME_SCENE_COLOR_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear_nomip'));
+                // Mip-filtered, because the refraction background is read at a LOD and
+                // not only at mip 0: the water picks one from how deep and how turbid
+                // the column it is looking through is. A `nomip` sampler pins mip 0
+                // whatever LOD the shader passes, so this and the copy's level count
+                // have to change together - and each backend only honours one of them.
+                // WebGPU binds the sampler declared here as a static binding the runtime
+                // cannot overwrite; WebGL falls back to the texture's own sampler, whose
+                // mip filter follows its level count.
+                //
+                // Every other reader of this texture passes an explicit LOD 0 (SSR hits,
+                // the sky blend), so none of them changes behaviour.
+                scope[UNIFORM_NAME_SCENE_COLOR_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear'));
                 scope[UNIFORM_NAME_SCENE_COLOR_MAP_SIZE] = pb.vec2().uniform(0);
             }
             if (ctx.HiZTexture) {
@@ -322,6 +379,8 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             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 +413,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 +475,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 +492,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 +505,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 +698,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);
@@ -535,6 +799,19 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         }
     }
     /**
+   * 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
@@ -550,6 +827,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,13 +838,17 @@ 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;
+        }
+        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
@@ -588,13 +873,16 @@ 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
@@ -676,10 +964,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 +1025,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) {
@@ -834,10 +1126,329 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
             bindGroup.setTexture(UNIFORM_NAME_SHADOW_MASK, ctx.shadowMaskTexture ?? this.getDummyShadowMask(ctx.device), fetchSampler('clamp_nearest'));
         }
         bindGroup.setTexture(UNIFORM_NAME_BAKED_SKY_MAP, ctx.scene.env.sky.getBakedSkyTexture(ctx));
+        if (this.usesWaterCaustics(ctx)) {
+            this.setWaterCausticUniforms(bindGroup, ctx);
+        }
         if (ctx.drawEnvLight) {
             ctx.env.light.envLight.updateBindGroup(bindGroup, ctx);
         }
     }
+    /**
+   * Whether the pass being built modulates its light with the water caustic map.
+   *
+   * True for every light pass of a frame that produced a map; which light the
+   * caustics actually attach to is decided per-fragment by
+   * {@link ShaderHelper.calculateWaterCaustic}. Both the shader variant hash and
+   * the global bind group hash fold this in, so a program that declares the
+   * caustic uniforms is always paired with a bind group that supplies them.
+   *
+   * Deliberately a function of the draw context alone, with no material input.
+   * The caustic uniforms sit in the global bind group, whose layout is built
+   * once per {@link DrawContext.renderPassHash} and shared by every material in
+   * the pass, so the declarations have to be uniform across the pass. A material
+   * that must not receive caustics - water itself - opts out of the sampling
+   * instead, through `receivesWaterCaustics()`; the uniforms stay declared and
+   * simply go unread.
+   *
+   * @param ctx - Current draw context.
+   * @returns True when the caustic uniforms take part in this pass.
+   * @internal
+   */ static usesWaterCaustics(ctx) {
+        return !!ctx.waterCaustics && !!ctx.waterCausticLight && ctx.renderPass.type === RENDER_PASS_TYPE_LIGHT;
+    }
+    /**
+   * Declares the global uniforms {@link ShaderHelper.calculateWaterCaustic} reads.
+   *
+   * Split out of the global uniform setup so a test can build a program that
+   * exercises the sampling code without standing up a whole light pass.
+   *
+   * @param pb - Program builder whose global scope receives the uniforms.
+   * @internal
+   */ /**
+   * Warps a linear caustic-map coordinate so texels concentrate near the centre.
+   *
+   * The map covers a fixed footprint, so its world texel size is the range
+   * divided by the resolution and a range large enough to light the scene is
+   * already too coarse to resolve a caustic cell. This trades the edge of the
+   * map, which is far from the camera, for the middle, which is not:
+   *
+   * ```
+   * warp(u)   = u (1 + k) / (1 + k |u|)
+   * unwarp(w) = w / ((1 + k) - k |w|)
+   * ```
+   *
+   * Texel density is `1 + k` times uniform at the centre and `1 / (1 + k)` times
+   * it at the border, and `k = 0` is exactly the identity, so the pass can apply
+   * this unconditionally. Both ends of `[-1, 1]` are fixed points, which is what
+   * lets the warp sit inside the existing parameterisation without moving the
+   * footprint the receiver gates on. The first derivative is continuous at the
+   * centre; the second flips sign there, which is not visible in a pattern this
+   * noisy.
+   *
+   * Applied per axis rather than radially: the photon grid, the map and the blur
+   * are all axis-aligned, so a separable warp keeps photon `(i,j)` on texel
+   * `(i,j)` for calm water and leaves the map's normalisation to 1.0 intact.
+   *
+   * @param scope - Current shader scope.
+   * @param ndc - Linear map coordinate in `[-1, 1]`.
+   * @param strength - Warp strength `k`; 0 is the identity.
+   * @returns The warped coordinate, also in `[-1, 1]`.
+   * @internal
+   */ static warpCausticNDC(scope, ndc, strength) {
+        const pb = scope.$builder;
+        const funcName = 'Z_warpCausticNDC';
+        pb.func(funcName, [
+            pb.vec2('ndc'),
+            pb.float('k')
+        ], function() {
+            this.$return(pb.div(pb.mul(this.ndc, pb.add(this.k, 1)), pb.add(pb.vec2(1), pb.mul(pb.abs(this.ndc), this.k))));
+        });
+        return pb.getGlobalScope()[funcName](ndc, strength);
+    }
+    /**
+   * Inverse of {@link ShaderHelper.warpCausticNDC}.
+   *
+   * The denominator is `1` at the border and `1 + k` at the centre, so it stays
+   * positive for any input the passes feed it - all of which come from `[-1, 1]`.
+   *
+   * @param scope - Current shader scope.
+   * @param warped - Warped map coordinate in `[-1, 1]`.
+   * @param strength - Warp strength `k`; 0 is the identity.
+   * @returns The linear coordinate the warp came from.
+   * @internal
+   */ static unwarpCausticNDC(scope, warped, strength) {
+        const pb = scope.$builder;
+        const funcName = 'Z_unwarpCausticNDC';
+        pb.func(funcName, [
+            pb.vec2('warped'),
+            pb.float('k')
+        ], function() {
+            this.$return(pb.div(this.warped, pb.sub(pb.vec2(pb.add(this.k, 1)), pb.mul(pb.abs(this.warped), this.k))));
+        });
+        return pb.getGlobalScope()[funcName](warped, strength);
+    }
+    /** @internal */ static declareWaterCausticUniforms(pb) {
+        const scope = pb.getGlobalScope();
+        const causticStruct = pb.defineStruct([
+            pb.vec4('frameX'),
+            pb.vec4('frameY'),
+            pb.vec4('center'),
+            pb.vec4('lightDir'),
+            pb.vec4('params'),
+            pb.vec4('extinction'),
+            // Per water body, because the slice is shared but the water is not: each
+            // has its own surface height, footprint and medium, and none of the three
+            // means anything until a receiver has resolved which water is above it.
+            pb.int('waterCount'),
+            pb.vec4[MAX_CAUSTIC_WATERS]('waterRegions'),
+            // (sigma_t.xyz, surface height)
+            pb.vec4[MAX_CAUSTIC_WATERS]('waterMedia')
+        ]);
+        scope[UNIFORM_NAME_CAUSTIC_PARAMS] = causticStruct().uniform(0);
+        // The map is single mip and read bilinearly; clamping keeps receivers
+        // outside the covered area reading the border rather than wrapping.
+        scope[UNIFORM_NAME_CAUSTIC_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear_nomip'));
+        // Displaced surface height per water slot, on the same slice as the map.
+        // Read with the map's uv, so it shares the map's sampling.
+        scope[UNIFORM_NAME_CAUSTIC_HEIGHT_MAP] = pb.tex2D().uniform(0).withSampler(getSamplerOptions('clamp_linear_nomip'));
+    }
+    /**
+   * Attenuation the water caustics apply to one light at a world position.
+   *
+   * Returns the product of two effects: the caustic pattern focused by the waves,
+   * and the Beer-Lambert transmittance of the water column the light travelled
+   * through to reach the point. The result is 1 for any light that is not the
+   * caustic light, above the surface, and outside the water region, so the caller
+   * can multiply unconditionally.
+   *
+   * The caustic light is identified at runtime by comparing directions rather
+   * than by which pass is running. Shadow-casting lights reach the opaque queue
+   * through the clustered path when the screen-space shadow mask is on (the
+   * default) and through a per-light additive pass when it is off; only a runtime
+   * test covers both. Two directional lights pointing the same way would both
+   * pick up the caustics, but they are physically the same light.
+   *
+   * @param scope - Current shader scope.
+   * @param worldPos - World position of the shaded fragment.
+   * @param lightType - The light's type constant.
+   * @param lightDirection - Direction the light travels, i.e. `directionAndCutoff.xyz`.
+   * @param ctx - Current draw context.
+   * @returns A `vec3` multiplier, or null when this pass has no caustics.
+   */ static calculateWaterCaustic(scope, worldPos, lightType, lightDirection, ctx) {
+        if (!this.usesWaterCaustics(ctx)) {
+            return null;
+        }
+        return this.sampleWaterCaustic(scope, worldPos, lightType, lightDirection);
+    }
+    /**
+   * {@link ShaderHelper.calculateWaterCaustic} without the pass gate.
+   *
+   * The gate asks whether the *light pass* has caustics, which is the right
+   * question for a material and the wrong one for a standalone full-screen pass
+   * that declared the same uniforms itself. Such a pass has already decided it
+   * has a map; this is the sampling half on its own.
+   *
+   * @param scope - Current shader scope.
+   * @param worldPos - World position of the shaded fragment.
+   * @param lightType - The light's type constant.
+   * @param lightDirection - Direction the light travels, i.e. `directionAndCutoff.xyz`.
+   * @param defocus - Whether to fade the pattern's contrast by how far the point
+   * is from the map's focal depth. True for a receiver surface, which is what
+   * that fade describes. False for a point inside the water column: see the
+   * comment on the term itself.
+   * @returns A `vec3` multiplier.
+   * @internal
+   */ static sampleWaterCaustic(scope, worldPos, lightType, lightDirection, defocus = true) {
+        const pb = scope.$builder;
+        const funcName = defocus ? 'Z_calculateWaterCaustic' : 'Z_calculateWaterCausticVolume';
+        pb.func(funcName, [
+            pb.vec3('worldPos'),
+            pb.int('lightType'),
+            pb.vec3('lightDirection')
+        ], function() {
+            this.$l.cu = this[UNIFORM_NAME_CAUSTIC_PARAMS];
+            // Only the one light the map was built for casts caustics.
+            this.$if(pb.or(pb.notEqual(this.lightType, LIGHT_TYPE_DIRECTIONAL), pb.lessThan(pb.dot(this.lightDirection, this.cu.lightDir.xyz), 0.999)), function() {
+                this.$return(pb.vec3(1));
+            });
+            // Project into the map: frameX/frameY are orthonormal and perpendicular to
+            // the light, so the same two dot products the splat pass used invert it.
+            this.$l.rel = pb.sub(this.worldPos, this.cu.center.xyz);
+            // Per-axis inverse extents: the slice is fitted to the water, so it is
+            // only square in texels, not in meters.
+            this.$l.mapNDC = pb.mul(pb.vec2(pb.dot(this.rel, this.cu.frameX.xyz), pb.dot(this.rel, this.cu.frameY.xyz)), pb.vec2(this.cu.frameX.w, this.cu.frameY.w));
+            // Texels are concentrated towards the middle of the map, so the lookup
+            // goes through the same warp the splat laid the photons out under.
+            this.$l.warpedNDC = ShaderHelper.warpCausticNDC(this, this.mapNDC, this.cu.extinction.w);
+            this.$l.uv = pb.add(pb.mul(this.warpedNDC, 0.5), pb.vec2(0.5));
+            // The displaced surface height of each water slot on this fragment's own
+            // sun ray, biased by CAUSTIC_HEIGHT_BIAS. The height map rasterises the
+            // displaced surface into the same light-space slice as the pattern, so
+            // the texel under this uv holds the surface the ray through this fragment
+            // passed through - no entry point has to be estimated. Beyond the map the
+            // sampler would repeat its border, which is some other ray's wave; the
+            // surface is taken as flat there.
+            this.$l.insideMap = pb.all(pb.lessThanEqual(pb.abs(this.mapNDC), pb.vec2(1)));
+            // How far this fragment is towards the map border, and how much the map is
+            // therefore trusted. Hoisted above the water loop because the wave height
+            // is faded by it too, not just the pattern.
+            //
+            // Measured on the linear coordinate, not the warped one. The warp fixes
+            // both ends of [-1, 1], so the border is in the same world place either
+            // way, but the band between them is not: warping it would make its world
+            // width depend on the warp strength, and the CPU sized it in meters.
+            //
+            // Distance is measured under an L4 norm rather than per-axis. A per-axis
+            // fade is a rectangle in light space, and the sun tilts that rectangle, so
+            // its border lands on the sea bed as straight lines - which the eye picks
+            // out of a caustic pattern however wide the gradient is. An L2 circle has
+            // no straight part anywhere but discards the 21% of the map outside its
+            // inscribed disc; L4 gives up 7% instead and still curves everywhere.
+            this.$l.ndcSq = pb.mul(this.mapNDC, this.mapNDC);
+            this.$l.edgeDist = pb.sqrt(pb.sqrt(pb.dot(this.ndcSq, this.ndcSq)));
+            this.$l.edge = pb.sub(1, pb.smoothStep(this.cu.params.w, 1, this.edgeDist));
+            this.$l.waveHeights = pb.textureSampleLevel(this[UNIFORM_NAME_CAUSTIC_HEIGHT_MAP], this.uv, 0);
+            // Find the water above this point. Several can qualify - a pool inside a
+            // lake, water on terraces - and the one that matters is the lowest of
+            // them, because that is the last surface the sun crossed on its way here.
+            this.$l.depth = pb.float(-1);
+            this.$l.medium = pb.vec3(0);
+            this.$for(pb.int('i'), 0, MAX_CAUSTIC_WATERS, function() {
+                this.$if(pb.greaterThanEqual(this.i, this.cu.waterCount), function() {
+                    this.$break();
+                });
+                this.$l.slotMedium = this.cu.waterMedia.at(this.i);
+                // Where the sun ray that lights this point crossed that water's rest
+                // plane, for the footprint test. The splat pass clips photons by that
+                // same crossing, so the receiver must ask the same question: a point
+                // under the footprint that the sun reaches from outside it saw no water
+                // at all, and a point beyond the footprint that the sun reaches through
+                // it did. Testing the point's own xz gets both wrong by the offset
+                // depth / tan(elevation). Only the footprint is decided here; the depth
+                // itself comes from the height map, which needs no crossing point.
+                this.$l.slotFlat = pb.sub(this.slotMedium.w, this.worldPos.y);
+                this.$l.slotPath = pb.mul(this.slotFlat, this.cu.lightDir.w);
+                this.$l.slotEntry = pb.sub(this.worldPos.xz, pb.mul(this.cu.lightDir.xz, this.slotPath));
+                this.$l.slotRegion = this.cu.waterRegions.at(this.i);
+                this.$if(pb.and(pb.all(pb.greaterThanEqual(this.slotEntry, this.slotRegion.xy)), pb.all(pb.lessThanEqual(this.slotEntry, this.slotRegion.zw))), function() {
+                    // Depth under the *displaced* surface on this ray, which is what
+                    // the splat refracted the photons through. Gating on the rest plane
+                    // instead cut the caustics off at a flat line across any receiver
+                    // that pokes above it under a crest. Slot i lives in channel i.
+                    this.$l.slotMask = pb.vec4(pb.float(pb.equal(this.i, 0)), pb.float(pb.equal(this.i, 1)), pb.float(pb.equal(this.i, 2)), pb.float(pb.equal(this.i, 3)));
+                    this.$l.slotSample = pb.dot(this.waveHeights, this.slotMask);
+                    // A cleared texel inside the map means this ray never meets that
+                    // body's surface - it crosses the rest plane beyond the footprint,
+                    // or the surface is on the far side of the receiver - and the
+                    // receiver is dry as far as this body is concerned. Outside the map
+                    // nothing is known and the surface is taken as flat.
+                    this.$l.slotCovered = pb.or(pb.not(this.insideMap), pb.greaterThan(this.slotSample, 0.5));
+                    this.$if(this.slotCovered, function() {
+                        // Faded into the rest plane over the same band the pattern fades
+                        // on, rather than switched off at the border. Beyond the map the
+                        // surface is taken as flat, and exp(-sigma * depth) is convex, so
+                        // a hard switch makes the wavy side systematically brighter than
+                        // the flat side - E[exp(-sigma*w)] > 1 - and the step lands as a
+                        // mean brightness seam that grows with both the swell and the
+                        // turbidity. Ramping the wave to zero puts the two sides on the
+                        // same value at the border.
+                        this.$l.slotWave = pb.mul(pb.sub(this.slotSample, CAUSTIC_HEIGHT_BIAS), pb.float(this.insideMap), this.edge);
+                        this.$l.slotDepth = pb.sub(pb.add(this.slotMedium.w, this.slotWave), this.worldPos.y);
+                        this.$if(pb.greaterThan(this.slotDepth, 0), function() {
+                            this.$if(pb.or(pb.lessThan(this.depth, 0), pb.lessThan(this.slotDepth, this.depth)), function() {
+                                this.depth = this.slotDepth;
+                                this.medium = this.slotMedium.xyz;
+                            });
+                        });
+                    });
+                });
+            });
+            this.$if(pb.lessThanEqual(this.depth, 0), function() {
+                this.$return(pb.vec3(1));
+            });
+            this.$l.pathLength = pb.mul(this.depth, this.cu.lightDir.w);
+            this.$l.transmittance = pb.exp(pb.neg(pb.mul(this.medium, this.pathLength)));
+            this.$l.pattern = pb.textureSampleLevel(this[UNIFORM_NAME_CAUSTIC_MAP], this.uv, 0).x;
+            if (defocus) {
+                // Receivers away from the focal plane see a defocused, lower-contrast
+                // pattern rather than a displaced one.
+                this.$l.defocus = pb.div(1, pb.add(1, pb.mul(pb.abs(pb.sub(this.depth, this.cu.params.y)), this.cu.params.z)));
+            } else {
+                // A point inside the water column is not a receiver, and has no depth of
+                // its own to be out of focus at - the volumetric march visits every
+                // depth along the ray. Charging it the receiver's fade makes the light
+                // shafts fade according to where the *sea bed* was told to be sharpest:
+                // the open-ocean preset focuses the map at 26m for its bed, which at the
+                // default defocus leaves a point 2m down at 26% contrast, and the shafts
+                // dissolve into grain. The shafts instead take the pattern as the map
+                // holds it and fade with the edge and the transmittance like everything
+                // else in the column.
+                this.$l.defocus = pb.float(1);
+            }
+            this.$l.weight = pb.mul(this.cu.params.x, this.defocus, this.edge);
+            this.$l.caustic = pb.add(1, pb.mul(pb.sub(this.pattern, 1), this.weight));
+            // Soften the waterline so the transmittance does not switch on abruptly.
+            this.$l.submerged = pb.smoothStep(0, 0.05, this.depth);
+            this.$return(pb.mix(pb.vec3(1), pb.mul(pb.vec3(this.caustic), this.transmittance), this.submerged));
+        });
+        return pb.getGlobalScope()[funcName](worldPos, lightType, lightDirection);
+    }
+    /** @internal */ static setWaterCausticUniforms(bindGroup, ctx) {
+        const uniforms = ctx.waterCausticUniforms;
+        bindGroup.setValue(UNIFORM_NAME_CAUSTIC_PARAMS, {
+            frameX: uniforms.frameX,
+            frameY: uniforms.frameY,
+            center: uniforms.center,
+            lightDir: uniforms.lightDir,
+            params: uniforms.params,
+            extinction: uniforms.extinction,
+            waterCount: uniforms.waterCount,
+            waterRegions: uniforms.waterRegions,
+            waterMedia: uniforms.waterMedia
+        });
+        bindGroup.setTexture(UNIFORM_NAME_CAUSTIC_MAP, ctx.waterCausticTexture, fetchSampler('clamp_linear_nomip'));
+        bindGroup.setTexture(UNIFORM_NAME_CAUSTIC_HEIGHT_MAP, ctx.waterCausticHeightTexture, fetchSampler('clamp_linear_nomip'));
+    }
     /** @internal */ static setLightUniformsShadow(bindGroup, ctx, light) {
         const shadowMapParams = ctx.shadowMapInfo.get(light);
         this._lightUniformShadow.sunDir = ctx.sunLight ? ctx.sunLight.directionAndCutoff.xyz().scaleBy(-1) : this.defaultSunDir;
@@ -857,6 +1468,9 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         this._lightUniformShadow.envLightSpecularStrength = ctx.env?.light.specularStrength ?? 1;
         bindGroup.setValue('light', this._lightUniformShadow);
         bindGroup.setTexture(UNIFORM_NAME_SHADOW_MAP, shadowMapParams.shadowMap, shadowMapParams.shadowMapSampler);
+        if (this.usesWaterCaustics(ctx)) {
+            this.setWaterCausticUniforms(bindGroup, ctx);
+        }
         bindGroup.setTexture(UNIFORM_NAME_BAKED_SKY_MAP, ctx.scene.env.sky.getBakedSkyTexture(ctx));
         if (ctx.drawEnvLight) {
             ctx.env.light.envLight.updateBindGroup(bindGroup, ctx);
@@ -978,6 +1592,50 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         return scope.camera.elapsedTime;
     }
     /**
+   * Declares the one camera field {@link ShaderHelper.getElapsedTime} reads.
+   *
+   * Wave generators animate off `camera.elapsedTime`, which the light and depth
+   * passes provide as part of the full camera struct. A standalone program that
+   * drives a wave generator - the caustics splat pass - has no such struct, so it
+   * declares that single field under the same name. Any generator that starts
+   * reading a second camera field will need it added here.
+   *
+   * The three padding floats round the struct up to 16 bytes. std140 aligns a
+   * struct to a vec4 boundary, so a lone float leaves the GLSL block larger than
+   * the buffer the engine sizes from the struct's own members - WebGL2 then
+   * rejects every draw with "uniform buffer that is too small" and rasterises
+   * nothing, while WebGPU is unaffected.
+   *
+   * @param scope - Global scope of the standalone program.
+   * @param uniformGroup - Bind group the uniform belongs to.
+   * @internal
+   */ static declareStandaloneCameraTime(scope, uniformGroup) {
+        const pb = scope.$builder;
+        scope.camera = pb.defineStruct([
+            pb.float('elapsedTime'),
+            pb.float('_pad0'),
+            pb.float('_pad1'),
+            pb.float('_pad2')
+        ])().uniform(uniformGroup);
+    }
+    /**
+   * Uploads the value declared by {@link ShaderHelper.declareStandaloneCameraTime}.
+   *
+   * Must be the same clock the light pass uses, or a wave generator's caustics
+   * would animate out of step with the surface they are refracted through.
+   *
+   * @param bindGroup - Bind group of the standalone program.
+   * @param ctx - Current draw context.
+   * @internal
+   */ static setStandaloneCameraTime(bindGroup, ctx) {
+        bindGroup.setValue('camera', {
+            elapsedTime: ctx.device.frameInfo.elapsedOverall * 0.001,
+            _pad0: 0,
+            _pad1: 0,
+            _pad2: 0
+        });
+    }
+    /**
    * Gets the elapsed time since last frame in seconds
    * @param scope - Current shader scope
    * @returns The elapsed time since last frame in seconds
@@ -1291,18 +1949,67 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
         return scope[UNIFORM_NAME_SHADOW_MAP];
     }
     /**
+   * 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, NoL, ctx) {
+   */ 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 +2020,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 +2046,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 +2058,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;
@@ -1555,5 +2266,5 @@ const UNIFORM_NAME_MORPH_INFO = 'Z_UniformMorphInfo';
     }
 }
 
-export { ShaderHelper };
+export { CAUSTIC_HEIGHT_BIAS, MAX_CAUSTIC_WATERS, ShaderHelper };
 //# sourceMappingURL=helper.js.map