game-design-document

Game Design Document (GDD)

A GDD is the single source of truth for what your game is — concept, mechanics, world, player flow, monetization, tech specs. It's also a living document: design evolves, reviewers leave comments, decisions get made then questioned then re-made.

This skill provides the template, the workflow for maintaining it as it evolves, and the rules for what belongs in a GDD vs. somewhere else.

When to invoke

• Concept locked via game-design-brainstorm → ready to expand to full GDD
• New system being added (combat, inventory, save, etc.) → add a section
• Reviewer left comments → resolve them (decisions, open questions, defer)
• Pre-milestone audit — does the GDD match what's actually being built?
• After a pivot — sections need to be invalidated, replaced, or marked deprecated

Two GDD formats to choose between

Single-file (recommended for solo / small team, <50 pages):

• One markdown file: docs/GDD.md
• All sections inline
• Comments as inline markers (<!-- @reviewer: question -->)

Multi-file (recommended for 5+ team, 50+ page GDD):

• docs/gdd/00-overview.md, 01-mechanics.md, ... separate files per major section
• Decisions log: docs/gdd/decisions.md
• Open questions: docs/gdd/questions.md
• Index: docs/gdd/README.md

For ARPG / city-builder / mobile PvP scale projects, multi-file pays for itself by month 3. For game jam or small-scope project, single-file is fine.

The GDD template

Below: every section a GDD should have, in order, with what goes where and what does NOT.

Section 1: Overview (1-2 pages)

From game-design-brainstorm output:

• One-sentence pitch
• Genre + platform + perspective + camera
• Target audience
• USP (3 bullets, specific)
• Core gameplay loop (moment-to-moment + session level)
• Scope (team size, timeline, commercial target)
• Biggest risk + prototype status

Anti-pattern: don't expand the pitch into prose. The pitch should fit on a sticky note. Detail goes into Section 3+.

Section 2: Story / Setting / Narrative (2-5 pages)

