threejs-spectral-ocean
Build large procedural oceans and coast transitions in Three.js. Use for WebGPU/TSL FFT oceans, multi-cascade wavelength bands, hybrid FFT plus Gerstner clear-water oceans, coastal breakers, signed-distance coastlines, shallow-water swash films, wet-sand transitions, 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.
scottstts · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add scottstts/Threejs-Awesome-Graphics-Agent-Skills --skill threejs-spectral-ocean技能说明
name: threejs-spectral-ocean description: Build large procedural oceans and coast transitions in Three.js. Use for WebGPU/TSL FFT oceans, multi-cascade wavelength bands, hybrid FFT plus Gerstner clear-water oceans, coastal breakers, signed-distance coastlines, shallow-water swash films, wet-sand transitions, 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.
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
- 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 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 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.
Read the submerged Snell ocean system when the camera must remain underwater beneath a WebGPU spectral surface: it provides exact water-to-air Fresnel with a derivative-filtered critical-angle mask, total internal reflection against a physically bright upwelling underside, an energy-conserving transmitted-sun lobe, forward projection of above-water structures into the window, shared HDR sky radiance, aquatic extinction and in-scatter, footprint-faded differential-area caustics, full-resolution god rays, suspended particulates, and the final HDR grade.
Read the coastal breaker ocean system when the defining view sits at the waterline: it provides deterministic band-limited gravity and capillary fields, a signed-distance mainland and island coast, coast-normal shallow-water swash chains, persistent breaker and film foam, camera-following warped geometry, wet-sand optics, and shared sky radiance.
Spectral 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.
- Transport opposite-medium structures by FORWARD projection: rasterize their own vertices at their refracted screen positions. On an open interface, never trace a water pixel backward to a source screen position, and never gate transported radiance on whether a direction's vanishing point lands on screen. (A bounded pool seen only from air can still use the screen-space offset in
$threejs-water-optics; an ocean whose camera changes medium cannot.) - Bracket a water-side crossing solve by the critical angle (
tan θc ≈ 1.1346times the ray's own distance from the interface), not by the camera-to-source span. - Scale spectral LOD by PIXEL FOOTPRINT —
distance² · pixelAngle / heightGap— and apply it to vertex displacement, derivatives, and every band that rides them. Fade each band to its own mean when the band is an albedo or radiance term. - Filter the critical-angle domain test over about one output pixel; never filter the interface normal itself to stabilize what is transported through it.
- Gate th