skills-IA/game-designer/references/gdd-structure.md

GDD Structure & Right-Sizing

A GDD's job is to get read and used, not to be exhaustive. Pick the right size before picking the sections.

Which size to use

Size	When	Length
One-pager / pitch doc	Early concept, pitching to a publisher/team lead, internal greenlight	High concept, pillars, core loop, hook, target audience/platform, comparable titles. ~1 page.
Lean GDD	Most indie/small-team projects, vertical slices	Adds: detailed core loop breakdown, primary systems (not exhaustive), progression overview, art/audio direction notes, scope/milestones. ~5-15 pages.
Full GDD	Larger teams, publisher-facing, complex systems that need shared source of truth	Every section below, fully detailed, often split into separate system-specific docs linked from a master doc.
Systems-only spec	User just wants one system nailed down (e.g. "write up the crafting system")	Skip the rest of this file — go straight to the relevant pattern in systems-design-patterns.md and write a focused spec: goal, player-facing rules, edge cases, open questions.

Default to lean GDD unless the user's request or stated team size clearly calls for more or less.

Full section list (use what's relevant, cut the rest)

1. High Concept — one sentence. What is this game, in genre-comparison shorthand if useful ("X meets Y").
2. Pillars — 3-4 design pillars that every feature decision gets checked against. Concrete, not generic ("readable chaos in combat," not "fun gameplay").
3. Target Audience & Platform — who, and where they'll play it. Drives UI scale, session length assumptions, monetization model if any.
4. Core Gameplay Loop — the verb loop the player repeats minute-to-minute, and how it nests into a session-level loop and a meta/long-term loop. Diagram this as a simple cycle if it helps (explore → fight → loot → upgrade → repeat).
5. Mechanics — the verbs themselves: what the player can do, moment to moment. Keep this to player-facing rules, not implementation.
6. Systems — the underlying machinery: combat system, progression system, economy, crafting, AI behavior, etc. Each gets its own subsection or its own doc once it's non-trivial — point to systems-design-patterns.md.
7. Progression — how player power/unlocks/narrative reveal unfolds over the full game. Pacing of new mechanics, not just numeric power.
8. Level/World Design — structure (linear, hub-and-spoke, open world), how levels teach and escalate. See the Stage 5 guidance in the main skill file.
9. Narrative & World — setting, tone, story structure, how much story is delivered vs. emergent. Skip or keep minimal for mechanically-driven games.
10. UI/UX — key screens, HUD philosophy, accessibility considerations (colorblind modes, remappable controls, difficulty options).
11. Art & Audio Direction — mood references, visual style pillars, audio's role (diegetic feedback, music adaptivity). Light touch unless the user is the art/audio lead.
12. Monetization (if F2P/mobile) — currency types, what's sold, what's earnable, and explicitly how monetization doesn't undercut the core pillars. Cross-reference the economy section in systems-design-patterns.md.
13. Technical Considerations — engine, platform constraints, anything that bounds design choices (e.g. mobile thermal/battery limits, online vs. offline).
14. Scope & Milestones — what's in the vertical slice vs. full release; biggest risk items first.

Writing conventions

• Player-facing language for mechanics ("the player can dodge-roll for 0.4s of i-frames"), not engineering language.
• Every section should answer "why" as much as "what" — tie back to pillars.
• Use tables for anything enumerable (enemy types, item tiers, currencies) rather than prose paragraphs.
• Flag open questions explicitly (**Open question:**) rather than silently picking an answer the user didn't ask for, when a decision has real design tradeoffs.