0016: Event line syntax

Status: Accepted. Amends decisions 0007 (item 3), 0008 (item 1), and 0011 (item 8). Item 9 amended by decision 0019 (applies to hands only).

Context

Decisions 0001 to 0015 define what a game record contains but leave the exact syntax to the spec. Before writing the grammar, the overall shape of a body line was agreed using the prototype's Sowing Mycospawn turn as the test case.

The prototype lists every object up front in a Cards: table and writes events as free English (Sowing Mycospawn #2: hand -> stack, PlayerA: life 19, hand 2).

Decision

1. Every body line has one shape: elapsed time, indentation, a subject, a verb from a fixed list, the verb's arguments, an optional cause (by ...), then optional annotations (glyphs and a {comment}).
2. Verbs are lowercase words from a fixed list defined in the spec (for example cast, tap, add, pay, resolve, pass). Free English is not used.
3. Objects are introduced with a new line at the point they are first seen, not in an up-front table. This lets writers stream a game as it happens and introduces hidden objects at the moment they appear.
4. Events repeat an object's name next to its instance ID (#7 "Ugin's Labyrinth" tap) for objects that have names. The ID is authoritative. The name is there for human readers, and parsers MUST check it matches the object's current name.
5. Indentation shows structure: turns, then steps, then events. Stack snapshots and keyframe contents are nested under the line they belong to.
6. Mana is written exactly as produced and spent, one symbol per mana, never as generic numbers. For a canonical form the symbols are written in the order {W}{U}{B}{R}{G}{C} ({G}{C}{C}{C}{C}{C}).

Writing the grammar settled these further details:

7. Untracked library cards. A card in a library that cannot be told apart from the others there has no instance ID; the library records how many such cards it holds. A new line with in library takes one out and gives it an ID. This is what decision 0002 item 4 already implies for shuffled cards, applied to the whole starting library.
8. identify binds a name to a hidden object. It is the "reveal event" of decision 0001. It is not called reveal, because revealing is a CR action (701.20a) with its own reveal statement, while a name also becomes known when a card simply moves to a public zone.
9. Hidden objects are interchangeable. When a source cannot say which hidden card an event involves (which unknown card in the opponent's hand was played), the writer uses the lowest-numbered hidden object of that player in that zone, and parsers must not treat the choice as information.
10. Abilities are put on the stack by their new line (new ability ... in stack). A mana ability's new line is its activation, with no zone.
11. Every object leaves the stack with one explicit line: move stack -> ... for cards and copies of cards, cease for abilities, after a resolve, fizzle, or countered line.
12. Every step and main phase that occurs is written, even when nothing happens in it. Skipped steps are not written.
13. Priority and pass lines are required only while the stack is not empty (amends decision 0007 item 3, which required them always). With an empty stack they are optional, because sources do not report every empty-stack priority window and a writer must not invent them.
14. The pregame also starts with a keyframe (extends decision 0008 item 1), giving starting life totals and library sizes.
15. Annotation glyphs are written as NAGs ($1 to $6), not as suffixes (amends decision 0011 item 8). PGN allows suffixes only in import format and translates them to NAGs on export; .mtgr has only the export format (decision 0013).

Rules basis

Checked against the Comprehensive Rules effective 2026-09-25.

• 106.1b: "There are six types of mana: white, blue, black, red, green, and colorless."
• 107.4b: numerical symbols such as {1} "represent generic mana in costs. Generic mana in costs can be paid with any type of mana." Generic is a cost notation, not a type of mana, so spent mana cannot be written as {5} without losing its type.
• 107.4c: {C} represents "one colorless mana, and also … a cost that can be paid only with one colorless mana". Costs such as Sowing Mycospawn's kicker {1}{C} can only be checked if colorless mana is recorded as {C}.
• 401.3: "Any player may count the number of cards remaining in any player's library at any time." The library's size is always recorded, even when its cards are untracked.
• 701.24a: to shuffle a library is to "randomize the cards within it so that no player knows their order". After a shuffle no tracked card can be told apart, so every ID in that library ends.
• 400.2, 701.20a: a card's identity becomes known either by moving to a public zone or by being revealed, so identifying and revealing are different events.
• 602.2a, 603.3: an activated ability "is created on the stack", and a triggered ability is put on the stack "as an object that's not a card". The ability is created as it goes on the stack. 605.3b: a mana ability "doesn't go on the stack".
• 608.2n: an instant or sorcery "is put into its owner's graveyard", and an ability "is removed from the stack and ceases to exist". 608.3a: a permanent spell "enters the battlefield". The destination differs, so it is written.
• 500.1: "Each of these phases takes place every turn, even if nothing happens during the phase." 103.8a, 508.8: some steps are skipped. Writing every step that occurs makes the turn structure checkable.
• 405.5: the top object resolves only when all players pass in succession, so passes matter only while the stack is not empty.

PGN basis, checked against https://www.saremba.de/chessgml/standards/pgn/pgn-complete.htm:

• Section 8.2.3.8: "Import format PGN allows for the use of traditional suffix annotations", and "when exported, a move suffix annotation is translated into the corresponding Numeric Annotation Glyph".

Alternatives rejected

• An up-front card table (the prototype). Rejected: a writer must buffer the whole game before writing, and hidden objects revealed later would appear in the table before they were seen.
• IDs only, without names, in events. Rejected: unreadable in a text editor (#16 move library -> battlefield by #14), against design principle 1.
• Free English event text (the prototype). Rejected: a parser would have to guess, against design principle 1.
• Compressed mana ({5}{G}). Rejected: loses the type of mana spent; see rules basis.
• An instance ID for every card in every library from the start. Rejected: 120 or more new lines before the first draw, all for cards that are indistinguishable until they leave the library.
• Suffix glyphs (!, ?) on event lines. Rejected: PGN's export format does not use them, and ! and ? appear in card names.
• Priority and pass lines always required. Rejected: sources do not report every empty-stack priority window.

Consequences

• Names in events are redundant with new lines, so a mismatch is a validity error the spec must define.
• The spec must define the full verb list, indentation levels, and how new lines interact with hidden objects and reveals.