The voxel engine started on 16 October at 08:51, as an empty repository with a licence, a roadmap and a list of budgets. Today is 16 November, so it is one month old, and it is at version 0.56.

Until now this diary came every few days: day one, days two to six, seven to twelve and thirteen to twenty-seven. That pace made sense while every day changed the engine’s shape. Now it changes less from day to day, so from here the posts come once a month, or earlier when something interesting arrives.

As before, agents write every line of the code, and I decide what gets built and check the result on the screen. That takes every evening and every weekend: at least three or four hours a day, sometimes up to ten. Every frame and timing below is from my laptop, an RTX 3080 Laptop GPU with a Ryzen 9, unless it says otherwise. The engine is built alongside a first game, and this post does not describe the game.

The first evening and today

On the evening of day one I recorded the screen for the first time. The cave was already streaming around the camera, drawn as grey cubes and lit by nothing but the headlamp.

A month later the cave has glowing amethyst and ore in it. Its light does not flicker. And a spider of fourteen parts walks across the floor.

Day one and day thirty-two

Both are my screen recordings from the windowed build. Left: 16 October, 20:41. Right: 16 November, 16:41.

Day one: the streamed cave under the headlamp
Day thirty-two: the spider in the showcase hall

Cropped from full-screen recordings; the spider's crop removes the debug line at the top of the window.

The month in pictures

The slider walks through the month by the pictures from the earlier posts and today’s recordings. Under each picture is the size of the engine on that date: its tests, and its lines of Rust and of shader code.

The engine's first month

Plays by itself while on screen; the slider and the buttons stop it.

A spherical pocket of air in grey voxel rock, lit by a cone of light from the viewerA cross-section of the voxel level seen from outside, with the lit walls of caverns visible through itThe inside of a gothic chapel with ribbed vaults, tall blue windows and torchesA cave wall under a headlamp with a vein of warm glowing ore running down itA cavern where glowing crystals cast warm, steady light on the pillars around themA ring of small white voxel figures in a warm-lit cave, seen from aboveA voxel spider in a cave lit by purple crystals and warm ore

16 Oct · day one

A bounded world, then a streamed one, under a headlamp.

tests
115
lines of Rust
13,200
lines of shaders
824
Show the numbers
Whentestslines of Rustlines of shaders
16 Oct · day one 11513,200824
20 Oct · collapse 50152,3181,490
22 Oct · light 64674,1444,050
28 Oct · glowing rock 72485,4846,237
11 Nov · steady light 876110,6177,438
16 Nov · walkers 1,054146,5668,317
16 Nov · the spider 1,054146,5668,317

Tests are the #[test] functions on that date; lines are all lines of the .rs and .wgsl files, comments and tests included.

The month by date

When each feature arrived.

  • the world
  • light
  • speed
  • creatures
  1. 16 Oct Empty repository at 08:51; a bounded world of bricks and chunks with digging at 15:20; a streamed world with coarse copies far away at 17:29
  2. 17 Oct One night: collision and a character controller, .vox import, collapse of unsupported rock, a server with an edit log and replay, game logic in WebAssembly, 3D sound
  3. 19 Oct The ray walk learns to skip empty space by flags
  4. 20 Oct Bricks stored four times smaller, falling rock that crushes what it lands on, the cutaway view, a gamepad
  5. 22 Oct Light per pixel, bounce light, a generated gothic castle
  6. 27–28 Oct AMD's FSR 2 upscaler, eye adaptation, the showcase hall of 72 × 58 × 24 metres
  7. 29 Oct–11 Nov Light computed ahead and stored per chunk, after two weeks of flicker Plain cubes became the default look on 3 November.
  8. 11–13 Nov Far caves no longer black while their light is computed; big speed cuts
  9. 15 Nov Sixteen dynamic lights; the first release, with a tester build
  10. 16 Nov Voxel creatures: walkers, a spider, animation written as text, a recorder that films them, a loading screen

How the engine sees

Everything in the engine stands on one idea: the ray walk. The world is made of voxels, 10 cm cubes. Eight by eight by eight voxels make a brick, and eight by eight by eight bricks make a chunk, 6.4 metres on a side. The GPU draws a picture by shooting a ray from the camera through every pixel and walking it through this grid until it hits rock.

Walking voxel by voxel would be slow, because most of a cave is air. So the walk crosses empty space in big steps, and each step starts on the edge of a block of its size. A whole empty chunk is one step. Then a group of two by two by two empty bricks, then one empty brick, then empty blocks of 4 and 2 voxels inside a brick that has some rock in it. Only right next to the rock does the ray go one voxel at a time.

The slice below does the same in two dimensions. Point at the cave and the rays turn. Click or drag to dig, and the big steps come back where the rock is gone. Untick the skipping to see the walk the slow way.

How a ray crosses empty space, in a 2D slice

