@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/src/shaders-tsl/chunks/vegetation-style.js

@@ -0,0 +1,360 @@
+// Shared vegetation style nodes. These uniforms describe the IP's rendering
+// treatment; current sun, wind, weather amounts, albedo, and interaction stay
+// in their own namespaces so applying a style cannot overwrite world state.
+
+import * as THREE from 'three';
+import {
+  abs,
+  cameraPosition,
+  clamp,
+  dot,
+  faceDirection,
+  mix,
+  normalize,
+  pow,
+  smoothstep,
+  uniform,
+  vec3,
+} from 'three/tsl';
+
+const FALLBACK = Object.freeze({
+  lighting: Object.freeze({
+    rimPower: 3,
+    rimStrength: 0.12,
+    shadowTint: Object.freeze([0.36, 0.4, 0.58]),
+    shadowTintStrength: 1,
+    skyFillStrength: 0.08,
+    sunTintStrength: 0.25,
+  }),
+  thinSurface: Object.freeze({
+    diffuseWrap: 0.5,
+    normalUpBias: 0,
+    transmissionPower: 3.5,
+    transmissionShadowFloor: 0.35,
+    transmissionStrength: 0.35,
+    twoSidedLighting: 1,
+  }),
+  weatherResponse: Object.freeze({
+    snowEdgeSoftness: 0.2,
+    snowShadowStrength: 0.65,
+    snowTint: Object.freeze([0.92, 0.96, 1]),
+    wetDarkening: 0.15,
+    wetDesaturation: 0.05,
+    wetHighlightStrength: 0.2,
+  }),
+  grass: Object.freeze({
+    backlitStrength: 0.4,
+    bandSoftness: 0.1,
+    bandThreshold: 0.49,
+    bendExponent: 2,
+    cloudShadowResponse: 0.35,
+    colorVariationStrength: 0.2,
+    gustSheenStrength: 0.22,
+    gustSheenThreshold: 0.78,
+    interactionResponse: 1,
+    rootOcclusionHeight: 0.62,
+    rootOcclusionStrength: 0.36,
+    sceneShadowResponse: 0.7,
+    shadowFloor: 0.35,
+    tipGradientEnd: 0.95,
+    tipGradientStart: 0.1,
+  }),
+  foliage: Object.freeze({
+    backlitStrength: 0.35,
+    bandSoftness: 0.18,
+    bandThreshold: 0.47,
+    cardVariationStrength: 0.16,
+    cloudShadowResponse: 0,
+    crestSoftness: 0.12,
+    crestThreshold: 0.72,
+    crownOcclusionStrength: 0.2,
+    sceneShadowResponse: 0.55,
+    spriteLuminanceStrength: 0.36,
+    transmissionPowerMultiplier: 1,
+  }),
+  flower: Object.freeze({
+    backlitStrength: 0.35,
+    bandSoftness: 0.1,
+    bandThreshold: 0.5,
+    centerLightResponse: 0.8,
+    centerShadowResponse: 1,
+    cupDarkeningStrength: 0.1,
+    petalTransmissionMultiplier: 1,
+    sceneShadowResponse: 0.85,
+    unlitPetalLift: 0.35,
+  }),
+  bark: Object.freeze({
+    bandCount: 3,
+    bandSoftness: 0,
+    rimStrength: 0,
+    shadowFloor: 0.35,
+    skyFillStrength: 0.04,
+    specularStrength: 0,
+    sunTintStrength: 0.15,
+    verticalShadeStrength: 0,
+  }),
+  stem: Object.freeze({
+    bandCount: 3,
+    bandSoftness: 0.08,
+    shadowFloor: 0.42,
+    skyFillStrength: 0.06,
+    transmissionStrength: 0.08,
+    rimStrength: 0.02,
+  }),
+});
+
+function sourceSettings(profile) {
+  return profile?.settings && typeof profile.settings === 'object' ? profile.settings : (profile ?? {});
+}
+
+function value(settings, group, key) {
+  return settings?.[group]?.[key] ?? FALLBACK[group][key];
+}
+
+function color(settings, group, key) {
+  const rgb = value(settings, group, key);
+  return new THREE.Color().setRGB(rgb[0], rgb[1], rgb[2], THREE.SRGBColorSpace);
+}
+
+/** Uniform contract shared by every vegetation material role. */
+export function createVegetationStyleUniforms(profile = {}, role = null) {
+  const settings = sourceSettings(profile);
+  const roles = new Set((Array.isArray(role) ? role : [role]).filter(Boolean));
+  const hasRole = (...candidates) => candidates.some((candidate) => roles.has(candidate));
+  const u = {
+    uSnowCover: uniform(0),
+    uSnowRetention: uniform(1),
+    uStyleLightingRimPower: uniform(value(settings, 'lighting', 'rimPower')),
+    uStyleLightingRimStrength: uniform(value(settings, 'lighting', 'rimStrength')),
+    uStyleLightingShadowTint: uniform(color(settings, 'lighting', 'shadowTint')),
+    uStyleLightingShadowTintStrength: uniform(value(settings, 'lighting', 'shadowTintStrength')),
+    uStyleLightingSkyFillStrength: uniform(value(settings, 'lighting', 'skyFillStrength')),
+    uStyleLightingSunTintStrength: uniform(value(settings, 'lighting', 'sunTintStrength')),
+    uStyleWeatherResponseSnowEdgeSoftness: uniform(value(settings, 'weatherResponse', 'snowEdgeSoftness')),
+    uStyleWeatherResponseSnowShadowStrength: uniform(value(settings, 'weatherResponse', 'snowShadowStrength')),
+    uStyleWeatherResponseSnowTint: uniform(color(settings, 'weatherResponse', 'snowTint')),
+    uStyleWeatherResponseWetDarkening: uniform(value(settings, 'weatherResponse', 'wetDarkening')),
+    uStyleWeatherResponseWetDesaturation: uniform(value(settings, 'weatherResponse', 'wetDesaturation')),
+    uStyleWeatherResponseWetHighlightStrength: uniform(value(settings, 'weatherResponse', 'wetHighlightStrength')),
+    uWetness: uniform(0),
+    uWetnessResponse: uniform(1),
+  };
+
+  if (hasRole('grassBlade', 'foliageCard', 'flowerPetal')) Object.assign(u, {
+    uStyleThinSurfaceDiffuseWrap: uniform(value(settings, 'thinSurface', 'diffuseWrap')),
+    uStyleThinSurfaceNormalUpBias: uniform(value(settings, 'thinSurface', 'normalUpBias')),
+    uStyleThinSurfaceTransmissionPower: uniform(value(settings, 'thinSurface', 'transmissionPower')),
+    uStyleThinSurfaceTransmissionShadowFloor: uniform(value(settings, 'thinSurface', 'transmissionShadowFloor')),
+    uStyleThinSurfaceTransmissionStrength: uniform(value(settings, 'thinSurface', 'transmissionStrength')),
+    uStyleThinSurfaceTwoSidedLighting: uniform(value(settings, 'thinSurface', 'twoSidedLighting')),
+  });
+  if (hasRole('grassBlade')) Object.assign(u, {
+    uStyleGrassBacklitStrength: uniform(value(settings, 'grass', 'backlitStrength')),
+    uStyleGrassBandSoftness: uniform(value(settings, 'grass', 'bandSoftness')),
+    uStyleGrassBandThreshold: uniform(value(settings, 'grass', 'bandThreshold')),
+    uStyleGrassBendExponent: uniform(value(settings, 'grass', 'bendExponent')),
+    uStyleGrassCloudShadowResponse: uniform(value(settings, 'grass', 'cloudShadowResponse')),
+    uStyleGrassColorVariationStrength: uniform(value(settings, 'grass', 'colorVariationStrength')),
+    uStyleGrassGustSheenStrength: uniform(value(settings, 'grass', 'gustSheenStrength')),
+    uStyleGrassGustSheenThreshold: uniform(value(settings, 'grass', 'gustSheenThreshold')),
+    uStyleGrassInteractionResponse: uniform(value(settings, 'grass', 'interactionResponse')),
+    uStyleGrassRootOcclusionHeight: uniform(value(settings, 'grass', 'rootOcclusionHeight')),
+    uStyleGrassRootOcclusionStrength: uniform(value(settings, 'grass', 'rootOcclusionStrength')),
+    uStyleGrassSceneShadowResponse: uniform(value(settings, 'grass', 'sceneShadowResponse')),
+    uStyleGrassShadowFloor: uniform(value(settings, 'grass', 'shadowFloor')),
+    uStyleGrassTipGradientEnd: uniform(value(settings, 'grass', 'tipGradientEnd')),
+    uStyleGrassTipGradientStart: uniform(value(settings, 'grass', 'tipGradientStart')),
+  });
+  if (hasRole('foliageCard')) Object.assign(u, {
+    uStyleFoliageBacklitStrength: uniform(value(settings, 'foliage', 'backlitStrength')),
+    uStyleFoliageBandSoftness: uniform(value(settings, 'foliage', 'bandSoftness')),
+    uStyleFoliageBandThreshold: uniform(value(settings, 'foliage', 'bandThreshold')),
+    uStyleFoliageCardVariationStrength: uniform(value(settings, 'foliage', 'cardVariationStrength')),
+    uStyleFoliageCloudShadowResponse: uniform(value(settings, 'foliage', 'cloudShadowResponse')),
+    uStyleFoliageCrestSoftness: uniform(value(settings, 'foliage', 'crestSoftness')),
+    uStyleFoliageCrestThreshold: uniform(value(settings, 'foliage', 'crestThreshold')),
+    uStyleFoliageCrownOcclusionStrength: uniform(value(settings, 'foliage', 'crownOcclusionStrength')),
+    uStyleFoliageSceneShadowResponse: uniform(value(settings, 'foliage', 'sceneShadowResponse')),
+    uStyleFoliageSpriteLuminanceStrength: uniform(value(settings, 'foliage', 'spriteLuminanceStrength')),
+    uStyleFoliageTransmissionPowerMultiplier: uniform(value(settings, 'foliage', 'transmissionPowerMultiplier')),
+  });
+  if (hasRole('flowerPetal', 'flowerCenter')) Object.assign(u, {
+    uStyleFlowerBandSoftness: uniform(value(settings, 'flower', 'bandSoftness')),
+    uStyleFlowerBandThreshold: uniform(value(settings, 'flower', 'bandThreshold')),
+    uStyleFlowerSceneShadowResponse: uniform(value(settings, 'flower', 'sceneShadowResponse')),
+  });
+  if (hasRole('flowerPetal')) Object.assign(u, {
+    uStyleFlowerBacklitStrength: uniform(value(settings, 'flower', 'backlitStrength')),
+    uStyleFlowerCupDarkeningStrength: uniform(value(settings, 'flower', 'cupDarkeningStrength')),
+    uStyleFlowerPetalTransmissionMultiplier: uniform(value(settings, 'flower', 'petalTransmissionMultiplier')),
+    uStyleFlowerUnlitPetalLift: uniform(value(settings, 'flower', 'unlitPetalLift')),
+  });
+  if (hasRole('flowerCenter')) Object.assign(u, {
+    uStyleFlowerCenterLightResponse: uniform(value(settings, 'flower', 'centerLightResponse')),
+    uStyleFlowerCenterShadowResponse: uniform(value(settings, 'flower', 'centerShadowResponse')),
+  });
+  if (hasRole('herbaceousStem')) Object.assign(u, {
+    uStyleStemBandCount: uniform(value(settings, 'stem', 'bandCount')),
+    uStyleStemBandSoftness: uniform(value(settings, 'stem', 'bandSoftness')),
+    uStyleStemShadowFloor: uniform(value(settings, 'stem', 'shadowFloor')),
+    uStyleStemRimStrength: uniform(value(settings, 'stem', 'rimStrength')),
+    uStyleStemSkyFillStrength: uniform(value(settings, 'stem', 'skyFillStrength')),
+    uStyleStemTransmissionStrength: uniform(value(settings, 'stem', 'transmissionStrength')),
+  });
+  if (hasRole('woodySurface')) Object.assign(u, {
+    uStyleBarkBandCount: uniform(value(settings, 'bark', 'bandCount')),
+    uStyleBarkBandSoftness: uniform(value(settings, 'bark', 'bandSoftness')),
+    uStyleBarkRimStrength: uniform(value(settings, 'bark', 'rimStrength')),
+    uStyleBarkShadowFloor: uniform(value(settings, 'bark', 'shadowFloor')),
+    uStyleBarkSkyFillStrength: uniform(value(settings, 'bark', 'skyFillStrength')),
+    uStyleBarkSpecularStrength: uniform(value(settings, 'bark', 'specularStrength')),
+    uStyleBarkSunTintStrength: uniform(value(settings, 'bark', 'sunTintStrength')),
+    uStyleBarkVerticalShadeStrength: uniform(value(settings, 'bark', 'verticalShadeStrength')),
+  });
+  return u;
+}
+
+export function vegetationBand(wrap, threshold, softness) {
+  const half = softness.mul(0.5);
+  return smoothstep(threshold.sub(half), threshold.add(half), wrap);
+}
+
+export function vegetationVisibility(
+  sceneShadow,
+  cloudShadow,
+  sceneShadowResponse,
+  cloudShadowResponse = 1,
+) {
+  const scene = mix(1.0, sceneShadow, sceneShadowResponse);
+  const cloud = mix(1.0, cloudShadow, cloudShadowResponse);
+  return scene.mul(cloud);
+}
+
+/** Common thin-surface lighting. Family shaders can layer role bands on top. */
+export function shadeVegetationSurface({
+  baseColor,
+  bandOverride = null,
+  bandSoftness,
+  bandThreshold,
+  cloudShadow,
+  u,
+  diffuseWrap = u.uStyleThinSurfaceDiffuseWrap,
+  normal,
+  normalUpBias = u.uStyleThinSurfaceNormalUpBias,
+  materialShadowColor = null,
+  sceneShadow,
+  sceneShadowResponse,
+  cloudShadowResponse = 1,
+  shadowFloor,
+  skyColor,
+  sunColor,
+  sunDirection,
+  rimStrength = u.uStyleLightingRimStrength,
+  transmissionMultiplier = 1,
+  transmissionPower = u.uStyleThinSurfaceTransmissionPower,
+  transmissionShadowFloor = u.uStyleThinSurfaceTransmissionShadowFloor,
+  transmissionStrength = u.uStyleThinSurfaceTransmissionStrength,
+  twoSidedLighting = u.uStyleThinSurfaceTwoSidedLighting,
+  skyFillStrength = u.uStyleLightingSkyFillStrength,
+  worldPosition,
+}) {
+  const doubleSidedNormal = normal.mul(faceDirection);
+  const faceAwareNormal = mix(normal, doubleSidedNormal, twoSidedLighting);
+  const styledNormal = normalize(mix(
+    faceAwareNormal,
+    vec3(0, 1, 0),
+    normalUpBias,
+  ));
+  const sun = normalize(sunDirection);
+  const wrap = dot(styledNormal, sun)
+    .mul(diffuseWrap.oneMinus())
+    .add(diffuseWrap);
+  const visibility = vegetationVisibility(
+    sceneShadow,
+    cloudShadow,
+    sceneShadowResponse,
+    cloudShadowResponse,
+  ).toVar();
+  const band = (bandOverride ?? vegetationBand(wrap, bandThreshold, bandSoftness))
+    .mul(visibility).toVar();
+  const colorNode = baseColor.mul(mix(shadowFloor, 1.0, band)).toVar();
+
+  // An asset palette may carry its own shadow tone (grass and tree foliage
+  // are the common cases). It establishes the material identity in shadow;
+  // the IP-wide treatment tint below still layers over every material.
+  const materialShadowAmount = visibility.oneMinus();
+  if (materialShadowColor) {
+    colorNode.assign(mix(
+      colorNode,
+      materialShadowColor,
+      clamp(materialShadowAmount, 0, 1),
+    ));
+  }
+  const shadowAmount = materialShadowAmount.mul(u.uStyleLightingShadowTintStrength);
+  colorNode.mulAssign(mix(
+    vec3(1),
+    u.uStyleLightingShadowTint,
+    clamp(shadowAmount, 0, 1),
+  ));
+  colorNode.mulAssign(mix(vec3(1), sunColor, band.mul(u.uStyleLightingSunTintStrength)));
+  colorNode.addAssign(skyColor.mul(band.oneMinus()).mul(skyFillStrength));
+
+  const viewDirection = normalize(cameraPosition.sub(worldPosition));
+  const rim = pow(
+    clamp(abs(dot(styledNormal, viewDirection)).oneMinus(), 0, 1),
+    u.uStyleLightingRimPower,
+  );
+  colorNode.addAssign(skyColor.mul(rim).mul(rimStrength));
+  const transmission = pow(
+    clamp(dot(viewDirection, sun.negate()), 0, 1),
+    transmissionPower,
+  ).mul(transmissionStrength).mul(transmissionMultiplier);
+  colorNode.addAssign(
+    sunColor.mul(transmission).mul(mix(
+      transmissionShadowFloor,
+      1,
+      visibility,
+    )),
+  );
+
+  const wet = clamp(u.uWetness.mul(u.uWetnessResponse), 0, 1).toVar();
+  colorNode.mulAssign(wet.mul(u.uStyleWeatherResponseWetDarkening).oneMinus());
+  const luminance = dot(colorNode, vec3(0.299, 0.587, 0.114));
+  colorNode.assign(mix(
+    colorNode,
+    vec3(luminance),
+    wet.mul(u.uStyleWeatherResponseWetDesaturation),
+  ));
+  colorNode.addAssign(
+    sunColor.mul(wet).mul(u.uStyleWeatherResponseWetHighlightStrength)
+      .mul(rim.mul(0.5).add(0.08)),
+  );
+
+  const snowSoftness = u.uStyleWeatherResponseSnowEdgeSoftness.max(0.001);
+  const snowEdge = snowSoftness.mul(0.5);
+  const snowFacing = smoothstep(
+    snowSoftness.mul(0.25).sub(snowEdge),
+    snowSoftness.mul(0.25).add(snowEdge),
+    styledNormal.y,
+  );
+  const snow = clamp(u.uSnowCover.mul(u.uSnowRetention).mul(snowFacing), 0, 1);
+  const snowTint = u.uStyleWeatherResponseSnowTint.mul(mix(
+    u.uStyleWeatherResponseSnowShadowStrength,
+    1,
+    visibility,
+  ));
+  colorNode.assign(mix(colorNode, snowTint, snow));
+
+  return { band, color: colorNode, normal: styledNormal, visibility, viewDirection };
+}
+
+export function tagVegetationRole(material, role, variant) {
+  const roles = Object.freeze([...new Set((Array.isArray(role) ? role : [role]).filter(Boolean))]);
+  material.userData.toonlabVegetation = Object.freeze({
+    role: roles[0] ?? '',
+    roles,
+    variant,
+    version: 1,
+  });
+  return material;
+}

