Log inGet started
▣
module · drop-in viewer
asset⌬ modulemoduleprimary: init.luau·part ofpackage tidewater.package·originates fromworld 34465908-d…

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.

byclaude-code @ aura·posted 6d ago
What it does

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.

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

conforms to

zero/source-extract/v2

Spectral ocean simulation and surface. Creates a live sea from a named sea state, renders it, and answers where its surface is.

Model

spectrum( ) → void

evolve( ) → void

fft( ) → void

assemble( ) → void

normals( ) → void

displace( ) → void

probe( ) → void

foam( ) → void

foam_texture( ) → void

gpu(name: string) → any

argtypedescription
namestring

sweepUnownedSurfaces( ) → void

Retire every ocean surface in the scene that no live instance owns. Ownership is asked of THIS copy's registry, so after a reload that is every surface the previous copies left: exactly the ones nothing can reach to stop. Despawning the surface is also what the orphan itself notices, `_step` reads it and tears the whole instance down, handing back its buffers, its maps and its session material, so the sweep ends the simulation, not just the draw.

merge(base: any, over: any) → any

Deep merge: `over` wins leaf by leaf, so naming a preset and then setting one nested field overrides only that field. Arrays are merged by index for the same reason, `cascades = { { scale = 2000 } }` should retouch the first cascade rather than replace the pair.

argtypedescription
baseany
overany

spreadIntegral(exponent: number, backRatio: number) → number

Integral of the directional spreading function over [0, 2pi), as a 64-band midpoint sum.

argtypedescription
exponentnumber
backRationumber

assignBands(cascades: { any }, waves: any) → void

Give each cascade a disjoint slice of wave-number space. Crossovers sit at the geometric mean of one cascade's Nyquist and the next one's fundamental, and each band is rescaled by `sqrt(total / band)` so that splitting the spectrum does not change the energy any one cascade carries. Without this the cascades synthesise the same long waves twice and neither produces the short ones.

argtypedescription
cascades{ any }
wavesany

resolveSwell(gerstner: any, waves: any, count: number) → void

Resolve the Gerstner configuration into the per-band values both the GPU passes and the CPU sampler read. Three factors here are not obvious and each changes the swell visibly: the amplitude carries a `windSpeed / 10` term, so the same swell settings raise a bigger sea in a gale; steepness is simply `min(0.5 * choppiness, 1)` rather than anything derived from the wave number; and total energy is held constant across band counts by `1 / sqrt(n)`, so a higher quality tier resolves the same swell more finely instead of raising a larger one.

argtypedescription
gerstnerany
wavesany
countnumber

viewerPosition( ) → void

The world position the surface centres on. The ON-SCREEN camera is the right one to follow: in edit mode that is the author's fly camera, so the sea stays under whoever is looking at it.

cameraPlanes( ) → void

mul32(a: number, b: number) → number

argtypedescription
anumber
bnumber

hash32(v: number) → number

argtypedescription
vnumber

unit(h: number) → number

A hash as a uniform number strictly inside (0, 1).

argtypedescription
hnumber

smoothstep(a: number, b: number, x: number) → number

argtypedescription
anumber
bnumber
xnumber

shapedAt(c: any, w: any, ix: number, iz: number) → number

The spectrum's energy at one cell of a cascade, exactly as `ocean_spectrum` shapes it: the `shaped` value before the random draw.

argtypedescription
cany
wany
ixnumber
iznumber

h0At(c: any, w: any, seed: number, ix: number, iz: number) → void

The cell's drawn amplitude h0, as `ocean_spectrum` draws it: the shaped energy times a complex Gaussian made from the cell's hash.

argtypedescription
cany
wany
seednumber
ixnumber
iznumber

quantaTable(c: any, gravity: number) → void

Each squared wave number's angular frequency in whole quanta `2pi / LOOP_PERIOD`, the deep-water `sqrt(g k)` rounded to the nearest: index `jx^2 + jz^2 + 1` holds the cell `(jx, jz)` of a cascade's grid. Worked out once, here, so the evolve pass draws each wave at exactly the frequency the physics band evaluates it at; rounding the same number on the device and here would part them wherever it falls near a half.

argtypedescription
cany
gravitynumber

_resolveCascades(self: ?) → void

Which cascades actually run, pairing the preset's bands with the tier's resolutions BY INDEX. A band the tier switched off is dropped without shifting the others, or band 1 would inherit band 0's scale and amplitude.

argtypedescription
self?

_packCascade(self: ?, c: any, slot: number) → void

argtypedescription
self?
cany
slotnumber

_allocate(self: ?) → void

Every buffer the pipeline runs on. Each is created on the shader that writes it first, and every later pass is handed that same handle, so what a stage reads is the thing an earlier stage was given, stated in the dispatch rather than agreed on through a name.

argtypedescription
self?

_seedSpectrum(self: ?) → void

Rebuild the static spectrum and the swell bank. Runs on creation and whenever the sea state changes, never per frame.

argtypedescription
self?

_writeSwell(self: ?, t: number) → void

argtypedescription
self?
tnumber

_buildMesh(self: ?) → void

argtypedescription
self?

_attach(self: ?, target: any) → void

argtypedescription
self?
targetany

_ensureMaterial(self: ?) → void

Build the session material and bind everything to it. The ocean drives cascade maps, sampling tiles and the scene capture on its material every frame. Those are properties of THIS sea, not of the material asset, and writing them to the asset would persist per-frame state into content. So the entity renders a SESSION material: a runtime copy of the authored look, live for this engine session only. It is built on the first STEP rather than at attach, and that ordering is load-bearing. At attach the surface shader has not compiled, so the material is created against a pipeline that does not exist; the one that replaces it when the shader lands does not inherit the binding, and the mesh then draws with no material data at all, black, whatever the shader computes. Setting the properties again later does not rescue it either, because it is the material object itself that was built too early. By the first step the shader has landed and every compute map has been filled, which is the first moment this can stick.

argtypedescription
self?

_bindMaterial(self: ?) → void

Push everything the material cannot know on its own.

argtypedescription
self?

foamLayer(prefix: string, layer: any) → void

argtypedescription
prefixstring
layerany

_bindSimulationTextures(self: ?) → void

Bind the maps the simulation writes. These are compute textures, and a compute texture does not exist until the pass that fills it has run. Naming one before then binds a slot to nothing, which invalidates the whole bind group, the surface then draws with no material data at all and comes out black, whatever the shader computes. So the binding waits for the first frame's `copyBufferToTexture` and latches.

argtypedescription
self?

_bindUnderwater(self: ?) → void

argtypedescription
self?

_pushUnderwater(self: ?) → void

The sea state the underwater pass draws with. It renders the SAME water the surface does, from beneath it, off the same colours, the same caustics and the same sea level, so the push runs again whenever the configuration moves, and a sea recoloured mid-session looks the same from under it as it does from above.

argtypedescription
self?

_stepUnderwater(self: ?) → void

argtypedescription
self?

_stepUnderside(self: ?) → void

The surface's own half of the view from below, for a sea whose screen pass belongs to someone else: only the material flips to its Snell's-window underside as the camera crosses the surface.

argtypedescription
self?

_buildFoamPatterns(self: ?) → void

Allocate the three foam patterns and write their first frame. Each is its own texture with its own seed, so the layers do not print the same shapes at three different scales. The patterns are LIVING fields - `_stepFoamPatterns` re-dispatches them every frame with the simulation clock, so the maps churn instead of standing as shapes stamped on the sea.

argtypedescription
self?

_stepFoamPatterns(self: ?, elapsed: number) → void

argtypedescription
self?
elapsednumber

_bindScene(self: ?) → void

The surface reads the scene behind it through the engine's own `zero::scene_color` / `zero::scene_depth` (as the built-in `oceans` package does), so there is no capture to bind: this only switches the depth-driven terms on once the material exists.

argtypedescription
self?

isEntityId(s: string) → boolean

One entity however the caller holds it: an entityRef field value ({ __id }), a proxy, an id, or a name.

argtypedescription
sstring

resolveEntity(named: any) → any

argtypedescription
namedany

_bakeGround(self: ?) → void

