Fluid simulation

A fluid volume simulates water in an area: it flows, fills basins, runs around rocks and falls over edges. It is a 2.5D shallow water simulation: every cell of a grid has a water height and a flow velocity. That covers what water does on a surface (flowing, filling, flooding, draining), not overhangs or water above water. The fluid is a water body: buoyancy, boats, splashes and Mass see it through the normal water queries. In the editor the Fluid tool of the Pulse Water mode places a volume, lists its obstacles and simulates it.

Class Purpose
APulseWaterFluidVolume The fluid in a box: domain, water body and surface mesh.
UPulseWaterFluidDomainComponent The area (a box turned around Z only), its grid and the simulation.
UPulseWaterFluidBody Answers the water queries from the grid and shows the wet cells.
UPulseWaterFluidSourceComponent Brings water: an amount per second, a fixed level or rain.
UPulseWaterFluidDrainComponent Takes water: an amount per second or seeping into the ground.
UPulseWaterFluidObstacleComponent Changes how an actor counts as an obstacle.
UPulseWaterFluidBakeData A bake: the water of a domain simulated once in the editor (Add > Pulse > Water > Fluid Bake).

The domain

  • The box of the volume is the area; it may be turned around Z. CellSize (default 50 cm) sets the grid: half the size gives four times the cells and costs four times as much.
  • RebuildGrid builds the grid: it finds the ground and the obstacles from above (see below), reads the sources and drains in the box, and sets the water of StartState: Empty, or Fill To Level up to FillLevel (world Z), at rest. A volume builds its grid when play begins.
  • Simulate(DeltaTime) advances the water, ResetWater puts it back to the start state, GetWaterVolume gives the water in liters.
  • LiquidType: the liquid of the water; its viscosity slows the flow (lava creeps).
  • Tier: where the simulation runs. A Baked domain answers the queries from its bake (see Bakes), queries leave out a Visual domain (it is only for the look), and a Gameplay domain answers them from its grid.
  • StartState From Bake starts the water of the grid with the first frame of BakeData (a calm reservoir whose dam breaks in the game).

Sides

Every side of the box (Front (+X), Back (-X), Right (+Y), Left (-Y)) is one of:

Side What happens
Wall Nothing flows through (default).
Fixed Level Water outside stands at Level (world Z), like an ocean or a lake next to the domain. It flows in where the inside is lower and out where it is higher.
Outflow Water falls out as over an edge (a free overfall); nothing flows in. For a river that goes on after the domain, a fixed level at the height of its water is closer.

A Fixed Level side next to the ocean or a lake at about that level (MaxBlendLevelDifference) blends into it: within BlendDistance of the fluid body (500 cm, at most half the domain) the surface goes over into the level and the waves of the other water, in the queries and in the material alike, so a stream flows into the sea without a seam. The ocean hides below the wet cells of the domain, as below lakes and rivers.

Ground and obstacles

RebuildGrid traces every cell from above against ObstacleObjectTypes (default world static and world dynamic):

  • The ground is the terrain below: the height of the terrain provider if the game set one, otherwise the lowest surface the traces hit.
  • An object that stands on the ground (its underside at most ObstacleGroundGap above it, default 50 cm) raises the ground to its top: rocks, pillars, steps. Water flows over it once it is high enough.
  • An object that reaches above the box is a wall.
  • Objects higher up (bridge decks, overhangs, branches) do not count: the water flows underneath.
  • UPulseWaterFluidObstacleComponent on an actor changes the rule: Ignore (never an obstacle, e.g. a low bridge deck or plants) or Solid (a wall wherever it stands; its bounds count, also without collision).

Rebuild the grid after obstacles moved; moving the volume in the editor, undo and changes in its details panel rebuild it on their own. GetObstacles lists the actors above the ground with what they are for the water in how many cells (ground, wall, overhang, ignored), most cells first: the obstacle list of the Fluid tool.

Sources and drains

Put the components on any actor in the box (in the editor they show as a sprite). They cover the cells within Radius (at least the cell below them); bActive switches them. The domain reads them in RebuildGrid; RefreshSourcesAndDrains reads them again and keeps the water (the Fluid tool calls it when one is placed, moved or changed).

Component Mode What it does
Source Rate Rate liters per second (a small spring 1, a stream 100, a river 10,000 and more).
Source Fixed Level Keeps the water at least at the height of the component (an inflow from a lake).
Source Rain RainRate millimeters per hour, with a radius of 0 over the whole domain.
Drain Rate At most Rate liters per second.
Drain Infiltration InfiltrationRate millimeters per hour into the ground, with a radius of 0 over the whole domain.

Rivers

Bake Flow of the Fluid tool places fluid volumes along a river: boxes turned along it, each at most a given length and wide enough for the river and its bends, the upstream and downstream sides at a fixed level of the river there, Tier Baked and the body one Priority above the river, so they answer where they overlap it. It bakes each of them; the surface of the river can hide. A long river becomes several volumes, each with a bake of its own, so World Partition streams them like other actors. The example map /PulseWater/Examples/River/LV_PulseWater_River shows it: a river of 48 m with rocks, a bridge and a weir at each end, in two baked fluid volumes. Baking a river walks through it.

Bakes

A bake keeps the water of a domain simulated once in the editor. A Baked domain with a bake answers its queries from it: nothing is simulated in the game, there is no tick and no network traffic, and every machine has the same water because it is an asset. Make it with Bake in the Fluid tool: it runs in the background and keeps what the timeline of the tool shows.

