ByteFoundry
VoxelWater

Unreal Engine plugin · Above and below ground · Multiplayer water

Dig it. Dam it. The water follows.

VoxelWater is an Unreal Engine plugin for games built on Voxel Plugin 2 terrain. It tracks how much water there is and where it is, so it fills hollows and caves, runs through tunnels, spills over edges and finds a new way down when players dig a channel, build a dam or knock one out, though for now some dams still leak through or underneath. The server runs the water and sends each player a compact copy of the water near them. Shared digging and filling now work in our network tests, on small levels.

See it runningIn development · Where it's at

Built on · Required

Two things you'll need first.

VoxelWater doesn't work on its own. Every project that uses it needs three third-party products, and two of them you get separately, from their own makers.

Where VoxelWater sits Layers from top to bottom: your game; VoxelWater, the water simulation; three required pieces side by side, Voxel Plugin 2 for the terrain, FluidNinja LIVE-2 for the look up close and UnrealJolt for physics; and Unreal Engine on Windows at the base. Your game VoxelWater the water simulation, the ledger and multiplayer Voxel Plugin 2FluidNinja LIVE-2UnrealJolt the terrainthe look up closephysics REQUIRED · SEPARATEREQUIRED · SEPARATEREQUIRED Unreal Engine 5.8 · Windows

Voxel Plugin 2 the terrain

A forested mountain landscape built with Voxel Plugin 2, seen in the Unreal editor viewport.From the maker
Voxel Plugin example shapes: a dome and a rock arch with a hole right through it.From the maker
The Unreal editor with a Voxel Plugin stamp selected over a forest, and the stamp types Mesh, Spline, Graph and Sculpt in the details panel.From the maker
A forested world, example shapes with an arch you can see through, and terrain stamps in the editor. Images: Voxel Plugin documentation.

Fully 3D terrain for Unreal: hills and mountains, but also caves, overhangs and arches, shaped with stamps and graphs, and editable while the game runs, though its makers call that feature experimental. It's the ground players dig, build on and tunnel through. VoxelWater picks up the stamps players dig and fill with, and the water reacts on the next step. Sculpt-brush edits aren't supported.

We build against its development branch, which carries no version number, so we'll name the build we tested with.

FluidNinja LIVE-2 the look up close

Waves breaking on a sandy beach while a mannequin walks along the shore, rendered with FluidNinja LIVE-2.From the maker
Shallow water spreading over a rocky landscape and filling the gaps between boulders.From the maker
A figure on a red beam above a swirling ring of clouds, seen from high altitude.From the maker
Surf from the maker's 4K render test, water filling the gaps on a rocky landscape, and clouds from the playable beta. Images: Andras Ketzer, from FluidNinja LIVE-2 videos; the landscape shot via 80.lv.

A real-time fluid effects system for Unreal: water, smoke, clouds, fire, sand and snow. In VoxelWater, our simulation drives it with the water's own speed and direction, so the surface near the player moves with the flow. Where it doesn't reach, such as caves and falls, VoxelWater draws its own surface. For now, players who join a host or server see water only to about 32 m.

It's content you add to your project, not a plugin, and it isn't included. See its maker's page.

UnrealJolt, for physics, is required too. The plan is to ship a prebuilt copy inside the plugin package, so you won't have to build it yourself.

Painted concept: two people with shovels have cut a channel across a green hillside, and a creek now pours into it while the old bed behind a dam of dug earth drains to puddles. Concept art
The idea, painted. Cut a channel, block the old bed, and the creek takes the new route. This is generated concept art, not a game capture. The real engine captures are below.

What the water does

Water that's kept, not faked.

In many games, water is a flat plane at a fixed height. VoxelWater tracks how much water there is and where it is, so terrain changes have real consequences. All of this runs in our development project today, on small test levels.

01 / VOLUME

It keeps its volume

Water lives in half-metre cells, and each cell knows how much it holds. Every move is a transfer from one place to another, and a ledger keeps track of the total every step, through digging and other terrain edits.

02 / DIGGING

Dig, and it reacts

Terrain edits reach the water on the very next step. Cut a trench across a running creek and it fills, taking most of the stream. Dig under deep water and the trapped air escapes gradually as water takes its place.

