Spectral Ocean
Treat an ocean as a sampled stochastic wave field with explicit frequency-space ownership. Do not approximate this target with a pile of Gerstner waves, scrolling normal maps, or unrelated foam noise.
Build order
- Define the sea-state spectrum and deterministic Gaussian seed.
- Partition wavelengths into disjoint cascades.
- Validate the inverse FFT independently with analytic inputs.
- Generate and conjugate-pack the initial spectrum.
- Evolve packed displacement and derivative fields in frequency space.
- Inverse-transform every packed field with explicit inter-step barriers.
- Assemble displacement, derivatives, and persistent Jacobian foam maps.
- Shade from summed cascade displacement and derivatives.
- Add sub-grid detail only below the resolved simulation bands.
- Expose spectrum, height, slopes, Jacobian, and foam-history diagnostics.
Read references/spectral-cascade-ocean-system.md before implementing or auditing a spectral ocean.
Read the spectral cascade ocean system
and its adjacent spectrum, FFT, material, and detail modules for the cascade,
FFT, derivative, Jacobian, foam-history, and shading contracts. Its WebGL2
fragment-FFT backend is an explicit compatibility tier; preserve the
production WebGPU/TSL architecture described in the reference when the target
supports it.
Read the
hybrid clear-water ocean material
when the target needs FFT displacement with authored long swell, clear shallow
refraction, animated sand-bed caustics, Beer-Lambert color, shared sky
reflection, side-aware above/below surface normals, GGX sun highlights, and
foam diagnostics.
Read the
stylized above/below ocean material
when the target needs a stylized FFT ocean that can be inspected from both
above and below the surface: height-gradient water color, sun-path glints,
crest scatter, Jacobian foam, water-tinted seafloor caustics, and an
underwater Beer-Lambert composite driven by scene depth.
Non-negotiable gates
- Require a power-of-two grid and a passing FFT impulse/frequency test.
- Keep cascade wavenumber intervals disjoint.
- Derive normals from transformed derivatives, not a detached normal texture.
- Detect breaking from the horizontal-displacement Jacobian.
- Persist foam in simulation state; do not infer all foam anew per frame.
- Submit FFT stages with the synchronization required by the active backend.
- Share sun and sky parameters between the visible sky and ocean reflection.
- Keep a deterministic seed and fixed-camera capture for comparisons.
Route elsewhere
- Use
$threejs-water-optics for bounded water, screen-space refraction, depth thickness, shoreline absorption, and analytic wave surfaces.
- Add
$threejs-procedural-vfx only when crest spray or interaction splashes are required.
- Add
$threejs-visual-validation for cross-seed, temporal, and GPU evidence.
1---2name: threejs-spectral-ocean3description: Build large procedural oceans in Three.js from directional wave spectra. Use for WebGPU/TSL FFT oceans, multi-cascade wavelength bands, hybrid FFT plus Gerstner clear-water oceans, stylized above/below surface ocean optics, choppy displacement, spectral derivatives, Jacobian whitecaps, temporal foam, analytic sky reflection, underwater absorption, crest scatter, and GPU validation.4---56# Spectral Ocean78Treat an ocean as a sampled stochastic wave field with explicit frequency-space ownership. Do not approximate this target with a pile of Gerstner waves, scrolling normal maps, or unrelated foam noise.910## Build order11121. Define the sea-state spectrum and deterministic Gaussian seed.132. Partition wavelengths into disjoint cascades.143. Validate the inverse FFT independently with analytic inputs.154. Generate and conjugate-pack the initial spectrum.165. Evolve packed displacement and derivative fields in frequency space.176. Inverse-transform every packed field with explicit inter-step barriers.187. Assemble displacement, derivatives, and persistent Jacobian foam maps.198. Shade from summed cascade displacement and derivatives.209. Add sub-grid detail only below the resolved simulation bands.2110. Expose spectrum, height, slopes, Jacobian, and foam-history diagnostics.2223Read [references/spectral-cascade-ocean-system.md](references/spectral-cascade-ocean-system.md) before implementing or auditing a spectral ocean.2425Read the [spectral cascade ocean system](examples/spectral-cascade-ocean/ocean-system.js)26and its adjacent spectrum, FFT, material, and detail modules for the cascade,27FFT, derivative, Jacobian, foam-history, and shading contracts. Its WebGL228fragment-FFT backend is an explicit compatibility tier; preserve the29production WebGPU/TSL architecture described in the reference when the target30supports it.3132Read the33[hybrid clear-water ocean material](examples/hybrid-clear-water-ocean/hybrid-ocean-material.js)34when the target needs FFT displacement with authored long swell, clear shallow35refraction, animated sand-bed caustics, Beer-Lambert color, shared sky36reflection, side-aware above/below surface normals, GGX sun highlights, and37foam diagnostics.3839Read the40[stylized above/below ocean material](examples/stylized-above-below-ocean/stylized-ocean-material.js)41when the target needs a stylized FFT ocean that can be inspected from both42above and below the surface: height-gradient water color, sun-path glints,43crest scatter, Jacobian foam, water-tinted seafloor caustics, and an44underwater Beer-Lambert composite driven by scene depth.4546## Non-negotiable gates4748- Require a power-of-two grid and a passing FFT impulse/frequency test.49- Keep cascade wavenumber intervals disjoint.50- Derive normals from transformed derivatives, not a detached normal texture.51- Detect breaking from the horizontal-displacement Jacobian.52- Persist foam in simulation state; do not infer all foam anew per frame.53- Submit FFT stages with the synchronization required by the active backend.54- Share sun and sky parameters between the visible sky and ocean reflection.55- Keep a deterministic seed and fixed-camera capture for comparisons.5657## Route elsewhere5859- Use `$threejs-water-optics` for bounded water, screen-space refraction, depth thickness, shoreline absorption, and analytic wave surfaces.60- Add `$threejs-procedural-vfx` only when crest spray or interaction splashes are required.61- Add `$threejs-visual-validation` for cross-seed, temporal, and GPU evidence.
jorgeasaurus