Guides

Waves, wind and foam

Three numbers shape the sea. Wind speed sets how high and how steep the waves are, the peak wavelength sets how long the swell is, and the direction sets where it travels. Foam follows from how hard the crests fold.

storm: 19 m/s wind over a 72 m swell. Significant wave height is 6.08 m, and whitecaps linger in the persistent foam field after the crests pass.

#The wave dials

Param	Default	Effect
`wind`	`6`	Wind speed in m/s. Sets the significant wave height and the chop
`wavelength`	`32`	JONSWAP peak wavelength in metres: the length of the swell
`windDirection`	`216.87`	Direction the waves travel toward, in degrees (0 = +X, 90 = +Z)
`choppiness`	`1`	Multiplier on the wind-derived steepness

The wave height comes straight from the wind and the wavelength:

Hs   = min(0.21 · wind² / g, wavelength / 12) + 0.08      (metres)
chop = min(0.92, (0.38 + wind / 32) · choppiness)

So a longer wavelength only raises the sea once the wind can build it, and short waves can't get taller than a twelfth of their length. Read the result at runtime from water.stats.significantWaveHeight and water.stats.chop.

water.setParams({ wind: 14, wavelength: 60 });     // a building sea, eased
water.setParams({ windDirection: 90 });            // waves travelling toward +Z
water.stats.significantWaveHeight;                 // ≈ 4.3 m once eased

The spectrum is rebuilt from the eased values every frame, so changing wind or wavelength morphs the sea rather than jumping. Every numeric param eases toward its target over about 1.5 s. time and windDirection take the short way round.

#Two wave sources

The quality tier picks where the waves come from. Both read the same wind, wavelength and windDirection, so presets look alike on every tier.

	Gerstner (low, medium)	FFT (high, ultra)
What it is	24–56 Gerstner waves sampled from a JONSWAP spectrum	Tessendorf FFT of a JONSWAP directional spectrum
Resolution	`waves` components	128² × 2 cascades (high), 256² × 3 (ultra)
Tiling	None, it's analytic	The 512 m swell cascade repeats, softened by rotated detail cascades (67.3 m, 10.7 m) and fog
CPU sampling	Evaluates the same sum	Reads back the swell cascade, 1–3 frames late

water.setQualityLevel('high', { waveSource: 'gerstner' });   // Gerstner on the high tier
water.setQualityLevel('ultra', { fftCascades: 2 });            // cheaper FFT
water.fft;                                                     // FFTWaves on FFT tiers, else null

Either way the ocean is a polar grid centred on the camera. Long waves displace the vertices, the short band is added per pixel, and waves smaller than a pixel become surface roughness. That's why far water turns rougher and brighter instead of shimmering.

#Foam

Foam comes from five places:

Source	Dial
Whitecaps and streaks	`foam` (1)	Where crests fold (the displacement Jacobian drops), plus wind streaks above about 9 m/s
Linger time	`foamPersistence` (4 s)	How long whitecap foam takes to fade, scaled by `0.5 + wind / 20`
Breakers and swash	`shoreFoam` (1)	Where shore waves break, and the swash on beaches. See Shorelines
Contact line	`shoreFoam` (1)	A thin line wherever your geometry pierces the surface, found from the depth buffer
Hulls	`addWake`	White water round each tracked hull, a Kelvin V and a trail. See Buoyancy and wakes

On medium and above, whitecaps are stamped into a persistent foam field: a texture of 256² to 1024² texels covering 256–400 m round the camera. Foam stays where the crest broke, drifts with the wind, and breaks up into lace as it fades. On low the field is off and foam lives only on the crest that makes it.

water.setParams({ foam: 1.6, foamPersistence: 8 });   // long-lived, heavy whitecaps
water.setParams({ foam: 0 });                          // glassy, no whitecaps

#The look of the surface

These change how the water shades, not how it moves.

Param	Default	Effect
`glitter`	`1`	GGX sun specular. The peak is clamped, so the sun path glitters without fireflies
`sss`	`1`	Subsurface light through thin crests
`reflections`	`1`	Screen-space reflections of your scene (high and ultra). The sky is always reflected
`refraction`	`1`	Refraction distortion and the depth blur of the seabed

`sunset`: a long glitter path under a low sun

`arctic`: 11 m/s over a 55 m swell, steel-blue water

The full list is on Water parameters.