3D Water · Expansion packs · Phaser AE

What it does

There are two shapes of water. Grid waters, the sea, ocean, lake and pool presets, are a shared grid moved by summed Gerstner waves, whose crests travel forward as well as up, gathering at the peaks and spreading in the troughs, which is what the eye reads as water rather than cloth. The presets differ only in their wave tables and colours. Ribbon waters are strips that follow a course over the terrain with the flow scrolling along them; steep sections foam, so a waterfall is simply a stream whose course runs off a cliff.

Hand it your terrain's height function as ground and it bakes it once, which switches on the whole shore. Waves shoal against the real beach and die away just before the waterline, the water parks below dry sand so the edge glides in and out with the tide, and bands of surf march up the shallows along the depth contours, following any coastline you give it.

heightAt is the exact wave the GPU draws, with the same swell, tide and shoaling, and it undoes the waves' sideways drift, so it reports the water that is actually visible at a point. hullPose turns four samples at bow, stern, port and starboard into a height, pitch and roll, and float applies that to an object every step while your game steers it. A well, a dry box around a hull, presses the surface down inside it so waves never rise through the deck, and stamps a foam wake that curves with the boat's real path and fades like froth. Seen from below, the surface shows the sky through a window overhead and a mirror of the depths around it.

Features

Five presets — sea, ocean, lake, pool and stream, each a wave table and a palette.
Waves you can author — up to eight waves a body, each with a direction, amplitude, wavelength, speed and crest sharpness.
Sea state and tide — swell runs from glass at 0 to a storm of triple height at 1, live, and tide and tidePeriod move the waterline.
Shores from your terrain — ground gives shoaling waves, a waterline that follows the tide, and surf along the coast.
Streams and waterfalls — a path downhill with a width and a flow speed.
Floating — heightAt, normalAt, submerged, hullPose and float, with length, beam, ride height, settling time, trim and heel.
Wells and wakes — up to four dry hull boxes a body, each with a foam wake of its own strength.
Named tints — caribbean, azure, temperate, emerald and northsea, palette and optics in one.
Many bodies at once — build the main body and add lakes, pools and streams beside it, every option a live field.
Lit and reflected — it reflects the sky's environment map and takes the scene's point and spot lights, so a lighthouse beam lands on the sea.
Both renderers — WebGPU and WebGL2, with the queries running headless from the simulation clock.

Good for

Boat and sailing games — hulls that pitch and roll on the swell, with wakes that follow every turn.
Jet-ski and powerboat racing — a squat at speed through trim, and a ride height that rises with the swell.
Island and beach scenes — a tide that washes a real shoreline and surf that follows the coast.
Open worlds with lakes and rivers — many bodies at once, with streams and waterfalls down the hills.
Swimming and diving — submerged tells the game when to swim, and the surface shows no crack as the camera crosses it.
Storms — raise swell live and the waves grow taller, sharper and faster together.
Games for WebGL2 devices — the same water where a WebGPU-only ocean cannot run.

Make it yours

The pack's options are the main body's: its preset, level, centre and extents, the wave table, the shallow, deep and foam colours, opacity, ripple strength, how quickly depth turns the colour deep, the shore foam width, swell, tide and its period, a tint, the ground function and the grid resolution. A ribbon adds its path, width and flow. Every one of them is a live field on the body afterwards.

Two very different scenes: a stormy northsea whose swell climbs during a level, with a skiff floated on it, its trim and ride height following the sea state and a well keeping its deck dry; and a calm mountain valley, an emerald lake at the height of its basin, shoaling against the terrain, fed by a brook that runs down from the hills.

A quick look

A sea that shoals against the terrain, a stream, and a boat kept on the waves:

const ground = (x: number, z: number): number => game.terrain.heightAt(x, z);
const sea = game.water.build({ preset: 'sea', level: 0, size: 6000, tide: 1.6, ground });
const brook = game.water.add({ path: [[400, 22, -160], [430, 18, -60], [470, 2, 40]], width: 5, flow: 6 });
sea.swell = 0.8;
sea.setTint('northsea');
const skiff = game.world3d.spawn({ mesh: 'box', x: 0, z: 520, sx: 4, sy: 1.2, sz: 10 });
game.water.float(skiff, { length: 10, width: 4.4, offset: 0.7 });
const hull = sea.well({ w: 5, d: 11, floor: -1.2, wake: 0.8 });

Works with

terrain-3d — the ground its shores shoal against.
underwater-3d — the view from below the surface: colour lost with depth, a waterline, caustics and fog.
sky-3d or skymax — the environment map it reflects.
rider-3d — to ride the swell with a footprint.
render-3d and world-3d — required; it draws against the renderer's depth.
watermax — the alternative for a simulated FFT ocean on WebGPU only, at a much higher cost; compose one or the other, never both.

Good to know

It reflects the sky, not the boats on it: there is no reflection of scene geometry, and no refraction beyond the depth-tinted colour.
float follows four height samples; it is not a buoyancy solver, so nothing sinks, drifts or feels a force.
Each body takes eight waves and four wells, and wakes are drawn for at most four wells a frame within 360 units of the camera.
Streams answer their still level and are shallow decoration, not swimming water.
The ground bake runs once, on the first frame a body is drawn, and a body cannot be resized afterwards; build another.