QUBU / WORKSHOP

What Is a Game Design Document? Free GDD Template and Filled Example

QUBU
← Back to Journal7 min readUpdated: October 9, 2026

A Game Design Document records how a game is supposed to work: the player’s actions, the rules, the scope and the questions still open. It gives the team somewhere to check a decision when the playable build raises a disagreement.

Keep the first version short enough to use during production. Describe the decisions people keep asking about and add detail where a misunderstanding would cost work. If the build and the document disagree, check which one reflects the current decision, then update the other.

Free tool: Open the QUBU GDD Builder and use the structure for your own project.

What should a GDD include?

  1. The player promise.
  2. The core gameplay loop.
  3. Main decisions and risk–reward structure.
  4. Progression.
  5. Economy sources, sinks, and limits.
  6. Content structure.
  7. Controls and interface states.
  8. Save data, online behavior, and technical constraints.
  9. Analytics questions.
  10. QA risks.

Start with the player promise

Before listing features, write one paragraph that answers four questions: Who is the player? What do they repeatedly do? Under what pressure do they make decisions? What should they feel when the system works? If this paragraph is unclear, the rest of the document often becomes a catalogue of unrelated mechanics.

Describe the core loop with verbs

A sequence such as “observe → choose → spend → see the result → recover” reveals the actual structure of play. It also gives onboarding, interface, analytics, and QA a shared reference. Each verb should have a visible player action and a readable response. If a step exists only in the document, it may not exist for the player.

Record the reason behind every important rule

“The cooldown is 12 hours” will lose meaning when the number changes. “The cooldown is 12 hours so ownership cannot change several times overnight” preserves the design goal. Numbers are adjustable; the reason lets the team judge whether a new number still protects the intended behavior.

Do not hide technical constraints at the end

Save migration, server authority, offline behavior, low-end hardware, input devices, and platform SDK requirements can change design. When a constraint affects what the player can do or understand, it belongs in the relevant system section. Keeping it separate as an engineering note makes conflicts appear late, when they cost more to fix.

A reusable GDD structure

  1. Game summary
  2. Player promise
  3. Audience and platforms
  4. Core loop
  5. Controls and camera
  6. Progression
  7. Economy
  8. Combat or interaction rules
  9. Content structure
  10. Interface states
  11. Save and online architecture
  12. Analytics questions
  13. QA risks
  14. Success measures
  15. Open questions

Use decision records to keep the document actionable

For each critical system, add four short fields: purpose, assumption, accepted risk, and validation method. A statement such as “a siege lasts 18 hours” is incomplete. The purpose may be to give defenders time to respond; the assumption may be that a counterattack remains possible; the accepted risk may be slower pacing. Validation can use match abandonment, return behavior, and playtest feedback.

This format preserves why a decision was made when team members change. QA can identify the behavior to test, analytics can connect events to a product question, and production can see when the decision needs another review.

Turn feature lists into decision tables

Decision Player effect Risk Validation
Sieges last 18 hours Players have time to respond Pacing may slow down Abandonment and return rate
Storage is limited Spending decisions matter New players may feel blocked First-week overflow data
Battle results are delayed Asynchronous tension remains Feedback may arrive too late Return to the result screen

A decision table explains what a feature is trying to do. When a number changes, the team can still protect the expected player effect rather than treating the old value as permanent truth.

A filled mini example

Player promise

The player chooses regions and positions armies with limited information, then earns a lasting strategic advantage by reading risk correctly.

Core loop

Read the map → choose a target → spend resources → observe the counterplay → evaluate the outcome → form the next plan.

Open question

Can a new player understand the difference between attack and defense during the first three turns? Tutorial completion, first-match abandonment, and moderated playtest notes should be read together.

Assign ownership across the team

The GDD should have one accountable owner, but it should not represent one person’s viewpoint. Design maintains the player promise and system rules. Engineering maintains dependencies and performance limits. QA records failure states and risky interactions. Production tracks scope and schedule impact. Add an owner and last verification date to each major section so outdated decisions are not mistaken for current rules.

Three common GDD failures

The first is writing marketing language instead of operational rules. A GDD should explain how a feature behaves and where it can fail. The second is formatting ideas, assumptions, and approved decisions in the same way. Mark them clearly so the team knows what can still change. The third is letting the document drift away from the game. After a major system change, review the relevant section beside the working build.

How often should a GDD be updated?

Update it when a decision, assumption, interface between systems, or validation plan changes. Do not rewrite every sentence after every meeting. A useful document changes at the speed of meaningful decisions: slower than casual discussion, but fast enough to match the build.

The new team member test

Give one system section to a teammate who does not know the project. If they can identify the rule, player feedback, failure condition, responsible person, and test method from the document, the section is working. If they need a long verbal explanation, the solution is clearer decisions in the right place rather than more pages.

Pre-production GDD checklist

Conclusion

A strong GDD reduces uncertainty. It gives design, engineering, QA, and production the same answer when they inspect a system. Keep the player promise clear, record the reason behind rules, separate open questions from decisions, and connect every major risk to a validation method.

Filled GDD example: a three-level tactical puzzle

This is a fictional design example prepared by QUBU for this guide, not an announced game or a report of player testing. It shows how a design decision becomes an acceptance test and a production estimate.

GDD field Filled decision
Player promise Read the enemy’s next move and find a safe route with a limited number of moves.
Platform and scope Windows PC, single player, offline. The first slice contains three levels and one enemy type.
Board and controls A 5×5 grid. Click an adjacent empty horizontal or vertical square; each valid move spends one move. No diagonal movement.
Turn order Player moves → enemy moves to the previously indicated square → check collision → check exit condition → display the next enemy move.
Win and loss Reach the exit within eight moves without a collision to win. Fail if the eighth move ends outside the exit or the player shares a square with the enemy. A collision on the final move overrides reaching the exit.
Feedback Show the enemy target with an arrow and a pattern; do not rely on color alone. Update remaining moves every turn.
Saving Persist completed levels. Do not save a turn in progress; reopening that level starts it from its initial state.
Outside the slice No online accounts, PvP, random maps, item economy or shop.

Acceptance tests derived from this GDD

  1. Clicking an invalid or diagonal square changes neither remaining moves nor enemy state.
  2. Reaching the exit without collision on the eighth valid move shows the win screen; a collision on that same turn shows the loss screen.
  3. Restart restores the player, enemy and eight available moves to their initial state.
  4. Reopening the application retains completed-level information and resets any unfinished level.
  5. The enemy target remains understandable from its arrow and pattern without identifying its color.

What should the first playtest ask?

Plan a small observation session with five people; it is not statistical evidence of success. Before a move, ask the participant to point to the enemy’s next square. Record the misunderstood turn and any explanation required. If the indicator is unclear, improve it and test again before expanding the level count. Do not present unmeasured completion or retention rates as findings.

Write your own rules in the GDD Builder. See the budget scenario for an illustrative production breakdown of this scope.

Explore this topic

Continue with the main guides in the same content cluster.