Terrain shaping
Lakes and rivers can shape the ground they lie in: a river cuts its bed, a lake its basin, and both close their banks where the ground is too low to hold their water. Terrain Shaping on the lake or river turns it on and names a terrain profile; without one the default profile of the settings is used. The body keeps its shape: move the river and its bed moves with it.

The example map /PulseWater/Examples/Terrain/LV_PulseWater_Terrain (it needs the engine plugin Landscape Patch) shows it: a test landscape with a bowl and a valley, the bowl flooded with the Lake tool up to its overflow, the overflow traced down the valley as a river, both shaped and committed to the landscape. Select the lake or the river and open the Terrain tool to see the cross-section, the cut and the fill.
In the editor
- Place or select a lake or river. The Lake and River tools make them from the terrain: a lake in a depression, a river down the steepest slope.
- Open the Terrain tool of the Pulse Water mode. Turn on Terrain Shaping of the body in its panel and pick a profile, or keep the default one.
- Shape shapes the ground now. While Follow Changes is on, the ground follows every change of the body when the change ends, in the same undo step: drag a point of the river and its bed follows.
- Commit to Terrain writes the shape into the ground for good, Remove Shape takes it out. Each is one undo step.
The panel shows the cross-section at a station along the body, the cut and fill volume and the area that changes; the view Terrain Change colors the cut red and the fill blue. Details are in Editor mode.
Profiles
A terrain profile (UPulseWaterTerrainProfile, Create > Terrain Profile) describes:
- Points: the cross-section of one side, from the middle outwards.
Acrosscounts in half widths of the water (0 = the middle, 1 = the waterline at the bank),Heightin depths above the waterline (-1 = the full depth below it). A river scales it with the width and depth of its sections. - Embankment Angle and Max Reach: beyond the last point the ground rises at this angle until it meets the old ground, at most this far out.
- Close Banks, Freeboard, Bank Top Width: banks that are too low are filled up to the waterline plus the freeboard, so the water stays in its bed; past the top of the bank they fall off at the embankment angle.
- Wet Band Height, Sand Depth: the paint zones (bed, wet bank, bank, sand, under water) that a project maps to its terrain layers (see Paint).
A double click on a profile opens the profile editor: the cross-section on test ground (set width and depth of the river, height and slope of the ground above the plot), the ground before (dashed) and after shaping, cut red, fill blue, the water in the bed and the waterline, and below it the cut and fill per meter along the river. Drag the points of the profile in the plot (one undo step per drag); add or remove points in the details. Templates starts the profile from one of the plugin’s profiles or a config template of your own.

The plugin ships profiles for a creek, a river, a canal, a gorge, a swamp, a lake shelf and a beach in /PulseWater/Terrain/Profiles. Terrain Shaping on a body can override the embankment angle, closing the banks and the freeboard of its profile. A lake uses the embankment, the closed banks and the paint of its profile, with its own Basin Depth, Shelf Width and Shelf Depth: a shallow shelf along the shore, then down to the depth.
The rules
The rules are plain C++ in PulseWaterTerrainShaping.h (Pulse::Water::Terrain), the same for the editor and for world generators, and safe on worker threads. BuildTerrainShape of a lake or river gives its shape, FPulseWaterTerrainShape::Evaluate where it wants the ground at a location (height, cut or fill, paint zones), EvaluateShapes the ground under several shapes and ComputeVolumes the cut and fill volume of an area. A waterfall pool (FPulseWaterTerrainShape_WaterfallPool) is a bowl below a waterfall; the cliff above stays. Beyond the ends of a river its bed rises out of the ground at the embankment angle, so a source leaves no pit and a mouth into a lower sea no dam.
Several shapes shape the ground in three passes, so their order does not matter: first every cut (the lowest wins), then every fill (closed banks, the highest wins), then the water of each shape is cut once more. That keeps a lake and its outflow, a river and its tributary or a river mouth in a lake open: the closed bank of one water body never dams the water of another one, and a river builds no bank inside a lake. GetTargets gives what a shape wants without the ground (FPulseWaterTerrainTargets: cut, fill, water cut); the patches on a Landscape run the same three passes.
// The ground of a world generator under a river
FInstancedStruct shape;
if (River->BuildTerrainShape(shape))
{
const FPulseWaterTerrainSample sample = shape.Get<FPulseWaterTerrainShape>().Evaluate(FVector2D(Location), GroundHeight);
GroundHeight = sample.Height;
}
Shaping a Landscape
With the engine plugin Landscape Patch enabled (the Pulse window offers it as an optional setup step), the module PulseWaterLandscape shapes a Landscape below a lake or river without destroying it: the shape becomes texture patches on the water body, in an edit layer of their own (PulseWater, created on top of the others when it is missing). Per tile of its area (at most 512 landscape vertices per side) a water body gets one patch that lowers the ground (Min), one that raises the closed banks (Max) and one that opens its water again (Min). All water bodies run these passes in the same order, so the Landscape gets the ground of the rules above. A fourth patch paints the paint layers of the settings where the body shapes the ground. The patches are editor data on the water body: they are saved with it, come back with undo, and packaged games do not load them. Deleting the water body deletes its patches.

