Gherkin for game backend APIs

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.

Next