How to write a game design document: rules and acceptance criteria

What real development documents reveal

Condor's 1994 Diablo proposal covers game design, marketing and production. Its Game Design section connects dungeon exploration, character progression and preparation in town into a recurring loop. Gameplay follows character creation, movement and interaction, while Development and the schedule set out the staffing and work needed to build that experience. All appear in the eight-page original released by David Brevik.

LucasArts' 1996 Grim Fandango puzzle document works at a different scale. The Year One character list leads into a puzzle dependency diagram and a location layout. Each puzzle has a setup and a solution. Together, these describe the story's progression, the requirements for moving forward and the player's route through the world.

This article uses those two originals alongside Ubisoft's design exercise, Frictional Games' design principles, Riot Games' prototyping guidance and Warren Spector's postmortem. The state and data tables and the 30-second rhythm exercise below are our own worked examples.

Choose the right level of detail

Start with the reader and the decision they need to make. An investor needs to understand the audience, the game's distinctive experience and the scale of production. A development team needs input rules, states, data and exception handling. A tester needs reproducible conditions and expected results.

Ubisoft's public Rainbow Six Siege operator design exercise separates goal definition, the pitch and prototype planning. It begins with the target audience and problem, explains the role, equipment and play experience, and then develops a plan to test the goal. This is the structure of a public mentorship assignment.

On a small project, this approach can be organized into an overview, feature specifications, content tables and test records. The overview sets priorities, the specifications define behavior, and the tables hold data used repeatedly in production. The structure below is our synthesis of the published sources.

Design principles guide feature choices

Frictional Games published five design principles for SOMA that connect actions, the world and the story. Even a locked-door puzzle has a short-term reason for opening the door and a narrative reward. The principles give the team a way to assess whether each scene creates the intended experience.

For a rhythm game, possible design principles include anticipating the next beat from a short audio cue, using input feedback to improve the next attempt, and learning different patterns through the same controls. Each principle becomes useful when it names a behavior the team can observe and explains why a feature belongs in the game.

A memory challenge depends on clearly separating demonstration from response, deciding how much the player must remember and choosing how often to repeat it. A reaction challenge depends on how early targets become visible and how readily players can distinguish their direction. Recording those differences helps set priorities for difficulty and presentation, even when both modes use the same buttons.

Connect play scenarios to rules

Gameplay in the original Diablo proposal describes character creation, movement through town, interaction and entry into a dungeon. It also explains how movement and interaction depend on the clicked target and its distance. These ideas belong to the proposal's original turn-based design.

A play scenario gives the team a shared picture of the experience. Breaking it into rules identifies the events and states that need implementing. For a ball that the player hits at a target line, the specification needs an appearance time, a target time, an accepted input, a timing window and a way to show the result.

For each scene, specify entry conditions, information given to the player, available actions, system responses and the condition for moving on. Feedback should identify the event it communicates as well as its visual or audio form. A flash after an input conveys different information depending on whether it confirms receipt of the input or a successful hit.

Design puzzles and stages around prerequisites

The Year One puzzle diagram in Grim Fandango distinguishes tasks that follow in sequence from tasks that can proceed in parallel. The Location Layout on the next page shows movement between places separately. Reading PDF pp. 3–4 together reveals the difference between progression prerequisites and spatial access routes.

The distinction also applies to unlocks and learning order in a rhythm game: teach a single-beat input, introduce left/right changes, then unlock a combined pattern after both skills are learned. Specifying the required skills and entry conditions lets the learning sequence and menu locks use the same criteria.

Label progression links with their completion requirements and spatial links with the routes players can take. State what carries over after retries, interruptions and return visits. The diagram below shows our example of two parallel learning requirements converging.

Specify what each state and input can change

A feature specification answers a practical question: what happens when this event occurs in the current state? A transition table records the state, event, conditions, values to update, feedback and next state. Programmers, designers and testers can then check the same event against the same rules.

The single-beat exercise has ready, playing, paused and results states. Each note is pending, hit or missed. An input can score only while the round is playing and the note is pending. Once a note is marked hit or missed, that result is final.

Specify input priority as well. If timing windows overlap, the game needs a selection rule, such as choosing the pending note in the same lane with the smallest timing error. State how many notes one physical input can affect and how to handle repeat events from a held key.

Define duplicate-input handling at the event level. Use the first keyboard keydown and ignore repeat events. For touch, use pointerdown for the game input and handle the resulting click separately in the UI. This exercise allows one note per input.

Work out the timing for a 30-second exercise

Our fictional single-beat exercise is a 30-second, one-button build at 120 BPM. One beat lasts 60÷120=0.5 s, so 30 seconds contains 60 beats. The first four beats, from 0 s inclusive to 2 s exclusive, are preparation. Place 56 input targets at 0.5 s intervals from 2.0 to 29.5 s. For target index k=0–55, t(k)=2.0+0.5k seconds.

Compare input and target times on the same music timeline. If correction c is subtracted from the input time, error e=t_input−c−t_target. A positive c interprets the recorded input as that much earlier. The trial judgment rule is |e|≤0.100 s, including both endpoints. Choose production values through tests of the target devices' input and audio conditions and through playtesting.

