The handbook
Come here with a design question. Each short chapter shows what one part of OpenGDD gives you, where it lives, and how to use it. If you are new to the format, read the first group below in order, or follow the Get started guide. The specification has the exact rules.
A chapter marked Required describes something every package has. Optional chapters describe things you add when your game needs them. Chapters without a badge are guides.
Start and foundations
See a finished package, then the core ideas behind its prose, numbers and tests.
A complete example: Garden Snake
You already know Snake. Here is a complete OpenGDD package for it, in five small files. It is a different game from the platformer in Get started, chosen because you …
What a package contains
A package is one folder with the complete design of one game. You give that folder to the builder: the person, team or AI that turns your package into a game.
The player fantasy
Every game starts with what the player gets to be and feel. OpenGDD asks for that first, in a short fantasy block at the top of 01-overview.md. The block comes before …
Who decides
Every sentence in your design has an owner. OpenGDD calls this authority, and there are three levels:
Names and addresses
Write each number once, give it a name, and use the name everywhere else. A name like stamina.dash_cost is an identifier. The whole name with its dots is its address: …
Tuning
tuning.json holds the shared numbers of your game: costs, speeds, sizes, timings. The builder reads them from here, and your prose points at them by name. The file has …
Acceptance tests
An acceptance test turns one important promise of your design into a check the finished game must pass. The builder has to show that the check passes. The builder is the …
Content, links and time
Organise repeated content, connect records, name changing values, and say how time passes.
Collections
Games are full of lists: technologies, recipes, cards, levels. A collection keeps one kind of content in one folder, with one JSON file per item. The example is the …
Links
A link is a field that holds another record's id. It connects items in your collections, and validation reports a missing target where the link is defined. The examples …
Runtime values
Some rules need to name a value that changes during play: oxygen left, the current score, progress toward an objective. A runtime value gives that changing value one …
Modes and clocks
When real time meets a pause or a turn structure, clocks.json says which clocks run in which situation. A time mode is one situation, such as diving or reading the map. …
Seeds and repeatable randomness
A seed is a text value that makes random results repeatable. The same seed gives the same world, as long as the procedure that uses it is Fixed. A draw is one request …
Art direction and variation
Guide the look and feel of the game, and define the choices one build may make differently from another.
Art direction
Art direction says what the game must look and feel like, without saying how to make it. The builder keeps the craft, and you keep the intent. The builder is the person, …
Palette and colour promises
A palette keeps the colours that define a game's look in one named place. Prose points at the whole set or at one named colour, and never copies a hex value. The example …
Personalization questions
Personalization lets you ask the builder a question that each build answers for itself. The builder is the person, team or AI that turns your package into a game. An …
Reusable mechanics
Adopt a familiar game mechanic by answering its questions, with tests included.
Checking and handoff
Understand what validation proves, then give the package one last human read.
What validation proves
Three different checks happen between a design and a finished game. Each one proves something different, so a pass means something different each time.
Before you hand it over
The validator (the checking tool) checks what it can prove from the files. A last human read checks the part only a designer can see: whether the package says one clear …