Module ocean 

Gerstner ocean wave spectrum — the single source of truth for wave math.

The CPU generates a deterministic, seeded spectrum of trochoidal (Gerstner) waves with deep-water dispersion. The renderer uploads the same wave array to the GPU (see flint-render/src/ocean_shader.wgsl), which only sums it — so a sample_height() query and the rendered surface can never disagree, which is what makes script-driven buoyancy believable.

Per-frame wave phases are computed here in f64 and reduced mod 2π before upload, so f32 sin precision never degrades over long sessions.

Conventions: Y is up; waves displace in XZ. For wave i with direction d, wavenumber k = 2π/λ, amplitude A, steepness Q, and phase θ = k·(d·p) − ω·t + φ₀:

offset.xz = Σ Q·A·d·cos θ        offset.y = Σ A·sin θ
normal    = normalize(−Σ d.x·k·A·cos θ,  1 − Σ Q·k·A·sin θ,  −Σ d.y·k·A·cos θ)

Steepness is normalized (Qᵢ = choppiness / (kᵢ·Aᵢ·N)) so the summed steepness never exceeds choppiness ≤ 1 — no self-intersecting loops.

Structs

GerstnerWave

One Gerstner wave. All fields precomputed at spectrum generation.

OceanParams

Simulation parameters — everything that shapes the spectrum. These map 1:1 to the ocean component fields (see schemas/components/ocean.toml).

WaveSpectrum

A generated spectrum plus the params that produced it.

Constants

GRAVITY

Gravitational acceleration for deep-water dispersion ω = √(g·k).

MAX_WAVES

Maximum waves in a spectrum (mirrors the WGSL uniform array size).