@call-me-sensei/toonlab 0.4.21 → 0.4.23

package/src/water/waterSettings.js

@@ -340,9 +340,9 @@ const WATER_PRESETS = Object.freeze({
     whitecapAmount: 0.08,
   }),
   coast: Object.freeze({
-    waveIntensity: 0.5,
-    waveAmplitude: 0.42,
-    waveLength: 9.0,
+    waveIntensity: 0.6,
+    waveAmplitude: 0.65,
+    waveLength: 18.0,
     // Onshore swell: surf only exists when waves travel toward the shallows.
     waveDirection: [0.15, -1.0],
     waveDirectionSpread: 0.5,
@@ -603,8 +603,9 @@ export function createWaterSettings(options = {}) {
   // `detailNormalStrength` or `reflectionStrength` alongside `colorTone:
   // 'anime'` was silently inert, which is exactly what §6.4 of the launch spec
   // asks for and could not get (D19-005). Callers that pass nothing are
-  // unaffected — they still resolve to the tone value, byte for byte.
-  const toneScalar = (key) => (source[key] === undefined ? tone[key] : source[key]);
+  // resolved from the authored style recipe, then the tone recommendation.
+  const styleRecipe = styleEntry?.presets?.[preset] ?? styleEntry?.scenarios?.[preset] ?? {};
+  const toneScalar = (key) => source[key] ?? styleRecipe[key] ?? tone[key];
 
   const quality = WATER_QUALITY_LEVELS.includes(String(source.quality).toLowerCase())
     ? String(source.quality).toLowerCase()
@@ -806,15 +807,6 @@ export function buildGerstnerWaves(settings) {
     });
   }
 
-  // Gerstner surfaces self-intersect when the summed steepness exceeds 1.
-  // Normalize so the whole stack stays stable at any dial position.
-  const steepnessSum = waves.reduce(
-    (sum, wave) => sum + wave.steepness * wave.waveNumber * wave.amplitude, 0);
-  if (steepnessSum > 0.9) {
-    const scale = 0.9 / steepnessSum;
-    for (const wave of waves) wave.steepness *= scale;
-  }
-
   // Wave sets: real swell arrives in groups — the big waves come minutes
   // apart, not every period. Splitting the primary component into a beat
   // pair (slots 0 and 1: same direction, slightly different frequency) makes
@@ -826,19 +818,43 @@ export function buildGerstnerWaves(settings) {
   const setStrength = resolved.waveSetStrength;
   if (setStrength > 0.001 && waves.length >= 2) {
     const primary = waves[0];
-    const beatOmega = primary.omega + (2 * Math.PI) / Math.max(resolved.waveSetPeriod, 1);
-    const speedScale = Math.max(resolved.waveSpeed, 1e-3);
+    // Detune in intrinsic frequency, then apply the common time scale.
+    // The old fixed omega offset kept the beat moving at speed=0 and made
+    // k explode as speed approached zero. A group requires nearby frequencies.
+    const intrinsicOmega = Math.sqrt(9.81 * primary.waveNumber);
+    const speedScale = resolved.waveSpeed;
+    const detuning = Math.min(
+      (2 * Math.PI) / (Math.max(resolved.waveSetPeriod, 1) * Math.max(speedScale, 1e-3)),
+      intrinsicOmega * 0.25,
+    );
+    const beatIntrinsicOmega = intrinsicOmega + detuning;
+    const beatOmega = beatIntrinsicOmega * speedScale;
     const beat = {
       ...primary,
       amplitude: primary.amplitude * setStrength * 0.5,
       omega: beatOmega,
-      waveNumber: (beatOmega / speedScale) ** 2 / 9.81,
+      waveNumber: beatIntrinsicOmega ** 2 / 9.81,
       phase: primary.phase + 2.39,
     };
     primary.amplitude *= 1 - setStrength * 0.5;
     waves.pop(); // drop the smallest tail component to keep the count fixed
     waves.splice(1, 0, beat);
   }
+  // Budget the FINAL spectrum, including its beat partner. Per-component
+  // ka limits alone allow eight individually legal waves to form spike-like
+  // sums. Stretch the spectrum together, preserving height and relative
+  // wavelengths, with a conservative aggregate slope budget (not a breaking
+  // law). Recompute frequencies through gravity-wave dispersion.
+  const slopeSum = waves.reduce((sum, wave) => sum + wave.waveNumber * wave.amplitude, 0);
+  const stretch = Math.max(1, slopeSum / 0.8);
+  for (const wave of waves) {
+    wave.waveNumber /= stretch;
+    wave.omega = Math.sqrt(9.81 * wave.waveNumber) * resolved.waveSpeed;
+  }
+  const steepnessSum = waves.reduce(
+    (sum, wave) => sum + wave.steepness * wave.waveNumber * wave.amplitude, 0);
+  const chopScale = Math.min(1, 0.85 / Math.max(steepnessSum, 1e-8));
+  for (const wave of waves) wave.steepness *= chopScale;
   return waves;
 }
 
@@ -1000,6 +1016,15 @@ export function sampleSwashCycleVariation(cycleIndex) {
   };
 }
 
