Water getting started

This chapter gets water on screen with the shortest path: enable the Gem, place a body, assign waves and a material, optionally add buoyancy, then verify with a query or a sample level.

Prerequisites

The Water Gem is enabled in your project (Project Manager or project.json). Dependencies include LmbrCentral, Atom, Atom_RPI, and SurfaceData.
Atom main pipeline includes the Water pass anchor: TransparentPass or MultiViewTransparentPass. If the anchor is missing, water draws are skipped once with a log warning.
For river-bed carve, enable PolyTerrain. For open-world oceans, enable World Streaming and pair with double-precision rendering.

Minimal loop (five steps)

1 Enable the Gem
    ��?2 Confirm Settings Registry
        ��?3 Place a water body
            ��?4 Assign waves / material (+ optional buoyancy)
                ��?5 Enter play mode and verify

1. Enable the Gem

Enable Water in Project Manager (or add it to the Gem list in project.json). Restart the Editor if needed so the system and editor components mount. The Gem defaults to enabled in Settings Registry.

2. Confirm Settings Registry

Key defaults from Gems/Water/Registry/water.setreg under /O3DE/Gems/Water/:

Key	Default	Purpose
`Enabled`	`true`	Master gate for bodies, queries, and rendering
`PhysicsEnabled`	`true`	Buoyancy / `WaterPhysicsSystem`
`QualityTier`	`High`	`Low` / `Medium` / `High` GPU feature ladder
`DebugOverlayEnabled`	`false`	ImGui Water Diagnostics overlay

3. Place a water body

Viewport Create Entity �?Water, or Add Component �?Water:

Body	Component	Needs
River family	`Water Body River`	`SplineComponent` (Catmull-Rom)
Lake	`Water Body Lake`	Closed spline or `PolygonPrismShape`
Ocean	`Water Body Ocean`	Non-empty `WaterWaveAsset`

Starter prefabs ship under Gems/Water/Assets/Prefabs/Water/:

River_Default.prefab
Lake_Default.prefab
Ocean_Default.prefab

Only one WaterBody*Component per entity. Overlap between bodies is resolved by query priority (defaults: River 160, Lake 128, Ocean 64; higher wins). See Core concepts.

4. Minimal lake setup

Create Entity �?Water �?Lake; drag the closed spline along the basin contour.
Click Snap To Terrain Lowest, then raise Water Level Offset for the desired depth.
Assign waves Waves_CalmLake.waterwaves and material WaterSurface_LakeGreen.material (paths under Gems/Water/Assets/).
For floating debris: Rigid Body + Collider + Water Buoyancy on the object.

River shortcut: Create Entity �?Water �?River, set Preset to Stream / River / GreatRiver, then edit the spline and per-point Width / Depth / Flow Speed. Ocean shortcut: Create Entity �?Water �?Ocean, set Sea Level, assign a wave asset before activate.

5. Enter play mode and verify

Check	Expected
Visible surface	Refraction / reflection in the viewport; no one-shot “missing TransparentPass�?warning
Query	Probe returns `m_inWaterBodyXY = true` over the body (see query snippet below)
Buoyancy (optional)	Debris floats and settles; no launch
Sample level	Open `AutomatedTesting/Levels/WaterSamples/Lake` (or Stream / Ocean) for a known-good scene

If the surface is missing or black, jump to Debugging#troubleshooting.

Query the surface (C++ / script)

#include <Water/WaterSurfaceRequestBus.h>

Water::WaterSurfaceSample sample;
Water::WaterSurfaceRequestBus::BroadcastResult(
    sample,
    &Water::WaterSurfaceRequests::GetWaterSurfaceSample,
    worldPosD,   // AZ::Vector3d absolute world position
    Water::WaterSampleFlags::Default);

if (sample.m_inWaterBodyXY)
{
    // sample.m_surfaceHeight, m_depth, m_flowVelocity, m_entityId
}

Script / Lua / Script Canvas use the same water BehaviorContext category (GetWaterSurfaceSample, IsPointUnderwater, GetWaterTime / SetWaterTime, and enter / exit notification handlers). Full bus list: Buoyancy and gameplay and Reference.

Optional next pieces

Enable /O3DE/Gems/Water/DebugOverlayEnabled and open Water �?Water Diagnostics for mouse-pick height / depth / flow.
Bake a river Flow Map or ocean Shore Distance �?see Authoring.
Follow a full level recipe �?see Recipes.

Next steps

Core concepts �?arbitration, clock, large-world rules.
Authoring �?full field tables for River / Lake / Ocean.
Recipes �?stream→lake, estuary, open ocean.