beautiful-water

KO | EN

gitlite — search

#docker #php #machine-learning #mcp #svg #ui #ai-agents #monitoring #github #ai-agent

beautiful-water

(★ 9)

Procedural Three.js shallow ocean with reflections, foam, underwater life, and visual regression testing

File Explorer

ZIP Download

- - ci.yml
  - deploy-pages.yml
  - pr-preview.yml
- effort-hours-manual-review.md
- effort-hours-report.md
- open-water.jpg
- check-linear-history.ps1
- check-pages-build.mjs
- profile-native-4k-sustain.mjs
- profile-performance.mjs
- smoke-pages.mjs
- - adaptive-quality.js
  - gpu-frame-timer.js
  - presentation-monitor.js
  - render-cap.js
  - renderer-diagnostics.js
  - renderer.js
  - runtime-identity.js
- - buoy.js
  - environment.js
  - fish.js
  - noise-texture.js
  - ocean-webgpu.js
  - ocean.js
  - pipeline.js
  - sky-webgpu.js
  - sky.js
  - underwater-rays-webgpu.js
  - underwater-rays.js
  - waves.js
  - webgpu-water-functions.js
  - webgpu-water-material.js
  - webgpu-wave-nodes.js
- - sky.js
  - water.js
- - loading.js
  - render-cap.js
  - renderer-toggle.js
- main.js
- style.css
- - adaptive-quality.test.js
  - gpu-frame-timer.test.js
  - presentation-monitor.test.js
  - render-cap.test.js
  - renderer-preference.test.js
  - runtime-diagnostics.test.js
  - workflow-budget.test.js
- - ocean.visual.spec.js
  - performance-hud.spec.js
  - runtime.performance.spec.js
  - runtime.sustain.spec.js
  - screenshot-metrics.js
  - wave-field.js
.gitignore
AGENTS.md
bun.lock
index.html
LICENSE
package.json
playwright.config.js
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

CI Visit
Deploy GitHub Pages Visit
MIT License Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A cinematic, full-screen shallow-ocean environment rendered with Three.js. It combines a
directional procedural wave spectrum with physically grounded surface lighting, a responsive
navigation buoy, and an explorable underwater habitat. WebGPU is the default renderer, with a
persistent in-scene WebGL toggle and automatic WebGL 2 fallback when native WebGPU is unavailable.

