Get started

OpenGDD is a way to describe a game clearly enough that someone else can build it. You write the rules and the intended experience in Markdown. The numbers go in a small JSON file. A tool then checks that everything fits together. This guide writes a first package in seven short steps. The example is a small forest-spirit platformer. You need a text editor. The last step uses the free Node.js runtime for the check.

1Make the folder#

A package is one folder. Five files make it complete.

forest-spirit/
  manifest.json      what this is
  tuning.json        the numbers
  01-overview.md     the player fantasy and the pitch
  02-mechanics.md    the rules
  05-build-plan.md   build stages and acceptance tests

Create the folder and start with the manifest. It says what the game is called, who designed it, and what kind of game to build.

manifest.json, complete

{
  "opengdd": "0.8",
  "id": "forest-spirit",
  "version": "0.1.0",
  "title": "Forest Spirit",
  "designer": { "name": "You" },
  "target": {
    "platform": "web-2d",
    "genre": "platformer"
  }
}

opengdd is the format version. Packages declare 0.8, the current version. version is the version of your design. platform is web-2d or web-3d. genre is free text. The folder name does not have to match id.

The numbered Markdown files are chapters. A tool reads them in filename order. The numbers 01 to 05 have fixed names. Two of them, 03-content.md and 04-presentation.md, are optional and not used here. Acceptance tests are the checks the finished game must pass. Step 6 writes one. The next steps fill the other four files.

2Say what the player feels#

01-overview.md opens with the fantasy block: what the player gets to be and feel, in a few lines. It comes right after the title, before anything else.

the opening of 01-overview.md

# Forest Spirit

```fantasy
You are a small forest spirit, a mote of light in a dying woodland.
You leap, cling, and glide through roots and ruins, rekindling what the decay took.
The forest grieves in silence, and answers every light you restore.
Feel: luminous, melancholy, hopeful.
NOT: grimdark, gory, hopeless.
```

Write one or more fantasy statements. Together they may use at most 280 characters. End each one with a full stop, exclamation mark or question mark. Then write a Feel: line with three to five adjectives. Then a NOT: line with what the game must not become. Everything you write after this should serve these lines. The rest of the overview is the pitch, in ordinary prose.

3Write the rules in plain language#

02-mechanics.md holds the rules. Write them in ordinary prose, the way you would explain the game to a colleague. State each rule once.

The spirit runs, leaps, and clings to walls. Touching a thorn costs a heart.

A rule can describe how something should feel and leave the implementation open.

At the top of a leap the spirit hangs for a moment before falling. The rise is quick and the fall is quicker.

That rule gives no exact numbers. It says what the player feels. The builder, the person, team or AI that turns your package into a game, decides how to make that happen. Leaving a detail open is your choice to make. When an exact value matters, the next step gives it a name.

4Name the numbers#

A number the game depends on gets a tuning key: a dotted name such as jump.height_tiles. Write the name in the rule, in backticks, and set the value once in tuning.json. Change it there and every rule that names it stays correct.

two rules in 02-mechanics.md

A full leap rises `jump.height_tiles` tiles. A thorn stands
`thorn.height_tiles` tiles tall, and a full leap must clear it.

tuning.json, complete

{
  "values": {
    "jump.height_tiles": 3.2,
    "thorn.height_tiles": 2,
    "player.hearts": 3
  },
  "ranges": {
    "jump.height_tiles": [2.5, 4]
  },
  "rules": {
    "leap-clears-the-thorn": "jump.height_tiles > thorn.height_tiles"
  }
}

values holds the numbers. A range is the lowest and highest value allowed. When balancing, you or whoever balances the build may pick any value between them, including the two ends. No delegation is needed for that. Here the leap may be tuned between 2.5 and 4 tiles. A number without a range stays as written.

A rule is a one-line check that must stay true. Here, a full leap clears the thorn. Raise the thorn to 4 tiles and the validator, the tool that checks a package, reports the rule as false. The level would be impossible. The validator also reports a name that points at nothing. The Tuning chapter lists the full rule syntax and the reserved words. The authoring tool shows where each key is set while you write.

The authoring tool showing a mechanics sentence citing jump.height_tiles, with a side panel classifying the key as a known value defined in tuning.json with value 3.2

5Who decides#

Every rule is Fixed unless you say otherwise: the builder follows it exactly. To hand a decision to the builder, tag the section Delegated and write the limits.

a Delegated section in 02-mechanics.md

> DELEGATED: landing-feedback
>
> Choose the landing animation and sound. A landing must remain readable
> without hiding the next hazard.

The builder chooses the animation and the sound. Readability and the clear view of the next hazard stay required. There is a third level, Personalization: a question each build answers for itself. The Personalization questions chapter explains it.

6Promise what the build must show#

05-build-plan.md splits the work into stages. It also holds the acceptance tests: checks the finished game must pass. A test gives a starting situation, what happens, and what must be true afterwards.

05-build-plan.md, complete small plan

# Build plan

## Phase 1: core-loop
Scope: Implement movement, leaping, thorns, and hearts.
Chapters: 02-mechanics.md.
Checkpoint: The spirit can cross one test room and take damage.

### AT-1: Jump over a spike
```test
{
  "type": "scenario",
  "given": "a grounded spirit at full hearts with one thorn ahead",
  "when": ["the spirit performs a full leap", "the spirit later touches the thorn"],
  "then": ["the leap apex reaches jump.height_tiles above its start", "the heart count is one below player.hearts after touching the thorn"],
  "diagnostics": ["player-position-timeline", "heart-count-before-after"]
}
```

## Phase 2: content and polish
Scope: Build one short level with readable visuals and sound, then apply the named values and rerun AT-1.
Chapters: 01-overview.md and 02-mechanics.md.
Checkpoint: The route is clear, and AT-1 passes.

Each stage says what to build and when it is done. A test is a heading that starts with AT- and a number. A JSON block marked test must follow that heading directly. diagnostics names the evidence to keep if the test fails. Names inside a test, such as jump.height_tiles, are for the person running it. The validator ignores them. The format requires the stages. The Scope, Chapters and Checkpoint lines are a helpful habit that the validator does not check.

7Check it and hand it over#

The validator checks that the files, names and references fit together. It needs Node.js on your computer. Nothing else to install. npx is a command that comes with Node.js. It runs the validator without a separate install.

In a CI job, pin the validator version: npx opengdd@0.8 validate <dir>. Later 0.x releases may change which checks run.

Open a terminal in the folder that contains your package folder and run npx opengdd validate forest-spirit.
Fix every error. Read each warning. Sometimes your design already answers it.
Send the whole folder to the builder as a zip or a Git repository.
Tell the builder to read manifest.json first, build the stages in 05-build-plan.md, and return the build with the test evidence the plan asks for. That evidence comes back as one small file, opengdd-build.json; the validator page says what it records.

A clean run ends with this line:

Result: PASS — 0 error(s), 0 warning(s)

These five files are a complete design. When your game needs more, the handbook has one short chapter per addition: lists of content in collections, the look in art direction, changing values in runtime values, and the rest. The specification has the exact rules.

Open the complete example Try the authoring tool