Here, music position means seconds elapsed since the audio start reference. Calibration tests examine output latency and player timing tendencies separately. Keep frame numbers and audio target times in their own units, and specify how they convert to the shared timeline used for hit detection.

Exclude inputs during preparation from scoring. While playing, inspect the hit windows of pending notes; an input outside the window leaves the target state unchanged. Finalize a pending note as missed once time exceeds target+0.100 s. The ready-state exclusion takes priority, so the first target accepts inputs only from 2.0 to 2.1 s. At 2.0 s, process the transition to playing before checking input. Other targets use ±0.100 s windows. The last note's late boundary is 29.6 s; open results at music position 30.0 s.

When the window is hidden, stop music and judgment time together. The resume button continues from the same music position with the remaining notes. Record initial audio preparation, resumption and AudioContext state as items to test in the execution environment.

Define data units and rules that must always hold

NC's public account of game design follows play requirements as they become rules, system flows and data. System designers define the structures and data that make the rules work. Content designers set individual values and balance them. The source describes how these roles work together within a studio.

Content tables hold values that designers produce repeatedly. A chart might use chart_id, chart_version, note_id, target time, input lane and note type as its main columns. For songs with tempo changes, include tempo segments and the convention for converting beat positions into time.

The single-beat exercise uses a fixed tempo, note_id=0–55 and target_seconds=2.0+0.5×note_id. Calculate appearance time by subtracting cue lead time from target time. Changing lead time from 1 to 1.5 s changes when the note appears while keeping its target time. Separating the values makes readability and judgment difficulty easier to adjust independently.

Import checks cover unique IDs, ordered target times, supported lanes, audio bounds and overlapping windows. If simultaneous notes are allowed, explicitly permit matching target times in different lanes. Version the conditions so the importer and editing tools use the same rules.

Treat inputs per beat, the length of uninterrupted input sequences, left/right changes, time spent memorizing demonstrations and rest sections as separate difficulty factors. Record which variables changed together and what was observed, so the next chart revision has a clear basis.

Estimate production scope and dependencies

Development in the Diablo proposal describes staffing and work in graphics, sound and programming. Its final schedule shows overlapping tasks and their order. The production plan follows the intended play experience.

Our example limits the first build to one character, one background, one note type, input effects and a results screen. Estimate artwork by subject, direction, action and appearance. Drawing two directions, three actions and two appearances separately gives 12 combinations. Note where mirroring or shared actions could reduce that work as separate production decisions.

A new stage needs audio preparation, background placement, difficulty review and input tests as well as a chart. A work table can identify prerequisites, owners, deliverables and review points for each stage. Audio playback and its timeline, for example, must work before the team can test whether chart timing and hit detection stay in sync.

Build prototypes to answer design questions

Riot Games describes prototypes in terms of their target players, a playable version of the core change, a shared team understanding and playtest evidence. It also discusses a game scaffold: the minimum structure of a genre needed to test a new element. What to build next follows from the question the prototype needs to answer.

A rhythm prototype might ask whether a longer lead time helps players notice and hit the first target. Keep target positions and the timing window fixed, change the lead time, then record time to first input, inputs during preparation and the positions of missed notes. If participants try both conditions, record their order and any effects of practice.

Keep tests of the rules separate from tests of the experience. Automatically injecting inputs at a window's boundaries checks hit detection. Watching what players notice and when they press without help reveals how guidance and learning work. Give participant comments, observed behavior and the editor's interpretation separate fields in the record.

Calculate hit rate by dividing successful notes by eligible notes. A participant's first result reflects their device, experience and instructions together. Keep individual results and attempt numbers, then repeat the observation after a revision. This allows design decisions to account for both correct behavior and the player's experience.

Use playtest results to revise the design

In his Deus Ex postmortem, Warren Spector describes evaluating systems against early goals and revising designs through proto-missions. He also recounts reducing the design document from 500 to 270 pages after reviewing playable missions. The account links evidence from play to the next production scope.

Record a rule ID, revision date, decision status, owner and test evidence. Adopted rules guide implementation; trial values define comparison conditions. For open items, identify the decision method and required evidence. Each change record should include the changed value, reason and affected tables, screens, saved data and checks.

Changing lead time affects note appearance, tutorial wording and test cases. Changing a timing window affects hit detection and the conditions used for comparisons. Where a value appears in several files, name its authoritative source. The design document, data and build should all be traceable to the same version.

Trace a feature from its rationale through validation

Link the exercise goal as G01, its input rule as R01, judgment rule as R02 and test as T01. For example, G01 can be anticipating regular intervals; R02 can judge one pending note once within ±100 ms; T01 can compare inputs at the 100 ms boundary with inputs outside it at 101 ms. All values are editorial learning examples.

Review the feature's purpose, normal flow, exceptions, data, visuals, sound, content requirements, tests and change history together. A useful check is whether another team member can build the same example from the document and compare the results. The template below includes blank sections and a worked example in that order.