jorgeasaurus Water Optics
Treat water as geometry motion, surface orientation, and a participating optical layer. A blue transparent material is not a water system.
For large stochastic seas driven by directional spectra and GPU FFTs, use
$threejs-spectral-ocean instead.
Analytic surface build order
- Define wave bands and evaluate displacement.
- Derive the normal analytically from the same waves.
- Choose displaced geometry or explicitly normal-only water.
- Establish scene-color ownership for heuristic refraction.
- Declare whether absorption uses true depth or a fallback path-length estimate.
- Blend analytic reflection/refraction through side-aware Fresnel.
- Derive foam and glints from the shared wave response.
- Filter unresolved normal bands from derivatives.
Read references/water-surface-system.md for the exact five-wave displaced ocean, six-band normal-only water, optical hierarchy, and the limits that distinguish both from the spectral-ocean skill.
Read the analytic wave optics implementation for shared displacement/normals, derivative filtering, reflection, screen-space refraction, absorption, Fresnel, and crest-linked foam diagnostics.
Read the interactive pool volume implementation for bounded RGBA height/velocity/normal simulation, local drops, moving-sphere displacement suitable for draggable objects, differential-area caustics, and shadered pool/water/sphere ray tracing against the pool bounds and sphere.
Failure conditions
- normal texture motion does not agree with displaced crests;
- heuristic refraction can sample foreground objects but the limitation is undisclosed;
- fallback path length is presented as reconstructed scene thickness;
- bounded pool caustics are a decorative projection detached from simulated height normals;
- micro-waves alias into sparkling noise;
- foam is a scrolling texture unrelated to the shared crest metric;
- Fresnel is replaced by constant opacity;
- reflection, refraction, and transparency are all added without energy control.
Routing boundary
Use $threejs-spectral-ocean for stochastic directional spectra, FFT
cascades, Jacobian breaking, and persistent ocean foam. This skill owns
authored analytic waves, bounded heightfield simulation, ray-traced
pool-volume optics, and bounded-water optics.