Our tower in Burrow on a clear morning: five storeys of rooms with chandeliers, beds and bookshelves, a glass stair room and an emerald on a pedestal. The player stands on the balcony at the top right, where a railway track leaves east toward islands in the sky. Below, lamp posts and a bench on the terrace, and the brick basement going down into the dark ground.

Making personal software

I enjoy making games for my kids. In October I created Burrow, a sandbox in the style of Terraria: you dig, build a house, find a grappling hook, and fight a giant moth at night. We play it together.

0:00 / 0:52

Why make personal software

I’ve been making personal software for as long as I can remember. I worked on a Terraria-like game a little after Terraria came out over a decade ago, and it took weeks of evenings to get a playable prototype. Now almost anything has something within a few hours.

We could obviously just play the original, which I still have on Steam, yet making ours is much more fun, and you can shape it exactly how you want.

Clay Shirky called this situated software, which “is personal from its inception.” Robin Sloan made an app for his family and wrote that programming this way is “a different activity altogether, just as cooking at home is really nothing like cooking in a commercial kitchen.”

My 4-year-old, our youngest, had a hard time with mouse and keyboard. I happened to have a pair of Switch Joy-Cons, so I added support for that after our first session. We play once a week, then they draw me something they want to see in the game, and I build some of it. A robot that scares zombies away with sound waves, trains, and countless others.

I’ve always created personal software; a database for myself, Shopify integrations for my wife’s business, a music studio for my son. I have more projects than I remember, sometimes I forget and rebuild things a decade later.

I don’t know if Terraria has a character studio, but I thought my kids would love to choose the hair and the skin color themselves, so we added it.

The Tangle in the rain at midday in a freshly generated world: the huge trunk of the Strangler Fig rising through the middle, its branches spreading flat crowns hung with glowing green vines, misty layers of jungle and pale stone spires behind.

the Tangle

Orchestrating agents

For most of my longer projects, the OpenTUI library included, I work in one main session that I pin and rename. I talk to it, and it keeps track of the project. Subagents do the implementation, each in its own worktree, other subagents review it, and the main session merges them. Burrow has two of these sessions: BURROW for the game and SCORE for the music.

Many of my chats with the main session happen away from the computer. The OpenCode iOS on my phone has a live audio session I can talk to, and it passes what I say on to the main session. I asked for the character studio by voice. What I say is usually a few sentences, and the main session writes a brief for a subagent from it.

What I asked for

I think another task which would be cool to add is a playable character studio, or I like the playable characters, so you can edit them. Currently they are randomized, so the hair, skin color, et cetera. But for my kids they’d love playing around with adjusting those kinds of things. Adding that in a sub agent session. Making it very, very good, intuitive. And fun, that would be awesome.

The brief it became

