Contributing

.mtgr is a specification. Changes are proposals about how Magic games are recorded, argued from real games and the Comprehensive Rules.

Design principles

Every part of the format follows these. A proposal that breaks one has to say why.

1. Human-readable, machine-unambiguous. A player should be able to read a file in a text editor. A parser must never have to guess: every line type has a grammar, and free-form English is not a substitute for a defined field.
2. Source-agnostic core. Nothing specific to MTGO, Arena, or any other client belongs in core definitions. Source-specific data (for example MTGO_Version, MTGO catalog IDs) goes in clearly identified source metadata, and the file must still be meaningful without it.
3. Grounded in the Comprehensive Rules. Zones, phases, steps, priority, the stack, triggered and activated abilities, costs, and so on use the terms from the Magic: The Gathering Comprehensive Rules (CR), published at https://magic.wizards.com/en/rules. Design decisions are justified by the rules that lead to them, not by how any one client behaves.
4. Record why, not just what. Every state change must be attributable to its cause. Record the choices made (kicker, modes, X, targets, colors), the costs paid (mana, life, sacrifices), and the identity of each ability (which ability of a card, not just "Triggered Ability from X"). The reference case is the Sowing Mycospawn sequence in examples/mycospawn-turn-5.md: in the prototype recorder's output, a reader could not connect the two cast triggers, the kicker, the fetched land, and the life changes.
5. Honest incompleteness. If a recorder does not know something, the file says so explicitly. A writer never infers or invents data to fill a gap. Incompleteness markers are defined, not ad hoc.
6. Explicit perspective. Every file is recorded from one player's seat and says which player that is. Every object has an instance ID, even when its identity is hidden from that player.
7. As close to PGN as realistically possible. PGN (the chess Portable Game Notation standard, https://www.saremba.de/chessgml/standards/pgn/pgn-complete.htm) is the model. Where PGN allows something, .mtgr allows it. Where PGN has a convention (tag pairs, comments, annotation glyphs, escape lines, import and export formats), .mtgr uses it unless Magic's rules make it impossible, and the decision record says why.

Two more rules apply to every change:

• No speculative features. Every addition traces back to a concrete game situation, ideally from a real recorded match.
• One obvious way. If something could be written two ways, pick one and record why in a decision record.

Before you start

Read the decision records in decisions/ for questions that are already settled. Settled questions can be reopened, but the proposal has to say what changed since the decision.

Proposing a change

Open an issue describing:

1. The situation. A concrete game situation the format cannot record, or records badly. Ideally an excerpt from a real recorded game.
2. The rules. The Comprehensive Rules that apply, with rule numbers and short quotes (see "Citing the rules" below).
3. The proposal. How the situation would be written, with an example.
4. PGN. If PGN has a convention for the same thing, how the proposal follows it, or why it cannot.

Making the change

A pull request that changes the format includes, in the same change:

• a decision record, decisions/NNNN-short-title.md, with Context, Decision, Rules basis, Alternatives rejected, and Consequences. The Rules basis lists the CR rules that led to the decision, each with its number and a short quote. If no rule applies (a pure format choice), it says so;
• the definition in spec/mtgr.md, including the grammar;
• at least one example showing it in a real situation, and updates to every affected example and walkthrough;
• updates to every affected conformance fixture;
• a CHANGELOG.md entry and a version bump.

Keep the spec, examples, and fixtures consistent with each other. When they disagree, the spec is authoritative and the others are bugs.

Write normative text with MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY (RFC 2119 and RFC 8174) only where a requirement is meant; use plain language elsewhere.

Player names are public and are recorded as they are, including in examples. Redaction is an application concern, not part of the format (see decisions/0001-point-of-view.md).

Citing the rules

• Never cite a rule number from memory. Look it up in the current CR text and quote it. Rule numbers and wording change between CR releases.
• The spec and each decision record state the CR version they were checked against, by effective date. The current baseline is the CR effective 2026-09-25, from the official plain-text file https://media.wizards.com/2026/downloads/MagicCompRules 20260925.txt, linked from https://magic.wizards.com/en/rules. Check citations against the official file, never a third-party copy.
• Do not commit the CR to this repository. It is Wizards of the Coast's document and changes with most set releases. Link to it and quote short excerpts.
• When a new CR is released, re-check the cited rules and update the citations or the baseline.
• Cite PGN by section number, checked against the standard text.

Open questions

Design questions that are known but not yet settled. Each needs a real recorded game and a decision record before it is settled.

• Effects that change the non-mana parts of a cost (adding life payments, sacrifices, or discards). Listed in spec section 15; decision 0031 covers only the mana component.

Versions

The format uses semantic versioning. Before 1.0, a breaking change bumps the minor version (0.3.0 to 0.4.0) and is marked as breaking in the changelog. Other changes bump the patch version.

Extension prefixes

Applications and sources can record their own data with a registered prefix (spec section 13). To register one, open a pull request adding it to the prefix registry with the owner's name.