Subterrans devlog

The ants learned to be afraid

Sun, 19 Jul 2026 00:00:00 GMT

The last post was about the controls — making the game answer to the player. That shipped in late June. The month since has gone in two very different directions at once.

One is the interesting one: the ants got a relationship with danger. They can be frightened now. They run from things, they route around things, and — as of this week — they eat the things that die. That is four sim versions of genuinely new behavior, and it changes how a round feels.

The other is the unglamorous one: I had the codebase reviewed against where it is actually going, and that review turned into about thirty pull requests of structural work. Seven sim versions landed in total — V31 through V37 — along with the groundwork for touch, a real performance pass, and a licensing decision I want to explain properly.

The ants learned about danger

Before this month, an ant’s relationship with a threat was binary and late: it was fine, and then it was in a fight. There was one exception — the spider’s reticle made nearby workers scatter — and that was it. Danger existed as a pheromone on the grid, but almost nothing read it.

Four changes fixed that, in order.

Fleeing and the idle reserve (#285, V34). This started as a bug report that the colony “looked hung”: when food storage filled up, surplus workers stopped having anything to do and froze in a motionless clump. They now mill around the entrance in a deterministic wander so the clump breaks up, and — the real addition — when the danger pheromone above them spikes, they dash for shelter down the nearest open entrance, hold at the shaft, and poke their heads back out once the danger overhead decays. There’s a nice detail in the safety logic: an ant only flees home if home is safe, so a panicking worker never sprints toward a spider parked on its own doorstep. The same PR added a cross-colony alarm — when an enemy kills one of your surface workers, that death seeds a danger mark on your pheromone grid. Your colony finds out that somewhere is dangerous by losing someone there, which is exactly how it should work.

Risk-aware foraging (#291, V36). Fleeing is a last-second reaction. This is the anticipatory version: a forager choosing its next step now weighs the food trail against the danger trail at each candidate cell. A spider sitting on a supply line visibly bends traffic around itself instead of just generating a stream of panicked flees. Crucially it is a soft bias rather than a wall — a strong enough food trail will still pull ants through mild danger. That trade-off is the whole point. Ants that refuse all risk starve.

Battlefield scavenging (#292, V37). Merged this week, and my favorite of the four because of what it does to the other three. Surface combat deaths now drop forageable food where they fall. An enemy killing one of your ants leaves a pickup; killing the spider leaves a hundred — a genuine windfall for finally bringing it down. Deaths underground, brood deaths, starvation, and anything the spider eats drop nothing.

Put those together and you get an actual dilemma. A battle leaves food on the ground. The battlefield is also, thanks to V34, the most danger-marked patch of the map. So the pile your foragers most want is sitting exactly where V36 tells them not to go, and the value of going anyway scales with how big the fight was. The greed-versus-fear crossover is now a real thing you can watch happen, and it emerged out of three separately-designed mechanics rather than being scripted.

Underground idle wander (#286, V35) rounds it out — the same de-clumping for surplus workers below ground. That one has a story of its own.

The 44% regression nobody could see

The underground wander should have been trivial: it is the surface milling from V34, applied to the tunnels. The first implementation did exactly that, and it passed everything. Every unit test green. Determinism intact. Replays byte-identical. Code review clean.

It also cut the AI colony’s economy by about 44%.

The cause is a rule that only bites underground: same-colony ants are one per tile. Idle workers wandering through tunnels were bumping productive foragers and diggers off their routes — thousands of tiny displacements a round, each individually invisible and collectively catastrophic. On one seed the AI colony went from 23 workers to 1.

Nothing in the test suite could see it, because nothing was wrong. The sim was correct, deterministic, and reproducible. It was just much worse. What caught it was a paired seed sweep — run eight seeds on the old version and the new one, twelve thousand ticks each, and compare the colonies that come out the other end. Five experiments narrowed it down, and the fix was to confine the wander to chamber footprints, which happen to be exempt from the one-ant-per-tile rule and are also exactly where the frozen clumps were in the first place. Post-fix the same sweep came back at a 1.05 worker ratio — slightly better than before, no colonies dead.

I think this is the most useful thing I have learned in months of building this way. I have a lot of gates: type checking, lint, thousands of unit tests, determinism proofs, byte-identical replay, two external AI reviewers on every PR. Every single one of them passed a change that would have quietly ruined the game. Correctness gates cannot see badness. The only thing that caught it was running the actual game a lot of times and looking at the outcome — and that is now a standing part of the process for anything that touches ant movement.

An architecture review, and the month it caused

At the start of July I stopped shipping features and had the whole codebase reviewed — not for bugs, but against where it is going next: bigger maps, mobile, and networked play. That produced about twenty tracked issues, shipped over three waves.

The review found real bugs, which is the part I did not expect. The spider was ignoring surface passability and walking through terrain it should not have (#248, V31). The AI’s operations were never validated, so a malformed one could be issued and quietly do something incoherent (#249, V32). The occupancy resolver left shifted ants slightly off tile center (#251, V33). And at 2× and 4× speed, ants were snapping between positions instead of interpolating, because the smoothing divided by a constant tick period rather than the live one (#246) — a thing I had been looking at for weeks without registering as a bug.

The rest was structural. Simulation scratch buffers that lived as process globals became owned by the world (#255), so two simulations in one process can no longer contaminate each other. The command pipeline got a single chokepoint with provenance and overflow visibility (#259). Three batches went into reaping dead compatibility gates (#260, #261, #262) — every old sim version that no accepted save could still reach was branches the code no longer needed to carry. Saving got tougher too: an async storage seam, a caption when an autosave fails instead of failing silently, and validation of loaded data rather than trusting it (#264, #266, #267).

And a proper performance pass, mostly on things that ran every tick without needing to: the per-tick brood-field rebuilds are now gated on whether the brood actually changed (#257), the pheromone overlay is LOD-gated and cached (#276), detailed-mode drawing reuses scratch buffers instead of churning allocations (#277), and the static minimap layer is baked once into a texture rather than redrawn every frame (#280).

Two engines, one hash

The single result I am happiest with is small and hard to screenshot. Subterrans has always been deterministic — same inputs, same round — but that was only ever proven within one engine. #253 runs an identical three-thousand-tick scenario in Node and in headless Chromium and requires the two worlds to hash to the same bytes. #283 added WebKit as a third.

That matters because everything interesting on the roadmap depends on it. Mobile means running the sim inside a WebView. Networked play means two machines stepping the same simulation and trusting they stay in agreement. Both assume the engine underneath does not change the answer. That was an assumption; now it is a test.

Getting ready for fingers

The controls post said touch was a later phase. Five PRs of groundwork landed anyway (#271–#275): a two-pointer state machine so a second finger is visible at all, pinch zoom over the camera built last month, a drag threshold that scales with zoom, long-press to open the chamber menu, and a press-and-hold hover preview — because touch has no hover, and the green/red placement cues from the controls rework are load-bearing enough that they needed a touch equivalent.

None of it is switched on as a shipped mobile mode. But the input layer no longer assumes a mouse, which was the actual blocker.

Anyone can ship it to an app store now

One non-code decision worth explaining. Subterrans is AGPL-3.0, which is a strong copyleft license and stays that way. The problem is that AGPL’s “no further restrictions” clause conflicts with app store terms — DRM, device limits, mandatory ToS — which is the old VLC-on-the-App-Store problem.

The usual fix is a contributor license agreement: consolidate the copyright, then ship your own official binary under different terms. That works, and it means only the copyright holder can do it. I did not want that. So Subterrans now carries an AGPL section 7 additional permission granted to everyone (#287) — anyone can build and distribute it through an app store, as long as the full source stays available under the AGPL. No CLA, no signing gate, and because contributions come in under the same terms they go out under, external contributors get it automatically.

The game stays copyleft. Nobody needs my permission to put it on a phone. That is the right shape for this project.

What’s next

The honest state of things: the simulation is in better structural condition than it has ever been, the ants are meaningfully smarter than they were a month ago, and there is now a real dilemma on the surface that I did not design directly — it fell out of three mechanics meeting.

The next open question is a big one, and it is about map size. Several of the remaining architecture items are blocked on deciding how large a world Subterrans should support, because that decision changes how terrain is stored and streamed. Everything else is queued behind it.

In the meantime, the corpse-food economy needs a tuning sweep — the same kind of paired seed run that caught the 44% regression, this time asking whether a defender reclaiming its own dead makes losing a fight too cheap. As ever: play it, lose a round, and the playtrace tells us both what happened.

Getting out of the player's way

Sat, 20 Jun 2026 00:00:00 GMT

The last post was about making Phase 3 correct. This one is about making it playable — which turns out to be a different problem.

The simulation was solid. The way you talked to it was not. The old control scheme had grown one mechanic at a time, and it showed: the left and right mouse buttons each did three or four different things depending on which view you were in and what was under the cursor. Panning was hold-Space-and-drag. Game speed lived on the 1, 2, and 4 keys. Zoom did not really exist. None of it was written down anywhere in the game, and most of it you could only discover by accident. It worked fine for the one person who built it and was close to unlearnable for everyone else.

So the controls got a rework — four stages of it, issue #18, shipped over about a week. The whole point was to get the interface out from between the player and the game.

Stage 1: a tool palette and one honest gesture

The root problem was overloading. A single click meant “give an order” or “pan the camera” or “dig a tile” or “open a chamber menu” depending on context, and the player had no way to know which without trying it.

Stage 1 (#210) split that apart into three explicit tools — Command, Dig, Chamber — on keys 1/2/3, each with its own cursor and highlight, each resetting to a sensible default when you switch views (Command on the surface, Dig underground). Now the cursor tells you what a click will do before you click.

Underneath the tools is a single left-button gesture arbiter with one rule that holds everywhere: tap to issue a context order, drag to pan — the one exception being the Dig tool underground, where drag paints tiles. One code path decides tap-versus-drag, and one cancelGesture() cleans it up on every tool switch, view switch, menu open, and phase change, so a half-finished drag can never leak into the next thing you do. Hold-Space-to-pan is gone; Space is now just pause/resume, and game speed moved off the number keys onto a proper HUD widget (with =/- for the keyboard).

The Command tool keeps the parts that were actually intuitive — tap a food pile to forage it, tap your nest to rally, tap an enemy to attack — but now they live behind a tool you chose on purpose, instead of being one of four things a click might have meant.

Stage 2: a camera that actually zooms

Stage 2 (#215) added the thing every strategy game is expected to have and Subterrans did not: continuous, Google-Maps-style zoom and smooth pan, in both the surface and underground views, with the zoom anchored to the cursor so the map grows toward whatever you are pointing at.

Making that smooth meant changing how terrain is drawn. Re-rendering every tile every frame at every zoom level is wasteful, so terrain is now baked into a render texture once and only the tiles that actually change — a freshly dug tunnel, a new entrance — get re-stamped, tracked by a dirty set. The camera just zooms and pans over the baked image. When you zoom all the way out to see the whole nest, individual ant sprites would be sub-pixel noise, so they collapse into a batched dot layer with a little hysteresis so the swap does not flicker at the threshold.

The felt result is that you can now read the whole battlefield at a glance and then dive into a single tunnel fight, without the camera fighting you on the way. The strategic view and the tactical view are the same view at different zooms.

Stage 3a: the game shows you your own commands

This is the stage I am happiest with, because the idea is simple and the effect is large: the game should show you your own commands.

Two things came out of that (#217). The first is feedforward validity: when you are aiming a placement tool — a chamber, a tunnel, an entrance — the target tints green if the command is valid, red if it is geometrically impossible, and grey if your command queue is full. You know whether the click will work before you commit to it. The second is the paused-queue preview: when you pause, the orders you have queued but that have not been applied yet are drawn as ghosts, so you can see what hitting resume will actually produce.

The trick that makes this trustworthy is that both the cue and the real command are computed from the same projected world — a clone of the game state with your entire pending queue folded through the real command handlers. The preview is not a separate “what I think will happen” guess that can drift from the truth; it is the truth, run one step ahead. Green never lies, because the same code that paints it green is the code that would execute the order.

Doing this honestly required one carefully bounded change inside the simulation: the block of code that applies queued commands during a tick was lifted out into its own function so the renderer could call it on a throwaway copy of the world. The behavior is byte-for-byte identical — proven by a golden test that captured the exact output before the refactor and replayed it after — so determinism and replay are untouched. (More on why that mattered below.)

Stage 3b: controls that teach themselves

The last stage (#218) closed the loop the intro opened: a new player should discover pan, zoom, view-switching, and the tool palette without a manual or a tutorial wall.

That’s three reactive surfaces, all drawn through one device-glyph resolver so the hints can never disagree with the real bindings. There’s a hint strip that composes its text from the actual key glyphs rather than hardcoded labels; one-time, cross-session first-use nudges that fire on the effect — the first real pan, the first accepted zoom, the first dig-drag that actually enqueues marks — plus a gentle [Tab] prompt to discover the view toggle on your first input of a session; and hover tooltips on every control widget, including the ones whose purpose isn’t obvious (the stats panel tooltip teaches that you can click it for ant activity). All of the captions route through a single queue with an explicit policy about what preempts what, so two hints never stomp on each other and a nudge that gets dropped under load un-marks itself and fires again later.

The nice part is that none of it nags. Each hint shows once, when the moment is right, and then never again.

The discipline: the simulation never moved

The throughline across all four stages — and the constraint I am proudest of holding — is that this was render-only. A complete overhaul of how the game looks and feels, and git diff main -- src/sim is empty for three of the four PRs. The fourth moved exactly one block of code without changing what it does, with a golden test to prove it.

That matters more than it sounds. Subterrans is deterministic: the same inputs always produce the same round, which is what makes saves, replays, and the playtrace data from the demo trustworthy. If the controls rework had reached into the simulation, every one of those guarantees would have needed re-checking. Keeping the line between “how the game is presented” and “how the game is computed” clean meant a week of UI work cost the sim exactly nothing. The tool palette, the camera, the previews, the teaching layer — all of it is a new lens on the same untouched machine.

What’s next

The controls were the last thing standing between the demo and a stranger’s hands. The simulation is correct, the round has shape, and now the interface explains itself instead of needing me next to you to translate. So the question from the last two posts still stands, just with the excuses removed: is it fun for someone who did not build it? Play it — and now you should not need me to tell you how.

Sanding down Phase 3

Sat, 06 Jun 2026 00:00:00 GMT

Phase 3 shipped ten days ago. The game has a beginning, a middle, and an end now. That post was the exciting one — seven mechanics, a round with shape, the first time the AI felt intentionally hostile.

This is the other kind of post. The ten days since were not about adding anything. They were about making what shipped actually hold up: pathing that is correct instead of approximately correct, a spider that behaves the same at the map edge as it does in the middle, hot paths that do not allocate, tests that run in CI instead of rotting, and one balance bug that was quietly starving colonies. None of it is visible as a feature. All of it is the difference between “it works in the rounds I played” and “it works.”

Here is what landed.

The spider got meaner, and better-behaved

The spider was the headline mechanic of Phase 3, and it was the part most likely to embarrass me under observation. Most of this stretch went into it.

It now has a chase reflex and the fighters around it have sight-based auto-aggression (PR #172): the spider commits to a target instead of dithering, and fighters who can see it engage on their own. It got a health bar above the sprite (#175) so that “is this fight worth it” is a question you can answer by looking, instead of guessing.

Then the edge cases. The spider’s feed-retreat used to walk it off the map; now it reflects inward at the edges (#176), and it keeps a margin from the boundary so its sprite never slides half-off-screen (#191, sim version V26). Its gate-hold behavior used to be able to pin the queen herself; that is now excluded, and there is a start grace period so the spider does not ambush you in the opening seconds before you have any fighters (#178). And the rampage notification, which used to fire once and then stay quiet through later rampages, now fires on every rampage — and lost the leftover “tunnels” copy, since the spider never goes underground (#202).

That last one is a small thing that says something true about building under observation: the copy described behavior the spider does not have, and it sat there until it was read by someone who would notice.

The invasion finally paths correctly

Phase 3’s combat made tunnel geometry matter. The problem was that the invaders did not always respect the geometry they were supposed to be fighting through. A bent underground tunnel could leave an invader stuck against a wall, because the descent logic assumed a straighter path than the dig tools let you build.

Invaders now route through bent underground tunnels via BFS (#171), descent is gated on entrance blockers so you cannot descend into a hole that is not actually open (#169), and foreign-grid recall now keys on the rally point rather than the fight ratio (#189, V25) — which is to say, fighters come home based on where you told them to go, not on a number that happened to correlate with it most of the time. The flow-field caches that drive all of this got scoped per-world (#168) so that two simulations running in the same process cannot poison each other’s pathing — which matters for both the AI and the test suite.

The starvation bug

The one genuine balance bug in this stretch: colonies were starving for a reason that had nothing to do with the player’s decisions. Larva maturation was set to 2400 ticks, slow enough that the food-to-workers pipeline could not refill the workforce fast enough to keep the food coming in. The colony would tip into a spiral that looked like a strategy failure but was actually a constant.

Dropping maturation to 1500 ticks (#180) fixed it. The reproduction loop described in the last post — surplus feeds eggs, eggs demand nurses, nurses cost foragers — only reads as a real trade-off if the loop can actually close. At 2400 it could not. This is exactly what the playtraces are for: the loss-cause ledger kept reporting starvation in rounds where starvation should not have happened, and that pattern is what pointed at the constant.

Alongside it, the nursery deposit became capacity-aware (#183, V24) so brood is not deposited into a nursery that is already full, which was the other half of why the pipeline stalled.

Performance, where it actually matters

Combat and the per-tick update are the hot paths — they run for every ant, every tick, in both simulations at once. They were allocating objects inside those loops (#170), which is the kind of thing that is invisible until the colony gets large and then is the whole problem. Removing the per-tick allocations from the combat and tick hot paths is the unglamorous performance work that keeps late-game rounds smooth.

Tooling, tests, and save robustness

A lot of this stretch was paying down the kind of debt that does not show up in a screenshot.

The codebase adopted Prettier and normalized formatting repo-wide (#184), then added a type-aware ESLint layer (#185) that catches a class of bugs the basic linter cannot see. A verify + coverage workflow went into CI (#187), and after some honest accounting, coverage got recorded as intentionally local-only rather than pretending it was a CI gate it was not (#199).

The end-to-end suite had rotted during the v3.0 mechanics work. It got restored and gated in CI (#195), then the flaky speed-cycle and pheromone tests got de-flaked and un-quarantined (#200) so they are real signal again. The save-flow tests were reworked around real captured saves instead of synthetic fixtures (#197), and a genuine save bug got fixed along the way: future-build saves now survive a fresh boot instead of being silently discarded (#198).

The F9 debug snapshot got a self-describing guide block (#182) so a captured snapshot explains its own fields — useful when a player sends one in and I am reading it cold. And the architecture docs got a refresh for the post-Phase-3 state (#201), because the map should match the territory after a phase that changed this much.

A note from the desk

People ask what it is actually like to build a game this way — AI-driven development, one person, a stack of pull requests a day. The honest answer is that most of it is what you just read: small, correct, unglamorous changes, one after another, each one closing a gap between “works in the rounds I played” and “works.” Claude does a lot of that closing. I describe the gap, we argue about the fix, it writes most of the code, and I keep the taste and the no’s. It is the most productive I have ever been, and the part of the work that is most genuinely mine is the judgment — which is the part I wanted to be doing anyway.

It also helps that, this week, the desk looks like this.

I’m in Hawaii for the week — not where I normally work, but the laptop came along, and a stack of PRs doesn’t care what’s on the other side of the railing. A bay, a papaya tree leaning into frame, the water doing the thing the water does. It doesn’t make the starvation bug any easier to find. But it’s a genuinely good place to go looking for it.

What’s next

This was a hardening pass, not a phase. The next real question is still the one the last post ended on: is the round fun in the hands of someone who did not build it? The systems are correct enough now to trust the playtraces. Play it, lose a round, and the sim will tell both of us how.

Phase 3 shipped: it's a round now

Wed, 27 May 2026 00:00:00 GMT

Phase 3 is done. Two colonies, a neutral predator, a deterministic AI that invades on its own, real combat math, a reproduction lever, difficulty tiers, and a polish pass that makes the events legible. The design post from ten days ago described what it was supposed to be. This is what it actually turned out to be.

The short version: it is all there. Seven mechanics, eight implementation stages, seven sim-version bumps (V16 through V22). The game is now something that has a beginning, a middle, and an end. A round has shape. That is a different thing than what existed before.

What changed in combat

Before Phase 3, two ants meeting on the same tile resolved combat by coin flip: one died, one lived, repeat. Numbers barely mattered. Position did not matter. The home colony had no meaningful advantage.

Phase 3 replaced this with a deterministic multi-tick model. Each ant has HP and a damage-per-strike, and home-ground ants get a 25% buff to both. A home defender at a tunnel entrance wins reliably against a single invader — not sometimes, always. Two invaders at the same chokepoint still beat one defender, because replacement depth means the second attacker inherits a wounded opponent. Three invaders beat the defender and barely lose anyone. The math is exact enough to plan around.

The practical effect is that tunnel geometry matters now. A narrow underground passage is defensible in a way it was not before. The decision about where to put the queen chamber relative to your entrances is a real decision. Widening a tunnel to speed supply trades directly against its defensibility. This was theoretically true before; now the numbers support it.

One thing that was not in the original plan: after combat shipped, a follow-on pass added sight-based fighter aggression. Fighters who see an enemy within range now initiate without being directed. The behavior ratio still governs how many fighters you have, but they are no longer passive — they engage what they find. This made the surface feel alive in a way the original plan underspecified.

What changed with the AI

The AI in Phase 2 foraged. It built its colony, occasionally its fighters ended up in the same space as your fighters, and things happened. It was never planning anything. The game outcome was whoever got unlucky on coin flips while running roughly parallel processes.

Phase 3 gave the AI a named state machine: Peacetime, War Footing, Probing, Invading, Recovery. The transitions are driven by conditions in the sim — fighter count, food storage, round age, your colony size relative to theirs. The AI enters War Footing when it is ready and starts sending small probe raids — three fighters toward a surface food pile, not toward your queen. If the probe succeeds, it comes back at scale. If it fails, it recovers and tries again.

The first time I saw a probe raid while the AI was in War Footing was the first time the game felt genuinely hostile. Not randomly hostile — intentionally hostile. There is now a reason to watch what the enemy colony is doing, not just your own.

The loss-cause ledger was spec’d as a low-key requirement in the design plan. It ended up shipping as its own PR and becoming more central than expected. The game-over screen now tells you specifically how you lost — the enemy fighters broke through, the spider rampaged your nursery, your queen starved — using actual sim event data, not placeholder text. That one detail made losing feel informative instead of opaque. Players need to know what went wrong. Generic “you lost” is a dead end.

What changed with the spider

The spider is a neutral predator with a hunger clock. It wanders the surface on a ~60-second hunt cadence and places a red reticle on its target tile 6–8 seconds before striking. Workers self-scatter away from the reticle. If enough fighters arrive within engagement range, the spider retreats. If not enough arrive, they die.

The design intent was that ignoring the spider is viable but costly: it picks off workers slowly, which compounds over a long round. Engaging it costs fighters and attention. The actual dynamic in play is that the reticle creates a recurring decision — every hunt cycle, you choose whether to respond. Most rounds you do not respond directly; you just route around it or accept the occasional worker loss. But at higher hunger levels the spider rampages into the nest, and that is immediately and visibly catastrophic. The hunger ring on the spider sprite (a color gradient that intensifies as hunger builds) is the only cue. If you are not watching it, you get surprised.

The right-click command to designate the spider as a priority target shipped last, in its own cleanup stage. It was deferred from the spider’s initial implementation to keep that PR focused on the sim foundation. By the time it shipped the mechanic was solid enough that adding the input felt like filling in a blank rather than making a design decision.

Reproduction and difficulty

The reproduction lever ties food surplus to egg-laying speed. When your food storage is high relative to colony size, the queen lays faster. Nurses in nursery chambers accelerate larval maturation. Nursery capacity caps the throughput. The three levers interact: more surplus → more eggs → more demand for nurses → fewer foragers → slower surplus accumulation. The cycle regulates itself if you let it.

This was the mechanic I was most uncertain about before Phase 3. In isolation, “food surplus accelerates growth” sounds like “just stockpile food and win.” In practice, the food-to-workers pipeline has enough latency and enough competing demands that it reads as a real trade-off, not a stat to maximize.

Difficulty tiers shipped as Easy/Normal/Hard and apply two independent axes: asymmetric modifiers on both colonies’ economics and combat (AI gets buffed, player gets nerfed, or vice versa) and symmetric world-pressure changes (spider hunger interval, food pile respawn rate). Normal is balanced for a player who has played two or three rounds. Easy gives enough margin to learn the systems without constant punishment. Hard is hard.

What this unlocks

Phase 2 was a proof that the simulation worked. Phase 3 is a proof that the game loop has the right shape. A round now has pressure that escalates, decisions that compound, and outcomes you can explain after the fact.

The honest next question is whether the game is fun in the hands of someone who did not build it. That is what the demo is for. Play it and use the feedback form at the end. The sim produces a playtrace for every session — loss reasons, decision points, where the round broke. That data is going to drive Phase 4 tuning.

A new roadmap

Sun, 17 May 2026 00:00:00 GMT

We have reorganized the roadmap. Versions are out; phases are in. Phases describe what we are building. Versions describe where we are. Those are different questions, and the old roadmap was trying to answer both with the same label.

Where we are

Subterrans is around v0.2. The simulation runs. Two colonies, pheromone trails, foraging, combat, a rule-based AI opponent. You can play a round end-to-end and lose to the enemy queen.

What rounds do not yet have is shape. There is no middle. You dig, forage, and fight until one queen dies. That is a loop, but it is not yet a game — there is nothing that builds pressure, no moment where the match turns, no point at which the right decision earlier becomes visible as the right decision in retrospect.

That is what Phase 3 is for. More on that in a companion post.

Where v1.0 is

Version 1.0 is feature-complete and genuinely fun. Not a date. A destination. The phases between here and there are the things we have to build to know whether the game is actually fun, and to fix it if it is not.

That framing matters. The old roadmap listed v1.0 as a milestone we had already shipped — the PRD and architecture phase. That was wrong in a way that mattered: it implied more progress than there was, and it made “v2.0” the new thing instead of acknowledging we are early in a long arc. The new numbering is honest. We are around v0.2. We know what we are building. The destination is clear.

The phases

The roadmap page has the full detail. Short version:

Phase 1 — PRDs & Architecture. Shipped 2026-04-14. Requirements and architecture for the seven essential systems.

Phase 2 — Playable POC. Shipped 2026-04-28. The simulation runs in a browser with two colonies and a functional game loop.

Phase 3 — First Real Round. In implementation now. Seven mechanics that give a match a beginning, middle, and end.

Phase 4 — Yard Scale. The world grows from one patch to a yard of connected territories with biome diversity.

Phase 5a — Sensory Pass. Audio and pixel art. The game starts to feel like a finished product.

Phase 5b — Variety Pass. Additional predator types, multiple map seeds, expanded round configurations.

Phase 6 — Mobile. Touch input and a performance budget for mid-range phones.

Phase 7 — World & Social. Castes, weather, day/night. Multiplayer is also here, framed as exploring — see below.

Version 1.0. Feature-complete, genuinely fun.

What changed from the old roadmap

Three things came off the list or moved.

Yellow Ant is removed. Direct control of a single ant, SimAnt-style, was on the old roadmap as a planned depth feature. It is not in any current design. The game’s interesting design space is in colony management, not individual control. Removing it is not a concession — it is an honest accounting of what the game is.

Castes, weather, and day/night have moved. They were filed under “Beyond v2.0” with no home. They now belong to Phase 7 — World & Social — which gives them a place in the sequence without implying a timeline.

Multiplayer stays, framed correctly. It is in Phase 7, labeled as “exploring.” The architecture preserves the option — deterministic simulation, replay logging, the whole foundation — but no design work has started, and a commitment to ship multiplayer before we know whether the single-player game is fun would be the wrong commitment to make. It is on the roadmap to anchor future architectural decisions. It is not a promise.

The point

Working in phases keeps us honest about scope. Each phase has a question it is answering. Phase 3 asks whether a round can have shape. Phase 4 asks whether the world can have scale. Phase 5 asks whether the game can be felt as well as played. Each question has a real answer, and if the answer is no, the phases after it are wrong.

The roadmap is subject to change. Phases may be reordered, split, or dropped as we learn what makes the game fun.

Phase 3: designing the first real round

Sun, 17 May 2026 00:00:00 GMT

Phase 3 is the first version of Subterrans where a match has a beginning, middle, and end.

Right now the simulation runs. Two colonies start on opposite sides of a patch, dig chambers, forage for food, grow workers, fight. One queen dies. The simulation is correct — deterministic, headlessly testable, well-specified. But a round does not have shape. There is no pressure that builds, no moment where the match turns. You play until one side wins, and the outcome feels roughly proportional to the decisions you made, but the decisions were not made in response to anything. That is a loop. It is not yet a round.

Phase 3 adds the mechanics that give it shape. Seven of them, in the order they layer in:

The spider

A neutral predator, not allied with either colony. The spider operates on a hunger clock independent of both players: it wanders, it attacks anything it finds, and when it is hungry enough it will engage ants it would otherwise avoid. It cannot be defeated by one colony alone at early-game population levels. Both colonies have to deal with it.

This introduces the first thing that happens to you that you did not cause — and that your opponent did not cause either. The early game is no longer just a race to grow. It is a race to grow while something is reducing your workers.

The threat reticle

Six to eight seconds before a spider attack lands, a reticle appears over the target area. The warning is long enough to react to — pull workers back, adjust the behavior ratio, send fighters — but short enough that the reaction has to be fast and costs something. You cannot pre-position perfectly for a threat you have not seen yet.

The reticle is a design principle as much as a mechanic. Danger that is invisible until it lands does not create decisions; it creates complaints. Telegraphed danger creates decisions. The question is whether you saw it, how fast you reacted, and whether the cost of reacting was worth paying.

The mark-priority command

A player command that designates a high-priority target — spider, enemy fighter, enemy entrance. Workers and fighters route toward it before taking other actions.

This is the player’s most direct lever over the colony’s response to a threat. Before Phase 3, the behavior ratio (forage / defend / dig) was the only coarse-grained control over what the colony was doing. Mark-priority adds a fine-grained one: not “send more fighters” in general, but “send fighters there, now.” The distinction between the two is most visible under threat, which is exactly when the difference matters.

Worker self-scatter

When danger is close, workers in the affected area move away from it without a player command. They do not fight. They do not freeze. They scatter, and return when the threat passes.

Self-scatter sounds passive, but it is the mechanic that makes the spider feel like a disruption rather than a damage event. A spider does not just remove workers — it scatters them, and scattering takes time to recover from. If workers were foraging a food pile near a spider patrol path, you lose not just the workers that got hit but the next twenty seconds of foraging efficiency while the rest return and re-establish trails. That is the middle of a round: a sequence of disruptions you manage better or worse than your opponent.

Danger pheromones

When ants encounter a threat — spider, enemy fighter, proximity to an enemy entrance — they emit danger pheromones. These propagate across the grid and decay over time, following the same two-grid pheromone system already used for food trails.

The effect: the colony remembers where things went wrong, and ants route around those areas until the pheromone fades. A spider that killed workers in a corner of the map leaves a danger signature there. Workers will forage around it. Fighters will approach more cautiously.

Danger pheromones do not require player input. They are emergent colony-level memory. But they are also visible — the pheromone overlay shows them — which means a player who reads them has information about where pressure has been and where it might return.

The reproduction lever

Food surplus above a threshold accelerates egg-laying rate and larva maturation speed. When the colony is well-fed, it grows faster. When food is contested or restricted, growth slows.

This creates a mid-game dynamic that was absent before: food is not just a resource, it is the colony’s growth rate. A player who controls more food patches earlier builds population faster, which enables defending more food patches, which compounds. The reproduction lever is the mechanism that makes early-game foraging decisions visible as late-game population differences — the thing that makes a middle exist.

It also makes the spider more interesting. A spider that disrupts foraging near a food-rich area does not just kill workers; it reduces the food flow that drives reproduction. Two disruptions, one event.

Difficulty tiers

Three settings that change how the AI opponent plays and how the world generates pressure. The differences are asymmetric: easier tiers reduce the AI’s resource efficiency and combat aggression, not just its health or numbers. Harder tiers give the AI better foraging routes, faster reaction to threat, and a world with more spider activity.

Difficulty tiers exist because Phase 3 adds enough mechanistic depth that the same settings that make the game learnable for a new player make it trivial for an experienced one. The tiers are a tuning surface. What matters for Phase 3 is that they exist and that the hardest tier is genuinely hard — that requires the spider system and the reproduction lever to be working, which is why it gets built last.

The design weekend

Phase 3 was designed over one weekend, using a three-pass Codex review process and a dual-reviewer structure: each proposal was reviewed independently by two agents before being folded into the decision journal. The seven mechanics above came out of that process.

The methodology matters only insofar as it produced a coherent phase. The seven mechanics reinforce each other — the spider creates disruption, the reticle makes disruption legible, scatter makes it expensive, danger pheromones make it persistent, the reproduction lever makes it consequential, mark-priority gives the player agency over it, and difficulty tiers calibrate how much of it there is. Designing them separately would have produced seven features. Designing them together produced a round.

What this unlocks

Once Phase 3 lands, the question shifts from “does the simulation run?” to “is the round fun?”

That is the question Phase 1 — the original PRD, written in April — said we would answer first. We are finally there. The simulation is correct. The architecture is sound. The feedback tooling is in place. Phase 3 is the first version of Subterrans that can be evaluated as a game.

What comes next

Implementation starts now, stage by stage. The spider comes first; then the reticle and scatter; then pheromones and reproduction; then mark-priority; then difficulty tiers and tuning. Each stage ships as a PR, visible in the game repo.

The devlog will be quieter while builds are happening. When Phase 3 is done, you will hear about it. In the meantime, the demo at /demo/play is the current state of the game, and the roadmap tracks where each phase sits. If you play it and something is confusing, broken, or just wrong — say so. That feedback matters more now than it will at any later point.

This post is a companion to A New Roadmap, which covers the updated phase structure and what changed from the old roadmap.

The week the ants got better

Mon, 04 May 2026 00:00:00 GMT

Five days since the last post. Nineteen merged PRs in the game repo, somewhere north of fifty individual commits. A few of the changes are immediately visible the next time you load the demo. Most of them aren’t, and that’s a story too.

Things you can see

Nurses now carry brood. Eggs and larvae used to teleport from the Queen’s chamber into the Nursery — the simulation faked transport and the renderer faked the rest. As of this week, a nurse picks up a brood entity, walks it visibly across the colony, and deposits it in an Open tile inside a Nursery. It’s a real pickup-and-deposit state machine: pickup field seeded from claimable brood, deposit field seeded from Nursery tiles, the brood’s position syncs to the carrier each tick, and the renderer nudges the brood sprite a quarter-tile up so it sits in the carrier’s arms instead of stacked on her thorax. Dead carriers drop their brood in place; a maturing larva drops the carry mid-flight; another nurse can claim an orphaned brood from the death tile. All of that sounds obvious until you write it; six rounds of internal + Codex review caught about ten edge cases I’d missed on the first pass.

Ants move diagonally now. Movement was 4-connected (N/E/S/W only) since the first prototype. This week the simulation switched to 8-connected with a scurry-stop-scurry cadence: forager workers take a few steps, pause to “search,” then resume. The change is subtle in a screenshot and dramatic in motion — the colony reads as alive in a way it didn’t before. Fighters keep their direct line, because fighters chasing a target shouldn’t look hesitant.

The dirt is dirt. Until last week, the underground was solid brown. It now uses a procedurally-generated pixel-art terrain atlas, with quarter-tile autotiling on the walls so chamber edges, tunnel turns, and chamber corners all join correctly. The surface got ant-scale motifs — boulders, twigs, leaves the size of a worker — that block movement and give the world a sense of scale. After all that, I went back and fixed the rim-clip artifacts at the chamfered corners. The art will still get redrawn entirely in a later phase; the point of this pass was to make programmer-art look intentional rather than pre-final.

The AI got harder to push around

Two changes worth calling out:

The enemy AI was concentrating its colony into a tight pocket near the entrance — easy to invade, predictable to fight. New depth gate + spread bias + frontier-dig logic means the enemy now expands their colony over a wider area, with chambers placed reachable-but-not-adjacent and digging continued past initial chamber satisfaction. They feel like a colony making decisions instead of a script unrolling.

The AI’s chamber-placement BFS was running every tick — a ~4096-tile search per AI colony, sixty times a second. Strategic chamber decisions don’t need 60 Hz responsiveness; they’re bounded by how fast diggers can reach the marked tiles. Cadence is now once every eight seconds. That’s a 99% cost reduction on the BFS for no observable downside, and it matches how the rest of the simulation budgets work — fast loops on the cheap stuff, slow loops on the strategic stuff.

Things you can’t see

Now the bigger story: I did a structured review pass over the entire codebase and shipped roughly twenty fixes for things nobody had reported yet.

A few of the worse ones:

Entity ID overflow. allocateEntityId would let the counter walk past MAX_ENTITIES = 8192 and the next caller would write to TypedArray index 8192 — silent corruption. Fixed: counter freezes at the cap, callers receive a -1 sentinel and gracefully bail. Egg-laying becomes a soft population cap instead of a crash.
NaN command coordinates. Every existing range check rejected Infinity (Infinity >= max is true) but not NaN (NaN >= max is false). A NaN coord slipped through every guard, persisted into colony state, and broke save replay determinism via JSON.stringify(NaN) === 'null'. New shared isTileCoord predicate enforces integer-in-range at handler entry.
Save validation against tampering. s.ants.count: 1e9 used to allocate ~88 GB of TypedArrays before any sanity check. Now clamped. s.simVersion outside the supported range used to silently flip every gate. Now throws.
Forward-compatible saves. A new FutureSimVersionError distinguishes “save written by a newer build” from “save corrupted.” Future-build saves are now preserved across bootFresh + autosave (the autosave gets suspended explicitly), so a player who downgrades the build can recover their world by reloading on a newer build. Definitively-corrupt saves get deleted normally.
Camera-pan freeze on HUD crossing. Drag-pan would jump every time the cursor crossed a HUD widget mid-drag. Combined with a related fix where keyboard pan no longer stacks on top of an active drag-pan, the camera input is finally consistent across every gesture I can think of.
Pheromone leakage between zones. Underground carriers were writing phantom trails on the surface food-trail grid, corrupting surface forager behavior. Behind a sim-version gate so existing saves replay byte-identically.

The pattern across all of these is the same: each one was a real bug hiding behind an acceptable-looking range check or an unexamined invariant. None of them produced obvious symptoms in normal play. All of them would have produced very confusing symptoms eventually.

Why the simVersion gates matter

Every correctness fix in the simulation is gated behind a sim-version sentinel. New games run at the latest version. Saves written before the fix replay at their original version, byte-for-byte identical to what they would have produced before the fix existed. There are now twelve sim versions, each with a documented contract.

The cost is ugly conditionals at hot paths. The benefit is that a player’s seed-3201734851 mid-game save still replays today exactly as it would have in week one — and that I can fix sim correctness without breaking a single existing player’s save. That property is non-negotiable for a deterministic simulation that wants a multiplayer future.

Going forward

The rest of the week was infrastructure: command-coordinate validation, save-boundary hardening, code hygiene, defensive guards. None of it ships a feature. All of it makes the next feature safer to ship.

Next up: another pass at the player-facing UI, especially the underground view’s information density, and probably the start of a tutorial layer. Plus more art, because the procedural terrain atlas opened up the path to actually-good-looking tiles and I want to follow it.

If you find something, issue tracker. The bug-report template walks you through the F9 debug log, which gives me a reproducible replay instead of guesswork.

More soon.

First players, first bugs

Wed, 29 Apr 2026 00:00:00 GMT

Two weeks ago the game lived in a private repo on my laptop. Today it’s embedded at /demo/play, the source code is on GitHub, and the issues page has real bug reports from people who aren’t me. That shift — from building in isolation to building under observation — changed what I worked on this week.

Here’s what landed.

Phase 1 is now actually playable end-to-end

The simulation has supported invading the enemy hive since Phase 09.1: a fighting ant standing on the enemy’s entrance descends into their grid, hunts the nearest hostile, and resolving combat against their queen triggers victory. That’s the win condition for Phase 1. But none of it was reachable from the UI — clicking on an enemy entrance did nothing visible, the keybind to swap underground views was undiscoverable, and there was no visual cue distinguishing “enemy entrance” from “any other surface tile.”

PR #29 wired up the four UI seams. Left-click on an enemy entrance now sets your rally point there. The X-keybind got a clickable button labeled “Your Colony / Enemy Colony.” Underground clicks on the spectator view became no-ops (instead of silently dispatching dig-marks against your own grid at the matching coordinates). And enemy entrances got a single-pixel red perimeter ring so they read as “rally here to invade” without any tutorial text.

The simulation work was already done. The lesson was that “feature ships when sim supports it” is wrong; the feature ships when a player can find it without reading the source.

One system got smaller

Phase 10 was originally going to add a dig-priority slider to the existing forage/dig/fight ratio that players control. After playtest, the slider got cut entirely. The behavior ratio is now two fields — forage and fight — and digging is auto-assigned based on outstanding marked tiles. Less UI, less to explain, and the simulation does the bookkeeping that a human would have done badly anyway.

This is the second time I’ve removed a control from the player surface in this project. The pattern: if a system has a single right answer most of the time, exposing it as a knob just lets the player make it worse. Auto-assign isn’t a smarter system; it’s a refusal to let the player accidentally starve the dig queue while staring at a UI element.

The first round of real issues

The issues page collected reports faster than I expected. The interesting ones, in rough order:

#16 — queen wanders into the corner of her chamber and stays there. Visually unsettling; functionally fine. Fix was a wander policy that keeps her inside the chamber bounds rather than against an arbitrary wall.
#15 — chamber food storage was render-authoritative. Storage capacity was being computed by the rendering layer reading sprite occupancy, which is exactly the inversion the seven principles say to never do. Made the chamber the authoritative source.
#27 — carriers oscillating between food piles when colony storage was full. A worker would pick up food, walk halfway home, drop it because storage was saturated, walk back, repeat. Fix: bail out at pickup time, not at delivery.
#30 / #31 — invisible ceiling-row dig marks. Clicking on the grass strip at the top of the underground view dispatched a real dig command against the tile underneath, but the renderer kept painting grass on top — zero feedback that anything happened, and the orphan marks were dragging idle workers into infinite loops. Fixed in three layers: input rejection, sim-handler rejection, and AI-controller pre-filter. Defense in depth, because the AI was creating ceiling-row marks too.

A pattern in this list: most of the bugs were input-layer or rendering-layer bugs surfacing simulation-layer symptoms. The sim itself, the part the seven principles protect, has been mostly fine. The friction is in the seams — the places where player intent translates into commands, or where world state translates into pixels.

How the game gets to the page

The library bundle work was the biggest mechanical chunk. The game builds itself as a single ESM module with a mount() entry point that the website’s Astro page imports dynamically. Cache-busted hashed filenames + a manifest.json so the website’s deploy can reference the right URL. A ready promise so the loading state knows when to clear. Source maps. A .d.ts file generated directly from the source so the public API can’t drift from its declared types.

It now takes a single push to game main to redeploy the live demo. The game’s CI bumps the website’s submodule pointer, the website’s deploy picks that up, the bundle builds with a fresh hash, and CloudFront serves it. None of that is interesting in isolation. What’s interesting is that the friction-to-ship is now low enough that I’ll fix bugs in the morning instead of batching.

The dual-AI review pipeline went live

Every PR on the public repo now gets reviewed by Codex automatically (skipped on owner-authored PRs, since I’m reviewing my own work via Claude already). The bug-report template emphasizes the F9 debug log, which produces the input-log + seed needed to reproduce a deterministic replay. The branch-and-PR workflow is now the rule, not the convention.

If you find something broken in the demo, I’d rather hear about it than not. The issue tracker is the place — the bug-report template walks you through the F9 debug log, which gives me a reproducible replay instead of guesswork.

More soon.

The seven principles

Thu, 23 Apr 2026 00:00:00 GMT

(Editor’s note, 2026-05-17: Phase numbering has been updated since this post was published. See the current roadmap for the active phase structure.)

Subterrans has seven architectural principles I won’t compromise on. They sound austere written down. They are. The reason they’re non-negotiable is that every one of them protects something I want — replay, future multiplayer, deterministic debugging, AI agents that can actually reason about the code — and the cost of relaxing any of them shows up later, when fixing it requires rewriting half the simulation.

This post is the long version of AGENTS.md, with the reasoning expanded.

1. Strict separation of simulation from rendering

src/sim/ is pure TypeScript. Zero dependencies on Phaser, the DOM, the browser, or any rendering framework. The simulation takes inputs (player commands, time deltas) and produces state. The rendering layer reads that state and draws it. The simulation must be liftable into Node.js with no code changes.

What this protects: headless tests, deterministic replay, future server-authoritative multiplayer, AI agents that can reason about the simulation in isolation.

What breaks if you skip it: every test that touches the simulation has to spin up Phaser. Every replay has to render. The “model” and the “view” tangle into one ball of mud, and a year from now any change to either one risks breaking the other in a way that wasn’t possible to predict.

The lint config flags any import from outside src/sim/ into src/sim/ as a hard violation. PR reviewers — both human and AI — block on it.

2. Fixed timestep at 20 Hz

The simulation advances exactly 50 milliseconds per tick. The renderer runs at the browser’s framerate (typically 60fps), interpolating between sim ticks for smooth visuals. Variable timestep is forbidden.

What this protects: determinism. Same inputs from the same seed produce the same final state, tick for tick.

What breaks if you skip it: SimAnt-era games could get away with frame-rate-tied physics because everyone’s hardware ran at roughly the same speed. In 2026, your laptop might render at 144fps and your friend’s tablet at 30fps, and a variable-step simulation produces different worlds on each. Goodbye replay, goodbye multiplayer, goodbye reproducible bugs.

20 Hz is enough resolution for ant-scale movement and slow enough that the simulation has headroom to do interesting work each tick. The 60fps render layer covers any visual smoothness gap via interpolation.

3. Lightweight ECS-flavored architecture

Entities are integer IDs. Components are typed arrays (structure-of-arrays for hot data) or plain maps. Systems are pure functions that operate on entities matching certain components.

No class Ant. No class Colony. Data is data; behavior is functions.

No ECS library in Phase 1 — no bitecs, no miniplex. The lightweight approach is migration-compatible if I ever need a real ECS, and the absence of the library means there’s no framework to fight when the architecture wants to evolve.

What this protects: cache-friendly hot loops, the ability to serialize the entire world cheaply, and a model that AI agents (and humans coming back to the code six months later) can hold in their heads.

What breaks if you skip it: classes accrete behavior. An Ant class quickly grows methods that touch the colony, the world, the renderer, and audio playback. By the time you notice, you can’t change one without breaking five others. ECS-shaped data avoids that by making the relationships explicit and the data flat.

4. Seeded deterministic random number generation

The simulation uses a single Mulberry32 PRNG instance, seeded at world creation. Every random decision in the entire game flows through this one instance. The seed is saved with the save file. Math.random() is banned in src/sim/.

What this protects: replay. Given a seed and an input log, the world plays back identically every time. That’s how I debug timing bugs, how I write determinism tests, and how multiplayer (Phase 4) becomes feasible at all.

What breaks if you skip it: subsystems quietly create their own RNGs. A worker’s path-finding uses Math.random. A larva’s hatching uses Date.now() % 100. Over a 10-minute round, the divergence between two replays accumulates into completely different worlds. Determinism is binary — you either have it everywhere or you don’t have it at all.

5. No wall-clock time in the simulation

Date, Date.now(), performance.now(), and any other wall-clock APIs are banned in src/sim/. The simulation knows only its own tick counter. Elapsed simulation time is tickCount * msPerTick.

What this protects: identical results regardless of when the simulation runs. A replay started at 3am produces the same world as one started at noon.

What breaks if you skip it: subtle bugs that are unreproducible. “Sometimes the queen lays eggs at the wrong rate.” “Sometimes a worker behaves differently.” If wall-clock time is part of the simulation, every “sometimes” is unfixable without rebuilding from first principles.

This rule is also what makes the game pause-able and step-able. You can call the tick function 100 times in a row in a test and the simulation can’t tell the difference between that and 5 seconds of real time.

6. Fixed-point integer math for all simulation quantities

Floats are banned in src/sim/. Positions, velocities, food quantities, pheromone strengths — all integers, with an implicit scale factor (e.g., 1 unit = 1/256 of a tile). Floats are fine in the rendering layer for visual smoothness.

What this protects: bit-identical results across platforms. IEEE 754 floating-point math is almost deterministic across CPUs but not quite — different SIMD paths, different rounding modes, different math libraries on different OSes can produce off-by-one-ULP differences. Over a 10-minute simulation those differences accumulate into divergent worlds.

What breaks if you skip it: my replay test passes on my Mac and fails on someone’s Linux box. The “deterministic” multiplayer desyncs after three minutes. The headless Node test runs different than the browser one.

The cost is that I write addFixed(x, y) instead of x + y and the math is mildly less ergonomic. The benefit is that determinism is mechanically guaranteed instead of crossed-fingers hoped-for.

7. Snapshot saves with replay logging

Save files are JSON snapshots of the world state. In addition, every player input is logged alongside the seed, enabling deterministic replay for debugging and (later) multiplayer. Binary save format is deferred until JSON becomes a real bottleneck (likely never at our scale).

What this protects: debugging power, replay-driven QA, and a foundation for multiplayer where the network layer just shuttles input logs around.

What breaks if you skip it: debugging colony behavior is guesswork. “It happened around minute three” is the bug report; without replay you can’t reproduce it. With replay, you reload the seed plus input log and watch the same bug happen, every time.

JSON also means saves are inspectable. I can grep them, diff two save states, and write tools against them without writing a binary parser first.

Why these are non-negotiable

Each of these rules is annoying at the moment you write the code. Fixed-point math is annoying. Banning Date.now() is annoying. Refusing to import Phaser into src/sim/ is annoying. Each of them, individually, you could relax for “just this one case.”

You can’t, though. Determinism is a system property, not a per-feature one. The day you let one float sneak into the sim, the property is gone, and you find out three months later when the multiplayer prototype desyncs and you can’t tell which subsystem to blame.

The seven principles together are a contract. They’re enforced via lint rules, PR review (one human, two AI agents — that’s a whole separate post about the dual-reviewer setup), and architectural tripwires that fail CI when they’re violated. The cost is paid up front, in friction. The benefit is paid out continuously, in things working the way you’d expect.

If you’re building anything where determinism matters — a game, a simulation, a deterministic-replay debugger, a multiplayer system — the specific rules will look different than these, but the shape is the same. Pick the properties you can’t compromise on. Make them mechanically enforceable. Refuse to relax them when it’s convenient.

That’s the whole thing.

Why Subterrans

Wed, 22 Apr 2026 00:00:00 GMT

(Editor’s note, 2026-05-17: Phase numbering has been updated since this post was published. See the current roadmap for the active phase structure.)

In 1991, Maxis released SimAnt. It put you in charge of a black ant colony in a suburban backyard, fighting a red colony for territory and eventually invading the house. You could zoom into a single ant and play it directly, or pull back and command the colony as a whole. Pheromone trails. Foraging. Larvae. A queen to protect.

I played a lot of SimAnt. So did a lot of people. Then it disappeared into the shelf where Maxis kept the games that didn’t become franchises, and nothing has really filled that gap since.

There are good ant-themed games — Empires of the Undergrowth is excellent, Ants Took My Eyeball is strange and great — but none of them are the SimAnt-shaped game. The thing where you’re managing a colony as a system, not commanding individual units, where pheromone fields propagate independently of the ants on them, where the enemy colony is running the same code you are.

Subterrans is an attempt to build that game. It’s a spiritual successor, not a remake. Same shape, modern foundations.

What’s actually different

Three things, mostly.

First, it runs in a browser. SimAnt shipped on floppies. Subterrans Phase 1 is a single static page on subterrans.com. Native builds for iOS, Android, Steam, and desktop come later, but the web is the primary target. That’s a deliberate constraint — if I can’t get the loop fun in 2D inside a browser tab, I shouldn’t be building anything bigger.

Second, the simulation is a first-class architectural object. In SimAnt, the simulation and the rendering were inseparable — that was just how games were built in 1991. In Subterrans, src/sim/ is pure TypeScript. No DOM, no Phaser, no Date.now(), no floats. Everything is integers, fixed timestep at 20 Hz, single seeded PRNG. The renderer reads state and draws it; the simulation doesn’t know the renderer exists.

That’s not architectural showing-off. It’s the only way I get deterministic replay, future multiplayer, and AI agents that can actually reason about the code. More on that in the seven principles post.

Third, this is also an experiment in AI-agent development. Most of the code is being written by Claude Code and Codex working from planning artifacts I write. The architectural rigor above isn’t separate from that — it’s how I get AI agents to produce code that doesn’t drift. Every PR gets reviewed by both agents independently. Lint rules enforce the architectural boundaries. The planning workflow is its own discipline.

I’ll write more about that elsewhere. The short version: I want to know how much of a real game one person can ship if they treat AI agents as collaborators with very specific failure modes, and design the project around those failure modes rather than ignoring them.

What Phase 1 actually is

Phase 1 answers exactly one question: is the core colony management loop fun?

Not “is the art good.” Not “is there a tutorial.” Not “are there ten enemy types.” The minimum thing that’s recognizably SimAnt-shaped is:

Your colony has a queen, workers, larvae, and food storage
You designate tunnels to dig; workers dig them
You assign chamber types (queen chamber, nursery, food storage); ants behave accordingly
You toggle between surface view and underground cross-section
Workers find food on the surface and bring it home
Pheromone trails form and decay
You set behavior priorities (forage / dig / defend / idle)
One enemy AI colony runs the same simulation systems you do
Win condition: kill the enemy queen. Lose condition: they kill yours.

That’s it. That’s the whole thing. A round takes 5 to 15 minutes. You play it, and either you want to play another round or you don’t.

If the answer is “yes” — Phase 2 starts adding depth. Multiple castes. Real pixel art. Sound. The Yellow Ant, where you can drop into a single individual SimAnt-style. Multiple patches. A day/night cycle.

If the answer is “no” — no amount of art, sound, tutorials, or content saves it. You go fix the core loop or you stop.

What I’m explicitly not doing in Phase 1

Pixel art. Phase 1 is programmer art — circles and rectangles. Real art begins after the loop is validated.
Sound and music. Same reason.
Tutorial system. There’s a one-page text explanation.
Settings menus, save/load UI, main menu. The game boots straight into a hardcoded scenario and autosaves to localStorage.
Multiple enemy types, multiple ant castes, weather, the Yellow Ant, the human invasion, mating flights. All deferred to later phases.
Multiplayer. The architecture preserves the option (deterministic simulation, replay logging) but Phase 1 is single-player only.

Each of these has a reason. The collective reason is the same: scope discipline. SimAnt was made by a bigger team than me, and they were doing it as their day job. I’m one person with AI collaborators. The way that math works is that I have to cut hard until the thing I’m building is small enough to be good, then expand from there.

Where this is now

The site you’re reading just came online. The game itself has a working simulation skeleton — fixed timestep, deterministic RNG, the seven principles enforced via lint — and is currently mid-Phase 1 buildout. There’s no playable demo yet. There will be, behind a sign-up gate, and you’ll see it land in the roadmap when it does.

I’ll keep posting here. No cadence promises — when something worth reading happens, you’ll see it.