ocean

The oceans package's substrate. One Ocean.create call brings up a live sea: the GPU wave simulation, the surface mesh that renders it, the material bound to the simulation's output, and the body of water physics reads.

The simulation is spectral and runs in cascades — independent wave fields over different patch sizes, each band-limited to its own range of wavelengths, summed into one surface. That is what gives detail at every scale (swell, wind waves, chop) while keeping each transform small.

The surface is one mesh whose vertices a compute pass rewrites every frame, so no wave data crosses to the CPU for rendering. It is graded radially and follows the viewer, snapped to a wave-patch multiple so the sea stays put in the world while the mesh slides under it.

sampleHeight / sampleDisplacement answer where the water is from the sea's physics band: the cascades' waves of at least physicsWavelength metres and the swell, defined as a body of water (Physics.water reads it as ocean.waterName) and evaluated on the CPU at the water clock's moment, which every peer shares. The drawn surface is that band plus the shorter chop, drawn from the same amplitudes; physicsBand states the difference and measureAgreement measures it. Both invert the horizontal wave displacement, so they return the surface point that actually ended up above the position you asked about.

Use the Ocean component to place a sea in a scene; use this module directly to drive one from code.