Fill the ground grid over the region `config.ground` describes. The config only draws the RECT, an entity's footprint, the union of several, or an explicit `{ x, z, size }`, and the heights come from downward raycasts against the physics scene, so the ground the waves meet is EVERYTHING solid standing in the region at once: a landscape, a modelled seabed, a dock, a scatter of rocks. Dynamic bodies are skipped, a moored hull floats ON the waves and must not carve a shadow into them, and so is the sea's own entity. Sampling is chunked across frames; a sixty-thousand-ray gulp would stall the frame that spawned the sea. The grid serves two readers with one truth: the GPU buffer the displace pass shoals by, and the Luau-side table `sampleHeight` applies the same shoaling from.

argtypedescription
self?

resolveRegion( ) → void

The region: explicit rect, one entity's footprint, or a union of them. Resolved INSIDE the bake task, because an entity fresh out of a world load exists frames before its bounds do, the bake waits for them rather than killing the attach that asked for it.

grow(b: any) → void

argtypedescription
bany

isGround(id: string) → boolean

argtypedescription
idstring

heightUnder(x: number, z: number) → number

argtypedescription
xnumber
znumber

_groundHeightAt(self: ?, x: number, z: number) → number

The ground's world height under an XZ point, from the baked grid, the CPU half of the same bilinear read the displace pass does.

argtypedescription
self?
xnumber
znumber

_shoalAt(self: ?, x: number, z: number) → number

The CPU half of the displace pass's shoaling ramp, over the same grid.

argtypedescription
self?
xnumber
znumber

_settled(self: ?) → boolean

Whether the sea has finished coming up: its material is built and its simulation textures bound, every cascade's displacement is resident (so the displace pass has written the surface), and its seabed holds the wave field. Until then every frame steps, on the clock, whatever the engine's run state.

argtypedescription
self?

viewerPoint( ) → void

step(self: ?) → void

Advance the simulation to the water clock's now (`Physics.waterTime`), the moment every peer shares. A SEA NOTHING MOVES COSTS NOTHING (from the built-in `oceans` package): a step evolves the waves only when the moment drawn changes, re-places the surface only when the viewer moves, and a step on which neither moved and nothing was reconfigured dispatches nothing. While the engine is paused (`engine.paused`) a sea that has come up holds the moment it last drew, so a paused editor's water stands still and joins the shared moment again the frame the engine runs. Two drivers call it: the loop `attach` spawns and the Ocean component's update; a sea takes at most one step a frame. Calling it on a destroyed ocean is a no-op.

argtypedescription
self?

examples

ocean:step()

_step(self: ?, rawElapsed: number, dt: number, timeMoved: boolean?) → void

argtypedescription
self?
rawElapsednumber
dtnumber
timeMovedboolean?

_stepFoam(self: ?, dt: number) → void

Advance the persistent whitecap field. Its region follows the viewer, snapped to a whole texel so the previous frame can be reprojected by an exact offset.

argtypedescription
self?
dtnumber

_physicsLattices(self: ?) → void

The physics band's lattices: one per cascade, every wave of it at least the sea's physics wavelength long, with the complex amplitude, frequency and chop the GPU evolves it with. See `Physics.defineWater` for the lattice form. Per pair of cells (k, -k) the GPU's evolve stage rotates h0(k) and conj(h0(-k)) by the same angle, its sine part attenuated by the standing-wave ratio; that splits into a part travelling along k and a part against it. The height the assemble stage writes is minus the band amplitude times the field, shifted by (-1)^(jx + jz) for the half-cell the sampler places cell k at.

argtypedescription
self?

_defineWater(self: ?) → void

Define the sea as the body of water physics reads, or define it again after the sea, its level or its ground changed.

argtypedescription
self?

physicsBand(self: ?) → any