03 / LEVELS

It finds its level

Pour into a basin and it becomes one lake. A U-bend evens out. A waterfall joins two pools without merging them. A sealed air pocket holds until someone digs a vent. Seven scenarios like these pass in the dev project.

04 / DAMS

Dams drain through the hole

A breach lets water out at a rate set by the hole, not all at once. Even with our 80,000-litre test dam removed in one go, the flow peaked near 9,400 litres a second. A one-cell hole starts close to what a textbook orifice would give.

05 / FLOODS

Floods that look like floods

A separate flood layer on the graphics card draws dam breaks and jets as a moving sheet of water, with FluidNinja adding surface detail near the player. It's there for looks. The gameplay water underneath carries on unchanged.

06 / MULTIPLAYER

Run by the server, shared with players

The server or listen host runs the water. Each player gets a compact copy of the water near them: about 2.5 KB a second on our creek test. Shared digs and fills have been tested with a dedicated server and two players, including a player joining later, with packet loss and lag. The server doesn't need a graphics card.

Underground

The water goes underground too.

Voxel Plugin 2 terrain is fully 3D, with caves, tunnels and overhangs, so VoxelWater's cells are 3D as well. Water runs down a shaft, fills a cave from the floor up and pools under rock. It also knows when air is trapped with nowhere to go. A flat plane at a fixed height can't do any of that.

Painted concept: a block of world cut away like a slice of cake, with rivers and a lake on top and caves, a flooded mine tunnel, an underground river and a lamp-lit dry cave with a miner in the rock below. Concept art
The idea, cut open. Rivers on top, and water in the rock below them: caves, flooded workings and a river underground. Generated concept art, not a capture. What works today, on small test levels, is below.
Cutaway of a test level: a lake sits in a basin on rock, above an empty, sealed cave. In engine · cutaway
1. It holds. A lake of about 54 m³ sits on rock above a sealed cave. The cave is full of air with no way out, so it stays dry.
The same cutaway after a vent is dug through the cave roof: a column of water pours from the lake into the cave and a pool forms on the cave floor. In engine · cutaway
2. Dig a vent. A hole about 1.5 m across through the roof lets the air out, and the lake pours in as it goes.
The same cutaway a few seconds later: the cave below is full of water and the lake basin above is nearly empty. In engine · cutaway
3. The lake moves down. About six seconds of game time later, the cave is full and only a shallow layer is left in the lake's basin.
Cutaway of a test level: a pond feeds a shaft down into a flooded chamber, and a newly dug round cavity on the chamber's left side is still full of air. In engine · cutaway
Dig beside a flooded chamber. The new cavity on the left starts as trapped air; the water then replaces it.
Cutaway of a U-shaped tunnel: the water stands high in the right-hand shaft and low in the left, with a round rock plug in the bend between them. In engine · cutaway
A U-bend, before. A rock plug in the bend holds one side high.
The same U-shaped tunnel after the water settles: both shafts hold water at the same level. In engine · cutaway
After. With the plug gone, both shafts settle to one level.

Cutaways of small test levels with placeholder terrain and an early surface look. The camera sits inside the rock and the water is clipped so you can see in.

01 / CAVES

Caves and tunnels fill

Water flows down shafts and through tunnels and fills caves from the floor up, the same way it fills a lake. Connected chambers settle to one level.

02 / TRAPPED AIR

Air that has nowhere to go

A sealed pocket of air holds back the water above it. Dig a vent, or any path up, and the air gets out as the water takes its place. There are no drawn bubbles yet; the water simply moves in.

03 / DIGGING IN

Break into a flooded chamber

Dig into rock beside or below flooded space and the new hole starts as trapped air, then floods. It needs at least half a metre of water above it; a shallower dig just fills.

04 / LEVELS

Shafts that even out

Water in two shafts joined at the bottom settles to one shared level. A fall from a higher pool to a lower one joins them without merging the two. The water levels out rather than sloshing.

05 / DRAWN BELOW

Drawn where FluidNinja can't reach

FluidNinja draws open-sky water. In caves, down falls and over trapped air, VoxelWater draws its own surface, and it's on in the game look, not only in debug views. There's no underwater effect yet, and the water doesn't cast shadows yet.

06 / HOW DEEP

