@call-me-sensei/toonlab 0.1.1

package/src/water/waterRippleSimulation.js

@@ -0,0 +1,227 @@
+import * as THREE from 'three';
+
+import { createWaterSimulationNodeMaterial } from '../shaders-tsl/water-simulation.js';
+
+export const WATER_SIM_MAX_IMPULSES = 16;
+
+const FIXED_TIMESTEP = 1 / 120;
+const MAX_SUBSTEPS_PER_FRAME = 6;
+
+// GPU ping-pong heightfield for interactive ripples (character wakes, splash
+// rings, rain, projectiles). State texture: R = height, G = velocity,
+// B = foam energy. The simulated window can follow a moving target via
+// setCenter(); the reprojection shift is texel-exact so ripples stay put in
+// world space while the window travels.
+export class WaterRippleSimulation {
+  constructor({
+    resolution = 256,
+    worldWidth = 20,
+    worldDepth = 20,
+    centerX = 0,
+    centerZ = 0,
+  } = {}) {
+    this.resolution = Math.max(16, Math.floor(resolution));
+    this.worldWidth = Math.max(0.1, worldWidth);
+    this.worldDepth = Math.max(0.1, worldDepth);
+    this.centerX = centerX;
+    this.centerZ = centerZ;
+
+    this.parameters = {
+      rippleDamping: 0.985,
+      ripplePropagation: 11,
+      rippleFoamDecay: 0.94,
+      rippleFoamGain: 2.4,
+    };
+
+    this.targets = [this.createTarget(), this.createTarget()];
+    this.readIndex = 0;
+    this.initialized = false;
+    this.timeAccumulator = 0;
+    this.pendingImpulses = [];
+    this.pendingShiftTexels = new THREE.Vector2(0, 0);
+
+    // Same fullscreen ping-pong contract and uniform-name surface as the
+    // retired ShaderMaterial path; the update loop writes `.value`s unchanged.
+    this.material = createWaterSimulationNodeMaterial({
+      maxImpulses: WATER_SIM_MAX_IMPULSES,
+      resolution: this.resolution,
+    });
+    this.material.uniforms.uDamping.value = this.parameters.rippleDamping;
+    this.material.uniforms.uFoamDecay.value = this.parameters.rippleFoamDecay;
+    this.material.uniforms.uFoamGain.value = this.parameters.rippleFoamGain;
+    this.material.uniforms.uRegionWorldSize.value.set(this.worldWidth, this.worldDepth);
+
+    this.fullscreenScene = new THREE.Scene();
+    this.fullscreenCamera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+    const quad = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), this.material);
+    quad.frustumCulled = false;
+    this.fullscreenScene.add(quad);
+  }
+
+  createTarget() {
+    const target = new THREE.WebGLRenderTarget(this.resolution, this.resolution, {
+      type: THREE.HalfFloatType,
+      format: THREE.RGBAFormat,
+      minFilter: THREE.LinearFilter,
+      magFilter: THREE.LinearFilter,
+      wrapS: THREE.ClampToEdgeWrapping,
+      wrapT: THREE.ClampToEdgeWrapping,
+      depthBuffer: false,
+      stencilBuffer: false,
+      generateMipmaps: false,
+    });
+    target.texture.name = 'waterRippleState';
+    return target;
+  }
+
+  get texture() {
+    return this.targets[this.readIndex].texture;
+  }
+
+  get texelSize() {
+    return this.material.uniforms.uTexel.value;
+  }
+
+  // (centerX, centerZ, halfWidth, halfDepth) for the surface shader.
+  getRegion(out = new THREE.Vector4()) {
+    return out.set(this.centerX, this.centerZ, this.worldWidth * 0.5, this.worldDepth * 0.5);
+  }
+
+  setParameters(parameters = {}) {
+    for (const key of Object.keys(this.parameters)) {
+      if (Number.isFinite(parameters[key])) this.parameters[key] = parameters[key];
+    }
+    return this;
+  }
+
+  // Moves the simulated window; existing ripples remain fixed in world space.
+  setCenter(x, z) {
+    const texelWorldX = this.worldWidth / this.resolution;
+    const texelWorldZ = this.worldDepth / this.resolution;
+    const quantizedX = Math.round(x / texelWorldX) * texelWorldX;
+    const quantizedZ = Math.round(z / texelWorldZ) * texelWorldZ;
+    this.pendingShiftTexels.x += (quantizedX - this.centerX) / texelWorldX;
+    this.pendingShiftTexels.y += (quantizedZ - this.centerZ) / texelWorldZ;
+    this.centerX = quantizedX;
+    this.centerZ = quantizedZ;
+    return this;
+  }
+
+  containsPoint(worldX, worldZ, margin = 0) {
+    return Math.abs(worldX - this.centerX) <= this.worldWidth * 0.5 - margin &&
+      Math.abs(worldZ - this.centerZ) <= this.worldDepth * 0.5 - margin;
+  }
+
+  // Queues a gaussian impulse at a world position. strength is a vertical
+  // velocity kick in m/s; negative values push the surface down.
+  addImpulse(worldX, worldZ, { radius = 0.35, strength = 0.6 } = {}) {
+    if (!this.containsPoint(worldX, worldZ)) return this;
+    if (this.pendingImpulses.length >= WATER_SIM_MAX_IMPULSES * 4) return this;
+    this.pendingImpulses.push({ worldX, worldZ, radius, strength });
+    return this;
+  }
+
+  // Queues a ring of impulses, used by splashes for an outward-running wave.
+  addRingImpulse(worldX, worldZ, { radius = 0.5, strength = 0.6, points = 6 } = {}) {
+    for (let i = 0; i < points; i += 1) {
+      const angle = (i / points) * Math.PI * 2;
+      this.addImpulse(
+        worldX + Math.cos(angle) * radius,
+        worldZ + Math.sin(angle) * radius,
+        { radius: radius * 0.8, strength: strength / points * 2.4 },
+      );
+    }
+    return this;
+  }
+
+  writeImpulseUniforms() {
+    const impulses = this.material.uniforms.uImpulses.value;
+    const count = Math.min(this.pendingImpulses.length, WATER_SIM_MAX_IMPULSES);
+    for (let i = 0; i < count; i += 1) {
+      const impulse = this.pendingImpulses[i];
+      impulses[i].set(
+        (impulse.worldX - this.centerX) / this.worldWidth + 0.5,
+        (impulse.worldZ - this.centerZ) / this.worldDepth + 0.5,
+        Math.max(impulse.radius, 1e-3),
+        impulse.strength,
+      );
+    }
+    this.material.uniforms.uImpulseCount.value = count;
+    this.pendingImpulses.splice(0, count);
+  }
+
+  clearTargets(renderer) {
+    const previousTarget = renderer.getRenderTarget();
+    const previousClearColor = renderer.getClearColor(new THREE.Color());
+    const previousClearAlpha = renderer.getClearAlpha();
+    renderer.setClearColor(0x000000, 0);
+    for (const target of this.targets) {
+      renderer.setRenderTarget(target);
+      renderer.clear(true, false, false);
+    }
+    renderer.setRenderTarget(previousTarget);
+    renderer.setClearColor(previousClearColor, previousClearAlpha);
+  }
+
+  step(renderer) {
+    const uniforms = this.material.uniforms;
+    uniforms.uPrevState.value = this.targets[this.readIndex].texture;
+    const writeTarget = this.targets[1 - this.readIndex];
+    renderer.setRenderTarget(writeTarget);
+    renderer.render(this.fullscreenScene, this.fullscreenCamera);
+    this.readIndex = 1 - this.readIndex;
+  }
+
+  update(renderer, delta) {
+    if (!this.initialized) {
+      this.clearTargets(renderer);
+      this.initialized = true;
+    }
+
+    this.timeAccumulator += Math.min(Math.max(delta, 0), 0.1);
+    let substeps = Math.floor(this.timeAccumulator / FIXED_TIMESTEP);
+    if (substeps <= 0 && this.pendingImpulses.length === 0) return;
+    substeps = Math.min(substeps, MAX_SUBSTEPS_PER_FRAME);
+    this.timeAccumulator = Math.max(
+      0, Math.min(this.timeAccumulator - substeps * FIXED_TIMESTEP, FIXED_TIMESTEP));
+
+    const uniforms = this.material.uniforms;
+    const texelWorld = this.worldWidth / this.resolution;
+    // Explicit heightfield stability (CFL): c * dt / dx must stay under ~0.7.
+    const maxPropagationSpeed = (texelWorld * 0.7) / FIXED_TIMESTEP;
+    const speed = Math.min(this.parameters.ripplePropagation, maxPropagationSpeed);
+    uniforms.uPropagation.value = (speed / texelWorld) * (speed / texelWorld);
+    uniforms.uDamping.value = this.parameters.rippleDamping;
+    uniforms.uFoamDecay.value = this.parameters.rippleFoamDecay;
+    uniforms.uFoamGain.value = this.parameters.rippleFoamGain;
+    uniforms.uDelta.value = FIXED_TIMESTEP;
+    uniforms.uRegionWorldSize.value.set(this.worldWidth, this.worldDepth);
+
+    const previousTarget = renderer.getRenderTarget();
+    const previousXrEnabled = renderer.xr.enabled;
+    renderer.xr.enabled = false;
+    try {
+      for (let i = 0; i < Math.max(substeps, this.pendingImpulses.length > 0 ? 1 : 0); i += 1) {
+        // Region shift and queued impulses apply on the first substep only.
+        if (i === 0) {
+          uniforms.uRegionShiftTexels.value.copy(this.pendingShiftTexels);
+          this.pendingShiftTexels.set(0, 0);
+          this.writeImpulseUniforms();
+        } else {
+          uniforms.uRegionShiftTexels.value.set(0, 0);
+          uniforms.uImpulseCount.value = 0;
+        }
+        this.step(renderer);
+      }
+    } finally {
+      renderer.setRenderTarget(previousTarget);
+      renderer.xr.enabled = previousXrEnabled;
+    }
+  }
+
+  dispose() {
+    for (const target of this.targets) target.dispose();
+    this.material.dispose();
+    this.fullscreenScene.traverse((object) => object.geometry?.dispose?.());
+  }
+}

