Water bodies, waves, and buoyancy

Dawn Engine Water authors streams, rivers, lakes, and oceans as first-class water bodies: a unified surface query (height / depth / flow), Atom refraction and reflection, Gerstner or FFT waves, buoyancy physics, and optional bridges to SurfaceData, Navigation3D, and particles.

Maturity: shipped. Provided by the Water Gem; depends on LmbrCentral, Atom / Atom_RPI, and SurfaceData. Enabled by default (/O3DE/Gems/Water/Enabled=true). After enablement, the system component mounts automatically; you still place river / lake / ocean components on scene entities.

It does not provide CFD flooding or automatic river–lake–ocean fusion: levels and estuary blends are authored (mouth fade + optional blend band). Tide is a global / per-body height offset, not a hydrodynamic sim.

What problem it solves

Open-world and digital-twin levels need more than a flat reflective plane: flowing rivers with variable width, lakes with islands, camera-centered oceans, floating objects, swimming / underwater fog, and gameplay that can ask “what is the water height here?”. Water provides:

• Spline rivers (Stream / River / GreatRiver presets), closed-spline or polygon lakes, and infinite or finite oceans;
• Deterministic surface mesh generation and a shared water clock so CPU queries match GPU displacement (≤ 1 cm @ 100 km);
• .waterwaves spectrum assets (explicit Gerstner or Phillips / JONSWAP → FFT);
• Stage rendering: refraction, planar reflection / SSR / IBL, shore foam, caustics, underwater fog / DoF, motion vectors;
• WaterBuoyancyComponent plus enter / exit / submersion events for physics and gameplay.

With the Gem disabled, levels have no water bodies, queries, or water pass draws.

How it works

Editor authoring (spline / sea level / waves / bake)
 │
WaterBody*Component ──► BuildSurface() ──► WaterBodyRegistry (CPU queries / physics)
 │
 └──────────────► BuildRenderData() ──► WaterFeatureProcessor (Atom)
 │
 TransparentPass ← WaterParent (refract / surface / FFT / caustics)
 │
Gameplay / buoyancy / script ──► WaterSurfaceRequestBus (Vector3d world sample)

Two rules run through the Gem:

1. Core vs framework: wave math, river sampling, and mesh generation depend only on AzCore and stay headless-testable; components and bridges orchestrate.
2. One query surface: physics, camera underwater checks, SurfaceData tags, and scripts all go through WaterSurfaceRequestBus against the same registry arbitration (river family > lake > ocean by default priority).

Layout under Gems/Water/:

Open-world projects typically combine Water with double-precision rendering, World Streaming, and optionally PolyTerrain for river-bed carve.

Quick start (summary)

1. Enable Water (Project Manager or project.json). Confirm /O3DE/Gems/Water/Enabled=true and that the Atom pipeline includes TransparentPass (or MultiViewTransparentPass).
2. Create Entity → Water → Lake (or River / Ocean), or spawn a prefab from Gems/Water/Assets/Prefabs/Water/.
3. Assign waves and a material; for floating debris add Rigid Body + Collider + WaterBuoyancyComponent.
4. Query via WaterSurfaceRequestBus (C++ / Lua / Script Canvas category water).

For the full walkthrough and verification checklist, see Getting started.

Handbook chapters

Glossary

Limits and related capabilities

You can rely on:

• Stream / River / GreatRiver, Lake, Ocean authoring with live editor preview;
• Unified WaterSurfaceRequestBus queries matching GPU displacement;
• Gerstner + Spectrum/FFT waves, shore / flow bake, buoyancy and script events;
• Quality tiers, World Streaming AlwaysLoaded ocean, optional Navigation3D / particle / SurfaceData bridges.

Do not assume:

• Automatic CFD flooding or auto-merged river–lake–ocean topology;
• Runtime PolyTerrain height queries without an editor shore / depth bake;
• More than one unbounded ocean, or more than one Spectrum ocean driving FFT (extras fall back to CPU approx);
• Mobile-tuned paths (use Low tier as the baseline).

Next steps

• Getting started — shortest path to visible water and a working query.
• PolyTerrain — river-bed carve and mesh-terrain coexistence.
• World Streaming / Double-precision rendering — large-world oceans and origin-stable waves.
• Navigation3D — underwater hybrid routing against Water body regions.