@call-me-sensei/toonlab 0.1.1

package/src/water/waterInteraction.js

@@ -0,0 +1,193 @@
+import * as THREE from 'three';
+
+const workingPosition = new THREE.Vector3();
+
+// Tracks objects interacting with a WaterSurface and converts their motion
+// into ripples, wakes, and splashes:
+//   - fast downward crossing of the surface -> entry splash + ripple ring
+//   - fast upward exit -> smaller exit splash
+//   - horizontal movement while touching the water -> wake ripples + foam
+//
+// Interactor sources can be a THREE.Object3D or a function/object producing a
+// world position, so physics bodies (e.g. rapier) hook in without adapters.
+export class WaterInteractionManager {
+  constructor(surface, {
+    wakeInterval = 0.07,
+    entrySplashSpeed = 1.4,
+    exitSplashSpeed = 2.2,
+    minWakeSpeed = 0.12,
+  } = {}) {
+    this.surface = surface;
+    this.wakeInterval = wakeInterval;
+    this.entrySplashSpeed = entrySplashSpeed;
+    this.exitSplashSpeed = exitSplashSpeed;
+    this.minWakeSpeed = minWakeSpeed;
+    this.interactors = new Map();
+    this.nextId = 1;
+  }
+
+  resolvePosition(source, out) {
+    if (typeof source === 'function') {
+      const result = source(out);
+      if (result && result !== out) out.set(result.x ?? 0, result.y ?? 0, result.z ?? 0);
+      return out;
+    }
+    if (source?.isObject3D) return source.getWorldPosition(out);
+    if (typeof source?.getPosition === 'function') {
+      const result = source.getPosition(out);
+      if (result && result !== out) out.set(result.x ?? 0, result.y ?? 0, result.z ?? 0);
+      return out;
+    }
+    if (source && Number.isFinite(source.x)) return out.set(source.x, source.y ?? 0, source.z ?? 0);
+    return out.set(0, -1e6, 0);
+  }
+
+  // Options: radius (m), splashStrength / wakeStrength multipliers, splashes /
+  // wakes toggles, onSplash(event) callback.
+  add(source, options = {}) {
+    const id = options.id ?? `interactor-${this.nextId += 1}`;
+    this.interactors.set(id, {
+      source,
+      radius: options.radius ?? 0.35,
+      // Vertical extent above the tracked point. For tall bodies (characters,
+      // boats) this makes "touching" mean the waterline passes through the
+      // body, so chest-deep wading wakes but a fully submerged body is silent.
+      height: options.height ?? 0,
+      splashStrength: options.splashStrength ?? 1,
+      wakeStrength: options.wakeStrength ?? 1,
+      splashes: options.splashes ?? true,
+      wakes: options.wakes ?? true,
+      onSplash: options.onSplash ?? null,
+      previousPosition: new THREE.Vector3(0, -1e6, 0),
+      wasTouching: false,
+      wasAboveSurface: true,
+      wasBelowSurface: false,
+      wakeTimer: 0,
+      initialized: false,
+    });
+    return id;
+  }
+
+  remove(id) {
+    this.interactors.delete(id);
+  }
+
+  clear() {
+    this.interactors.clear();
+  }
+
+  update(delta) {
+    if (delta <= 0) return;
+    for (const interactor of this.interactors.values()) {
+      this.updateInteractor(interactor, delta);
+    }
+  }
+
+  updateInteractor(interactor, delta) {
+    const position = this.resolvePosition(interactor.source, workingPosition);
+    if (position.y < -1e5) return;
+
+    if (!interactor.initialized) {
+      interactor.previousPosition.copy(position);
+      interactor.initialized = true;
+      interactor.wasTouching = false;
+      interactor.wasAboveSurface = true;
+      interactor.wasBelowSurface = false;
+      return;
+    }
+
+    const surface = this.surface;
+    const inArea = surface.containsPoint(position.x, position.z);
+    const waterHeight = surface.getHeightAt(position.x, position.z);
+    const height = typeof interactor.height === 'function' ? interactor.height() : interactor.height;
+    const top = position.y + Math.max(height, interactor.radius);
+    const bottom = position.y - interactor.radius;
+    // Surface effects only happen where the waterline actually passes through
+    // the interactor volume. A body running along the seabed (fully below) or
+    // flying above leaves the surface untouched.
+    const touching = inArea && waterHeight >= bottom - 0.05 && waterHeight <= top + 0.05;
+    const aboveSurface = bottom > waterHeight;
+    const belowSurface = top < waterHeight;
+
+    const velocityY = (position.y - interactor.previousPosition.y) / delta;
+    const planarSpeed = Math.hypot(
+      position.x - interactor.previousPosition.x,
+      position.z - interactor.previousPosition.z) / delta;
+
+    // Crossing detection uses the previous frame's relation to the surface so
+    // a fast fall that skips past the waterline band in one step still counts.
+    const enteredFromAbove = interactor.wasAboveSurface && (touching || belowSurface);
+    const exitedUpward = (interactor.wasTouching || interactor.wasBelowSurface) && aboveSurface;
+
+    if (inArea && enteredFromAbove && interactor.splashes &&
+      velocityY < -this.entrySplashSpeed) {
+      const strength = Math.min(2.4, 0.4 + Math.abs(velocityY) * 0.22) *
+        interactor.splashStrength * (0.6 + interactor.radius);
+      surface.splash(position, { strength, radius: interactor.radius * 2.2 });
+      interactor.onSplash?.({ type: 'enter', position: position.clone(), strength });
+    } else if (inArea && exitedUpward && interactor.splashes &&
+      velocityY > this.exitSplashSpeed) {
+      const strength = Math.min(1.4, 0.3 + velocityY * 0.1) * interactor.splashStrength;
+      surface.splash(position, { strength: strength * 0.7, radius: interactor.radius * 1.6 });
+      interactor.onSplash?.({ type: 'exit', position: position.clone(), strength });
+    }
+
+    if (interactor.wakes && interactor.wasTouching && belowSurface && velocityY < -0.3) {
+      surface.addRipple(position, { radius: interactor.radius * 1.4, strength: -0.4 * interactor.wakeStrength });
+    } else if (interactor.wakes && interactor.wasBelowSurface && touching && velocityY > 0.3) {
+      surface.addRipple(position, { radius: interactor.radius * 1.4, strength: 0.35 * interactor.wakeStrength });
+    }
+
+    if (touching && interactor.wakes) {
+      interactor.wakeTimer -= delta;
+      if (planarSpeed > this.minWakeSpeed && interactor.wakeTimer <= 0) {
+        const speedFactor = Math.min(planarSpeed, 4);
+        // A body pushing through water makes a V-wake, not concentric rings:
+        // a rising bow push just ahead, and a pair of depressions at the
+        // flanks slightly behind. The propagating pair draws the trailing V.
+        const stepX = position.x - interactor.previousPosition.x;
+        const stepZ = position.z - interactor.previousPosition.z;
+        const stepLength = Math.hypot(stepX, stepZ) || 1;
+        const dirX = stepX / stepLength;
+        const dirZ = stepZ / stepLength;
+        const sideX = -dirZ;
+        const sideZ = dirX;
+        const radius = interactor.radius;
+        const wakeStrength = speedFactor * interactor.wakeStrength;
+        surface.addRipple({
+          x: position.x + dirX * radius * 1.15,
+          z: position.z + dirZ * radius * 1.15,
+        }, { radius: radius * (0.9 + speedFactor * 0.1), strength: 0.16 * wakeStrength });
+        const backX = position.x - dirX * radius * 0.5;
+        const backZ = position.z - dirZ * radius * 0.5;
+        surface.addRipple({
+          x: backX + sideX * radius,
+          z: backZ + sideZ * radius,
+        }, { radius: radius * 0.85, strength: -0.12 * wakeStrength });
+        surface.addRipple({
+          x: backX - sideX * radius,
+          z: backZ - sideZ * radius,
+        }, { radius: radius * 0.85, strength: -0.12 * wakeStrength });
+        // Fast movers kick up a little spray off the bow.
+        if (planarSpeed > 1.8 && interactor.splashes) {
+          surface.sprayAt({
+            x: position.x + dirX * radius,
+            y: position.y,
+            z: position.z + dirZ * radius,
+          }, {
+            count: Math.round(2 + speedFactor),
+            strength: speedFactor * 0.22 * interactor.splashStrength,
+          });
+        }
+        interactor.wakeTimer = this.wakeInterval / Math.max(planarSpeed, 1);
+      }
+    } else {
+      interactor.wakeTimer = 0;
+    }
+
+    interactor.wasTouching = touching;
+    interactor.wasAboveSurface = aboveSurface;
+    interactor.wasBelowSurface = belowSurface;
+    interactor.previousPosition.copy(position);
+  }
+}