• Setting: where, when, who. World rules (genre conventions, what's different).
• Initial narrative: how the game opens, what motivates the player character
• Story arcs: 3-5 high-level story beats across the playthrough
• Characters: named NPCs, factions, antagonists (1-paragraph each)
• Tone: dark / hopeful / comedic / surreal. Reference 2-3 games or films with similar tone.

For systems-heavy games (city-builders, RPGs without narrative campaign), this section can be 1 page focused on setting + tone. For story-driven games, this section can be 30+ pages with branching dialogue trees in a separate doc.

Anti-pattern: don't write the entire script here. Reference a separate docs/script/ directory for dialogue and detailed narrative.

Section 3: Core Mechanics (the bulk of the GDD — 10-50 pages)

This is where you describe every gameplay system in enough detail that an implementer can build it without designer follow-up.

For each mechanic, structure:

### [Mechanic name]

**Purpose**: What this mechanic adds to the loop. Why it exists.

**Player verbs**: What the player does (in/with this system).

**Inputs**: Resources, choices, time the player commits.

**Outputs**: Rewards, progression, state changes.

**Rules**: How it works step by step. Include numbers (cooldowns, damage formulas, costs).

**Failure / edge cases**: What happens when the player can't do this? Empty input? Conflicting inputs?

**Open questions**: <!-- @designer: question -->

**Cross-references**: Links to other systems this depends on (e.g. "depends on the Tech Tree from §3.4")

Common mechanics to cover for different genres:

City-builder / colony sim:

• Resources (extraction, processing, storage — see Sea Nation example)
• Population (stats, roles, needs — happiness, hunger, fatigue, oxygen)
• Buildings (categories, placement rules, upgrade paths)
• Technology / research tree
• Events (random, scripted, environmental — disasters, trade, attacks)
• Time progression (day/night, season, year)
• Combat / defense (if applicable)
• Exploration / expansion

ARPG:

• Stats (primary attributes, derived stats, scaling formulas) — see arpg-systems-checklist
• Damage calculation (formula, types, resistances, crit rules)
• Skills / abilities (per class or shared tree)
• Loot (item types, rarity tiers, affix system)
• Inventory (grid or slot-based, stack rules, equip slots)
• Progression (XP curves, level rewards, respec policy)
• Combat (melee/ranged/spell, AI behavior, boss patterns)
• Difficulty scaling

Mobile PvP:

• Match types (1v1, 3v3, 5v5, asymmetric)
• Matchmaking (skill brackets, queue times)
• Player progression (XP, rank, season pass)
• Classes / characters / bioforms (each gets a sub-section)
• Combat (movement, cooldowns, hitboxes)
• Economy (soft currency vs. hard currency)
• Crafting / equipment

Roguelite:

• Run structure (length, biomes, milestones)
• Permanent progression (meta-currency, unlocks)
• Build variety (synergies, item rarity, randomization)
• Death penalty
• Endless mode (if any)

Universal:

• Tutorial / onboarding flow
• UI / HUD layout (what info shown, when)
• Save system (what's saved, save points, cloud)
• Settings (graphics, audio, input remapping, accessibility)

Section 4: World / Environment (3-10 pages)

• Maps / zones / biomes: list each with size, theme, mechanical differences
• Environmental hazards: what hurts the player, what helps
• Points of interest: landmarks, towns, dungeons (if applicable)
• Procedural vs handcrafted: which areas, by what algorithm

For open-world games, this becomes a sub-doc (docs/world/). For arena-based games (PvP), this is the maps reference.

Section 5: Player Flow (3-10 pages)

The user-facing first 30 minutes + critical paths after.

Cover in order:

• Boot → splash → main menu (what's there)
• New game flow (character creation, difficulty pick, tutorial)
• Tutorial structure (forced vs optional, what's taught, how long)
• First hour gameplay (what unlocks when, the "aha" moment)
• Mid-game (after onboarding, before endgame)
• Endgame (what keeps players past the campaign)
• Death / failure flow (where do they respawn, what do they lose)
• Quit / resume (save flow, daily check-in if F2P)

This section is the player retention contract. Get it right and players stay. Skim it and they bounce in 5 min.

Section 6: Visual & Audio (1-5 pages)

• Art style: highpoly stylized / lowpoly pixel / 2D hand-drawn / 3D realistic. Reference 3-5 games for visual feel.
• Color palette: 3-5 anchor colors per major biome/zone
• Camera framing: standard shot, hero shot, cutscene framing
• Animation principles: snappy / weighty / cinematic
• VFX: hit feedback, environmental, magical
• Audio direction: synthwave / orchestral / lo-fi / chiptune. Reference 3-5 game soundtracks.
• SFX hierarchy: what gets a unique sound (combat hits, UI clicks, ambient)
• Voice acting: yes / no / partial

For polished projects this expands into a separate Art Bible document. For prototypes, 2-3 pages is fine.

Section 7: Monetization (1-5 pages — if F2P or live-service)

Skip this entire section if your game is pure paid (single purchase, no DLC). For F2P / live-service:

• Soft currency (earned in-game): faucets (how to earn) + sinks (what to spend on)
• Hard currency (real money): purchase tiers, USD prices, conversion rates
• Battle pass / season pass: tier rewards, length, free vs paid track
• Ads: rewarded video placements, frequency caps, gated rewards
• IAPs: cosmetic vs progression-affecting (transparent which)
• Anti-pay-to-win policy: explicitly written
• Whale design: top spender behaviors, conversion targets

Be honest in this section. F2P that says "no pay-to-win" but ships hard pay-to-win loses trust fast.

Section 8: Technical Specifications (1-2 pages)

• Target platform(s): PC (Steam — Win64, macOS, Linux?), mobile (Android API level, iOS version), console
• Minimum spec: CPU, GPU, RAM, storage, OS version per platform
• Recommended spec: as above, better
• Network: required online / offline-first / hybrid
• Engine + render pipeline: Unity 2022.3 LTS + URP (or HDRP, or Built-in, or Unreal 5.3, etc.)
• Languages supported: ship-with vs post-launch
• Accessibility features: colorblind modes, font scaling, remappable controls, subtitle options

Section 9: Links + Appendix (1 page)

• Game flow diagram (Miro / Whimsical / draw.io link)
• Moodboard (Pinterest / Figma board)
• Reference games shortlist
• Team capacity doc (if relevant)
• Concept art portfolio
• Sound reference playlist

Living document workflow

A GDD is not "write once, freeze". Design evolves. The workflow:

Inline comments

When reviewing a section, leave comments rather than overwriting. Two formats:

HTML comment style (markdown-clean, invisible in rendered output):

The Player can build up to 80 buildings.
<!-- @marcin 2026-01-15: too many? Test 30, 50, 80 caps in prototype before committing -->
<!-- @collaborator 2026-01-16: agreed, 80 feels arbitrary. Add to open questions. -->

Visible comment style (for when comments themselves are content):

> **Open question (@marcin, 2026-01-15)**: should building count cap at 80 or scale with zone tier?
> **Reply (@collaborator, 2026-01-16)**: scale with tier — 30/50/80 by zone level. Forces tradeoff: rush new zone vs. consolidate.

Pick one style per project, stick with it.

Decision log

Major design decisions go to docs/gdd/decisions.md (or a section in single-file GDD):

## Decision log

### 2026-01-15: Building count cap scales with zone tier

**Question**: hard cap at 80 or tiered?
**Options considered**: flat 80 cap; tiered (30/50/80); unlimited but resource-bottlenecked.
**Chosen**: tiered.
**Why**: forces explicit tradeoff between rushing new zones and consolidating existing colony. Flat cap is arbitrary; unlimited removes a design lever.
**Revisit if**: playtests show players don't engage with the rush-vs-consolidate choice.

Without this log, "why did we decide X" gets re-litigated every 3 months.

Open questions

## Open questions

- [ ] Should colonists have a "sanity" stat in addition to happiness? (@marcin, 2026-01-15) — Defer to prototype, decide month 3.
- [ ] Tutorial: forced or skippable? (@collaborator, 2026-01-20) — Need playtest data.
- [ ] Save system: cloud-only or local + cloud? (@team, 2026-01-22) — Steam Cloud auto-syncs `persistentDataPath`, default to that. Confirm month 4.

Mark [x] and move to decision log once resolved.

Deprecation markers

When a system gets removed or replaced, don't delete it from the GDD — mark it deprecated with a date and a reference to what replaced it:

### Skill respec system (DEPRECATED 2026-02-10)

Originally: free respec at any time via menu.
Replaced by: respec items as rare drops (see §3.7 — Items).
Reason: free respec removed all build commitment. Items create scarcity decision.

This preserves design history for future "wait, didn't we try X already?" conversations.

What belongs in a GDD vs. somewhere else

Belongs in GDD

• Mechanics: how systems work, formulas, rules
• World: setting, zones, themes
• Player flow: first-time experience, retention loops
• Visual & audio direction (high level)
• Tech specs (target platforms, engine)
• Monetization (if F2P)

Does NOT belong in GDD

• Implementation details — that's the codebase + tech_state.md
• Bug lists — that's an issue tracker
• Sprint planning — that's working_memory.md or your project tracker
• Concept art portfolio — that's a separate art bible
• Full dialogue scripts — that's docs/script/
• API specs — that's API docs
• Marketing copy — that's a separate marketing doc

If you find yourself adding sprint-level detail to the GDD, you're conflating documents. The GDD answers "what is this game"; other docs answer "how do we ship it" and "what's broken right now".

Maintenance cadence

• Pre-milestone: 30-min GDD audit. Does the GDD match what's actually built? If not, either the build is wrong (track to backlog) or the GDD is stale (update or mark deprecated).
• Monthly: review open questions. Resolve what you can, defer what you can't, kill what's no longer relevant.
• After playtests: update sections that playtest invalidated. Decision log every major change.
• Pre-public-demo or launch: full pass. Strip deprecated sections from publicly-shared version (keep them in versioned git history).

Anti-patterns

• Writing the GDD all at once before any prototyping — you'll be wrong about half of it. Prototype, learn, then write.
• GDD with no decisions.md — every major change goes into oral tradition, future-you forgets why.
• Sections marked "TBD" for 6 months — those aren't placeholders, they're warnings the design isn't actually figured out. Either resolve or remove.
• Implementer ignoring the GDD because it's stale — pre-milestone audit fixes this. If the GDD lies, nobody trusts it.
• GDD has bug list, sprint plan, asset list interleaved — separate documents per purpose.

Real example structures

The Sea Nation GDD (city-builder / colony sim) covers:

1. Wstęp (Koncept + USP + Target)
2. Game Loop + Game Scale
3. Rozgrywka i Mechaniki (Tryby, Surowce, Rozwój kolonii — Populacja / Buildings / Technologie / Ekspedycje / Eksploracja, System walki, Zdarzenia losowe, Postęp czasu)
4. Menu Główne
5. Story (Setting, Narracja, Postacie)
6. Visual & Audio (Styl wizualny, Elementy świata, Przerywniki, Udźwiękowienie)
7. Interfejs (UI, Sterowanie, Kamera, Photo Mode)

The SimRoyale GDD (mobile PvP RPG) covers:

1. Przegląd
2. Koncepcja Gry
3. Główne Mechaniki Gry (Klasy + Frakcje, Statystyki Postaci, System Walki, Zarządzanie Zasobami, Crafting i Ekwipunek, System Wydarzeń / Sezony)
4. Świat Gry (Środowiska)
5. Tryby gry (PvP modes)
6. Przepływ Gracza (Ekran Startowy → Tworzenie Postaci → Tutorial → Eksploracja → Walka → Crafting → Eventy → Podsumowanie)
7. Monetyzacja
8. Specyfikacje Techniczne (Android, iOS)
9. Podsumowanie + Linki (Game flow, Moodboard)

Different genres, same meta-structure. Use one as a template, swap the genre-specific mechanics.

See Also

• game-design-brainstorm — Run BEFORE writing GDD. Produces Section 1.
• arpg-systems-checklist — Genre-specific mechanic checklist for ARPGs
• unity-architecture — After GDD locks, foundations for the codebase
• tdd-with-claude — Implementing systems from the GDD with tests-first discipline