The Handbook
Use the Handbook when you have a design question. Each short chapter explains one part of a package: what the part is for, where you write it, 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 OpenGDD 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 show the complete example, or explain checking and the handoff to a builder.
The basic parts
Read a finished package first. Then learn the main ideas in its prose, numbers and tests.
A complete example: Garden Snake
You already know Snake, so you can see where the format puts each rule. Here is a complete OpenGDD package for it, in five small files. It is a different game from the …
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. You can …
The player fantasy
Every game starts with an idea: who the player is in the game, and how playing should feel. OpenGDD asks for that first, in a short fantasy block at the top of …
Who decides
Every sentence in your design has a level of authority: it says who decides that part of the game. There are three levels:
Names and addresses
When your prose needs a number, write it 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 …
Tuning
tuning.json holds the shared numbers of your game: costs, speeds, sizes, timings. The builder, the person, team or AI that turns your package into a game, reads them …
Acceptance tests
An acceptance test turns one important promise of your design into a check the finished game must pass. The builder, the person, team or AI that turns your package into …
Content, links and time
Organize 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. If a link names a record that does not exist, validation reports it and names …
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 a game mixes real time with a pause or with turns, clocks.json says which clocks run in which situation. A time mode is one situation, such as diving or reading the …
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. You decide the intent, and the builder decides how to achieve it. The builder is …
Palette and color promises
A palette keeps the colors that define a game's look in one named place. Prose points at the whole set or at one named color, 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 …
Contracts: reusable mechanics
A contract is a list of questions about one familiar game mechanic. Answer the questions to define the mechanic. The tests of the contract come in a separate file, the verification pack.
Checking and handoff
Understand what validation proves, then read the package one last time yourself.
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 send it to the builder
The validator (the checking tool) checks what it can prove from the files. A final read by a person checks what only a designer can judge: whether the package describes …