Commit writes the shaped ground into a normal edit layer (PulseWater Committed, right below the patch layer) and removes the patches of the body, for working on the ground by hand afterwards. Once no patch uses the patch layer anymore (all shapes committed or removed), Commit and Remove delete it too, so the level loads without Landscape Patch. In World Partition levels, and in levels with sub-levels that are not loaded, the layer stays: water bodies there may still use it.
Scripts call ShapeTerrain, RemoveTerrainShape and CommitTerrainShape of UPulseWaterEditorLibrary; each returns why it did not work (in Python only that text, empty when it worked). C++ finds the shaper of a target with Pulse::Water::Editor::FindTerrainShaper.
import unreal
lib = unreal.PulseWaterEditorLibrary
selected = unreal.get_editor_subsystem(unreal.EditorActorSubsystem).get_selected_level_actors()
river = next(actor for actor in selected if isinstance(actor, unreal.PulseWaterRiver))
error = lib.shape_terrain(river) # the ground below the river, as patches
if not str(error):
lib.commit_terrain_shape(river) # into the layer PulseWater Committed
To try it without a landscape of your own, UPulseWaterLandscapeLibrary::CreateTestLandscape places a small one, flat or from heights, with paint layers whose layer info assets go into a folder (by default next to the level, as in the Landscape mode).
Paint
The settings name a terrain layer for each paint zone of shaped ground: Bed (the bottom of deeper water), Wet Bank (the band around the waterline), Bank (the ground above the water that the shape changes), Sand (shallow water: shelves and beaches) and Under Water (all shaped ground below the waterline, e.g. a darker variant). On a Landscape these are names of its target layers; the Terrain tool offers the layers of the landscape. A zone without a layer paints nothing.
The paint patch blends its weights only where the body paints; the rest of its tile keeps what was there, also paint of other water bodies and paint by hand. The landscape material has to blend these layers (a Landscape Layer Blend of the same names) to show them; the example uses M_PulseWaterExample_Landscape with plain colors per layer. Commit writes the paint into the layer PulseWater Committed with the shape.
Other ground
A terrain shaper (IPulseWaterTerrainShaper, PulseWaterEditor) shapes one kind of ground, the Landscape one comes with the plugin. For another kind (a voxel terrain, meshes of a world generator) implement CanShape, Apply, Remove and Commit, and for the Terrain tool ReadGround (the ground below all shapes as a grid), DescribeTarget, DescribeShape and GetPaintLayerNames. Register it as a modular feature in your editor module:
IModularFeatures::Get().RegisterModularFeature(IPulseWaterTerrainShaper::GetModularFeatureName(), &MyShaper);
The Terrain tool and the library then find it for the ground below a water body. A world generator that builds its ground itself uses the rules directly (see The rules) and needs no shaper.
Limits
- Shaping a Landscape needs Landscape Patch in the editor; packaged games do not need it. Shapes that are not committed live in patches of that plugin: commit them before turning the plugin off. Without it the engine deletes the patch layer when it loads the level (with an error in the log) and the shapes are gone.
- In World Partition levels the patches load with their water body. Load the water body when you work on the landscape around it, or commit its shape.
- The patch layer and the commit layer are two edit layers of the landscape; a landscape that has the most layers it can have gets an error that says so.
- The paint of a body replaces the weights where it paints, also paint by hand below it.
Settings
Project Settings > Pulse > Water Terrain:
| Setting | Default | Description |
|---|---|---|
Default River Profile | DA_PulseWater_Profile_River | Cross-section of rivers that shape the terrain without a profile of their own. |
Default Lake Profile | DA_PulseWater_Profile_LakeShelf | Shore rules of lakes that shape the terrain without a profile of their own. |
Bed, Wet Bank, Bank, Sand, Under Water | none | Paint layer of the terrain for each paint zone; on a Landscape the name of a target layer. None paints nothing. |
Landscape Patch Layer | PulseWater | Edit layer with the patches of water bodies. |
Landscape Commit Layer | PulseWater Committed | Edit layer that Commit writes into. |
Max Patch Size | 512 | Most landscape vertices per side of one patch; larger water bodies get several. |