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, v0.7, or v0.8 package or build record into the v0.9 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> [<package-dir>] [--dry-run] [--json]

For a build record, you may add its source package after the record path. The migrator changes a v0.8 record to v0.9 only when the recorded and source address lists are the same. Without the package, the record stays at v0.8 and the report asks for the source package. When an address changed, the record stays at v0.8 and the builder must issue a new record.

The meaning of tag scope changed in v0.9. The v0.8 to v0.9 version step keeps chapter text unchanged. It reports each passage that needs review. Quote the lines that should stay under the tag, or leave them unquoted as Fixed text or text that applies in every ruleset. Equal address lists do not prove unchanged chapter meaning. Build-record migration still requires tag-scope review.

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.

Criteria for version 1.0

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. A change that makes such a package fail is made only in version 2.0.
  2. Clear checking requirements. Automated checks give repeatable results. Requirements that need human review are listed separately. A reader can then see which checks a tool made and which checks a person made. The reference validator is tested with example packages in the repository. Version 1.0 also requires a published set of tests that other 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 to propose a change

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

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.

Include with your proposal 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. Designers 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 page describes what the format does not cover yet. The OpenGDD specification gives the exact rules.