Kind Keeps Played
Stationary One state of the water Always the same; the material moves the surface along the flow. Rivers, streams, pools.
Loop Frames of a flow that repeats over LoopDuration By the water time, blending between the frames; the end flows into the start. Eddies, whirlpools.
  • Per cell a bake keeps the water depth, the flow and the foam of every frame, and the ground and the obstacles once, as half floats: the same values for the queries and for the material.
  • InputHash is a hash of what the bake depends on (ground, obstacles, sources and drains, the settings of the solver and the start state). IsBakeOutOfDate compares it with the level as it is now (ComputeCurrentInputHash traces a grid of its own and leaves the grid and the water of the domain alone; ComputeBakeInputHash hashes the grid the domain has). The Pulse Water mode marks such volumes yellow and the Pulse Check reports them with a fix that bakes again.
  • Simulate makes a Baked domain show its live water instead (for a preview), ShowBake switches back; UsesBake says which one the queries read.
  • The data validation reports an empty bake, data that does not fit together, and bakes above 256 MB.
  • Settings (FPulseWaterFluidBakeSettings) says how it was made: Stationary with the second of simulation it keeps (Time, 0 once the water settled), or Loop from LoopStart to LoopEnd with FramesPerSecond (60 divided by a whole number) and BlendFrames. Report keeps what the bake found: when the water settled and the seam of a loop (how much its end differs from its start before blending, in cm and as a part of the depth).
  • Settled means that the means of the water heights over a second agree two seconds in a row: the cells with water change by at most 5 mm on average and the volume by at most 0.2 % (Pulse::Water::Fluid::FSettleCheck). The eddies behind the rocks of a settled river keep moving; a pool that still fills does not settle.
  • From C++: UPulseWaterFluidDomainComponent::MakeSimulation copies the grid of the domain at its start state with its settings and fixed levels (Pulse::Water::Fluid::FSimulation); it steps like Simulate, also on a worker thread. Pulse::Water::Fluid::RunBake simulates it in steps of 1/60 s (StepTime) and records the frames into a FPulseWaterFluidBakeBuilder (plain data), and TakeBake hands that to the asset on the game thread. By hand: BeginBake with the grid of the domain, AddFrame once (Stationary) or for every frame of a loop plus its blend frames (recorded after its end and blended into its start), then FinishBake.
  • GetSimulatedTime of the domain counts the seconds its live water was simulated since the start state, SetBakeData sets the bake without touching the live water.

Bake editor

A double click on a bake asset opens the bake editor:

  • Preview: the water of the bake over its ground, in the space of the domain; obstacles stand as walls. Depth, Flow and Foam color the water, the corner of the preview says how. A loop plays on the timeline below it: play, step frame by frame, scrub, speeds from 0.25 to 4; the status says which frame shows. A stationary bake has one frame and no timeline.
  • Statistics: the resolution and size; the length (frames, frames per second and the span it simulated, or the second a stationary bake keeps); the memory as half floats next to what the same data would need as 32-bit floats; how much of the area has water; when the water settled; the seam of a loop; when it was baked; and which fluid volumes of the open level use it, marked “out of date” where they changed since.
  • Validation: the data validation of the bake and every volume of the open level that uses it but changed since, with Bake Again. A click on such a volume selects it in the level.
  • Notes of the author (kept in the package, not cooked) and the Details of the asset.

Baking a volume again while its bake is open shows the new bake.

Queries and the surface

The fluid body answers the water queries where the grid has water: the surface between the cell centers (bilinear over the wet cells), the flow velocity and a normal from the slope of the surface. Where at least half of the weight lies on dry cells there is no water, so the shore runs half way between wet and dry cells. Locations from a little below the ground up to MaxHeightAbove above the surface belong to it.

The surface

The surface mesh has a vertex in the middle of every wet cell; along the sides of the box the vertices sit on the side, so the water covers the whole box and volumes side by side (Bake Flow) meet without a gap. A baked volume is drawn from its bake by MI_PulseWater_Fluid (master M_PulseWater_Fluid, Default Fluid Material in the project settings, see Water materials; edits of it show in the editor right away):

  • The bake keeps its frames as textures, one RGBA16F texel per cell with depth, flow and foam (GetFrameTexture), the values the queries read.
  • Every frame the body gives the material the two frames around the water time and how far between them (GetFrameBlend), the same frames the queries blend. The mesh covers every cell with water in any frame; the material lifts its vertices to the water of now and sinks cells without water below the ground. So a loop plays without building the mesh again.
  • Flow and foam come per pixel from the textures; detail waves (FluidDetailStrength, FluidDetailScale) and foam patches flow with them.
  • A baked volume shows its bake as soon as the level is loaded, also in the editor.

While the domain simulates, the mesh follows at most every MeshRefreshInterval seconds (default 0.1) and the material shows the flow and foam of its vertices; the queries always read the grid itself.

The simulation

The solver runs the shallow water equations on a staggered grid (heights in the cells, velocities on their edges):

  • Volume: water only moves between cells, so a closed basin keeps its water exactly; sources, drains and the sides add and take what they say.
  • Rest: a lake at rest stays at rest, also next to a dry shore and over a sloped ground.
  • Fronts: floods, dam breaks and bores move at the right speed. Advection (advanced) picks how the flow carries its velocity: Momentum Conserving (default), or Semi Lagrangian and MacCormack, which keep eddies behind rocks sharper in calm water but let fronts over dry ground crawl.
  • Cliffs: water falls over an edge driven by its own depth, not by the height of the drop, so cliffs and walls do not make the simulation explode.
  • Same everywhere: every run and every number of threads gives the same result.
  • BedFriction slows thin water most (about 0.003 for a river bed), MaxVelocity limits the flow. Foam forms where the flow is fast or hits an obstacle and moves with the water.

Timings are on the Performance page.


This site uses Just the Docs, a documentation theme for Jekyll.