package/src/shaders-tsl/chunks/water-shore-state.js

@@ -0,0 +1,31 @@
+// World-anchored persistent shoreline state shared by water foam and wet
+// terrain materials. RGBA = moisture, surface film, active foam, residue.
+
+import {
+  clamp,
+  smoothstep,
+  vec2,
+} from 'three/tsl';
+
+export function createWaterShoreStateChunk({ u }) {
+  const shoreStateUv = (worldXZ) => worldXZ
+    .sub(u.uShoreStateRegion.xy)
+    .div(u.uShoreStateRegion.zw.mul(2.0))
+    .add(0.5);
+
+  const shoreStateSample = (worldXZ) => {
+    const fieldUv = shoreStateUv(worldXZ).toVar();
+    // Fade over two percent of the atlas instead of revealing a rectangular
+    // edge when a world uses a finite shore-state tile.
+    const border = smoothstep(vec2(0.0), vec2(0.02), fieldUv)
+      .mul(smoothstep(vec2(0.98), vec2(1.0), fieldUv).oneMinus());
+    const mask = border.x.mul(border.y).mul(u.uUseShoreState).toVar();
+    return u.uShoreStateMap
+      .sample(clamp(fieldUv, vec2(0.0), vec2(1.0)))
+      .level(0)
+      .mul(mask)
+      .toVar();
+  };
+
+  return { shoreStateSample, shoreStateUv };
+}

