GDD structure, templates, and living documentation patterns for game projects — wiki pages, design docs, section layout, sync triggers
A GDD (Game Design Document) is the living specification of a game's design intent. In this project, it exists at two levels:
docs/wiki/Demo-{DemoName}.md) — per-demo, code-synced, <300 lines| Section | Purpose |
|---|---|
| Game Overview | Title, genre, platform, audience, core loop |
| Game Pillars |
| 3-5 non-negotiable design tenets |
| Gameplay Mechanics | Core loop, combat, inventory, progression |
| Game Flow | Phase state machine, win/lose conditions |
| UI/UX Design | Screen layout, HUD, menu flow |
| Economy & Monetization | Currency, shops, drop rates |
| Technical Requirements | FPS target, memory budget, platform constraints |
| Art & Audio Direction | Visual style, palette, sound design |
| Content Matrix | Items, enemies, levels with stats |
| Balance Parameters | Tuning knobs, difficulty curves |
→ See references/gdd-template.md for full section templates
Editor/ (SceneSetup, PrefabCreator) to extract unit counts, arena sizes, menu pathsRuntime/ (Systems, Components) to extract class names, constantsgame-designer agent→ See references/demo-wiki-template.md for mandatory section list and examples
| Event | Action |
|---|---|
| New demo implemented | Create docs/wiki/Demo-{Name}.md from template |
| Code changes (systems, components) | Update affected wiki sections |
| Stats/balance tuned | Update Content Matrix and Balance Parameters |
| UI redesigned | Update UI/UX Design section |
| New editor tool added | Update Editor Tools section |
| Library module added | Update Library Coverage section |
→ See references/living-doc-patterns.md for sync patterns and cross-reference conventions
| # | Mistake | Fix |
|---|---|---|
| 1 | Hardcoded numbers in wiki that don't match code | Grep source constants before writing |
| 2 | Wiki over 300 lines | Extract deep-dives to Domain-*.md, link from wiki |
| 3 | Missing cross-reference updates | After any wiki change, search for pages that link to it |
| 4 | Stale system class names after rename | Run grep for old name, update all occurrences |
| File | Coverage |
|---|---|
references/gdd-template.md | Full GDD with all standard sections and guidance |
references/living-doc-patterns.md | Sync triggers, cross-reference conventions, wiki patterns |
references/demo-wiki-template.md | Demo-*.md mandatory structure, how to gather info from code |