Design¶

Players sit in the Patrician’s chair. They meet the loops drawn on the system pages, know only what the Palace has been told, and at the end of a term see which loops did what.

The city lives in configuration¶

System pages will keep changing. An arrow added to a page has to reach the game, and an arrow taken off has to leave it, without anyone searching code. Calibrating against the real world later means changing numbers and comparing results, many times.

So everything about the city is configuration: variables and links, districts and buildings, triggers, stressors, remedies, endings, headline texts and stories. The engine holds no fact about Ankh-Morpork. A link from power cuts to pumps is a line in a file, and the engine only knows how to apply links.

The links come straight from the files the diagrams are drawn from, which live with the game and which systemdiagrams draws. Each row there already names a cause, an effect, which way it pushes, whether a person acts and whether it waits. The name on a box is the variable, so a box drawn on five pages is one variable. The game reads those rows, and one list gives each box what an arrow cannot: its level, who decides it if anybody does, and whether it piles up. Nobody copies an arrow into the game by hand.

Every arrow belongs to one system page. The dependencies and triggers pages borrow their arrows from the system pages, or draw one arrow for a path a system page draws in full. The only arrows they own are the causes from outside the city that start a failure: neglect, an error, a lost supplier, crime, a grievance, a probing state.

That makes configuration the hardest part of the project to read, and easy to get wrong. The engine checks the whole model on loading, and refuses links to variables that do not exist, boxes without a row in the box list, and links given numbers but a delay without a length.

Loops and moments¶

Most of what the pages describe are quantities that rise and fall: trust, cracks, cash in the vaults. The engine simulates these as system dynamics.

The pages also tell of events. A pump fails, an attack succeeds, the Palace issues an official alert. Events act on quantities: a failed pump supplies no water until mended, and an inquiry raises political pressure. Quantities in turn set the odds of events, so pumps without maintenance fail more often. The trigger chosen when the game opens decides which kinds of event come from outside the city, and how often. The stressors, chosen at the same time, are boxes that start away from normal, such as low maintenance spending or a thin stock in the warehouse. Both are settings with a default, and neither adds a rule of its own. The city’s own state does the rest. A remedy that takes a pump out of service while it is rebuilt is a series of steps, handled with the events, in code that names no particular place.

Every quantity is measured against normal: 1 is the city on an ordinary day, 0 is none at all. Normal, in Ankh-Morpork, includes a fair number of fires. A reinforcing loop with nothing to stop it drives a value on and on, so every quantity has a floor of 0 and a ceiling a few times normal, the same for all unless the box list says otherwise. A quantity starts at normal unless the box list or a setting says it does not. Real units come back only when the model is calibrated against the real world.

Districts and buildings¶

A burst pipe on Nap Hill is reported at once. The same pipe in the Shades is found days later and gets a short paragraph in the Times. The contract makes this unequal treatment central to the game, so the engine keeps districts. The pages also describe places that fail in their own ways, such as the Cockbill Street Pump and the Lady Sybil Free Hospital, so it keeps buildings as well.

Districts hold what people feel and do: trust, complaints, anger, illness. Buildings hold what one place does: whether a pump runs, how many hospital beds are free, what the works produces. The treasury, political pressure and public worry belong to the city.

Buildings affect the district they stand in. Districts add up to the city, weighted by their properties, so Nap Hill’s trust counts for more at the Palace than its population alone would give it. The city affects every district, but money only reaches a district through a remedy that spends it there. A link can change sign by district: an upgrade narrows the gap between rich and poor in the Shades and widens it on Nap Hill. One district affects another only through a link naming both, so fire can spread from the Shades into the next district, and Nap Hill’s private water serves nobody else.

An hour at a time¶

Some things on the pages happen within hours, such as mast batteries running down. Others take years, such as anger in Small Gods turning into money for repairs. The engine moves in steps of one game hour, short enough for the fastest of these, and updates every variable at each step. Loops slower than a term are already partway along when the game starts. The gap between Nap Hill and the Shades on day one is the result of years before it.

Some boxes pile up. Trust, cracks in the walls and the cash in the vaults keep whatever they had the hour before, and each arrow into them adds or takes away. The rest are worked out afresh every hour from their causes, and settle back to normal once their causes do, the way rumours die down when nothing feeds them. The box list says which is which. Either way an arrow pushes by how far its cause stands from normal, in its own direction and with its own strength.

