OpenGDD

How the format evolves

OpenGDD is a working draft. Trials with game designs, tools and builds help identify missing rules and unclear instructions. A package may need edits to move to a newer version.

The changelog describes changes between versions. Older schema files, which define data-file structure, remain available at their versioned addresses.

Move a package to the released version

opengdd migrate rewrites a v0.6 or v0.7 package or build record into the v0.8 form. Use --dry-run to see the changes without writing them, or --json for a machine-readable report.

npx opengdd migrate <package-dir> [--dry-run] [--json]
npx opengdd migrate --build <opengdd-build.json> [--dry-run] [--json]

Exit code 0 means the migration is complete with no manual items. Exit code 1 means manual items remain. Exit code 2 means invalid arguments, unreadable input, or another migration error.

The 1.0 promise

Version 1.0 has no target date. It depends on five criteria:

  1. Stability. A package that meets version 1.0's requirements will keep meeting them in later 1.x releases. Breaking changes wait for version 2.0.
  2. Clear checking requirements. Automated checks give repeatable results. Requirements that need human review are listed separately. A reader can then tell a tool check apart from a full review. The reference validator is tested against repository fixtures; version 1.0 also requires a published suite that independent validators can run.
  3. An independent implementation. Someone outside the project has built a working tool from the written specification alone.
  4. Public review. A public review round has run, and every finding is resolved.
  5. Real games. The format is tested on real games and can describe their designs accurately. The known limitations page must be current.

Until these criteria are met, OpenGDD remains a 0.x working draft.

How proposals happen

The steward decides what enters the specification. Proposals and questions go through GitHub Discussions. Accepted changes appear in the changelog with the version they land in.

A useful proposal shows a real design problem. It explains how the current format handles it. It suggests a small change. Examples from unrelated games show whether the change would help many designers. Ideas can be tried in prototypes first. Evidence from those trials decides which changes enter the specification.

Proposals go to GitHub Discussions on the specification repository. Include a small example that other people can examine or reproduce. Security reports go to security@opengdd.org, never to public threads.

Areas for further work

Examples and feedback are welcome in these areas:

  • A designer shorthand for acceptance tests. A simpler writing form could let designers describe a check that a tool turns into the required test data.
  • Long design chapters. Authors need a way to split a large chapter into smaller files and keep its writing and data connected.
  • Maps and levels. The format can describe grids as layers of text. Overlapping terrain, objects and other features need more than that.
  • Puzzle-solving tools. A package can describe a puzzle and the requirement that it has a solution. Independent tools still need shared rules for receiving the puzzle and reporting a solution.
  • Checking 3D images. Game logic can be checked today. Rendered 3D images cannot. A shared method that works across different rendering systems is still missing.

The known limitations describe current boundaries. The OpenGDD specification gives the exact rules.