Keyword reference

Every keyword and symbol in .mtgr, grouped by where it appears, with an example. This page is a quick reference. The specification is authoritative, and the section numbers below point into it.

Symbols

Symbol	Meaning	Example	Spec
[Name "value"]	A tag.	[Perspective "PlayerA"]	4
M:SS	Time since the game started, at the start of every body line.	1:52	5.1
-	The time of a line inside a variation.	- (	12
#N	An instance ID.	#2	6.1
#hN	A hypothetical ID, inside a variation only.	#h1	12
"..."	A string: a name, a player, or text. \", \\, and \n are escapes.	"Ugin's Labyrinth"	2
{W} {U} {B} {R} {G} {C}	One mana of a type.	{G}{C}{C}	9.4
->	From one zone or value to another.	move hand -> exile, life 20 -> 19	7.1, 9.5
?	Unknown.	by ?	8
$N	A Numeric Annotation Glyph, 0 to 255. $1 good, $2 poor, $3 very good, $4 very poor, $5 speculative, $6 questionable.	$2	11
{...}	A comment, after the statement.	{should have held up mana}	11
;	A comment to the end of the line.	; misclick	11
%	In the first column: an escape line that parsers ignore.	%debug 1234	3
( )	A variation: an alternative to the line before it.	- (	12
1-0 0-1 1/2-1/2 *	The result line that ends each game.	1-0	3

Structure

Keyword	Meaning	Example	Spec
deck	The perspective player's decklist for this game.	deck "PlayerA" name "Mono Green"	10.5
main, side	A decklist entry in the main deck or sideboard.	main 4 "Ugin's Labyrinth"	10.5
unknown	The decklist is not known.	deck "PlayerA" unknown	10.5
pregame	Everything before turn 1: die rolls, opening hands, mulligans.	pregame	9.1
turn	A turn, with its active player.	turn 5 "PlayerA"	9.2
keyframe	The full game state at the start of the pregame or a turn.	keyframe	10
player	In a keyframe: a player's life, poison, library size, and clock.	player "PlayerA" life 20 poison 0 library 53	10.2
round-clock	In a keyframe: round time left.	round-clock 31:20	10.4
stack	Under a priority line: the whole stack, top first.	stack	9.9
incomplete	Events may be missing from here to the next keyframe. Turns after it may be missing.	incomplete "source disconnected"	9.8, 5.3
day, night	The game becomes day or night; in a keyframe, the game is day or night.	night by rule:day-night	9.10
game-draw	The game is a draw.	game-draw by rule:sba	9.7

Steps and phases

Written in this order, one line each when they occur (spec 9.2):

Keyword	Step or phase	CR
untap	untap step	502
upkeep	upkeep step	503
draw	draw step	504
precombat-main	precombat main phase	505
beginning-of-combat	beginning of combat step	507
declare-attackers	declare attackers step	508
declare-blockers	declare blockers step	509
combat-damage	combat damage step	510
end-of-combat	end of combat step	511
postcombat-main	postcombat main phase	505
end	end step	513
cleanup	cleanup step	514

Introducing objects

Keyword	Meaning	Example	Spec
new card	A card whose name is known.	new card #7 "Ugin's Labyrinth" owner "PlayerA" in library	6.5
new hidden	A card whose name is hidden from the perspective player.	new hidden #24 owner "PlayerB" in library	6.5
new token	A token, optionally tapped and attacking.	new token #62 "Angel" owner "PlayerA" in battlefield tapped attacking "PlayerB" by #61	6.5
new copy	A copy of a card or spell, or (with controller) of an ability. It has the original's choices.	new copy #102 of #98 controller "PlayerA" in stack by #101	6.5
new ability	An ability. With in stack, it is put on the stack; a mana ability has no zone. from #N names the effect a delayed trigger came from.	new ability #33 triggered of #2 "Sowing Mycospawn" "When you cast ..." controller "PlayerA" in stack	6.5
new effect	A lasting effect: a delayed trigger, or an effect lasting past this turn.	new effect #15 of #1 "Tamiyo, ..." "Until your next turn, ..." controller "PlayerA" by #14	9.10
new emblem	An emblem in the command zone.	new emblem #171 "You have no maximum hand size." owner "PlayerA" by #170	9.10
top N, bottom N	On new ... in library: which card it is.	new hidden #38 owner "PlayerB" in library top 1	6.5
activated triggered loyalty mana	The kind of ability.	new ability #29 mana of #7 ...	6.5
of	The source of an ability or the original of a copy.	of #7 "Ugin's Labyrinth"	6.5
owner	The object's owner.	owner "PlayerA"	6.5
controller	An ability's or stack entry's controller.	controller "PlayerB"	6.5, 9.9
in	The zone an object is introduced in.	in library	6.5
print	A printing: set code and collector number.	print "MH3" "233"	6.4
src	A source's own ID for the card.	src mtgo:126485	6.4
identify	Names a hidden object.	#16 identify "Island"	6.6

Zones

Keyword	Zone
library hand graveyard	A player's library, hand, or graveyard.
battlefield stack exile command ante	The shared zones.
outside "label"	Outside the game (not a zone), for example outside "sideboard".

Object events

All start with an object: #2 "Sowing Mycospawn" cast from hand.

Keyword	Meaning	Example	Spec
play from	Plays a land, with tapped if it enters tapped.	#1 "Watery Grave" play from hand tapped	7.1
cast from	Casts a spell: it moves to the stack. Caused by ID only when cast while that spell or ability resolves (cascade, suspend).	#54 "Living End" cast from exile by #51	7.1
face	Which face or half is cast, played, entering, or up.	#80 "Fire // Ice" cast from hand face "Ice"	7.1
fused	Both halves of a split card with fuse are cast.	#70 "Wear // Tear" cast from hand fused	7.1
move	Moves between zones.	#17 "Urza's Tower" move battlefield -> exile by #34	7.1
as	The keyword action behind a move: draw, discard, sacrifice, destroy, mill.	move library -> hand as draw by rule:draw	7.1
top, bottom	Position in a library.	move hand -> library bottom by rule:mulligan	7.1
tapped	Enters the battlefield tapped.	move library -> battlefield tapped by #33	7.1
pt	The power and toughness a creature enters with.	move stack -> battlefield pt 2/1 by rule:resolve	7.1
attacking	Enters the battlefield attacking (it never "attacked").	move hand -> battlefield tapped attacking "PlayerB" by #71	7.1
with	Exiled with an object, for linked abilities. The link ends when either object changes zone, except a permanent spell becoming a permanent (CR 607.2q).	move hand -> exile with #7 by #22	7.1
choose	A choice: see below.	#2 "Sowing Mycospawn" choose cost "kicker"	7.2
target	A target, with amount when divided.	#34 target #17 "Urza's Tower"	7.2
tap, untap	Taps or untaps.	#7 "Ugin's Labyrinth" tap by cost:#29	7.3
attach, unattach	Attaches to or unattaches from an object.	#3 "Utopia Sprawl" attach #36 "Stomping Ground" by rule:resolve	7.3
control	Changes controller.	#40 "Island" control "PlayerA" by #39	7.3
counters	Counters of a kind change.	#50 "Walking Ballista" counters "+1/+1" 0 -> 2 by #50	7.3
pt	Power and toughness change; none for a noncreature.	#10 "Ragavan, Nimble Pilferer" pt 2/1 -> 1/1 by #20	7.5
cost	An effect changes the mana cost of a spell or ability.	#2 "Thoughtseize" cost {1}{B} -> {2}{B} by #31	7.6
damage	Deals damage; prevented if it was completely prevented.	#1 "Talisman of Impulse" damage "PlayerA" 1 by #31	7.3
attack	Declared as an attacker. Followed by tap by rule:declare-attackers unless it has vigilance.	#2 "Sowing Mycospawn" attack "PlayerB"	7.3
block	Declared as a blocker.	#45 block #2 "Sowing Mycospawn"	7.3
reveal	Revealed (a game action).	#30 "Island" reveal by #29	7.3
look	A player looks at the card.	#87 "Consider" look "PlayerA" by #86	7.3
transform	A double-faced permanent turns over.	#66 "Delver of Secrets // Insectile Aberration" transform by #86	7.3
become-copy	Becomes a copy of another object, taking its name.	#90 "Phantasmal Image" become-copy #3 "Ragavan, Nimble Pilferer" by #90	7.3
special	A special action: companion, suspend, or plot.	#125 "Crashing Footfalls" special suspend	7.3
goad, end-goad	Becomes goaded; stops being goaded by a player.	#150 "Grizzly Bears" goad by #149	7.3
untracked	Can no longer be told apart; its ID ends.	#15 untracked	7.3
cease	Ceases to exist (abilities, tokens, copies, effects); its ID ends.	#34 cease by rule:resolve	7.3
resolve	Begins to resolve.	#34 resolve	7.4
fizzle	Does not resolve: every target is illegal, optionally with what made them illegal.	#2 "Thoughtseize" fizzle by #9	7.4
countered	Is countered.	#2 "Sowing Mycospawn" countered by #46	7.4

Choices

Keyword	The choice	Example
choose mode	A mode, as text.	choose mode "Return target nonland permanent to its owner's hand."
choose cost	An additional or alternative cost, by name, one line per payment. A free cast is "without paying its mana cost".	choose cost "kicker"
choose x	The value of X.	choose x 3
choose symbol	How a hybrid or Phyrexian symbol is paid: a symbol, or life.	choose symbol {B/P} life
choose color	white, blue, black, red, or green.	choose color red
choose option	A choice offered in words.	choose option "pay 2 life"
choose object	An object, without targeting.	choose object #5 "Emrakul, the Exigent Doom"
choose player	A player, without targeting.	choose player "PlayerB"
choose number	A number.	choose number 2
choose name	A card name.	choose name "Urza's Tower"
choose type	A card type or other characteristic.	choose type "Artifact"
choose hidden	A choice whose value is hidden.	choose hidden

A choice is made by the object's controller unless the line ends with by "Player": #51 choose option "do not discard" by "PlayerB". choose object is not targeting, so hexproof and ward don't apply to it; target is.

Player events

All start with a player: "PlayerA" pass.

Keyword	Meaning	Example	Spec
roll	Rolls a die, optionally with its size.	"PlayerA" roll d20 15	9.1
choose first	Chooses who takes the first turn.	"PlayerA" choose first "PlayerA"	9.1
choose	A choice belonging to no spell or ability, with a rule cause.	"PlayerA" choose object #3 "Ragavan, Nimble Pilferer" by rule:sba	7.2
mulligan	Declares a mulligan.	"PlayerB" mulligan	9.1
keep	Keeps their hand.	"PlayerA" keep	9.1
priority	Receives priority, optionally with both clocks.	"PlayerB" priority clock "PlayerA" 21:04 "PlayerB" 19:51	9.3
pass	Passes priority.	"PlayerB" pass	9.3
add	Mana is added to their pool, with any restriction.	"PlayerA" add {C}{C} by #29	9.4
pay	Spends mana from their pool.	"PlayerA" pay {G}{C}{C}{C}{C}{C} by cost:#2	9.4
lose-mana	Loses unspent mana as the pool empties.	"PlayerB" lose-mana {C} by rule:empty-pool	9.4
life	Life total changes.	"PlayerA" life 19 -> 17 by #36	9.5
poison	Poison counters change.	"PlayerB" poison 3 -> 5 by #41	9.5
counters	Other player counters change.	"PlayerA" counters "energy" 0 -> 2 by #12	9.5
search	Searches a zone, optionally another player's.	"PlayerA" search library "PlayerB" by #145	9.6
shuffle	Their library is shuffled.	"PlayerA" shuffle by #33	9.6
concede	Concedes.	"PlayerB" concede	9.7
lose, win	Loses or wins the game.	"PlayerB" lose by rule:sba	9.7

Keyframe entries

Keyword	Meaning	Example	Spec
tapped	The permanent is tapped.	#7 "Ugin's Labyrinth" battlefield "PlayerA" tapped	10.3
face	The face that is up.	#66 "Delver of Secrets // Insectile Aberration" battlefield "PlayerA" face "Insectile Aberration"	10.3
pt	A creature's current power and toughness.	#3 "Ragavan, Nimble Pilferer" battlefield "PlayerB" pt 2/1	10.3
adventure	The card is in exile on an adventure, and the player who may play it.	#82 "Bonecrusher Giant // Stomp" exile adventure "PlayerA"	10.3
companion	A revealed companion, still outside the game.	#1 "Lurrus of the Dream-Den" outside "sideboard" "PlayerA" companion	10.3
goaded	Goaded by that player.	#150 "Grizzly Bears" battlefield "PlayerB" goaded "PlayerA"	10.3
emblem	An emblem's text.	#171 command "PlayerA" emblem "You have no maximum hand size."	10.3
effect	A lasting effect still in force.	#15 effect of #1 "Tamiyo, ..." "..." controller "PlayerA"	10.3
attached	Attached to an object.	#3 "Utopia Sprawl" battlefield "PlayerA" attached #36	10.3
with	Exiled with an object.	#5 "Emrakul, the Exigent Doom" exile with #7	10.3
counters	Counters on the object.	counters "+1/+1" 2	10.3
top N, bottom N	Position in a library, 1 being the end card.	#15 library "PlayerB" bottom 1	10.3
clock	Time left on the player's clock.	player "PlayerA" life 17 poison 0 library 51 clock 21:04	10.2

Causes

Every cause starts with by (spec 8).

Cause	Meaning	Example
by #N	The effect of an object.	by #34
by cost:#N	Paying a cost of a spell or ability.	by cost:#2
by "Player"	The player's own action; on a choice line, who chose.	by "PlayerB"
by rule:opening-hand	Drawing the opening hand (CR 103.5).
by rule:mulligan	A mulligan (CR 103.5).
by rule:untap	The untap step (CR 502.3).
by rule:draw	The draw step's draw (CR 504.1).
by rule:combat-damage	Combat damage (CR 510.2).
by rule:cleanup	Cleanup step actions (CR 514.1, 514.2).
by rule:sba	A state-based action (CR 704.3).
by rule:empty-pool	The mana pool emptying (CR 106.4).
by rule:resolve	Leaving the stack after resolving, or an Aura attaching as it resolves (CR 608.2n, 608.3a, 608.3c).
by rule:fizzle	Leaving the stack with illegal targets (CR 608.2b).
by rule:no-choice	A trigger removed with no legal choice or no mode (CR 603.3d, 700.2b).
by rule:intervening-if	A trigger whose "if" is false as it resolves (CR 608.2a).
by rule:declare-attackers	Attackers becoming tapped (CR 508.1f).
by rule:lore	Saga lore counters (CR 703.4f).
by rule:replacement-order	Choosing which replacement effect applies (CR 616.1).
by rule:duration	An effect's duration ending (CR 611.2a).
by rule:delayed-trigger	A once-only delayed trigger having triggered (CR 603.7b).
by rule:day-night	Day or night changing in the untap step (CR 731.2).
by source:clock	A player's clock ran out.
by source:disconnect	A player disconnected.
by ?	Unknown.

After a cause, replacement #N names a replacement effect that changed the event: #10 "Ragavan, Nimble Pilferer" move hand -> exile as discard by #18 replacement #15 (Leyline of the Void exiles a discarded card instead of putting it into the graveyard).