+// Numerical extinction near zero forcing. This does not turn the authored
+// run-up animation into a hydrodynamic solver; it prevents a dry/flat spectrum
+// from driving a full-distance swash event. Fade over the last 5 cm of summed
+// amplitude so the limit is continuous instead of an on/off snap.
+function swashActivity(waves) {
+  const amplitude = (waves ?? []).reduce((sum, wave) => sum + Math.abs(wave.amplitude), 0);
+  return THREE.MathUtils.smoothstep(amplitude, 0, 0.05);
+}
+
 // Continuous centerline position of the swash edge in metres along the beach.
 // Event N begins exactly at event N-1's rundown endpoint, rises to its own
 // varying inland maximum, then drains to a new endpoint without a reset jump.
@@ -1009,9 +1034,9 @@ export function sampleSwashDistance(waves, time, runupDistance, uprushFraction =
   const previous = sampleSwashCycleVariation(sequence.index - 1);
   const progress = shapeSwashProgress(sequence.cycle, uprushFraction);
   const peak = Math.max(Number(runupDistance) || 0, 0) * current.runupScale;
-  return sequence.cycle <= uprushFraction
+  return swashActivity(waves) * (sequence.cycle <= uprushFraction
     ? THREE.MathUtils.lerp(previous.rundownOffset, peak, progress)
-    : THREE.MathUtils.lerp(current.rundownOffset, peak, progress);
+    : THREE.MathUtils.lerp(current.rundownOffset, peak, progress));
 }
 
 // One CPU-authored frame shared by the visible swash and the persistent
@@ -1036,6 +1061,7 @@ export function sampleSwashFrameState(
     shapeSwashProgress(afterSequence.cycle, uprushFraction) -
     shapeSwashProgress(beforeSequence.cycle, uprushFraction)
   ) / (derivativeStep * 2);
+  const activity = swashActivity(waves);
   const maximumDistance = Math.max(Number(runupDistance) || 0, 0);
   const edgeDistance = maximumDistance > 0
     ? sampleSwashDistance(waves, time, maximumDistance, uprushFraction)
@@ -1057,9 +1083,10 @@ export function sampleSwashFrameState(
     primaryDirectionZ: waves?.[0]?.dirZ ?? -1,
     progress,
     progressSpeed,
-    runupScale: current.runupScale,
-    startOffset: previous.rundownOffset,
-    endOffset: current.rundownOffset,
+    activity,
+    runupScale: current.runupScale * activity,
+    startOffset: previous.rundownOffset * activity,
+    endOffset: current.rundownOffset * activity,
     edgeShape,
   };
 }
