Documentation guide
What Is a Game Design Document (GDD)?
A GDD organizes a game's vision, rules, and systems so the design can be communicated and reviewed. When that vision needs to become a concrete playable level, an LDD completes the documentation.
What a GDD is
A Game Design Document is the source of truth for a game's design. It organizes the core idea, intended experience, pillars, mechanics, systems, progression, narrative when relevant, and the decisions the team needs to understand before building the game.
What an LDD is
A Level Design Document brings that vision into a concrete playable space. It explains what a level or area must achieve, how it is navigated, which mechanics it teaches or combines, what pacing it creates, what risks it has, and how it connects to the broader GDD.
Difference between a GDD and an LDD
- The GDD defines the whole game: vision, rules, systems, loops, and global decisions.
- The LDD defines a specific playable part: level goal, layout, pacing, routes, challenges, and spatial validation.
- The GDD answers what game we are making and why it works.
- The LDD answers how that idea is experienced in a concrete level, area, puzzle, or sequence.
- A useful LDD always returns to the GDD to avoid attractive levels that are disconnected from the game.
Practical structure without overdocumenting
- 01
Define the foundation
High concept, main fantasy, target player, tone, genre, design pillars, and playable promise.
- 02
Organize the loop
What the player does, why they repeat it, how progression changes it, and what feedback they receive.
- 03
Turn ideas into rules
Each important mechanic needs actions, limits, costs, rewards, states, and feedback.
- 04
Connect systems
Progression, economy, combat, resources, abilities, inventory, or any system that affects another.
- 05
Document levels
Goal, intent, initial layout, routes, pacing, difficulty, rewards, risks, and relationship with the GDD.
- 06
Review open decisions
The document should also show doubts, risks, and parts that still need validation.
Copyable GDD and LDD template
Copy this foundation and replace each instruction in brackets. If a section does not apply yet, mark it as an open decision instead of inventing an answer.
Game summary
A clear description of the experience, player, main fantasy, and expected scope.
Design pillars
Criteria that help decide what enters, what gets cut, and how each feature is evaluated.
Mechanics and rules
Player actions, restrictions, feedback, states, rewards, and consequences.
Systems
Relationships across progression, economy, combat, resources, abilities, and dependencies.
Level Design Document
Level goal, intent, route, zones, blockout, pacing, puzzles, risks, and validation.
Tasks and team
Mature decisions, actionable work, owners, open risks, and next steps.
Template to copy
# GDD — [Game name]
## 1. Game summary
- High concept: [One sentence that explains the game]
- Genre and platform: [Genre] · [Platform]
- Target player: [Who it is for]
- Core fantasy: [What the player should feel or be able to do]
- Current scope: [Prototype, vertical slice, production]
## 2. Design pillars
1. [Pillar and concrete criterion]
2. [Pillar and concrete criterion]
3. [Pillar and concrete criterion]
## 3. Core loop
1. [Main action]
2. [Outcome or reward]
3. [Upgrade or progression decision]
4. [What drives repetition]
## 4. Mechanics and rules
### [Mechanic]
- Player action: [What they do]
- Rules and limits: [What they can and cannot do]
- Costs and rewards: [What they risk or gain]
- Feedback: [How they understand the result]
- Related systems: [What other parts it affects]
## 5. Systems
### [System]
- Goal: [Why it exists]
- Inputs and outputs: [Resources, states, results]
- Dependencies: [Which mechanics or systems it connects]
- Risks or questions: [What still needs validation]
## 6. LDD — [Level name]
- Level goal: [What the player must achieve]
- Intent: [What it teaches, combines, or tests]
- Start and end: [Entry and exit state]
- Route and zones: [Main route, alternatives, key points]
- Mechanics used: [List]
- Pacing and difficulty: [How they escalate]
- Rewards: [What the player gains]
- Design risks: [What must be tested]
## 7. Open decisions
- [Question] — Owner: [Name] — Next test: [Action]
## 8. Next tasks
- [Task] — Owner: [Name] — Status: [Pending/In progress/Done]Minimal filled example
# GDD — Salt Beacon
- High concept: Explore a flooded lighthouse and guide ships with limited light.
- Genre and platform: Exploration puzzle · PC
- Core fantasy: Feel like the keeper of a fragile, mysterious place.
## Pillars
1. Every light solves one problem and creates another.
2. The space tells the story without interrupting exploration.
3. Decisions must be readable before they punish the player.
## Core loop
Explore → recover energy → aim the beam → open a route → go deeper.
## Mechanic: aim the beacon
- Rule: the beam rotates across three sectors and spends one charge per turn.
- Feedback: lens color, sound, and the ship silhouette in the fog.
- Dependencies: energy, weather, and sea routes.
## LDD — Level 01: Broken Pier
- Goal: start the backup generator and guide the first ship.
- Intent: teach exploration, energy, and beam aiming separately.
- Risk to validate: players understand the cost of turning the light before the first failure.Documentation review checklist
- A new person can understand what game is being designed.
- Core mechanics have clear rules, limits, and feedback.
- Systems do not contradict the intended experience.
- Each level has playable intent, not just a map description.
- LDDs connect objectives, layout, pacing, and mechanics with the GDD.
- Doubts, risks, and next decisions are visible.
- The document can be updated without rewriting everything.
How Mainloop organizes it
Mainloop turns this structure into editable, connected modules: Essentials for the GDD base, Freeboard for open ideas, Loops for repeated play, Mechanics for rules, Systems for dependencies, Areas and Levels for spatial structure, Blockouts and Puzzles for readable play, and Tasks, Team, and Engines for moving decisions into development.
Frequently asked questions
What does a GDD include?
It includes game vision, pillars, core loop, mechanics, systems, levels, progression, narrative when it affects design, risks, and open decisions.
What does an LDD include?
It includes level goal, intent, layout or blockout, routes, pacing, mechanics used, challenges, rewards, risks, and relationship with the GDD.
Does an LDD replace a GDD?
No. The LDD complements the GDD. The GDD defines the full game and the LDD documents how that vision applies to concrete levels or spaces.
Do I need to document everything on day one?
No. Start with the decisions that clarify the design and expand documentation when a part of the game needs more precision.
The GDD stops being an isolated file
Mainloop connects mechanics, systems, levels, tasks, and decisions in one GDD. Each module can be worked on separately and viewed inside the complete system as the game changes.
See how Mainloop turns this guide into a design systemOpen Mainloop