Where to work
You work on Burrow, a Terraria-like 2D sandbox in Zig 0.17 with Raylib. Work ONLY in the git worktree ~/src/burrow-wt/studio (branch `iter/studio`, based on main 3fd6876). Verify `pwd` and `git branch --show-current` before editing. Never edit files under ~/src/burrow (the main checkout) or in other worktrees.
Sharing the machine
## Common rules - Read AGENTS.md and docs/brief.md first and follow them. Other agents share this machine: use a FILTERED test watcher (`-Dtest-filter=TEXT`) for the tests you change, avoid repeated full-suite runs, and run the full `zig build test -fno-incremental` once before finishing. Stop only your own processes, by PID.
Must not touch
- Do not touch music/, assets/music/, src/music_score.zig, `music.zig`, or `ambience.zig`. Never write to ~/.local/state/burrow/ or ~/src/save-burrow/ (use `--settings PATH`, `--save PATH`, or a temporary state directory for tests and captures).
Saves and the network
- Saved and boundary enums are append-only; a save layout change needs the next free `file_version` (main is at 11; another branch may take 12 — take the next free one when you merge main) with readers for older versions. A protocol change raises `net.version`.
Who else is working
- Other agents work in parallel: `iter/critters` (creatures, navigation, saving dens) and a separate session on the moon (`iter/moon-*`, `offworld.zig`). Keep out of those areas.
Before finishing
- Before finishing: `git merge main`, resolve conflicts, rerun `zig build -fno-incremental`, `zig build test -fno-incremental`, `zig fmt --check src/*.zig`, and captures proving the client starts. Commit with plain descriptive messages. - Update docs/brief.md for lasting rules and controls; no plan or report documents.
The owner’s words
## Why The owner, on a voice call: "A playable character studio — the playable characters, so you can edit them. Currently they are randomized: the hair, skin color, et cetera. My kids would love playing around with adjusting those kinds of things. Make it very, very good, intuitive, and fun."
What exists
Today a player's look is a seed derived from their identity (`party.zig` ~44: `s.player_look[slot] = @truncate(identity *% 0x9E3779B1)`) that `scene.zig` (~1730) and `sprites.zig` turn into hair, skin, clothes, and so on; `State.player_look` is a `u32` per player. Inspect exactly what the look seed decides (hair style and color, skin, eyes, shirt, pants, shoes, anything else) and what the drawing supports, and design from there.
The task
## Build a character studio 1. **The look as choices, not a seed**: a small look record (each trait an index into a palette or style list the art already supports, or that you add in the existing procedural style: more hair styles, hair and eye colors, skin tones covering a wide, respectful range, shirt and pants colors, maybe an accessory such as a hat or freckles if cheap and good-looking). Keep it compact on the boundary (it may still fit 32 bits or grow slightly; raise `net.version` if the State changes). A seed still produces a random look for players who never open the studio, so existing players keep looking as they do today unless they change it. 2. **Where it's saved**: the look belongs to the player, not the world, so the client keeps it with the player's profile on their own machine (next to the `player` identity file and `settings` in the state directory; a small `look` file or a settings section — keep the format as simple and forgiving as `settings`), and sends it when joining; the host uses it for that player in every world they join (solo and LAN), and changing it in game updates everyone's view. Decide whether the host should also remember it per identity in the world save (useful for a mannequin or a portrait) — only if it's cheap and clean. 3. **The studio itself**: a fun, discoverable, polished panel for kids: a big live preview of the character that idles, blinks, walks, and jumps (and can turn); categories with large clear swatches and style tiles rather than text lists; arrows or clicks to cycle; a **Randomize** button (a die) that rolls a whole new look with a little flourish, plus per-trait shuffle if it fits; **Undo** of the last change; satisfying sounds on picks (synthesized in `sounds.zig` to the existing loudness targets) and a small sparkle on confirm; works with mouse and keyboard and with a game controller (the pad focus system on main: rectangles register while drawing and the D-pad moves a gold focus frame; hints switch by device; read `ui.zig` and `pad_play.zig`); readable at the UI's scale. Reach it from the **title screen** (a "Character" button before entering the world, so a kid can make their character first) and **in game** (from the inventory's equipment column or a button near Settings, and maybe a mirror furniture item at home that opens it — only if it's quick and fun). Show armor and vanity on the preview as worn in game if the preview can draw it (a toggle "show armor" is nice). 4. **Gameplay continuity**: the look shows everywhere the player is drawn (the world, the lineup sheet, the map marker colors if any, co-op other players), and survives restarts.
Proof
Validation (focused): tests for the look record's encode/decode and its ranges, that an old identity-seeded look decodes to exactly today's appearance, that the profile file round-trips and tolerates bad values like `settings` does, that a joining player's chosen look reaches the host's State and other peers, and studio focus order with a pad. Captures under ~/.cache/tmp/opencode/studio/ (one at a time; read each PNG a moment after it is written): the studio from the title (add `--open studio` and, if useful, `--look SPEC` for captures), a few very different looks side by side (`--open lineup` or a studio sheet), the studio with pad hints, and the player in the world wearing a chosen look. Judge the panel against the Terraria character creator for clarity and charm (see reference/terraria/README.md for the UI baseline), but make it friendlier for children.
Final report
Final message: commits, the look record and what each trait offers, where it's saved and how it reaches the host, how the studio works (mouse, keys, pad), tests, captures, and anything to check with the kids.

