Water core concepts

This chapter covers the ideas that every Water workflow shares: body types, overlap arbitration, the shared clock, and how queries stay aligned with rendering in large worlds.

Body family

WaterBodyComponentBase
    ├── WaterBodyRiverComponent   presets: Stream / River / GreatRiver
    ├── WaterBodyLakeComponent
    └── WaterBodyOceanComponent

Stream / River / GreatRiver share one component; Preset only resets curve defaults. Field details: Authoring.

One registry, one query surface

All bodies register with WaterBodyRegistry. Gameplay, buoyancy, camera underwater checks, and SurfaceData go through WaterSurfaceRequestBus against that registry—not ad-hoc heightfields.

WaterSurfaceSample fields:

Sample mode flags (WaterSampleFlags): Default (full Gerstner inverse), HeightOnly, StillWater, plus independent IgnoreFlow.

Overlap arbitration and blend

When several bodies cover the same XY:

1. Higher m_queryPriority wins (defaults above).
2. Ties resolve toward the higher surface.
3. If the winner’s Blend Band (m_blendPriorityBand) is > 0 and the sample is within that distance of the winner’s boundary, height / depth / flow smoothstep toward the best lower-priority body covering the same XY. 0 keeps winner-takes-all.

Estuaries usually combine:

• River Mouth Fade Length �?zeros river waves toward the mouth and damps ocean waves in a disc around the mouth;
• River Blend Band �?soft height/depth/flow transition into the ocean.

See Recipes#estuary.

Shared water clock

waterTime drives CPU queries, buoyancy, and GPU wave constants. It wraps every 3600 s (GetWaterTime / SetWaterTime on WaterSystemRequestBus). Pinning time makes screenshots and CI phase-stable.

Optional C++-only SetTimeSource / ClearTimeSource injects an external monotonic clock (replay / network). While a time source is installed, its per-tick value wins over a direct SetWaterTime.

CPU / GPU consistency

Wave math lives in AzCore-only core (WaveEvaluator, spectrum helpers). The GPU Gerstner path uses the same formulas with large-world UV folding; golden tests pin �?1 cm disagreement at 100 km. Spectrum oceans render via GPU FFT; buoyancy samples a �?6-component CPU approximation of the same spectrum (statistical alignment, not texel-identical).

Large-world rules

• Query inputs are absolute AZ::Vector3d world positions (same contract as terrain GetHeightD).
• GPU positions are render-origin-relative; origin shifts must not slide waves—keep the shared clock and do not reinvent per-body time.
• Oceans in World Streaming levels should use WorldStreamingMemberComponent with AlwaysLoaded (not spatially unloaded). Long rivers may be split across cells; use Align To Adjacent Segments / River Network to keep endpoints matched.
• At most one unbounded ocean per level. Multiple finite oceans are allowed via Region Entities.

Related systems

Next steps

• Authoring �?place and tune each body type.
• Waves and materials �?spectrum assets and quality tiers.
• Buoyancy and gameplay �?physics and script APIs.