Small and shallow, for now

One water area is a box up to 256 m on a side, and digging can grow it. The cave tests with real terrain are a few metres deep; a test of the water alone ran a lake 256 m deep. Players who join see water within about 32 m.

Underground, planned

  • Groundwater and a water table under the map-wide world, with aquifers a dig can break into
  • Springs fed from below. Springs and drains a designer places already work.
  • Pipes, with narrow tunnels treated as pipes
  • Cave mouths that join caves to the map-wide rivers and lakes
  • Underground rivers through cave networks
  • Pumps and buckets for players to move water themselves
Painted concept: looking down a timbered mine shaft as water breaks in from a side tunnel and rises, with air bubbling up, while two players with lamps watch from a platform. Concept art · planned
A mine floods from below. The pieces work on test levels: flooded digs and trapped air. A full mine with pumps hasn't been built, and we don't draw air bubbles.

In the engine today

Real captures, small test levels.

Everything in this section was recorded in our development project in Unreal Engine. The terrain and props are test-level placeholders; the water is the plugin, with FluidNinja adding the close-up surface in most shots. Moving pictures were rendered frame by frame, so they show the look, not a live frame rate.

Moving capture: with the test dam removed, the reservoir pours into a dug channel and the white falling sheet fades away. In engine · moving
A dam break, end of the event. The reservoir pours out where the dam stood and down the dug channel while the flood layer fades out. A separate effect draws the falling water; the flood layer and FluidNinja draw the run-out.
A test dam one second after it was removed: a white falling sheet of water and spray drops into the channel below. In engine
One second in. The dam is gone and the first sheet of water drops into the channel.
A single hole dug through the base of an earth dam, with water jetting through it into a channel. In engine
One hole, one jet. Dig through the base of the dam and the water comes out through the hole, at a rate the hole allows.
Wide view one second in: a small reservoir at the top of a dug channel, its water just starting down it. Wide view two seconds later: the released water runs most of the length of the channel. In engine · 1 s and 3 s
Two seconds apart. Left, one second in, the water has just started down the channel. Right, it runs most of the length.
Moving capture at player height: a creek flows away from the camera down a dug channel, its surface rippling with the flow. In engine · moving
The surface follows the flow. The ripples are moved by the simulation's own speed and direction, not scrolled at a fixed rate.
Top-down view of the test dam break: the reservoir on the left, white water where the dam stood, and water running right. In engine
From above. The reservoir, the fall where the dam stood and the run-out in one frame.
A trench dug off a running creek fills with water, taking most of the stream from the creek below it. In engine · earlier look
Dig across a creek. The new trench fills and takes most of the stream. Captured before the current surface look.
A raised stone pool spills a thin waterfall into a lower pool; each pool holds its own level. In engine · earlier look
Two pools, two levels. The upper pool spills into the lower one without the two becoming one lake.
Host view: a creek running down a grey chequered test slope, with player mannequins standing beside it. Player view of the same creek, drawn from the copy the host sent; its water covers the same channel. In engine · host and player
Same water, host and player. Left, the listen host that runs the water. Right, a connected player drawing the copy it was sent. An early test level and an earlier look.

How it works

Cells, a ledger and one authority.

Each water area, a box up to 256 m across, is split into half-metre cells. Each knows how much water it holds. Water moves from cell to cell, and any water added or taken away is counted, so the ledger is checked every step.

Cross-section: water cells over dug terrain A slice through terrain made of half-metre cells. A lake fills a hollow to a flat level, spills over a lip and runs down a dug channel. A ledger beside it shows the lake losing 1,200 litres and the channel gaining 1,200, with the total unchanged. 0.5 m cell the lake finds its level spills over the lip and runs down the dug channel terrain (Voxel Plugin 2) LEDGER every step Lake −1,200 L Channel +1,200 L Total unchanged
Diagram, not to scale. The litre figures are an example. Real cells sit in 3D bricks. Solid rock is skipped, but every brick with open space is stored and checked each step, wet or dry.
Who runs the water in a multiplayer game The server or listen host checks players' dig and fill requests, applies accepted terrain edits and sends them to every player. It steps the water on the processor, thirty times a second, without needing a graphics card, and sends each player a compact copy of the water near them. Each player's machine draws it: water within about 32 m, with FluidNinja close by and the plugin's own surface elsewhere, plus the flood layer for dam breaks. SERVER OR LISTEN HOST Runs the water Applies terrain editsSteps the water 30 times a secondKeeps the water ledgerProcessor only, no graphics card needed compact copy ≈2.5 KB/s each, creek test PlayerPlayer Draws water within about 32 m: FluidNinjaclose up, the plugin's own surface elsewhereSame copy, same lake, plus the floodlayer when a dam lets go
One authority. Listen and dedicated servers run the same code path, with or without a graphics card. Players ask to dig or fill; the server checks the request and sends accepted changes to every player. A joining player catches up on that session's edit list. This works in network tests; saving a world between sessions is still planned.