Delays come in two kinds. A repair arrives all at once when done. Anger builds gradually. Each delayed arrow says which kind it is, as delay or gradual in its diagram file.

Within each hour, decisions take effect first, then events, then loops. Then whatever was noticed reaches the Palace, the Times reports it, and the engine checks whether the term has ended.

Day one¶

The city on day one has already lived for years. Before the first hour the engine starts every quantity at normal and runs the city for some years with nobody in the chair: every Palace decision at its default, the chosen trigger and stressors already at work. Wherever that leaves the city is day one. The Shades fall behind Nap Hill through the city’s own loops, pumps and towers age as fast as their maintenance allows, and trust in each district stands wherever the unheard loop left it. Nobody writes down a starting value for trust in the Shades, so the starting state cannot disagree with the diagrams.

Five districts take part, the ones the pages name: Nap Hill, the Shades, the docks, Small Gods and Dolly Sisters. Each is given only its character: how wealthy it is, how many people live there, and how loud it is, which means how fast its complaints reach the Palace and how much the Times cares. The buildings are the ones the pages draw, such as the Cockbill Street Pump, the Lady Sybil Free Hospital, the works and the bridges. A new building arrives the way a new box does.

No ending is checked during the run-in, so a harsh setting cannot end the term before it starts. The game opens on the first Monday of autumn. The first winter comes within months, and finds whatever the run-in left behind.

Chance¶

Luck enters only through events. Whether a pump fails this week, when the trigger sends cable thieves, and whether an inquiry finds the cause are draws, with odds that the city’s state sets. Arrows are never random: more customers off supply always darkens more masts. So every change in the record is a link, an event or a decision, and only the events are luck.

Every game draws its luck from one number, its seed, picked fresh when the game opens. Players never need to see it. The same seed, settings and decisions give the same game, run-in included. That lets a test tell a bug from bad luck, lets calibration compare two versions of the model on the same dice, and lets a saved game be replayed to the point where it was left.

Each building and each kind of trigger draws from its own sequence, made from the seed. A different decision on Monday then changes only what that decision touches, and the Cockbill Street Pump does not fail on another day for no reason anybody could see. Adding a diagram leaves the luck of the old ones alone.

The record keeps the odds of each event beside it. A bridge that failed early reads differently when the odds were poor and the dice unkind than when nobody had inspected it for years.

Saving¶

A saved game is a short list: the seed, the settings, the hour it was saved, and every decision with the hour it was made, pressing included. Loading replays the game from the run-in to that hour, which rebuilds the city, both accounts and the record exactly as they were, so none of them is stored. The file stays small, and loading takes a few seconds of replay.

The diagrams will keep changing, so a save also carries a fingerprint of the configuration it was made with. If the city has changed since, loading says so and replays anyway, skipping any decision whose box no longer exists and noting each one it skips.

A game can be saved at any moment, paused or running, and saves itself when closed. A finished term is saved the same way, so its record can be opened again later, or the term replayed with one decision changed and everything else, luck included, left as it was.

What the Palace knows¶

On the homes page, the Cockbill Street Pump stops on a Monday and the Palace hears about it on Saturday, from Vimes.

The contract denies players perfect information, and the homes page makes this a loop: a street that no longer complains has its failures found late, and late repairs teach it again that complaining is pointless. For that loop to work, the engine has to separate what happened from what the Palace has heard. It keeps two accounts of the city. One is the city as it is. The other is the city as reported: which failures came in, when, from whom and how reliably, which causes were found, and what things looked like when last checked.

A failure moves into the second account when someone notices it. How long that takes is a variable like any other, raised or lowered by a district’s complaints, press coverage and connections. Causes are known only after an investigation, which costs time and money. Whether a repair worked is known only when the thing fails again, or does not.

Players see only the second account, on screen and in headlines. Keeping one account and hiding parts of it on screen would be simpler, until someone added a useful figure to the dashboard and revealed a hidden failure.

So players will sometimes act on something the Palace believes that is false. At the end of a term both accounts are shown together.

Headlines and stories¶

The Times prints from the same account as the Palace. A pump that stopped unreported on Monday is no more news to the Times than to the Patrician, until Vimes mentions it on Saturday. A headline appears when a reported quantity crosses a line, such as customers off supply on Nap Hill above normal for an hour, and its words come from a short list of texts kept for that quantity.