Most of what I tell the main session is how something feels. When I said the world felt samey, its brief asked for a way to measure that, so an agent could show its change had helped. When I said the game’s moon felt flat and small, not like a planet, I got a larger moon with hills, and it still didn’t feel like a planet. Before the next try the main session asked me what I meant by a planet. You can walk all the way around the moon it built after that.

The first moon, at its landing: flat gray ground under a black sky, pale blue mountains behind, home hanging in the sky, and "The Pale Moon. Home hangs in the sky. Mind your breath" on screen.The moon made bigger and hillier: a steep gray peak and the rim of a basin, more gray hills behind, and home in the black sky. The same gray ground, only taller.The Pale Moon today in a freshly generated world: gray ground with craters and boulders under a black sky, the home world hanging in the sky as a blue and green globe, and the player standing on the rim.
The Dunes at noon in a freshly generated world: the player on the sand by an oasis pond with palms and cacti, a red butte rising on the right, banded buttes and a smoking volcano behind, and a torch-lit sandstone house buried in the dark earth below.

the Dunes

Keep everything in text

I keep as much of the game as I can in code and text, because that is what an agent can read and change. Burrow is written in Zig on top of Raylib, with no external game engine. It is about 220,000 lines of Zig.

A host process runs the world, and each player’s game sends it input and draws what comes back. The host builds without the graphics library, so tests can run the whole game without opening a window and play it the way a player would.

There are no sprite files either. Code draws every sprite when the game starts.

The game's sheet of item icons: 442 small pixel-art pictures, each in its own dark blue box, in a grid 24 across and 19 rows down, separated by thin light-blue lines. Ores, wood, bricks and blocks; furniture, chests, doors and lamps; swords, pickaxes, hammers, bows, wands and staves in copper, iron, gold, crystal and fire; potions in every color; armor and boots; fish of a dozen kinds, critters in jars and cages, bugs and birds; mushrooms, flowers, gems and keys; minecarts and rail parts. The last row stops after 17 boxes, on the game's dark ground.

An agent runs the game on a display of its own and looks at screenshots.

What the agent sees

Six frames from one recording of a boss attack, in a plain grid of three by two on white: in the red Ashen Depths, light breaks from the rock under the player's feet while the Cinder Wyrm's chain of ring segments coils below; the light flares; the wyrm's horned head bursts up out of the ground into her; and it rears up high above the floor, its body trailing down into the dark.

What I see

In the first screenshot of Burrow, an agent saw dark squares behind the treetops, and it fixed two lighting bugs before its first commit.

In my earlier games I ended up building tools to make the music. Studio is one of those tools, a music program pulled out into a project of its own the week before I started Burrow. An agent writes a song as a file and renders it, and I can open the same file in Studio and play it. My son and I also use it to practice piano.

Studio's arrange page with Burrow's boss theme, Queen of Moths, open: eighteen tracks for strings, brass, winds, timpani, and percussion, with sections named altar, queen, brood, dive, lull, climb, rage, and turn and a row of chords above, at 144 bpm in C minor.

0:00 / 2:13

Queen of Moths

My son kept complaining about the first soundtrack, which was all synths in an 8‑bit style, so I restarted the score from scratch with mostly orchestral instruments. Then I missed the 8‑bit sound, so two of the pieces that play at home also have an 8‑bit version.

The score

Our family's tower on a clear morning: five storeys of rooms with chandeliers, beds, bookshelves, a glass stair room, an emerald on a pedestal, and glowing blue mushroom roofs, townsfolk inside; on the balcony at the top right the player in a crown, where a railway track leaves east toward floating islands. Lamp posts, a bench, and a tent on the terrace by the east door, mountains and pine forest behind under a blue sky.

Home

Plays near the player’s home, by day or by night.

0:00 / 2:49

Hearth

Home and the town

Home
The bard’s dance
A visitor’s fire

The surface

The forest by day
The surface at night
The Shore
The Frozen Reach
The Dunes
The dry canyon
The Tangle
The Lantern Wood

The sky

The Sky Isles
The sea of cloud
The Wind Keep

Caves and depths

Underground
Lantern Grotto
The Glowcap Marsh
The Glowshroom Hollows
The Sunken Halls
The Ashen Depths