Point at the cave and the rays follow; click or drag to dig. The squares are the ray’s steps: the bigger and darker, the more empty space one step crossed; orange ones are single voxels.

  • chunk 64
  • 2×2 bricks (16)
  • empty brick (8)
  • block of 4 or 2
  • one voxel

A 2D model of the engine’s shaders/walk.wgsl: an 8-voxel brick, a 64-voxel chunk. The engine does the same in 3D, and walks far chunks through coarser copies of them (mips), shown further down.

Every frame pays for the walk first, and it got cheaper twice. On day one the primary rays took 6.69 ms at 1080p in the streamed cave. On 19 October the engine got flags that say “nothing in here” for blocks of every size, which is what lets the ray skip, and the time fell to just under 2 ms. Today it is under 1.5 ms.

Primary rays, 1080p, the streamed cave's spawn

GPU time of the ray walk on the RTX 3080 Laptop.

16 Oct 6.69 ms
19 Oct 1.98 ms
16 Nov 1.48 ms

From the engine's notes and changelog; the two later readings were ranges (1.93–1.98 and 1.44–1.48 ms), shown at their upper end. The budget for primary rays is 3.0 ms of a 16.6 ms frame.

Show the numbers
ray walk
16 Oct 6.69 ms
19 Oct 1.98 ms
16 Nov 1.48 ms

What the engine keeps around the camera

The cave has no edge. As the camera flies, chunks ahead are generated and chunks behind are dropped, so only the space around the camera exists at all. And not all of it at the same detail. Close to the camera every voxel is kept. Further out the engine keeps mips: coarser copies of a chunk, where one cell stands for 2, 4 or 8 voxels a side. A mip cell is solid if any voxel under it is solid, and it takes the most common material. From far away the difference is hard to see, and the ray steps over the coarse cells there, so it is cheaper too.

In the engine full detail reaches 102 metres from the camera and the mips 154. The slice below is scaled down to fit the page. Move the pointer and the rings travel with the camera. Notice that a whole chunk changes level at once, and that far rock keeps its shape even in cells of 8 × 8. The counter shows how many cells the mips save.

What the engine keeps around the camera

Move the pointer (or use the arrow keys) and the camera, the black dot, follows. Near it the world is kept in full detail, further out as coarser and coarser copies, and beyond that not at all. Each square is a chunk; its frame colour is its level of detail.

  • full detail
  • cell of 2×2
  • cell of 4×4
  • cell of 8×8

A chunk here is 16 voxels, not 64, and the rings are smaller, so that it fits a slice. The mip rule is the engine’s: a cell is solid if any voxel under it is, and takes the most common material.

Digging

The second foundation is the edit. An edit is a shape, like a sphere or a box, applied to the world, and it reports back exactly how many voxels of each material it removed. The math uses whole numbers only, so a server and a client that apply the same edits get the same world to the bit. That is also why the engine can keep a log of every edit and replay it: ten thousand digs of a one-metre radius replay in 279 ms.

After an edit the engine checks whether any rock lost its connection to something that holds it, on a coarse grid, in 0.33 to 0.4 ms. Rock that lost it drops straight down as one piece, and in the engine it also crushes what it lands on. Below is the same in two dimensions, without the crushing. Dig, and the counter lists every material you removed and how many voxels fell. Then undercut the ceiling.

Dig, and watch it fall

Click or drag on the rock to dig (keyboard: arrow keys and Enter). Anything no longer holding on to the floor or the walls falls as one piece. Try undercutting the ceiling.

The support rule is cut down to two dimensions: a voxel holds if a chain of neighbours sharing a side (not a corner) reaches the floor or a side wall. The slice leaves crushing out.

Light, finished

The two weeks of light I described last time ended with light that is computed ahead and stored per chunk, so it does not change by a pixel while nothing moves.

The worst leftover was black. Light for the far chunks was computed in a queue, and until the queue reached a chunk, the chunk stayed black. My own note from 11 November was “after several seconds distant caves still black”. Now such a chunk borrows the averaged light of the bigger block around it, and if there is none yet, of the block around that. The far caves are dim for a moment, never black.

Then dynamic lights. The game can now hand the engine up to sixteen point or spot lights every frame. Each lit pixel computes each light in reach exactly, with one shadow ray: a ray toward the light that checks nothing blocks it. There is no randomness in it, so there is no noise and nothing to settle. The old light flickered exactly because it was estimated at random, so that was the whole reason for doing it this way. A moving light is computed exactly every frame, and the light that does not move stays stored. The headlamp is now simply light number zero, and each light in reach costs about 0.17 ms on the RTX.

