gg, week 16: Harbinger, particles, and an animation graph
The jam gets a second run and turns into a game worth keeping, which drags particles, an animation graph, retargeting and decals into the engine behind it.
The last post ended with a list of plans waiting their turn and a traversal slice that still hadn't started. None of that moved this week. On the evening that post went up I ran the first jam's prompt a second time, mostly to see how much further the engine would get, and the game that came out of it was fun enough that I was still playing it at one in the morning. Then I decided to keep it.
That decision set the agenda for everything else here. A game I intend to keep has no patience for a torch that's a glowing box, or for a player who's a stick man with one clip to his name. Within the week the engine had grown a particle system, an animation graph, retargeting, decals and save files to pay for it.
The jam, again
The first jam, back in September, lasted exactly one question. A game module couldn't put so much as a capsule into the world, the evening went on exposing EnTT to it, and what eventually got built was seven capsules walking at a fence. Its prompt has been sitting in the repo ever since, so I handed it to Claude again, word for word: a village in a clearing, forage by day, build defences, survive five nights.
This time every question in the opening round was about the game. A bit over an hour later I had the controls to a wave-survival builder with a day and a night, four kinds of defence, levelling with a choice of three traits and a storm rolling in every evening, all of it in the demo's village.

Night one of the second run, behind a pair of barriers. The torch is a post with a very bright material on top, and so is nearly everything else that glows.
I played it four times that night, and after each pass my notes went back in as changes. The first pass was far too easy, because a few arrow towers did all the work and I never had a reason to leave the village. So XP became something you walk out and pick up, gold only comes from foraging, and the creatures split into kinds that hunt particular defences. Sappers run at towers and torches and blow up beside them, and brutes go for the barriers. By the fourth pass it was properly fun.
The engine came out with a list as well, though a shorter and less embarrassing one than September's. A felled tree left its collider behind, and re-running CMake under a running session relinked the engine for no reason, after which the session refused every hot swap until it was restarted. Both are fixed. The one real hole is that a game can't harvest the grass and trees a terrain scatters, because scatter isn't made of entities. The jam painted the scatter out of a copy of the terrain and grew its vegetation by hand, and that one is on the plan.
Harbinger
A jam game is supposed to go in the bin, and September's did. I couldn't quite bring myself to bin this one, so it's staying as a small side project beside the game the plan describes, and it has a name.
A harbinger was the officer sent ahead of an army or a court to arrange its lodging, and that's roughly the job. The kingdom pays harbingers to go out into wild, magical country and raise a gate for its forces to come through. A gate takes several nights to finish building itself, and starting one tells everything in the forest exactly where you are. It's grimdark-ish, a bit Lovecraftian, and doesn't take itself very seriously.
The resource is ichor, the residue left behind when you wither a piece of the natural world out of existence. That's the foraging, and it's shamelessly the reclaim from Total Annihilation: hold a button, reach out, and a stream swirls off the tree and into your hand while the tree glows and dissolves. Building spends it, and a run is five nights in about half an hour, the way a survivors-like's is.