Landmarks

The Great Tree
The Smoking Mountain
Ravenhold
The Sunken Temple
The Underworld City
The market ward

Rides

The rails
The Deep Ride

The far shore

The Lantern Shoals
The High Caps
The Gill Hills
The Ink Flats
The Quiet

The Pale Moon

The Homeward Seas
The Highlands
The polar lands
The Ray Fields
The Far Side
The Great Basin
The Undermoon
The selenite caverns
The moon’s ice caves
The moon’s deep
The Moth Lantern

The moon’s ruins

The ice works
The long stair
The sealed door
The last garden

Fights

The Moth Queen
The Cinder Wyrm
The Hollow Warden
The Lantern Keeper
The Veilmother
Old Gale
The Raven King
The Sun Idol
The Ash King
The Ash King’s rage
The Rumbler

Moments

The title screen
The Ember Moon
The Moonwell
Stings

An agent can’t hear the music, so it measures the rendered audio and reads its spectrogram.

A spectrogram of the 8-bit home theme, the whole piece: frequency over time in red and yellow, with the chip pulse's harmonics as thin horizontal lines in the middle section.

0:00 / 2:52

Hearth (8-bit)

In another piece, a horn that was supposed to sound distant measured as the loudest part.

The Glowshroom Hollows underground: a giant glowing blue mushroom with a spotted cap stands in a cave of dark blue stone, a row of smaller caps stepping down beside it, more caps on the ledges to the left under green glowing brood bells hanging from the rock, a small glowing mushroom creature on the cave floor, and specks of light drifting in the dark; below the floor the cave falls away into black.

the Glowshroom Hollows

Playtesting with the kids

On the first day the tests said the grappling hook worked, and it did, when worn in an accessory slot. I carried it in the hotbar, pressed the grapple key, and nothing happened. Five minutes after I reported it, the hook worked from the hotbar too.

When my kids put on iron armor, it turned the character they had made into a gray block with a helmet over its face, and they didn’t want to wear armor at all. I asked for armor that hides less, and the helmets became open-faced.

The same character in iron armor beside a sunflower on a grassy hill, before and after: first a gray suit with a full helm that hides her face, then an open-faced helm that shows her face, her braid, and her green shirt. Opened, the picture shows a third panel as well, with the helm hidden and her crown and braid above the same armor.

We fought the giant moth several times just to get everyone a pickaxe. I asked for that to change, and a boss now gives every player their own rewards.

Home's forest at night, under a dark blue sky with mountains and tall trees: the Moth Queen, a giant purple moth with orange eyespots on her wings, hovers high over the player in armor, who swings a sword from the grass. A ring of light closes round her as she warns, and she dives down through the player and on into the ground, trailing purple dust; the screen flashes red as she hits. She bursts up out of the earth again inside a ring of light, wheels overhead dropping glowing spores, dives again, and a townsperson runs up beside the player as the fight goes on.
Inside the gill hall of the Mother Cap, a giant mushroom: a dark hall under a roof of mushroom flesh, columns of misty light rising from breathing mouths in the floor. The Veilmother, a huge pale jellyfish-like dome with a ring of six eyes and hanging tendrils, hangs from the roof. Her eyes light and her dome glows; the player in armor walks under her and the breath from the floor lifts her up to the dome, where she hangs at its side striking it with a sword. Then the eyes close one at a time, left to right, a ring of light marking each as it shuts, and arcs rise over the mouths in the floor. As the last eye closes the breath stops: the player drops to the floor, flashing red where she lands, and bursts of spores break along it.
On the Ember Moon at night, on the summit of a volcano beside a dark brick tower, the player in armor stands with a sword under a red sky, home hanging in it as a blue and green globe. The Great Flare, a living ember with a crown of flame and wings of fire, bursts out at the tower and draws a burning line through her, then dives along it. It wheels round the summit, swells white high above her, and blazes: white-gold rays pour down over everything. It draws its line through her a second time; she leaps into the air and strikes it with her sword, and the dive misses her.
On the Pale Moon at night: gray dusty ground and rock spires under a black sky full of stars, a small white sun, and home hanging in the sky as a blue and green globe. The player in armor stands on the balcony of a tall moonstone tower, the Moth Lantern, swinging a sword. The Lantern Keeper, a glowing white winged creature of crystal, wakes on the tower in rings of light, flies out round it, and glows; thin lines of light drop from the sky to marks on the balcony and the ground, and stars fall along them. It wheels round the tower and calls the stars down again, and one lands on the player in a red flash.
In a hall of dark blue stone brick in the Sunken Halls, lit by small lamps and glowing glyphs, the player in armor fights the Hollow Warden, a stone knight twice her height with a tall shield, a hammer, and a crown of glowing spikes. Its hammer glows as it raises it, and it slams the floor; the player is struck. She backs away; it raises the glowing hammer again and slams, sending shockwaves along the floor both ways, and she leaps over the one coming at her. Then it charges across the hall behind its shield, knocks into her, and she turns and strikes at its shield.

