Water authoring
This chapter covers placing and tuning water bodies in the Editor: shared settings, River / Lake / Ocean field tables, bake buttons, Dry Volume, and River Network.
Placement entry points
| Entry | Notes |
|---|---|
| Add Component ?Water | Water Body River / Lake / Ocean, plus Buoyancy, Dry Volume, Surface Attachment, River Network |
| Create Entity ?Water | Spawns entity with default spline / shape + editor body component |
| Prefabs | Gems/Water/Assets/Prefabs/Water/River_Default, Lake_Default, Ocean_Default |
Editor components mirror runtime components and share mesh generation, so the viewport preview matches play mode.
Shared Water Body Settings
Every body exposes WaterBodyCommonConfig:
| Field | Default | Purpose |
|---|---|---|
| Waves | empty | .waterwaves asset; empty = still water |
| Waves Preview | ? | Height-field thumbnail at t = 0 |
| Max Depth | 10 m | Absorption shading + buoyancy saturation |
| Flow Speed Scale | 1.0 | Multiplies authored flow |
| Affects Physics | true | Register with buoyancy system |
| Emits Surface Tags | true | Publish water / underwater / riverbank |
| Query Priority | type default | Overlap arbitration (higher wins) |
| Blend Band | 0 m | Soft cross-body blend at boundary |
| Affected By Global Tide | true | Apply system tide offset |
Default priorities: River family 160, Lake 128, Ocean 64. Material path empty ?type default material. Wave / material details: Waves and materials.
River (Stream / River / GreatRiver)
Create
- Create Entity ?Water ?River (Catmull-Rom spline with four default points + editor river component).
- Set Preset ?resets Width / Depth / Flow Speed curve defaults (you can override per point afterward).
- Enter spline edit mode; drag / insert control points along the channel.
- Select a spline point to edit that point’s Width / Depth / Flow Speed, or use the width-disk ComponentMode manipulator.
Preset defaults
| Preset | Half-width | Depth | Flow | Waves / physics |
|---|---|---|---|---|
| Stream | ~1 m | ~0.3 m | ~1.5 m/s | Still; physics off by convention |
| River | ~8 m | ~2 m | ~1.0 m/s | Optional; physics on |
| GreatRiver | ~120 m | ~8 m | ~0.6 m/s | Small Gerstner; physics on |
River Settings
| Field | Purpose |
|---|---|
| Preset | Stream / River / GreatRiver defaults |
| Width / Depth / Flow Speed Curve | Per-spline-point half-width, bed depth, flow (m, m, m/s) |
| Bank Falloff | Shore foam / transparency falloff width (m) |
| Segment Length | Strip mesh longitudinal segment target (m) |
| Flow Map | Baked product path (read-only; use Bake Flow Map) |
| Mouth Fade Length | Estuary fade from spline end (m); 0 = off |
| Flow Obstacles | Circular stamps (arc position, lateral offset, radius, strength) that deflect flow |
| Wave Direction | Asset Wind / Perpendicular To Flow / Blend |
| Bed Profile | Parabolic / Trapezoid / Power Curve lateral depth shape |
| Bed Flat Fraction | Trapezoid only: fraction of half-width at full depth |
| Bed Power Exponent | Power Curve only: exponent e in `depth*(1- |
| Elevation Mode | Spline Z (default) or Terrain Snap |
| Terrain Sink Offset | TerrainSnap: surface sits this far below sampled terrain (m) |
Spline Z uphill segments (downstream Z higher than upstream) show a red viewport warning. Saving is allowed (falls / cascades).
Editor groups and buttons
| Group / button | Action |
|---|---|
| Bake Flow Map | Writes Assets/WaterBakes/FlowMap_<entityId>_lutrgba8.png and binds it for dual-phase normal scroll |
| Clear Flow Map | Removes the bake binding |
| Align To Adjacent Segments | Snaps end vertices / Width / Depth / Flow Speed to the nearest other river endpoint within Match Distance |
| Generate Audio Emitters | Spawns Audio Trigger child entities along the spline (repeat clears previous; single undo) |
| Carve Terrain / Update Carve / Remove Carve | PolyTerrain V-ditch or flat bed (edit-time only; single max width/depth profile for the whole spline) |
| Show Flow Arrows / Show Depth Heatmap | Viewport helpers |
Long rivers over PrebakeArcLengthThreshold (default 512 m) get AssetProcessor 3-LOD mesh products for faster activate.
Lake
Create
- Create Entity ?Water ?Lake (closed Catmull-Rom, ~8-point circle by default).
- Drag points along the basin contour (XY projection; water level is entity Z + offset).
- Click Snap To Terrain Lowest, then raise Water Level Offset for depth.
- Optional: Trace Shoreline (marching-squares contour ?simplified spline vertices in one undo).
Needs a closed spline or PolygonPrismShape on the same entity.
Lake Settings
| Field | Purpose |
|---|---|
| Water Level Offset | Level relative to entity Z (m) |
| Uniform Depth | Depth when no terrain depth is available (m) |
| Shoreline Falloff | Foam / transparency falloff (m) |
| Mesh Cell Size | Fill mesh cell size (m) |
| Excluded Regions | Closed-spline or polygon entities carved as islands |
| Exclusion Fade Band | Soft query fade near island edges before hard miss (0 = hard edge) |
| Far LOD Area Threshold | Boundary area (km²) above which deep interior uses CDLOD far patches; ?0 disables |
| Far LOD Shore Band | Detailed fill band width from shoreline once far LOD is active (m) |
| Far LOD Shore Clip | Discard far-patch pixels past the shoreline using a coarse shore-distance grid |
Ocean
Create
- Create Entity ?Water ?Ocean. Entity XY is not critical for rendering (camera-centered grid); Sea Level is absolute double-precision world Z.
- Assign a non-empty wave asset before activate (validation error otherwise).
- At most one unbounded ocean (empty Region Entities). Additional oceans need Region Entities (closed spline / polygon union).
- For World Streaming: add
WorldStreamingMemberComponent, keep AlwaysLoaded.
Ocean Settings
| Field | Purpose |
|---|---|
| Sea Level | Absolute world Z (m) |
| Grid Extent | Camera-centered coverage radius (default 8192 m) |
| LOD Levels | CDLOD subdivision levels (default 6; quality tier may lower) |
| Shore Fade Distance | Wave amplitude fade band from shoreline (m) |
| Shore Bake Extent | Bake footprint edge length around the entity (m) |
| Shore Bake Resolution | Bake grid texels per side |
| Region Entities | Finite-domain rings; empty = infinite |
Shore Distance bake
| Button | Action |
|---|---|
| Bake Shore Distance | Signed chamfer shore grid serialized onto the component (m_shoreGrid); drives foam + amplitude fade |
| Clear Shore | Clears the baked grid |
Without a bake, runtime falls back to a coarse terrain-derived estimate when terrain is present.
Dry Volume
Water Dry Volume places an oriented box that excludes surface queries (cabins, glass tunnels, underwater rooms). Camera underwater checks, buoyancy, and gameplay all honor the exclusion.
| Field | Purpose |
|---|---|
| Dimensions | Full box size in entity-local units (a sibling Box Shape overrides these) |
River Network
Water River Network holds a confluence graph for tributaries:
| Field | Purpose |
|---|---|
| River Segments | Participating river entity IDs |
| Junctions | Upstream river + Downstream river + Blend Fade Length |
Each junction treats the upstream spline end as merging into the downstream course; blend fade recovers waves/flow beyond the solved disc. Editor Align Network can help sync endpoint parameters. Sample: AutomatedTesting/Levels/WaterSamples/RiverNetwork.
Baking summary
| Bake | Where | Output |
|---|---|---|
| Flow map | River Bake Flow Map | PNG under Assets/WaterBakes/ + config path |
| Shore distance | Ocean Bake Shore Distance | Serialized m_shoreGrid on the ocean |
| Long river mesh | AssetProcessor (PrebakeArcLengthThreshold 512 m) | 3-LOD model products |
After changing Flow Obstacles, re-bake the flow map so GPU scrolling matches CPU analytic deflection.
Next steps
- Waves and materials ?assign spectra and materials.
- Recipes ?end-to-end stream, lake, ocean, estuary setups.
- Debugging ?probes and viewport helpers while authoring.