Game code can request sphere or box digs and fills, and undo earlier player edits, in Blueprint or C++. A game can set its own permission rules and size and rate limits. Runtime terrain changes must use these calls to reach every player; sculpt-brush edits aren't shared. Long edit histories still cost more to replay and update, so these tests don't establish a supported map size or player count.

  • 0.5 mWater cell size. Half a metre each way.
  • 30 / sWater steps a second for now, on the server's processor.
  • 9,400 L/sPeak flow when our 80,000-litre test dam was removed in one go.
  • 2.5 KB/sAverage sent to each player on our creek test.

Where it's going

Boats, caves and whole maps.

The pictures in this section are generated concept art. They show where the plugin is headed, not what it does today. The list after them says what's built, what's under way and what's planned.

Painted concept: one person rows a wooden boat along a freshly dug canal into a lake, another digs the bank, a third swims beside the boat. Concept art · planned

Boats, swimming and canals

Buoyancy, boats and rafts, swimming and holding your breath, and floating things that push water aside. Planned, with Jolt doing the physics.

Painted concept: a hand-dug tunnel breaks into a cave and groundwater pours in, pooling below a ledge where a miner with a headlamp stands. Concept art · partly built

Water underground

Flooded chambers, caves and trapped air already work on test levels. A water table under the map-wide world is planned.

Painted concept: a muddy surge bursts through a breached earth dam and floods a valley around trees and boulders. Concept art · partly built

Floods at the scale of a valley

Dam breaks already run on a test dam. Rivers and waterfalls across a whole world are on the map-wide plan.

Painted concept: a cube cut from the ground shows a trench of glowing water cells draining into a pocket underground. Concept art · the idea

Cells you can't see

The blocks show the cells the plugin tracks. In a game, the terrain is smooth Voxel Plugin 2 ground and the water is drawn as a surface.

Built

  • Volume tracking, checked every step
  • Digging that moves water on the next step, with trapped air
  • Seven behaviour scenarios, from lakes to cave-ins
  • Water underground: caves, tunnels and trapped air
  • Dam breaks limited by the size of the hole
  • A surface look driven by the flow
  • Flood layer for dam breaks and jets
  • Water shared with players over the network
  • Dedicated-server joins checked with two players, with water continuing to run
  • D3D12 on Windows; Vulkan so far in GPU tests only

Under way

  • Shared terrain edits: digs, fills and undo work in network tests; scale work continues
  • Flood layer review, including multiplayer and cost checks
  • A query API so game code can ask where the water is
  • Debug views and timing tools
  • Groundwork for map-wide water
  • A demo look: proper terrain and sky on the test levels

Planned

  • Saving and loading, and full support for players joining late; terrain edit replay already works in tests
  • Pipes and the sea, and springs that feed rivers
  • Splash and spray as real particles
  • Boats, rafts, swimming and buoyancy
  • Damming tools: bucket, pump, block
  • Packaging, a quick start and the remaining game-facing APIs; terrain edit calls already work in Blueprint and C++