package/src/water/waterMaterial.js

@@ -0,0 +1,263 @@
+import * as THREE from 'three';
+
+import { createWaterNodeMaterial } from '../shaders-tsl/water.js';
+import {
+  buildGerstnerWaves,
+  createWaterSettings,
+  WATER_DEBUG_MODES,
+  WATER_GERSTNER_WAVE_COUNT,
+} from './waterSettings.js';
+
+// Quality tiers gate the most expensive fragment features:
+// low    — no caustics/sparkles, 2-octave detail noise
+// medium — caustics + sparkles, no chromatic caustics, 3-octave detail
+// high   — chromatic caustics, 4-octave detail
+const QUALITY_DEFINES = Object.freeze({
+  low: Object.freeze({ WATER_QUALITY: 0, WATER_DETAIL_OCTAVES: 2, WATER_FOAM_OCTAVES: 2 }),
+  medium: Object.freeze({ WATER_QUALITY: 1, WATER_DETAIL_OCTAVES: 3, WATER_FOAM_OCTAVES: 3 }),
+  high: Object.freeze({ WATER_QUALITY: 2, WATER_DETAIL_OCTAVES: 4, WATER_FOAM_OCTAVES: 3 }),
+});
+
+/**
+ * The named water quality tiers, keyed 'low' | 'medium' | 'high'. Each tier
+ * maps to the shader defines it produces:
+ * `{ WATER_QUALITY, WATER_DETAIL_OCTAVES, WATER_FOAM_OCTAVES }` — see
+ * resolveWaterQualityDefines for the feature gates per WATER_QUALITY level.
+ * Frozen; use a custom `{ detailOctaves, foamOctaves, qualityLevel }` quality
+ * object to deviate from the named tiers.
+ */
+export const WATER_QUALITY_TIERS = QUALITY_DEFINES;
+
+function clampOctaves(value, fallback) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(8, Math.max(1, Math.round(number)));
+}
+
+/**
+ * Resolves a quality request into the water shader defines
+ * `{ WATER_QUALITY, WATER_DETAIL_OCTAVES, WATER_FOAM_OCTAVES }`.
+ *
+ * Accepts either a named tier ('low' | 'medium' | 'high', see
+ * WATER_QUALITY_TIERS) or a custom tier object:
+ *
+ *   { detailOctaves: 5, foamOctaves: 4, qualityLevel: 'high' }
+ *
+ * - `qualityLevel` picks the feature gate (0/'low' = no caustics or sparkles,
+ *   1/'medium' = caustics + sparkles, 2/'high' = chromatic caustics) and the
+ *   octave fallbacks; it defaults to 'high'.
+ * - `detailOctaves` / `foamOctaves` override the noise octave counts
+ *   (clamped to 1..8 integers).
+ *
+ * Unknown or missing values fall back to the 'high' tier, matching the
+ * previous behavior.
+ *
+ * @param {string|{detailOctaves?: number, foamOctaves?: number, qualityLevel?: string|number}} quality
+ * @returns {{WATER_QUALITY: number, WATER_DETAIL_OCTAVES: number, WATER_FOAM_OCTAVES: number}}
+ */
+export function resolveWaterQualityDefines(quality) {
+  if (quality && typeof quality === 'object') {
+    const level = quality.qualityLevel;
+    const numericLevel = Number(level);
+    const tier = Number.isFinite(numericLevel)
+      ? Object.values(QUALITY_DEFINES)
+        .find((entry) => entry.WATER_QUALITY === Math.min(2, Math.max(0, Math.round(numericLevel))))
+      : QUALITY_DEFINES[String(level ?? 'high').toLowerCase()];
+    const base = tier ?? QUALITY_DEFINES.high;
+    return Object.freeze({
+      WATER_QUALITY: base.WATER_QUALITY,
+      WATER_DETAIL_OCTAVES: clampOctaves(quality.detailOctaves, base.WATER_DETAIL_OCTAVES),
+      WATER_FOAM_OCTAVES: clampOctaves(quality.foamOctaves, base.WATER_FOAM_OCTAVES),
+    });
+  }
+  return QUALITY_DEFINES[String(quality ?? '').toLowerCase()] ?? QUALITY_DEFINES.high;
+}
+
+// createWaterSettings normalizes `quality` to a named tier string, so a
+// custom tier object must be pulled from the raw options before it is lost.
+function requestedWaterQuality(options, settings) {
+  const raw = options && typeof options === 'object' ? options.quality : undefined;
+  return raw && typeof raw === 'object' ? raw : settings.quality;
+}
+
+// Water colors are authored as sRGB values in settings/presets; uniforms are
+// uploaded in linear working space and converted back at the end of the
+// fragment shader, matching the pipeline used by built-in materials.
+function setSrgbColorUniform(uniform, value) {
+  if (!uniform) return;
+  const [r, g, b] = Array.isArray(value) ? value : [value?.r ?? 1, value?.g ?? 1, value?.b ?? 1];
+  if (!uniform.value?.isColor) uniform.value = new THREE.Color();
+  uniform.value.setRGB(r, g, b, THREE.SRGBColorSpace);
+}
+
+function setVector2Uniform(uniform, value) {
+  if (!uniform) return;
+  if (!uniform.value?.isVector2) uniform.value = new THREE.Vector2();
+  uniform.value.set(value?.[0] ?? value?.x ?? 1, value?.[1] ?? value?.y ?? 0);
+}
+
+function setDirection3Uniform(uniform, value) {
+  if (!uniform) return;
+  if (!uniform.value?.isVector3) uniform.value = new THREE.Vector3();
+  uniform.value
+    .set(value?.[0] ?? value?.x ?? 0, value?.[1] ?? value?.y ?? 1, value?.[2] ?? value?.z ?? 0)
+    .normalize();
+}
+
+function writeWaveUniforms(material, waves) {
+  const wavesA = material.uniforms.uWavesA.value;
+  const wavesB = material.uniforms.uWavesB.value;
+  for (let i = 0; i < WATER_GERSTNER_WAVE_COUNT; i += 1) {
+    const wave = waves[i];
+    wavesA[i].set(wave.dirX, wave.dirZ, wave.omega, wave.waveNumber);
+    wavesB[i].set(wave.amplitude, wave.phase, wave.steepness, wave.crestWeight);
+  }
+}
+
+export function resolveWaterDebugMode(mode) {
+  if (typeof mode === 'number' && Number.isFinite(mode)) return Math.max(0, Math.floor(mode));
+  return WATER_DEBUG_MODES[String(mode ?? 'off').toLowerCase()] ?? 0;
+}
+
+export function setWaterDebugMode(material, mode) {
+  if (material?.uniforms?.uDebugMode) {
+    material.uniforms.uDebugMode.value = resolveWaterDebugMode(mode);
+  }
+  return material;
+}
+
+export function applyWaterSettingsToMaterial(material, options = {}) {
+  const uniforms = material?.uniforms;
+  if (!uniforms) return material;
+  const settings = createWaterSettings(options);
+  const waves = buildGerstnerWaves(settings);
+
+  writeWaveUniforms(material, waves);
+
+  uniforms.uDetailNormalStrength.value = settings.detailNormalStrength;
+  uniforms.uDetailScale.value = settings.detailScale;
+  setVector2Uniform(uniforms.uFlowDirection, settings.flowDirection);
+  uniforms.uFlowSpeed.value = settings.flowSpeed;
+
+  setSrgbColorUniform(uniforms.uShallowColor, settings.shallowColor);
+  setSrgbColorUniform(uniforms.uMidColor, settings.midColor);
+  setSrgbColorUniform(uniforms.uDeepColor, settings.deepColor);
+  uniforms.uDepthFadeDistance.value = settings.depthFadeDistance;
+  uniforms.uDeepFadeDistance.value = settings.deepFadeDistance;
+  uniforms.uOpacity.value = settings.opacity;
+  uniforms.uRefractionStrength.value = settings.refractionStrength;
+  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.uFoamContactDistance.value = settings.foamContactDistance;
+  uniforms.uFoamLineSpacing.value = settings.foamLineSpacing;
+  uniforms.uFoamNoiseScale.value = settings.foamNoiseScale;
+  uniforms.uWhitecapAmount.value = settings.whitecapAmount;
+  uniforms.uRippleFoamStrength.value = settings.rippleFoamStrength;
+
+  setDirection3Uniform(uniforms.uSunDirection, settings.sunDirection);
+  setSrgbColorUniform(uniforms.uSunColor, settings.sunColor);
+  uniforms.uSpecularStrength.value = settings.specularStrength;
+  uniforms.uSpecularShininess.value = settings.specularShininess;
+  uniforms.uSpecularStretch.value = settings.specularStretch;
+  uniforms.uSparkleStrength.value = settings.sparkleStrength;
+  uniforms.uSparkleScale.value = settings.sparkleScale;
+  uniforms.uSparkleSpeed.value = settings.sparkleSpeed;
+  uniforms.uSunGlowStrength.value = settings.sunGlowStrength;
+  uniforms.uSceneShadowStrength.value = settings.sceneShadowStrength;
+  uniforms.uFresnelStrength.value = settings.fresnelStrength;
+  uniforms.uFresnelPower.value = settings.fresnelPower;
+  uniforms.uFresnelBias.value = settings.fresnelBias;
+  uniforms.uReflectionSoftness.value = settings.reflectionSoftness;
+  setSrgbColorUniform(uniforms.uFresnelColor, settings.fresnelColor);
+  setSrgbColorUniform(uniforms.uSkyZenithColor, settings.skyZenithColor);
+  setSrgbColorUniform(uniforms.uSkyHorizonColor, settings.skyHorizonColor);
+  uniforms.uReflectionStrength.value = settings.reflectionStrength;
+  uniforms.uReflectionDistortion.value = settings.reflectionDistortion;
+
+  uniforms.uRippleHeightScale.value = settings.rippleHeightScale;
+  uniforms.uShoalingDepth.value = settings.shoalingDepth;
+  uniforms.uShorelineWaves.value = settings.shorelineWaves;
+  uniforms.uShorelineRunup.value = settings.shorelineRunup;
+  // 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;
+  material.userData.waterWaveEnergy = waveEnergy;
+
+  const qualityDefines = resolveWaterQualityDefines(requestedWaterQuality(options, settings));
+  const currentDefines = material.defines ?? {};
+  if (currentDefines.WATER_QUALITY !== qualityDefines.WATER_QUALITY
+    || currentDefines.WATER_DETAIL_OCTAVES !== qualityDefines.WATER_DETAIL_OCTAVES
+    || currentDefines.WATER_FOAM_OCTAVES !== qualityDefines.WATER_FOAM_OCTAVES) {
+    material.defines = { ...material.defines, ...qualityDefines };
+    material.needsUpdate = true;
+  }
+
+  material.userData.waterMaterial = true;
+  material.userData.waterSettings = settings;
+  material.userData.gerstnerWaves = waves;
+  return material;
+}
+
+export function createWaterMaterial(options = {}) {
+  const settings = createWaterSettings(options);
+  const requestedQuality = requestedWaterQuality(options, settings);
+  const qualityDefines = resolveWaterQualityDefines(requestedQuality);
+
+  // Node-backend material: same uniform-name surface, quality defines baked
+  // as graph flags (a later quality change needs a new material on this
+  // backend). `options.shoaling` is the WATER_SHOALING define analog —
+  // WaterSurface passes it when a bed sampler bakes aBedHeight.
+  const material = createWaterNodeMaterial({
+    waveCount: WATER_GERSTNER_WAVE_COUNT,
+    qualityLevel: qualityDefines.WATER_QUALITY,
+    detailOctaves: qualityDefines.WATER_DETAIL_OCTAVES,
+    foamOctaves: qualityDefines.WATER_FOAM_OCTAVES,
+    shoaling: Boolean(options.shoaling),
+  });
+  return applyWaterSettingsToMaterial(
+    material,
+    typeof requestedQuality === 'object' ? { ...settings, quality: requestedQuality } : settings,
+  );
+}
+
+const invViewProjScratch = new THREE.Matrix4();
+
+// Node backends: the water fragment reconstructs world positions with the
+// literal GLSL math — screenUv/rawDepth * 2 - 1 into uInvViewProjMatrix — so
+// the backend differences are composed into the matrix on the CPU
+// (docs/tsl-conventions.md #6): screenUV is top-left-origin on both node
+// backends (y-negate), and WebGPU NDC z is [0,1] (the stored [0,1] window
+// depth IS the WebGPU NDC z, so z' maps 2d-1 back to d). These are the
+// inverses of pass-depth-color's shadowClipAdjust* matrices.
+const ndcAdjustWebGPU = new THREE.Matrix4().set(
+  1, 0, 0, 0,
+  0, -1, 0, 0,
+  0, 0, 0.5, 0.5,
+  0, 0, 0, 1,
+);
+const ndcAdjustGL = new THREE.Matrix4().set(
+  1, 0, 0, 0,
+  0, -1, 0, 0,
+  0, 0, 1, 0,
+  0, 0, 0, 1,
+);
+
+// Per-frame camera/screen uniform refresh. WaterSurface calls this for you;
+// it is exported for projects driving the material directly.
+export function updateWaterMaterialCamera(material, renderer, camera) {
+  const uniforms = material?.uniforms;
+  if (!uniforms) return material;
+  renderer.getDrawingBufferSize(uniforms.uResolution.value);
+  uniforms.uCameraNear.value = camera.near;
+  uniforms.uCameraFar.value = camera.far;
+  invViewProjScratch.multiplyMatrices(camera.matrixWorld, camera.projectionMatrixInverse);
+  invViewProjScratch.multiply(
+    renderer.coordinateSystem === THREE.WebGPUCoordinateSystem ? ndcAdjustWebGPU : ndcAdjustGL,
+  );
+  uniforms.uInvViewProjMatrix.value.copy(invViewProjScratch);
+  return material;
+}

