Threejs Water Optics Agent Skill

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

in-shader 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, persistent ocean foam, and any interface the camera

crosses — this skill's heuristic screen-refraction offset assumes a bounded

volume seen from air, and an open interface needs that skill's forward

projection instead. Use

$threejs-precipitation-surfaces for rain-driven puddle wetness, ripple masks,

and weather-coupled splashes on ground surfaces. This skill owns authored

analytic waves, bounded heightfield simulation, ray-traced pool-volume optics,

and bounded-water optics.