# Threejs Spectral Ocean

Build large procedural oceans and coast transitions in Three.js.

- Repository: https://github.com/scottstts/Threejs-Awesome-Graphics-Agent-Skills (956 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-22
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add scottstts/Threejs-Awesome-Graphics-Agent-Skills --skill threejs-spectral-ocean -g -a claude-code -y`
Codex: `npx skills add scottstts/Threejs-Awesome-Graphics-Agent-Skills --skill threejs-spectral-ocean -g -a codex -y`
Cursor: `npx skills add scottstts/Threejs-Awesome-Graphics-Agent-Skills --skill threejs-spectral-ocean -g -a cursor -y`
Gemini CLI: `npx skills add scottstts/Threejs-Awesome-Graphics-Agent-Skills --skill threejs-spectral-ocean -g -a gemini-cli -y`

## Description

Build large procedural oceans and coast transitions in Three.js. Use for WebGPU/TSL FFT oceans, multi-cascade wavelength bands, coastal breakers, finite-volume shallow-water beach waves, signed-distance coastlines, shallow-water swash films, wet-sand transitions, rock-impact spray, stylized above/below surface optics, permanently submerged Snell-window views, total internal reflection, forward-refracted structures through an interface, pixel-footprint spectral LOD, aquatic perspective, caustic god rays, choppy displacement, spectral derivatives, Jacobian whitecaps, windrow and temporal foam, analytic sky reflection, underwater absorption, crest scatter, and GPU validation.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Spectral Ocean

Choose the representation that owns the requested view. Open-water sea states use
explicit frequency-space ownership. A beach-level breaker view uses a coupled
band-limited wave field, coast representation, swash state, foam history, and
sand response. Do not reduce either target to scrolling normal maps or unrelated
foam noise.

This skill contains exemplary examples and assets beyond descriptive guidance,
they're worth studying, referencing, or even copying. Use them sufficiently
when relevant and do NOT blindly skip them.

## Spectral build order

1. Define the sea-state spectrum and deterministic Gaussian seed.
2. Partition wavelengths into disjoint cascades.
3. Validate the inverse FFT independently with analytic inputs.
4. Generate and conjugate-pack the initial spectrum.
5. Evolve packed displacement and derivative fields in frequency space.
6. Inverse-transform every packed field with explicit inter-step barriers.
7. Assemble displacement, derivatives, and persistent Jacobian foam maps.
8. Shade from summed cascade displacement and derivatives.
9. Add sub-grid detail only below the resolved simulation bands.
10. Expose spectrum, height, slopes, Jacobian, and foam-history diagnostics.

Read [references/spectral-cascade-ocean-system.md](references/spectral-cascade-ocean-system.md) before implementing or auditing a spectral ocean.

Read
[references/coastal-breaker-and-swash-ocean.md](references/coastal-breaker-and-swash-ocean.md)
before implementing or auditing the water-to-wet-sand transition of a coastal
breaker system.

Read the [spectral cascade ocean system](examples/spectral-cascade-ocean/ocean-system.js)
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.

The rest: https://github.com/scottstts/Threejs-Awesome-Graphics-Agent-Skills/blob/HEAD/skills/threejs-spectral-ocean/SKILL.md