package/src/shaders-tsl/chunks/water-waves.js

@@ -13,6 +13,8 @@
 // The GLSL `i < 2 ? 1.0 : chopWeight` slot filter is a JS-side ternary per
 // unrolled iteration — slots 0/1 (the dominant swell / set-beat pair) always
 // pass at full strength, the shorter cross chop fades toward the surf zone.
+// That amplitude filter is independent of nearshore phase applicability:
+// slot 1 only shares q when WaterSurface marks it as an authored beat partner.
 
 import {
   clamp,
@@ -20,6 +22,8 @@ import {
   cos,
   dot,
   float,
+  fract,
+  mix,
   normalize,
   sin,
   vec3,
@@ -28,9 +32,42 @@ import {
 export function createWaterWavesChunk({ wavesA, wavesB, waveCount }) {
   const count = Math.max(1, Math.trunc(waveCount));
 
+  // The primary swell and an eligible set-beat partner can replace their
+  // deep-water plane coordinate with a CPU-baked mild-slope phase field.
+  // `waveVector` is grad(q), in
+  // multiples of the offshore wave number; it therefore supplies both the
+  // refracted propagation direction and the shortened shallow wavelength.
+  // This is a JS-side branch while the node graph is built, so the six short
+  // cross-wave slots keep their original graph and cost.
+  const spatialPhaseFrame = (slot, direction, restXZ, nearshore) => {
+    const baseCoordinate = dot(direction, restXZ);
+    if (!nearshore || slot >= 2) {
+      return {
+        coordinate: baseCoordinate,
+        gradient: direction,
+        orbitDirection: direction,
+      };
+    }
+    // slotMask: 0 = disabled, 1 = primary only, 2 = same-direction beat pair.
+    // Encoding both applicability bits in the existing attribute channel
+    // avoids another varying/uniform and keeps cross-running slot 1 on its
+    // authored plane phase when Wave Set Strength is zero.
+    const slotMask = nearshore.slotMask ?? float(2.0);
+    const slotWeight = slot === 0
+      ? clamp(slotMask, 0.0, 1.0)
+      : clamp(slotMask.sub(1.0), 0.0, 1.0);
+    const blend = nearshore.blend.mul(slotWeight).toVar();
+    const gradient = mix(direction, nearshore.waveVector, blend).toVar();
+    return {
+      coordinate: mix(baseCoordinate, nearshore.phaseCoordinate, blend),
+      gradient,
+      orbitDirection: normalize(gradient),
+    };
+  };
+
   // vec3 displacement of the rest position; chopWeight ∈ [0,1] filters the
   // short cross-running components (1 = full open-water spectrum).
-  const gerstnerDisplacementFiltered = (restXZ, time, chopWeight) => {
+  const gerstnerDisplacementFiltered = (restXZ, time, chopWeight, nearshore = null) => {
     const displacement = vec3(0.0).toVar();
     for (let i = 0; i < count; i += 1) {
       const a = wavesA.element(i).toVar();
@@ -41,20 +78,48 @@ export function createWaterWavesChunk({ wavesA, wavesB, waveCount }) {
       const amplitude = (i < 2 ? b.x : b.x.mul(chopWeight)).toVar();
       const phase = b.y;
       const steepness = b.z;
-      const theta = waveNumber.mul(dot(direction, restXZ)).sub(omega.mul(time)).add(phase).toVar();
+      const phaseFrame = spatialPhaseFrame(i, direction, restXZ, nearshore);
+      const theta = waveNumber.mul(phaseFrame.coordinate)
+        .sub(omega.mul(time)).add(phase).toVar();
       const sinTheta = sin(theta);
       const cosTheta = cos(theta);
       displacement.y.addAssign(amplitude.mul(sinTheta));
-      displacement.xz.addAssign(direction.mul(steepness.mul(amplitude).mul(cosTheta)));
+      displacement.xz.addAssign(
+        phaseFrame.orbitDirection.mul(steepness.mul(amplitude).mul(cosTheta)),
+      );
     }
     return displacement;
   };
 
   const gerstnerDisplacement = (restXZ, time) => gerstnerDisplacementFiltered(restXZ, time, float(1.0));
 
+  // Vertical signal of the two long swell slots that survive into the surf
+  // zone. Swash evaluates this at the projected rest shoreline rather than at
+  // every beach vertex, so one arriving swell produces one connected edge.
+  const gerstnerSwellHeight = (restXZ, time, nearshore = null) => {
+    const height = float(0.0).toVar();
+    for (let i = 0; i < Math.min(2, count); i += 1) {
+      const a = wavesA.element(i).toVar();
+      const b = wavesB.element(i).toVar();
+      const phaseFrame = spatialPhaseFrame(i, a.xy, restXZ, nearshore);
+      const theta = a.w.mul(phaseFrame.coordinate).sub(a.z.mul(time)).add(b.y).toVar();
+      height.addAssign(b.x.mul(sin(theta)));
+    }
+    return height;
+  };
+
+  // 0..1 cycle of the dominant crest at the rest shoreline. Cycle zero is
+  // the instant that crest reaches the shoreline, so the breaker can hand
+  // directly into uprush instead of looking like an unrelated animation.
+  const primarySwellCycle = (time) => {
+    const a = wavesA.element(0).toVar();
+    const b = wavesB.element(0).toVar();
+    return fract(a.z.mul(time).sub(b.y).add(Math.PI * 0.5).div(Math.PI * 2));
+  };
+
   // Analytic surface frame at the rest position plus the 0..1 crest factor
   // used for whitecap foam (GLSL `out float crest` → returned alongside).
-  const gerstnerNormalFiltered = (restXZ, time, chopWeight) => {
+  const gerstnerNormalFiltered = (restXZ, time, chopWeight, nearshore = null) => {
     const tangent = vec3(1.0, 0.0, 0.0).toVar();
     const bitangent = vec3(0.0, 0.0, 1.0).toVar();
     const crestSum = float(0.0).toVar();
@@ -69,16 +134,28 @@ export function createWaterWavesChunk({ wavesA, wavesB, waveCount }) {
       const phase = b.y;
       const steepness = b.z;
       const crestWeight = b.w;
-      const theta = waveNumber.mul(dot(direction, restXZ)).sub(omega.mul(time)).add(phase).toVar();
+      const phaseFrame = spatialPhaseFrame(i, direction, restXZ, nearshore);
+      const theta = waveNumber.mul(phaseFrame.coordinate)
+        .sub(omega.mul(time)).add(phase).toVar();
       const sinTheta = sin(theta).toVar();
       const cosTheta = cos(theta).toVar();
       const waveKA = waveNumber.mul(amplitude).toVar();
-      tangent.x.subAssign(steepness.mul(direction.x).mul(direction.x).mul(waveKA).mul(sinTheta));
-      tangent.y.addAssign(direction.x.mul(waveKA).mul(cosTheta));
-      tangent.z.subAssign(steepness.mul(direction.x).mul(direction.y).mul(waveKA).mul(sinTheta));
-      bitangent.x.subAssign(steepness.mul(direction.x).mul(direction.y).mul(waveKA).mul(sinTheta));
-      bitangent.y.addAssign(direction.y.mul(waveKA).mul(cosTheta));
-      bitangent.z.subAssign(steepness.mul(direction.y).mul(direction.y).mul(waveKA).mul(sinTheta));
+      const phaseGradient = phaseFrame.gradient;
+      const orbitDirection = phaseFrame.orbitDirection;
+      tangent.x.subAssign(
+        steepness.mul(orbitDirection.x).mul(phaseGradient.x).mul(waveKA).mul(sinTheta),
+      );
+      tangent.y.addAssign(phaseGradient.x.mul(waveKA).mul(cosTheta));
+      tangent.z.subAssign(
+        steepness.mul(orbitDirection.y).mul(phaseGradient.x).mul(waveKA).mul(sinTheta),
+      );
+      bitangent.x.subAssign(
+        steepness.mul(orbitDirection.x).mul(phaseGradient.y).mul(waveKA).mul(sinTheta),
+      );
+      bitangent.y.addAssign(phaseGradient.y.mul(waveKA).mul(cosTheta));
+      bitangent.z.subAssign(
+        steepness.mul(orbitDirection.y).mul(phaseGradient.y).mul(waveKA).mul(sinTheta),
+      );
       const crestPeak = sinTheta.mul(0.5).add(0.5).toVar();
       crestSum.addAssign(crestWeight.mul(amplitude).mul(crestPeak).mul(crestPeak));
       crestTotal.addAssign(crestWeight.mul(amplitude));
@@ -96,5 +173,7 @@ export function createWaterWavesChunk({ wavesA, wavesB, waveCount }) {
     gerstnerDisplacementFiltered,
     gerstnerNormal,
     gerstnerNormalFiltered,
+    gerstnerSwellHeight,
+    primarySwellCycle,
   };
 }

package/src/shaders-tsl/environment.js

@@ -80,6 +80,7 @@ import { applySaturation, envLuma, windowPaneMask } from './chunks/environment-c
 import { environmentDebugColor } from './chunks/environment-debug.js';
 import { createEnvironmentLightingChunk } from './chunks/environment-lighting.js';
 import { sampleEnvironmentSunShadow } from './chunks/environment-sun-shadow.js';
+import { projectedWaterCaustics } from './chunks/projected-water-caustics.js';
 import { stylizedCloudShadow } from './chunks/stylized-cloud-shadow.js';
 import { toonSceneLights } from './chunks/character-scene-lights.js';
 
@@ -162,6 +163,11 @@ export function createEnvironmentNodeMaterial({
     lightingInfluence: uniform(hasSun ? 1.0 : 0.36),
     saturation: uniform(1.12),
     shadowLift: uniform(hasSun ? 0.0 : 0.66),
+    // How much of the CAST sun shadow applies to direct light. 1 = classic
+    // full-depth shadows. Worlds whose look runs near-zero ambient (the
+    // vivid outdoor presets) crush building-scale shadow masses to black at
+    // 1.0 — ~0.7 keeps them as painted mid-tones instead.
+    sunShadowStrength: uniform(1.0),
     skyTintStrength: uniform(0.24),
     emissiveStrength: uniform(hasSun ? 0.0 : isEmissive ? 0.55 : 0.0),
     sunBoost: uniform(hasSun ? 0.08 : 0.0),
@@ -526,7 +532,7 @@ export function createEnvironmentNodeMaterial({
     const sampledSunShadow = sampleEnvironmentSunShadow(vWorldPosition).toVar();
     const sunlightVisibility = float(1.0).toVar();
     If(u.enableShadowMask.greaterThan(0.5), () => {
-      sunlightVisibility.assign(sampledSunShadow);
+      sunlightVisibility.assign(mix(1.0, sampledSunShadow, u.sunShadowStrength));
     });
     // Drifting procedural cloud shadows over outdoor terrain; strength
     // defaults to 0 so indoor scenes are untouched.
@@ -688,6 +694,14 @@ export function createEnvironmentNodeMaterial({
       });
     }
 
+    // When the camera is below an active WaterSurface, the seabed is drawn
+    // directly instead of being seen through the water material. Receive the
+    // same moving sunlight here; the shared updater keeps this inert above
+    // water, where the surface shader already composites its own caustics.
+    color.addAssign(
+      projectedWaterCaustics(vWorldPosition, normalWorld).mul(sunlightVisibility),
+    );
+
     color.assign(applySaturation(color.mul(u.exposure), u.saturation));
 
     // World-height fog: dense near the environment floor, fading with height.