.mtgr

Appearance

0011: Extensions and annotations ​

Status: Accepted. Item 1 amended by decision 0012 (tag names use PREFIX_Name). Item 8 amended by decision 0016 (glyphs are written as NAGs).

Context ​

The prototype has no extension rules. Source-specific tags (MtgoVersion, SdkVersion, FormatCode) sit alongside core tags with nothing to distinguish them, so a parser cannot tell an extension tag from a broken file or one from a newer version. The prototype also has no way to annotate a game, although annotation is one of PGN's main uses beyond recording: players and coaches comment on moves and mark them good or bad.

.mtgr aims to stay as close to PGN as realistically possible (see CONTRIBUTING.md, design principle 7). Where PGN allows something, .mtgr allows it.

Decision ​

Extensions ​

  1. Extension names are prefixed. Data outside the core spec uses a namespace prefix: a source prefix for source data (for example mtgo:) and a registered prefix for an application or tool (for example mymtgo:, mtgreplay:). Core names never have a prefix. The registry of prefixes lives in the spec.
  2. Parsers MUST ignore unknown extensions (tags, card table fields, event lines) and MUST reject unknown core names, which indicate a broken file or a newer version.
  3. Extensions MUST NOT change the meaning of core data. A file with all extension data removed is still valid and describes the same game.
  4. A % in the first column escapes the line, as in PGN: the rest of the line is private data that conforming parsers ignore.
  5. The version header governs compatibility. Before 1.0, any minor version may break compatibility. From 1.0, parsers accept files of the same major version.
  6. Extensions can be promoted to core through the process in CONTRIBUTING.md, with a decision record. Promoted names lose their prefix.

Annotations ​

  1. Comments work as in PGN: a brace comment {...} attached to an event, and a rest-of-line comment starting with ;. Brace comments do not nest.
  2. Annotation glyphs work as in PGN: the six traditional suffixes !, ?, !!, ??, !?, ?! on an event, and Numeric Annotation Glyphs $0 to $255. NAGs 1 to 9 have their PGN meanings for "the action just taken" (for example $1 good, $2 poor). Magic-specific meanings for other ranges are defined in the spec only when a real need arises.
  3. Annotations never change game data. Removing every comment and glyph leaves the same game.

Exact syntax, including where comments and glyphs may appear on a line, is defined in the spec.

Rules basis ​

The Comprehensive Rules (effective 2026-09-25) do not cover file formats or annotation; this decision is a format choice.

PGN basis, checked against "Standard: Portable Game Notation Specification and Implementation Guide" (Steven J. Edwards, 1994), https://www.saremba.de/chessgml/standards/pgn/pgn-complete.htm:

  • Section 5: two kinds of comment, rest-of-line starting with ; and brace comments {...}; brace comments do not nest.
  • Section 6: a % in the first column of a line escapes it, "intended for the private use of software developers and researchers to embed non-PGN commands and data in PGN streams".
  • Section 8.1.1: "the definition and use of additional tag names and semantics is permitted and encouraged when needed".
  • Section 8.2.3.8: "There are exactly six such annotations available: "!", "?", "!!", "!?", "?!", and "??"."
  • Sections 8.2.4 and 10: NAGs are $ followed by an integer from 0 to 255. NAGs 1 to 9 annotate the move just played, 10 to 135 the position, and 136 to 139 time pressure.

Alternatives rejected ​

  • Unprefixed extension tags, as PGN allows. Rejected as the only mechanism: PGN parsers can tolerate any unknown tag, but .mtgr also needs to reject unknown core names to catch broken or newer files. The prefix is the smallest change from PGN that makes that possible.
  • Annotations kept outside the file (for example only on mtgreplay.app). Rejected: annotated games are a core PGN use case, and annotations held by one site are not portable.
  • A Magic-specific NAG table defined up front. Rejected: no speculative features. Ranges get Magic meanings when real annotated games need them.

Consequences ​

  • The spec must define the prefix registry, comment and glyph syntax on event lines, and the % escape.
  • the prototype's MtgoVersion, SdkVersion, FormatCode, and MatchId become mtgo:-prefixed tags, or are moved to the recorder's own prefix.
  • PGN's recursive annotation variations (alternative lines) are covered by decision 0014.