OpenGDD

Version 0.8 · Working draft

OpenGDD

An open format for game design documents.

Written in prose for creative control. Blended with data for validation.

Start with the guide Read the specification

A standard for game designers and builders

OpenGDD gives designers and builders a shared format for game design. The designer records the game they intend in a package: one folder containing the complete design.

A complete package can be as small as 3 written chapters and 2 small data files in JSON, a text format for structured data. A text editor is enough to write one. OpenGDD's authoring tool helps keep the files connected and checks the package as the designer writes.

Creative vision and the craft to build it

The designer shapes the experience. The builder brings it to life. OpenGDD keeps creative control with the designer as the tools and methods used to build games evolve.

The designer

Shapes what the player gets to be and feel.

Defines the rules and numbers.

Sets the creative direction.

The builder

The person, team or AI that turns the package into a game.

Chooses the engine and writes the code.

Follows the design and resolves its open choices.

Different strengths, one game

Like a screenwriter and a director, designer and builder contribute different strengths. A designer can imagine a game without knowing how to build it. A builder brings skill, judgment and feel to making that vision playable. OpenGDD gives them a way to work together.

From a game rule to a checkable design

The designer writes the rules in ordinary sentences and refers to numbers by name. An acceptance test describes a result the finished game must demonstrate. This critical-hit rule shows how the words, numbers and test work together.

02-mechanics.md

A basic attack lands a critical hit with chance combat.crit_chance. A critical hit deals combat.crit_multiplier times normal damage.

tuning.json

combat.crit_chance 0.05 5% chance per hit
combat.crit_multiplier 2.0 × normal damage

05-build-plan.md · AT-1

Check the critical-hit chance over repeated attacks. Each critical hit must deal the declared multiple of normal damage.

Here, each attack has a 5% chance of dealing twice normal damage. The test describes the behavior to check in the game; the builder chooses how to implement it.

Creative control over game decisions

The designer can settle a decision, leave it to the builder within stated limits, or ask a question to be answered for each build. OpenGDD gives these choices three names.

Fixed

The builder follows the design as written. This is the default for every design statement.

Each attack has a 5% chance of a critical hit.

Delegated

The designer explicitly leaves a choice to the builder and describes the intent and limits.

Choose how a critical hit looks and sounds, within the game's art direction.

Personalization

The designer records a question in the package. The builder records an answer for each build and follows it.

Does a two-hit attack check for a critical hit once, or separately for each hit?

One design, different builds

Different builders can turn the same package into a game using different engines, code and working methods. Each follows the same design and makes the choices it leaves open. Personalization can give each build different answers and numbers.

One OpenGDD package

One build

Engine and code chosen by its builder.

Another build

Different building choices within the same design.

Same Fixed rules · choices within the design's limits

Checking the design and the finished game

Checking a package before building helps catch missing information and conflicting numbers early. OpenGDD's validator runs these checks inside the authoring tool, with no separate installation needed. Checking whether the finished game follows the design requires running it and examining the results.

  1. 1

    Design

    The designer writes the package and its acceptance tests.

  2. 2

    Validate

    The validator checks file structure, references and numeric rules. People review the written design.

  3. 3

    Build

    The builder follows the design and makes the choices the package leaves open.

  4. 4

    Test and record

    The builder tests the game and records the chosen numbers, test results and supporting evidence.

An audit examines whether that evidence supports the builder's claims. OpenGDD's audit process is experimental; there is no official build certification yet.

How the checks work

Version 0.8 is a working draft

The format is being tested against real games and clean-room builds. A clean-room build starts from the package alone, without access to an earlier implementation. Missing rules and unclear instructions found in these trials guide the next revision.

Follow the format's evolution Read the known limitations
Current version
0.8
Change policy
The format may change before version 1.0
Public materials
Specification, handbook, schemas, validator, changelog, and limitations

Licensing and publication

OpenGDD is published at opengdd.org. The core specification source is at github.com/opengdd/core-spec.

Specification proseCC-BY 4.0

Schemas and validator codeMIT

Explore the format

Follow the guide to make a first package, or look up a particular part of the format in the handbook.

Get started

Build a first package in 7 steps, following one small platformer design.

The handbook

Short explanations and examples for each part of a package.

Authoring tool

Write and check a package in the browser. Your files stay on your machine.

Validator

Find missing references, invalid data and broken numeric rules in a package.

The specification

The complete rules for the current working draft.

Standard resources

File definitions, checking requirements and how the standard develops.