Getting started
Like every Pulse plugin, Pulse Water is used in four steps: Set Up, Create, Test and Check. The Pulse window (Tools > Pulse > Pulse) walks through them, and its Guide shows each step in the editor. The list at the start of each section comes from the plugin itself; the text after it goes into the details.
To see the water before you set anything up, start with Test: the plugin brings an example map.
Set Up
The Pulse window (Tools > Pulse > Pulse, tab Workflow, step Set Up) checks each of these and fixes it with a click:
- Optional: Place the ocean in the Pulse Water mode. The ocean renders the waves around the view and answers water queries, one per world. It is not replicated: place it in the level, or spawn it on the server and on every client with the same wave set. The Pulse Water mode places it and sets its waves and sea level.
- Optional: Keep agents out of the sea. The navigation mesh lies on the sea floor too, so agents walk into the sea. Block Navigation Below Sea of the ocean takes it away deeper than Navigation Block Depth below the sea level; a shore stays walkable.
- Optional: Add the Pulse Water Boat Controller Component to the Player Controller. Lets players steer a boat from its helm without possessing it; the game calls SetThrottleInput and SetRudderInput from its input.
- Optional: Add the Pulse Water Audio Component to the Player Controller. Plays the sounds of the water around the player: the open sea, surf at the nearest shore, flowing rivers, still lakes, and a low pass under water. Set the sounds in Project Settings > Pulse > Water Audio.
- Optional: Enable Landscape Patch to shape the Landscape with water bodies. Lakes and rivers shape the Landscape below them (a bed, an embankment, closed banks, paint zones) with patches of the engine plugin Landscape Patch. The patches are editor data: packaged games do not load them.
- Optional: Let the Asset Manager scan PulseWaterBoatDefinition assets. An entry in Project Settings > Game > Asset Manager > Primary Asset Types to Scan gives the assets their primary asset id (lookups by id, async loading) and lets the cook find them.
- Optional: Let the Asset Manager scan PulseWaterBoatModifier assets. An entry in Project Settings > Game > Asset Manager > Primary Asset Types to Scan gives the assets their primary asset id (lookups by id, async loading) and lets the cook find them.
- Optional: Let the Asset Manager scan PulseWaterSplashDefinition assets. An entry in Project Settings > Game > Asset Manager > Primary Asset Types to Scan gives the assets their primary asset id (lookups by id, async loading) and lets the cook find them.
- Optional: Let the Asset Manager scan PulseWaterLiquidType assets. An entry in Project Settings > Game > Asset Manager > Primary Asset Types to Scan gives the assets their primary asset id (lookups by id, async loading) and lets the cook find them.
- Optional: Connect with PulseGameplay: PulseWaterGameplayBridge. Shipyards build boats through crafting and launch them on the water; players patch leaks and repair the hull with items.
Project settings
In Project Settings > Pulse > Water:
Default Wave Set: used by every ocean without its own wave set. The plugin shipsDA_PulseWater_DefaultWaves.Max Sea State Scale: the highest sea state of the game; the automatic terrain cover band reaches above the highest wave crest at this sea state, see Terrain and caves.Default Ocean Material: a material built as described in Water materials. The plugin ships the instanceMI_PulseWater_Ocean; change the look in an instance. Changes show in the level while you edit the instance, no restart needed.Default Underwater Material: post process used near and under water (see Underwater). The plugin shipsMI_PulseWater_Underwater.Default Underwater Surface Material: ocean surface used while the view is under water. The plugin shipsMI_PulseWater_OceanUnderside.Default Lake Material,Default River Material,Default Waterfall Material,Default Fluid Material: materials of the water bodies and fluid volumes; the plugin ships instances (MI_PulseWater_*).- Terrain shaping (default profiles, paint layers, the Landscape) has a page of its own, Project Settings > Pulse > Water Terrain: see Terrain shaping.
Water Body Mask Resolution,Water Body Mask Size,Water Body Mask Margin: where the ocean hides below water bodies at about its level.Default Environment: sea state, wind and mood used when no environment provider is set.Default Liquid Type: liquid of the ocean and the water bodies that name none, see Liquids.Environment Grid Resolution,Environment Grid Cell Size,Environment Grid Refresh Per Frame: how materials see the environment, see Environment.Render Origin Snap Size,Max Gpu Waves: rendering, see Waves, time and large worlds.Wave Event Start Delay,Wave Event Cell Size,Wave Event Relevancy Distance,Wave Event Cell Idle Time,Max Cells Per Wave Event: how ring waves reach the clients, see Interaction.Quality Levels: limits per quality level, see Quality and performance.Surface Solver Iterations: precision of water queries on steep waves.Min Parallel Query Points: batches with at least this many points are split over worker threads (0 = never).Time Smoothing Speed,Time Snap Threshold: how clients follow the server’s water time.
Add an ocean
Place an APulseWaterOcean in the level or spawn it at runtime. There is one ocean per world. The ocean actor is not replicated: spawn it on the server and on every client with the same wave set and sea level. The ocean mesh follows the camera, so the actor location does not matter.
Set Up checks the level open in the editor; its fix opens the Pulse Water mode on the Ocean tool, which places the ocean and sets its waves and sea level (**Add to
Underwater effect
Every APulseWaterOcean has an Underwater Component that blends a post process material into the camera of every local player near and under the surface: fog in the color of the liquid, caustics, light shafts and a waterline. It uses Default Underwater Material from the settings (the plugin ships MI_PulseWater_Underwater); see Underwater.
To handle only one player, add a Pulse Water Underwater Component to that player’s pawn or player controller instead; there it only reacts to the locally controlled owner.
The ocean material must be one sided (see Water materials). To see the surface from below, the ocean switches its tiles to the underwater surface material while the view is under water (UnderwaterSurfaceMaterial on the ocean component, or Default Underwater Surface Material in the settings). The plugin ships MI_PulseWater_OceanUnderside, an instance of the ocean material with Two Sided turned on.
Terrain and caves
Without further setup the ocean is water everywhere below its surface, also inside islands. Tell the ocean what the terrain is, so the water ends at the coast:
- Terrain Object Types: collision object types of the terrain (
SetTerrainObjectTypes). A query has no water (bHasWaterfalse,bCoveredByTerraintrue) where terrain of these types covers the ocean (see the rule below). This works on the server too and always uses the current collision, so terrain the player digs away is taken into account. Use object types only the terrain has; otherwise e.g. a pier makes the water below it dry. - Terrain Actors: actors whose primitives are captured from above (
AddTerrainActor). The ocean material hides the water where captured terrain covers it. CallRequestTerrainUpdateafter the terrain changed.
Which terrain covers the ocean is the Terrain Cover Rule of the ocean:
- Band (default): only terrain in a band above the sea level counts, that is surfaces facing up between the top of the band and the water surface. A beach or a low rock is dry; water stays below rock arches above the band, below terrain piers and in sea caves whose rock reaches above the band. The height of the band is Terrain Cover Band: automatic (the highest wave crest of the wave set at
Max Sea State Scaleof the settings plus 0.5 m) or a fixed height (SetTerrainCoverBand). Data validation warns when a fixed band is below the highest crest. - Column: any terrain above the water surface covers it, up to
Terrain Trace Distance(the rule of Pulse Water 0.x). Caves and the space under overhangs stay dry, also a tunnel dug sideways from the sea into a cliff.
With either rule a tall island reaches above the band or the trace and does not cover the ocean. Locations inside its rock still have no water when the terrain provider knows solid ground (IsSolid): the query reports bHasWater false and bInsideTerrain true there, while open water below an overhang of the island keeps its water. The default trace provider knows no solid ground.
Queries and the material follow the same rule: the query traces from the top of the band down to the water surface, the terrain capture renders from the top of the band downwards. Both skip the undersides of terrain, so keep its collision and its material single sided (“Double Sided Geometry” off, no two sided material); otherwise the two can disagree below overhangs.
EPulseWaterQueryFlags::IgnoreTerrain skips the check for a single query.
Dry rooms below the sea level
With the Band rule a room inside a mountain below the sea level (a cellar, a tunnel, a dry cave) sees the ocean, because the rock above it reaches over the band. Place an APulseWaterExclusionVolume (a box) around the room: inside it, queries report no ocean water (Status NoWater), and where the box spans the sea level the ocean material hides the water. Water bodies in the box (a cave lake) keep their water.
Agents and the sea floor
The navigation mesh lies on any ground, also on the sea floor under the ocean, so agents walk into the sea. Turn on Block Navigation Below Sea of the ocean (category Navigation, Blueprint Set Block Navigation Below Sea): its Pulse Water Nav Blocker component puts a Null navigation area under the ocean from Navigation Block Depth (1 m by default) below the sea level down, so a shore agents wade through keeps its navigation. It is off by default. The area follows the sea level; dry caves below the sea level lose their navigation too. While the game runs the navigation mesh needs Runtime Generation Dynamic to follow a change. The optional setup step Keep agents out of the sea checks it in levels with an ocean and a Nav Mesh Bounds Volume.
Terrain provider
Queries ask a terrain provider (IPulseWaterTerrainProvider, C++) about the terrain: whether it covers the ocean at a point of the surface, the ground height below a location (WaterDepth, with EPulseWaterQueryFlags::Depth), whether the terrain at a location is loaded, and whether a location under the water surface lies inside solid terrain (IsSolid, false by default; queries there have no water, bInsideTerrain; EPulseWaterQueryFlags::IgnoreTerrain skips it). The default, UPulseWaterTraceTerrainProvider, traces against the terrain object types and is always loaded.
A world generator sets its own provider with UPulseWaterSubsystem::SetTerrainProvider and answers from its height function, which is faster than traces and needs no collision. The ocean asks it even without terrain object types. Return true from SupportsParallelSampling if it may answer from worker threads; otherwise batches stay on the game thread. Where it reports terrain that is not loaded yet, queries return the status NotLoaded: buoyancy sleeps and boats hold still until the terrain is there. Its answers must be the same on the server and every client.
Steering boats from the helm
Players who stand at the helm of a boat steer it through a Pulse Water Boat Controller component on their player controller. Add Automatically in Set Up turns on its entry in Project Settings > Pulse > Water Boats, so every player controller gets it without Blueprint changes; the game calls SetThrottleInput and SetRudderInput from its input. See Boats.
Water sounds
The Pulse Water Audio component plays the water around a player: the open sea, the surf at the nearest shore, rivers where they flow, still lakes, and a low pass under water. Add Automatically in Set Up turns on its entry in Project Settings > Pulse > Water Audio, so every player controller gets it; set your looping sounds on the same page. The plugin ships no sounds. See Audio.
Create
New assets come from Add > Pulse > Water in the content browser or New in the Pulse window:
- Wave Set (
UPulseWaterWaveSet, the main asset): The waves of an ocean, generated from a seed or edited by hand (Bake Generated Waves); set it on the ocean or as Default Wave Set. - Liquid Type (
UPulseWaterLiquidType): A kind of liquid (salt water, lava, swamp): density for floating, thickness, swimmable, damage tag and look; set it on the ocean, a water body or a zone. - Boat Definition (
UPulseWaterBoatDefinition): Mass, hull size, pontoons, drag, propulsion and rudder of a boat type. - Boat Upgrade (
UPulseWaterBoatModifier): Changes values of a boat definition: a stronger engine, a bigger sail, an armored hull. - Splash (
UPulseWaterSplashDefinition): How something splashes when it enters or leaves the water: effects and sounds, strength by speed. - Fluid Bake (
UPulseWaterFluidBakeData): The water of a fluid volume simulated once in the editor: set it as Bake Data of a Baked fluid volume, which then answers from it without simulating. - Terrain Profile (
UPulseWaterTerrainProfile): The cross-section a river bed or a lake shore gets in the ground: bed, sides and bank relative to the waterline, embankment, closed banks and paint zones; set it in Terrain Shaping of a lake or river. - Boat (Blueprint of
APulseWaterBoat): A boat pawn: set its definition, give the hull a collision mesh, put the meshes below VisualRoot and add seats. - Starter content: The sail boat and the test boat with their definitions, and two upgrades (engine, armored hull). Add Starter Content copies it to
/Game/Pulse/PulseWater.
Create a wave set
Create a Wave Set (Add > Pulse > Water > Wave Set, class UPulseWaterWaveSet). By default it generates its waves from a seed (Generator). Use Bake Generated Waves to copy them into the Waves list and edit them by hand.
Boats
A boat is a Boat Definition (mass, hull size, pontoons, drag, propulsion, rudder), a Boat Blueprint that uses it and optionally Boat Upgrades; see Setting up a boat. Splash assets describe how things splash when they enter or leave the water (Interaction), lakes, rivers and waterfalls are actors you place (Water bodies). Add > Pulse > Water > Add Starter Content copies the sail boat and the test boat with their definitions and two upgrades to /Game/Pulse/PulseWater/Boats.
Query the water
if (const UPulseWaterSubsystem* Water = UPulseWaterSubsystem::Get(this))
{
FPulseWaterQueryResult Result;
if (Water->QueryWater(GetActorLocation(), Result, EPulseWaterQueryFlags::Normal | EPulseWaterQueryFlags::Velocity))
{
const bool bUnderwater = Result.IsUnderwater();
// Result.SurfaceHeight, Result.SurfaceNormal, Result.SurfaceVelocity, Result.ImmersionDepth
}
}
Blueprints use Query Water on the subsystem. Result.Status is Water, NoWater or NotLoaded (not streamed in yet), Result.LiquidType the liquid. The flags Tags and Depth add the tags of the water and the distance down to the ground.
Query many points at once with QueryWaterBatch: from Min Parallel Query Points (64) the points are split over worker threads, with the same results as one by one (the environment and terrain providers must support parallel sampling, the default ones do). Components that query every frame can queue their points for the batch of the frame instead:
// In a pre-physics tick; AddQueryBatchPrerequisite at BeginPlay gets the results in the same frame
Water->RequestQueries(Points, EPulseWaterQueryFlags::Velocity, [this](TConstArrayView<FPulseWaterQueryResult> Results)
{
// Called on the game thread after the batch, still before the physics step
});
All queries are made on the game thread.
Test
- Play Example in the Pulse window opens
/PulseWater/Examples/LV_PulseWater_Exampleand starts Play in Editor. - Then the cheat
PulseWaterGrantgives the player what the plugin needs. - The Pulse Debugger opens on its page
PulseWater.Water. - An ocean with the default waves, the sail boat and the test boat. PulseWaterGrant puts a sail boat in front of you (“test” for the test boat), PulseWaterWave starts a ring wave; PulseWaterBoatDamage lets the boat nearest to the view take water, PulseWaterBoatInfo prints its hull, PulseWaterBoatRepair repairs it; Pulse.Water.Quality switches the quality level. The Live page of the Pulse Debugger shows the water, the boats, their hulls and the buoyancy. Two more examples: /PulseWater/Examples/River/LV_PulseWater_River, a river baked into fluid with Bake Flow and driftwood that drifts down with it (open it and press Play), and /PulseWater/Examples/Terrain/LV_PulseWater_Terrain (with Landscape Patch), a lake and its outflow shaped into a landscape. The guide First river with a bake walks through baking a river in your own level.
The example maps
The plugin brings three example maps (enable Show Plugin Content in the content browser):
/PulseWater/Examples/LV_PulseWater_Example: an ocean with the default waves, the sail boat and the test boat. Play Example for Water in the Pulse window opens it and starts Play in Editor./PulseWater/Examples/River/LV_PulseWater_River: a river through a valley with rocks, a bridge on two pillars and a weir at each end, turned into baked fluid with Bake Flow. The water flows around the rocks and the pillars; open the map and press Play: four logs of driftwood (BP_PulseWater_Driftwood) drift down with it. Its bakes lie next to it; the bake editor shows them. Baking a river walks through it./PulseWater/Examples/Terrain/LV_PulseWater_Terrain(with the engine plugin Landscape Patch): a test landscape with a lake flooded by the Lake tool and its outflow as a river, both shaped into the landscape and committed. Select the lake or the river and open the Terrain tool.
PulseWaterGrant puts a boat on the water in front of you (test for the test boat), in the middle of a river seen from its bank, where it drifts with the current. The cheat PulseWaterBoatDamage lets the boat nearest to the view take water, PulseWaterBoatInfo prints its hull and PulseWaterBoatRepair repairs it; Pulse.Water.Quality switches the quality level (see Console). The Live page of the Pulse Debugger shows the buoyancy of floating objects and boats.
Check
- Check in the Pulse window, Check All there (console
Pulse.Check) or the commandlet-run=PulseCheck -Plugins=PulseWaterchecks the setup and validates every Wave Set, Liquid Type, Boat Definition, Boat Upgrade, Splash, Fluid Bake, Terrain Profile and Boat in the project. - The plugin also runs checks of its own over the project.
Boat definitions validate themselves when they are saved; Check does it for every water asset of the project, together with the setup.
The check of the plugin looks at the fluid volumes of the open level: a bake that no longer fits the level (the ground, the obstacles, the sources and drains or the settings changed since it was baked) is a warning with the fix Bake Again, and with several of them Bake All Again; a Baked volume without a bake gets the fix Bake. The fixes bake in the background like the Fluid tool; save the bake assets afterwards. In the Pulse Water mode such volumes are marked yellow (“bake out of date”).
Console variables
| Variable | Meaning |
|---|---|
Pulse.Water.Ocean.MaxLevels | Maximum number of clipmap levels of the ocean (scalability) |
Pulse.Water.Quality | Quality level of Pulse Water, -1 (default) follows sg.EffectsQuality |
Pulse.Water.Ripples.Enable | 0 turns ripples and wakes off |
Quality and performance
Quality Levels in the project settings hold one entry per quality level, from Low to Epic. The level in use follows the effects quality of the engine scalability (sg.EffectsQuality, so the graphics settings of a game change it without extra code); Pulse.Water.Quality sets it directly. Each value of a level is a limit: it caps the setting of the components and project settings, it never raises it. The default levels are:
| Level | Ocean levels / tile quads | GPU waves | Terrain capture | Ripples | Boats simulated within | Splashes within |
|---|---|---|---|---|---|---|
| Low | 9 / 8 | 8 | 256 | 128, 30 steps/s | 80 m | 30 m |
| Medium | 10 / 12 | 16 | 512 | 256, 45 steps/s | 150 m | 50 m |
| High | 11 / 16 | 32 | 1024 | 512, 60 steps/s | 300 m | 80 m |
| Epic | no limit | no limit | no limit | no limit | always | always |
Only what a player sees is scaled. Water queries, the physics of boats the machine drives or owns, and everything the server computes are the same on every level, so players with different settings play together without corrections.
- GPU waves: the materials evaluate only the longest waves; queries still use all of them, so floating objects may differ from the visible surface by the height of the short waves.
- Boats of other players farther away than the simulation distance are not simulated on clients: they move on with the velocity of their last server update and keep their height and tilt.
- Changing the level at runtime rebuilds the ocean mesh and restarts the ripple simulation.
stat PulseWater shows the time of water queries, boat movement (simulation, collision, moving the components, replays after corrections), hulls, splash components and ripples. Unreal Insights shows the same scopes. Measured costs are on Performance.