Game backends have an unusual property: the behaviour is often intricate and highly stateful, but the domain vocabulary is full of terms that mean something specific to the team and nothing to anyone else. That combination makes them unusually well suited to specification — and unusually easy to specify wrongly.
This guide covers the four areas where game backend specifications most often go wrong.
Matchmaking is a rules engine, so write it as one
Matchmaking rules compound: skill band, party size, region latency, queue time, character roles, party composition. Each rule is individually simple and the combination is where the bugs live.
The specification should separate the rules from the search, because the search is implementation and the rules are intent.
Feature: Matchmaking queue
Scenario: A solo player is matched within their skill band
Given player "P-221" has a rating of 1480
And the rating expansion is 200 points
When player "P-221" enters the queue
Then player "P-221" is matched with an opponent rated between 1280 and 1680
And the match region equals the player's region
Scenario: A player is not matched across a region boundary
Given player "P-221" is in region "eu-west"
And the queue for region "eu-west" contains no eligible opponent
When 40 seconds elapse in the queue
Then player "P-221" remains queued
And no match is created
The second scenario is the one worth attention. "Remains queued" is the correct behaviour — expanding the search across regions would leak the player’s presence to another region and break their privacy expectations. A specification that never mentions region would let the implementation quietly expand the search, and players would notice.
State the exclusion rules as explicitly as the inclusion rules. Exclusions are where intent hides.
Inventory limits are stated as limits
Inventory is a bounded resource with a hard cap, and the interesting behaviour is what happens at the cap.
Scenario: An item is added to a full inventory
Given player "P-221" has 100 items in their inventory
And the inventory limit is 100
When player "P-221" picks up "iron_sword"
Then the pickup is rejected with code "INVENTORY_FULL"
And the inventory contains 100 items
And the item "iron_sword" is not added
The third clause is the one that distinguishes a real check from a status code. "The pickup is rejected" could be satisfied by a handler that rejects the request but has already mutated the inventory. "The item is not added" cannot.
State the limit as a number, not as a concept. "The inventory limit is 100" is checkable; "the inventory is full" is not, because a reader cannot tell what full means or whether the limit varies.
Reconnection is the classic state-machine bug
A player loses connection mid-session. The state machine has to decide whether the session continues, whether the player is replaced, and whether actions taken during the disconnection are replayed or discarded.
Scenario: A player reconnects within the grace period
Given player "P-221" is in a match
And the connection to player "P-221" drops
And 25 seconds elapse
When player "P-221" reconnects
Then player "P-221" resumes the same match
And the player's score is unchanged
And the player's inventory is unchanged
Scenario: A player does not reconnect within the grace period
Given player "P-221" is in a match
And the connection to player "P-221" drops
And 90 seconds elapse
When player "P-221" reconnects
Then player "P-221" is placed in a new match
And a reconnect penalty is applied to player "P-221"
The grace period is a number that appears in both scenarios. It should appear in the specification as a constant, not as a value repeated in prose, because when it changes — and it will — the specification has one place to change.
Note that the second scenario asserts a penalty. Specifications of reconnect behaviour usually assert only the mechanics ("placed in a new match") and leave the consequence implicit. If there is a penalty, a reward, or a warning, it is a rule, and rules belong in clauses.
Seasonal and event rules change, and that is fine
Live-service games change. Seasonal rules, event rewards, and balance patches are part of the specification, and they are the part most likely to rot.
The answer is not to avoid specifying them. It is to specify them in a way that separates the rule from the value:
Scenario: The seasonal double-XP event applies its multiplier
Given the seasonal event "winter_2026" is active
And the event multiplier is 2
When player "P-221" earns 500 XP
Then player "P-221" has 1000 XP
"When the seasonal event is active" and "the multiplier is 2" are both preconditions. They are set up as data, not hardcoded into the scenario. The scenario states the rule — the multiplier applies to earned XP — and the values can change without touching it.
A specification that hardcodes winter_2026 and 2 into the scenario body is a specification that will be wrong in eight weeks, and everyone will stop trusting it.
What to leave implicit
- Rendering, animation, and client presentation. The server does not know what the player sees.
- Client-side prediction and reconciliation. It is a real mechanism, but it is a client concern; specify the server’s observable state and let the client be a client.
- Anti-cheat heuristics. Almost impossible to specify precisely, and the teams that try usually produce a specification nobody can review.
The review question for this domain
For each clause, ask:
Would a player notice if this were false?
If yes, it belongs in the specification and needs a scenario that could fail. If no — internal bookkeeping, telemetry, a counter nobody reads — it probably does not belong in a specification at all, and including it makes the review slower for everyone.
Related
- Gherkin feature files — the format and its conventions
- Gherkin for trading and risk rules — similar shape, different stakes
- Templates — a starting point