LumosLab-Innovation/3D-lab-skills / plugins/threejs-lab/skills/threejs-water-optics
threejs-water-optics
VerifiedBuild 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.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 3.4 KB |
| agents/openai.yaml | config | 377 B |
| references/water-surface-system.md | markdown | 5.7 KB |
SKILL.md
View on GitHub---
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.
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](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](https://github.com/scottstts/Threejs-Awesome-Graphics-Agent-Skills/blob/31bf12e7b76b76a2650735e02d554a04fb2d2f8b/skills/threejs-water-optics/examples/analytic-wave-optics/water-system.js) for
shared displacement/normals, derivative filtering, reflection, screen-space
refraction, absorption, Fresnel, and crest-linked foam diagnostics.
Read the
[interactive pool volume implementation](https://github.com/scottstts/Threejs-Awesome-Graphics-Agent-Skills/blob/31bf12e7b76b76a2650735e02d554a04fb2d2f8b/skills/threejs-water-optics/examples/interactive-pool-volume/water-volume-system.js)
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. 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.
Source: Scott Sun, MIT. Adapted by LumosLab: example assets remain linked to pinned upstream source; skill instructions and references are bundled. See [LICENSE](LICENSE).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |