On this page
Contribute
Writing game scenarios
Last updated
Scale or Fail is the system design game in the practice page's Daily menu (Arcade) (play it). You pick a scenario, place components on a board by tapping or dragging, and keep the system up while traffic grows, new use cases arrive and the requirements tighten. Every number comes from Proschi's simulation, and every failure says why it happened and what a senior engineer would do.
This page explains how the game works and how to add to it: scenarios, tech
cards, incidents and components are plain files in
frontend/src/game/content/, checked by proschi game check.
How a run works #
A run is twelve waves in three acts. Once the twists are open (see First runs) it starts with a choice of three mutators (below), and each wave is a month of traffic:
-
Forecast. Kernel, the cat SRE lead, briefs the wave in plain words: how traffic changed since last month, the new use cases and requirements, and the incidents coming (a boss wave opens with its own intro). The forecast panel then shows the traffic curve and its peak per use case, the requirements in force (as Proschi lines), and the incidents coming (with their tick, below difficulty 1), and this wave's three bounties to choose from. With the twists, the peak is a range: the real traffic lands within 12% of the forecast either way (20% on a boss), drawn from the seed, so a load test, which tests the middle, is a guide and headroom is a choice, and from wave 5 some incidents are unannounced. The cat button in the run's header turns the briefings off.
-
Plan. Place, wire, scale out (replicas), scale up (sizes S, M, L), shard, remove. Nothing is timed. A load test shows the plan at the forecast peak for $100. The board is drawn on the editor's canvas (the same nodes and connections as a diagram), and Code shows it as Proschi text you can edit instead: one line per component (
api "App Server" [Service] x3), one per wire, andsizeandshardsin acapacityblock. Which use cases an app server handles is set in its settings, or written after its line as# handles: book, pay(use case keys). Users and the externals stay on the board: their lines cannot be typed into. Compiled shows the whole document the simulation runs: the board with the scenario's use cases, the peak traffic and the requirements, and after a load test (or during the run) a warning on each line that broke. See The code pane. -
Run: hold the line. Eight ticks, each one simulated with the wave's traffic at that point of the curve, and the run keeps going while you act. With the twists, change the board as you would when planning and ship it: it goes live after provisioning, a tick for scaling or removing a component, two for new components or wires, and a cache that goes live mid-wave starts cold (30%, then 70% of its usual hit ratio). Three live changes a wave; one still provisioning when the wave ends is live for the next. And there are three hotfixes a wave (more with cards and perks), each from that tick to the end of the wave:
Hotfix Cost What it does One more replica $200 On the node you tap. Bring it back $100 A node an incident took down (a lost zone, a dead primary) is back. Warm the cache $150 A cold cache (a stampede) is warm again. Rate limit 2 Trust Turns away 15% of requests and every bot at the edge. Switch a feature off 3 Trust A use case gets no traffic: no load, no revenue, no limits checked. A hotfix acts at once and costs overtime; a live change is free but takes time. Pause stops the clock for those who need it. (Hotfixes are not the On-call mode, whose pages are tickets.)
-
Score and debrief. Revenue, cost, interest, bonuses and the bounty. If anything broke, the debrief shows the bottleneck, the simulation's hint and the review cards that explain it.
-
Draft. Take one of three tech cards, or skip it for $100. Rerolls cost $150, then $50 more each. With the twists, after waves 2, 5 and 8, choose one of three contracts: a new use case for more revenue, stricter requirements for a multiplier, or cash now.
Waves 4, 8 and 12 are bosses: a launch, a holiday, a Super Bowl ad. After wave 12 you can bank the score or keep going in Endless (traffic ×1.3 a wave, two incidents, up to wave 24).
First runs #
So that a first run is not a dozen ideas at once, a new player plays the basic rules until their first clear of a Scale or Fail scenario (Shortly, for nearly everyone; clearing a design-first mode does not count):
- no mutators and no bounties;
- an exact forecast instead of a range, and no unannounced or cascading incidents;
- no live changes: the board deployed is the board of the whole wave (hotfixes still work);
- no card sets and no contracts.
In Shortly's first wave, after the briefing, Kernel walks through a short
tutorial: place a load balancer, add a replica, load test, deploy. Each
step is read off the board (undo steps back), its control pulses, and "Skip
the tutorial" puts it away. The first run with the twists opens with
Kernel's one-time intro to them, before the mutator picker. Both are
remembered in the browser (proschi.onboarding, arcade and
arcade-twists).
The gate is part of the run's setup (twists: false in RunSetup; absent
means on), decided from the player's progress when the run starts
(runTwists in engine/meta.ts), so a replay plays the same rules. The
Worker starts a ranked run with it from the stored progress, never from the
request, and takes an imported run's basic rules only while the progress at
that point had no clear (twistsAllowed). The daily run always has every
twist, for everyone, so its board compares one game. Basic runs score on
the scenario's ordinary board: they can only be ascension 0, they lose the
mutator, bounty and set bonuses, and they gain an exact forecast.
The code pane #
The game teaches Proschi as it goes. A scenario's code setting opens the
code pane in steps:
- Watch (before the wave in
edit): the Code tab is read-only, and every change on the board lights up the line it wrote. - Edit (from
edit): type the board, with completion that offers only what you can place (Ctrl+Space). - Only (from
only): on a wide screen the palette is gone, and new components are typed; nodes are still tapped to scale, size or remove. On a phone the palette stays.
Kernel says when a step begins. The terminal button in a run's header turns Code only on for any scenario, as a player's own choice; it changes nothing in the score.
Mutators and bounties #
So that no two runs want the same design, a Scale or Fail run with the twists (not the design-first modes, nor first runs) has two kinds of twist, both seeded like everything else: the daily run offers everyone the same ones.
- Mutators. Before the first deploy, pick one of three, or play it straight. A mutator changes the whole run: 60% of users on another continent, a SQL licence 75% dearer, reads ×1.5 and writes halved, writes ×3, a zone outage on waves 3, 6 and 10, 60% of the seed money with twice the interest cap, or a cache stampede on waves 5 to 7. Each multiplies every tick's points (×1.1 to ×1.3), the harder the more. Deploying without a pick plays it straight. The pick is an action like any other, so the Worker replays it.
- Bounties. Every wave offers three optional objectives; take one before deploying, or none. Met, it pays; missed, it costs a quarter of its cash. The objectives: every app server under 50% at the peak, a cloud bill under 40% of revenue, a wave without a breach, the right-sized bonus, a clean wave without a hotfix or without a load test, a lost zone survived, a boss without a dropped request. Met, it pays its cash at once and its points × the act. A bounty made for the wave (its announced incident, its boss) is four times as likely, and the one taken last wave is not offered again.
Bounties and contracts are both optional offers, but different decisions, so they stay apart: a bounty is a goal for one wave that pays if met and costs a little if missed, and changes nothing else; a contract changes the rest of the run (a new use case that grows each wave, a stricter requirement, or cash for a tighter SLA) and has no goal to meet.
Cash, Trust and score #
- Cash starts at the scenario's seed round. Each tick adds the revenue of the requests that succeeded and takes the cloud bill (the simulation's monthly cost, egress included, over the ticks). At the end of a wave you get 5% interest, at most $100. Below $0 at the end of a wave, the run is over (bankrupt).
- Trust starts at 100. Each tick, a missed latency limit costs 3, a missed availability limit 5, a lost zone you could not survive 5, dropped requests 1 per 2% (at most 10), a use case with no route 8, a backlog older than its freshness limit 2, a seat sold twice 5. A clean wave gives 5 back, a boss 15. At 0, users churn and the run is over.
- Score is the revenue of every tick × quality × the uptime streak. Quality is 1 for a clean tick, 0.6 with a latency, cost or freshness breach, 0.4 with anything worse. The streak grows by 0.1 per clean tick up to ×3, and any breach resets it. A wave where every compute and store node stays under 75% at the peak, none could lose a replica and stay there, and something works above 40% earns the right-sized bonus (+15%), and in Scale or Fail a tenth of the wave's bill back in cash. Bosses add 500 × the act, and a met bounty its points × the act. A mutator multiplies every tick's points. The end adds Trust × 10 and cash ÷ 10.
Cards with a price, and sets #
Some cards bend a rule and charge for it: Kubernetes autoscales but every app
server costs 25% more, Read replicas everywhere takes 60% more reads at 35%
more per database, Long TTLs raise every hit ratio but cost Trust. A card's
downside is a second effect against you.
With the twists, three cards of one topic (caching, resilience, estimation…) make a set: every tick's points ×1.1 per set held.
Incidents that cascade #
With the twists, an incident with then sets off another when it broke something badly
(dropped or failed requests, a lost zone it could not survive), at most once
a wave: a lost cache node comes back cold (a stampede), a stampede knocks the
database primary over, a dead primary brings a storm of retried writes. The
next one starts the tick after, unannounced. Handle the first (or have the
design for it) and there is no second.
Progression #
A run earns Blueprints: 1 per wave survived, 3 per boss, 1 per 2 500 points (at most 10), and 5 for a scenario's first clear. Blueprints buy:
- Components. The first run has a load balancer, app servers and a SQL database. Caches, CDNs, queues and workers, firewalls, object storage, gateways, NoSQL, search and warehouses are unlocked one by one, each with a short intro to what it solves, what it costs and how it fails.
- Features: instance sizes, sharding, wider lanes.
- Rare cards for the draft (common and uncommon ones are in from the start).
- Perks, permanent and equipped into up to three slots: more seed money, more Trust, a free reroll, a starting card, a free load test, a second pager.
Scenarios open as you reach waves in earlier ones, and each has ten
difficulty levels (ascensions): you may play one above the highest you
cleared. Unlocks and perks count on the leaderboard; each scenario and
difficulty has its own board, and there is a daily run with the same seed for
everyone. A finished daily run can be shared: a square per wave (🟩 no
breach, 🟨 breached but survived, 🟥 lost), the score and the day's rank, with
a link that opens today's daily run (#/arcade/daily).
Design-first modes #
Scale or Fail is the arcade mode. The others put the design first: no card draft, no rerolls, no boss names. Each wave a ticket lands in the inbox, from the product manager, the CTO, a customer, legal, finance or marketing, and asks for something real: a feature, a launch, an SLA, a law. The cash, Trust and score rules are the same, and so are the leaderboards.
The Arcade home lists them apart from the Scale or Fail scenarios, under Design challenges: one scenario per mode, each card with a line on what its mode asks.
Chaotic Startup (Pawprint) is about change. Besides scaling, it has:
- API versions. A breaking change ships as a new use case (v2) next to the
old one. Old clients keep calling v1, with traffic falling wave by wave.
Once v2 is live, v1 costs its
upkeepevery wave until you sunset it, and sunsetting it while it still has traffic gives those clients 410 Gone (acompatbreach, every tick). - Migrations. A schema change goes expand → dual-write → backfill →
cutover → contract, one phase a wave (each is a deploy), and can be rolled
back until the contract. Dual writes double the writers' writes on the
store; the backfill adds a background job; the use cases that need the new
shape are served from the cutover; and the contract drops the old shape,
which breaks any use case still reading it (
compat). All at once jumps to the end: the store's writes lock for two ticks (amigrationbreach).
On-call (Dinnerbell) is about incidents. Each wave's ticket is a page with its alert and logs, the incident really happens, and before deploying you name the root cause from a few plausible ones: right gives Trust back and points, wrong costs Trust, and every answer explains why. Then you fix it on the board, and the next page tests whether the fix holds.
Legacy rescue (Monolith) is about change without downtime: put a gateway in front of a ten-year-old monolith, move one use case at a time to new app servers (an app server's settings say which use cases it handles), split a table out with a migration, and retire the old endpoint once its clients are gone. A big-bang rewrite locks writes and breaks the old readers.
Cost crunch (Runway) is about spending less without breaking anything:
finance lowers a cost <= … usd/month requirement every wave while the SLOs
stay. Remove what is idle, right-size what is over-built, keep the cache that
spares the database, and keep two of everything for the failure drills.
How the game uses the simulation #
The board is a graph of components and wires, but the simulation reads
use cases: sequences of steps. The engine (frontend/src/game/engine/)
compiles the board and the scenario's use cases to Proschi source, which the
ordinary parser reads and the ordinary simulation analyses, once per tick:
- A use case enters at Users, passes the edge components it is wired through (load balancer, firewall, CDN, gateway) on the shortest path, and reaches the first app server that handles it.
- Each step runs from that app server:
read dbgoes to the first database it is wired to,call pushto the external system with that id. - With a cache wired to the app server and a
cachehit ratio, reads go cache-aside: "Cache hit", "Cache miss" (which fills the cache) and "Cache down" (a fallback, so the cache does not count against availability, but a failed call costs its timeout). - With a CDN on the path and an
edgehit ratio, an "Edge hit" scenario ends at the CDN. - Steps marked
asyncgo through a queue and a worker when the app server is wired to a queue whose worker reaches their targets. The request only publishes; the worker's work is a separate "(background)" use case, and a worker that cannot keep up builds a backlog (in minutes) instead of slowing the request. Without a queue, async steps run on the request. - Far users (a wave's
globalshare) cross an ocean: 120 ms on the request, except for CDN edge hits, which are answered nearby.
Sizes, cards and incidents become capacity overrides; requirements are the
scenario's Proschi lines, checked with runTests. "Open in editor" on the
end-of-run report opens the compiled design. What the game adds on top of the
simulation, and approximates:
| Game rule | How it works |
|---|---|
| Dropped requests | A request is served with probability min(1, 1 / utilisation) at every node on its path. |
| Backlog | Each tick adds 60 × (utilisation − 1) minutes of lag at the busiest background node, and drains the same way below 100%. |
| Availability zones | Three zones; an outage takes a third of every component's replicas (rounded up). A single instance goes down with it. |
| Failover | A SQL database's writes stop for the first tick while a replica is promoted; with shards, only one shard's share. Without a replica, it is down. |
| Hot key | Caches and databases lose that share of their read capacity. |
| Bots | Extra traffic on random keys; a firewall (403) or gateway (429) stops it at the edge. |
The engine #
The engine is pure TypeScript with no React, shared by the page, the Worker
(which replays every submitted run) and proschi game check. It is split by
what each part decides:
| File | What it holds |
|---|---|
engine/run.ts |
The core state machine every scenario shares: Game, waves, the deploy and load test, the card draft, scoring a wave and ending a run. |
engine/state.ts |
The run's state and what it reports (RunState, TickResult, WaveSummary, Forecast), breach kinds and requirement helpers. |
engine/tick.ts |
One tick of the simulation: traffic, capacity, analysis, what was served, breaches, backlog and points. |
engine/incidents.ts |
Drawing the wave's incidents, what they do to a tick, and the on-call's hotfixes. |
engine/twists.ts |
What a run adds after a first clear: mutators, the forecast range and unannounced incidents, bounties, contracts, cascades, card sets and live changes. |
engine/modes/ |
One file per mode (scale, startup, incident, legacy, cost) and the mechanics they use. |
A mode (modes/mode.ts) says whether waves end in a card draft, whether the
twists apply, whether a right-sized wave gets cash back, and which
mechanics its scenarios use. A mechanic owns its planning actions and
hooks into the core: when a wave starts, before a deploy, how the wave's use
cases are shaped and which are served, what locks a store's writes, which use
cases get no answer this tick, the breaches after serving, and upkeep. There
are three: migrations (Pawprint and Monolith: the migrate action, dual
writes, backfills and big bangs), legacy-versions (the same two: sunset,
upkeep and 410 Gone) and diagnosis (Dinnerbell: name the root cause).
Runway needs none: its cost requirement is checked like any other.
proschi game check refuses a scenario whose data needs a mechanic its mode
does not play (a diagnosis in a cost scenario, say).
engine/determinism.test.ts replays every reference and wrong run (and the
references with each mutator, under the basic rules, at higher ascension,
with perks, into Endless, taking bounties, and with hotfixes and live
changes) against a snapshot of every tick, forecast and refused action. A
change that moves any score fails it; a deliberate rule change bumps
GAME_VERSION and updates the snapshot with
npx vitest run determinism -u.
The content folder #
frontend/src/game/content/
components.json placeable components and unlockable features
perks.json permanent perks
ids.lock every id ever published (never remove a line)
cards/<id>.md tech cards for the draft
events/<id>.md incidents and spikes
scenarios/<id>/
scenario.md title, summary, prose: briefing, acts, debriefs, interview translation
scenario.json start board, use cases, waves, event pool, contracts
reference.json a scripted run that must clear all 12 waves
wrong/<name>.json scripted runs that must fail by a given wave
scenario.md #
Front matter (the same strict subset of YAML as problems and cards: flat
keys, one-line lists, quote values with : in them):
| Field | |
|---|---|
title, summary |
What the scenario picker shows. |
difficulty |
easy, medium or hard. |
tags |
Free words for the picker. |
related |
Practice problem ids, linked from the end-of-run report. |
cards |
Review card ids the report suggests. |
order |
Position in the picker. |
version |
Bump it when a change can change a score: it starts a new leaderboard season for the scenario. |
mode |
scale (the default), startup, incident, legacy or cost. Every mode but scale has no card draft and gives every wave a ticket, and may have 4 to 12 waves. |
Sections: ## Briefing (required), ## Act 1 to ## Act 3 (shown at the
start of each act), ## Debrief: <id> (shown after a wave whose debrief
names it), ## Ticket: <id> (the text of a wave's ticket), and
## Interview translation (required): the design in the words you would use
in an interview.
scenario.json #
{
"start": { "cash": 3000, "trust": 100, "board": { "nodes": [ … ], "edges": [ … ] } },
"grants": ["storage"],
"externals": [{ "id": "push", "name": "Push provider", "tech": "Push Service", "rps": 30000, "latencyMs": 60 }],
"useCases": { "redirect": { … } },
"waves": [ … twelve … ],
"eventPool": [{ "id": "noisy-neighbor", "weight": 3 }],
"contracts": [ … ],
"unlock": { "scenario": "shortly", "wave": 6 },
"code": { "edit": 3, "only": 9 }
}
- start.board has a
usersnode, every external, and only components unlocked from the first run or granted. - grants lends components for this scenario's runs whether the player unlocked them or not: the ones its lesson is about.
- externals are systems you call but do not run: a catalog tech of the
external kind, with optional
rpsandlatencyMs. - unlock: reach this wave in that scenario to open this one. Leave it out for a scenario open from the start.
- code: the waves (1-based) from which the code pane may be typed in
(
edit, 1 when absent) and from which new components are typed only (only, never when absent). See The code pane.
A use case:
"redirect": {
"name": "Redirect",
"method": "GET",
"path": "/aZ3x9",
"status": 302,
"value": 250,
"size": "500B",
"steps": [{ "op": "read", "to": "db", "entity": "Url" }],
"cache": 0.9,
"edge": 0.85
}
| Field | |
|---|---|
name |
The Proschi use case name; requirement lines refer to it. No quotes or brackets. |
method, path, status |
The entry request and its answer. |
value |
Revenue per wave for every 1 000 rps that succeed. |
size |
Payload between the user and your edge: the upload for a POST, the response for a GET. It fills bandwidth, and responses to users are billed as egress (less from a CDN). |
steps |
In order: {"op": "read" | "write", "to": "db" | "blob" | "search" | "warehouse"} or {"op": "call", "to": "<external id>"}, with optional entity, async (may run in a worker), x (fan-out) and size. |
cache, edge |
Hit ratios (0 to 0.99) when a cache or CDN is in place; leave out for data that cannot be cached. |
strong |
Reads must see the latest write: no cache, and an eventually consistent store is a breach. |
optional |
Contracts and extras: a missing route costs less Trust. |
A wave:
| Field | |
|---|---|
traffic |
Base rps per use case key. Once a use case appears, every later wave gives its rps. |
curve |
flat, day, ramp, spike (×4 for two ticks) or double-peak. |
requirements |
Proschi requirement lines, each naming a use case: p99 "Redirect" < 50ms, availability "Checkout" >= 99.9%, durable "Shorten", survive any node failure, cost <= 4000 usd/month. A line for the same measure and use case replaces the earlier one. |
freshness |
[{"useCase": "send", "maxMinutes": 5}]: how far background work may lag. |
events |
Event ids that happen this wave, telegraphed. |
contract |
Offer three contracts after this wave. |
global |
Share of far users from this wave on. |
boss, name |
Waves 4, 8 and 12 are bosses. |
brief |
What Kernel says first when the wave begins, at most 240 characters: a boss's intro. The rest of the briefing comes from the wave itself. |
debrief |
A ## Debrief: <id> section shown after the wave. |
From wave 3, one incident a wave is also drawn from the eventPool
(weighted, never the one drawn the wave before, and no spikes on a boss).
A contract has an id, name and text, and any of: useCase with
rps and growth (it adds that use case), requirements, freshness,
cash, revenue (a multiplier on every use case).
Cards #
---
name: Connection pooling
icon: cable
rarity: common
topic: databases
learn: [connection-pooler, connection-pool-size]
effect: capacity
target: db
stat: rps
value: 1.2
---
## Text
Databases take 20% more reads and writes.
## Why
Every database connection costs the server memory…
icon is required: a kebab-case lucide name
listed in frontend/src/game/engine/icons.ts (see Icons), and no
other card may use it; its tile takes the card's rarity colour. rarity is
common, uncommon, rare or legendary; unlock (Blueprints) makes a card
buyable instead of in the pool from the start. learn lists review card
ids. The effect is one the engine implements:
| Effect | target / value |
|---|---|
capacity |
Component id or role, stat rps, reads or writes; multiplier. |
latency, cost |
Component id or role; multiplier. |
cache-hit, edge-hit |
Added to every hit ratio. |
timeout |
What a failed call costs, in ms. |
coalesce |
Cold caches and stampedes do nothing. |
autoscale |
App servers and workers resize every tick. |
write-batching |
Share of background messages that write. |
payload |
Multiplier on every payload. |
presigned |
Uploads go straight to object storage. |
hot-key |
Multiplier on the hot-key penalty. |
failover |
No write outage while a SQL replica is promoted. |
reserved, spot |
Cost multiplier on app servers (no scaling below today's for 3 waves) or workers (they lose a replica in any incident). |
trust, cash, interest, oncall, loadtest, streak |
Paid once, or a per-wave allowance. |
A card may have a downside: downside (one of capacity, latency,
cost, cache-hit, edge-hit, trust, interest) with
downside-target, downside-stat and downside-value, which must work
against the player (a multiplier above 1 on cost or latency, a negative
Trust). Say it in ## Text.
Events #
---
title: Cache stampede
icon: snowflake
category: incident
topic: caching
learn: [cache-stampede, cold-cache-restart]
effect: cache-cold
target: cache
values: ["0", "0.5"]
duration: 2
telegraph: The cache cluster restarts for a version upgrade.
counters: [request-coalescing]
requires: [cache]
min-wave: 4
---
## What happened
## Why
## What a senior engineer would do
Effects: traffic (multiplier), write-surge (multiplier on the use cases
that write, or target: async for those with background work), bots
(multiplier of real traffic), az-down, node-down (the first component
matching target), failover (a SQL database), cache-cold (values per
tick, a share of the usual hit ratio), latency (multiplier), hot-key
(share), external-slow (latency in ms; target an external id or none for
all). from fixes the first tick; otherwise the seed picks it. then names the
event it sets off when it caused a breach (see above). requires
lists roles the board must have for the pool to draw the event. icon is
required, as for cards, and unique among the events; its tile is red for an
incident and pink for a spike. All three sections are required: they are the
debrief.
perks.json #
{ "id": "seed-round", "icon": "piggy-bank", "name": "Bigger seed round", "text": "Start every run with $250 more per level.", "costs": [6, 10, 14], "effect": "cash", "value": 250 }
costs are the Blueprints for each level, value is the effect per level,
and effect is one of cash, trust, free-reroll, starter-card,
loadtest or oncall. icon is required and unique among the perks.
mutators.json #
{ "id": "licence-audit", "name": "Licence audit", "icon": "receipt", "text": "…", "why": "…", "score": 1.15, "cost": [{ "target": "sql", "mult": 1.75 }], "excludes": ["snapshots"], "learn": ["cache-aside"] }
score multiplies every tick's points (above 1, at most 2). The effects, any
of them: cost (bill multipliers by component id or role), traffic
(read for GET use cases, write for the rest), global (the far users'
share from the first wave), cash and interest (multipliers on the
starting cash and the interest cap) and events (an event id on given waves,
2 to 12). excludes lists the scenarios it would make impossible, so they
never offer it. text says what changes, why the design it pushes toward.
bounties.json #
{ "id": "cool-servers", "name": "Cool heads", "icon": "gauge", "text": "Keep every app server under 50% busy at the peak.", "kind": "max-utilization", "role": "app", "value": 0.5, "cash": 150, "points": 250 }
kind is the test: max-utilization (every node of role under value at
the peak), budget (the bill under value × revenue), clean,
no-breach (no breach of kind breach all wave), right-sized,
no-oncall and no-loadtest (a clean wave without a hotfix, or without a
load test). event (an event
effect) and boss limit it to waves that have that incident, or a boss.
cash is paid at once, points × the act.
Icons #
Perks, mutators, bounties, cards and events each have an icon of their own:
an icon may appear once in each of those, but not twice in one of them. The names are lucide's, listed in
frontend/src/game/engine/icons.ts (no React, so proschi game check can
read it) and mapped to their components in
frontend/src/game/ui/gameIcons.tsx. To use a new icon, add its name to
both; the frontend tests fail if the two lists differ.
Tickets, versions and migrations #
A wave's ticket: "ticket": {"id": "multi-pet", "from": "pm", "kind": "schema", "title": "Multi-pet bookings"}.
from is pm, cto, customer, legal, finance, sre or marketing;
kind picks its icon (feature, scale, compliance, mobile, region,
api-version, schema, data-move, deprecation, security, cost,
incident, reliability, analytics, performance). Its text is the
## Ticket: <id> section.
An old API version is a use case with "legacy": {"upkeep": 400, "replacedBy": "book-v2"}.
A migration, in "migrations":
{
"id": "pets",
"name": "the multi-pet migration",
"entity": "Booking",
"store": "db",
"needs": ["book-v2"],
"writers": ["book", "book-v2"],
"oldReaders": ["book"],
"backfillRps": 900
}
needs are served only from the cutover, writers write twice from the dual
write to the contract, and oldReaders break once the old shape is dropped.
An on-call wave's diagnosis: a question and options, each with an
id, text and why, exactly one of them "correct": true. A play picks
one with "diagnose": "<id>" (the first option when it says nothing).
Reference and wrong runs #
Every scenario ships with scripted runs, like a problem's reference solution
and wrong designs. A run is a seed, an optional loadout and ascension (and "twists": false
for the basic rules of a first run), and a play per wave:
{
"seed": "reference",
"loadout": { "unlocked": ["cache", "cdn", "tiers"], "perks": {} },
"plays": [
{},
{
"add": [{ "id": "lb", "component": "lb", "replicas": 2 }],
"set": { "api": { "replicas": 3 } },
"unwire": [["users", "api"]],
"wire": [["users", "lb"], ["lb", "api"]],
"pick": ["async-io", "right-sizing"],
"contract": "angel"
}
],
"expect": { "cleared": true }
}
A play changes the board deployed last wave (add, remove, set, wire,
unwire), may loadtest, take a bounty (an id, or first), ship live changes during the run
([{"tick": 2, "set": {"api": {"replicas": 6}}}], each with the same
add, remove, set, wire and unwire as a play), call the
oncall for a hotfix ([{"tick": 3, "node": "api"}], or with "act":
reboot, warm, ratelimit or shed with a useCase),
reroll, pick the first card on offer from a list, sign a contract,
migrate ([{"id": "pets", "to": "next"}]; to is next, rollback or
big-bang) and sunset legacy use cases (["book"]).
Waves past the list keep the board and skip every choice.
reference.jsonmust clear all twelve waves ("expect": {"cleared": true}).- Each
wrong/<name>.jsonis a plausible design that must lose by a wave ("expect": {"failsBy": 8}): no cache, no CDN, a provider called inline. It may also name the breaches it must show ("shows": ["compat"]), or only those, for a mistake the run survives. Add anotesaying what it shows. - The check also plays "do nothing" (the start board, every wave), which must lose by wave 8 (or the wave before the last, in a shorter scenario).
- And it plays the reference under the basic rules of a first run (no
bounty or contract, and its
livechanges made before the deploy): it must clear Shortly, the scenario new players learn on, and get past act 1 in the other Scale or Fail scenarios.
Balancing #
cd tooling
npm run build
node dist/cli.cjs game sim shortly # the reference run, wave by wave
node dist/cli.cjs game sim shortly --seed other # the same plays with other incidents
node dist/cli.cjs game sim shortly --run my.json --ascension 5
node dist/cli.cjs game sim shortly --basic # the basic rules of a first run
sim prints each wave's cost, revenue, points, Trust and what broke. Good
scenarios:
- teach one new idea per wave, and make each act's last wave a boss;
- break last wave's design every two or three waves (traffic about ×1.5 a wave), so there is always something to do;
- burn cash early and turn a profit once the design is right (a hockey stick), with no single build that wins every scenario;
- keep requirements achievable: a dependency at 99.9% caps the use cases that call it, and far users cannot have a 50 ms p99 without a CDN hit.
Checks #
node tooling/dist/cli.cjs game check # everything below; exits 1 on any violation
node tooling/dist/cli.cjs game lock # adds new ids to ids.lock
game check reads every file and checks: fields and their values, ids in
ids.lock (and none removed), review cards, topics and practice problems
that exist, card and event targets, icons (known, and unique within their
kind), requirement lines that parse and name a use case, traffic for every
active use case, start boards the first run allows, and the scripted runs.
For every mutator a Scale or Fail scenario offers, it also plays the
reference with that mutator through act 1, which it must survive: a twist
may force a new design later, but should not end a sound one at once. And it
flags a far-user mutator in a scenario with a latency limit the ocean alone
breaks (a use case no edge can answer, under 120 ms): exclude it there. It
plays the reference under the basic rules of a first run too (see
Reference and wrong runs). The frontend tests
run the same check.
Checklist #
- Write
scenario.mdandscenario.json(copy a scenario close to yours). - Write
reference.jsonand at least onewrong/*.json; tune withgame simuntil the reference clears with some margin and the wrong runs lose for the reason in their note. - New cards or events: one file each, with
learncards and all sections. New mutators or bounties: an entry inmutators.jsonorbounties.json. node tooling/dist/cli.cjs game lock, thengame check.npm testinfrontend/andtooling/.- Open the pull request with a conventional commit title (
feat(game): …); release-please adds it toCHANGELOG.md.