Get started

1Make the folder#

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

forest-spirit/
  manifest.json      what the game 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.9",
  "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.9, 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 files numbered 01 to 05 have fixed names. Two of these files, 03-content.md and 04-presentation.md, are optional and not used here. Acceptance tests are the checks that the finished game must pass. You write one in step 6. In the next steps you write the other four files.

2Say what the player feels#

01-overview.md starts with the fantasy block. The fantasy block says in a few lines who the player is in the game and how playing should feel. It comes directly after the title.

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. Punctuation is not checked. Then write a Feel: line with three to five entries that describe how the game feels. Each entry is one word or one short phrase, and commas separate the entries. Then write a NOT: line with what the game must not become. Everything you write after this should support 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.

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

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 the person who balances the build may pick any value between the lowest and the highest, including those two values. This needs no Delegated passage (see step 5). 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 is not defined anywhere. The Tuning chapter lists the full rule syntax and the reserved words. The authoring tool shows where each key is set while you write.

5Who decides#

Every rule is Fixed unless you say otherwise: the builder follows it exactly. To give a decision to the builder, write it in a Delegated blockquote, with its limits.

a Delegated passage in 02-mechanics.md

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

The builder chooses the animation and the sound. The landing must still be readable, and it must still not hide the next hazard. There is also Personalization: a question that the builder answers for each build. The Personalization questions chapter explains it.

6Write the tests that the game must pass#

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.

Tests are optional. Without them, a build can only be reported as not verified, never as passing.

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 thorn
```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.

The format requires at least one stage. Each stage says what to build. The chapters that describe the work, and a checkpoint, which says when the stage is done, are optional. Writing these as Scope:, Chapters: and Checkpoint: lines is a helpful habit. The validator checks none of this.

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 does not check them.

7Check it and send it to the builder#

The validator checks that the files, names and references agree with each other. The validator needs Node.js on your computer. npx is a command that comes with Node.js. It runs the validator, so you do not need to install anything else.

If the check runs automatically, for example in a continuous integration (CI) job, name the exact validator version: npx opengdd@0.9 validate <dir>. Later 0.x releases may change which checks run.

1. Open a terminal in the folder that contains your package folder and run npx opengdd validate forest-spirit.
2. Fix every error. Read each warning. A warning does not always need a change.
3. Send the whole folder to the builder as a zip file or a Git repository.
4. 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. The builder returns that evidence in one small file, the build record opengdd-build.json. The validator page says what the build record contains.

A run with no errors and no warnings shows this result line. A short safety scan section follows the line.

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

These five files are a complete design. When your game needs more, the Handbook has a short chapter for each optional part. Collections hold lists of content. Art direction describes the look. Runtime values are values that change during play. The Handbook lists all chapters. The OpenGDD specification has the exact rules.