The road to map-wide water Ten milestones along a river line: sparse core; sea, springs and lakes; world regions; rivers and waterfalls; multiplayer at scale; one look at scale; groundwater; saves and long runs; then, later, rain and evaporation, and erosion. An earlier study used worlds of 8 by 8 kilometres and 32 players. The aim is now Unreal's largest maps, with supported map sizes and player counts still to be established. MAP-WIDE WATER · PLANNED Earlier study: 8 × 8 km worlds, 32 players 12345678 910 Sparsecore Sea, springsand lakes Worldregions Rivers andwaterfalls Multiplayerat scale One lookat scale Groundwater Saves andlong runs Rain andevaporationErosion Solid dots: the map-wide plan. Dotted: later. Today one water area is a box of up to 256 m.
The map-wide plan. These milestones describe the larger water system; shared digging, swimming, save and load, and packaging come first. The aim is Unreal's largest maps, with supported map sizes and player counts still to be established. The earlier study shown here used 8 × 8 km and 32 players. Today one water area is a box of up to 256 m.

Speculation A thought experiment, not a plan

From your boots to the edge of the world, and under it.

Today FluidNinja draws the water up close, and players who join a game see water within about 32 m. This section asks a bigger question. If the same water had to reach the horizon of the largest world Unreal Engine can hold, how might the work split, across and down? Our guess: particles for the splash at your feet, the cells for the water you can change, and FluidNinja's surface carried out to the horizon. Only the cells, drawn up close by FluidNinja, run today. The particles are planned; carrying FluidNinja's surface to the horizon runs against our current plan.

Painted concept: a player with a shovel has dug a trench through the bank of a hillside pond, and the water spills out and tumbles down it, while valleys, winding rivers and lakes stretch away to the sea at a curved horizon. Concept art · speculation
One view, every distance. A splash at your feet, rivers in the valley, the sea on the horizon. Generated concept art of the idea, not a capture.
Powers of ten, from a water particle to Unreal's largest world A logarithmic scale from 1 centimetre to 100 million kilometres. Marked: a 25 cm APIC grid and 16 m APIC zone (planned); the 0.5 m water cell, 32 m that joined players see and the 256 m largest water area (built); one FluidNinja simulation, usually 5 to 100 m; an earlier 8 km map study; a small water test positioned 1,000 km from the origin, not a world that size; the 12 km deepest hole dug on Earth, Earth's 12,742 km diameter and the 384,400 km to the Moon for reference; and Unreal Engine's largest world, about 88 million km edge to edge. 1 cm 10 cm 1 m 10 m 100 m 1 km 10 km 100 km 1,000 km 10⁴ km 10⁵ km 10⁶ km 10⁷ km 10⁸ km 25 cm APIC grid 0.5 m water cell 16 m APIC zone 32 m joined players see 5–100 m one FluidNinja sim 256 m largest water area 8 km earlier map study 12 km deepest hole dug on Earth ~1,000 km test offset from origin 12,742 km Earth across 384,400 km Earth to Moon 88 million km Unreal's largest world
Every step on this line is ten times the last. Solid blue is what runs today, pale green what's planned, grey for reference, amber the rest of the room Unreal gives you. Unreal's largest world is about 88 million km edge to edge: some 6,900 Earth diameters, 229 trips to the Moon, or about 59% of the way to the Sun.
How the layers could split around a player Rings around a player, not to scale. Innermost, APIC splash zones about 16 m across at jets, falls and splashes (planned). Next, the cell water run by the server, drawn with FluidNinja's live simulation (built, small). Next, FluidNinja's passive surface carried to the horizon and fed from our lake and river levels (speculation). Outermost, the coarse far water planned for map-wide work, stretched across the whole world until someone comes near (speculation). you 1234 not to scale 1 Splash zones: APIC particles About 16 m across, at jets, falls and splashes. PLANNED 2 The cells, with FluidNinja's live sim The water you can change, run by the server. BUILT, SMALL 3 FluidNinja's surface to the horizon Passive patterns fed from our lake levels. SPECULATION 4 The whole world, coarse Planned coarse water, stretched to the world. SPECULATION
Detail where you look, bookkeeping everywhere else. Each ring hands over to the next. Only ring 2 runs today, on test levels.
1 · AT YOUR FEET

APIC for the splash

Where water jets through a gap, falls or splashes, a zone of particles about 16 m across would take over the look: droplets and sheets that keep their swirl. APIC (affine particle-in-cell) is a particle-and-grid method that's stable and holds on to rotation. It's planned as a cosmetic layer on each player's machine. It never changes the gameplay water, and two players may see different spray.

Planned · nothing built or measured yet

2 · AROUND YOU

The cells stay in charge