package/src/water/waterRain.js

@@ -0,0 +1,136 @@
+import * as THREE from 'three';
+
+import { createWaterRainNodeMaterial } from '../shaders-tsl/water-rain.js';
+
+// Node-backend rain: WGSL has no gl_PointSize, so the streak POINTS become
+// instanced billboard quads (dust-motes pattern; see water-rain.js). Same
+// public API as the classic Points-based WaterRain — the WaterRain
+// constructor returns an instance of this class on the TSL backend.
+class WaterRainNodeMesh extends THREE.Mesh {
+  constructor({
+    count = 2400,
+    areaSize = 30,
+    fallHeight = 16,
+    speed = 16,
+    streakLength = 0.42,
+    wind = [2.2, 0.8],
+    color = [0.8, 0.88, 0.95],
+    opacity = 0.34,
+  } = {}) {
+    const quad = new THREE.PlaneGeometry(1, 1);
+    const geometry = new THREE.InstancedBufferGeometry();
+    geometry.index = quad.index;
+    geometry.setAttribute('position', quad.attributes.position);
+    geometry.setAttribute('uv', quad.attributes.uv);
+    const seeds = new Float32Array(count * 4);
+    for (let i = 0; i < count; i += 1) {
+      seeds[i * 4] = Math.random();
+      seeds[i * 4 + 1] = Math.random();
+      seeds[i * 4 + 2] = Math.random();
+      seeds[i * 4 + 3] = Math.random();
+    }
+    geometry.setAttribute('aSeed', new THREE.InstancedBufferAttribute(seeds, 4));
+    geometry.instanceCount = count;
+    geometry.boundingSphere = new THREE.Sphere(new THREE.Vector3(), 1e5);
+
+    const material = createWaterRainNodeMaterial({
+      areaSize, color, fallHeight, opacity, speed, streakLength, wind,
+    });
+
+    super(geometry, material);
+    this.name = 'WaterRain';
+    this.frustumCulled = false;
+    this.renderOrder = 40;
+    this.count = count;
+    this.baseOpacity = opacity;
+    this.intensity = 1;
+    // Rain is an overlay effect: keep it out of the water's scene passes.
+    this.userData.waterExclude = true;
+  }
+
+  setIntensity(intensity) {
+    this.intensity = THREE.MathUtils.clamp(intensity, 0, 1);
+    this.visible = this.intensity > 0.005;
+    this.material.uniforms.uOpacity.value = this.baseOpacity * (0.4 + 0.6 * this.intensity);
+    // Instanced quads: the draw-count scaling happens through instanceCount
+    // (setDrawRange would trim the base quad, not the particle pool).
+    this.geometry.instanceCount = Math.floor(this.count * this.intensity);
+    return this;
+  }
+
+  update(delta, camera, renderer, waterLevel = 0) {
+    const uniforms = this.material.uniforms;
+    uniforms.uTime.value += Math.min(Math.max(delta ?? 0.016, 0), 0.1);
+    if (camera) {
+      const position = camera.getWorldPosition(new THREE.Vector3());
+      uniforms.uCenter.value.set(position.x, waterLevel, position.z);
+    }
+    if (renderer) {
+      uniforms.uPixelRatio.value = renderer.getPixelRatio();
+      uniforms.uPointScale.value = (renderer.domElement?.clientHeight || 540) * 0.9;
+    }
+    return this;
+  }
+
+  dispose() {
+    this.geometry.dispose();
+    this.material.dispose();
+  }
+}
+
+// Procedural rain: GPU-looping streak particles in a volume that follows a
+// center point (usually the camera over the water). No texture assets and no
+// per-frame buffer writes; intensity scales draw count and opacity.
+//
+//   const rain = new WaterRain({ count: 2600 });
+//   scene.add(rain);
+//   rain.setIntensity(0.9);
+//   rain.update(delta, camera, renderer, waterLevel);   // each frame
+//
+// Pair it with WaterSurface.addRipple(...) dimples for rain-pocked water.
+export class WaterRain extends THREE.Points {
+  constructor({
+    count = 2400,
+    areaSize = 30,
+    fallHeight = 16,
+    speed = 16,
+    streakLength = 0.42,
+    wind = [2.2, 0.8],
+    color = [0.8, 0.88, 0.95],
+    opacity = 0.34,
+  } = {}) {
+    // Derived constructors may skip super() when they return an object: the
+    // instanced-quad implementation keeps the same public API surface, so call
+    // sites stay `new WaterRain(...)`.
+    return new WaterRainNodeMesh({
+      areaSize, color, count, fallHeight, opacity, speed, streakLength, wind,
+    });
+  }
+
+  setIntensity(intensity) {
+    this.intensity = THREE.MathUtils.clamp(intensity, 0, 1);
+    this.visible = this.intensity > 0.005;
+    this.material.uniforms.uOpacity.value = this.baseOpacity * (0.4 + 0.6 * this.intensity);
+    this.geometry.setDrawRange(0, Math.floor(this.count * this.intensity));
+    return this;
+  }
+
+  update(delta, camera, renderer, waterLevel = 0) {
+    const uniforms = this.material.uniforms;
+    uniforms.uTime.value += Math.min(Math.max(delta ?? 0.016, 0), 0.1);
+    if (camera) {
+      const position = camera.getWorldPosition(new THREE.Vector3());
+      uniforms.uCenter.value.set(position.x, waterLevel, position.z);
+    }
+    if (renderer) {
+      uniforms.uPixelRatio.value = renderer.getPixelRatio();
+      uniforms.uPointScale.value = (renderer.domElement?.clientHeight || 540) * 0.9;
+    }
+    return this;
+  }
+
+  dispose() {
+    this.geometry.dispose();
+    this.material.dispose();
+  }
+}