Most game design documents are written once, never read, and quietly abandoned by month three.
That is not a discipline failure — it is a format failure. A document that takes a week to write and
an hour to read will not survive contact with a project. This one is built to be read.
The template is free to download from our
design documents section, in two versions:
one for solo developers and small teams, one for teams of five or more where the document has to
carry information between people who are not in the same room.
Why most GDDs fail
Three reasons, in order of how often they occur.
They are written for an imaginary reader. A hundred-page document describing every
system in a game nobody has built yet is fiction. It cannot be verified, so it cannot be wrong, so it
stops being useful the moment reality disagrees with it.
They are never updated. The design changes in week two. The document does not. By
month two the team knows the document is stale, so nobody opens it, so it gets staler.
They describe features instead of decisions. “The player can double jump” is a
feature. “The player can double jump, because our levels are built around vertical exploration and
playtesters kept falling into pits they could see the way out of” is a decision. Only the second one
tells a future teammate whether they may change it.
What actually belongs in it
The one-page core
If you write nothing else, write this. One page, and it should be readable by someone who has
never heard of your project:
- The pitch — one sentence. Not a genre list; what the player does and why it is
interesting. - The loop — what the player does in the first thirty seconds, and why they do it
again. - The hook — the thing this game has that others do not. If you cannot name it, that
is a finding, not a gap in the document. - The scope line — how long the game is and how many levels, characters or hours.
Write it early so you can notice later when you have quietly tripled it. - What it is not — the most useful section, and the most often missing. “Not an
open world. Not multiplayer. No crafting.” This is what protects the project.
The systems section
One page per system, written only when you are about to build that system. Not before — anything
written earlier is guesswork that will need rewriting.
Each system page answers four questions: what the player does, what the game does back, what the
numbers are, and what happens when it goes wrong. Rough numbers beat no numbers. “Enemies have 100 HP,
the sword does 25” gives a teammate something to reason about; “enemies should feel challenging”
does not.
The decision log
The section that makes a document worth keeping. A dated list of design decisions and why they were
made. Three lines each.
2026-03-14 — Removed stamina from combat. Playtesters treated it as a
timer rather than a resource and it made every fight feel identical. Revisit if fights become too
button-mashy.
Six months later, someone will propose adding stamina back. This log is how you remember whether
that was already tried, and why it failed. No other document format captures this.
What to leave out
- Story detail before the mechanics are settled. Narrative written around systems
that later change is thrown away wholesale. - Level-by-level descriptions. Those belong in a level document, made when the
blockout exists. - Technical architecture. Separate document, different reader, different lifespan.
- Anything you copied from another GDD because it looked professional. A section
you did not need to write is a section nobody needs to read.
Keeping it alive
Two habits are enough. First, review the one-page core at the end of every milestone — it takes ten
minutes and it is where you notice the scope has drifted. Second, whenever a design argument is
settled, add three lines to the decision log while the reasoning is fresh. If you do only the second,
the document still earns its keep.
Format matters less than people think, as long as it is searchable and everyone can edit it. A
shared doc, a wiki page, a markdown file in the repo — all fine. A PDF is not, because nobody updates
a PDF.
For solo developers
You still need the one-page core and the decision log, for a reason that surprises people: your
future self is a different person. In four months you will not remember why you rejected the crafting
system, and you will spend a weekend re-deciding it. The log is a note to that person.
Skip the systems pages if you are holding the whole design in your head — write them only when a
system is complicated enough that you have caught yourself re-deriving it.
What each section looks like filled in
Templates are easier to understand filled in than described. These examples are deliberately
ordinary — a small 2D game, the kind most people reading this are actually making.
The pitch
A single-screen roguelike where you fight with a weapon you cannot choose. Every thirty
seconds the game swaps it for a random one, and the fun is in adapting rather than in mastering a
build.
One sentence for what happens, one for why it is interesting. If the second sentence is hard to
write, that is a finding about the design rather than about the document.
The loop
Enter a room → assess enemies and current weapon → fight → weapon swaps mid-fight →
clear the room → choose one of three upgrades → next room. Roughly 45 seconds per room, 12 rooms per
run.
Rough timings matter more than they look. “45 seconds per room, 12 rooms” tells you the run is about
nine minutes, which tells you what kind of session the game is for — and later, whether it is dragging.
What it is not
Not procedurally generated levels — rooms are hand-built. No meta-progression between
runs. No inventory. No story cutscenes. Single player only.
The section that protects the project. Every item is a feature someone will suggest in month three,
and this is where you already decided.
A systems page
Weapon swapping. Every 30 seconds the player’s weapon is replaced by a
random one from the unlocked pool. A 3-second warning appears at 27 seconds. The new weapon is chosen
without repeating the previous two. Player health, position and momentum are unaffected.
Numbers: pool of 12 weapons at launch. Damage range 8–25. Swap timer fixed at 30s;
tested 20s and 45s, both worse — 20s felt random, 45s felt like a normal roguelike.
Failure case: if the pool is somehow empty, keep the current weapon rather than
disarming the player.
Four things: what the player experiences, the numbers, what was already tried, and what happens
when it goes wrong. That last line is the one programmers thank you for.
Adapting it to your team size
| Team | What to keep | What to skip |
|---|---|---|
| Solo | One-page core, decision log | Systems pages, unless a system got complicated enough that you re-derive it each time |
| 2–4 | Core, decision log, systems pages for anything more than one person touches | Formal sign-off, version numbering |
| 5+ | All of it, plus who owns each system | Nothing — at this size the document is how information moves between people |
Reviewing it without it becoming a chore
Two review points are enough, and both are short.
At every milestone, re-read the one-page core. Ten minutes. You are looking for one
thing: has the scope line drifted? If the document says twelve rooms and you have built twenty, either
the document is wrong or the project is — and deciding which, deliberately, is the entire value of the
exercise.
Whenever a design argument is settled, add three lines to the decision log. While
the reasoning is fresh. This costs a minute and saves the weekend six months later where the same
argument is had again from scratch.
If you only ever do the second one, the document still earns its place.
When the document is wrong
Eventually the game and the document disagree. How you handle that moment determines whether the
document survives the project.
The instinct is to treat the document as the plan and the divergence as a failure of discipline.
That is backwards. The game is the truth; the document is a record of what you decided and why. When
they disagree, one of two things has happened:
The design changed for a good reason. Playtesting revealed something, or a system
turned out differently in practice. Update the document and add a line to the decision log explaining
what changed. This is the document working correctly.
The design drifted without anyone deciding. Features accumulated, scope crept, and
nobody noticed. This is the case the document exists to catch — and catching it is only possible
because you wrote the scope line down at the start.
The distinction matters because the responses are opposite. The first calls for updating the
document. The second calls for cutting back to it, or for consciously deciding that the new scope is
the real one and rewriting the core page to say so.
What you should not do is leave them disagreeing. A document that contradicts the game teaches the
team to ignore it, and from that point it is dead weight regardless of how good it was.
A five-minute milestone check
- Read the one-page core. Does it still describe the game you are building?
- Check the scope line against reality. More content than planned is not automatically wrong — but
it must be a decision, not an accident. - Look at “What it is not”. Has anything on that list quietly arrived anyway?
Three questions, once per milestone. That is the whole maintenance burden.
Related
The design documents section also has a
production tracker, a level design planner and an economy balance kit — the spreadsheets that sit
alongside a GDD rather than inside it. Design questions are welcome on the
Mechanics & Systems board, where posts with real
numbers get real answers.