My kids and I built a railway. It runs from the balcony of our house out to a station on an island in the sky, and back.

One round trip on our railway at dusk. The player gets into a minecart on the tower’s balcony and rides east: up a ramp of boosters beside a brick staircase, through the trunk of a giant tree, round a loop, and into a station hall on an island in the sky. On the way home the cart runs along the high line, leaves the end of a ramp, falls past the mountains and lands on the track below, which runs back to the balcony.

After playing with it I told the main session to go all in on trains. Before designing anything, an agent opened a copy of our save and went over the railway. Beside the ramps it found staircases of bricks, and near home it found booster rails pointing backwards. It read the stairs as where we stood to lay the next rail and the boosters as our brake.

Our railway at noon, close: a ramp of track with gold booster arrows climbs to a grassy island in the sky, and beside it a staircase of dark mossy brick steps zigzags up to the same island.

There is a brake rail now, and you lay a run of rail by dragging. Our railway as it stood that day went into the tests. They take the ride out and the ride back separately, and check that the cart lands and stops where it did then. I’ve tested the new trains. They work okay, and some of the interactions are a bit janky.

The Frozen Reach by day in a freshly generated world: a frozen lake with pines on its shore, penguins on a blue ice rock, the player on the bank, light snow falling, and snowy mountains behind.

the Frozen Reach

Remaking the world

In the first days I kept changing how worlds are generated, and my kids were mostly about playing the one world we had started. So the game keeps track of what we build and dig. When the layout of the world changes, it makes a new world from the same seed and puts our house and whatever else we built into it, with our chests and the townsfolk who live with us. Then it says “The Valley Has Changed” and, under it, “Your home stands”.

I told the agents that the only important thing to keep is the house. The rest can change. Later the map got wider, and across the eastern sea there is a mushroom country. From our beach you can see its largest cap on the horizon.

Rowing east across the sea at dusk in a freshly generated world: the player in a small rowboat on calm water, and ahead a giant mushroom with a lit dome rising over sea stacks.
The High Caps at first light in a freshly generated world: under a deep blue dawn sky, the player steps off the deck of a giant mushroom cap and drifts slowly down past the gold-lit brim of the next cap to the glowing turf below.
The Gill Hills at noon in a freshly generated world: a column of pale green light breathes up from a dark mouth in the scaly hills; the player walks into it, is thrown up the column, and drifts down beside it among small pale moths.
The Mother Cap at night in a freshly generated world, from below: an enormous mushroom on one thick stalk, its hollow underside lit by five shafts of pale light with spores drifting in them, above a dark forest.

In November the kids added stone steps outside our door and picture frames on the shelf.

Inside our tower at night: a glass-walled stair room with a bed and a chandelier, an emerald on a pedestal with a townsperson asleep beside it, and a shelf of eight picture frames over chests, one holding a glowing blue mushroom. Below them, the workshop with an anvil and a furnace, where the miner stands by the fire.

We usually play over the network at home, where I host the world and my son joins from his laptop. He wanted to show Burrow at school, so I made a second launcher for his laptop that starts a fresh world and doesn’t save it.

Terraria is a better game for most people. The point of Burrow, or of any personal software, is that it’s better for you. Nobody else will probably ever play this, but that’s fine.