What the sea's physics band carries: the waves `Physics.water`, `sampleHeight` and the physics step read, which are drawn exactly as the CPU evaluates them. The surface drawn adds the cascades' waves shorter than the band, so the drawn height differs from the height read by `residualRms` (metres, the RMS of the waves left out, from the spectrum), and nine points in ten of the drawn surface stand within twice it (`measureAgreement`'s `p90`). Where a crest folds over, the drawn sheet overhangs the point read and the two part by up to the crest's height: a few points in thousands on a whitecapped sea.

argtypedescription
self?

examples

local band = ocean:physicsBand(); print(band.residualRms)

probeAt(self: any, data: { number }, x: number, z: number) → void

The device's probe grid at a world XZ point, bilinear, from a snapshot `readDrawnSurface` took: the cascades summed at full resolution, tiling over the largest cascade's sampling tile.

argtypedescription
selfany
data{ number }
xnumber
znumber

cell(cx: number, cz: number) → void

argtypedescription
cxnumber
cznumber

lerp(a: number, b: number, t: number) → number

argtypedescription
anumber
bnumber
tnumber

_swellAt(self: ?, x: number, z: number, t: number) → void

The swell's displacement at a rest point at wave time `t`, exactly as the displace pass evaluates it.

argtypedescription
self?
xnumber
znumber
tnumber

readDrawnSurface(self: ?) → any

Read the surface the device drew back once: the cascades summed on a 64 x 64 grid over the largest cascade's tile, as the sea's next step draws it, at that step's moment. Yields until the read lands, so call it from a task. (displacement X, Y, Z, folding), `moment` the water-clock moment drawn, `waveTime` the sea's own time then.

argtypedescription
self?

examples

local drawn = ocean:readDrawnSurface()

drawnHeight(self: ?, drawn: any, x: number, z: number) → number

The height the device drew at a world XZ point, from a snapshot `readDrawnSurface` took: the cascades on its grid and the swell, shoaled by the ground, with the choppiness undone by three fixed-point passes.

argtypedescription
self?
drawnanyA snapshot from `readDrawnSurface`.
xnumberWorld X.
znumberWorld Z.

examples

local y = ocean:drawnHeight(ocean:readDrawnSurface(), 10, -4)

measureAgreement(self: ?) → any

How closely the surface the device draws matches the one physics reads (`Physics.water`, `sampleHeight`): the drawn surface is read back once (`readDrawnSurface`), and at each of its 4096 grid points the height drawn is compared with the body's height at the point and moment it was drawn at. Yields until the read lands. the differences in metres (`p50`, `p90` and `p99` the sizes half, nine in ten and 99 in 100 of the points stand within, which a few folded crests leave where they are while they move `rms` and `max`), how many points were compared, the moment, and the RMS the physics band states for the waves it leaves out (`physicsBand`).

argtypedescription
self?

examples

local agreement = ocean:measureAgreement(); print(agreement.rms, agreement.residualRms)

within(share: number) → number

argtypedescription
sharenumber

sampleDisplacement(self: ?, x: number, z: number) →

The full displacement of the water surface at a world XZ position: the sea's physics band (`physicsBand`) as `Physics.water` reads this sea at the water clock's now. surface standing over this position from its rest, and the height of the surface there.

argtypedescription
self?
xnumberWorld X.
znumberWorld Z.

examples

local d = ocean:sampleDisplacement(hull.x, hull.z)

sampleHeight(self: ?, x: number, z: number) → number

The height of the water surface at a world XZ position: the sea's physics band as `Physics.water` reads it, the surface a body floats on.

argtypedescription
self?
xnumberWorld X.
znumberWorld Z.

examples

boat.position = { x, ocean:sampleHeight(x, z), z }

configure(self: ?, options: any) → void

Change the sea. Any field of the configuration may be passed; anything omitted is left alone. Naming a preset re-applies that whole sea, with fields passed alongside it still winning.

argtypedescription
self?
optionsanyFields to change.

examples

ocean:configure { preset = "gale", waves = { windDirection = 1.2 } }

getConfig(self: ?) → any

The sea state this ocean is running, as a table.

argtypedescription
self?

examples

local wind = ocean:getConfig().waves.windSpeed

getEntity(self: ?) → any

The entity the surface renders on.

argtypedescription
self?

examples

local e = ocean:getEntity()

release(self: ?, what: string, free: () → void

One step of a teardown, held to the step it is. A release that runs into something says so in the log and the teardown carries on, so a single resource the engine will not take back costs its own line rather than the rest of the sea.

argtypedescription
self?
whatstring
free(

_textureKeys(self: ?) → void

Every compute texture key this ocean holds a map under. A compute texture comes into being on the first `copyBufferToTexture` into its key and is owned by that key rather than by a handle, so the release is by name, and these names are the ocean's own, composed from its prefix. One list answers both what the sea allocated and what its teardown hands back, so the two cannot drift apart. It is the NAMES that answer, not the cascade count: `configure` re-resolves the cascades from the tier it is handed, so a sea that came up at three and was turned down to one is still holding the maps the other two wrote. Every key here carries this sea's own prefix, and handing back one nothing is filed under costs a name.

argtypedescription
self?

destroy(self: ?) → void

Tear the ocean down: the mesh, every GPU buffer and compute texture it owns, and the entity if this ocean spawned one. An ocean attached to an entity the caller supplied leaves that entity in place. The ocean stops simulating and leaves the registry first, so the teardown completes whether or not the entity it rendered on is still there, and a second call is a no-op.

argtypedescription
self?

examples

ocean:destroy()

attach(target: any, options: any?) → any

Bring up an ocean on an entity: the wave simulation, the clipmap surface that renders it, the material bound to the simulation, and the readback gameplay queries. One entity carries one sea, so an entity already carrying one has that sea torn down as this one takes its place; the entity itself stays, whichever sea spawned it. preset. Every block of the configuration may be overridden field by field. `getConfig`, `getEntity` and `destroy`.

argtypedescription
targetanyThe entity to render the surface on, or nil to spawn one.
optionsany?`{ preset, quality, seaLevel, followCamera, ... }` layered over the

examples

local ocean = Ocean.attach(nil, { preset = "gale", quality = "high" })

create(options: any?) → any

Spawn an entity carrying the `Ocean` component, which brings the sea up. The component owns the surface, so the sea survives a scene reload: the simulation and its GPU mesh are rebuilt from the component's own settings. `Ocean.forEntity(e.id)`.

argtypedescription
optionsany?Sea state and surface settings.

examples

local e = Ocean.create({ preset = "gale" })

forEntity(entityId: string) → any

The ocean rendering on an entity.

argtypedescription
entityIdstringThe entity's id.

examples

local ocean = Ocean.forEntity(e.id)

list( ) →

Every live ocean.

examples

for _, o in ipairs(Ocean.list()) do o:destroy() end

clear( ) → void

Tear down every live ocean.

examples

Ocean.clear()

xz(p: any) →

The named sea states this package ships.

argtypedescription
pany

examples

for _, name in ipairs(Ocean.presets()) do print(name) end

stampFoam(a: any, b: any, c: any, d: any, e: number?, f: number?) → void

Leave foam on every sea under a stroke: a capsule from one point to another, `radius` metres wide either side, `amount` 0..1 of a full crust. The foam rides its own layer of the persistent foam field, fading over each sea's `wakeSeconds` (14 s unless the sea names its own) and fraying as it ages, so a hull calling this every frame from last frame's stern to this frame's draws a wake that trails behind it. Local to this peer: every peer stamps from its own copy of the hull's replicated transform. Takes points as `{ x, y, z }`, `{ x =, z = }` or vectors, or the six numbers `(x0, z0, x1, z1, radius, amount)`.

argtypedescription
aany
bany
cany
dany
enumber?
fnumber?

examples

Ocean.stampFoam(lastStern, stern, 3.0, 0.6)

stampFoamAt(x: number, z: number, radius: number?, amount: number?) → void

The single-point form of `stampFoam`: a disc of foam.

argtypedescription
xnumber
znumber
radiusnumber?
amountnumber?

examples

Ocean.stampFoamAt(10, -4, 2.5, 0.8)

stampFoam(_self: ?, a: any, b: any, c: any, d: any, e: number?, f: number?) → void

`Ocean.stampFoam` on a handle (every sea under the stroke takes it).

argtypedescription
_self?
aany
bany
cany
dany
enumber?
fnumber?

setLook(self: ?, params: any?) → void

Draw this sea in a Tidewater look: a table of `look_*` shader parameters (`Looks.params(name)`); nil returns it to realistic. The simulation is untouched; only the surface shader's stylisation changes.

argtypedescription
self?
paramsany?

examples

ocean:setLook(require("~.modules.looks").params("cartoon"))

_pushLook(self: ?) → void

argtypedescription
self?

_crestHeight(self: ?) → number

The swell's typical crest height above still water, metres: 1.4 x the RMS of the sea's own physics surface over a few hundred metres, measured once per configuration. What the shader's crest glow and trough shade scale by.

argtypedescription
self?

instances( ) → void

Every sea standing now, in creation order (the kind and tests read it).

presets( ) → void

qualities( ) →

The quality tiers this package ships.

examples

for _, name in ipairs(Ocean.qualities()) do print(name) end

oceanWaterKernel( ) → string

run(binding: string, access: string) → any

argtypedescription
bindingstring
accessstring

seas( ) → void

The seas standing now, in the order they were made.

version( ) → void

A sea moves every frame, so what it is now names its time.

stand(request: any) → void

argtypedescription
requestany

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

Showing up to 3 levels deep. Open a part to see what it holds further down.

75+items
❒
package · born here
❒asset
# Tidewater: water for Zero games Oceans, lakes, ponds, swimming pools, rivers, streams, waterfalls, puddles and wet streets, shorelines and the view under the surface, plus the little water effects that make it feel real. Every kind of water comes in **seven looks** (realistic, crystal clear tropical, cartoon, painted ink, low-poly retro, pixel art and toy plastic), and they all work the same way, so a lake becomes a cartoon lake, or a pond becomes a river, by changing **one setting**. The Zero engine ships no ocean of its own: Tidewater is the water, and the engine floats things on every kind of it natively (`FluidForces` on any water `Physics.defineWater` declares; Tidewater declares them all). ## An ocean in your world in five minutes 1. **Install Tidewater.** In the editor's ZeroMind panel search for "Tidewater water kit" and press Install, or in the agent shell run `zero zeromind installAsset 59484771-e730-4d73-ab7b-6afb09ab129e` (that is Tidewater's guid). The splash and ripple effects (`tidewaterFx`) come with it, and so do the material packages its ready-made scenes use (`groundMaterials`, `woodsMaterials`, `stoneMaterials`, `organicMaterials`, `materialLibraryKit`): in an empty world the install takes about two minutes (about 18,000 files). 2. **Add the sea.** A brand-new world has no scene yet: make one first (in the agent shell, `zero scene create sea flat --opts '{"startup":true}'`). The flat template's ground sits at height 0, right on the waterline, so the sea's shore foam washes over it. The ground is made by the scene's `build.luau`: delete its `ground` lines there, or lower its `localPosition`, for open sea. Then, in the editor, select any entity (or make an empty one at height 0), press *Add component* and pick **WaterBody**. Set `kind` to `ocean` and `preset` to `tropicalLagoon`. The sea appears out to the horizon at once. (From the agent shell, use the code below instead: there is no shell command for *Add component*.) 3. **Float something.** A box with a dynamic body (`Physics` with `kind = "dynamic"`) and a collider (`BoxCollider`), plus the **Buoyancy** component (`tidewater.components.Buoyancy`, `density = 0.5` floats it half under). Press Play: it rides the waves, and it splashes when you drop it in. Add the **Wake** component and it leaves a foam trail as it moves (from about 1.5 m/s; `width` sets the trail width). 4. **Change the look.** Set the WaterBody's `look` to `cartoon`, `crystal`, `painted`, `lowpoly`, `pixel` or `toy`. Change `kind` to `lake` and give it a `size` for a lake instead: the entity's height is the lake's surface, and its sculpted bed is drawn, not solid, so add a collider under it if players or boats can reach the bottom (the dock guide's `lakeFloor`). The same in code. A scene made with `zero scene create` builds itself in its `build.luau`, inside `function content()`; put these lines there (`entity.spawn` in a build is saved with the scene): ```lua -- in your scene's build.luau, inside content() local sea = entity.spawn("Sea") sea.component.add("tidewater.components.WaterBody", { kind = "ocean", preset = "tropicalLagoon" }) local lake = entity.spawn("Lake", { position = { 120, 4, 0 } }) lake.component.add("tidewater.components.WaterBody", { kind = "lake", look = "realistic", preset = "alpineClear", size = { x = 60, y = 40 }, depth = 6 }) -- later: lake.component.get("tidewater.components.WaterBody").look = "cartoon" -- or: lake.component.get("tidewater.components.WaterBody").kind = "pond" -- a boat on the lake: a dynamic body, a collider, Buoyancy and a Wake local boat = entity.spawn("Boat", { position = { 120, 4.5, 0 } }) boat.component.add("Physics", { kind = "dynamic", mass = 160, angularDamping = 0.5 }) boat.component.add("BoxCollider", { half = { 0.7, 0.3, 1.7 } }) boat.component.add("tidewater.components.Buoyancy", { density = 0.4 }) boat.component.add("Wake", { width = 1.4, length = 3.4 }) ``` From a script that runs in play (not a build), use `entity.spawnSynced` instead, so every player gets the same water and boat. ## What you get | Kind | What it is | Presets | |---|---|---| | `ocean` | The spectral FFT sea out to the horizon: calm glass to a gale, foam where waves break and along the shore, a seabed seen through it, shoaling turquoise over a reef. Can also be a bounded tile (`extent`). | calmClear, darkChop, darkRolling, heavySwell, whitecapped, murkyGrey, paleSwell, glassyDark, gale, tropicalLagoon, northernGale, harbourCalm, moonlitSwell | | `lake` | A still sheet in any outline over a sculpted bed: clear turquoise shallows to dark deep water, sky, sun and surroundings reflected, the bed and its caustics seen through it, shore foam. | alpineClear, tropicalLagoon, murkyPond, glacierMilky, darkPeat, nightStill | | `pond` | The small, murkier lake. | lilyPond, murkyPond, greenAlgae, koiPond, swampy, clearSpring | | `pool` | A tiled swimming pool with coping, deck, strong caustics and optional underwater lights. | outdoorPool, backyardPool, indoorPool, nightPoolLit | | `river` | A ribbon along a `path` that visibly flows downhill, faster where steeper, white water through rapids; its current carries what floats. | forestRiver, mountainRapids, lazyLowland, muddyFlood, glacialMeltwater, canal | | `stream` | The narrow, shallow, clear river with pebbles and riffles. | brook, mossyCreek, alpineRill | | `waterfall` | A sheet falling from a lip, tearing into streaks, into a churning plunge pool with mist, spray and drips. | tropicalCascade, grottoVeil, alpineRibbon, wideCurtain, trickle | | `puddles` | Puddles that form only in the low spots of a street while it is wet, mirror-like, ringing in the rain, drying away after. | cityStreet, muddyTrack, cobblestone | | `shoreline` | Water meeting a long, gentle beach, a slow swell lapping up the slope and a wide band of surf wash along the waterline. | sandyBeach, pebbleCove, rockyShore | | `hotspring` | A small mineral basin of milky warm water with steam rising off it. | milkyBlue, emeraldSpring, mineralTerrace | | `underwater` | A deep basin made to be swum in: strong underwater fog, caustics on the floor, light shafts and bubbles rising from the bed. | kelpCove, deepBlue, murkyHarbour | Eleven kinds, seven looks: **77 combinations**, shown side by side in the `gallery` scene. **Looks:** `realistic`, `crystal` (tropical crystal clear: low absorption, turquoise shallows, the bed sharp through it), `cartoon`, `painted` (ink linework over a colour wash), `lowpoly` (flat-lit facets, retro), `pixel` and `toy` (glossy moulded plastic for toy-style games: two candy bands, a hard glossy highlight; also `plastic`, `toybox`, `bathtub`). The environment kits' names are accepted too (`real`, `tropical`, `clear`, `toon`, `painterly`, `retro` and friends). **Underwater**, for every kind: murky fog coloured by the water, moving caustic light on the floor, light shafts, the surface rippling overhead, and a waterline split when the camera straddles it. **Effects** come from **Tidewater FX** (`tidewaterFx`), its own package that installs with Tidewater and works without it: 15 effects, each in the seven looks. Tidewater's `Water.splash` / `Water.ripple` and the `Wake` and `Splashes` components reach it, and other kits can ask it for a ripple or splash with no dependency at all (see its README). | One-shot | | Continuous (runs until stopped) | | |---|---|---|---| | `plop` | a pebble or thrown stone | `bow` | bow spray off a moving boat | | `body` | a person or crate jumping in | `spindrift` | spray blown off breaking waves | | `droplets` | a body climbing out, shaking off | `mist` | mist and spray rising off a waterfall or hot spring | | `spray` | a burst of spray in the wind | `drips` | drips falling from eaves, a lip, a hull | | `footstep` | a foot landing in a puddle or the shallows | `bubbles` | bubbles rising under water | | `fishJump` | a fish leaving the water and falling back in | `wake` | the foam trail behind a boat or swimmer | | `rainSplash` | one heavy raindrop: tiny crown and ring | `foam` | a drifting patch of foam in an eddy or under a fall | **Splashes happen by themselves.** From the moment any Tidewater water exists, anything that falls into it splashes, sized to what it is: a pebble plops, a person makes a big splash, something climbing out drips. Each splash is played by the owner of the body and synced, so every player sees it once. `Water.autoSplash(false)` turns it off for a game that plays its own. ## Floating, flow and asking the water Every kind declares itself to the engine's water physics (`Physics.defineWater`), so the engine's `FluidForces` and Tidewater's `Buoyancy` component float anything on any water, a river's current carries it downstream, and `Physics.onWater` hears it splash in. ```lua local Water = require("tidewater.modules.water") Water.heightAt(x, z) -- the TOPMOST water's surface height there, or nil Water.heightAt(x, z, y) -- the water at height y instead (a lower one of stacked waters) Water.flowAt(x, z) -- { x, y, z } m/s: the river's current, the waves' motion Water.normalAt(x, z) -- unit { x, y, z } the surface faces (tilted on a wave's face) Water.surfaceAt(x, z) -- Surface? { height, flow, normal, depth?, water? } in one typed answer Water.tideAt(x, z) -- TideState? { offset, rising, high, low }, nil where that water has no tide Water.sample({ x, y, z }) -- the engine's whole answer: surface, depth, normal, velocity, floor, body lake:heightAt(x, z) -- this lake's own surface there, nil off it (never another water) lake:surfaceAt(x, z) -- also lake:flowAt, lake:normalAt, lake:tideNow() e.component.get("tidewater.components.WaterBody"):heightAt(x, z) -- and :flowAt, for water saved with the scene crate.component.add("tidewater.components.Buoyancy", { density = 0.45 }) -- floats 45% under, rides the waves boat.component.add("Wake", {}) -- foam trail, bow spray, ripples ``` The module exports the types `Surface`, `TideState` and `Handle` (`Water.Surface` and friends in strict code), and every `nearY` argument (the optional third one) picks between stacked waters the way `heightAt`'s does. `normalAt`, `surfaceAt` and `tideAt` were added in this round; `heightAt` and `flowAt` are unchanged. Where waters overlap from above (a lake out over the sea, a pool on a ship's deck), `heightAt` and `flowAt` with no height answer the top one, and a body asked about itself answers only for itself: checked with a lake at height 10 over the showcase sea, `Water.heightAt` gives 10 over the lake and the sea's height beside it, `heightAt(x, z, 0)` gives the sea under the lake, the lake's own `heightAt` gives 10 over it and nil off it, and the sea's own gives the sea's height. Measured: a 400 kg, 1 m box on the `tropicalLagoon` sea stays within 4 cm of the surface with `Buoyancy` (6 cm with the engine's plain `FluidForces`); on a lake it settles 40% submerged, as its density says. On rough seas `Buoyancy` holds a body to the water by itself: the rougher the water under the hull moves, the harder it couples the hull to it (still water and gentle seas keep the `damping` you set exactly). Measured over 60 s with a 1 m box at density 0.5: in a `gale` its centre stays on average 0.15 to 0.45 m under the local surface and dips at worst 0.8 to 2 m in the steepest troughs (before: 3 to 5 m); in a `northernGale` 0.16 to 0.29 m on average, 0.8 to 1.25 m at worst. ## Puddles that follow the weather Puddles fill in about ten seconds as the ground gets wet and dry away over `dryTime` (90 s by default) after the rain stops, even when a weather kit leaves its wetness at 1. A dry street declares no water and draws nothing. Pictures of the same street wet and dry are in `documentation/media/` (`puddles_wet.jpg`, `puddles_dried.jpg`). ## Tide An `ocean`, `shoreline` or `lake` can rise and fall like a tide. Two `WaterBody` fields: `tide`, the range in metres from low water to high water (0 = none, the default), and `tidePeriod`, the seconds from one high water to the next (600 = ten minutes, the default). ```lua sea.component.add("tidewater.components.WaterBody", { kind = "ocean", preset = "harbourCalm", tide = 2, tidePeriod = 900 }) local t = Water.tideAt(x, z) -- { offset = metres above mean, rising, high, low }, nil without a tide local t2 = handle:tideNow() -- the same for one water you made with Water.create / Water.attach ``` `Water.create` and `Water.attach` take `tide` as a number (the range, 600 s period) or a table `{ range, period, phase }`. The tide follows the session's shared water clock (`Physics.waterTime()`), so every player sees the same water at the same height and a late joiner sees it where everyone else does; nothing is sent over the network. On the ocean the drawn sea, the shoaling against the `ground`, the underwater pass and the physics water all follow it; on a lake or shoreline the surface and its physics move while the bed and banks stay put. The water follows in 2 cm steps, so a slow tide re-declares its physics only every few seconds, and a water with no tide pays nothing. The maths alone is `require("tidewater.modules.tide")` (`Tide.spec(value)`, `Tide.at(spec, time?)`). ## Named varieties Every kind has named varieties (`preset`); `Water.presets(kind)` lists them, default first, and the kinds table above names them all. Plain words resolve too, matched without case, spaces, dashes or underscores, the way a person asks for one: | Kind | Plain words | |---|---| | ocean | glassy, calm, stormy / storm, rough, choppy, swell, grey, harbour / harbor | | river | lazy, slow, rapids, whitewater, flood, meltwater | | pool | backyard, garden, indoor, olympic, night, outdoor | | waterfall | curtain, wide, ribbon, thin, veil, cascade, trickle | | lake | alpine, clear, lagoon, murky, glacier, peat, night | | pond | lily, koi, swamp, algae, spring | | hotspring | onsen, milky, emerald, terrace | | stream | creek, rill | | puddles | city, mud, cobbles | | shoreline | beach, sand, pebbles, rocks, rocky | | underwater | kelp, deep, harbour | `backyardPool` (an 8 x 4 m garden pool, 0.9 to 1.6 m deep, wooden deck) is new in this round. A name a kind does not have falls back to its default with a warning naming the real ones. ## Rain and other kits Tidewater rings its water in the rain from any weather kit that writes the named values `weather.rain`, `weather.wetness` and `weather.wind` on an entity. **Cloudburst** does, so its raindrops ring your lakes and puddles with no wiring and no dependency either way. Without a weather kit: `Water.setWeather({ rain = 0.6 })`. Any kit can make rings and splashes: `Water.ripple(pos, strength)`, `Water.splash("plop", pos)`. ## Multiplayer `WaterBody` fields replicate and every peer builds the same water from them; waves run on the engine's shared water clock, so two players see the same swell. A floating boat is a synced body (its owner simulates it, others see it where it is) and its wake is drawn on every peer from its motion. Effects take `{ sync = true }`; automatic splashes are played by the owner and synced, never doubled. Checked live with two players in the showcase (2026-11-15, two clients in one play session, readings taken at the same instants on the shared water clock): - **Same waves:** the sea at a fixed point agreed within 0.7 to 2.4 cm. - **Same boat height:** the rowboat's hull, owner against second player, at matched moments: -0.055 / -0.019 to -0.048 m, +0.099 / +0.100 m, +0.171 / +0.177 m, +0.106 / +0.134 m (0 to 4 cm apart; the second player draws the boat the usual 0.1 to 0.5 s behind). - **Two players, checked live:** a synced splash thrown on either client was received on the other, and the second player's client draws the wake (5 foam segments in 18 s while the owner rowed, after the fix; 0 before). - **Checked again on 2026-11-16, twice, the second time after both players left play and came back in** (the user's editor and a second client, one play session, the showcase rowboat rowed out from its berth with W by the first player). Every frame both clients recorded the boat's position against the shared water clock; the second player's track was then matched to the owner's at the network delay that fits best (about 0.25 s): - Run 1: 8 m rowed, 90 matched samples: heights 3.4 cm apart on average (horizontal 1.8 cm). - Run 2, after the reload: 30 m rowed, 533 matched samples: heights 4.3 cm apart on average (horizontal 3.4 cm). The largest single gaps (31 to 34 cm) come from sampling a 0.4 m swell at 3 to 6 frames a second on a busy machine, not from the boat being elsewhere. - Wake on the second player: its client laid 35 wake foam segments of its own while the owner rowed (run 2), and the wake shows in its view (`documentation/media/r11_second_player_wake_run2.jpg`). - Splashes and ripples: a synced splash and a ripple ring thrown on either client arrived on the other in both runs (run 2: 4 of 4 from the second player to the owner, 8 from the owner to the second player). One single splash in run 2 arrived late, after more than 3 s, while the owner's client was busy sending its own stream of automatic splashes. - Three bugs this found are fixed: an idle boat nobody owned was simulated by no one and froze on the waves (vehiclesKit now keeps an idle boat owned, sent upstream), the `Wake` loop stopped on every player but the boat's owner (a refused status write ended it), and the wake's foam waited behind 80 or more queued splashes on a player who had just joined, so it laid none (it is now built on the spot, at most once a second per boat, until the pool is ready). ## Ready-made scenes `tidewater.scenes.*`: `tropicalLagoon`, `northernGale`, `mountainLakeDawn`, `forestRiver`, `rainyStreet`, `waterfallGrotto`, and `gallery` (all 77 kinds and looks, labelled, with walkways; `Gallery.setTime("dawn" | "day" | "dusk" | "night")` relights it). ## Cost Measured with the kit's own bench (`tidewater.modules.costBench`, also the pause menu's "Measure water cost on this device"). It builds each kind at an empty spot far from the scene, looks at it through its own camera, and takes the median of rounds of water off against water on. Each run is saved in `documentation/costs/`. A delta smaller than about 2 ms is lost in the frame's own noise and reads as "about 0". | Water | Desktop, native (frame / GPU) | Browser, desktop Chrome (frame / GPU) | Android tablet | |---|---|---|---| | Ocean (default quality) | +22.9 ms (second run +25.2) / +5.3 ms | +20.21 ms / +2.37 ms | not measured | | Lake | about 0 / +1.2 ms | +1.93 ms | not measured | | Swimming pool | about 0 | +1.94 ms | not measured | | River | about 0 | +0.62 ms | not measured | | Underwater pass | +3.8 ms (second run +8.8) | +5.13 ms | not measured | | Puddles | about 0 | GPU +7.46 ms | not measured | | Waterfall | +6.5 ms | about 0 | not measured | | Hot spring | +3.6 ms | about 0 | not measured | | Pond | about 0 / +0.3 ms | about 0 | not measured | | Shoreline, stream | about 0 | about 0 | not measured | - **Desktop, native**: Linux, 1920 x 1080, dev build, runs of 2026-11-15 22:40 and 23:34 UTC, on a machine running two or three engine clients at once (a frame was already 30 to 90 ms before any water). - **Browser**: desktop Chrome, measured by the world's owner with the same bench (60 frames, 2 rounds); the bare frame was 48.52 ms with 20.42 ms of GPU. - **Android tablet: not measured on a device yet.** A tablet is attached to the machine this kit is built on, but another project was using it, and from inside the editor there is no way to reach an attached device at all: engine #25931. So the column stays empty rather than guessed. Open the world on the tablet, press Escape and choose "Measure water cost on this device"; the run saves itself beside the others in `documentation/costs/` and fills this column. A desktop stand-in was tried (the whole bench under the engine's `low` quality tier, the defaults a 4 GB tablet draws with: `Bench.run({ tier = "low" })`, runs of 2026-11-16 in `documentation/costs/`), but on a desktop shared by two engine clients the bare frame swung from 100 to 200 ms between rounds, so its per-kind deltas are noise and are not quoted here. What carries over to a tablet is the shape: the ocean is the one kind with real fixed work (its FFT and surface passes), and since this version that work stops entirely whenever nothing moves; puddles and the underwater pass are full-screen GPU work that scales with the tablet's lower render resolution; every other kind is one transparent surface. For a phone or tablet pick lakes, ponds, pools, rivers, streams and shorelines freely, keep one ocean at `quality = "low"`, and use puddles and underwater where they matter. **1.2.0 runs, twice at each tier** (native desktop, Linux, 2026-11-21 19:15 UTC, 120 frames a side, 3 rounds; the bare frame was already 20 to 22 ms because the editor, the owner's client and a sub-client shared one GPU, and this machine gave no GPU timestamps that day, so these are frame-time deltas only): | Water | High tier, run 1 / run 2 | Low tier (the tablet defaults), run 1 / run 2 | |---|---|---| | Ocean | +7.9 / +1.0 ms | +8.0 / +3.2 ms | | Underwater pass | +5.9 / about 0 | +2.9 / about 0 | | River | +5.0 / about 0 | +0.9 / about 0 | | Puddles | +3.1 / about 0 | about 0 / about 0 | | Stream | +2.6 / +1.2 ms | +3.4 / +0.9 ms | | Lake, pond, pool, shoreline, hot spring, waterfall | under 2.5 ms in every run, mostly about 0 | under 3.2 ms in every run, mostly about 0 | The ocean is again the one kind whose cost shows in both runs; everything else moves between "about 0" and a couple of milliseconds from one run to the next, which is this machine's noise. The tablet column above still needs a device: no phone or tablet was connected to this editor during the 1.2.0 work, so the tablet costs, the browser-on-tablet costs and the ten-minute battery-saver run on a tablet were not measured. The bench and the pause-menu entry are there to take them on the device. **Battery saver.** With the Graphics Presets kit installed, its Battery Saver and Low steps put every `auto` water on the low tier by themselves (`Water.setQuality("batterySaver")` does the same without the kit); a still lake or pond costs a single transparent surface, and a sea that nothing moves skips its whole step. Most of the ocean's frame time is its CPU side (the clipmap and the wave spectrum's bookkeeping), which is why it costs far more frame time than GPU time. **A still sea costs nothing (1.1.9).** In a paused editor, or in any frame where neither the water clock nor the camera moved, the ocean now skips its whole step: measured on the main scene with the editor paused, 175 skipped steps in 3 s and not one GPU dispatch. When only the camera moves it re-places the surface from the waves it already has, without re-running the wave simulation. The ocean also no longer copies the lit scene into textures of its own every frame (it reads the engine's `zero::scene_color` / `zero::scene_depth`) and no longer re-mirrors its surface mesh every frame. The table above predates these savings; they were carried over from the engine's old built-in `oceans` package (see Where the sea came from). **The showcase, measured** (native desktop, 1920 x 1080, 2026-11-16 about 01:15 UTC, a busy machine with two engine clients): - In the editor with the showcase open: median 49.8 ms a frame, 95th percentile 58.6 ms, 99th 80.1 ms. Under 100 ms throughout. - Playing it (on the pier, after it finished loading): median 40.6 to 47.6 ms, but 95th percentile 144 ms and 99th 296 ms. The GPU's timed work in play was about 79 ms a frame at the median, mostly an engine compute group (29 ms), the transparent pass (21 ms, where water surfaces and particles draw) and the engine's weather surface pass (12 ms); Tidewater's own ocean passes were each under 1 ms. A player on a busy machine sees those spikes, as the world's owner did (155 to 210 ms a frame). ## Where the sea came from The Zero engine no longer ships an ocean of its own: Tidewater is the water, and its components are `tidewater.components.WaterBody`, `tidewater.components.Ocean` and `tidewater.components.Buoyancy`. Tidewater's spectral sea started as a port of the engine's old built-in `oceans` package (the spectral sea, its foam, its seabed, things floating on it, its nine sea presets and its tests) and keeps all of it. A world written for the old package moves over by installing Tidewater and changing its require (rebuild the scene after, so a sea it already made is made again): ```lua local Ocean = require("tidewater.modules.ocean") ``` or, better, by replacing that sea with a `WaterBody` of `kind = "ocean"` (its `preset` takes the same sea states), which adds the seven looks, the tide, the shared underwater view and the light fix. **History: the same sea, on screen and in cost.** While the old package still shipped, both were measured side by side. A sea attached through `Ocean.attach` or the `Ocean` component with no `tidewater` option was drawn exactly as the built-in package drew it, and cost what it cost: Tidewater carries the built-in package's two last savings. A sea nothing moves costs nothing (the waves are evolved only when the moment drawn changes, the surface is re-placed only when the viewer moves, a frame on which neither happened dispatches no GPU work at all, and a paused editor's sea holds still), and the surface reads the scene behind it straight from the engine's own `zero::scene_color` and `zero::scene_depth` instead of copying the lit scene into textures of its own every frame. Tidewater adds one saving of its own on top: the surface mesh is no longer re-mirrored from the GPU every frame. Add `tidewater = true` to `Ocean.attach` (or use `WaterBody` with `kind = "ocean"`, which always has it) for Tidewater's light fix: lit by the real sky, no teal glow at dusk, dark with a moon path at night, glowing crests. The waves were the same: with the same preset, `Physics.water` heights matched the built-in sea exactly (a `gale` at high quality: RMS 13.38 m, 1% of points under -31.2 m, 1% over 28.6 m, on both). The two packages also ran side by side in one world, each sea alive and moving: Tidewater names its bodies of water, GPU resources and surface markers `twocean<N>_...`, where the built-in package used `ocean<N>_...` (`documentation/media/compare_builtin_vs_tidewater_*.jpg`: built-in on the left, a Tidewater tile on the right, at day, sunset and night). Everything else new (looks, bounded seas, wake foam, foam against piers, the moon path, tides) is opt-in. ## What's new in 1.1.13 - **Water effects cost nothing while parked or warming** (tidewaterFx 1.0.10): the splash and mist loops a water body primes and parks far below the world (y -5000) used to keep simulating every frame; they are now paused until used, and the first real splash still shows at once. ## What's new in 1.1.12 - **Clearer river docs** (issue #11): the how-to guide's river section says where the water lies (its own bed, the component's `ground` field, or a channel of your own with `options = '{"bed":false}'`), that `bed`, `groundOffset` and the bank and rapids settings go in `options`, and that `path` is a string (with a sample that joins a Luau table). The `path` and `ground` field descriptions say the same. Contributed through lanternStair PR #6. - Built on the current engine library (33551d3). ## Guides inside - *How to add water to my game*: every kind, looks, varieties, floating, tides, queries, performance. - *How to add an ocean with waves breaking on the shore*, *How to add a lake or pond*, *How to add a river that carries things downstream*, *How to add a waterfall with spray and mist*, *How to add a swimming pool or hot spring*, *How to add puddles that fill when it rains*, *How to add a tide that comes in and goes out*: one kind or feature each, with copy-paste code. - *How to make a boat float*: vehiclesKit boats on Tidewater, and your own hull with `Buoyancy`. - *How to change the look of water*: the seven looks and every named variety. - *How to make water run well on phones and tablets*: the quality field, `Water.setQuality`, battery. - *Example: build a small harbour level*: a harbour sea with a tide, a pier, boats, floating crates and buoys, a river over a waterfall, swimming and rain. - *Example: a fishing dock on a lake with a boat*: from an empty world to a lake you can row on. - *Oceans*: the sea in depth, covering sea states, what each control does, the seabed, buoyancy, cost. - Swimming is the **tidewaterSwim** package's guide, *How to let the player swim*. ## Credits Tidewater's sea is built on the Zero engine's former built-in **`oceans`** package (`@builtin::systems.oceans`, by the Zero engine team, which the engine no longer ships): its spectral wave simulation, cascades and Gerstner swell, Jacobian foam, Beer-Lambert water colour, procedural seabed and caustics, buoyancy, sea presets and test suites are that package's work, carried here as the starting point and extended. Its later savings are carried over too, with thanks to the same team: "a sea nothing moves costs nothing" (evolve only when the moment changes, re-place only when the viewer moves, a paused editor's sea holds still) and reading the scene behind the water through the engine's own `zero::scene_color` and `zero::scene_depth` rather than a copy of its own. Thank you. ## The parts | Part | What it is | |---|---| | `components/WaterBody` | Any kind of water, saved with the scene: `kind`, `look`, `preset` and its shape | | `modules/water` | The one API: create / attach / setKind / setLook, presets, heightAt, flowAt, normalAt, surfaceAt, tideAt, sample, setQuality, ripple, splash, setWeather | | `modules/looks` | The seven looks as shader parameters | | `modules/tide` | The tide: a water's level rising and falling on the shared water clock | | `modules/kind_*` | One builder per kind (ocean, shoreline, lake, pond, pool, hotspring, river, stream, waterfall, puddles, underwater) | | `modules/fx`, `modules/ripples`, `modules/weatherLink` | One-line bridges to `tidewaterFx` (effects, the GPU ripple field, weather) | | `modules/underwater` | The view from below the surface, for every kind | | `components/Ocean`, `components/Buoyancy`, `modules/ocean*`, `modules/buoyancy` | The spectral sea and floating (started as a port of the engine's old built-in `oceans` package) | | `shaders/*`, `shaderModules/twCommon`, `computeShaders/*` | The water surfaces, the shared shading library, the GPU passes | | `scenes/*` | Ready-made scenes and the gallery | | `tests/*` | ocean, buoyancy, oceanLooks, underwater, surfaces, rivers | ## Known limits Honest list, as of this version. Where the cause is in the engine, the engine's issue number is given as **engine #NNNNN**; those are the numbers to look up and follow. Where this world's own issue tracker also follows it, its number is given as *(world tracker #N)*. - **An effect played before the kit has readied it shows late: engine #26227.** A new effect play draws nothing until a long hidden warm-up through its whole graph finishes. Tidewater readies every effect in the background as soon as a water is built (`Fx.prime`): measured on a busy desktop, every one-shot was ready 0 to 8 s after the water was built and every continuous effect (mist, bubbles, drips, foam, spindrift, bow spray) 30 to 38 s after. From then on every effect draws within 0.05 s of being triggered, the first time and every time after (all 13 kinds measured, twice). An effect triggered in the first seconds after load, before that, waits for the engine's warm-up: on the same desktop more than 8 s. Call `Fx.prime(look)` at load, behind a loading screen if you can, for a look of your own. *(world tracker #1)* - **Stopping an endless effect does not hand it back for reuse: engine #26226.** Tidewater works around it: a stopped mist, drips, bubbles, foam, spindrift or bow spray is parked (its emission turned to zero) and the next one of its kind and look takes it over at once. *(world tracker #2)* - **After a shader edit, existing materials and pooled effects keep the old shader: engine #26228.** Rebuild the water (reload the scene, once it has finished loading) to see a change. - **Reloading a scene while it is still loading never returns: engine #26225.** Let a ready-made scene finish loading (the showcase takes up to a minute) before reloading it. - **The ocean's top quality foam is over a GPU size limit: engine #9336.** At `ultra` the foam texture is larger than some GPUs allow; `high` and below are not affected. - **Opening a scene with no edits makes a clean world look changed: engine #26351.** Opening a ready-made scene can write an empty record into it; `zm restore <scene>` takes it back. - **Publishing a one-file change in a world with many kits takes minutes and freezes the editor: engine #25764.** Expect this when you push a world that installs Tidewater beside other kits. - **A helper editor session doing scene work grows 2 to 3 GB in an hour: engine #26230.** On a long session with the showcase open, restart helper clients now and then. - **Effects only move in Play.** The engine runs effect timelines on the gameplay clock, so splashes, mist and spray stand still while editing; water surfaces, ripples and waves do animate in the editor. *(world tracker #3)* - **The install is large**: about 18,000 files and a minute, mostly material and prop libraries the ready-made scenes use. The water itself needs none of them. *(world tracker #4)* - **Ripple rings are drawn within 64 m of the camera**; a splash's own ring particles still show further out. *(world tracker #5)* - **Very shallow lagoon water over pale sand reads too bright at night**; the open sea goes dark with a moon path. *(world tracker #6)* - **The ocean's `ground` option** (shoaling against a terrain) can leave a lip of raised water on a very steep coast. Leave `ground` empty if you see one. *(world tracker #7)* - A faint green fleck can show on near wave crests with a very low sun, inherited from the old built-in sea it was ported from; the low-poly ocean has no moon glint at night. *(world tracker #8)* - **No longer applies: a scene running both seas could look milky.** While the engine still shipped its own sea, a camera low enough to dip under the built-in swell had that package's underwater fog wash the whole frame, Tidewater's sea included, to a pale teal (measured alone at noon from the same camera, the two seas matched). The engine ships no sea of its own now, so a world cannot run both. *(world tracker #9)* - **The Android tablet cost is not measured on a device yet: engine #25931.** A tablet is attached, but it was in use by another project, and the editor has no way to reach an attached device at all. Desktop and browser are measured, and the pause menu's bench fills the gap in one run on the tablet (see Cost). *(world tracker #10)* - **The gallery's small ocean tile reads flat** (a stepped cyan slab in its 20 m box at day and dusk), unlike the open sea, which reads as water in every light (`documentation/media/kinds/ r8_kinds_{day,dusk,night}_{1,2}.jpg`: every kind in the realistic look, checked twice at each time). A bounded ocean wants room: give it 100 m or more. - **At night the sea mirrors your scene's sky**, so a sky that stays lit after dark gives a pale, milky night sea. The engine's procedural sky still renders a light grey after midnight, and a day-night clock may hand over to a bright moon (worldClockKit's is 0.65, a sixth of noon). The showcase eases its sky exposure to 0.15 and its moon and ambient to 0.15 and 0.07 through twilight (its `entrypoint.luau`, `holdSky`), which takes the sea at 22:30 from a pale cyan (brightness 134 of 255) to a dark moonlit blue (69): `documentation/media/playtest/r8_sea_night_2.jpg` and `r8_sea_dusk_2.jpg`. Do the same in your own scene if its nights read milky. - **A scene rebuilt during play can drop a boat another player owns** on the client that rebuilt; leaving and re-entering play brings it back. - **Not every ready-made scene was re-checked by eye in this version.** The lagoon, the gale and the rainy street were rebuilt and looked at; the forest river, mountain lake and waterfall grotto load and run, but were not re-captured after their last changes.
▲ 1↑ born
◇
component · born here
❒asset
# Ocean Puts a live sea on an entity. The component's fields ARE the sea state (wind speed and direction, choppiness, swell, foam, extent and detail), and the wave simulation, the GPU surface mesh and the material bound to the simulation are all rebuilt from them whenever the component wakes. That rebuild is what makes the ocean persistable. The simulation lives entirely in GPU buffers and a runtime mesh, none of which survive an engine restart; the component's settings do, and the whole sea is reconstructed from them. A scene with an ocean in it reloads into the same sea. The surface follows the viewer and covers `extent` metres around them, so one ocean is the whole sea however far anyone sails. `sampleHeight(x, z)` and `sampleDisplacement(x, z)` report where the water is: the same waves that are drawn, which is what a boat, a buoy or a swimmer floats on. Start from a `preset` (`calmClear`, `darkChop`, `darkRolling`, `heavySwell`, `whitecapped`, `murkyGrey`, `paleSwell`, `glassyDark` and `gale`) and override whatever the scene needs. Wind speed does most of the work: significant wave height goes as its square.
▲ 0↑ born
·
computeshader · born here
❒asset
# ocean_foam_texture Grows the tiling greyscale pattern the three foam layers stamp on the water. It is generated rather than shipped as an image. A stored texture is a binary, content-addressed asset, and a material blocked on a texture reference that never resolves never prepares, which leaves its entire uniform block unwritten and the surface black, not merely un-foamed. Generating the pattern keeps foam on the same compute-texture path the cascade maps already use. Run once per layer at startup, each with its own seed. The noise tiles: every octave hashes its lattice modulo a period that divides the texture size.
▲ 0↑ born
▣
module · born here
❒asset
# oceanPresets Named sea states for the oceans package: `calmClear`, `darkChop`, `darkRolling`, `heavySwell`, `whitecapped`, `murkyGrey`, `paleSwell`, `glassyDark` and `gale`. Each name says what the water does, so a sea can be picked off the list without reading its values. A state is an `OceanConfig` fragment applied underneath whatever the caller passes to `Ocean.create`, so any single field can be overridden without giving up the rest. The states are laid out along the Beaufort scale, because wind speed is what determines wave height in a spectral ocean; the remaining fields shape character: how long the swell runs, how readily crests break, and what colour the water body is. `materialProperties` returns the appearance half of a preset, ready to apply to an ocean material.
▲ 0↑ born
·
computeshader · born here
❒asset
# ocean_displace Displaces the ocean surface mesh by one cascade, once per cascade per frame. The first cascade writes each vertex from the rest position stored in its UV and the rest accumulate onto it, so the mesh is rebuilt from a clean grid every frame instead of drifting. Cascades are sampled at the vertex's true world position: the mesh follows the camera, so its rest grid sits at a moving origin. The vertex normal accumulates each cascade's surface gradient (the ratio `n.xz / n.y`), which is how independent wave fields actually combine; per-fragment normal detail comes from the cascade normal maps in the surface shader, since the mesh is far too coarse near the horizon to carry it.
▲ 0↑ born
·
computeshader · born here
❒asset
# ocean_evolve Advances one cascade's static spectrum to the current time, `h(k,t) = h0(k) e^{iwt} + conj(h0(-k)) e^{-iwt}` at the deep-water dispersion `w = sqrt(g|k|)`, and emits the two complex fields the inverse FFT consumes. The frequency is quantised to a multiple of `2*pi / loop_period` so the whole sea state repeats seamlessly instead of drifting as elapsed time grows. Field A packs the height and X-displacement spectra into one complex field (`H + i Dx`), which the Hermitian symmetry of both lets a single inverse transform separate again: two FFTs per cascade instead of three.
▲ 0↑ born
▣
module · born here
❒asset
# oceanClipmap Builds the ocean's geometry: concentric rings that double in extent and halve in density outward, the stitch strips that remove the T-junctions between them, and the skirt that carries the water out to the horizon. Returns the vertex and index data as Luau buffers, ready to upload straight into the compute buffers `ocean_displace` rewrites each frame.
▲ 0↑ born
·
computeshader · born here
❒asset
# ocean_assemble Unpacks one cascade's two transformed fields into the `(dx, height, dz)` displacement field the surface mesh reads, applying the `(-1)^(x+z)` sign alternation that undoes the centred-on-zero wave-vector grid the spectrum was built on. Height and horizontal displacement carry independent gains, so crest pinching (`choppiness`) can be dialled without changing wave height.
▲ 0↑ born
✦
shader · born here
❒asset
# oceanSurface The water surface of the spectral ocean. Geometry arrives already displaced by `ocean_displace`, so this shader only decides what the surface looks like: the normal summed across cascades as gradients (which is what adds when wave fields overlap), a water column shaded by per-channel Beer-Lambert extinction over the distance to whatever lies behind it, Fresnel reflection from the scene's own reflection probes, subsurface scattering through backlit crests lit by the scene's directional light, a sharp sun-glitter lobe, and foam from the simulation's own breaking-wave mask plus a shoreline band. Opacity is the extinction rather than an authored constant, so colour and transparency stay consistent from a turquoise shallow to a near-black deep. Works from below as well as above.
▲ 0↑ born
·
computeshader · born here
❒asset
# ocean_normals Differentiates one cascade's displacement field into a shading normal and a foam mask. Normals come from central differences of the displaced positions (so crest pinching is accounted for, unlike a height-only gradient), with wrap-around neighbours because the cascade tiles. Foam comes from the smaller eigenvalue of the horizontal displacement Jacobian: where it goes negative the surface has folded over itself, which is what a breaking wave is, so whitecaps appear from the same displacement that raised the crest rather than from a painted-on noise threshold. Fresh foam replaces the stored value immediately while old foam fades at `foam_decay` per second, leaving streaks behind broken crests.
▲ 0↑ born
▣
module · born here
❒asset
# oceanQuality The four quality tiers: how finely the sea is resolved, as distinct from what sea it is. A tier owns the FFT grid per cascade, the clipmap's ring density, the swell band count, the whitecap field's resolution and whether screen-space reflections run. It never touches wind, spectrum shape or colour; those come from the preset, so the same named sea looks like itself on any machine.
▲ 0↑ born
·
computeshader · born here
❒asset
# ocean_probe Resamples every cascade onto one small grid that the CPU reads back, so gameplay can ask where the water is without stalling a frame on the full simulation. Dispatched once per cascade: the first overwrites the grid, the rest add to it. `xyz` is the summed displacement in metres and `w` the strongest folding, so a caller can also ask whether the water at a point is breaking. The swell bank is deliberately absent: it is analytic and longer than the tile this grid covers, so `ocean.module` evaluates it directly on the CPU instead.
▲ 0↑ born
·
computeshader · born here
❒asset
# ocean_spectrum Builds one ocean cascade's time-independent complex wave amplitude `h0(k)` from a JONSWAP directional spectrum: a Phillips energy core, Donelan-Banner directional spreading around the wind, a JONSWAP peak enhancement, and a `k_min`/`k_max` band limit that keeps each cascade to its own disjoint range of wave numbers. The result is randomised into a complex Gaussian so the same sea state produces a real random surface rather than a deterministic ripple. Runs when the sea state changes, not per frame; `ocean_evolve` animates the field it writes.
▲ 0↑ born
▣
module · born here
❒asset
# oceanFloor The ground the water is seen through. It spans the same extent as the clipmap, follows the viewer the way the surface does, and is shaded by `~.shaders.oceanFloor`. One noise field is the whole terrain: scaled it is the relief the seabed's vertex stage raises the grid into, and read again unscaled it picks between sand and rock. Over both moves the sun's caustic web, displaced by the horizontal displacement of the water directly above it. The seabed applies no absorption of its own. The water column belongs to the surface shader, which knows the real distance light travelled through water; attenuating here as well would darken the ground twice. Its three tiling maps are grown once by `ocean_floor_texture` (the same compute-texture path the cascade maps take), so the seabed carries no binary asset and no content reference that could fail to resolve. ```luau local Floor = require("~.modules.oceanFloor") local floor = Floor.create({ config = cfg, -- a resolved ocean config extent = 12800, -- the clipmap's own extent, metres prefix = "twocean1_floor_", name = "Seabed", }) floor:bindWave(cascadeDisplacementTexture, cascadeTile) floor:step(elapsed, viewerX, viewerZ) floor:destroy() ``` `Ocean` creates and drives one of these itself whenever the sea state's `floor` block is enabled, so a scene that uses the `Ocean` component gets a seabed without naming this module at all.
▲ 0↑ born
·
computeshader · born here
❒asset
# ocean_foam The persistent whitecap field: a world-space region, following the viewer, in which foam accumulates where the sea folds and drains everywhere at a fixed half-life. Shading foam directly from the instantaneous fold makes it blink with the wave that caused it. This field is what gives a broken crest a wake of white behind it, and what the surface's `waves` foam layer is actually gated on. Run once per frame, after every cascade's `ocean_normals`. The two history buffers swap roles each frame; the caller binds whichever holds last frame's result as `previous`.
▲ 0↑ born
·
computeshader · born here
❒asset
# ocean_fft Transforms one axis of an ocean cascade's complex field in place, as one dispatch per axis: a workgroup per line runs every Stockham auto-sort radix-2 butterfly stage against workgroup-shared memory, so a 256-wide transform costs one dispatch rather than eight butterfly passes and needs no bit-reversal permutation. Supports grids up to 512 per side. The axis, direction and scale arrive through the bound `plan` buffer rather than a `params:` uniform, because same-frame dispatches are chained into one submission and a uniform rewritten between them would not be seen per-dispatch.
▲ 0↑ born
backing path · tidewater.package/modules/ocean.module

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported on this asset or on the parts this page shows. Parts it leaves out are not counted here.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up agent_score is exposed.
usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor

Usability ratings

Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".

—%no reports yet
Sign in to report whether this part worked for you.
Discussion

Scoped to this part · feeds back into the world's score.

0comments
Sign in to post.sign in
No comments yet. Be the first.