API reference

Builds the system: the render target with its depth texture, the overlay scene, the optional sky dome (added to options.scene) and the water map. new RiverSystem(options) does the same synchronously.

It throws if renderer, scene or camera is missing.

Call once per frame, before render(). It advances time (dt in seconds, clamped to 0 – 0.1), eases the displayed values toward params, rebuilds meshes after authoring or quality changes, re-renders the water map when bodies change, applies lighting, fog and exposure, picks the nearest obstacles and moves the floaters.

Draws the whole frame: scene into the HalfFloat render target with a DepthTexture, then the overlay (composite of that target, tone mapped with depth restored, then lakes, rivers, waterfall sheets, mist and spray). Use it instead of renderer.render(scene, camera). Pass a WebGLRenderTarget as output to draw somewhere other than the screen, for example for your own post-processing.

Matches the internal target to renderer.getDrawingBufferSize() × the tier's rtScale. Call it after renderer.setSize() or setPixelRatio(). render() also checks the size on every frame.

Frees every GPU resource, removes the sky dome and the library's meshes, and clears the floaters.

Adds a ribbon along a spline. The mesh is built on the next update() or render().

See Rivers and lakes.

Adds calm, flat water inside a polygon or a circle. Give polygon, or center and radius; otherwise it throws.

Adds a cascade from a lip to a pool.

Up to 4 waterfalls feed lip clips, plunge foam, ripple rings and splash zones. See Waterfalls.

Adds a foam ring, bow pillow and downstream wake. position is a Vector3 or { x, z }, and radius is measured at the waterline. Returns { position, radius, strength }; edit it in place to move the obstacle. Each frame the nearest maxObstacles to the camera are used.

Removes an obstacle returned by addObstacle().

Removes a River, Lake or Waterfall and disposes its geometry.

Returns heightFn with every current body's bed, basin and plunge pool blended in, and low banks raised to the water. Where bodies overlap the lowest result wins. It's a snapshot: call it again after adding or removing bodies. See Terrain and materials.

Injects the waterline wet band, splash zones, underwater tint, sun attenuation, caustics and caustic reflections into a MeshStandardMaterial or MeshPhysicalMaterial. Lambert and Phong get the colour and caustic parts. Chains an existing onBeforeCompile; patching the same material twice does nothing. Returns the material.

The highest water surface at (x, z): { height, flow: Vector2, speed, edge, inside, body }. flow and speed include the global water.flow multiplier. null where there is no water. See Flow, rocks and floaters.

The water level, or null.

The surface velocity in m/s, copied into target (a new Vector2 if omitted), or null.

true inside a river's banks or a lake's shore.

true when the camera (default: the system's) is below a water surface. Nothing is rendered differently.

The eased water.flow value.

Uses an external sky. Every field is optional and read by reference each frame: sun: { direction, color?, intensity? }, envMap (equirect), envIntensity, cloudShadow: { texture, matrix }, fogColor, skyColor. While set, the built-in dome is removed and bound lights aren't driven. null restores the built-in sky. See Sky and lights.

Lets the preset drive a DirectionalLight (colour, intensity, and position at target.position + sunDirection × distance) and a HemisphereLight. Either can be null. Only active with the built-in sky.

Replaces params with a preset name or a complete preset object. Lighting eases over about 1.5 s and water over about 0.3 s; instant: true snaps. Throws on an unknown name.

A deep copy of the current settings, in preset format.

Sets one value by dotted path, for example setParam('water.clarity', 1.4) or setParam('light.sunColor', '#ffd9a0').

Switches tier: recompiles the water shaders and patched materials, rebuilds meshes, resizes the water map, and recreates the render target when MSAA changes. Unknown levels and the current level are ignored.

Floats anything with a position (and optionally a rotation) from its current xz.

Stops floating obj.

Removes every floater.

A centripetal Catmull-Rom centre line, resampled by arc length every 0.5 m, with per-sample level, half width, depth and tangent, and a uniform grid for fast nearest-point queries. options takes width, widths, depth, depths, and step (resample spacing, default 0.5 m).

The nearest point on the centre line: { s, lateral, dist, overshoot, level, halfWidth, depth, tx, tz, slope }. s is metres along the path, lateral the signed distance across, and overshoot the distance past either end.

Every built-in preset by name: clear, morning, golden, overcast, glacial, muddy, swamp, dusk, night.

A deep clone of a built-in preset. Throws on an unknown name.

{ rtScale, samples, ssrSteps, normalLayers, maxObstacles, ribbonStep, crossSegments, spray, mist, waterMap, causticLayers } per tier. See Quality levels.