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 already know its rules and can watch where the format puts each one. To work from the real files, download Garden Snake as a zip or open the package page.

the whole package on disk

garden-snake/
  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

manifest.json, complete

{
  "opengdd": "0.8",
  "id": "garden-snake",
  "version": "1.0.0",
  "title": "Garden Snake",
  "designer": {
    "name": "OpenGDD Examples"
  },
  "target": {
    "platform": "web-2d",
    "genre": "arcade",
    "session_minutes": 5,
    "audience": "anyone; one player and one garden"
  }
}

The first thing in 01-overview.md is the fantasy block: what the player gets to be and feel, in a few lines. Everything else in the package serves it.

the fantasy block, opening 01-overview.md

You are a garden snake with an appetite bigger than the garden, growing longer with every fallen apple until there is no room left for you.
Feel: hungry, tidy, inevitable.
NOT: violent, rushed, cluttered.

The rules are prose. A number the build reads is never written into the rule. The rule names the number, and the number lives in tuning.json.

a rule, from 02-mechanics.md

Time advances in steps of `snake.tick_seconds`. Each tick, the
head moves one cell in the current direction, the body follows,
and the tail cell empties.

After every `snake.speedup_every_apples` apples eaten in the current
run, later ticks become `snake.speedup_step_seconds` shorter, down to
`snake.minimum_tick_seconds`.

tuning.json, complete

{
  "values": {
    "snake.tick_seconds": 0.4,
    "snake.speedup_every_apples": 5,
    "snake.speedup_step_seconds": 0.025,
    "snake.minimum_tick_seconds": 0.15,
    "garden.size": 13,
    "snake.start_length": 3
  },
  "ranges": {
    "snake.tick_seconds": [0.3, 0.8],
    "snake.speedup_every_apples": [2, 12],
    "snake.speedup_step_seconds": [0.01, 0.05],
    "snake.minimum_tick_seconds": [0.1, 0.2]
  }
}

ranges says how far each number may be moved, by you when balancing or by a personalization answer. garden.size has no range, so it stays as written.

An acceptance test is a check the finished game must pass. Garden Snake has four. The Acceptance tests chapter explains the block.

one of the four acceptance tests, from 05-build-plan.md

{
  "type": "scenario",
  "given": "a run in progress with the head one cell from the apple",
  "when": ["the head moves onto the apple", "play continues until the head moves into the wall", "a fresh run continues until the head moves into the snake's own body"],
  "then": ["eating grows the snake by one cell, scores one apple, and a new apple appears in an empty cell", "the wall ends its run on the spot", "the body ends its run on the spot", "each finished run reports its apple count"],
  "diagnostics": ["tick-log", "garden-before-after"]
}

What to notice:

You describe Snake the way you would describe it to a friend.
Change a number once in tuning.json and every rule that names it stays correct.
The tests say what a build must show, not how to program it.
The fantasy block sets the feeling. The overview leaves presentation choices to the builder and keeps the gameplay fixed.

This package validates with no errors and no warnings. Chapters marked Optional describe things you add only when your game needs them.