What a package contains

Required

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.

the five required files

my-dungeon-crawler/
  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

These five files can describe a complete game. Everything else is optional.

the same package with optional files

my-dungeon-crawler/
  manifest.json         what this is
  tuning.json           the numbers
  01-overview.md        the player fantasy and the pitch
  02-mechanics.md       the rules
  03-content.md         prose about the game's content
  04-presentation.md    art direction and presentation
  05-build-plan.md      build stages and acceptance tests
  06-traps.md           a chapter of your own
  personalization.json  questions the builder answers for one build
  direction.json        structured art direction
  clocks.json           for games that mix real time with turns or a pause

The Markdown files are chapters: the design in prose. The JSON files hold data a tool can check.

A chapter is a file at the top of the folder named NN-name.md. Chapters are read in filename order. Numbers 01 to 05 have fixed names: 01-overview.md, 02-mechanics.md, 03-content.md, 04-presentation.md and 05-build-plan.md. Any other name with one of those numbers fails validation (the check a tool runs on your package before a build). 03-content.md and 04-presentation.md are optional. Add your own chapters from 06 upward, with any name after the number. Keep notes that are not part of the design in files without a number, so tools and builders do not read them as chapters.

The builder reads manifest.json first, then the chapters in order.

manifest.json, complete

{
  "opengdd": "0.8",
  "id": "my-dungeon-crawler",
  "version": "0.1.0",
  "title": "My Dungeon Crawler",
  "designer": { "name": "You" },
  "target": { "platform": "web-2d", "genre": "dungeon crawler" }
}

opengdd is the format version. id, version, title and designer say which package this is. target needs platform and genre; session_minutes and audience are optional. genre is free text. The manifest carries the package's identity and target, plus optional commerce terms. It does not list the chapters, the optional files, or the collections. Their presence in the folder is the declaration.

These are plain Markdown and JSON files. They do not depend on any engine or build system. The authoring tool can create the folder and keep the names in it connected.

In later JSON examples, … means that unrelated fields were left out.

Full rules: OpenGDD specification, §1 and §3.