react-three-water-caustics

Water caustics simulation for React Three Fiber. Provides an interactive, GPU-simulated water surface that projects realistic caustics onto arbitrary meshes, via a Provider + Hook pattern.

Features

• Provider + Hook architecture — WaterCausticsProvider runs the water simulation once; any descendant reads shared uniforms via useWaterCaustics().
• World-space projected caustics — caustics project onto any mesh using world XZ coordinates, not just a single plane.
• Interactive ripples — CausticsInteractionPlane turns pointer move/down events into ripples and drops in the simulation.
• Ambient auto-ripples — toggle periodic ambient ripples with enableWaterDrop.
• Shared uniform references — the provider creates { value } uniform objects once; consumers spread them into their own ShaderMaterial/CustomShaderMaterial instances and the provider's per-frame mutation updates every consumer without each one needing its own useFrame.

Install

npm install react-three-water-caustics

Peer dependencies: react >=18, three >=0.150, @react-three/fiber >=8.

Quick Start

import { Canvas } from "@react-three/fiber";
import {
  WaterCausticsProvider,
  useWaterCaustics,
  CausticsInteractionPlane,
  poolCausticsVertexShader,
  poolCausticsFragmentShader,
} from "react-three-water-caustics";

function CausticsFloor() {
  const { uniforms } = useWaterCaustics();
  return (
    <mesh rotation={[-Math.PI / 2, 0, 0]}>
      <planeGeometry args={[10, 10]} />
      <shaderMaterial
        vertexShader={poolCausticsVertexShader}
        fragmentShader={poolCausticsFragmentShader}
        uniforms={uniforms}
      />
    </mesh>
  );
}

export default function Scene() {
  return (
    <Canvas camera={{ position: [0, 3, 8] }}>
      <WaterCausticsProvider size={10} waterSurfaceY={4}>
        <CausticsFloor />
        <CausticsInteractionPlane />
      </WaterCausticsProvider>
    </Canvas>
  );
}

WaterCausticsProvider props

| Prop | Type | Default | Description | |---|---|---|---| | position | [number, number, number] | [0, 0, 0] | World position of the water volume. | | size | number | 10 | Width/depth of the simulated water area. | | enableWaterDrop | boolean | true | Periodically spawn ambient ripples in the water simulation. | | chromaticAberration | number | 0.005 | Chromatic aberration strength applied by the caustics shaders. | | waterSurfaceY | number | 5 | World Y coordinate of the water surface plane. | | depthColor | string | '#66e5ff' | Tint color applied with depth. | | depthDistance | number | 5 | Distance over which depthColor fully applies. | | lightDir | [number, number, number] | [0.667, 0.667, -0.333] | Normalized light direction used by the caustics shaders. |

useWaterCaustics() return value

| Field | Type | Description | |---|---|---| | uniforms | WaterCausticsUniforms | Shared uniform references (auto-updated by the provider). | | addDrop | (x, y, radius?, strength?) => void | Add a ripple at simulation coordinates (-1 to 1). | | enableWaterDrop | boolean | Current value of the enableWaterDrop prop. |

Shaders

| Shader | Description | |---|---| | poolCausticsVertexShader / poolCausticsFragmentShader | Caustics for a flat pool floor. | | projectedCausticsVertexShader / projectedCausticsFragmentShader | Generic world-space projected caustics with a baseColor uniform. | | projectedTileCausticsFragmentShader | Tile caustics with PBR textures + refraction (pair with projectedCausticsVertexShader). | | waterSurfaceVertexShader | Vertex shader for rendering the animated water surface itself. |

Run the Examples

git clone <repository-url>
cd react-three-water-caustics
npm install
npm run dev

Open the URL Vite prints (usually http://localhost:5173). The examples app (examples/) is a full demo scene — pool, projected caustics on a sphere and tile, and a water surface with pointer ripples — built entirely against the published public API.

License

See LICENSE.