技能 编程开发 Three.js 光谱海洋渲染

Three.js 光谱海洋渲染

v20261015
threejs-spectral-ocean
该技能用于在 Three.js 中构建大型程序化海洋和海岸过渡效果。支持 WebGPU 和 TSL FFT 海洋、多级波长带及海岸破碎波。包含有限体积浅水波、有向距离海岸线、湿沙过渡及水下光学效果,如斯内尔窗视图和焦散神光。适用于需要 GPU 验证的真实水生环境。
获取技能
470 次下载
概览

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 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
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.

Read the
ocean beach waves implementation
when the beach is owned by a positivity-preserving finite-volume solver: it
provides a rocky coastal grid, reconstructed water and wet-sand fields,
advected foam, shallow-film optics, reflected and refracted sky radiance, and
impact-triggered spray.

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.1346 times 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 the entire optical side from one camera-medium state; do not choose above/below behavior per triangle.
  • Terminate distant underwater sightlines with a safely submerged terrain rim; do not mask an empty seabed/ocean horizon with a view-aligned scattering layer.
  • Keep a deterministic seed and fixed-camera capture for comparisons.

Coastal breaker gates

  • Keep coastline SDF, arclength tables, ribbon geometry, and swash columns in

one coast contract; do not derive unstable column ordering from SDF gradients.

  • Hand offshore wave level into the coast-normal conserved-volume chain; a

linear spring chain does not uniquely recover a flat free surface.

  • Persist both world-space breaker foam and coast-parameterized film foam.
  • Blend water, wet sand, and dry sand by the actual water column, not a detached

shoreline decal.

  • Derive water normals from the same gravity/capillary fields that displace the

surface, and derivative-filter sand normal detail at grazing distance.

  • Share sky radiance and sun direction between the visible surround and ocean

reflection.

  • Keep the orbit camera above the terrain and use a fixed waterline camera for

comparisons.

Route elsewhere

  • Use $threejs-water-optics and its photoreal-water example for air-side shallow-water FFT optics, RGB caustics and diffraction glare. Use that skill for bounded water, screen-space refraction, depth thickness, shoreline absorption, and analytic wave surfaces. Its screen-space refraction is valid there because the camera stays in air and the volume is bounded; it is not a substitute for this skill's forward projection across an open interface.
  • Add $threejs-procedural-vfx only when crest spray or interaction splashes are required.
  • Add $threejs-visual-validation for cross-seed, temporal, and GPU evidence.
信息
分类 编程开发
名称 threejs-spectral-ocean
版本 v20261015
大小 4.83MB
更新时间 2026-10-17
语言