@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/src/villagegen/villageSites.js

@@ -0,0 +1,105 @@
+// POI site selection: score the terrain per archetype (flatness, dryness,
+// shore/hilltop affinities from the archetype table), then greedy-pick
+// mutually distant winners. Deterministic per seed.
+
+import { POI_ARCHETYPES } from './villageArchetypes.js';
+
+function mulberry32(seed) {
+  let state = (Math.trunc(seed) || 1) >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * @param {Object} options
+ * @param {Function} options.heightAt
+ * @param {number} [options.waterLevel]
+ * @param {number|{x,z}} [options.size]
+ * @param {number} [options.seed]
+ * @param {Array<{archetype: string, count: number, radius?: number}>} options.requests
+ * @returns {Array<{archetype, seed, x, z, radius}>}
+ */
+export function pickPoiSites({
+  heightAt,
+  waterLevel = 0,
+  size = 1000,
+  seed = 1,
+  requests = [],
+} = {}) {
+  const width = Number(size?.width ?? size?.x ?? size) || 1000;
+  const depth = Number(size?.depth ?? size?.z ?? size) || 1000;
+  const random = mulberry32(seed * 22695477 + 3);
+  const innerX = width * 0.4;
+  const innerZ = depth * 0.4;
+
+  const slopeAt = (x, z) => {
+    const step = 3;
+    const dx = (heightAt(x + step, z) - heightAt(x - step, z)) / (2 * step);
+    const dz = (heightAt(x, z + step) - heightAt(x, z - step)) / (2 * step);
+    return Math.hypot(dx, dz);
+  };
+  const shoreDistance = (x, z) => {
+    for (const reach of [6, 12, 20, 28]) {
+      for (let probe = 0; probe < 8; probe += 1) {
+        const angle = (probe / 8) * Math.PI * 2;
+        if (heightAt(x + Math.cos(angle) * reach, z + Math.sin(angle) * reach) <= waterLevel) {
+          return reach;
+        }
+      }
+    }
+    return 99;
+  };
+  const context = { heightAt, shoreDistance, slopeAt, waterLevel };
+
+  // Site flatness must hold across the whole radius, not just the center —
+  // sample a ring too.
+  const areaScore = (archetypeSpec, x, z, radius) => {
+    let score = archetypeSpec.siteScore(x, z, context);
+    if (score <= 0) return 0;
+    for (let probe = 0; probe < 4; probe += 1) {
+      const angle = (probe / 4) * Math.PI * 2 + 0.5;
+      const rx = x + Math.cos(angle) * radius * 0.6;
+      const rz = z + Math.sin(angle) * radius * 0.6;
+      const ringScore = archetypeSpec.siteScore(rx, rz, context);
+      if (ringScore <= 0) return 0;
+      score += ringScore * 0.25;
+    }
+    return score;
+  };
+
+  const picked = [];
+  for (const request of requests) {
+    const archetypeSpec = POI_ARCHETYPES[request.archetype];
+    if (!archetypeSpec) continue;
+    const radius = request.radius ?? Math.max(archetypeSpec.minRadius, 30);
+    for (let instance = 0; instance < (request.count ?? 1); instance += 1) {
+      let best = null;
+      for (let attempt = 0; attempt < 220; attempt += 1) {
+        const x = (random() * 2 - 1) * innerX;
+        const z = (random() * 2 - 1) * innerZ;
+        let clear = true;
+        for (const site of picked) {
+          const minDistance = site.radius + radius + 40;
+          if ((site.x - x) ** 2 + (site.z - z) ** 2 < minDistance ** 2) { clear = false; break; }
+        }
+        if (!clear) continue;
+        const score = areaScore(archetypeSpec, x, z, radius);
+        if (score > 0 && (!best || score > best.score)) best = { score, x, z };
+      }
+      if (!best) continue; // terrain had no room — honest miss, not a crash
+      picked.push({
+        archetype: request.archetype,
+        radius,
+        seed: Math.floor(random() * 0xffffffff),
+        x: best.x,
+        z: best.z,
+      });
+    }
+  }
+  return picked;
+}

package/src/water/sceneOverrideLayers.js

@@ -0,0 +1,23 @@
+/**
+ * Ordered transient layers for active water. Lower priorities establish a
+ * base that higher priorities can derive from or replace. Runtime policy is
+ * never serialized into a portable water preset.
+ */
+export const WATER_SCENE_OVERRIDE_PRIORITIES = Object.freeze({
+  lighting: 100,
+  weather: 200,
+  scene: 300,
+});
+
+/**
+ * Authored fallback fields that a live scene may replace without editing the
+ * portable water asset. Palette, wave structure, foam, and interaction
+ * response remain authored settings.
+ */
+export const WATER_SCENE_OVERRIDE_KEYS = Object.freeze([
+  'waveIntensity',
+  'sunDirection',
+  'sunColor',
+  'skyZenithColor',
+  'skyHorizonColor',
+]);

package/src/water/water.js

@@ -9,12 +9,17 @@
 //   water.update(renderer, scene, camera, delta);
 
 export * from './waterSettings.js';
+export * from './sceneOverrideLayers.js';
 export * from './waterMaterial.js';
+export * from './waterCurrentField.js';
+export * from './waterNearshorePhase.js';
 export * from './waterRippleSimulation.js';
 export * from './waterSplashSystem.js';
 export * from './waterBreakerSystem.js';
 export * from './waterScenePasses.js';
 export * from './waterInteraction.js';
 export * from './waterSurface.js';
+export * from './waterShoreStateField.js';
+export * from './waterShoreMaterial.js';
 export * from './waterRain.js';
 export * from './waterVegetation.js';

package/src/water/waterBreakerSystem.js

@@ -54,6 +54,20 @@ export function computeBreakingDepth(settings, waveEnergy) {
   return depth;
 }
 
+// The overhanging shell is a second water surface. It works in a substantial
+// shore/open-water column, but cannot be welded convincingly to the few-cm
+// film used by an explicit calibration swash; there it produced detached
+// foam ribbons. The main heightfield still performs depth capping and breaker
+// foam, controlled by breakerEnabled/breakerAmount.
+export function shouldUseDedicatedBreakerShell(settings, hasBedSampler = true) {
+  return Boolean(
+    hasBedSampler
+      && settings?.breakerEnabled !== false
+      && (settings?.breakerAmount ?? 0) > 0.001
+      && (settings?.runupDistance ?? 0) <= 0.01,
+  );
+}
+
 function pointKey(x, z) {
   return `${Math.round(x * 512)},${Math.round(z * 512)}`;
 }
@@ -556,7 +570,7 @@ export class WaterBreakerSystem extends THREE.Group {
         (1 - smoothstep(delta, 0.38, 0.47));
 
       const capDepth = Math.min(col.depth, localDepth);
-      const breakHeight = 0.9 * capDepth * p.scale * p.amount * col.endFade * setEnvelope;
+      const breakHeight = 0.48 * capDepth * p.scale * p.amount * col.endFade * setEnvelope;
       const H = breakHeight * THREE.MathUtils.lerp(0.12, 1, pulse) * (1 - 0.55 * post);
       const fade = p.amount * col.endFade * travelFade * setGate *
         smoothstep(pulse + post, 0.12, 0.35) * smoothstep(H, 0.05, 0.15);

package/src/water/waterCurrentField.js

@@ -0,0 +1,447 @@
+import * as THREE from 'three';
+
+const DEFAULT_MAX_SPEED = 8;
+const sampleScratch = new THREE.Vector2();
+
+function finiteOr(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
+function clamp01(value) {
+  return THREE.MathUtils.clamp(finiteOr(value, 0), 0, 1);
+}
+
+function smoothstep01(value) {
+  const x = clamp01(value);
+  return x * x * (3 - 2 * x);
+}
+
+function vector2Components(value, fallbackX = 0, fallbackZ = 0) {
+  if (Array.isArray(value)) {
+    return [finiteOr(value[0], fallbackX), finiteOr(value[1], fallbackZ)];
+  }
+  return [
+    finiteOr(value?.x ?? value?.[0], fallbackX),
+    finiteOr(value?.z ?? value?.y ?? value?.[1], fallbackZ),
+  ];
+}
+
+// Constructor regions use full width/depth. Vector4 uses the shader-facing
+// (centerX, centerZ, halfWidth, halfDepth) convention shared by ripple and
+// shoreline atlases.
+function normalizeRegion(region) {
+  if (region?.isVector4) {
+    return {
+      centerX: finiteOr(region.x, 0),
+      centerZ: finiteOr(region.y, 0),
+      width: Math.max(finiteOr(region.z, 16) * 2, 0.1),
+      depth: Math.max(finiteOr(region.w, 16) * 2, 0.1),
+    };
+  }
+  if (Array.isArray(region)) {
+    return {
+      centerX: finiteOr(region[0], 0),
+      centerZ: finiteOr(region[1], 0),
+      width: Math.max(finiteOr(region[2], 32), 0.1),
+      depth: Math.max(finiteOr(region[3], 32), 0.1),
+    };
+  }
+  if (region?.min && region?.max) {
+    const minX = finiteOr(region.min.x, -16);
+    const minZ = finiteOr(region.min.z ?? region.min.y, -16);
+    const maxX = finiteOr(region.max.x, 16);
+    const maxZ = finiteOr(region.max.z ?? region.max.y, 16);
+    return {
+      centerX: (minX + maxX) * 0.5,
+      centerZ: (minZ + maxZ) * 0.5,
+      width: Math.max(maxX - minX, 0.1),
+      depth: Math.max(maxZ - minZ, 0.1),
+    };
+  }
+  const center = region?.center;
+  const size = region?.size;
+  return {
+    centerX: finiteOr(region?.centerX ?? center?.x ?? region?.x, 0),
+    centerZ: finiteOr(region?.centerZ ?? center?.z ?? center?.y ?? region?.z, 0),
+    width: Math.max(finiteOr(
+      region?.width ?? size?.x ??
+        (Number.isFinite(region?.halfWidth) ? region.halfWidth * 2 : undefined),
+      32,
+    ), 0.1),
+    depth: Math.max(finiteOr(
+      region?.depth ?? size?.z ?? size?.y ??
+        (Number.isFinite(region?.halfDepth) ? region.halfDepth * 2 : undefined),
+      32,
+    ), 0.1),
+  };
+}
+
+function normalizeResolution(resolution) {
+  let x;
+  let y;
+  if (Number.isFinite(resolution)) {
+    x = resolution;
+    y = resolution;
+  } else if (Array.isArray(resolution)) {
+    [x, y] = resolution;
+  } else {
+    x = resolution?.x ?? resolution?.width;
+    y = resolution?.y ?? resolution?.height;
+  }
+  return {
+    x: THREE.MathUtils.clamp(Math.round(finiteOr(x, 128)), 2, 2048),
+    y: THREE.MathUtils.clamp(Math.round(finiteOr(y, 128)), 2, 2048),
+  };
+}
+
+function resolveVelocity(result, out) {
+  if (result === false || result === null) return false;
+  if (Array.isArray(result)) {
+    out.set(finiteOr(result[0], NaN), finiteOr(result[1], NaN));
+  } else if (result && result !== out) {
+    out.set(
+      finiteOr(result.x ?? result[0], NaN),
+      finiteOr(result.z ?? result.y ?? result[1], NaN),
+    );
+  }
+  return Number.isFinite(out.x) && Number.isFinite(out.y);
+}
+
+/**
+ * CPU-authored, world-space horizontal current field.
+ *
+ * The CPU retains full-precision velocity/mask arrays for gameplay queries.
+ * A compact linearly-filtered RGBA8 texture mirrors the field for lightweight
+ * GPU consumers such as shoreline-foam advection:
+ *
+ *   R/G = signed X/Z velocity encoded around 0.5
+ *   B   = fluid/obstacle weight
+ *   A   = valid authored domain
+ *
+ * This is deliberately not a shallow-water or Navier-Stokes solver. The
+ * caller authors the large-scale velocity (`velocitySampler`) and optional
+ * water-domain mask. A signed-distance sampler adds a deterministic
+ * no-penetration projection near banks/rocks, but it cannot infer circulation,
+ * pressure, wakes, separation, or downstream turbulence. Those need authored
+ * vectors, a flow-map bake, or a real fluid solver upstream.
+ *
+ * `velocitySampler(x, z, out, context)` may mutate `out` or return a Vector2,
+ * `[vx, vz]`, `{ x, z }`, `false`, or `null`. `context.time` lets a caller bake
+ * a new tidal phase. For cheap whole-field tidal reversal between bakes, use
+ * `setStrength(-1)`; CPU and GPU consumers receive the same multiplier.
+ */
+export class WaterCurrentField {
+  constructor({
+    region = {},
+    resolution = { x: 128, y: 128 },
+    velocity = [0, 0],
+    velocitySampler = null,
+    sampler = velocitySampler,
+    maskSampler = null,
+    domainMaskSampler = maskSampler,
+    signedDistanceSampler = null,
+    obstacleDistanceSampler = signedDistanceSampler,
+    obstacleInfluence = 1,
+    obstacleDeflection = 1,
+    preserveTangentialSpeed = 0.7,
+    obstacleGradientStep = null,
+    maxSpeed = DEFAULT_MAX_SPEED,
+    strength = 1,
+    time = 0,
+  } = {}) {
+    const normalizedRegion = normalizeRegion(region);
+    const normalizedResolution = normalizeResolution(resolution);
+    this.isWaterCurrentField = true;
+    this.centerX = normalizedRegion.centerX;
+    this.centerZ = normalizedRegion.centerZ;
+    this.worldWidth = normalizedRegion.width;
+    this.worldDepth = normalizedRegion.depth;
+    this.resolutionX = normalizedResolution.x;
+    this.resolutionY = normalizedResolution.y;
+    this.region = new THREE.Vector4(
+      this.centerX,
+      this.centerZ,
+      this.worldWidth * 0.5,
+      this.worldDepth * 0.5,
+    );
+    this.minX = this.centerX - this.worldWidth * 0.5;
+    this.minZ = this.centerZ - this.worldDepth * 0.5;
+    this.cellSizeX = this.worldWidth / this.resolutionX;
+    this.cellSizeZ = this.worldDepth / this.resolutionY;
+
+    const [constantX, constantZ] = vector2Components(velocity);
+    this.constantVelocity = new THREE.Vector2(constantX, constantZ);
+    this.velocitySampler = typeof sampler === 'function' ? sampler : null;
+    this.maskSampler = typeof domainMaskSampler === 'function' ? domainMaskSampler : null;
+    this.obstacleDistanceSampler = typeof obstacleDistanceSampler === 'function'
+      ? obstacleDistanceSampler
+      : null;
+    this.obstacleInfluence = Math.max(finiteOr(obstacleInfluence, 1), 0);
+    this.obstacleDeflection = clamp01(obstacleDeflection);
+    this.preserveTangentialSpeed = clamp01(preserveTangentialSpeed);
+    this.obstacleGradientStep = Math.max(
+      finiteOr(obstacleGradientStep, Math.min(this.cellSizeX, this.cellSizeZ) * 0.75),
+      1e-3,
+    );
+    this.maxSpeed = Math.max(finiteOr(maxSpeed, DEFAULT_MAX_SPEED), 1e-3);
+    this.strength = finiteOr(strength, 1);
+    this.time = finiteOr(time, 0);
+    this.revision = 0;
+    this.disposed = false;
+    this.sampleContext = { time: this.time, field: this };
+
+    const count = this.resolutionX * this.resolutionY;
+    this.velocities = new Float32Array(count * 2);
+    this.weights = new Float32Array(count);
+    this.validity = new Float32Array(count);
+    this.encodedData = new Uint8Array(count * 4);
+    this.texture = new THREE.DataTexture(
+      this.encodedData,
+      this.resolutionX,
+      this.resolutionY,
+      THREE.RGBAFormat,
+      THREE.UnsignedByteType,
+    );
+    this.texture.name = 'waterCurrentField';
+    this.texture.wrapS = THREE.ClampToEdgeWrapping;
+    this.texture.wrapT = THREE.ClampToEdgeWrapping;
+    this.texture.minFilter = THREE.LinearFilter;
+    this.texture.magFilter = THREE.LinearFilter;
+    this.texture.generateMipmaps = false;
+    this.texture.flipY = false;
+    this.texture.colorSpace = THREE.NoColorSpace;
+    this.texture.unpackAlignment = 1;
+
+    this.rebuild({ time: this.time });
+  }
+
+  getRegion(out = new THREE.Vector4()) {
+    return out.copy(this.region);
+  }
+
+  containsPoint(x, z) {
+    return Number.isFinite(x) && Number.isFinite(z) &&
+      x >= this.minX && x <= this.minX + this.worldWidth &&
+      z >= this.minZ && z <= this.minZ + this.worldDepth;
+  }
+
+  setStrength(strength) {
+    this.strength = finiteOr(strength, this.strength);
+    return this;
+  }
+
+  setTime(time, { rebuild = true } = {}) {
+    this.time = finiteOr(time, this.time);
+    if (rebuild) this.rebuild({ time: this.time });
+    return this;
+  }
+
+  setVelocitySampler(sampler, { rebuild = true } = {}) {
+    if (sampler != null && typeof sampler !== 'function') {
+      throw new TypeError('WaterCurrentField velocitySampler must be a function or null.');
+    }
+    this.velocitySampler = sampler ?? null;
+    if (rebuild) this.rebuild();
+    return this;
+  }
+
+  setMaskSampler(sampler, { rebuild = true } = {}) {
+    if (sampler != null && typeof sampler !== 'function') {
+      throw new TypeError('WaterCurrentField maskSampler must be a function or null.');
+    }
+    this.maskSampler = sampler ?? null;
+    if (rebuild) this.rebuild();
+    return this;
+  }
+
+  setObstacleDistanceSampler(sampler, { rebuild = true } = {}) {
+    if (sampler != null && typeof sampler !== 'function') {
+      throw new TypeError(
+        'WaterCurrentField obstacleDistanceSampler must be a function or null.',
+      );
+    }
+    this.obstacleDistanceSampler = sampler ?? null;
+    if (rebuild) this.rebuild();
+    return this;
+  }
+
+  // Applies the local solid-boundary approximation in-place. Positive signed
+  // distance is fluid; <= 0 is solid. The gradient points out of the solid,
+  // so only velocity aimed into it is removed.
+  projectAtObstacle(x, z, velocity, distance) {
+    if (!this.obstacleDistanceSampler || !Number.isFinite(distance)) return 1;
+    if (distance <= 0) {
+      velocity.set(0, 0);
+      return 0;
+    }
+
+    const influence = this.obstacleInfluence;
+    if (influence <= 0 || distance >= influence) return 1;
+    const h = this.obstacleGradientStep;
+    const left = Number(this.obstacleDistanceSampler(x - h, z, this.sampleContext));
+    const right = Number(this.obstacleDistanceSampler(x + h, z, this.sampleContext));
+    const down = Number(this.obstacleDistanceSampler(x, z - h, this.sampleContext));
+    const up = Number(this.obstacleDistanceSampler(x, z + h, this.sampleContext));
+    const gradientX = right - left;
+    const gradientZ = up - down;
+    const gradientLength = Math.hypot(gradientX, gradientZ);
+    const avoidance = (1 - smoothstep01(distance / influence)) * this.obstacleDeflection;
+    if (gradientLength > 1e-6 && avoidance > 0) {
+      const normalX = gradientX / gradientLength;
+      const normalZ = gradientZ / gradientLength;
+      const inward = velocity.x * normalX + velocity.y * normalZ;
+      if (inward < 0) {
+        const originalSpeed = velocity.length();
+        velocity.x -= normalX * inward * avoidance;
+        velocity.y -= normalZ * inward * avoidance;
+        const projectedSpeed = velocity.length();
+        if (projectedSpeed > 1e-5 && originalSpeed > projectedSpeed) {
+          const preservedSpeed = THREE.MathUtils.lerp(
+            projectedSpeed,
+            originalSpeed,
+            avoidance * this.preserveTangentialSpeed,
+          );
+          velocity.multiplyScalar(preservedSpeed / projectedSpeed);
+        }
+      }
+    }
+    // Feather the last fraction of a cell so linear GPU sampling does not
+    // carry a full-speed texel across a solid boundary.
+    const feather = Math.max(Math.min(influence * 0.25, Math.hypot(
+      this.cellSizeX,
+      this.cellSizeZ,
+    )), 1e-3);
+    return smoothstep01(distance / feather);
+  }
+
+  rebuild({ time = this.time } = {}) {
+    if (this.disposed) return this;
+    this.time = finiteOr(time, this.time);
+    this.sampleContext.time = this.time;
+    const width = this.resolutionX;
+    const height = this.resolutionY;
+    const maximum = this.maxSpeed;
+
+    for (let y = 0; y < height; y += 1) {
+      const worldZ = this.minZ + (y + 0.5) * this.cellSizeZ;
+      for (let x = 0; x < width; x += 1) {
+        const worldX = this.minX + (x + 0.5) * this.cellSizeX;
+        const index = y * width + x;
+        const velocityIndex = index * 2;
+        const textureIndex = index * 4;
+        sampleScratch.copy(this.constantVelocity);
+        let valid = true;
+        if (this.velocitySampler) {
+          const result = this.velocitySampler(
+            worldX,
+            worldZ,
+            sampleScratch,
+            this.sampleContext,
+          );
+          valid = resolveVelocity(result, sampleScratch);
+        }
+
+        let weight = valid ? 1 : 0;
+        if (valid && this.maskSampler) {
+          weight *= clamp01(this.maskSampler(worldX, worldZ, this.sampleContext));
+        }
+        if (valid && this.obstacleDistanceSampler) {
+          const distance = Number(
+            this.obstacleDistanceSampler(worldX, worldZ, this.sampleContext),
+          );
+          if (Number.isFinite(distance)) {
+            weight *= this.projectAtObstacle(worldX, worldZ, sampleScratch, distance);
+          }
+        }
+
+        if (!valid || weight <= 0) sampleScratch.set(0, 0);
+        const speed = sampleScratch.length();
+        if (speed > maximum) sampleScratch.multiplyScalar(maximum / speed);
+        this.velocities[velocityIndex] = sampleScratch.x;
+        this.velocities[velocityIndex + 1] = sampleScratch.y;
+        this.weights[index] = clamp01(weight);
+        this.validity[index] = valid ? 1 : 0;
+        // Reserve byte 128 as exact zero. A conventional UNORM 0.5 bias
+        // decodes 128/255 to +1/255, which becomes a persistent 3.1 cm/s
+        // diagonal drift at the default 8 m/s range even in authored still
+        // water. Codes 1..255 provide a symmetric signed 127-step range;
+        // code 0 remains unused by valid velocity samples.
+        this.encodedData[textureIndex] = Math.round(
+          128 + THREE.MathUtils.clamp(sampleScratch.x / maximum, -1, 1) * 127,
+        );
+        this.encodedData[textureIndex + 1] = Math.round(
+          128 + THREE.MathUtils.clamp(sampleScratch.y / maximum, -1, 1) * 127,
+        );
+        this.encodedData[textureIndex + 2] = Math.round(this.weights[index] * 255);
+        this.encodedData[textureIndex + 3] = valid ? 255 : 0;
+      }
+    }
+    this.texture.needsUpdate = true;
+    this.revision += 1;
+    return this;
+  }
+
+  sampleChannelsAt(x, z, out) {
+    if (!this.containsPoint(x, z)) {
+      out.vx = 0;
+      out.vz = 0;
+      out.weight = 0;
+      out.valid = 0;
+      return out;
+    }
+    const pixelX = (x - this.minX) / this.worldWidth * this.resolutionX - 0.5;
+    const pixelY = (z - this.minZ) / this.worldDepth * this.resolutionY - 0.5;
+    const baseX = Math.floor(pixelX);
+    const baseY = Math.floor(pixelY);
+    const x0 = THREE.MathUtils.clamp(baseX, 0, this.resolutionX - 1);
+    const y0 = THREE.MathUtils.clamp(baseY, 0, this.resolutionY - 1);
+    const x1 = THREE.MathUtils.clamp(baseX + 1, 0, this.resolutionX - 1);
+    const y1 = THREE.MathUtils.clamp(baseY + 1, 0, this.resolutionY - 1);
+    const tx = THREE.MathUtils.clamp(pixelX - baseX, 0, 1);
+    const ty = THREE.MathUtils.clamp(pixelY - baseY, 0, 1);
+    const i00 = y0 * this.resolutionX + x0;
+    const i10 = y0 * this.resolutionX + x1;
+    const i01 = y1 * this.resolutionX + x0;
+    const i11 = y1 * this.resolutionX + x1;
+    const bilerp = (array, stride = 1, offset = 0) => {
+      const a = THREE.MathUtils.lerp(
+        array[i00 * stride + offset],
+        array[i10 * stride + offset],
+        tx,
+      );
+      const b = THREE.MathUtils.lerp(
+        array[i01 * stride + offset],
+        array[i11 * stride + offset],
+        tx,
+      );
+      return THREE.MathUtils.lerp(a, b, ty);
+    };
+    out.vx = bilerp(this.velocities, 2, 0);
+    out.vz = bilerp(this.velocities, 2, 1);
+    out.weight = bilerp(this.weights);
+    out.valid = bilerp(this.validity);
+    return out;
+  }
+
+  /** Bilinear CPU sample in metres/second. Outside/solid/invalid = (0, 0). */
+  sampleAt(x, z, out = new THREE.Vector2()) {
+    const channels = this.sampleChannelsAt(x, z, WaterCurrentField._sampleChannels);
+    const scale = channels.weight * channels.valid * this.strength;
+    return out.set(channels.vx * scale, channels.vz * scale);
+  }
+
+  /** Fluid-domain weight after obstacle and validity feathering, 0..1. */
+  sampleWeightAt(x, z) {
+    const channels = this.sampleChannelsAt(x, z, WaterCurrentField._sampleChannels);
+    return clamp01(channels.weight * channels.valid);
+  }
+
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.texture.dispose();
+  }
+}
+
+WaterCurrentField._sampleChannels = { vx: 0, vz: 0, weight: 0, valid: 0 };

package/src/water/waterMaterial.js

@@ -133,6 +133,9 @@ export function applyWaterSettingsToMaterial(material, options = {}) {
   const waves = buildGerstnerWaves(settings);
 
   writeWaveUniforms(material, waves);
+  if (uniforms.uSwashIncidenceX) {
+    uniforms.uSwashIncidenceX.value = waves[0]?.dirX ?? 0;
+  }
 
   uniforms.uDetailNormalStrength.value = settings.detailNormalStrength;
   uniforms.uDetailScale.value = settings.detailScale;
@@ -146,12 +149,16 @@ export function applyWaterSettingsToMaterial(material, options = {}) {
   uniforms.uDeepFadeDistance.value = settings.deepFadeDistance;
   uniforms.uOpacity.value = settings.opacity;
   uniforms.uRefractionStrength.value = settings.refractionStrength;
+  uniforms.uIndexOfRefraction.value = settings.indexOfRefraction;
+  uniforms.uUnderwaterTransmission.value = settings.underwaterTransmission;
+  uniforms.uUnderwaterTintStrength.value = settings.underwaterTintStrength;
   uniforms.uCausticsStrength.value = settings.causticsStrength;
   uniforms.uCausticsScale.value = settings.causticsScale;
   uniforms.uCausticsSpeed.value = settings.causticsSpeed;
 
   setSrgbColorUniform(uniforms.uFoamColor, settings.foamColor);
   uniforms.uFoamAmount.value = settings.foamAmount;
+  uniforms.uSwashFoamAmount.value = settings.swashFoamAmount;
   uniforms.uFoamContactDistance.value = settings.foamContactDistance;
   uniforms.uFoamLineSpacing.value = settings.foamLineSpacing;
   uniforms.uFoamNoiseScale.value = settings.foamNoiseScale;
@@ -182,6 +189,11 @@ export function applyWaterSettingsToMaterial(material, options = {}) {
   uniforms.uShoalingDepth.value = settings.shoalingDepth;
   uniforms.uShorelineWaves.value = settings.shorelineWaves;
   uniforms.uShorelineRunup.value = settings.shorelineRunup;
+  uniforms.uRunupDistance.value = settings.runupDistance;
+  if (uniforms.uBreakerEnabled) {
+    uniforms.uBreakerEnabled.value = settings.breakerEnabled === false ? 0 : 1;
+  }
+  if (uniforms.uBreakerAmount) uniforms.uBreakerAmount.value = settings.breakerAmount;
   // Total swell energy — normalizes breaker foam and scales swash run-up.
   const waveEnergy = waves.reduce((sum, wave) => sum + Math.abs(wave.amplitude), 0);
   uniforms.uWaveEnergy.value = waveEnergy;