Water debugging
This chapter covers diagnostics while authoring and shipping water: ImGui overlay, viewport helpers, Registry knobs, GPU readback hooks, and common failure modes.
Water Diagnostics overlay
Gate: /O3DE/Gems/Water/Enabled and /O3DE/Gems/Water/DebugOverlayEnabled (default false). Requires ImGui.
Menu: Water ?Water Diagnostics.
| Panel | Shows |
|---|---|
| Body table | Entity, type, priority, physics flag |
| Floater count | Active buoyancy bodies |
| Water time | Current shared clock |
| Quality | Active tier, GPU wave caps, ocean LOD caps |
| Query probe | Follow camera or Mouse pick; XYZ; surface height / depth / flow / underwater / winning body |
Use mouse pick along an estuary path to confirm surfaceHeight continuity when tuning Mouth Fade / Blend Band.
Viewport helpers (per component)
| Helper | Where | Purpose |
|---|---|---|
| Show Flow Arrows | River | Flow direction (and obstacle stamps) |
| Show Depth Heatmap | River | Bed depth visualization |
| Uphill red strip | River (Spline Z) | Downstream Z higher than upstream |
| Waves Preview | Any body | Spectrum thumbnail at t = 0 |
| Ocean validation labels | Ocean | Duplicate infinite ocean / missing waves |
Settings Registry reference
Defaults: Gems/Water/Registry/water.setreg under /O3DE/Gems/Water/.
| Key | Default | Purpose |
|---|---|---|
Enabled | true | Master gate |
PhysicsEnabled | true | Buoyancy system |
DebugOverlayEnabled | false | ImGui diagnostics |
MaxGerstnerComponents | 16 | Asset-load Gerstner cap (lower only) |
MaxActiveBodies | 64 | Soft registration cap |
MeshBuildBudgetMs | 2.0 | Per-frame mesh publish budget |
QueryCacheSlots | 256 | Query cache size |
QualityTier | High | Low / Medium / High |
PrebakeArcLengthThreshold | 512.0 | Long-river AP mesh bake threshold (m) |
Fft/Enabled | true | Spectrum ocean FFT |
Fft/Resolution | 256 | FFT grid (tier may lower) |
Fft/CascadeSizes | [512, 64, 8] | Cascade world sizes (m) |
CausticsEnabled | true | Full-screen caustics |
PlanarReflectionEnabled | true | High-tier planar reflection |
PlanarReflection/MaxWaveAmplitude | 0.1 | Reflection clip / warp budget |
PlanarReflection/Resolution | 0 | 0 = pipeline default |
UnderwaterDoF/Enabled | true | Underwater depth of field |
SmallBodyBatch/CellSize | 512.0 | Small still-pond batch cell (m) |
SmallBodyBatch/ZCellSize | 16.0 | Vertical batch cluster size (m) |
Ripples/* | see setreg | Interactive ripple pool |
Particles/* | empty paths | Optional splash / bubble / marine-snow assets |
Additional advanced keys may appear in project overrides (for example InfoMap near-cascade or SceneColorCopy full-res). Prefer documenting project-local setreg diffs when shipping.
GPU displacement readback (advanced)
Atom bridge console hooks (for golden / CI, not day-to-day art):
FrameCapture.Begin WaterGpuDisplacementReadback <x> <y> [z…]
FrameCapture.End
CVar FrameCapture.LastResult.WaterGpuDisplacement reports dx dy dz, pending, or unavailable. Used with the golden table under Gems/Water/Code/Tests/Data/water_golden_gpu_displacement.json.
Troubleshooting
| Symptom | Likely cause | What to try |
|---|---|---|
| No visible water | Missing TransparentPass / waterSurface draw list, or Gem disabled | Check log warning; confirm Enabled and pipeline |
| River floats / clips terrain | Spline Z vs terrain mismatch; no carve | Depth heatmap; Carve Terrain or brush the bed |
| No buoyancy | No rigid body; Affects Physics off; body not active in streaming cell | Enable physics; keep ocean AlwaysLoaded; verify cell residency |
| Floater launches | Too few sample points / very shallow water | Add samples; raise Linear Drag |
| Missing shore foam | Ocean shore not baked; falloff too small | Bake Shore Distance; raise Shore Fade Distance / Bank Falloff / Shoreline Falloff |
| No underwater fog | Point outside XY body; DeferredFog missing | Probe m_inWaterBodyXY; confirm DeferredFog in pipeline |
| Waves ?floater motion | Wave Sample Mode downgraded or custom time source | Use Full; sync SetWaterTime / clear time source |
| Estuary height pop | No blend / mouth fade | Set Mouth Fade Length and Blend Band ?see Recipes#estuary |
| Second ocean fails activate | Two unbounded oceans | Give extras Region Entities, or remove the duplicate |
| Transparent sorting artifacts | Cross-waterline glass / particles | Compare WaterSamples/TransparentSorting; review material opacity modes |
| FFT ocean looks Gerstner-only | Low tier or Fft/Enabled=false; non-primary Spectrum ocean | Raise tier; ensure one Spectrum ocean owns FFT |
Sample levels for isolation
| Level | Focus |
|---|---|
WaterSamples/Stream | Narrow flowing strip |
WaterSamples/Lake | Calm lake + buoyancy |
WaterSamples/Ocean | CDLOD ocean + shore |
WaterSamples/Estuary | Mouth fade + blend band |
WaterSamples/RiverNetwork | Confluences |
WaterSamples/ConcaveLake | Far LOD shore clip |
WaterSamples/RiverProfiles | Bed profile shapes |
WaterSamples/TransparentSorting | Cross-waterline transparency |
Path root: AutomatedTesting/Levels/WaterSamples/.