Under the hood

What happens in update() and render(), and what changed from the waterpro.html page this package grew from. Drag each slider to compare the original with the package.

#The frame

#Rebuild, only when needed

After you add or remove a body, or change tier, update() rebuilds the meshes. Rivers become ribbons with flow-space attributes, lakes become discs or triangulated outlines, and waterfalls become two sheets and two particle systems. The lip clips and plunge data go into shared uniforms.

#The water map

A top-down orthographic render of every surface into a small HalfFloat target: level, flow x, flow z and coverage. It is re-rendered only when bodies change. Patched materials read it to know where they are under water, and how deep.

#The world pass

render() draws your scene, with the sky dome inside it, into a HalfFloat render target that has a DepthTexture (and 4× MSAA on ultra).

#Composite

A fullscreen blit copies that target to the output, tone maps it and writes gl_FragDepth, so the depth buffer holds your scene again.

#Water surfaces

Lakes (opaque), then rivers (with their end fades), each reading the world colour and depth. The shader measures the water thickness along the view ray, refracts, applies Beer–Lambert absorption and in-scatter, reflects the sky, the tree line and, on high and ultra, the screen. It then adds glints and foam and applies the scene's fog.

#Cascades and particles

Waterfall sheet and veil refract the world target. Mist and spray are soft particles faded against the depth texture.

#Flow mapping without pulsing

Ripples and foam are sampled in each ribbon's flow space: metres across and metres along. They are advected with two-phase blending: two copies of the texture scroll with the current and cross-fade, so neither stretches forever. Plain two-phase blending pulses visibly at the crossover. NatureGL River removes that with two changes:

a per-pixel phase jitter from a noise channel, so the crossover happens at different times across the surface
a variance-preserving blend weight, so the mix keeps its contrast at the crossover instead of turning grey

Two layers run at different periods (1.1 s and 1.73 s), and the textures stretch along the current in proportion to speed.

#Changes from waterpro.html

The original page hard-coded one stream: riverX(z), riverW(z), two flat water planes and a fixed cascade. The package keeps its look (the pebbled bed, the turquoise Beer–Lambert water, the tree-line reflections and the mossy granite) and makes all of it authorable. The demo valley is that original stream, rebuilt through the API.

The stream in the original page and in the NatureGL River demo, 1280×720.

waterpro.html — The stream in the original page and in the NatureGL River demo, 1280×720.

#The cascade

The original fall was a fixed sheet. The new one is a ballistic curtain: a glassy, refracting lip, then an aerated curtain whose streaks accelerate with the fall. It adds an aerated veil layer, ragged edges, soft-particle spray and billowing mist, a boiling plunge churn, a foam plume carried downstream, and radial ripple rings in the pool.

#Rocks at the waterline

Boulders now get a hugging foam ring, a bow pillow and a bounded wake that follows the flow. The rock surface itself has a noisy, lapping wet band that is darker, more saturated and glossier, with a tide line. On high and ultra the water reflects the rocks through screen-space reflections, where the original reflected only the sky and a tree-line colour.

#Also new

Shallow transparency. The first few centimetres of water fade into the unrefracted bed, which removes the hard line where water meets ground. Refraction strength scales with depth.
Caustics are focused by depth, with dispersion that grows with depth. They animate faster in fast water and break up in rapids. Sunlight is attenuated on its way through the water to the bed, so muddy water darkens the bed. Faint caustic reflections dance on rock faces just above the waterline.
Speed follows width at constant discharge, and steep sections become rapids with extra turbulence.
Five new looks (glacial, muddy, swamp, dusk, night) join the original four lighting options, and presets ease in.
three r160 → r186 with no deprecation warnings: THREE.Timer instead of Clock, and PCFShadowMap with shadow.radius instead of PCFSoftShadowMap.