[![Beautiful Water running in the browser](https://raw.githubusercontent.com/VictorZakharov/beautiful-water/main/docs/open-water.jpg)](https://victorzakharov.github.io/beautiful-water/)

**[Open the live demo](https://victorzakharov.github.io/beautiful-water/)**

## A two-day build and effort-estimation case study

The complete project—from the initial water prototype through dual WebGPU/WebGL renderers,
underwater behavior, automated visual regression, performance adaptation, and publishing—was
developed in **two days of intensive human-AI collaboration**. That unusually short delivery
window makes the repository useful both as a pretty public graphics demo and as a transparent
calibration case for software-effort estimation.

[EffortHours](https://github.com/VictorZakharov/efforthours) is an evidence-first, offline .NET CLI.
It uses static analysis to turn source, tests, documentation, configuration, and delivery
artifacts into traceable **Equivalent Human Effort (EHE)**. EHE asks how long one competent senior
contractor, unfamiliar with the domain and not using AI, would need to recreate the current
functional and quality state from a clear specification. EffortHours does not infer productivity
from a repository alone and is not an authorship detector. When EHE is paired with independently
measured delivery effort, however, it can support a derived productivity comparison.

Its analysis estimates that this finished repository represents 161.5 equivalent human-hours,
with a preliminary range of 78–306.75 hours. A separate manual code review estimates 240 hours,
with a clean-recreation range of 182–302 hours. Pairing those expected values with the observed
two-day delivery window compares roughly four to six conventional full-time weeks of represented
output with two days of AI-assisted delivery. That demonstrates striking productivity
amplification, but it is not a precise individual productivity score: calculating an exact
multiplier would require separately logged active human hours.

- [Complete EffortHours report](docs/effort-hours-report.md)
- [Detailed manual effort review](docs/effort-hours-manual-review.md)

Both reports are committed with the source so this project can serve as a reproducible case for
refining the `eh` estimator while the live demo remains available for direct visual inspection.

## Features

- Broad, non-repeating directional swells with domain warping, wave packets, crest shaping,
  distance-aware detail, and a CPU sampler shared by floating objects.
- Projective reflection and refraction, Fresnel response, GGX sun glitter, shallow-water
  transmission, depth-dependent cyan-to-blue color, cloud reflections, and cloud shadows.
- Transported, lifecycle-driven foam that follows energetic crests without revealing a tiled
  wave pattern or moving as a single permanent sheet.
- A visible sun, procedural sky and clouds, natural reflection path, underwater caustics,
  volumetric sun rays, seabed vegetation, and rocks.
- A procedural navigation buoy that bobs, tilts, reflects, casts a shadow, and remains the
  camera's orbit pivot.
- Three procedural fish schools with separation, alignment, cohesion, depth avoidance,
  curiosity, habituation, and escape responses to a moving underwater camera.
- Above-water and underwater rendering states reached continuously by orbiting through the
  animated surface, plus a responsive loading screen, rolling GPU-pass timing, and a 15-second
  rendered-FPS history. Clicking the performance panel copies a complete diagnostic report.
- GPU-aware render budgets, high-density antialiasing policy, and GPU-pass p95 feedback keep
  4K displays practical without changing the CSS resolution or the default 1080p presentation.
- Native WebGPU/TSL and legacy WebGL/GLSL water pipelines share the same wave spectrum, scene,
  controls, simulation clock, and quality controller. Backend-only code is loaded on demand so
  the compatibility option does not block the initial renderer.
- No downloaded scene assets: geometry, behavior, shaders, sky, noise, and habitat details are
  generated in code and released under the MIT license.

## Run locally

```bash
bun install
bun run dev
```

Open the local URL printed by Vite.

- Left mouse: orbit around the buoy
- Wheel: move toward or away from the buoy
- Orbit beneath the surface to enter the underwater environment
- Use the upper-right renderer switch to reload in WebGPU or WebGL mode
- Use the upper-right render-cap selector to limit actual GPU submissions to 30, 60, 120, 144,
  or 240 FPS. The selection is saved locally; `Off` renders once per browser animation callback.
  A cap is a maximum workload rate, not a guarantee that a slow GPU or physical panel can meet it.
- When timestamp queries are available, adaptive quality reserves GPU headroom for a 60 FPS target,
  or for a lower selected cap. Browser callback cadence remains the fallback on unsupported GPUs.
- Click the upper-left performance graph to copy the latest 15-second diagnostic report. It labels
  actual rendered FPS separately from browser animation callback rate, reports the selected cap and
  whether the browser sees multiple screens, and states that physical panel Hz is unavailable to
  the page. It also includes a readable browser/platform summary plus the raw compatibility user
  agent, adaptive-quality GPU decision, and per-frame renderer statistics.

Panning and cursor-offset zoom are intentionally disabled so the buoy remains the stable focal
point.

## Automated visual harness

The included Playwright harness starts Vite, freezes the simulation clock, and captures twenty
named regression views at 1600 by 900 locally. It also renders four identical camera/time presets
through WebGL and WebGPU, writes the individual frames plus labeled side-by-side composites, and
enforces normalized pixel-error and perceptual-similarity limits. Pull-request CI runs the scene,
fish, and renderer-parity gates in parallel at 960 by 540; every CI job has a hard two-minute cap.
The full camera matrix remains available locally, while the required gate samples every major
rendering and behavior system. Fixed-step fish habituation advances simulation state without
wasting software-GPU time on intermediate frames. Coverage includes:

- the sun path, cross-sun grazing angles, opposite-sun water, and top-down rendering;
- near, wide, and far-field compositions designed to expose repetition and grazing artifacts;
- foam formation, transition, replacement, and long-interval transport;
- general underwater rendering plus calm, curious, and startled fish behavior;
- loading-stage order, progress monotonicity, frame cadence, shader warm-up, and browser errors;
- rolling rendered-FPS history, saved render-cap behavior, runtime identity, per-frame renderer
  statistics, and click-to-copy performance-report contents;
- 4K framebuffer budgets, integrated/discrete GPU policy, GPU-overload downshifts, and guarded
  adaptive quality recovery;
- WebGPU/WebGL selection, fallback diagnostics, shared wave geometry, and side-by-side parity;
- displacement-field correlation at three simulation times to prevent periodic tiling from
  returning unnoticed.

```bash
bun run visual:test
bun run quality:test
# Optional WebGL/WebGPU 1080p, 1440p, and 4K timing profile
# (not used as a hardware-dependent CI gate)
bun run performance:profile
# Native WebGPU 4K/144 Hz sustain gate (hardware-dependent, local only)
bun run performance:sustain-4k
```

Screenshots, side-by-side composites, pixel metrics, camera and renderer diagnostics,
wave-correlation measurements, and startup timing are written to `visual-results/`. The optional
profile adds rendered FPS, browser animation callback rate, and rolling 10-second GPU-pass p50/p95
measurements to `runtime-timings.json`. Each renderer/resolution case runs in
a fresh browser process so GPU state cannot leak between samples. Set
`PERFORMANCE_VIEWPORT` to `1080p`, `1440p`, or `4K`, and
`PERFORMANCE_RENDERER` to `webgl` or `webgpu`, to profile a subset. Set
`PLAYWRIGHT_CHROMIUM_PATH` when Chrome or Edge is not in a standard location.

The native-4K sustain gate is the stricter throughput proof. It locks WebGPU to an exact
3840-by-2160 drawing buffer and the high-quality capture/shadow settings, warms up for 10 seconds,
then measures both the surface and underwater views for 30 seconds each in fresh browser
processes. It fails if the canvas or quality revision changes, observed animation-loop throughput
falls below 99.5% of the requested callback target, more than 0.5% of callback slots are missed,
frame-interval-tail, CPU-submit, or GPU-pass budgets are exceeded, or the browser reports an error.
The complete
per-view evidence is written to `visual-results/native-4k-sustain.json`; change the default
144 callbacks/s target with `PERFORMANCE_TARGET_FPS` when validating a different callback budget.

## Production and GitHub Pages

```bash
bun run build
bun run build:pages
bun run check:pages
```

Pull requests run independent production-build and time-budgeted browser renderer checks. Pushes to
`main` retain the quick production verification but skip the already-passed browser gate. Pages
then builds the repository-scoped artifact, deploys through GitHub's official actions, and
smoke-tests the live document and JavaScript bundle without repeating the visual matrix.

Every same-repository pull request also receives a sticky link to an isolated preview at
`/beautiful-water/pr-preview/pr-<number>/`. Preview and production publication share one serialized
Pages pipeline, production retains previews for open pull requests, and stale previews are removed
when their pull requests close.

## License

MIT -- see [LICENSE](LICENSE).

beautiful-water

Owner Repos

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

beautiful-water

Owner Repos

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README