What it does. Build production analytic and bounded water in Three.js. Use for shared multi-wave displacement and normals, bounded RGBA heightfield pool simulation, local drops, object-driven ripples, differential-area caustics, ray-traced pool/water/sphere volume optics, derivative-filtered normal bands, analytic sky reflection, side-aware Fresnel, heuristic screen refraction, Beer-Lambert absorption, and crest foam. Part of scottstts/Threejs-Awesome-Graphics-Agent-Skills (scottstts/Threejs-Awesome-Graphics-Agent-Skills).

Install

• npx skills add scottstts/Threejs-Awesome-Graphics-Agent-Skills --skill threejs-water-optics, or copy the skill folder into ~/.claude/skills/threejs-water-optics/.
• Raw file: curl -sL https://raw.githubusercontent.com/scottstts/Threejs-Awesome-Graphics-Agent-Skills/HEAD/skills/threejs-water-optics/SKILL.md

SKILL.md (verbatim)

name: threejs-water-optics
description: Build production analytic and bounded water in Three.js. Use for shared multi-wave displacement and normals, bounded RGBA heightfield pool simulation, local drops, object-driven ripples, differential-area caustics, ray-traced pool/water/sphere volume optics, derivative-filtered normal bands, analytic sky reflection, side-aware Fresnel, heuristic screen refraction, Beer-Lambert absorption, and crest foam.

Water Optics

Treat water as geometry motion, surface orientation, and a participating optical layer. A blue transparent material is not a water system.

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.

For large stochastic seas driven by directional spectra and GPU FFTs, use $threejs-spectral-ocean instead.

Analytic surface build order

1. Define wave bands and evaluate displacement.
2. Derive the normal analytically from the same waves.
3. Choose displaced geometry or explicitly normal-only water.
4. Establish scene-color ownership for heuristic refraction.
5. Declare whether absorption uses true depth or a fallback path-length estimate.
6. Blend analytic reflection/refraction through side-aware Fresnel.
7. Derive foam and glints from the shared wave response.
8. 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.

Other files in this skill

• agents/openai.yaml
• assets/interactive-pool-volume/tiles.jpg
• assets/interactive-pool-volume/xneg.jpg
• assets/interactive-pool-volume/xpos.jpg
• assets/interactive-pool-volume/ypos.jpg
• assets/interactive-pool-volume/zneg.jpg
• assets/interactive-pool-volume/zpos.jpg
• examples/analytic-wave-optics/water-system.js
• examples/interactive-pool-volume/water-volume-system.js
• references/water-surface-system.md

references/water-surface-system.md (verbatim)

Analytic water surface system

Use this reference for analytic water surfaces with shared displacement and normals, derivative-filtered detail, analytic reflection, heuristic refraction, absorption, and crest foam. For the bounded pool heightfield simulation and its volume optics, read the interactive-pool-volume example. Use $threejs-spectral-ocean for stochastic FFT seas.

Contents

• Authored five-wave displaced ocean
• Shared displacement/normal contract
• Optical hierarchy
• Normal-only wave bundle
• Side-aware refraction and absorption
• Foam and distance response
• Objective limits
• Diagnostics

Authored five-wave displaced ocean

The analytic-wave-optics example uses five authored Gerstner-style components:

For every wave:

k = 2π / wavelength
omega = sqrt(9.81 * k)
phase = k * dot(direction, xz) - omega * time
horizontal offset = direction * steepness * amplitude * cos(phase)
vertical offset = amplitude * sin(phase)

The ocean is a 1200 x 1200 plane with 256 x 256 segments. A CPU height function evaluates the same five vertical sine terms for camera clearance.

Shared displacement/normal contract

The TSL normal function evaluates the same directions, amplitudes, wavelengths, and phases as displacement:

Nx += direction.x * k * amplitude * sin(phase)
Ny += steepness * k * amplitude * cos(phase)
Nz += direction.y * k * amplitude * sin(phase)
normal = normalize((-Nx, 1 - Ny, -Nz))

This exact parameter sharing is the defining mechanism. If a wave changes, both geometry and normal evaluation change together.

Optical hierarchy

After the displaced macro normal, the example adds three derivative-attenuated micro wave bands (wavelengths 5.25, 3.0, 1.5, amplitudes 0.12, 0.08, 0.05) and two low-amplitude noise gradients for wind-aligned micro-turbulence.

Water response is side-aware:

above water: eta = 1 / 1.333
underwater:  eta = 1.333
F0 = ((1 - eta) / (1 + eta))^2 + 0.035
F = F0 + (1 - F0) * (1 - |NdotV|)^5

Reflection samples the same analytic sky used by the sky dome. Sun response:

reflection disc = dot(reflection, sun)^2500 * 14
reflection halo = dot(reflection, sun)^14 * 1.1
surface specular = dot(normal, halfVector)^1200 * 12

The transmitted body mixes a deep-blue base with the refracted scene sample (mix(deep, sceneRefraction, 0.65)) under Beer-Lambert transmittance. A forward-scatter term uses dot(view, -sun)^4, scaled by 0.42 * (1 - Fresnel). Crest scatter adds crest * 0.28; crest itself derives from (1 - normal.y) slope, and distance haze uses:

1 - exp(-distance * 0.0026)

Normal-only wave bundle

The flat-mesh variant leaves geometry undisplaced. Its material computes a normal and crest from six world-XZ wave bands:

wavelengths = 12, 6, 2.5, 5.25, 3.0, 1.5
relative amplitudes = 1, 0.55, 0.22, 0.12, 0.08, 0.05
directions = wind, cross-wind, 45°, +30°, -30°, +60°
dispersion = sqrt(9.8 * k)

High-frequency bands are attenuated from screen derivatives:

aa3 = 1 - smoothstep(0, 2.0, footprint * k3)
aa4 = 1 - smoothstep(0, 1.5, footprint * k4)
aa5 = 1 - smoothstep(0, 1.0, footprint * k5)

Two low-amplitude noise gradients add wind-aligned micro-turbulence. The crest metric combines slope with phase alignment from all six waves. The analytic-wave-optics example adopts this bundle’s three finest bands and turbulence gradients as its micro detail.

Use this only when normal-only water is appropriate. Do not claim geometry and normal parity because the geometry remains flat.

Side-aware refraction and absorption

Defaults:

air/water eta = 1 / 1.333
extra Fresnel bias = 0.035
absorption = (0.20, 0.06, 0.02) per meter
fallback depth = 4 m
refraction strength = 0.18
roughness control = 0.35

The shader is side-aware:

above water: eta = air / water
underwater: eta = water / air
F0 = ((1 - eta) / (1 + eta))^2 + artistic bias

When scene color exists, sample one or two clamped screen offsets from the refracted direction and procedural noise (the analytic-wave-optics example uses one clamped sample). When scene depth is absent, path length is approximated from fallback thickness and the refracted vertical component:

path = fallbackDepth / abs(refractedDirection.y)
transmittance = exp(-absorption * path)

This produces depth-dependent color but not actual object thickness.

Foam and distance response

Crest-attached foam:

foamSeed = noise(xz * 0.9 + wind * time * foamDrift)
foam = smoothstep(
  threshold,
  1,
  crest * noisy modulation
)

It is causally attached to the crest output, then broken up by noise.

A bounded transparent surface can also increase opacity over a configured distance range (25–140 world units) and treat underwater alpha separately. This helps it meet a far-ocean horizon.

Objective limits

• The five-wave sea is authored, not a directional spectrum.
• The normal-only bundle cannot produce crest silhouette or geometric parallax.
• The screen refraction has no depth rejection and can sample foreground objects.
• Its thickness is a fallback estimate, not reconstructed scene thickness.
• The demonstrated paths use artistic sky reflection rather than environment prefiltering or planar reflection.
• Crest foam is instantaneous and lacks persistent build/decay.
• Route to $threejs-spectral-ocean when the target is implementation-level spectral open water rather than a bounded authored-wave surface.

Diagnostics

Expose:

each authored wave band
displaced position and analytic normal
normal-only versus displaced comparison
derivative attenuation per micro band
crest metric before noise
Fresnel and side classification
raw refraction UV and validity
fallback path length and transmittance
reflection, body scatter, glint, and foam separately
distance haze/opacity
CPU versus GPU surface height at camera position

Back to scottstts/Threejs-Awesome-Graphics-Agent-Skills or Agent skills.