An economy design doc that survives contact with live data

Economy documents have a short half-life. A detailed spreadsheet of every reward, price, and rate is accurate on the day it is written and wrong within a few sprints, because live tuning happens faster than documentation does.

Teams respond either by abandoning documentation or by trying to keep the spreadsheet current, and both fail. The useful response is to write down a different kind of thing.

What goes stale and what does not

The values go stale. Every number in a live economy is provisional — reward amounts, prices, drop rates, all of it moves. Any document whose content is mostly numbers is a snapshot of a moment.

What does not go stale is intent. Why this currency exists, what it is supposed to be scarce relative to, which player it is for, what would tell you it had gone wrong. Those hold across many rounds of tuning, and they are exactly what is missing when somebody new tries to understand why a value is what it is.

The practical distinction: if a change to a number would make the sentence false, it is a value and belongs in the config rather than the doc. If a change to a number would leave the sentence true, it is intent and belongs in the doc.

"The mid-tier upgrade costs three hundred" is a value. "The mid-tier upgrade should be reachable in about a week of normal play, so that players hit it while still in the early arc" is intent, and it survives every repricing while explaining all of them.

The four things worth writing

The first is what each currency is for, in one sentence, including what it is deliberately not for. Most confusion about a multi-currency economy comes from two currencies whose distinction was clear to the person who added the second one and to nobody since.

The second is where currency comes from and where it goes, as a list rather than a model. Names and rough magnitudes, no precise figures. This list changes slowly and is the thing nobody has when they need it.

The third is the intended pace: roughly how long a typical player should take to reach the significant points. This is what every tuning decision is implicitly measured against, and writing it down converts arguments about whether something feels right into a checkable question.

The fourth is the failure conditions — what you would expect to see if the economy had drifted. Balances climbing, purchases falling among engaged players, a particular step taking much longer than intended. Writing these before anything is wrong is much easier than agreeing on them during an incident, and they double as a monitoring list.

The part that gets skipped and matters most

The single most valuable line in an economy doc is the reason behind a number that looks arbitrary.

Every economy has values that were set deliberately for a reason that is not obvious from the value. A rate that seems oddly specific, a price that does not fit the ladder, a cap that exists because of something that happened once. These are the values most likely to be "cleaned up" by someone tidying inconsistencies, and cleaning them up reintroduces whatever problem they were solving.

One sentence next to each — this is set here because of that — prevents a category of regression that is otherwise guaranteed on a long enough timeline. It is also the cheapest documentation in the whole exercise, because it is written at the moment the decision is made, when the reason is fresh.

See how we keep economy intent alongside the numbers →

Keeping it alive

A document that is not read does not stay true, so the maintenance question is really a question about when anyone opens it.

The pattern that works is to attach it to a recurring moment that already exists. If the team reviews the economy quarterly — and that review is worth having regardless — the doc gets read then, and updating it is part of the review rather than a separate task nobody schedules.

The second pattern is to make it the thing a new person reads. A document that is the standard onboarding for anyone touching the economy gets corrected naturally, because newcomers ask about the parts that no longer match reality and someone fixes them.

What does not work is a rule that the doc must be updated with every change. That rule is broken within a month in every team that adopts it, and its failure discredits the document entirely. Better to accept that it describes intent at a coarser cadence and to keep the values where they actually live, which is the config.

The test of whether the document is doing its job is simple: can someone who was not there read it and correctly predict roughly what any given value should be, and correctly identify when a proposed change is out of line with how the economy was meant to work. If yes, the numbers can move as much as they like.

Talk to us about documenting a live economy →