The last fix was to a bug that had been in every screenshot of this diary. A screen expects colour encoded with a standard curve called sRGB, and the final pass, which puts the picture in the window, used pow(c, 2.2) instead, a rough copy of that curve. It shifted 216 of the 256 possible values of a channel, the dark ones by up to nine steps: a value that should have reached the screen as 16 arrived as 7. The real curve is a straight line near black. The power curve has no straight part, so it presses the darkest values toward black. In a cave, where most of the picture is dark, that is a lot of lost shadow. Now every value reaches the screen as it should, and the colours I see got darker and more natural.

Speed, and the first release

The same days cut a lot of time. None of it shows in a picture, and that was the rule: every reference image, a saved picture each test must match, stayed the same to the byte.

Three cuts from the last five days

Milliseconds on the RTX 3080 Laptop, before and after.

  • before
  • after
creature animation, 64 creatures 15.12 ms 0.5 ms
processor time per frame 4.43 ms 1.68 ms
copying changed chunks to the GPU 0.18 ms 0.019 ms

From the engine's changelog. The last row is a median; its after value is the upper end of a 15–19 µs range. The animation row is explained below.

Show the numbers
beforeafter
creature animation, 64 creatures 15.12 ms0.5 ms
processor time per frame 4.43 ms1.68 ms
copying changed chunks to the GPU 0.18 ms0.019 ms

Version 0.54 is the first release. It ships a tester build: a launcher window that runs three scenes in turn, the streamed cave, the showcase hall and the castle. In each it flies the camera along a fixed path, times it like a benchmark and writes a report. Until now the only machine that had ever run the engine was my laptop. Then a programmer from America, who is building an engine of his own, wrote to me and offered to develop together. I said no, but we stayed partners for testing.

Creatures

Creatures started with one line from me on 10 November: “we need a plan for voxel model entity … with possibility of emissive light (gloving eyes for example) - we place model on a level”. Six days later the first one walked.

A creature is a voxel model made of up to sixteen rigid parts, each at most 64 voxels on a side. Every part hangs from another, turns around its own pivot and has its own detail: one, two or four model voxels per world voxel. A creature is not written into the world grid; creatures live in a pool of their own on the GPU. First the world’s walk finds the hit for a pixel. Then a second walk traces the creatures, never further than that hit. The shadow rays see creatures, so a creature throws a shadow.

The simulation moves in ticks, 30 a second, and a pose is computed for each tick in fixed point: whole numbers with an agreed scale, offsets in 1/256 of a voxel. Rotations are quaternions, the usual four numbers for a rotation, here also whole numbers, built from a fixed table of sines stored with the code. That is for the network. A server and every client compute the same pose to the bit, so a creature’s every voxel is in the same place on every machine.

flowchart TB
vt["spider.voxtext: the voxels drawn as text"] --> vox["spider.vox: the parts as voxel models"]
rig[".rig text file: parts, pivots, materials, clips"] --> pose
vox --> pose["pose at a tick, in whole numbers"]
pose --> pool["creature pool on the GPU, up to 64 creatures and 512 parts a frame"]
world["world walk: the hit for each pixel"] --> trace
pool --> trace["creature walk, never past the world hit"]
trace --> light["lights and shadows"]

The first creature is the walker: a torso, a head with two glowing eyes and two legs, about 1.3 metres tall with 10 cm voxels. One key places a walker, another sets them all walking in small circles at a metre a second. A third puts a real light between each walker’s eyes, one that casts shadows, as long as the list of sixteen lights has room; the rest keep their glow.

Walkers

My screen recording from 16 November: a crowd of walkers on their circles, seen from above.

Each walker is its own posed model, traced after the world

Sixteen walkers with their eye lights cost 1.8 to 2.2 ms on the RTX. On the integrated Radeon of the same laptop the same scene costs 15 to 23 ms, so a crowd there is not affordable yet.

Two problems showed only on the screen. The first was grain. With the eye lights off, a walking crowd looked “quite bad” in my window. A moving walker keeps uncovering pixels that the previous frames never saw, so there is nothing to average their noisy light with. A first fix halved it: the noise on screen, relative to the mean brightness, went from 10.6 to 5.5 percent. Filtering the freshly uncovered pixels harder barely moved it further and blurred fresh shadow edges, so I took another way. A walker that no listed light reaches is now lit by the stored light of the nearest wall or floor, with nothing random in it.

The second was a freeze. The first walker I placed stopped the app for about twelve seconds, long enough for the desktop to say “Application Not Responding”. The graphics driver was compiling the creature shaders right then, on the first frame that drew one. I decided: “its fine to wait for entities on startup when we have a loader in place”. The loader is further below.

Animation as text

A creature’s animation is a .rig file next to its model. It names the parts, which part hangs from which, where each joint is, which palette colour is which material, and the clips. A clip is a list of keys like “at tick 12 turn this leg 68 degrees about z”. Here is the start of the spider’s walk, the first leg’s keys:

