Water bodies
Besides the endless ocean, a world can have lakes, rivers and waterfalls. Lakes and rivers are water bodies: they have their own water level, are part of every water query and work with everything that uses the queries (buoyancy, boats, splashes, ripples, Mass, the underwater effect). Waterfalls are visual and connect two water bodies.
All of them are splines, so they can be shaped in the editor or created at runtime by a world generator.
| Class | Purpose |
|---|---|
APulseWaterLake / UPulseWaterLakeComponent | Lake, pond or cave water with one water level. |
APulseWaterRiver / UPulseWaterRiverComponent | River or stream with width, depth and flow per spline point. |
APulseWaterfall | Falling water between a river and the water below, with optional Niagara effects. |
UPulseWaterBodyComponent | Base of the water bodies, for your own kinds of water. |
Lakes
- The actor’s Z is the water level. The spline points only give the outline (closed loop), their Z is ignored.
- The lake shows the waves of the wave set, scaled by
WaveScale(default 0.2) and by the sea state of the environment, in queries and in the material alike. Depth: how deep the water is. Locations below the bottom belong to other water (a cave lake further down).LiquidTypeandWaterTags: what the water is and how queries tag it, see Liquids (lakes and rivers).- The surface is a grid mesh (
MeshCellSize, at mostMaxMeshCellscells) that reaches a little under the shore, so the terrain hides its edge. - Runtime:
SetOutline(WorldPoints). - In the editor the Lake tool floods a depression of the terrain and creates the lake with an outline that follows the shore.
Caves. A lake may lie below the sea level, inside an island, and gives the cave its own water level: queries ask the water bodies before the ocean. A dry cave below the sea level gets an exclusion volume, see Dry rooms below the sea level.
Rivers
- The spline runs along the middle of the water surface from the source to the mouth; the surface follows its height.
Sectionsholds the width, depth and flow speed per spline point (DefaultSectionfor points without an entry).Width Of All Sectionsin the details panel (orSetAllSectionWidths) sets the width of all of them at once.- The flow is the surface velocity of the water queries: it follows the slope and is slower near the banks (
BankSlowdown). Boats, buoyant objects and Mass entities drift with it without extra code. - Rivers have no waves in the queries; the material carries detail waves along with the flow and shows patches of white water where the river is fast (
RapidsSpeed) or steep (from about 6 degrees on). - Runtime:
SetPath(Points)with location and section per point. - In the editor the River tool traces a river from a source down the terrain, suggests waterfalls at steep steps and paints width, depth and speed along a river.
Waterfalls
APulseWaterfall is a sheet of falling water along its spline, from the lip down to the pool. It does not answer water queries; the river above and the lake or river below do. Set Width and FallSpeed, and optionally TopEffect / BottomEffect (Niagara systems at both ends). At the bottom it keeps the surface rippling (RippleStrength) and leaves wake foam (Foam).
Blending into other water
Where water bodies meet other water at a similar level, they blend into it instead of ending with a hard edge:
- Rivers blend into the lakes and the open sea they flow into or come out of. Where the middle of a river lies in a lake or the open sea (calm levels at most
MaxBlendLevelDifferenceapart, default 3 m), the river is that water; before that it blends in overBlendDistance(default 15 m). Inside a lake the river has no mesh, the lake shows the surface. A river that ends above a waterfall keeps its own surface. - Lakes blend into the open sea along the parts of their shore where the sea lies right outside at about the same level (lagoons).
- Rivers do not blend into other rivers and lakes not into rivers or lakes, so two bodies never blend into each other. Where rivers meet,
Prioritydecides which one shows.
In the blend zone the surface moves to the calm level of the other water plus the waves of the wave set with its wave scale. Water queries and materials compute exactly the same, so floating objects and boats cross the transition without a step. bBlendWithOtherWater turns blending off for a body.
The ocean hides below water bodies at about its level (the water body mask, Water Body Mask Resolution, Water Body Mask Size, Water Body Mask Margin): around lagoons and river mouths it neither shows through nor overlaps their edges. The mask is rasterized from the shapes of the bodies around the view.
Where the blending goes depends on where the open sea is, which depends on the terrain: APulseWaterOcean::RequestTerrainUpdate (call it when terrain was added or changed) also rebuilds the blending of all water bodies (UPulseWaterSubsystem::RefreshWaterBodies).
Which water answers a query
Water queries ask the water bodies at the location first and use the ocean only where no body claims it:
- A body claims a location inside its shape, between its bottom and
MaxHeightAboveabove its surface. - If the location is under the surface of a body, that body wins (the water it is in). Otherwise the highest surface below the location wins (the water it would fall into).
Prioritydecides between overlapping bodies, e.g. where a river flows into a lake.
FPulseWaterQueryResult::WaterBody tells which body answered (nullptr for the ocean).
Water bodies are part of the queries, so they must be the same on the server and on every client: place them in the level, or spawn them on every machine from the same data (e.g. the seed of a generated world).
Materials
The project settings name the default materials (Default Lake Material, Default River Material, Default Waterfall Material); each body can use its own (SurfaceMaterial, Material on the waterfall). The plugin ships the instances MI_PulseWater_Lake, MI_PulseWater_River and MI_PulseWater_Waterfall: change a look there, the masters only combine the material functions (see Water materials). Lakes use MF_PulseWater_LakeVertex and MF_PulseWater_LakePixel, rivers MF_PulseWater_RiverVertex and MF_PulseWater_RiverPixel (HLSL in /Plugin/PulseWater/Private/PulseWaterBody.ush). Body materials get the same parameters as the ocean plus PW_BodyWaveScale and PW_BodyCellSize. Edits of a body material in the editor show on the bodies right away (see live tuning). River meshes carry the flow velocity in UV channel 1 and the white water amount in UV channel 2 (X); the functions blend the surface into the water it touches (UV 2 Y, UV 3).
Lake and river surfaces are one sided: seen from below (under water) only the underwater post process shows.
Terrain shaping
Lakes and rivers can shape the ground they lie in: a river cuts its bed, a lake its basin, with profiles for the cross-section and on a Landscape as patches that follow the water body. See Terrain shaping.
Your own water bodies
Derive from UPulseWaterBodyComponent and implement QueryBody (answer for a location), GetQueryBounds (areas for the lookup), BuildSurfaceMeshAt and RebuildQueryData. Call RefreshShape when the shape changes. A simulated fluid could be such a body: it only has to answer queries from its own data.
BuildSurfaceMeshAt runs on a worker thread: read only the data the body derives in RebuildQueryData and RebuildBlendData (it does not change while a build runs) and the transform that is passed in, never GetComponentTransform or other components. To hide the ocean below the body at about its level, also implement RasterizeFootprint and MakeFootprintRasterizer (the same rasterization on copies of your data, for the background task of the body mask).
Building the surface in the background
Bodies build their surface mesh in a background task: the old mesh stays visible until the new one is applied on the game thread, a frame or two later. A lake of 1 km takes over 100 ms to build, the game thread only spends a few milliseconds on the rest of the refresh (see Performance). When the mesh must be there right away, for example before it is baked or captured, call FlushSurfaceMesh (Blueprint: Flush Surface Mesh).