API reference

Builds the ocean mesh and the built-in sky dome and adds both to options.scene. The constructor is synchronous, since every texture is procedural; create() is async to match the other NatureGL packages, and new WaterSystem(options) works too.

Advances time by dt seconds (clamped to 0.1). Eases params toward their targets, rebuilds and advances the spectrum, updates the sky, the underwater state, buoyancy, wakes and the foam simulation. Call it once per frame before render(), after you move your objects.

Runs the depth pipeline for scene and camera and composites into target (the canvas by default). Restores renderer.autoClear and the previous render target. See Rendering.

Passes 1–3 only (world, water, overlay) into the pipeline's linear HDR target, with no bloom or tone mapping. depthTexture holds world and water-surface depth. The size is the drawing buffer × renderScale. The underwater colour grade is skipped; the underwater fog is kept.

Re-reads renderer.getDrawingBufferSize() and resizes the offscreen targets. render() does this on its own; the camera's aspect is yours to update.

Removes the ocean and sky from the scene and frees the GPU resources.

Switches to a built-in preset by id, or to any partial params object. Missing keys come from DEFAULT_PARAMS. opts.instant skips the ease.

Changes some target params; the rest keep their values. opts.instant snaps.

A deep, JSON-safe copy of the target params. Paste it into a preset file.

Switches tier at runtime and rebuilds only what changed: spectrum size, grid, shaders, FFT, foam field, targets, and the bathymetry bake if its resolution changed. overrides replace single settings, for example setQualityLevel('high', { msaa: 0, ssrSteps: 32 }).

Plugs in an external sky, read every update(). null returns to the built-in sky and re-adds its dome if addSky. Options: sunIntensityScale (1), moonIntensityScale (1), moonTint, envIntensity (1), syncExposure (true). See Any sky-like object.

Points a DirectionalLight at the water's current key light (sun by day, moon by night) and colours a HemisphereLight from the sky. opts.distance (250) places the light from its target; opts.intensity (1.3) splits colour and intensity. See Sky and lighting.

Bakes a seabed from { heightAt(x, z), bounds, resolution?, shoreTrainMinRadius? } so waves shoal, breakers roll up the beach and shore foam follows the coast. null returns to open ocean. See Shorelines.

Surface height at world (x, z), including shoaling and breakers. The horizontal displacement is inverted in 4 fixed-point steps. Gerstner tiers evaluate the spectrum; FFT tiers read the swell cascade back from the GPU (1–3 frames old).

Central differences of sampleHeight at ±0.5 m.

Whether object (default: the camera) is below the surface.

Floats an object. Options: probes, size: { length, beam }, draft (0), heightSmoothing (2.5), rotationSmoothing, spring (true), tiltSample (0.8), rollJitter (0.012). You keep x, z and the heading; buoyancy writes height, pitch and roll. See Buoyancy and wakes.

Stops floating an object. handle.enabled = false pauses one instead.

Tracks a moving object: hull contact foam, a Kelvin V and a persistent trail. Options: length (10), beam (length / 3), headingOffset (0), useVelocityHeading (false). handle.speed is the measured speed in m/s. Up to MAX_HULLS (8) are drawn.

Frees the object's wake slot.

Adds animated caustics below sea level to a built-in lit material (Standard, Physical, Lambert, Phong, Toon), chaining onBeforeCompile. Options: strength (1), scale (0.11), lightAbsorption (0.25). See Caustics on your materials.

The analytic sky: sun arc from time, zenith and horizon colours, a cloud deck, stars and moon. new BuiltinSky({ uniforms? }), mesh, sun, sunDirection, moon.direction, fogColor, ambient { sky, ground }, day, apply(params), follow(camera), bindLights(directional, hemisphere, opts), dispose(), and BuiltinSky.createUniforms().

new Buoyancy(surface) works with any object that has sampleHeight(x, z). addObject, removeObject, update(dt), objects.

add, remove, update(dt), list, and the hullA / hullB uniform arrays the shaders read. MAX_HULLS is 8.

new Caustics(uniforms), patch(material, opts), and the static Caustics.glsl (the same as CAUSTIC_FN_GLSL) for custom shaders.

The Gerstner spectrum shared by the GPU and the CPU: new WaveSpectrum(count), build(U, Lp, windAngle, chopScale), advance(dt), displacement(x, z, att, out), WA / WB uniform arrays, hs, chop, setCount(n).

bake(desc, defaultResolution), sample(x, z, out?) → { seabed, dist, dx, dz, train, breaking }, texture, trainTexture (1.1), xform, enabled.

The GPU FFT wave source: new FFTWaves(renderer, { size, cascades }), update(time, { wind, wavelength, windAngle, chop, hs }), sample(x, z, out) from the read-back swell cascade, targets[i].textures[0..1], slopeVariance[i], lambda, cascades[i] (L, rot, kmin, kmax, texel).