The water you can dig, dam and flood stays in half-metre cells, run by the server, with FluidNinja drawing it up close. That's the part that works today: one water area up to 256 m, and about 32 m of view for players who join.

Built, on small test levels

3 · TO THE HORIZON

FluidNinja's surface, further out

FluidNinja runs a live 2D simulation that follows the player, usually over 5 to 100 m. Its makers carry the water on past that with passive, unsimulated surface patterns, with the mesh detail dropping away with distance. The idea: feed those far patterns from our own lake and river levels, so the horizon shows the right water in the right place. Our current plan draws far water with our own surfaces instead.

Speculation · not in our plan

4 · THE WHOLE WORLD

88 million km of room

Unreal Engine 5 keeps positions in 64-bit numbers, and its largest world is about 88 million km edge to edge, or 44 million km either way from the centre. Our map-wide plan uses full cells near players, coarser water further off and sleeping still water. The guess is stretching that across the whole world. A small water test now works 1,000 km from the origin; that checks position handling, not water covering that distance. Today's water area is still a box of up to 256 m.

Speculation · map-wide water is planned

5 · BELOW YOU

As much room down as across

The cells are 3D, so caves, tunnels and flooded workings are the same water as lakes and rivers. Our map-wide plan adds groundwater and a water table. The guess is a whole world with water in the rock beneath it: aquifers, underground rivers and flooded mines, coarse until someone digs in. The deepest hole people have dug on Earth is about 12 km. Unreal's world goes millions of kilometres down.

Speculation · groundwater is planned, not built

It's been done in film. For Disney's Moana, close-up "hero" waves around boats and characters came from an APIC solver, art-directed and tsunami-scale waves from a cheaper procedural tool, and both were blended into the rest of the ocean (SIGGRAPH talk). The split we're guessing at is a similar idea, only it would have to run live in a game.

Painted concept at ground level: water bursts through a breach in an earth dam as a spray of droplets and sheets beside a player's boots. Concept art · speculation

Ring 1: the splash

Droplets, sheets and spray where a dam gives way. Planned as APIC zones, not built.

Painted concept from about 500 m up: a river valley with a dam, a reservoir, a waterfall into a lake and a channel diverting part of the river. Concept art · speculation

Rings 2 and 3: the valley

Rivers, a dam and a waterfall you could change, fading into surface detail further off.

Painted concept: an underground river rushes through a vast cavern lit by lanterns and a shaft of daylight, with a player in a headlamp on a ledge. Concept art · speculation

Below: rivers in the rock

Underground rivers through cave networks are on our plan for later. A whole world with water under it is the guess.

Painted concept from near orbit: a fictional world with river networks draining across continents into a deep blue ocean under bands of cloud. Concept art · speculation

Ring 4: the world

A whole planet would fit in Unreal's largest world thousands of times over. Water at that scale would be coarse bookkeeping until a player arrives.

What 64-bit doesn't fix. Positions are 64-bit on the processor, but the graphics card still works relative to the camera in 32-bit pieces. Some engine systems are still sized to the old 21 km world (lighting traces stop at about 10 km), and particle effects keep their positions relative to local tiles. Any world this size would stream its land in pieces, and so would its water.

Where it's at

Working on test levels. Not for sale.

VoxelWater runs in our development project, on small test levels. It isn't released or sold, and the source isn't published. We haven't decided how it'll be distributed.

It's a plugin for developers, not a game. The project around it holds our test levels and a basic stand-in character; a sample game to show the water off is planned.

In development

Plugin version 0.1 · beta

What it needs

  • Windows, 64-bit. No Linux, Mac, console or mobile.
  • The latest Unreal Engine only, 5.8 at the moment, on D3D12. Vulkan has only run our GPU tests so far.
  • Voxel Plugin 2 for the terrain, FluidNinja LIVE-2 for the close-up surface, and UnrealJolt for physics. You get Voxel Plugin 2 and FluidNinja separately.

What it doesn't do yet

  • Boats, swimming, buoyancy, oceans and map-wide water are planned, not built.
  • Shared terrain edits work in small network tests; large edit histories and map-wide multiplayer still need work.
  • Saving and loading a world between sessions is still planned.
  • Only tested on NVIDIA graphics so far.