List of known triggers
Summary
Below is a list of known triggers that are used in the TRIGGERED_ABILITY tag in the individual card XML files.
There are many more triggers in the game, to see a basic list of them open up CONSTANTS.LUA and search for the word "TRIGGER".
ATTACKING
This ability triggers when a creature attacks. Example syntax:
<TRIGGER value="ATTACKING">
return SelfTriggered()
</TRIGGER>
To see a working example of this, check the card Flameblast Dragon.
ATTACKING_AND_ISNT_BLOCKED
This ability triggers when a creature attacks and isn't blocked. Example syntax:
<TRIGGER value="ATTACKING_AND_ISNT_BLOCKED">
return SelfTriggered()
</TRIGGER>
As far as I am aware, there is no working example of this, however it works much the same as the card Flameblast Dragon.
BECAME_TAPPED
This ability triggers when a permanent becomes tapped. Example syntax:
<TRIGGER value="BECAME_TAPPED">
return SelfTriggered()
</TRIGGER>
As far as I am aware, there is no working example of this, but the best way to learn is to have a play around and see what you can come up with.
BECAME_UNTAPPED
This ability triggers when a permanent becomes tapped. Example syntax:
<TRIGGER value="BECAME_UNTAPPED">
return SelfTriggered()
</TRIGGER>
As far as I am aware, there is no working example of this, but the best way to learn is to have a play around and see what you can come up with.
BEGINNING_OF_STEP
This ability triggers at the start of the specified step. It is used for cards that have abilities that occur at certain points, e.g. "every upkeep" or "during your upkeep". Example syntax:
<TRIGGER value="BEGINNING_OF_STEP">
return MyUpkeep()
</TRIGGER>
For ideas on alternatives to MyUpkeep, look in the EXTRACT_INFO.LUA file, you can see a list of other similar steps and how to make your own.
CARD_CONSIDERED_FOR_TARGETTING
This ability triggers if a card is being targeted by the internal system, not the player. It's mostly use when a card can't be targeted by spells and abilities and tells the computer not to let the player select it as a valid target. Example syntax:
<TRIGGER value="CARD_CONSIDERED_FOR_TARGETTING">
return SelfTriggered() and ( SecondaryObject():GetPlayer():GetTeam() ~= Object():GetPlayer():GetTeam() )
</TRIGGER>
What the second part of that return is doing is only including it if the targeting player is not (~=) on the same team as the player.
To see a working example of this, check the card Troll Ascetic.
COMES_INTO_PLAY
This is fairly self explanatory, it triggers when a permanent comes into play. Example syntax:
<TRIGGER value="COMES_INTO_PLAY">
return SelfTriggered()
</TRIGGER>
To see a working example of this, check the card Angel of Mercy.
CREATURE_DEALT_COMBAT_DAMAGE_TO_CREATURE
This triggers when a creature deals combat damage to another creature. Example syntax:
<TRIGGER value="CREATURE_DEALT_COMBAT_DAMAGE_TO_CREATURE">
return SelfTriggered()
</TRIGGER>
If you want it to trigger when your creature deals combat damage to another creature, the other creature can be targeted in the effect part of the rule by calling SecondaryObject().
To see a working example of this, check the card Phage the Untouchable.
CREATURE_DEALT_COMBAT_DAMAGE_TO_PLAYER
This triggers when a creature deals combat damage to a player. Example syntax:
<TRIGGER value="CREATURE_DEALT_COMBAT_DAMAGE_TO_PLAYER">
return SelfTriggered()
</TRIGGER>
To see a working example of this, check the card Abyssal Spector.
DISCARD
This triggers when a player discards a card. Example syntax:
<TRIGGER value="DISCARD">
return Object():GetPlayer():GetTeam() ~= TriggerObject():GetPlayer():GetTeam()
</TRIGGER>
The above example returns when the opponent of the triggering card discards a card.
To see a working example of this, check the card Megrim.
DREW_CARD
This triggers when a player draws a card. Example syntax:
<TRIGGER value="DREW_CARD">
return OpponentTriggered( TriggerPlayer() )
</TRIGGER>
The above example returns when the opponent of the triggering card draws a card.
To see a working example of this, check the card Underworld Dreams.
END_OF_STEP
This is the same as BEGINNING_OF_STEP, except it triggers at the end of that step instead. It is also used for cards that have abilities that occur at certain points, e.g. "every upkeep" or "during your upkeep". Example syntax:
<TRIGGER value="END_OF_STEP">
return MyUpkeep()
</TRIGGER>
For ideas on alternatives to MyUpkeep, look in the EXTRACT_INFO.LUA file, you can see a list of other similar steps and how to make your own.
LAND_PLAYED
This triggers when a player plays a land. Example syntax:
<TRIGGER value="LAND_PLAYED">
return YouDontControl()
</TRIGGER>
The above example returns when the opponent of the triggering card plays a land.
To see a working example of this, check the card Dirtcowl Wurm.
PLAYER_CONSIDERED_FOR_TARGETTING
This ability triggers if a player is being targeted by the internal system, not the player. It's mostly used when a player can't be targeted by spells and abilities and tells the computer not to let the other player select it as a valid target. Example syntax:
<TRIGGER value="PLAYER_CONSIDERED_FOR_TARGETTING">
return (TriggerPlayer() == Object():GetPlayer()) and (SecondaryObject():GetPlayer():GetTeam() ~= Object():GetPlayer():GetTeam())
</TRIGGER>
To see a working example of this, check the card Spirit of the Hearth.
PLAYER_TOOK_DAMAGE
This triggers when a player takes damage. Example syntax:
<TRIGGER value="PLAYER_TOOK_DAMAGE">
local damage = Damage():GetAmount()
if damage > 0 then
Object():Register_Set( 0 , damage )
return Damage():GetSource() == Object()
else
return false
end
</TRIGGER>
The above example is quite complicated compared to some others. What it is doing is retrieving the amount of damage the player has taken and recording it into a variable and then registering that variable. This is handy if the amount of damage is important as it can then be retrieved in the <EFFECT> section of the rule.
To see a working example of this, check the card Corrupt.
SPELL_BEING_COUNTERED
This triggers when a spell is being countered. Example syntax:
<TRIGGER value="SPELL_BEING_COUNTERED">
return TriggerObject():GetCardType():Test( CARD_TYPE_CREATURE ) ~= 0
</TRIGGER>
I'm not completely clear on how this one works, but the above line prevents creature spells from being countered.
To see a working example of this, check the card Gaeas Herald.
SPELL_PLAYED
This triggers when a spell is played. Example syntax:
<TRIGGER value="SPELL_PLAYED">
return WhiteSpell()
</TRIGGER>
The above example triggers whenever a white spell is cast.
To see a working example of this, check the card Angel's Feather.
ZONECHANGE
This triggers when a permanent moves from one zone to another. Example syntax:
<TRIGGER value="ZONECHANGE">
return ( SelfTriggered() and (Object():GetZone() == ZONE_GRAVEYARD) and (Object():GetErstwhileZone() == ZONE_IN_PLAY) )
</TRIGGER>
The above example triggers when the card moves from into the graveyard from play.
To see a working example of this, check the card Mudbutton Torchrunner.