Devlog: Building the Guide Update

Update 0.1.34 grew out of one observation from launch week: new players were confused. They could see a world full of things to do and had no way to learn what any of it meant without leaving the game. This devlog walks through what we built in response, the decisions behind it, and a few things we discovered along the way.

A guide that cannot go stale

The first decision was that the guide must never state a balance number as text. Anything a person types into a guide is wrong the moment the game changes, and this game changes often. So the guide has two layers. The prose is written in our content system by the team. The numbers come from the same public content reads the game itself uses, computed fresh when a page is opened: loot weights become drop percentages, recipe lines become costs, building definitions become health, floor and burn timers, and the enhancement ladder is read straight from the service that runs the forge. A page for a creature can tell you that leather drops every time and a blueprint drops one time in two hundred, because that is what the server will roll.

The second decision was that the game and the website must render the same thing. The game client has no HTML engine, so the guide is published as a small set of plain blocks: headings, paragraphs, lists, callouts, step lists, stat tables, references and links. One converter produces those blocks from the editor's rich text, the website draws them, and the game draws them. A block type the game does not understand yet renders as a polite note asking for a newer version rather than breaking the page.

The question mark you now see on menus is resolved from the thing you tapped, not from a list of special cases. A flag, a deer, a sword or a recipe carries its own definition, and the guide's manifest maps that definition to a page. Adding a new item to the game gives it a guide page without touching any code.

The tutorial's order is the game's order

The Getting Started journey we started from went cabin first. The game disagreed. A Log Cabin and a Personal Workshop can only be built on land you own, so the flag has to come before either of them, and a sword and a breastplate need smelted iron, which needs the workshop. The deer also had to move up, because the flag itself costs a leather. We let the game's rules set the order and adjusted the guide to match, rather than the other way around.

The tutorial's state lives on the server. The server decides which step is current and refuses to advance out of order, and the client's only job is to notice when a step looks complete and say so. That split matters for the milestone gifts. Each gift is written into the economy with a fixed identity for that account and that step, so no amount of retrying, resetting or racing between two devices can mint it twice. If the economy service happens to be unreachable at the exact moment a milestone is reached, the gift is simply owed, and it is delivered the next time the tutorial is opened.

The practice deer follows the same shape. The client can ask for one, but only the server decides whether the account is on the fight step, under its lifetime limit, past its cooldown and not already standing next to a deer. When it agrees, a temporary deer is placed on land nearby and vanishes on its own ten minutes later.

What an hourly census taught us

The Economy page started as a simple request: show the crowns and every item in the game, refreshed once an hour. Building it meant asking the economy service to count itself, which it now does every hour under a lock so that only one copy ever counts, and to publish the totals through a read that exposes nothing about any individual account.

The first numbers looked wrong, and investigating them was useful. Several hundred thousand backpacks turned out to be exactly what the ledger said they were: test grants made to staff accounts in early August that had never been cleared before launch. The ledger keeps a record of every one of those grants, which is the whole point of having a ledger. The Royal Sigil total was more interesting. A large amount listed for sale on a Trade Hub was missing, because a listed stack or currency leaves the ledger until it sells. The marketplace now publishes its own count of what is listed, and the Economy page adds the two together, which is why the page reads owned, in escrow and on hubs as three separate columns.

Two bugs behind the reports we heard most

The first was creatures respawning on exactly the same spot. Respawns had always scattered up to a kilometre from home, so the reports did not fit, until we looked at what a restart does. Wild creatures are stored in the world database and restored from it when a region loads, but their stored position was only ever written for owned companions and world bosses. Every deploy restored every wild creature at the pixel it was first seeded on, and we deployed many times in one day. Creatures now plan their next spawn point on land before they return, their home follows them, and that home is written back so restarts keep it.

The second was screens saying unavailable for a moment, then working after a refresh. Nothing was failing at rest. Every service runs as a single copy, and for a few seconds during a rolling update, new requests could still be routed to the copy that was shutting down. Each service now keeps serving for a short grace period after it is picked for replacement, and both the website and the game retry a read once before showing an error.

Small things that mattered

Icons were rendering small and off centre. The cause was invisible: generated art carries a soft glow that fades across most of the canvas, and the trim that centres an icon was treating that faint glow as part of the picture. Trimming on real visibility fixed every slot at once.

Google Play's review flagged the orientation lock in the Android app's manifest. The game is designed for portrait and stays that way, so the lock simply moved into code, applied the moment the game starts on any phone or tablet, and the manifest no longer carries a restriction. The release build is now optimised as well. Both changes came from Google Play's own review of the app.

Every player now starts with two free destinations: the nearest city with a Trade Hub and the hub itself, chosen once from their first spawn and never moved. It is a small change with a clear purpose. A new player should never have to work out where the market is.

What comes next

The guide's pages will keep filling in as the team writes them, and every page already shows its live facts even before the prose exists. Elections will hold their first count on the first of October. And the reports keep coming, which is exactly how this update was built.