package/src/water/waterScenePasses.js

@@ -0,0 +1,415 @@
+import * as THREE from 'three';
+
+import { createPassDepthColorMaterial } from '../shaders-tsl/chunks/pass-depth-color.js';
+
+// Render passes that feed the water material:
+//   grab pass  — scene color + depth in one render (refraction, absorption,
+//                shoreline foam, caustics)
+//   reflection — planar mirror render with oblique near-plane clipping
+//
+// Exclusion flags on object.userData:
+//   waterExclude           — hidden from both passes
+//   waterReflectionExclude — hidden from the reflection pass only
+//   skipWaterReflection    — legacy alias of waterReflectionExclude
+//
+// Node backends (docs/tsl-conventions.md):
+// - The grab target keeps its texture linear (working space): rendering into
+//   a user render target skips the renderer's output color transform, so the
+//   texels are exactly the linear values the water shader's own output path
+//   feeds the final screen pass — refraction stays an exact pass-through.
+// - TSL shaders cannot portably sample depth ATTACHMENTS (WGSL/GLSL builders
+//   type them differently), so scene depth comes from a second render into a
+//   float COLOR target with swapped depth materials (pass-depth-color.js),
+//   following environmentSunShadowPass's swap-cache lessons (no per-frame
+//   allocations, cached swap arrays, visibility kept in step).
+// - Node-backend RTs are written top-down: the projective reflection matrix
+//   gets a CPU-side uv y-flip, and the oblique near-plane clip uses the
+//   coordinate-system-aware construction from three's own ReflectorNode.
+
+const BIAS_MATRIX = new THREE.Matrix4().set(
+  0.5, 0, 0, 0.5,
+  0, 0.5, 0, 0.5,
+  0, 0, 0.5, 0.5,
+  0, 0, 0, 1,
+);
+
+// uv' = (u, 1 - v): the node backends write render targets top-down, so the
+// GL-convention projective uv needs a y-flip (composed after BIAS_MATRIX).
+const FLIP_Y_UV_MATRIX = new THREE.Matrix4().set(
+  1, 0, 0, 0,
+  0, -1, 0, 1,
+  0, 0, 1, 0,
+  0, 0, 0, 1,
+);
+
+function hideFlagged(root, predicate) {
+  const hidden = [];
+  root.traverse((object) => {
+    if (!object.visible || !predicate(object)) return;
+    object.visible = false;
+    hidden.push(object);
+  });
+  return () => {
+    for (const object of hidden) object.visible = true;
+  };
+}
+
+export class WaterScenePasses {
+  constructor({
+    sceneColor = true,
+    reflection = true,
+    sceneColorScale = 1,
+    reflectionScale = 0.5,
+    clipBias = 0.02,
+  } = {}) {
+    this.sceneColorEnabled = sceneColor;
+    this.reflectionEnabled = reflection;
+    this.sceneColorScale = sceneColorScale;
+    this.reflectionScale = reflectionScale;
+    this.clipBias = clipBias;
+
+    this.grabTarget = null;
+    this.reflectionTarget = null;
+    this.reflectionCamera = new THREE.PerspectiveCamera();
+    this.reflectionMatrix = new THREE.Matrix4();
+    this.reflectionValid = false;
+    this.grabValid = false;
+
+    // Scene-depth pass state for the TSL renderer path.
+    this.depthTarget = null;
+    this.depthMaterialCache = new WeakMap();
+    // Swapped material (or material ARRAY) per mesh, keyed by the source
+    // material identity: handing the renderer a fresh array every frame
+    // churns its render-object cache (see environmentSunShadowPass).
+    this.depthSwapCache = new WeakMap();
+    this.depthMaterialRestores = [];
+    this.depthVisibilityRestores = [];
+
+    this.scratch = {
+      drawingBufferSize: new THREE.Vector2(),
+      cameraPosition: new THREE.Vector3(),
+      cameraDirection: new THREE.Vector3(),
+      target: new THREE.Vector3(),
+      plane: new THREE.Plane(),
+      clipPlane: new THREE.Vector4(),
+      q: new THREE.Vector4(),
+      waterWorldPosition: new THREE.Vector3(),
+      clearColor: new THREE.Color(),
+    };
+  }
+
+  ensureGrabTarget(renderer) {
+    renderer.getDrawingBufferSize(this.scratch.drawingBufferSize);
+    const width = Math.max(1, Math.floor(this.scratch.drawingBufferSize.x * this.sceneColorScale));
+    const height = Math.max(1, Math.floor(this.scratch.drawingBufferSize.y * this.sceneColorScale));
+    if (!this.grabTarget) {
+      this.grabTarget = new THREE.WebGLRenderTarget(width, height, {
+        depthBuffer: true,
+        stencilBuffer: false,
+        generateMipmaps: false,
+        minFilter: THREE.LinearFilter,
+        magFilter: THREE.LinearFilter,
+      });
+      // Working-space (linear) texels — see the node-backend notes above.
+    } else if (this.grabTarget.width !== width || this.grabTarget.height !== height) {
+      this.grabTarget.setSize(width, height);
+    }
+    if (!this.depthTarget) {
+      this.depthTarget = new THREE.WebGLRenderTarget(width, height, {
+        depthBuffer: true,
+        stencilBuffer: false,
+        generateMipmaps: false,
+        minFilter: THREE.NearestFilter,
+        magFilter: THREE.NearestFilter,
+      });
+      this.depthTarget.texture.name = 'WaterScenePasses.Depth';
+      this.depthTarget.texture.type = THREE.FloatType;
+    } else if (this.depthTarget.width !== width || this.depthTarget.height !== height) {
+      this.depthTarget.setSize(width, height);
+    }
+  }
+
+  ensureReflectionTarget(renderer) {
+    renderer.getDrawingBufferSize(this.scratch.drawingBufferSize);
+    const width = Math.max(1, Math.floor(this.scratch.drawingBufferSize.x * this.reflectionScale));
+    const height = Math.max(1, Math.floor(this.scratch.drawingBufferSize.y * this.reflectionScale));
+    if (!this.reflectionTarget) {
+      this.reflectionTarget = new THREE.WebGLRenderTarget(width, height, {
+        depthBuffer: true,
+        stencilBuffer: false,
+        generateMipmaps: false,
+        minFilter: THREE.LinearFilter,
+        magFilter: THREE.LinearFilter,
+        samples: 4,
+      });
+      // Keep the texture linear (see the grab-target notes).
+    } else if (this.reflectionTarget.width !== width || this.reflectionTarget.height !== height) {
+      this.reflectionTarget.setSize(width, height);
+    }
+  }
+
+  // Depth replacement for one material, cached by source identity. Camera-view
+  // depth pass: keep the source's side (unlike the shadow pass's flip) and
+  // match the depth buffer's participation rules (visible + depthWrite).
+  depthMaterialFor(material) {
+    let depthMaterial = this.depthMaterialCache.get(material);
+    if (!depthMaterial) {
+      if (typeof material?.userData?.createDepthColorVariant === 'function') {
+        // Materials with custom vertex displacement (tree foliage cards,
+        // kelp blades) provide their own cutout depth variant.
+        depthMaterial = material.userData.createDepthColorVariant();
+      } else {
+        const cutoff = material?.uniforms?.aCutoff?.value ??
+          material?.uniforms?.alphaCutoff?.value ??
+          (material?.alphaTest > 0 ? material.alphaTest : -1);
+        const map = material?.uniforms?.base?.value ??
+          material?.uniforms?.baseMap?.value ??
+          material?.map ?? null;
+        depthMaterial = createPassDepthColorMaterial({
+          alphaTest: cutoff > 0 ? cutoff : 0,
+          map: cutoff > 0 ? map : null,
+          side: material?.side ?? THREE.FrontSide,
+        });
+      }
+      // Depth-as-color must never be fogged: with scene.fog set, the node
+      // pipeline's per-material fog mix would blend distant depth values
+      // toward the fog color (the pass also nulls scene.fog — see below).
+      depthMaterial.fog = false;
+      this.depthMaterialCache.set(material, depthMaterial);
+    }
+    depthMaterial.visible = material?.visible !== false && material?.depthWrite !== false;
+    return depthMaterial;
+  }
+
+  // Node backends only: render linear window depth into the float color
+  // target with swapped materials. Runs inside renderGrabPass's hide window
+  // (waterMesh + waterExclude objects are already invisible).
+  renderDepthPass(renderer, scene, camera) {
+    const materialRestores = this.depthMaterialRestores;
+    const visibilityRestores = this.depthVisibilityRestores;
+    materialRestores.length = 0;
+    visibilityRestores.length = 0;
+
+    scene.traverse((obj) => {
+      if (!obj.visible) return;
+      const renderable = obj.isMesh || obj.isPoints || obj.isLine || obj.isSprite;
+      if (!renderable) return;
+      // Points/lines/sprites would draw their color into the depth target;
+      // outline shells hug the base mesh depth.
+      if (!obj.isMesh || obj.userData?.isToonOutline || obj.userData?.isToonFurShell) {
+        obj.visible = false;
+        visibilityRestores.push(obj);
+        return;
+      }
+      const sourceMaterials = Array.isArray(obj.material) ? obj.material : [obj.material];
+      if (!sourceMaterials.some((mat) => mat && mat.visible !== false && mat.depthWrite !== false)) {
+        obj.visible = false;
+        visibilityRestores.push(obj);
+        return;
+      }
+      // Instanced custom-attribute geometry without its own depth variant
+      // (e.g. grass blades) would collapse to its base quads under the
+      // generic swap — the ground behind still writes depth, so skip them.
+      const primary = sourceMaterials.find(Boolean);
+      if (
+        obj.geometry?.isInstancedBufferGeometry &&
+        !obj.isInstancedMesh &&
+        typeof primary?.userData?.createDepthColorVariant !== 'function'
+      ) {
+        obj.visible = false;
+        visibilityRestores.push(obj);
+        return;
+      }
+      materialRestores.push({ material: obj.material, mesh: obj });
+      let swap = this.depthSwapCache.get(obj);
+      if (!swap || swap.source !== obj.material) {
+        swap = {
+          source: obj.material,
+          swapped: Array.isArray(obj.material)
+            ? obj.material.map((mat) => this.depthMaterialFor(mat))
+            : this.depthMaterialFor(obj.material),
+        };
+        this.depthSwapCache.set(obj, swap);
+      } else if (Array.isArray(swap.swapped)) {
+        // Keep per-group visibility in step.
+        for (let i = 0; i < swap.source.length; i += 1) this.depthMaterialFor(swap.source[i]);
+      } else {
+        this.depthMaterialFor(swap.source);
+      }
+      obj.material = swap.swapped;
+    });
+
+    const previousBackground = scene.background;
+    // Scene fog would blend the encoded depth toward the fog color on any
+    // depth variant that keeps material.fog on (e.g. foliage-provided
+    // variants).
+    const previousFog = scene.fog;
+    const previousClearColor = renderer.getClearColor(this.scratch.clearColor);
+    const previousClearAlpha = renderer.getClearAlpha();
+    scene.background = null;
+    scene.fog = null;
+    renderer.setRenderTarget(this.depthTarget);
+    // Depth clears to 1 (far plane / sky) like the classic depth buffer.
+    renderer.setClearColor(0xffffff, 1);
+    renderer.clear();
+    renderer.render(scene, camera);
+    scene.background = previousBackground;
+    scene.fog = previousFog;
+    renderer.setClearColor(previousClearColor, previousClearAlpha);
+
+    for (const { material, mesh } of materialRestores) mesh.material = material;
+    for (const obj of visibilityRestores) obj.visible = true;
+    materialRestores.length = 0;
+    visibilityRestores.length = 0;
+  }
+
+  renderGrabPass(renderer, scene, camera, waterMesh) {
+    this.ensureGrabTarget(renderer);
+    const restoreFlagged = hideFlagged(scene, (object) => object.userData?.waterExclude);
+    const waterWasVisible = waterMesh.visible;
+    waterMesh.visible = false;
+    const previousTarget = renderer.getRenderTarget();
+    const previousXr = renderer.xr.enabled;
+    const previousShadowAutoUpdate = renderer.shadowMap.autoUpdate;
+    try {
+      renderer.xr.enabled = false;
+      renderer.shadowMap.autoUpdate = false;
+      renderer.setRenderTarget(this.grabTarget);
+      renderer.clear();
+      renderer.render(scene, camera);
+      this.renderDepthPass(renderer, scene, camera);
+      this.grabValid = true;
+    } finally {
+      renderer.setRenderTarget(previousTarget);
+      renderer.xr.enabled = previousXr;
+      renderer.shadowMap.autoUpdate = previousShadowAutoUpdate;
+      waterMesh.visible = waterWasVisible;
+      restoreFlagged();
+    }
+  }
+
+  updateReflectionCamera(renderer, camera, waterY) {
+    const { cameraPosition, cameraDirection, target } = this.scratch;
+    camera.getWorldPosition(cameraPosition);
+    if (cameraPosition.y <= waterY + 1e-4) return false;
+
+    camera.getWorldDirection(cameraDirection);
+    target.copy(cameraPosition).add(cameraDirection);
+
+    const reflectionCamera = this.reflectionCamera;
+    // Prevent the node renderer from rebuilding (and wiping) the oblique
+    // projection: Renderer.render forces updateProjectionMatrix when the
+    // camera's coordinate system mismatches.
+    reflectionCamera.coordinateSystem = renderer.coordinateSystem;
+    reflectionCamera.position.set(cameraPosition.x, 2 * waterY - cameraPosition.y, cameraPosition.z);
+    reflectionCamera.up.copy(camera.up);
+    reflectionCamera.up.y *= -1;
+    reflectionCamera.lookAt(target.x, 2 * waterY - target.y, target.z);
+    reflectionCamera.near = camera.near;
+    reflectionCamera.far = camera.far;
+    reflectionCamera.projectionMatrix.copy(camera.projectionMatrix);
+    reflectionCamera.updateMatrixWorld();
+    reflectionCamera.matrixWorldInverse.copy(reflectionCamera.matrixWorld).invert();
+
+    // Oblique near-plane clipping (Lengyel), same construction as
+    // THREE.Reflector: geometry below the water plane never leaks into the
+    // mirrored image. The node backends use ReflectorNode's coordinate-
+    // system-aware variant of the same construction.
+    const { plane, clipPlane, q } = this.scratch;
+    plane.setFromNormalAndCoplanarPoint(
+      new THREE.Vector3(0, 1, 0),
+      new THREE.Vector3(0, waterY, 0));
+    plane.applyMatrix4(reflectionCamera.matrixWorldInverse);
+    clipPlane.set(plane.normal.x, plane.normal.y, plane.normal.z, plane.constant);
+
+    const projectionMatrix = reflectionCamera.projectionMatrix;
+    q.x = (Math.sign(clipPlane.x) + projectionMatrix.elements[8]) / projectionMatrix.elements[0];
+    q.y = (Math.sign(clipPlane.y) + projectionMatrix.elements[9]) / projectionMatrix.elements[5];
+    q.z = -1.0;
+    q.w = (1.0 + projectionMatrix.elements[10]) / projectionMatrix.elements[14];
+    clipPlane.multiplyScalar(1.0 / clipPlane.dot(q));
+    projectionMatrix.elements[2] = clipPlane.x;
+    projectionMatrix.elements[6] = clipPlane.y;
+    projectionMatrix.elements[10] = renderer.coordinateSystem === THREE.WebGPUCoordinateSystem
+      ? clipPlane.z - this.clipBias
+      : clipPlane.z + 1.0 - this.clipBias;
+    projectionMatrix.elements[14] = clipPlane.w;
+
+    this.reflectionMatrix
+      .copy(BIAS_MATRIX)
+      .multiply(reflectionCamera.projectionMatrix)
+      .multiply(reflectionCamera.matrixWorldInverse);
+    // Node-backend RTs are written top-down: flip the projective v.
+    this.reflectionMatrix.premultiply(FLIP_Y_UV_MATRIX);
+    return true;
+  }
+
+  renderReflectionPass(renderer, scene, camera, waterMesh) {
+    this.ensureReflectionTarget(renderer);
+    this.scratch.waterWorldPosition.setFromMatrixPosition(waterMesh.matrixWorld);
+    if (!this.updateReflectionCamera(renderer, camera, this.scratch.waterWorldPosition.y)) {
+      this.reflectionValid = false;
+      return;
+    }
+
+    const restoreFlagged = hideFlagged(scene, (object) => object.userData?.waterExclude ||
+      object.userData?.waterReflectionExclude ||
+      object.userData?.skipWaterReflection);
+    const waterWasVisible = waterMesh.visible;
+    waterMesh.visible = false;
+    const previousTarget = renderer.getRenderTarget();
+    const previousXr = renderer.xr.enabled;
+    const previousShadowAutoUpdate = renderer.shadowMap.autoUpdate;
+    try {
+      renderer.xr.enabled = false;
+      renderer.shadowMap.autoUpdate = false;
+      renderer.setRenderTarget(this.reflectionTarget);
+      renderer.clear();
+      renderer.render(scene, this.reflectionCamera);
+      this.reflectionValid = true;
+    } finally {
+      renderer.setRenderTarget(previousTarget);
+      renderer.xr.enabled = previousXr;
+      renderer.shadowMap.autoUpdate = previousShadowAutoUpdate;
+      waterMesh.visible = waterWasVisible;
+      restoreFlagged();
+    }
+  }
+
+  render(renderer, scene, camera, waterMesh) {
+    if (this.sceneColorEnabled) this.renderGrabPass(renderer, scene, camera, waterMesh);
+    else this.grabValid = false;
+    if (this.reflectionEnabled) this.renderReflectionPass(renderer, scene, camera, waterMesh);
+    else this.reflectionValid = false;
+  }
+
+  bindToMaterial(material) {
+    const uniforms = material?.uniforms;
+    if (!uniforms) return;
+    if (this.grabValid && this.grabTarget) {
+      uniforms.uSceneColor.value = this.grabTarget.texture;
+      uniforms.uSceneDepth.value = this.depthTarget.texture;
+      uniforms.uUseSceneColor.value = 1;
+      uniforms.uUseSceneDepth.value = 1;
+    } else {
+      uniforms.uUseSceneColor.value = 0;
+      uniforms.uUseSceneDepth.value = 0;
+    }
+    if (this.reflectionValid && this.reflectionTarget) {
+      uniforms.uReflectionMap.value = this.reflectionTarget.texture;
+      uniforms.uReflectionMatrix.value.copy(this.reflectionMatrix);
+      uniforms.uUseReflectionMap.value = 1;
+    } else {
+      uniforms.uUseReflectionMap.value = 0;
+    }
+  }
+
+  dispose() {
+    this.grabTarget?.dispose();
+    this.reflectionTarget?.dispose();
+    this.depthTarget?.dispose();
+    this.grabTarget = null;
+    this.reflectionTarget = null;
+    this.depthTarget = null;
+  }
+}