clip walk ticks 48 loop
key 0 leg_l1 rot z 50 rot y 14
key 4 leg_l1 rot z 59 rot y 12
key 8 leg_l1 rot z 66 rot y 7
key 12 leg_l1 rot z 68 rot y 0

The leg swings around the vertical axis from 50 to 68 degrees and back. While it swings forward it is also turned about y, which lifts it off the floor. Eight legs with thirteen keys each, plus a few keys that bob the body and sway the abdomen, palps and fangs, and that is the whole walk.

The spider itself is drawn in text too. A .voxtext file is a stack of layers of characters, one character per voxel, s for shell, a for amethyst, e for ember, and a tool turns it into a .vox. The spider has fourteen parts (a body, an abdomen, eight legs, two palps and two fangs) and 32,455 voxels, of which the abdomen alone is 20,788. When I first saw it walk, I nearly fell off my chair: how cool it is, how much detail there is, and everything moves.

The slice below plays that walk straight from the numbers in spider.rig, seen from above. The simulation samples a clip at whole ticks, and the screen blends between two ticks for every frame it draws. Slow it down and untick “between ticks” to see what the simulation sees.

The spider's walk, played from its .rig file

Seen from above. Eight legs, each on its own phase; a lifted leg is lighter and casts a shadow. The numbers are the walk clip’s keys as written.

 

Source: the engine’s spider.rig, clip walk, 48 ticks at 30 ticks a second.

The engine’s viewer reloads the files on save: edit the text, save it, and the creature in the running window changes. I wrote down “arrived instantenious”, and about the motion between ticks “smooth”. A broken line keeps the old model and shows the error with its line number. MagicaVoxel, the usual editor for .vox files, still opens the same models. An agent also writes text as easily as code.

The blend between ticks had one surprise. The first version took 15.12 ms for 64 creatures of 16 parts each, because it composed every part’s pose from scratch for every point of every part, so the work grew with the square of the parts. Composing it once brought it to 0.50 ms. What is still missing is a crossfade between clips. When I switched the spider from walking to a head turn, it jumped.

The engine films itself

The recordings at the top of this post come from my screen. The engine can now record its creatures by itself. A small program renders the animation off-screen frame by frame, and frame n always shows the same instant of the clip, blended between ticks the way the screen would blend it.

The light needs a few frames to settle, so before the first kept frame the program renders 64 warm-up frames. Then it renders each instant 16 times and keeps the last one. Every run gives exactly the same footage, which ffmpeg turns into a GIF or an MP4.

The spider, filmed by the engine

The walk clip rendered off-screen frame by frame in the showcase hall, 25 frames a second, one 1.6-second loop played four times.

Every run of the recorder gives these same frames

The recorder wrote this as a GIF; re-encoded for the page, so the GIF's palette banding stays.

A loading screen

The castle scene used to start with a blank window for about three seconds, and bigger scenes for up to ten. The start is now cut into slices of 25 ms. Between slices the window draws a frame: a turning cube of 3 × 3 × 3 voxels, ray-traced in a shader, a progress bar that only ever moves forward, and the name of the stage.

The loading screen

The test's reference image: the castle at 37 percent.

A black screen with a small cube of 27 tan voxels in the middle, a progress bar a third full below it, and in the top corner the lines "castle - benchmark", "lighting the near chunks: 31 / 49 chunks" and "37 % 0.4 s"
The cube turns, the bar only moves forward

A plain splash appears as soon as the GPU is ready, so the castle shows something after about a third of a second instead of one to three seconds. The price is that the big streamed scenes load 8 to 10 percent longer. I accepted that, because loading is not so bad when the user sees that something is changing. I follow the RAIL model of interfaces here: the point is not the speed, it is that the user is not bored and does not think something broke. Slices of 25 ms plus the frame between them mean at most about 40 frames a second while loading, and that is what I saw: “a bit of a stutter yes, like fps in 30-40. bar is fine”.

The impression after a month

I think the engine has come a long way. I had no special plan for what must be done by when; I go with the flow. While the light was broken it was hard. The worst moment of the month was when I saw the light flicker and lag, and that was awful. The best was when we solved it, and that filled me with hope and enthusiasm. Today is a very good day too: finally there is life in the caves.

The biggest surprise of the month is still the limit of the agents: a task they cannot solve without me there. The work went fast wherever a test could check the result, and slowly wherever only a person looking at the screen could say whether the picture was right: the light for two weeks, and this week the grain on the walkers and the freeze.

What is next

Next come creatures that follow the floor instead of walking at a fixed height, and squash and stretch in the clips, shown off by a bouncing slime. Then a layer of small detail above the surfaces, grass blades, caps and pebbles, swaying in the wind. Then anything from a .vox file: large scenes stamped into the world, and structures built in stages and demolished. But what I want to see most is the outdoors: the sun, weather, liquids and gases, fire. Next post in a month, or earlier if one of these turns out interesting.