.mtgr

Appearance

0014: Variations ​

Status: Accepted

Context ​

PGN supports variations (recursive annotation variations, RAVs): a parenthesised sequence of moves after a move, meaning "instead of that move, this could have happened". Coaches use them to show better lines. .mtgr allows what PGN allows (design principle 7).

In Magic, a variation can never be fully determined the way a chess variation can: it runs into hidden information (the opponent's hand, the next draw), randomness (shuffles, die rolls), and the opponent's unknown responses. Letting a user step through a "what if" legally needs a rules engine (for example Forge) to check each hypothetical action. That is a tool's job; the format only has to be able to hold the variation.

Decision ​

  1. The format supports variations. A variation is a bracketed block of events placed after an event, meaning "instead of that event, this could have happened". Variations may nest.
  2. Variations use the normal event grammar, including causes, choices, comments, and glyphs.
  3. Variations may contain unknowns. Hidden or unknown objects are written as in the main line (decision 0001). Objects that exist only in the variation get hypothetical instance IDs, scoped to that variation, that never collide with main-line IDs.
  4. Variations never change the game. Keyframes, stack snapshots, and every check apply only to the main line. Removing every variation leaves the same game.
  5. Parsers that do not support variations MAY skip each variation block whole. The grammar makes the block's extent unambiguous without understanding its contents.
  6. The format does not guarantee a variation is legal. Checking legality is the job of a rules engine or the tool that wrote the variation.

Exact syntax, including the bracket characters and how hypothetical IDs are written, is defined in the spec.

Rules basis ​

The Comprehensive Rules (effective 2026-09-25) do not cover file formats; 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 8.2.5: an RAV "is used to represent an alternative variation", is enclosed in parentheses, "may be legally played by first unplaying the move that appears immediately prior to the RAV", and, being recursive, "may be nested".

Alternatives rejected ​

  • Deferring variations until a tool produces them. Rejected: the spec should be able to represent annotated alternative lines from the start, as PGN does, so tools can be built against it.
  • Comments only ({should have held up Remand here}). Rejected as the only mechanism: a viewer cannot let a user step through a comment. Comments remain available alongside variations.
  • Requiring variations to be legal. Rejected: legality in Magic depends on hidden information and needs a rules engine; a file format cannot check it.

Consequences ​

  • The spec must define the variation block syntax, hypothetical ID scoping, and how skipping parsers find the end of a block.
  • Conformance fixtures need files with nested variations, and a check that removing them leaves the main line unchanged.