@@ -1125,7 +1152,7 @@ export const WATER_SETTING_GROUPS = Object.freeze([
 const FIELD_METADATA = {
   waveIntensity: { group: 'waves', label: 'Wave Intensity', min: 0, max: 1, step: 0.01, description: 'Authored baseline from glassy mirror (0) to storm swell (1); scene weather can transiently modulate it without changing the preset.' },
   waterLevel: { group: 'waves', label: 'Water Level', min: 0, max: 4, step: 0.01, description: 'World-space rest height of the surface; waves and run-up displace around it.' },
-  waveAmplitude: { group: 'waves', label: 'Wave Amplitude', min: 0, max: 5, step: 0.01, description: 'Largest wave amplitude in meters at full intensity; 5 gives a 10 m crest-to-trough swell.' },
+  waveAmplitude: { group: 'waves', label: 'Wave Amplitude', min: 0, max: 5, step: 0.01, description: 'Primary amplitude in meters at full intensity, before splitting into a wave set. The combined surface includes smaller waves; its wavelengths lengthen to keep slopes bounded.' },
   shoalingDepth: { group: 'waves', label: 'Shoaling Depth', min: 0.05, max: 12, step: 0.05, description: 'Column depth in meters at which waves reach full height; shallower water shrinks them (needs a bed height sampler).' },
   shorelineWaves: { group: 'waves', label: 'Shoreline Waves', min: 0, max: 1, step: 0.01, description: 'Fraction of wave height that keeps rolling through the shallows as surf before dying at the waterline.' },
   shorelineRunup: { group: 'waves', label: 'Shoreline Run-up', min: 0, max: 3, step: 0.05, description: 'How far incoming waves wash a thin foam film up the beach; reach scales with wave energy.' },
@@ -1140,7 +1167,7 @@ const FIELD_METADATA = {
   waveSpeed: { group: 'waves', label: 'Wave Speed', min: 0, max: 4, step: 0.01, description: 'Phase speed multiplier over the deep-water dispersion.' },
   waveDirection: { group: 'waves', label: 'Wave Direction', type: 'vector2', description: 'Main travel direction of the swell in the XZ plane.' },
   waveDirectionSpread: { group: 'waves', label: 'Direction Spread', min: 0, max: 1, step: 0.01, description: '0 keeps all waves aligned (river); 1 spreads them omnidirectionally (open sea). The primary swell always follows Wave Direction exactly.' },
-  waveSetPeriod: { group: 'waves', label: 'Set Period (s)', min: 8, max: 600, step: 1, description: 'Seconds between wave-set peaks at a fixed point; big waves arrive in groups, not every period.' },
+  waveSetPeriod: { group: 'waves', label: 'Set Period (s)', min: 8, max: 600, step: 1, description: 'Requested minimum interval between wave-set peaks. Stability limits and slow motion can lengthen it.' },
   waveSetStrength: { group: 'waves', label: 'Set Strength', min: 0, max: 1, step: 0.01, description: 'Depth of the set/lull cycle: 0 = constant swell, 1 = the swell dies completely between sets.' },
   detailNormalStrength: { group: 'waves', label: 'Detail Normals', min: 0, max: 2, step: 0.01, description: 'Strength of the procedural micro-ripple normal detail.' },
   detailScale: { group: 'waves', label: 'Detail Scale', min: 0.05, max: 8, step: 0.05, description: 'Spatial frequency of the micro-ripple detail.' },
@@ -1172,7 +1199,7 @@ const FIELD_METADATA = {
   indexOfRefraction: { group: 'surface', label: 'Water IOR', min: 1.0001, max: 1.8, step: 0.001, description: 'Index of refraction used by the underwater Snell window and total internal reflection.' },
   underwaterTransmission: { group: 'surface', label: 'Underwater View', min: 0, max: 1, step: 0.01, description: 'Visibility of the real above-water scene through the surface from below.' },
   underwaterTintStrength: { group: 'surface', label: 'Underwater Tint', min: 0, max: 1, step: 0.01, description: 'Stylized water-color tint applied to the view through the surface.' },
-  causticsStrength: { group: 'surface', label: 'Caustics', min: 0, max: 3, step: 0.01, description: 'Brightness of the procedural voronoi caustics on the bottom.' },
+  causticsStrength: { group: 'surface', label: 'Caustics', min: 0, max: 3, step: 0.01, description: 'Brightness of focused sunlight on the submerged bed. The dynamics path derives focusing from the water normals.' },
   causticsScale: { group: 'surface', label: 'Caustics Scale', min: 0.05, max: 8, step: 0.05, description: 'Spatial frequency of the caustic web.' },
   causticsSpeed: { group: 'surface', label: 'Caustics Speed', min: 0, max: 4, step: 0.01, description: 'Animation speed of the caustic web.' },
 
@@ -1654,7 +1681,7 @@ registerWaterStyle('call_me_sensei', {
   presets: {
     lake: { flowSpeed: 0.4, sparkleStrength: 0.55, waveIntensity: 0.32 },
     river: { flowSpeed: 1.15, foamLineSpacing: 0.38, sparkleStrength: 0.45, waveIntensity: 0.3 },
-    coast: { flowSpeed: 0.45, swashFoamAmount: 1.4, sparkleStrength: 0.5, waveIntensity: 0.5 },
+    coast: { flowSpeed: 0.45, swashFoamAmount: 1.4, causticsStrength: 1.25, sparkleStrength: 0, waveIntensity: 0.6 },
     ocean: { flowSpeed: 0.5, sparkleStrength: 0.7, waveIntensity: 0.7, whitecapAmount: 0.45 },
   },
 });

package/src/water/waterShoreMaterial.js

@@ -2,6 +2,7 @@ import * as THREE from 'three';
 
 import { MeshPhysicalNodeMaterial } from 'three/webgpu';
 import {
+  abs,
   clamp,
   float,
   luminance,
@@ -21,6 +22,7 @@ import {
 } from 'three/tsl';
 
 import { projectedWaterCaustics } from '../shaders-tsl/chunks/projected-water-caustics.js';
+import { getWaterFoamTexture } from './waterFoamTexture.js';
 import { sampleEnvironmentSunShadow } from '../shaders-tsl/chunks/environment-sun-shadow.js';
 import { sampleEnvironmentCloudShadow } from '../sky/cloudShadow.js';
 
@@ -145,6 +147,11 @@ export function updateWaterShoreMaterial(material, {
   if (stateField !== undefined) material.userData.waterShoreStateField = stateField;
   const field = material.userData.waterShoreStateField ?? null;
   uniforms.uShoreStateMap.value = resolveStateTexture(field);
+  uniforms.uShoreFoamCoordinates.value = field?.foamCoordinateTexture ?? getFallbackStateTexture();
+  if (uniforms.uShoreSolvedDepth) uniforms.uShoreSolvedDepth.value = field?.isWaterDynamics ? 1 : 0;
+  if (uniforms.uShoreContinuation) uniforms.uShoreContinuation.value.set(
+    field?.level ?? 0, field?.options?.renderExtent && field?.mode === 'coast' ? 1 : 0,
+  );
   resolveStateRegion(field, regionScratch);
   uniforms.uShoreStateRegion.value.copy(regionScratch);
 
@@ -184,6 +191,10 @@ export function createWaterShoreMaterial({
 } = {}) {
   const uniforms = {
     uShoreStateMap: texture(getFallbackStateTexture()),
+    uShoreFoamCoordinates: texture(getFallbackStateTexture()),
+    uShoreFoamBubbles: texture(getWaterFoamTexture()),
+    uShoreSolvedDepth: uniform(0),
+    uShoreContinuation: uniform(new THREE.Vector2(0,0)),
     // (centerX, centerZ, halfWidth, halfDepth), matching the ripple-region
     // convention used by the rest of the water system.
     uShoreStateRegion: uniform(new THREE.Vector4(0, 0, 0.5, 0.5)),
@@ -198,17 +209,31 @@ export function createWaterShoreMaterial({
     .sub(uniforms.uShoreStateRegion.xy)
     .div(max(uniforms.uShoreStateRegion.zw.mul(2.0), vec2(1e-3)))
     .add(0.5);
-  const inside = step(0.0, fieldUv.x).mul(step(fieldUv.x, 1.0))
+  const insideX = step(0.0, fieldUv.x).mul(step(fieldUv.x, 1.0));
+  const inside = mix(insideX,1.0,uniforms.uShoreContinuation.y)
     .mul(step(0.0, fieldUv.y)).mul(step(fieldUv.y, 1.0));
   // State render targets have no mip chain. Explicit level zero is required
   // by WGSL in non-uniform control flow and is harmless on the GLSL builder.
-  const state = uniforms.uShoreStateMap
+  const rawState = uniforms.uShoreStateMap
     .sample(clamp(fieldUv, vec2(0.0), vec2(1.0)))
-    .level(0)
-    .mul(inside);
+    .level(0);
+  const state = rawState.mul(inside);
+  const boundedUv=clamp(fieldUv,vec2(0),vec2(1));
+  const foamCoordinates=uniforms.uShoreFoamCoordinates.sample(boundedUv).level(0).rg
+    .add(fieldUv.sub(boundedUv).mul(uniforms.uShoreStateRegion.zw).mul(2));
+  const foamBubbles=uniforms.uShoreFoamBubbles.sample(foamCoordinates.div(.72));
+
+  // Submerged continuation cannot suddenly become dry sand at the atlas
+  // boundary. Carry boundary moisture outward, tending to rest submersion.
+  const outside = max(abs(positionWorld.xz.sub(uniforms.uShoreStateRegion.xy))
+    .sub(uniforms.uShoreStateRegion.zw),vec2(0.0));
+  const nearBoundary = smoothstep(0.0,80.0,max(outside.x,outside.y)).oneMinus();
+  const restWet = smoothstep(0.002,0.04,uniforms.uShoreContinuation.x.sub(positionWorld.y));
+  const continuationWet = max(restWet,rawState.r.mul(nearBoundary))
+    .mul(inside.oneMinus()).mul(uniforms.uShoreContinuation.y);
 
-  const moisture = clamp(state.r, 0.0, 1.0);
-  const film = clamp(state.g, 0.0, 1.0);
+  const moisture = clamp(max(state.r,continuationWet), 0.0, 1.0);
+  const film = clamp(max(mix(state.g, state.g.div(0.04), uniforms.uShoreSolvedDepth),continuationWet), 0.0, 1.0);
   const foamAmountNode = clamp(uniforms.uShoreFoamAmount, 0.0, 2.0);
   const activeFoam = clamp(state.b, 0.0, 1.0);
   const residue = clamp(state.a, 0.0, 1.0);
@@ -270,7 +295,7 @@ export function createWaterShoreMaterial({
     visibleActiveFoam.mul(0.72).add(visibleResidue.mul(0.12)).mul(foamAmountNode),
     0.0,
     0.74,
-  );
+  ).mul(mix(1.0, smoothstep(0.0001, 0.0015, state.g).oneMinus().mul(foamBubbles.g.mul(.7).add(.3)), uniforms.uShoreSolvedDepth));
   const receiverVisibility = sampleEnvironmentSunShadow(positionWorld)
     .mul(sampleEnvironmentCloudShadow(positionWorld, 1))
     .toVar();
@@ -279,7 +304,7 @@ export function createWaterShoreMaterial({
     vec3(1.0),
     receiverVisibility,
   );
-  const shadowedFoamColor = uniforms.uShoreFoamColor.mul(shadowTint);
+  const shadowedFoamColor = uniforms.uShoreFoamColor.mul(shadowTint).mul(mix(1,foamBubbles.r,uniforms.uShoreSolvedDepth));
   const shoreColor = mix(wetBaseColor, shadowedFoamColor, foamCoverage)
     .mul(shadowTint);
 
@@ -301,12 +326,11 @@ export function createWaterShoreMaterial({
 
   const material = new MeshPhysicalNodeMaterial({ vertexColors: false });
   material.name = 'WaterShoreMaterial';
-  // Fold the underwater light into albedo instead of assigning emissiveNode.
-  // Some node backends replace the normal lit path when an otherwise-zero
-  // custom emissive graph is present, which made the dry beach charcoal while
-  // the camera was above water. The shared enabled uniform keeps this addend
-  // exactly zero outside the underwater pass.
-  material.colorNode = shoreColor.add(
+  material.colorNode = shoreColor;
+  // Focused sunlight is extra incident illumination, not a brighter sand
+  // pigment. Keeping it out of albedo preserves its contrast under tone
+  // mapping and avoids multiplying it by the ordinary sun a second time.
+  material.emissiveNode = shoreColor.mul(
     projectedWaterCaustics(positionWorld, normalWorld).mul(receiverVisibility),
   );
   material.metalnessNode = float(0.0);

package/src/water/waterSpectralOcean.js

@@ -0,0 +1,137 @@
+// Independent spectral ocean implementation: seeded Gaussian amplitudes,
+// JONSWAP-shaped directional frequency density and finite-depth dispersion.
+// Three non-overlapping wave-number bands. FFT evaluates the linear wave
+// solution; it is not a nonlinear overturning/breaking solver.
+const TAU = 2 * Math.PI;
+const G = 9.81;
+function random(seed) { let s = seed >>> 0; return () => { s = (Math.imul(1664525, s) + 1013904223) >>> 0; return (s + 0.5) / 4294967296; }; }
+export function inverseFFT2D(real, imaginary, size) {
+    const line = (offset, stride) => {
+        for (let i = 1, j = 0; i < size; i++) {
+            let bit = size >> 1;
+            for (; j & bit; bit >>= 1)
+                j ^= bit;
+            j ^= bit;
+            if (i < j) {
+                const a = offset + i * stride, b = offset + j * stride;
+                let temp = real[a];
+                real[a] = real[b];
+                real[b] = temp;
+                temp = imaginary[a];
+                imaginary[a] = imaginary[b];
+                imaginary[b] = temp;
+            }
+        }
+        for (let len = 2; len <= size; len <<= 1) {
+            const wr0 = Math.cos(TAU / len), wi0 = Math.sin(TAU / len);
+            for (let start = 0; start < size; start += len) {
+                let wr = 1, wi = 0;
+                for (let j = 0; j < len / 2; j++) {
+                    const a = offset + (start + j) * stride, b = offset + (start + j + len / 2) * stride;
+                    const tr = real[b] * wr - imaginary[b] * wi, ti = real[b] * wi + imaginary[b] * wr;
+                    real[b] = real[a] - tr;
+                    imaginary[b] = imaginary[a] - ti;
+                    real[a] += tr;
+                    imaginary[a] += ti;
+                    const next = wr * wr0 - wi * wi0;
+                    wi = wr * wi0 + wi * wr0;
+                    wr = next;
+                }
+            }
+        }
+    };
+    for (let z = 0; z < size; z++)
+        line(z * size, 1);
+    for (let x = 0; x < size; x++)
+        line(x, size);
+    const norm = 1 / (size * size);
+    for (let i = 0; i < real.length; i++) {
+        real[i] *= norm;
+        imaginary[i] *= norm;
+    }
+}
+export class WaterSpectralOcean {
+    constructor({ resolution = 64, seed = 731 } = {}) {
+        if (resolution < 8 || (resolution & (resolution - 1)))
+            throw new RangeError('FFT resolution must be a power of two');
+        this.resolution = resolution;
+        this.seed = seed;
+        this.bands = [];
+        this.signature = '';
+        this.time = 0;
+    }
+    configure(settings, depth = 20, minWavelength = 0) {
+        const { waveAmplitude = 0.3, waveIntensity = 0.3, waveLength = 13, waveDirection = [1, 0], waveDirectionSpread = 0.5 } = settings;
+        const peakLength = Math.max(waveLength, waveAmplitude * Math.pow(waveIntensity, 1.35) * TAU / 0.18, 2);
+        const signature = JSON.stringify([peakLength, waveAmplitude, waveIntensity, waveDirection, waveDirectionSpread, depth, minWavelength]);
+        if (signature === this.signature)
+            return;
+        this.signature = signature;
+        const targetRms = waveAmplitude * Math.pow(waveIntensity, 1.35) * 0.707;
+        const n = this.resolution, dk0 = TAU / (peakLength * 8), kp = TAU / peakLength;
+        const direction = Math.atan2(waveDirection[1], waveDirection[0]);
+        this.bands = [];
+        // Separate k ranges avoid counting the same energy in several cascades.
+        for (let band = 0; band < 3; band++) {
+            const length = peakLength * 8 / Math.pow(4, band), dk = TAU / length, rand = random(this.seed + band * 101);
+            const data = { length, real: new Float64Array(n * n), imag: new Float64Array(n * n), h0r: new Float64Array(n * n), h0i: new Float64Array(n * n), omega: new Float64Array(n * n), size: n };
+            for (let z = 0; z < n; z++)
+                for (let x = 0; x < n; x++) {
+                    const i = z * n + x, kx = (x <= n / 2 ? x : x - n) * dk, kz = (z <= n / 2 ? z : z - n) * dk, k = Math.hypot(kx, kz);
+                    if (k < dk0 || k < (band === 0 ? 0 : dk * n / 16) || k >= dk * n / 4 || (minWavelength > 0 && k > TAU / minWavelength))
+                        continue;
+                    const omega = Math.sqrt(G * k * Math.tanh(k * Math.max(depth, 0.2))), wp = Math.sqrt(G * kp * Math.tanh(kp * Math.max(depth, 0.2)));
+                    const sigma = omega <= wp ? 0.07 : 0.09, r = Math.exp(-((omega / wp - 1) ** 2) / (2 * sigma * sigma));
+                    const density = Math.pow(omega, -5) * Math.exp(-1.25 * Math.pow(wp / omega, 4)) * Math.pow(3.3, r);
+                    const c = Math.cos(Math.atan2(kz, kx) - direction);
+                    const directional = Math.pow(Math.max(c, 0), 2 + 14 * (1 - waveDirectionSpread)) + 0.015 * waveDirectionSpread;
+                    const kh = k * Math.max(depth, 0.2), t = Math.tanh(kh);
+                    const derivative = G * (t + kh * (1 - t * t)) / (2 * omega);
+                    const amplitude = Math.sqrt(Math.max(density * directional * derivative / k * dk * dk, 0));
+                    const gaussian = Math.sqrt(-2 * Math.log(rand())), phase = TAU * rand();
+                    data.h0r[i] = amplitude * gaussian * Math.cos(phase);
+                    data.h0i[i] = amplitude * gaussian * Math.sin(phase);
+                    data.omega[i] = omega;
+                }
+            this.bands.push(data);
+        }
+        const expectedVariance = this.bands.reduce((sum, b) => sum + b.h0r.reduce((a, v, i) => a + 2 * (v * v + b.h0i[i] ** 2), 0) / (n ** 4), 0);
+        const scale = targetRms / Math.sqrt(Math.max(expectedVariance, 1e-30));
+        for (const b of this.bands)
+            for (let i = 0; i < n * n; i++) {
+                b.h0r[i] *= scale;
+                b.h0i[i] *= scale;
+            }
+        this.peakLength = peakLength;
+        this.rms = targetRms;
+    }
+    update(time) {
+        this.time = time;
+        const n = this.resolution;
+        for (const b of this.bands) {
+            for (let z = 0; z < n; z++)
+                for (let x = 0; x < n; x++) {
+                    const i = z * n + x, j = ((n - z) % n) * n + (n - x) % n;
+                    // Use negative phase: an h0(k) travelling component moves along +k.
+                    const phase = b.omega[i] * time, c = Math.cos(phase), s = Math.sin(phase);
+                    const cj = c, sj = s;
+                    b.real[i] = b.h0r[i] * c + b.h0i[i] * s + b.h0r[j] * cj + b.h0i[j] * sj;
+                    b.imag[i] = b.h0i[i] * c - b.h0r[i] * s - b.h0i[j] * cj + b.h0r[j] * sj;
+                }
+            inverseFFT2D(b.real, b.imag, n);
+        }
+    }
+    sample(x, z, minWavelength = 0) {
+        let h = 0;
+        const n = this.resolution;
+        for (const b of this.bands) {
+            // Geometry excludes bands below its spatial sampling limit. Full-band
+            // normals/caustics may use sample(...,0) on their denser grid.
+            const gx = ((x / b.length % 1) + 1) % 1 * n, gz = ((z / b.length % 1) + 1) % 1 * n;
+            const ix = Math.floor(gx), iz = Math.floor(gz), tx = gx - ix, tz = gz - iz;
+            const a = iz * n + ix, bb = iz * n + (ix + 1) % n, c = ((iz + 1) % n) * n + ix, d = ((iz + 1) % n) * n + (ix + 1) % n;
+            h += (b.real[a] * (1 - tx) + b.real[bb] * tx) * (1 - tz) + (b.real[c] * (1 - tx) + b.real[d] * tx) * tz;
+        }
+        return h;
+    }
+}

package/src/water/waterStageSettings.js

@@ -5,7 +5,7 @@
 
 export const BEACH_RUNUP_DISTANCE = 10;
 export const BEACH_WATER_LEVEL = 0.36;
-export const BEACH_WAVE_SPEED = 0.35;
+export const BEACH_WAVE_SPEED = 0.65;
 export const BEACH_DIRECTION_SPREAD = 0.18;
 
 export const SHOREWARD_ORIENTATION = Object.freeze({
@@ -14,8 +14,13 @@ export const SHOREWARD_ORIENTATION = Object.freeze({
 });
 
 export function waterStageOverrides(stage, baseSettings = {}) {
+  const shoreResponse = {
+    ...(Number.isFinite(baseSettings.shorelineRunup) ? { shorelineRunup: baseSettings.shorelineRunup } : {}),
+    ...(Number.isFinite(baseSettings.breakerAmount) ? { breakerAmount: baseSettings.breakerAmount } : {}),
+  };
   if (stage === 'beach') {
     return {
+      ...shoreResponse,
       flowDirection: [...SHOREWARD_ORIENTATION.flowDirection],
       runupDistance: BEACH_RUNUP_DISTANCE,
       waterLevel: BEACH_WATER_LEVEL,
@@ -24,8 +29,20 @@ export function waterStageOverrides(stage, baseSettings = {}) {
       waveDirectionSpread: BEACH_DIRECTION_SPREAD,
     };
   }
+  if (String(stage ?? '').startsWith('river')) {
+    return {
+      flowDirection: [1, 0],
+      waveDirection: [1, 0],
+      runupDistance: 0,
+      shorelineRunup: 0,
+      breakerAmount: 0,
+      ...(Number.isFinite(baseSettings.waterLevel) ? { waterLevel: baseSettings.waterLevel } : {}),
+      ...(Number.isFinite(baseSettings.waveSpeed) ? { waveSpeed: baseSettings.waveSpeed } : {}),
+    };
+  }
   if (stage === 'shore') {
     return {
+      ...shoreResponse,
       flowDirection: [...SHOREWARD_ORIENTATION.flowDirection],
       runupDistance: 0,
       ...(Number.isFinite(baseSettings.waterLevel)
@@ -42,6 +59,7 @@ export function waterStageOverrides(stage, baseSettings = {}) {
   }
   if (stage === 'open') {
     return {
+      ...shoreResponse,
       ...(baseSettings.flowDirection ? { flowDirection: [...baseSettings.flowDirection] } : {}),
       runupDistance: 0,
       ...(Number.isFinite(baseSettings.waterLevel)