How hard a failure hits political pressure depends on its frame, which is its cause as far as anybody knows. Until an investigation says otherwise, the Times assumes the worst: neglect for an old pump, incompetence when the Palace was told and did nothing. Bad luck costs little, an attack rallies the city for a while, and neglect costs the most. An investigation costs time and money, and changes the frame to whatever it finds.

Official alerts and reassuring statements are boxes on the pages, with their arrows to worry and rumours. A statement that a later inquiry contradicts costs political capital, so a statement that buys time today makes the next scandal worse.

Behind each headline is the story of the loop that moved it, a few lines in the game’s own voice, filled in with the district and the building concerned. For the unheard loop in the Shades it might read: Cockbill Street stopped complaining years ago. Its pump stops, nobody tells the Palace, and the repair comes late enough to teach the street the same lesson again.

Remedies¶

Remedies live on the system pages, next to the loops they pull. Each is a box on a diagram reached by an arrow that somebody decides, and the page says whose decision it is and what it costs. When a diagram changes, its remedies change with it, and the engine takes them from the pages the way it takes links.

Where a page draws a decision as the Palace’s, players make it. Most decisions belong to other people: engineers reconnect a street at a time, the network company keeps the connection queue, households in the better districts buy generators. The pages show what moves them, as links, and the engine runs those like any other link.

The Patrician cannot make other people’s decisions, but can press the people who make them. A word from the Palace can make the network company reconnect the Shades first or keep a feeder on the rota. The pages draw pressing like any other decision. Each press is a Palace box named for whoever is pressed, such as Palace pressure on the repair crews, drawn on the page of the decision it bears on, with an arrow to that decision. Every press also adds to one box on the Palace’s diagram, the pressure from the Palace, which is the one place political capital is spent, and political capital limits every press. Political capital is a quantity like trust, so the engine needs nothing special for it. Pressing does not always work. Vimes pushes back.

Some remedies act once. Some stay until changed, such as the rota. Some take years, such as reinforcing the grid. A remedy costs money, time before its effect arrives, or both. The contract makes attention finite, so only so many things can be in hand at once.

Players choose remedies on what the Palace knows, and the remedies act on the city as it is.

The term and its endings¶

A term is four years, the same in every game. It can end sooner in four ways. Political capital stays at nothing, and the guilds remove the Patrician, by vote or by other means the Assassins’ Guild would rather not discuss. Anger in the poorer districts stays near its ceiling for days, and the city revolts. The treasury stays empty, and the city is bankrupt. Or players decide to retire.

Each ending is a box crossing a line and staying past it for a while, a few rows of configuration that the engine checks every hour. Political capital and the treasury belong to the Palace’s own diagram, with the loops that fill and empty them. Political capital falls fast and comes back slowly, which is all that legitimacy ever meant.

The record¶

The game cannot be won. A served term ends with “You served your term. Here is what happened,” and an early ending with a line of its own. Either needs more than final values. Daily snapshots would show that trust fell in the Shades, but not why.

So the engine records the cause of every change: a link, an event, or a decision. Each link knows which page and loop it comes from, so the ending can say, for example, that trust in the Shades fell mostly through the unheard loop, or that pressing the network company for the hospital bought time and cost capital that was missing later. The record is totalled per day, and its totals must equal the actual changes.

Pace¶

A term runs to some 35,000 hours, and few of them deserve watching. The screen offers three speeds, an hour, a day or a week of game time to each real second, and a pause. At the slowest a blackout’s first evening takes a minute or so, at the fastest a quiet year takes less than one, and a whole term takes about an evening, depending on how much goes wrong.

The game drops to the slowest speed when news reaches the Palace, never when something merely happens. A pump that stops unreported on Monday must not slow the clock, or the clock would report it. A quiet week in the Shades runs at full speed, which is how the Palace lives it too.

Decisions can be made while paused, and still take game time to act. Pausing buys time to think, not time to mend. Speed never changes how many things can be in hand at once.

The core and the screen¶

Players want the city running in real time, with pause and fast-forward. Calibration needs many terms run without anyone watching, and tests need single steps. So the engine is a core with no screen and no real-time clock. On request it advances the city, reports what the Palace knows, accepts decisions, and hands over the record at the end. Pause and speed belong to the screen.

The screen has not been designed yet. Whether it becomes a desktop window or a browser page makes no difference to the core.