The warlock, the warrior and the ranger. It's one body in three outfits, with a weapon hung off a hand.
There are three classes (a warlock who casts from range and falls over if you look at him, a warrior who's the opposite, and a ranger who does a bit of both), talents and relics that carry over between runs, and four clearings to do it in so far.

Pinewood and Deadwood, a couple of minutes into day one. The wagon in the corner is standing in for the gate, which doesn't exist yet.
Keeping a game changes one rule. In a jam, when the engine can't do something, you write it down, hack around it in the game and carry on. On a game that's staying, a gap in the engine stops that piece of work until the engine does it properly, and nearly everything below exists because Harbinger stopped on it.
Particles
My notes from that first night had a theme. Torch flames, the build hologram, explosions and death effects were all boxes and spheres with emissive materials, because that was the only thing a game could put in the world. I wanted fire, sparks, smoke, energy swirls and magic bolts.
An effect is a document of particle layers plus a sound, and a game plays one the way it plays a sound: by id, at a place or following an entity, once or until it's told to stop.
The motion is all closed-form. Where a particle is at any moment is a function of where and when it was born, its random draws and the time, with gravity, drag, an orbit, a noise wobble and a pull toward an attractor folded in. Nothing is integrated from frame to frame, so the editor can scrub an effect's clock, an instance that left the view comes back exactly where it would have been, and a C++ copy of the same function checks the compute shader in the tests.
Particles run in the same GPU pool as last month's rain, and they sort against glass and water. That took more thought than the particles did. The blended phase of the frame is cut into as many as eight depth slabs, with the cuts placed in the biggest gaps between things, and each slab draws its glass and then its particles. A fire behind a window stays behind it while the sparks in front stay in front.

The effects test scene: a swirl, smoke, a flame and sparks, in front of and behind a pane of glass.
When I first measured it, all of this added a third of a millisecond to a frame with no effects in it. Every slab is a view in the GPU cull, and a view costs the same however few items it holds. Slabs are only cut now on frames that have particles to sort, and an empty frame's cost fell back into the noise. One stage of the sort also got rewritten to run wide, and since the rain goes through the same sort, ordering a storm's particles went from 5.1 ms to 0.12. I'll take it.
What's missing is light. Particles glow and the fog dims them, but nothing lights them, so smoke by day is a dark smudge and an effect can't light the ground under it. That's the next stage.

A damage aura in Harbinger. Emitters couldn't be hollow until the game asked for a ring.
Glow and dissolve
The other half of the hologram problem was the mesh. An entity can now carry a small component that tints every surface it draws, adds emission, fades it out evenly, or dissolves it away through a noise pattern behind a glowing edge. In Harbinger the structure under the build cursor glows, and withered trees and dead creatures dissolve behind an edge the colour of ichor.
Getting a per-entity value into the fragment shader without paying for it everywhere was the interesting bit. The obvious route is one more interpolant out of the vertex stage, and when I measured that it cost 2.1% of the scene pass, on every mesh in the frame whether it glowed or not. The vertex stage already passes along a flat integer for the level of detail, though, and that integer had bits to spare. An entity with the component gets a row in a table and the row's index goes in the spare bits.
The dissolve reads its noise in the entity's space, projected from three sides. I'd have used the mesh's UVs, but these packs colour their models from a palette texture and every UV on a face sits on the same few texels, so a dissolve by UV takes out a whole face at a time.
An animation graph
Until this week a character played exactly one clip at a time, and the engine picked a walk, a jog or a run from the body's speed with some hard-coded logic. That was the whole animation system, and it's why every character in every screenshot so far has been a blocky stick man.
It's two documents now. A rig is a skeleton and its library of clips, along with everything the engine needs to know about them: which ones loop, where the feet are down, named sockets, masks over the joints. A motion is a graph over one rig, made of clips, choices, blends and state machines, and a game drives it by setting parameters or by letting the engine write the body's speed, turn rate and grounded state into them every tick.
The graph advances on the simulation tick, and its state is a handful of plain numbers on the entity. Everything else follows from that: a saved scene holds the pose a character was in, a replay reproduces every transition, and a game can ask what state a body is in and get a straight answer.
Blends are where it got fiddly. The weights come from Daniel Holden's way of doing blend spaces without triangulating them, and that part was easy enough. But blending a walk into a jog only works if both have the same foot on the ground at the same moment, and clips out of a library don't start in the same place. The eight jog directions in the library I'm using plant the left foot on frame 1, 13, 48 or 50 of 57, depending on which way they're heading. So the cook finds where each foot is down in every clip, and a blend holds its clips in step at each footfall they share.
That still slid. A jog and a run each have a moment with both feet in the air, and mixing them while one held down a foot the other had already lifted measured 0.38 m/s of slide under a planted sole. Lifts are marks now as well and the same blend slides at 0.03. I know the numbers because the engine measures them: one verb reports how fast each planted sole is moving across the ground, and a test bounds it across the strafe's directions and speeds. Eyeballing foot slide is a great way to convince yourself there isn't any.
My favourite bug of the week came out of this, too. For a while a body walking the way it faced reported, with total confidence, that it was travelling at 2.4 m/s backwards. The models face +Z, and the code reading a body's velocity along its facing had assumed the other end.
Over the base tree a graph lays layers, each through a mask: an upper body held over a jog, an aim offset, a flinch that adds to whatever is under it. A slot is a layer that shows nothing until the game plays an action on it, and that's how an attack, a roll or a spell gets played over the locomotion.

A layer over a jog. The legs belong to the jog, and everything from the spine up is another clip, held in the model's space so it doesn't sway with the hips.
An action can move the body as well. If the rig marks a clip's root as carrying travel, the cook lifts that travel out into a separate track, and the action drives the capsule along it through the same character controller steering uses, so a roll still collides with things and still falls off edges. Give it a target point and the travel bends to arrive there, much like Unreal's motion warping.
Feet on the ground
All of that produces a pose in the clip's idea of the world, where the ground is flat and the body moves at exactly the speed the animator had in mind. A second pass fixes that up just before the pose is drawn.
A ray down through each foot finds the real ground, the pelvis drops as far as the lowest foot needs, each leg is solved to put its heel at the right height, and a planted foot tilts onto the slope under it. A planted foot is also locked where it came down in the world until the clip lifts it.

One foot on each step. The rest of the test bay is in the background, doing its exercises.
The leg solve is Daniel Holden's two-joint IK with his foot locking on top, and I left the recipe in one place. It softens the last stretch of a leg's reach so the knee never snaps straight. Applied to every foot, that would have pulled each one 7 mm short of where its clip had already put it, and everybody would have hovered. Here a leg is only eased when it's asked to reach further than its pose does.
That solver went through a version I'm glad didn't survive. It had two paths, one for a knee bending in the plane it's meant to and a fallback for one that isn't, with a tolerance choosing between them. Every test passed and so did every golden image. Reviewing it turned up a pose sitting right on the tolerance, where a tiny change of input flipped paths and the thigh jumped seven degrees in a single step. It's one path now. The tests sweep a limb through bends and reaches in small steps and bound how far it may turn in each, since a foot ending up in the right place turns out to say nothing about how it got there.
Warping happens in the same pass. The stride is scaled to the body's real speed and the pelvis turned toward its real course, which lets a character strafe on nothing but a forward and a backward jog. A chain of joints turns until a socket points at a target, and a support hand stays on a weapon. It finishes with the cheap physical stuff, where a blow turns the struck joint and the spine above it on a spring and the trunk leans into acceleration. None of it is simulated, so a replay never depends on what happened to be on screen.
One library, many bodies
The stick man's clips come out of a Python script, and he was never going to carry a game. Quaternius publishes a Universal Animation Library under CC0, and its two volumes are now the engine's second rig: a mannequin and 253 clips, from eight-way jogs through sword combos, spell casts and deaths to fishing and a zombie shuffle.
A library that size made storage a problem straight away, since the cooked rig was 31 MB of raw samples. Clips are quantised on disk and stay that way in memory, with a pose decoding only the frames it reads, and the same library is 2.3 MB. The error bound is a tenth of a millimetre, measured a few centimetres out from every joint as ACL defines it, and further out wherever a socket says something long is attached, so the tip of a 1.2 m sword is as precise as the hand holding it. I tried ACL itself and couldn't find a setting that held that bound on both rigs, so the encoder ended up being mine.
Quaternius's monsters and people share the mannequin's joint names but very little of its proportions, and I wanted every one of them to play that one library. Retargeting happens when a model is bound to a rig. Each joint takes the library's rotation and keeps the model's bone length, and every distance the library gives in metres (root travel, foot placement, socket offsets) is scaled by the ratio of the two leg lengths.

One jog on eight bodies, from the stick man to something carrying an anchor.
Which leg length turned out to matter. Adding up the bone lengths said the Lycan, a hunched wolf-thing that runs on permanently bent legs, was 10% bigger than the mannequin, when its feet cover about 86% of the mannequin's stride. Hip to heel in a straight line at rest gives 0.88, so that's the measure.
Proportions put the feet in the wrong places too, since a monster's hips are wider and its legs fold differently. After retargeting, each leg is solved again to put the heel where the library's heel is at the body's scale, and on the test brute that took the heels from 97 mm off to 2. It isn't finished. The Lycan's knee still bends backwards for a few frames of every stride, which is as unpleasant as it sounds, and the fix is next in line.
The models needed two more things before Harbinger could wear them. Many come with several texture sets, so the cook reads glTF's material variants and an entity picks a skin by name. And an outfit is a separate skinned model that has to move with the body under it, so a child entity can be posed by its parent, joint for joint by name, the way Unreal's leader pose does it. That's what the three classes further up are. The first outfit came out with its limbs squashed flat wherever they left a box sized for the outfit's T-pose.
Decals, and a sphere that came out too dark
Harbinger wanted a withered thing to scar the ground, and the scale plan had decals on it already. A deferred renderer gets decals nearly free, since there's a G-buffer to paint into. This one is forward with MSAA and has no G-buffer, so they went into the clustered grid the lights already use: each cluster lists the decals touching it, and the surface shader walks that list straight after sampling its material. A lattice of 64 adds a third of a millisecond to the scene pass, and 512 adds three quarters.
The same stretch of work took a first run at normal maps that sparkle. A bumpy normal map seen from far away averages out to a flat normal in its small mips, so the surface gets shinier with distance and glitters as the camera moves. The usual fix, going back to Toksvig, is to measure how much the normals under each mip texel disagree and widen the roughness there to match. The cook does that now, and a quarter-pixel nudge of the camera that used to change 16 pixels on the test sphere changes none.
It also overshoots. The baked sphere comes out 10.7% darker than the plain one supersampled eight times per axis, and that render is the truth it's supposed to match. The first reading of the comparison had it the wrong way round and blamed the plain sphere for being too shiny. The widening gets another go before any real asset is cooked with it.
Odds and ends
Pro-tip: If you hot-reload C++ built with GCC, run readelf --dyn-syms over the module and look for UNIQUE. glibc never unmaps a library holding an STB_GNU_UNIQUE symbol, so dlclose quietly does nothing and every old copy of the module stays mapped. -fno-gnu-unique on every translation unit that ends up in the module sorts it out. Mine had two, both out of libstdc++.
- A game can load a scene, write and read save files, sweep a shape through the world, ask a model for its bounds and find an entity by its persistent id. Each one is something Harbinger stopped on.
- After a shader change the first start has the driver compiling a few dozen pipelines, and for 18 seconds that looked exactly like an empty editor. I closed it within seven, more than once. There's a banner now.
- A sanitised build found a use-after-free in the music code that every ordinary test run had been passing, since freed memory usually still holds the right bytes. Under ASan every asset store now reallocates on every load, so the next pointer held across one fails loudly.
- A flaky golden turned out to be two test processes sharing NVIDIA's on-disk shader cache: 16 of 34 paired runs failed on a shared cache, and none on private ones.
- Music can be stems, one track as several layers that start on the same sample and stay in step.
- Ubuntu's unattended upgrades got me again. Last month they swapped the NVIDIA driver out from under its kernel module, and this week they replaced libc6 and its headers while the test suite was running. Ninja doesn't track system headers for a precompiled header, so the next compile failed on a stale one.
Where it stands
The animation plan is down to a node canvas for editing graphs and making a crowd cheap. Effects still owe lit particles, lights, trails and a dissolving thing's shadow.
Harbinger has no gate yet, and its flying creature is a sphere with two flapping boxes because no pack I own has anything with wings. It is fun, though.
And the traversal slice still hasn't started, although for once I have a decent excuse.
Credits
Everything that isn't engine is bought or borrowed:
- The buildings, props, trees, foliage and rocks are Quaternius kits: the Medieval Village and Stylized Nature MegaKits, bought as the paid source versions, plus the free Ultimate Stylized Nature set. All of it is released CC0, and he takes Patreon support.
- The characters are Quaternius's too: the Universal Animation Library, Universal Base Characters, the fantasy Modular Character Outfits and the Fantasy Props MegaKit, all CC0. The monsters are his Dungeon Monsters bestiary, whose licence covers using them in a game and not passing them on.
- The weapons are KayKit's Fantasy Weapons Bits by Kay Lousberg, CC0.
- The ground materials are Poly Haven textures, CC0.
- The sound effects are Imphenzia's Universal Sound FX, under a purchased licence.
- The type is Inter by Rasmus Andersson, under the SIL Open Font License.