@call-me-sensei/toonlab 0.4.21 → 0.4.23

package/src/shaders-tsl/water.js

@@ -26,6 +26,7 @@
 // phase resolves the ordering.
 
 import * as THREE from 'three';
+import { getWaterFoamTexture } from '../water/waterFoamTexture.js';
 import {
   abs,
   attribute,
@@ -33,6 +34,7 @@ import {
   cameraProjectionMatrix,
   cameraViewMatrix,
   clamp,
+  cos,
   Discard,
   dot,
   exp,
@@ -75,6 +77,7 @@ import { createWaterFoamChunk } from './chunks/water-foam.js';
 import { createWaterLightingChunk } from './chunks/water-lighting.js';
 import { createWaterRippleChunk } from './chunks/water-ripple.js';
 import { createWaterShoreStateChunk } from './chunks/water-shore-state.js';
+import { projectedWaterCaustics } from './chunks/projected-water-caustics.js';
 import { createWaterWavesChunk } from './chunks/water-waves.js';
 
 // Node-backend placeholders: same roles as waterMaterial.js's placeholders,
@@ -132,8 +135,10 @@ export function createWaterNodeMaterial({
   detailOctaves = 4,
   foamOctaves = 3,
   shoaling = false,
+  dynamics = false,
 } = {}) {
   const flags = {
+    dynamics: Boolean(dynamics),
     caustics: qualityLevel >= 1,
     chromaticCaustics: qualityLevel >= 2,
     detailOctaves,
@@ -168,6 +173,23 @@ export function createWaterNodeMaterial({
     uDistanceFogColor: uniform(new THREE.Color(0.66, 0.8, 0.94)),
     uDistanceFogDensity: uniform(0),
     uTime: uniform(0),
+    uReferenceView: uniform(0),
+    uUseShoreContour: uniform(0),
+    uFoamCoordinates: texture(holders.ripple),
+    uFoamBubbles: texture(getWaterFoamTexture()),
+    uFoamParticleRegion: uniform(new THREE.Vector4(0,0,1,1)),
+    uFoamParticleCoverage: uniform(0),
+    uFoamFrontState: texture(holders.ripple),
+    uUseFoamFrontState: uniform(0),
+    uContinueShoreAlongX: uniform(0),
+    uUseSpectralNormals: uniform(0),
+    uSpectralNormal0: texture(holders.ripple),
+    uSpectralNormal1: texture(holders.ripple),
+    uSpectralNormal2: texture(holders.ripple),
+    uSpectralLengths: uniform(new THREE.Vector3(1,1,1)),
+    uDetailNormal0: texture(holders.ripple),
+    uDetailNormal1: texture(holders.ripple),
+    uDetailLengths: uniform(new THREE.Vector2(1,1)),
     uResolution: uniform(new THREE.Vector2(1, 1)),
     uCameraNear: uniform(0.05),
     uCameraFar: uniform(200),
@@ -279,7 +301,7 @@ export function createWaterNodeMaterial({
   const shoreState = createWaterShoreStateChunk({ u });
   const color = createWaterColorChunk({ u, flags });
   const foam = createWaterFoamChunk({ u, foamOctaves });
-  const lighting = createWaterLightingChunk({ u });
+  const lighting = createWaterLightingChunk({ u, physicalSurface: flags.dynamics });
 
   const material = new NodeMaterial();
   material.name = 'StylizedWater';
@@ -309,12 +331,34 @@ export function createWaterNodeMaterial({
   // is under dry land; the fragment shader discards those fragments so
   // triangles spanning a cliff face can't poke through the terrain.
   const vRestDepth = varying(float(), 'vWaterRestDepth');
+  const vDynamicsFoam = varying(float(), 'vDynamicsFoam');
+  const vDynamicsFlow = varying(vec2(), 'vDynamicsFlow');
+  const vWetDistance = varying(float(), 'vWaterWetDistance');
 
   material.vertexNode = Fn(() => {
     const worldPosition = modelWorldMatrix.mul(vec4(positionGeometry, 1.0)).toVar();
     const restXZ = worldPosition.xz.toVar();
     vRestWorldXZ.assign(restXZ);
 
+    if (flags.dynamics) {
+      const state = attribute('aWaterState', 'vec4');
+      vWetDistance.assign(attribute('aWaterWetDistance','float'));
+      worldPosition.y.assign(state.x);
+      vRestDepth.assign(state.y);
+      vSwashZone.assign(smoothstep(0.02, 0.25, state.y).oneMinus());
+      vSwashFoamData.assign(vec2(state.y.sub(0.002), 0.02));
+      vSwashSurge.assign(vec2(0.0));
+      vGerstnerNormal.assign(attribute('aWaterNormal', 'vec3'));
+      vCrest.assign(float(0.0));
+      vShoal.assign(float(1.0));
+      vBreaker.assign(float(0.0));
+      vDynamicsFlow.assign(state.zw);
+      vDynamicsFoam.assign(shoreState.shoreStateSample(restXZ).b);
+      vWorldPosition.assign(worldPosition.xyz);
+      return cameraProjectionMatrix.mul(cameraViewMatrix).mul(vec4(worldPosition.xyz, 1.0));
+    }
+    vDynamicsFoam.assign(float(0.0));
+    vDynamicsFlow.assign(vec2(0.0));
     // Shallow water filters the spectrum: the short cross chop dies out toward
     // the surf zone, leaving clean parallel lines of the dominant swell.
     const chopWeight = float(1.0).toVar();
@@ -454,10 +498,13 @@ export function createWaterNodeMaterial({
         .mul(u.uSwashEdgeShape.z)
         .mul(macroWave.mul(macroWave))
         .toVar();
+      const swashActivity = smoothstep(0.0, 0.05, u.uWaveEnergy)
+        .mul(select(max(u.uRunupDistance, u.uShorelineRunup).greaterThan(0.0), 1.0, 0.0)).toVar();
       const edgeHead = edgeDistance.mul(bedSlope)
         .add(
           edgeTilt.add(edgeScallop).mul(edgeEnvelope)
             .add(edgeMacro)
+            .mul(swashActivity)
             .mul(bedSlope),
         ).toVar();
       const filmHead = restDepth.add(edgeHead).toVar();
@@ -493,7 +540,7 @@ export function createWaterNodeMaterial({
       const surgeDistance = min(runupDistance.mul(0.32), 3.2).toVar();
       const swashDrift = shoreDirection.mul(swashProgress).mul(surgeDistance)
         .add(alongDirection.mul(sin(u.uTime.mul(0.37))).mul(swashProgress).mul(0.55));
-      vSwashSurge.assign(swashDrift.mul(beach));
+      vSwashSurge.assign(swashDrift.mul(beach).mul(swashActivity));
       waveDisplacement.assign(vec3(
         rawWave.x.mul(shoal),
         mix(brokenY, filmY, beach),
@@ -539,7 +586,9 @@ export function createWaterNodeMaterial({
     // Apply the nonlinear wet threshold after the signed film head has been
     // interpolated. Evaluating smoothstep at sparse vertices first exposed
     // individual triangle rows as the water advanced at a grazing angle.
-    if (flags.shoaling) {
+    if (flags.dynamics) {
+      Discard(mix(vRestDepth.sub(0.002),vWetDistance,u.uUseShoreContour).lessThan(0.0));
+    } else if (flags.shoaling) {
       const fragmentWet = mix(
         1.0,
         smoothstep(-0.004, 0.012, vSwashFoamData.x),
@@ -571,13 +620,16 @@ export function createWaterNodeMaterial({
     // A centimetres-thin film is optically smooth at this camera scale. Full
     // open-water normal detail turned every texel into a bright grazing-angle
     // mirror and made the swash look like an opaque sheet of snow.
-    const detailStrength = u.uDetailNormalStrength
+    const detailStrength = u.uDetailNormalStrength.mul(u.uReferenceView.oneMinus())
       .mul(mix(0.2, 1.0, detailFade))
       .mul(mix(0.1, 1.0, horizonFade))
       .mul(mix(1.0, 0.18, swashOptics)).toVar();
     const flowOffset = u.uFlowDirection.mul(u.uTime).mul(u.uFlowSpeed).toVar();
-    const detailUv1 = vRestWorldXZ.mul(u.uDetailScale).add(flowOffset.mul(0.55));
-    const detailUv2 = waterRotate2d(1.9).mul(vRestWorldXZ).mul(u.uDetailScale.mul(1.63)).sub(flowOffset.mul(0.34));
+    // Advect in world space BEFORE frequency/rotation: changing detail scale
+    // must not reverse or rotate the current (f(x - U*t) travels with U).
+    const advectedXZ = vRestWorldXZ.sub(flowOffset).toVar();
+    const detailUv1 = advectedXZ.mul(u.uDetailScale);
+    const detailUv2 = waterRotate2d(1.9).mul(advectedXZ).mul(u.uDetailScale.mul(1.63));
     const waterDetailGradient = (detailUv) => {
       const uv = vec2(detailUv).toVar();
       const center = waterFbm(uv, flags.detailOctaves).toVar();
@@ -585,11 +637,31 @@ export function createWaterNodeMaterial({
       const dy = waterFbm(uv.add(vec2(0.0, 0.11)), flags.detailOctaves);
       return vec2(dx.sub(center), dy.sub(center)).div(0.11);
     };
-    const detailGradient = waterDetailGradient(detailUv1).mul(detailStrength)
-      .add(waterDetailGradient(detailUv2).mul(detailStrength).mul(0.55)).toVar();
+    const detailGradient = vec2(0.0).toVar();
+    if (flags.dynamics) {
+      // Broadband short waves with seeded phases and dispersion. Two tiles
+      // of different extents avoid the eight visible, endlessly repeated
+      // ridges from the former plane-wave sum. Mips filter distant glints.
+      const activity = clamp(u.uWaveEnergy.div(0.35), 0.0, 1.0);
+      const styleGain = mix(u.uDetailNormalStrength.mul(0.45).add(1.0), 1.0, u.uReferenceView);
+      const shortSlope = u.uDetailNormal0.sample(advectedXZ.div(u.uDetailLengths.x).add(0.5/64)).rg
+        .add(u.uDetailNormal1.sample(advectedXZ.div(u.uDetailLengths.y).add(0.5/64)).rg);
+      detailGradient.assign(shortSlope.mul(activity).mul(styleGain).mul(detailFade).mul(smoothstep(0.025,0.22,vRestDepth)));
+    } else {
+      detailGradient.assign(waterDetailGradient(detailUv1).mul(detailStrength)
+        .add(waterDetailGradient(detailUv2).mul(detailStrength).mul(0.55)));
+    }
     const rippleGradient = ripple.rippleGradient(vRestWorldXZ);
     const rippleState = ripple.rippleSample(vRestWorldXZ).toVar();
     const waveNormal = waterCombineNormal(gerstnerNormal, rippleGradient).toVar();
+    if (flags.dynamics) {
+      const spectralSlope = u.uSpectralNormal0.sample(advectedXZ.div(u.uSpectralLengths.x)).level(0).rg
+        .add(u.uSpectralNormal1.sample(advectedXZ.div(u.uSpectralLengths.y)).level(0).rg)
+        .add(u.uSpectralNormal2.sample(advectedXZ.div(u.uSpectralLengths.z)).level(0).rg);
+      const spectralNormal = normalize(vec3(spectralSlope.x.negate(), 1.0, spectralSlope.y.negate()));
+      const depthBlend = smoothstep(0.2, 1.5, vRestDepth).mul(u.uUseSpectralNormals);
+      waveNormal.assign(normalize(mix(waveNormal, spectralNormal, depthBlend)));
+    }
     const surfaceNormal = waterCombineNormal(waveNormal, detailGradient).toVar();
     // Refraction reads with most of the micro detail removed.
     const refractionNormal = waterCombineNormal(waveNormal, detailGradient.mul(0.3)).toVar();
@@ -609,23 +681,21 @@ export function createWaterNodeMaterial({
         float(1.0).sub(float(1.0).div(eta.mul(eta))),
         0.0,
       ).sqrt().toVar();
-      const snellWindow = smoothstep(
-        criticalCos.sub(0.04),
-        criticalCos.add(0.045),
-        cosIncident,
-      ).toVar();
+      // No transmitted ray exists beyond the critical angle. Fresnel itself
+      // approaches full reflection continuously from the transmissive side.
+      const snellWindow = select(cosIncident.greaterThan(criticalCos), 1.0, 0.0).toVar();
       const refractedDirection = refract(
         incident,
         surfaceNormal.negate(),
         eta,
       ).toVar();
-      // refract() returns zero under total internal reflection. Blend toward
-      // the incident ray there to keep the projection numerically stable;
+      // refract() returns zero under total internal reflection. Use the
+      // incident ray only for a finite unused projection in that branch;
       // snellWindow prevents that fallback ray from becoming transmission.
       const transmissionDirection = normalize(mix(
         incident,
         refractedDirection,
-        max(snellWindow, 0.001),
+        snellWindow,
       )).toVar();
       const transmissionWorld = vWorldPosition.add(
         transmissionDirection.mul(min(u.uCameraFar.mul(0.75), 400.0)),
@@ -653,10 +723,10 @@ export function createWaterNodeMaterial({
         clamp(insideCapture.mul(u.uUseSceneColor), 0.0, 1.0),
       ).toVar();
 
-      // Compact Beer-Lambert-inspired attenuation through the camera's water
-      // column. This uses ToonLab's authored palette, keeping the result
+      // Compact Beer-Lambert-inspired attenuation along the camera's water
+      // path. This uses ToonLab's authored palette, keeping the result
       // graphic and readable instead of pursuing the reference's realism.
-      const cameraDepth = max(vWorldPosition.y.sub(cameraPosition.y), 0.0).toVar();
+      const cameraDepth = viewDistance; // optical path to this surface point, not vertical depth
       const volumeAbsorb = exp(
         cameraDepth.div(max(
           u.uDepthFadeDistance.add(u.uDeepFadeDistance.mul(0.5)),
@@ -668,6 +738,10 @@ export function createWaterNodeMaterial({
         u.uMidColor,
         clamp(volumeAbsorb.mul(1.35), 0.0, 1.0),
       ).toVar();
+      if (flags.dynamics) {
+        const transmittance = exp(vec3(0.20, 0.055, 0.035).mul(viewDistance).negate());
+        transmitted.assign(transmitted.mul(transmittance).add(u.uMidColor.mul(transmittance.oneMinus()).mul(0.35)));
+      } else {
       transmitted.mulAssign(mix(
         vec3(1.0),
         waterTint.mul(1.12),
@@ -679,10 +753,16 @@ export function createWaterNodeMaterial({
         volumeAbsorb.mul(u.uUnderwaterTintStrength),
       ));
 
-      const f0 = eta.sub(1.0).div(eta.add(1.0)).pow2().toVar();
-      const fresnel = f0.add(
-        f0.oneMinus().mul(pow(cosIncident.oneMinus(), 5.0)),
-      ).toVar();
+      }
+
+      const cosTransmitted = max(float(1.0).sub(
+        eta.mul(eta).mul(float(1.0).sub(cosIncident.mul(cosIncident))),
+      ), 0.0).sqrt().toVar();
+      const parallel = cosIncident.sub(eta.mul(cosTransmitted))
+        .div(max(cosIncident.add(eta.mul(cosTransmitted)), 1e-5));
+      const perpendicular = eta.mul(cosIncident).sub(cosTransmitted)
+        .div(max(eta.mul(cosIncident).add(cosTransmitted), 1e-5));
+      const fresnel = parallel.mul(parallel).add(perpendicular.mul(perpendicular)).mul(0.5).toVar();
       const transmissionWeight = fresnel.oneMinus()
         .mul(snellWindow)
         .mul(u.uUnderwaterTransmission)
@@ -691,7 +771,15 @@ export function createWaterNodeMaterial({
         u.uDeepColor.mul(0.48),
         u.uMidColor.mul(0.72),
         cosIncident.mul(0.3),
-      );
+      ).toVar();
+      If(u.uUseReflectionMap.greaterThan(0.5), () => {
+        const reflectedClip = u.uReflectionMatrix.mul(vec4(vWorldPosition, 1.0));
+        const reflectedUv = reflectedClip.xy.div(max(abs(reflectedClip.w), 1e-5))
+          .add(surfaceNormal.xz.mul(u.uReflectionDistortion));
+        const reflectedScene = u.uReflectionMap.sample(clamp(reflectedUv, vec2(0.0), vec2(1.0))).level(0).rgb;
+        const attenuation = exp(viewDistance.mul(0.06).negate());
+        tirColor.assign(mix(u.uMidColor, reflectedScene, attenuation));
+      });
       const underColor = mix(
         tirColor,
         transmitted,
@@ -706,10 +794,10 @@ export function createWaterNodeMaterial({
         criticalCos.add(0.1),
         cosIncident,
       ).oneMinus());
-      underColor.addAssign(u.uFresnelColor.mul(criticalRim).mul(0.12));
-      underColor.addAssign(
-        lighting.sparkles(vRestWorldXZ, surfaceNormal, viewDir, viewDistance, u.uTime).mul(0.5),
-      );
+            if (!flags.dynamics) {
+        underColor.addAssign(u.uFresnelColor.mul(criticalRim).mul(0.12).mul(u.uReferenceView.oneMinus()));
+        underColor.addAssign(lighting.sparkles(vRestWorldXZ, surfaceNormal, viewDir, viewDistance, u.uTime).mul(0.5));
+      }
       // The captured air-side scene is already composited; render the
       // underside opaque to avoid double-blending the main scene behind it.
       output.assign(vec4(underColor, 1.0));
@@ -728,7 +816,9 @@ export function createWaterNodeMaterial({
         max(vWorldPosition.y.sub(groundWorld.y), 0.0),
         u.uDepthFadeDistance.add(u.uDeepFadeDistance),
       ).toVar();
-      const effectiveDepth = columnDepth.add(viewDepthDiff.mul(0.18));
+      const effectiveDepth = flags.dynamics
+        ? length(groundWorld.sub(vWorldPosition))
+        : columnDepth.add(viewDepthDiff.mul(0.18));
 
       const { absorb, tint: absorptionTint } = color.absorptionTint(effectiveDepth);
 
@@ -738,6 +828,26 @@ export function createWaterNodeMaterial({
         const sceneColor = u.uSceneColor.sample(refractedUv).level(0).rgb;
         const tintedScene = sceneColor.mul(mix(vec3(1.0), u.uShallowColor.mul(1.25), clamp(absorb.mul(0.6), 0.0, 1.0)));
         bodyColor.assign(mix(tintedScene, absorptionTint, absorb));
+        if (flags.dynamics) {
+          const transmission = exp(vec3(0.20,0.055,0.035).mul(effectiveDepth).negate());
+          const physicalBody = sceneColor.mul(transmission).add(u.uDeepColor.mul(transmission.oneMinus()));
+          // Preserve optical depth in both treatments. Style colours the
+          // scattering, rather than replacing clear swash with opaque tint.
+          const shallowDistance = max(u.uDepthFadeDistance, 0.05);
+          const deepDistance = max(u.uDeepFadeDistance, 0.05);
+          const styledScatter = mix(
+            mix(u.uShallowColor, u.uMidColor, smoothstep(0.0, shallowDistance, effectiveDepth)),
+            u.uDeepColor,
+            smoothstep(shallowDistance, shallowDistance.add(deepDistance), effectiveDepth),
+          );
+          // Style controls optical density as well as hue. At centimetre
+          // depths this still transmits the sand; metre-deep water now
+          // visibly consumes the authored shallow, mid and deep palette.
+          const styledTransmission = transmission.mul(exp(effectiveDepth.div(shallowDistance).mul(-0.65)));
+          const styledBody = sceneColor.mul(styledTransmission)
+            .add(styledScatter.mul(styledTransmission.oneMinus()));
+          bodyColor.assign(mix(styledBody, physicalBody, u.uReferenceView));
+        }
         alpha.assign(1.0);
       }).Else(() => {
         bodyColor.assign(absorptionTint);
@@ -749,12 +859,14 @@ export function createWaterNodeMaterial({
       const clearScene = u.uSceneColor.sample(screenUv).level(0).rgb;
       const wetScene = clearScene.mul(0.85);
       const clearSceneWeight = select(u.uUseSceneColor.greaterThan(0.5), 0.48, 0.0);
-      bodyColor.assign(mix(bodyColor, wetScene, swashOptics.mul(clearSceneWeight)));
-      bodyColor.assign(mix(bodyColor, u.uShallowColor, swashOptics.mul(0.18)));
+            if (!flags.dynamics) {
+        bodyColor.assign(mix(bodyColor, wetScene, swashOptics.mul(clearSceneWeight)));
+        bodyColor.assign(mix(bodyColor, u.uShallowColor, swashOptics.mul(0.18)));
+      }
 
       // Steep wave faces act like windows, not lenses: drop caustics there,
       // and fade the dappling with view distance (WATER_QUALITY >= 1).
-      const caustics = flags.caustics
+      const caustics = flags.caustics && !flags.dynamics
         ? color.caustics(groundWorld, columnDepth, u.uTime)
           .mul(smoothstep(0.62, 0.85, gerstnerNormalY))
           .mul(smoothstep(14.0, 38.0, viewDistance).oneMinus())
@@ -767,13 +879,19 @@ export function createWaterNodeMaterial({
       // staying glued to rest space while only the envelope moves.
       const foamXZ = vRestWorldXZ.sub(vSwashSurge).toVar();
       const pierce = color.pierceProximity(screenUv, waterViewDistance, vWorldPosition.y).toVar();
-      const shoreFoam = foam.shoreFoam(columnDepth, viewDepthDiff, foamXZ, u.uTime, pierce)
+      const shoreFoam = (flags.dynamics ? float(0.0) : foam.shoreFoam(columnDepth, viewDepthDiff, foamXZ, u.uTime, pierce))
         // The legacy contact mask assumes a water body deeper than the foam
         // distance. On a centimetre-thin swash film it is almost 1 everywhere,
         // so keep its familiar offshore/rock character but let the dedicated
         // turbulent edge above own the beach foam.
         .mul(mix(1.0, 0.05, clamp(vSwashZone, 0.0, 1.0))).toVar();
-      const whitecaps = foam.whitecaps(crest, gerstnerNormalY, foamXZ, u.uTime).toVar();
+      // Solver foam is an aeration concentration, not already opaque coverage.
+      // Map optical thickness to coverage before the toon threshold; passing
+      // a dilute swash tracer straight into it erased virtually all the lip.
+      const solvedFoamCoverage = exp(vDynamicsFoam.mul(-4.0)).oneMinus()
+        .mul(mix(1.0, u.uWhitecapAmount, u.uUseSpectralNormals))
+        .mul(mix(1.0, u.uSwashFoamAmount, swashOptics));
+      const whitecaps = (flags.dynamics ? solvedFoamCoverage : foam.whitecaps(crest, gerstnerNormalY, foamXZ, u.uTime)).toVar();
       const rippleFoamRaw = clamp(
         rippleState.b.mul(u.uRippleFoamStrength).add(abs(rippleState.r).mul(u.uRippleFoamStrength).mul(4.0)),
         0.0,
@@ -786,7 +904,7 @@ export function createWaterNodeMaterial({
       const persistentShoreCoverage = flags.shoaling
         ? shoreState.shoreStateCoverage(vRestWorldXZ)
         : float(0.0);
-      if (flags.shoaling) {
+      if (flags.shoaling && !flags.dynamics) {
         // The temporal shore field owns transport, decay, breakup, and
         // event-to-event variation. Keep this main material deliberately
         // small: duplicating procedural noise here can exceed WebGPU's hard
@@ -835,7 +953,56 @@ export function createWaterNodeMaterial({
       // together with offshore/contact foam; never max an unshaped milky mask
       // over the final result.
       const foamRaw = max(baseFoamRaw, swashFoamValue).toVar();
-      const foamValue = foam.foamShape(foamRaw, foamXZ, u.uTime).toVar();
+      let dynamicsFoam = foamRaw;
+      let bubbleShading = float(1.0);
+      if (flags.dynamics) {
+        // Transport texture coordinates with the water once per update.
+        // Multiplying the local velocity gradient by a long animation phase
+        // stretched the former breakup into sharp, shifting white ribbons.
+        const fieldUv=foamXZ.sub(u.uShoreStateRegion.xy).div(u.uShoreStateRegion.zw.mul(2.0)).add(0.5);
+        const boundedUv=clamp(fieldUv,vec2(0.0),vec2(1.0));
+        const outsideOffset=fieldUv.sub(boundedUv).mul(u.uShoreStateRegion.zw).mul(2.0);
+        const coordinates=u.uFoamCoordinates.sample(boundedUv).level(0).rg.add(outsideOffset);
+        const bubbles=u.uFoamBubbles.sample(coordinates.div(0.72));
+        const clusters=u.uFoamBubbles.sample(coordinates.mul(u.uFoamNoiseScale).mul(0.65)).b;
+        const coverage=smoothstep(0.32,0.68,clusters);
+        const thinFringe=smoothstep(0.012,0.06,vRestDepth).oneMinus();
+        const rafts=max(coverage,thinFringe.mul(0.5));
+        // Dense rafts expose packed bubble membranes. Dilute fringes break
+        // into individual bubbles, never an opaque cut-paper silhouette.
+        const packed=smoothstep(0.15,0.65,foamRaw.mul(rafts));
+        const pores=mix(bubbles.g,1.0,packed.mul(0.82));
+        const particleLocal=abs(foamXZ.sub(u.uFoamParticleRegion.xy)).div(u.uFoamParticleRegion.zw);
+        const particleBlend=smoothstep(vec2(.65),vec2(1.0),particleLocal).oneMinus();
+        const particleCoverage=particleBlend.x.mul(particleBlend.y).mul(u.uFoamParticleCoverage);
+        dynamicsFoam=clamp(foamRaw,0.0,1.0).mul(rafts).mul(pores).mul(mix(1.0,.28,particleCoverage));
+        // Coastal particles and the rim own the foam shape. The broad UV
+        // mask retained here for open-water whitecaps stretched into large
+        // flame-like ribbons on the thin beach sheet, even after advection.
+        const front=u.uFoamFrontState.sample(vec2(boundedUv.x,.5)).level(0);
+        // Thin cellular strands, not a thresholded broad mask. Cross-shore
+        // coordinates translate with local front flow without stretching
+        // every cell into a long solid ribbon as the old UV field did.
+        const laceUv=vec2(foamXZ.x,foamXZ.y.sub(front.a.mul(u.uUseFoamFrontState))).div(2.4).add(.5/512);
+        const lace=u.uFoamBubbles.sample(laceUv).a;
+        const trail=exp(max(vWetDistance.sub(.25),0).mul(-.65));
+        const laceFoam=clamp(foamRaw,0,1).mul(lace.mul(trail).mul(.65).add(.02)).mul(mix(.65,1,bubbles.g));
+        dynamicsFoam=mix(dynamicsFoam,laceFoam,u.uUseShoreContour);
+        // Connect the densely packed front rather than rendering individual
+        // rafts uniformly over the swash. Actual transported aeration still
+        // gates this rim: a calm, foam-free edge remains transparent.
+        const retreat=smoothstep(.02,.18,front.g.negate()).mul(u.uUseFoamFrontState);
+        const rimWidth=mix(.05,.13,clamp(front.b.mul(2),0,1)).mul(mix(1.0,.55,retreat));
+        const rim=smoothstep(.012,rimWidth,vWetDistance).oneMinus().mul(u.uUseShoreContour);
+        const rimAeration=max(vDynamicsFoam,front.b.mul(retreat));
+        const rimFoam=exp(rimAeration.mul(-12.0)).oneMinus()
+          .mul(clamp(u.uSwashFoamAmount,0.0,2.0)).mul(foamAmount)
+          .mul(rim).mul(mix(.75,1.0,bubbles.g)).mul(mix(.32,.14,retreat));
+        dynamicsFoam=max(dynamicsFoam,clamp(rimFoam,0.0,1.0));
+        bubbleShading=bubbles.r;
+      }
+      const foamValue = (flags.dynamics ? dynamicsFoam
+        : mix(foam.foamShape(foamRaw, foamXZ, u.uTime), foamRaw, u.uReferenceView)).toVar();
 
       // Drifting cloud shadows plus scene shadows (shared sun-shadow pass).
       const proceduralCloudShadow = stylizedCloudShadow(
@@ -860,20 +1027,20 @@ export function createWaterNodeMaterial({
       // Thin swash still catches the sky at its lip, but the interior should
       // mostly reveal wet sand. Attenuate (rather than remove) its Fresnel,
       // reflection and glints while keeping offshore water unchanged.
-      const swashLight = mix(1.0, 0.36, swashOptics).toVar();
+      const swashLight = (flags.dynamics ? float(1.0) : mix(1.0, 0.36, swashOptics.mul(u.uReferenceView.oneMinus()))).toVar();
       const surfaceFresnel = fresnel.mul(swashLight).toVar();
       const reflectionMix = clamp(
-        surfaceFresnel.mul(u.uReflectionStrength), 0.0, 0.92,
+        surfaceFresnel.mul(flags.dynamics ? 1.0 : mix(u.uReflectionStrength, 1.0, u.uReferenceView)), 0.0, 1.0,
       ).toVar();
       const litColor = mix(bodyColor, reflection, reflectionMix).toVar();
       litColor.addAssign(
-        u.uFresnelColor.mul(surfaceFresnel).mul(surfaceFresnel).mul(0.35),
+        u.uFresnelColor.mul(surfaceFresnel).mul(surfaceFresnel).mul(flags.dynamics ? 0.0 : 0.35).mul(u.uReferenceView.oneMinus()),
       );
       litColor.addAssign(
         lighting.specular(viewDir, surfaceNormal, foamValue.mul(0.75).oneMinus())
           .mul(sunVisibility).mul(swashLight),
       );
-      if (flags.sparkles) {
+      if (flags.sparkles && !flags.dynamics) {
         litColor.addAssign(
           lighting.sparkles(vRestWorldXZ, surfaceNormal, viewDir, viewDistance, u.uTime)
             .mul(foamValue.oneMinus()).mul(sunVisibility).mul(swashLight),
@@ -897,6 +1064,7 @@ export function createWaterNodeMaterial({
         u.uFoamColor.mul(foamLight),
         smoothstep(0.5, 0.82, foamRaw),
       ).toVar();
+      foamTint.mulAssign(bubbleShading);
       // Foam is sky-lit and remains readable in shade, but it cannot remain a
       // pure-white post-lighting overlay. Consume the same shared cast-shadow
       // visibility as the water body so its white line cools and dims while
@@ -954,7 +1122,7 @@ export function createWaterNodeMaterial({
         [3, vec4(surfaceNormal.mul(0.5).add(0.5), 1.0)],
         [4, vec4(rippleState.r.mul(2.0).add(0.5), rippleState.b, float(0.5).sub(rippleState.r.mul(2.0)), 1.0)],
         [5, vec4(reflection, 1.0)],
-        [6, vec4(caustics, 1.0)],
+        [6, vec4(flags.dynamics ? projectedWaterCaustics(groundWorld, vec3(0.0,1.0,0.0)) : caustics, 1.0)],
         [7, vec4(
           lighting.specular(viewDir, surfaceNormal, float(1.0))
             .add(lighting.sparkles(vRestWorldXZ, surfaceNormal, viewDir, viewDistance, u.uTime)),

package/src/sky/skySystem.js

@@ -343,6 +343,8 @@ function createGodRaysGroup(params = {}) {
  * volumes before the first frame can be rendered.
  */
 export class SkySystem {
+  /** Host cost policy. Disable only when no receivers need cloud shadows. */
+  cloudShadowsEnabled = true;
   #renderer;
   #camera;
   #scene;
@@ -711,6 +713,21 @@ export class SkySystem {
     return this.#cloudShadow.setLightDirection(direction);
   }
 
+  /**
+   * Opt-in opaque occlusion. Supply an unfiltered, linear color texture whose
+   * red channel is positive view-space distance in metres, cleared to >=65000.
+   * Render it with this camera BEFORE update(), excluding sky and transparent
+   * objects. The host owns the texture. Pass null for legacy backdrop depth.
+   */
+  setSceneDepthTexture(map = null) {
+    this.#assertLive();
+    if (map && this.#cloud.sceneDepthNode.value === map) return;
+    this.#cloud.setSceneDepthTexture(map);
+    this.#cloudLayer.material.depthTest = map === null;
+    this.#cloudLayer.material.needsUpdate = true;
+    this.#reprojection.reset();
+  }
+
   /** The sky dome. */
   get dome() {
     return this.#dome;
@@ -942,8 +959,8 @@ export class SkySystem {
     const enabled = this.#clouds.enabled === true;
     this.#post.cloudsEnabled.value = enabled ? 1 : 0;
     this.#cloudLayer.mesh.visible = enabled;
-    this.#cloudShadow.enabled = enabled;
-    if (enabled) {
+    this.#cloudShadow.enabled = enabled && this.cloudShadowsEnabled;
+    if (this.#cloudShadow.enabled) {
       // The shadow bake samples an explicit mip before the primary cloud pass
       // runs, so upload the authored 3D mip pyramid here as well as in the
       // reconstruction path. The helper is idempotent per renderer.
@@ -1221,6 +1238,7 @@ export class SkySystem {
       height,
       historyDiv: this.#quality.cloudHistoryDiv,
       shape: this.#clouds.shape,
+      wind: this.#clouds.wind,
       width,
     });
   }
@@ -1246,11 +1264,9 @@ export class SkySystem {
    * `depthWrite: false` keeps the layer out of everyone else's depth test, and it
    * draws before host transparency, so glass and particles composite over it.
    *
-   * One consequence worth naming: the depth is the sphere's radius, not the
-   * cloud's own distance, so a mountain 60 km out has cloud drawn over it even
-   * where the cloud it hides is nearer. The marcher already computes a
-   * transmittance-weighted mean cloud distance; writing that as the layer's depth
-   * is the fix, and it needs the reconstruction to carry the depth through.
+   * Without a scene-depth input, occlusion is still based on the carrier.
+   * setSceneDepthTexture opts into clipped integration and disables this
+   * carrier depth test so cloud in front of opaque geometry can composite.
    *
    * Premultiplied over, not alpha blending: the marcher writes
    * `vec4(scatteredRadiance, viewTransmittance)`, and the composite the cloud
@@ -1430,6 +1446,13 @@ export class SkySystem {
           max(atmosphere.fogFarFadeEnd, atmosphere.fogFarFadeStart.add(1)),
           distance,
         ).toVar();
+        // The cloud march already applies aerial perspective at cloud depth.
+        // Fog only the opaque contribution behind it, preserving its radiance.
+        If(this.#cloud.uniforms.sceneDepthEnabled.greaterThan(0.5)
+          .and(this.#post.cloudsEnabled.greaterThan(0.5)), () => {
+          const cloud = this.#cloudTextureNode.sample(screenUV);
+          skyTarget.assign(skyTarget.mul(cloud.a).add(cloud.rgb));
+        });
         rgb.assign(mix(mix(skyTarget, rgb, transmittance), skyTarget, farFade));
       });
 

package/src/toon/settings/perspectiveRemovalSettings.js

@@ -52,7 +52,7 @@ export function createPerspectiveRemovalSettings(options = null) {
 
   return {
     amount: enabled ? requestedAmount : 0,
-    enabled: enabled && requestedAmount > 0,
+    enabled,
     endHeight: numberOption(firstDefined(source, ['endHeight']), DEFAULT_PERSPECTIVE_REMOVAL_SETTINGS.endHeight, { min: -100, max: 1000 }),
     radius: numberOption(firstDefined(source, ['radius']), DEFAULT_PERSPECTIVE_REMOVAL_SETTINGS.radius, { min: 0.05, max: 50 }),
     startHeight: numberOption(firstDefined(source, ['startHeight']), DEFAULT_PERSPECTIVE_REMOVAL_SETTINGS.startHeight, { min: -100, max: 1000 }),