Difference between revisions of "Object() functions (DotP 2012)"
Thefiremind (Talk | contribs) |
m |
||
(6 intermediate revisions by one user not shown) | |||
Line 1: | Line 1: | ||
Below is a list of functions that can be applied to Object(). | Below is a list of functions that can be applied to Object(). | ||
− | Note that I'll call "current object" the object that calls the function. Maybe "parent object" could have been more appropriate, but since the word "parent" is used for objects that got other objects attached, I opted for another word, in order to avoid confusion. | + | Note that I'll call "current object" the object that calls the function. Maybe "parent object" could have been more appropriate, but since the word "parent" is used for objects that got other objects attached, I opted for another word, in order to avoid confusion. Also remember that the codes for "lower than" and "greater than" are automatically converted by the Wiki in the examples: you'll have to write "& lt;" and "& gt;" (without spaces) as usual. |
== AddCounters == | == AddCounters == | ||
Line 645: | Line 645: | ||
'''Notes:''' | '''Notes:''' | ||
− | Just to be clear, think about a permanent: it's in hand, then you cast it, it goes to the stack, then it resolves and it comes into play. At this point, | + | Just to be clear, think about a permanent: it's in hand, then you cast it, it goes to the stack, then it resolves and it comes into play. At this point, its "ErstwhileErstwhileZone" would be the hand. |
'''Example:''' | '''Example:''' | ||
Line 665: | Line 665: | ||
'''Notes:''' | '''Notes:''' | ||
− | Just to be clear, think about a permanent: it's in hand, then you cast it, it goes to the stack, then it resolves and it comes into play. At this point, | + | Just to be clear, think about a permanent: it's in hand, then you cast it, it goes to the stack, then it resolves and it comes into play. At this point, its "ErstwhileZone" would be the stack. |
'''Example:''' | '''Example:''' | ||
Line 777: | Line 777: | ||
end | end | ||
</RESOLUTION_TIME_ACTION> | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == GetNumberOfChildren == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetNumberOfChildren( <assignment type> ) | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns the number of objects assigned to the current object that belong to the specified type. The possible types are: | ||
+ | ''PARENT_CHILD_ATTACHED'' (for Equipments)<br /> | ||
+ | ''PARENT_CHILD_FORTIFIED'' (for Fortifications)<br /> | ||
+ | ''PARENT_CHILD_ENCHANTED'' (for Auras)<br /> | ||
+ | ''PARENT_CHILD_OTHER'' (for something that doesn't belong to any category) | ||
+ | |||
+ | '''Notes:''' | ||
+ | Nothing to add. | ||
+ | |||
+ | '''Example:''' | ||
+ | Kor Duelist's static ability: | ||
+ | |||
+ | <CONTINUOUS_ACTION> | ||
+ | if Object():GetNumberOfChildren( PARENT_CHILD_ATTACHED ) > 0 then | ||
+ | local characteristics = Object():GetCurrentCharacteristics() | ||
+ | characteristics:Badge_Set( BADGE_DOUBLESTRIKE ) | ||
+ | characteristics:Bool_Set( CHARACTERISTIC_DOUBLE_STRIKE, 1 ) | ||
+ | end | ||
+ | </CONTINUOUS_ACTION> | ||
+ | |||
+ | == GetNumberOfTargets == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | ? | ||
+ | |||
+ | '''Effect:''' | ||
+ | ? | ||
+ | |||
+ | '''Notes:''' | ||
+ | There's no proof of the use of this function. It probably returns the number of targets that the current object has. | ||
+ | |||
+ | '''Example:''' | ||
+ | No example given. | ||
+ | |||
+ | == GetOwner == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetOwner() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns the owner of the current object. | ||
+ | |||
+ | '''Notes:''' | ||
+ | The owner is the player that has the object in his deck. The controller can change, the owner cannot. Note that the GetPlayer function probably calls GetOwner or GetController according to the object's zone, but when you need the owner of an object in play, you have to call GetOwner. | ||
+ | |||
+ | '''Example:''' | ||
+ | Any card that shuffles itself in its owner's library: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | Object():GetOwner():ShuffleLibrary() | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == GetParent == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetParent() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns the parent of the current object (in other words, the object to which the current object is assigned to). | ||
+ | |||
+ | '''Notes:''' | ||
+ | Nothing to add. | ||
+ | |||
+ | '''Example:''' | ||
+ | Arrest's static ability: | ||
+ | |||
+ | <CONTINUOUS_ACTION> | ||
+ | local parent = Object():GetParent() | ||
+ | if parent ~= nil then | ||
+ | parent:GetCurrentCharacteristics():Bool_Set( CHARACTERISTIC_CANT_ATTACK, 1 ) | ||
+ | parent:GetCurrentCharacteristics():Bool_Set( CHARACTERISTIC_CANT_BLOCK, 1 ) | ||
+ | parent:GetCurrentCharacteristics():Bool_Set( CHARACTERISTIC_CANT_USE_ABILITIES, 1 ) | ||
+ | end | ||
+ | </CONTINUOUS_ACTION> | ||
+ | |||
+ | == GetParentalNature == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetParentalNature() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns the type of assignment used to assign the current object to its parent. The possible types are: | ||
+ | ''PARENT_CHILD_NONE'' (probably if it's not assigned to anything)<br /> | ||
+ | ''PARENT_CHILD_ATTACHED'' (for Equipments)<br /> | ||
+ | ''PARENT_CHILD_FORTIFIED'' (for Fortifications)<br /> | ||
+ | ''PARENT_CHILD_ENCHANTED'' (for Auras)<br /> | ||
+ | ''PARENT_CHILD_OTHER'' (for something that doesn't belong to any category) | ||
+ | |||
+ | '''Notes:''' | ||
+ | This function has never been used in the core, but it seems quite intuitive in what it does. | ||
+ | |||
+ | '''Example:''' | ||
+ | No example given. | ||
+ | |||
+ | == GetPlaneswalkerAttacked == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | ? | ||
+ | |||
+ | '''Effect:''' | ||
+ | ? | ||
+ | |||
+ | '''Notes:''' | ||
+ | It's useless to struggle about this function: Planeswalkers are not currently supported by the game. | ||
+ | |||
+ | '''Example:''' | ||
+ | No example given. | ||
+ | |||
+ | == GetPlayer == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetPlayer() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns the controller of the current object if it's in a zone where it can have a controller, otherwise it returns the owner. | ||
+ | |||
+ | '''Notes:''' | ||
+ | The effect I wrote is just a speculation, but it seems right, since GetPlayer is widely used in the core. | ||
+ | |||
+ | '''Example:''' | ||
+ | The following statement returns the controller/owner of the current object according to the zone: | ||
+ | |||
+ | Object():GetPlayer() | ||
+ | |||
+ | == GetPlayerAttacked == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetPlayerAttacked() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns the defending player during the attack made by the current object. | ||
+ | |||
+ | '''Notes:''' | ||
+ | Needless to say, this has sense only for attacking creatures. | ||
+ | |||
+ | '''Example:''' | ||
+ | The following statement returns the defending player: | ||
+ | |||
+ | Object():GetPlayerAttacked() | ||
+ | |||
+ | == GetRef == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetRef() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns an identifier that has the same meaning as the name of the card, but it's not the name itself. | ||
+ | |||
+ | '''Notes:''' | ||
+ | I'm not really sure about what this function exactly returns, but in the old DotP this function was used in order to compare the names of 2 cards without explicitly refer to a name. Since in DotP 2012 the function GetCardName() returns the name and we can be sure about it, just use GetCardName() and you'll be fine. | ||
+ | |||
+ | '''Example:''' | ||
+ | The following statement returns (or should return?) true when Object() has the same name as FilteredCard(): | ||
+ | |||
+ | return Object():GetRef() == FilteredCard():GetRef() | ||
+ | |||
+ | == GetRevealFilter == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetRevealFilter() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Points to the filter used to reveal cards. | ||
+ | |||
+ | '''Notes:''' | ||
+ | No card in the core reveals other cards just to reveal them without doing anything more, so this function is never used. It would be interesting to learn how to use it. Anyway, see [[Filter() functions (DotP 2012)]] for the list of sub-functions you can use with it. | ||
+ | |||
+ | '''Example:''' | ||
+ | No example given. | ||
+ | |||
+ | == GetSpec == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetSpec() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns an identifier that defines how a copy of the current object should be. | ||
+ | |||
+ | '''Notes:''' | ||
+ | I know that the effect explanation is quite cryptic, but I really don't know which other words to use. This function is used in the core when a token needs to be created as a copy of something else. | ||
+ | |||
+ | '''Example:''' | ||
+ | Ignite the Cloneforge!'s resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | local targetCard = Object():GetTargetCard() | ||
+ | if targetCard ~= nil then | ||
+ | local token = MTG():ObtainTokenFromSpec( targetCard:GetSpec(), Object():GetPlayer() ) | ||
+ | if token ~= nil then | ||
+ | token:PutIntoPlay( Object():GetPlayer() ) | ||
+ | end | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == GetSubType == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetSubType():Test( <requested sub-type> ) | ||
+ | |||
+ | '''Effect:''' | ||
+ | Used with the sub-function Test, it returns 0 if the current object doesn't contain the specified card sub-type. | ||
+ | |||
+ | '''Notes:''' | ||
+ | It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail. | ||
+ | |||
+ | '''Example:''' | ||
+ | Blade of the Bloodchief's resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | local parent = Object():GetParent() | ||
+ | if parent ~= nil then | ||
+ | if parent:GetSubType():Test( CREATURE_TYPE_VAMPIRE ) ~= 0 then | ||
+ | parent:AddCounters( MTG():PlusOnePlusOneCounters(), 2 ) | ||
+ | else | ||
+ | parent:AddCounters( MTG():PlusOnePlusOneCounters(), 1 ) | ||
+ | end | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == GetSupertype == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetSupertype():Test( <requested supertype> ) | ||
+ | |||
+ | '''Effect:''' | ||
+ | Used with the sub-function Test, it returns 0 if the current object doesn't contain the specified card supertype. | ||
+ | |||
+ | '''Notes:''' | ||
+ | It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail. Note that this function doesn't have the capital "T" as GetCardType and GetSubType: make sure you write it correctly. | ||
+ | |||
+ | '''Example:''' | ||
+ | The following statement returns true if FilteredCard() is legendary: | ||
+ | |||
+ | return FilteredCard():GetSupertype():Test( SUPERTYPE_LEGENDARY ) ~= 0 | ||
+ | |||
+ | == GetTargetCard == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetTargetCard() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Points to the target of the current object. Returns ''nil'' if the current object has no targets, or the target is a player instead of a card. | ||
+ | |||
+ | '''Notes:''' | ||
+ | If the object has multiple targets, this function should point to the target card 0 in the data chest 0. | ||
+ | |||
+ | '''Example:''' | ||
+ | Aether Adept's triggered ability resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | if Object():GetTargetCard() ~= nil then | ||
+ | Object():GetTargetCard():ReturnToOwnersHand() | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == GetTargetPlayer == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetTargetPlayer() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Points to the target of the current object. Returns ''nil'' if the current object has no targets, or the target is a card instead of a player. | ||
+ | |||
+ | '''Notes:''' | ||
+ | If the object has multiple targets, this function should point to the target player 0 in the data chest 0. | ||
+ | |||
+ | '''Example:''' | ||
+ | Bloodgift Demon's triggered ability resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | if Object():GetTargetPlayer() ~= nil then | ||
+ | PlayerDrawCards( Object():GetTargetPlayer(), 1 ) | ||
+ | Object():GetTargetPlayer():LoseLife( 1 ) | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == GetZone == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GetZone() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns the current zone of the current object. | ||
+ | |||
+ | '''Notes:''' | ||
+ | Be careful when using GetZone() in a triggered ability with pre_trigger="1": if the ability triggers during a zone change, the pre-trigger will start when the zone change hasn't been made yet, and GetZone() will return the original zone. | ||
+ | |||
+ | '''Example:''' | ||
+ | Any ability that adds a +1/+1 counter to the current object: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | if Object():GetZone() == ZONE_IN_PLAY then | ||
+ | Object():AddCounters( MTG():PlusOnePlusOneCounters(), 1 ) | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == GiveRegeneration == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GiveRegeneration() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Grants a regeneration to the current object. | ||
+ | |||
+ | '''Notes:''' | ||
+ | Remember that regeneration is treated as a "one-shot" property: it doesn't need a continuous action to work. If you try to regenerate a permanent in a continuous action, you'll see its "regeneration layers" increment each time the state-based effects are checked, and that's not how regeneration works. | ||
+ | |||
+ | '''Example:''' | ||
+ | Cudgel Troll's regeneration code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | Object():GiveRegeneration() | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == GuidedReveal == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | GuidedReveal( <start zone>, <end zone> ) | ||
+ | |||
+ | '''Effect:''' | ||
+ | Shows to all players the current object moving from the specified start zone to the specified end zone. | ||
+ | |||
+ | '''Notes:''' | ||
+ | Remember that the card doesn't move, you just see it moving. The real movement needs to be coded separately. It doesn't work well when one of the zones is ZONE_REMOVED_FROM_GAME (probably because the removed zone doesn't have a specific location on the field), and it's not used at all if the end zone is ZONE_IN_PLAY, since the card is automatically revealed when it enters the battlefield. | ||
+ | |||
+ | '''Example:''' | ||
+ | Coiling Oracle's triggered ability resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | local card = Object():GetPlayer():Library_GetNth(0) | ||
+ | if card == nil then | ||
+ | return | ||
+ | end | ||
+ | if card:GetCardType():Test(CARD_TYPE_LAND) == 1 then | ||
+ | card:PutIntoPlay( Object():GetPlayer() ) | ||
+ | else | ||
+ | card:GuidedReveal( ZONE_LIBRARY, ZONE_HAND ) | ||
+ | card:PutInHand() | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == HasRegeneration == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | HasRegeneration() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns 0 if the current object has no regenerations granted. | ||
+ | |||
+ | '''Notes:''' | ||
+ | This function has never been used in the core, but it seems quite intuitive in what it does. | ||
+ | |||
+ | '''Example:''' | ||
+ | No example given. | ||
+ | |||
+ | == Hold == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | Hold() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Gives the current object the property that it "doesn't untap during its controller's next untap step". | ||
+ | |||
+ | '''Notes:''' | ||
+ | Nothing to add. | ||
+ | |||
+ | '''Example:''' | ||
+ | Wall of Frost's triggered ability resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | if SecondaryObject() ~= nil then | ||
+ | SecondaryObject():Hold() | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == IncreaseColouredCost == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | IncreaseColouredCost( <mana colour>, <increase amount> ) | ||
+ | |||
+ | '''Effect:''' | ||
+ | Increases the cost of the current object by the specified amount of mana of the specified colour. | ||
+ | |||
+ | '''Notes:''' | ||
+ | This function is not used in the core of the game, but we have working examples from the modders' community. | ||
+ | |||
+ | '''Example:''' | ||
+ | The following statement increases the red mana cost of the current object by 2: | ||
+ | |||
+ | Object():IncreaseColouredCost( COLOUR_RED, 2 ) | ||
+ | |||
+ | == IncreaseCost == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | IncreaseCost( <increase amount> ) | ||
+ | |||
+ | '''Effect:''' | ||
+ | Increases the cost of the current object by the specified amount of colourless mana. | ||
+ | |||
+ | '''Notes:''' | ||
+ | Nothing to add. | ||
+ | |||
+ | '''Example:''' | ||
+ | Lodestone Golem's static ability continous code: | ||
+ | |||
+ | <FILTER> | ||
+ | return (NonArtifacts() and NonLands() and InHand()) | ||
+ | </FILTER> | ||
+ | <CONTINUOUS_ACTION> | ||
+ | FilteredCard():IncreaseCost( 1 ) | ||
+ | </CONTINUOUS_ACTION> | ||
+ | |||
+ | == IsAttacking == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | IsAttacking() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns 0 if the current object is not attacking at the moment. | ||
+ | |||
+ | '''Notes:''' | ||
+ | It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail. | ||
+ | |||
+ | '''Example:''' | ||
+ | Annihilator mechanic's trigger definition: | ||
+ | |||
+ | <TRIGGER value="ATTACKERS_DECLARED"> | ||
+ | return TriggerPlayer() == Object():GetPlayer() | ||
+ | and ( Object():IsAttacking() ~= 0 ) | ||
+ | </TRIGGER> | ||
+ | |||
+ | == IsBlocked == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | IsBlocked() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns 0 if the current object is unblocked at the moment. | ||
+ | |||
+ | '''Notes:''' | ||
+ | It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail. | ||
+ | |||
+ | '''Example:''' | ||
+ | No example given. | ||
+ | |||
+ | == IsBlocking == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | IsBlocking() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns 0 if the current object is not blocking a creature at the moment. | ||
+ | |||
+ | '''Notes:''' | ||
+ | It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail. | ||
+ | |||
+ | '''Example:''' | ||
+ | No example given. | ||
+ | |||
+ | == IsToken == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | IsToken() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns 0 if the current object is not a token. | ||
+ | |||
+ | '''Notes:''' | ||
+ | It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail. | ||
+ | |||
+ | '''Example:''' | ||
+ | Mirrorworks' triggered ability trigger definition: | ||
+ | |||
+ | <TRIGGER value="COMES_INTO_PLAY"> | ||
+ | return (TriggerObject():GetCardType():Test( CARD_TYPE_ARTIFACT ) ~= 0 | ||
+ | and TriggerObject():IsToken() == 0 and TriggerObject() ~= Object() and TriggerObject():GetPlayer() == Object():GetPlayer()) | ||
+ | </TRIGGER> | ||
+ | |||
+ | == Kicked == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | Kicked() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns the number of times the current object was kicked when it was cast. | ||
+ | |||
+ | '''Notes:''' | ||
+ | Of course it works for the normal Kicker, too: it will just have 2 possible results (0 or 1). | ||
+ | |||
+ | '''Example:''' | ||
+ | Bloodhusk Ritualist's triggered ability resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | if (Object():GetTargetPlayer() ~= nil) and Object():Kicked() > 0 then | ||
+ | Object():GetTargetPlayer():DiscardNCards( Object():Kicked(), "CARD_QUERY_CHOOSE_CARD_TO_DISCARD" ) | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == NailOnto == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | NailOnto( <object to be attached to> ) | ||
+ | |||
+ | '''Effect:''' | ||
+ | Assigns the current object to the specified object in a non-specific way. | ||
+ | |||
+ | '''Notes:''' | ||
+ | Assigning basic lands to objects works really bad: basic lands can't stay outside their area on the battlefield, so the land will keep showing itself together with the other basic lands (and the assignment probably won't even be considered as valid). | ||
+ | |||
+ | '''Example:''' | ||
+ | Faceless Butcher's comes-into-play ability code (after target choosing): | ||
+ | |||
+ | <PLAY_TIME_ACTION> | ||
+ | local card = Object():GetTargetCard() | ||
+ | if card ~= nil then | ||
+ | card:RemoveFromGame() | ||
+ | if card:GetZone() == ZONE_REMOVED_FROM_GAME then | ||
+ | MTG():ObjectDataChest():Set_CardPtr( 1, card ) | ||
+ | Object():RetainDataChest() | ||
+ | card:NailOnto( Object() ) | ||
+ | end | ||
+ | end | ||
+ | </PLAY_TIME_ACTION> | ||
+ | |||
+ | == NumAttacksThisTurn == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | NumAttacksThisTurn() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns the number of attacks made by the current object this turn. | ||
+ | |||
+ | '''Notes:''' | ||
+ | Nothing to add. | ||
+ | |||
+ | '''Example:''' | ||
+ | Relentless Assault's untap code: | ||
+ | |||
+ | <FILTER> | ||
+ | return (FilteredCard() ~= nil and | ||
+ | FilteredCard():GetCardType():Test( CARD_TYPE_CREATURE ) ~= 0 and | ||
+ | FilteredCard():NumAttacksThisTurn() > 0) | ||
+ | </FILTER> | ||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | FilteredCard():Untap() | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == PlayFreeFromAnywhere == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | PlayFreeFromAnywhere( <casting player> ) | ||
+ | |||
+ | '''Effect:''' | ||
+ | Makes the specified player cast the current object as a spell, for free, in any zone it is. | ||
+ | |||
+ | '''Notes:''' | ||
+ | Apparently there's no difference between this function and "PlaySpellForFreeAtAnyTime", except for a switch between calling object and parameter. | ||
+ | |||
+ | '''Example:''' | ||
+ | Djinn of Wishes' activated ability resolution code (after target choosing): | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | local wishSpell = Object():GetTargetCard() | ||
+ | if (wishSpell ~= nil) then | ||
+ | wishSpell:PlayFreeFromAnywhere( Object():GetController() ) | ||
+ | else Object():GetController():Library_GetNth(0):RemoveFromGame() | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == PreventDamage == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | ? | ||
+ | |||
+ | '''Effect:''' | ||
+ | ? | ||
+ | |||
+ | '''Notes:''' | ||
+ | I'd really like to know how to use this function, but I don't. Everytime there's damage to prevent in the core cards, the damage is just lowered (or set to 0) in a triggered ability with pre_trigger="1". | ||
+ | |||
+ | '''Example:''' | ||
+ | No example given. | ||
+ | |||
+ | == PreventNextDamage == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | ? | ||
+ | |||
+ | '''Effect:''' | ||
+ | ? | ||
+ | |||
+ | '''Notes:''' | ||
+ | I'd really like to know how to use this function, but I don't. Everytime there's damage to prevent in the core cards, the damage is just lowered (or set to 0) in a triggered ability with pre_trigger="1". | ||
+ | |||
+ | '''Example:''' | ||
+ | No example given. | ||
+ | |||
+ | == Protection == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | Protection() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Gives protection from something to the current object. The kind of protection is decided by setting filter requirements before calling the function. | ||
+ | |||
+ | '''Notes:''' | ||
+ | This is one of the most clever functions, because it allows us to give protection from anything we can represent with a Filter() object. See [[Filter() functions (DotP 2012)]] for more details. | ||
+ | |||
+ | '''Example:''' | ||
+ | Akroma's protection from red and black: | ||
+ | |||
+ | <CONTINUOUS_ACTION> | ||
+ | local filter = Object():GetFilter() | ||
+ | filter:Clear() | ||
+ | filter:AddColour( COLOUR_RED ) | ||
+ | filter:AddColour( COLOUR_BLACK ) | ||
+ | Object():Protection() | ||
+ | </CONTINUOUS_ACTION> | ||
+ | |||
+ | == PutInGraveyard == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | PutInGraveyard() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Puts the current object in its owner's graveyard. | ||
+ | |||
+ | '''Notes:''' | ||
+ | It doesn't count as discard, sacrifice or destruction. Anyway it can be called no matter where the object is. | ||
+ | |||
+ | '''Example:''' | ||
+ | Beast Hunt spell resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | local count = 0 | ||
+ | for i=0, 2 do | ||
+ | local card = Object():GetController():Library_GetNth( 0 ) | ||
+ | if card == nil then | ||
+ | return | ||
+ | elseif card:GetCardType():Test( CARD_TYPE_CREATURE ) == 1 then | ||
+ | card:GuidedReveal( ZONE_LIBRARY, ZONE_HAND ) | ||
+ | card:PutInHand() | ||
+ | else | ||
+ | card:GuidedReveal( ZONE_LIBRARY, ZONE_GRAVEYARD ) | ||
+ | card:PutInGraveyard() | ||
+ | end | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == PutInHand == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | PutInHand() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Puts the current object in its owner's hand. | ||
+ | |||
+ | '''Notes:''' | ||
+ | There could be no difference between this function and ReturnToOwnersHand, but the name of the latter suggests to use it when the card must be returned from play to its owner's hand, while PutInHand should be used in any other case. | ||
+ | |||
+ | '''Example:''' | ||
+ | Angelic Destiny's return-to-hand resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | if Object():GetZone() == ZONE_GRAVEYARD then | ||
+ | Object():GuidedReveal( ZONE_GRAVEYARD, ZONE_HAND ) | ||
+ | Object():PutInHand() | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == PutInLibrary == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | PutInLibrary( <library position> ) | ||
+ | |||
+ | '''Effect:''' | ||
+ | Puts the current object in its owner's library at the specified position: -1 for bottom, 0 for top, any other number for a position after the top. | ||
+ | |||
+ | '''Notes:''' | ||
+ | When using a number higher than 0, it's best practice to check if there are enough cards in the library for that position to be possible, and if there aren't, use -1. | ||
+ | |||
+ | '''Example:''' | ||
+ | Darksteel Colossus' return-to-library resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | Object():GuidedReveal( Object():GetErstwhileZone(), ZONE_LIBRARY ) | ||
+ | Object():PutInLibrary( -1 ) | ||
+ | Object():GetOwner():ShuffleLibrary() | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == PutIntoPlay == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | PutIntoPlay( <controller> ) | ||
+ | |||
+ | '''Effect:''' | ||
+ | Puts the current object into play under the control of the specified player. | ||
+ | |||
+ | '''Notes:''' | ||
+ | It doesn't count as a played spell. | ||
+ | |||
+ | '''Example:''' | ||
+ | Elvish Piper's activated ability resolution code (after target choosing): | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | if Object():GetTargetCard() then | ||
+ | Object():GetTargetCard():PutIntoPlay( Object():GetController() ) | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == PutIntoPlayAttachedTo == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | ? | ||
+ | |||
+ | '''Effect:''' | ||
+ | ? | ||
+ | |||
+ | '''Notes:''' | ||
+ | There's no proof of it, but judging from the name, this function should put the current object into play attached to another object already in play. This behaviour is usually coded by putting the current object into play and then attaching it to something else, so it can be done even without knowing about this function. | ||
+ | |||
+ | '''Example:''' | ||
+ | No example given. | ||
+ | |||
+ | == PutIntoPlayTapped == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | PutIntoPlayTapped( <controller> ) | ||
+ | |||
+ | '''Effect:''' | ||
+ | Puts the current object into play under the control of the specified player, but tapped. | ||
+ | |||
+ | '''Notes:''' | ||
+ | It doesn't count as a played spell. | ||
+ | |||
+ | '''Example:''' | ||
+ | Reassembling Skeleton's activated ability resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | if Object():GetZone() == ZONE_GRAVEYARD then | ||
+ | Object():PutIntoPlayTapped( Object():GetOwner() ) | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == PutOnBottomOfLibrary == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | PutOnBottomOfLibrary() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Puts the current object on the bottom of its owner's library. | ||
+ | |||
+ | '''Notes:''' | ||
+ | It should give the same result as PutInLibrary(-1), but it's longer to write, so why using it? In fact, it has never been used in the core of the game. | ||
+ | |||
+ | '''Example:''' | ||
+ | No example given. | ||
+ | |||
+ | == PutOnTopOfLibrary == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | PutOnTopOfLibrary() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Puts the current object on the top of its owner's library. | ||
+ | |||
+ | '''Notes:''' | ||
+ | It should give the same result as PutInLibrary(0), but it's longer to write, so why using it? In fact, it has never been used in the core of the game. | ||
+ | |||
+ | '''Example:''' | ||
+ | No example given. | ||
+ | |||
+ | == ReleaseDataChest == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | ReleaseDataChest() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Deletes the current object's data chest. | ||
+ | |||
+ | '''Notes:''' | ||
+ | As far as I could understand, this function is automatically called everytime the current object changes zone, unless a RetainDataChest() function has been called before. | ||
+ | |||
+ | '''Example:''' | ||
+ | Zubera creatures' zone changing resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | if Object():GetDataChest() ~= nil then | ||
+ | Object():ReleaseDataChest() | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == RemoveCounters == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | RemoveCounters( <counter type identifier>, <number of counters> ) | ||
+ | |||
+ | '''Effect:''' | ||
+ | Removes the specified type of counters in the specified quantity from the current object. | ||
+ | |||
+ | '''Notes:''' | ||
+ | The identifiers for the counter types must be taken from MTG(). See [[MTG() functions (DotP 2012)]] for more information. | ||
+ | |||
+ | '''Example:''' | ||
+ | Fading mechanic upkeep resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | if Object():CountCounters(MTG():GetCountersType("Fade")) > 0 then | ||
+ | Object():RemoveCounters(MTG():GetCountersType("Fade"), 1) | ||
+ | else | ||
+ | Object():Sacrifice() | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == RemoveFromGame == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | RemoveFromGame() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Exiles the current object. | ||
+ | |||
+ | '''Notes:''' | ||
+ | Nothing to add. | ||
+ | |||
+ | '''Example:''' | ||
+ | Morningtide spell resolution code: | ||
+ | |||
+ | <FILTER> | ||
+ | return (FilteredCard() ~= nil and FilteredCard():GetZone() == ZONE_GRAVEYARD) | ||
+ | </FILTER> | ||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | FilteredCard():RemoveFromGame() | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == RemoveFromParent == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | RemoveFromParent() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Cancels the assignment of the current object to its parent. | ||
+ | |||
+ | '''Notes:''' | ||
+ | Nothing to add. | ||
+ | |||
+ | '''Example:''' | ||
+ | Oblivion Ring's leaving-play resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | if Object():GetDataChest() and MTG():ObjectDataChest():Get_CardPtr( 1 ) ~= nil then | ||
+ | MTG():ObjectDataChest():Get_CardPtr( 1 ):RemoveFromParent() | ||
+ | MTG():ObjectDataChest():Get_CardPtr( 1 ):PutIntoPlay( MTG():ObjectDataChest():Get_CardPtr( 1 ):GetOwner() ) | ||
+ | Object():ReleaseDataChest() | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == RetainDataChest == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | RetainDataChest() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Forces the current object's data chest to persist after zone changes. | ||
+ | |||
+ | '''Notes:''' | ||
+ | As far as I could understand, this function is needed everytime we want to preserve the data chest even after the current object changes zone. | ||
+ | |||
+ | '''Example:''' | ||
+ | Zubera creatures' zone changing pre-trigger resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | if Object():GetDataChest() ~= nil then | ||
+ | Object():RetainDataChest() | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == ReturnToOwnersHand == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | ReturnToOwnersHand() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Returns the current object to its owner's hand. | ||
+ | |||
+ | '''Notes:''' | ||
+ | There could be no difference between this function and PutInHand, but the name of this function suggests to use it when the card must be returned from play to its owner's hand, while PutInHand should be used in any other case. | ||
+ | |||
+ | '''Example:''' | ||
+ | Aether Adept's triggered ability resolution code (after target choosing): | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | if Object():GetTargetCard() ~= nil then | ||
+ | Object():GetTargetCard():ReturnToOwnersHand() | ||
+ | end | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == Reveal == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | ? | ||
+ | |||
+ | '''Effect:''' | ||
+ | ? | ||
+ | |||
+ | '''Notes:''' | ||
+ | No card in the core reveals other cards just to reveal them without doing anything more, so this function is never used. It would be interesting to learn how to use it. | ||
+ | |||
+ | '''Example:''' | ||
+ | No example given. | ||
+ | |||
+ | == Sacrifice == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | Sacrifice() | ||
+ | |||
+ | '''Effect:''' | ||
+ | Makes the current object's controller sacrifice it. | ||
+ | |||
+ | '''Notes:''' | ||
+ | Of course the object must be in play, otherwise it would have no sense. | ||
+ | |||
+ | '''Example:''' | ||
+ | Arc Runner's triggered ability resolution code: | ||
+ | |||
+ | <RESOLUTION_TIME_ACTION> | ||
+ | Object():Sacrifice() | ||
+ | </RESOLUTION_TIME_ACTION> | ||
+ | |||
+ | == SetController == | ||
+ | |||
+ | '''Syntax:''' | ||
+ | SetController( <new controller> ) | ||
+ | |||
+ | '''Effect:''' | ||
+ | Makes the specified player gain control of the current object. | ||
+ | |||
+ | '''Notes:''' | ||
+ | Of course the object must be in play, otherwise it would have no sense. | ||
+ | |||
+ | '''Example:''' | ||
+ | Act of Treason spell control-changing continuous code: | ||
+ | |||
+ | <CONTINUOUS_ACTION> | ||
+ | local target = Object():GetTargetCard() | ||
+ | if target ~= nil then | ||
+ | target:SetController( Object():GetPlayer() ) | ||
+ | end | ||
+ | </CONTINUOUS_ACTION> | ||
+ | |||
+ | == Tap == | ||
+ | == TapAndHold == | ||
+ | == Tapped == | ||
+ | == TurnIntoCopyOf == | ||
+ | == Untap == | ||
''work in progress...'' | ''work in progress...'' | ||
[[Category:DotP_Editing]] | [[Category:DotP_Editing]] |
Latest revision as of 03:50, 10 March 2012
Below is a list of functions that can be applied to Object(). Note that I'll call "current object" the object that calls the function. Maybe "parent object" could have been more appropriate, but since the word "parent" is used for objects that got other objects attached, I opted for another word, in order to avoid confusion. Also remember that the codes for "lower than" and "greater than" are automatically converted by the Wiki in the examples: you'll have to write "& lt;" and "& gt;" (without spaces) as usual.
[edit] AddCounters
Syntax: AddCounters( <counter type identifier>, <number of counters> )
Effect: Adds the specified type of counters in the specified quantity to the current object.
Notes: The identifiers for the counter types must be taken from MTG(). See MTG() functions (DotP 2012) for more information.
Example: Blood Tyrant's triggered ability resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetZone() == ZONE_IN_PLAY then Object():AddCounters( MTG():PlusOnePlusOneCounters(), 5 ) end </RESOLUTION_TIME_ACTION>
[edit] Attach
Syntax: Attach( <object to be attached to> )
Effect: Assigns the current object to the specified object as an Equipment.
Notes: There's a specific sequence of functions that make an equipment work, this alone isn't enough. See the example for more details.
Example: Any equipment assignment resolution code:
<RESOLUTION_TIME_ACTION> local target = Object():GetTargetCard() if target ~= nil then Object():AttachmentFilter_Get():Clear() Object():AttachmentFilter_Get():AddCardType( CARD_TYPE_CREATURE ) Object():Attach( target ) end </RESOLUTION_TIME_ACTION>
[edit] AttachmentFilter_Get
Syntax: AttachmentFilter_Get()
Effect: Returns a filter that specifies the kinds of objects that the current object can be assigned to.
Notes: Despite the name, it's used not only for Equipments, but also for Auras. See the example for more details, and see Filter() functions (DotP 2012) for the list of sub-functions you can use with it.
Example: Any aura assignment resolution code:
<RESOLUTION_TIME_ACTION> Object():AttachmentFilter_Get():Clear() Object():AttachmentFilter_Get():AddCardType( CARD_TYPE_CREATURE ) Object():Enchant( Object():GetTargetCard()) </RESOLUTION_TIME_ACTION>
[edit] CalcPotentialScore
Syntax: ?
Effect: ?
Notes: There's no proof of it, but judging from the name, this function should be used by the AI in order to calculate the score of cards. Not clear what it means for "potential".
Example: No example given.
[edit] CalcScore
Syntax: ?
Effect: ?
Notes: There's no proof of it, but judging from the name, this function should be used by the AI in order to calculate the score of cards.
Example: No example given.
[edit] ClearDamage
Syntax: ?
Effect: ?
Notes: There's no proof of it, but judging from the name, this function should clear all the damage on a creature, just as the regeneration does.
Example: No example given.
[edit] ClearTarget
Syntax: ?
Effect: ?
Notes: There's no proof of it, but judging from the name, this function should delete the target(s) chosen for the current object.
Example: No example given.
[edit] ComesIntoPlayTapped
Syntax: ComesIntoPlayTapped()
Effect: Forces the current object to come into play tapped.
Notes: The only official example (Loxodon Gatekeeper) uses this function in a COMES_INTO_PLAY triggered ability with pre_trigger="1". It could be the only working way of using it.
Example: Loxodon Gatekeeper's triggered ability resolution code:
<RESOLUTION_TIME_ACTION> if TriggerObject() ~= nil then TriggerObject():ComesIntoPlayTapped() end </RESOLUTION_TIME_ACTION>
[edit] CountCounters
Syntax: CountCounters( <counter type identifier> )
Effect: Counts the quantity of the specified type of counters on the current object.
Notes: The identifiers for the counter types must be taken from MTG(). See MTG() functions (DotP 2012) for more information.
Example: Blastoderm's fading ability resolution code:
<RESOLUTION_TIME_ACTION> if Object():CountCounters(MTG():GetCountersType("Fade")) > 0 then Object():RemoveCounters(MTG():GetCountersType("Fade"), 1) else Object():Sacrifice() end </RESOLUTION_TIME_ACTION>
[edit] CounterSpell
Syntax: CounterSpell()
Effect: Counters the current object.
Notes: The object that calls this function should be on the stack, otherwise it wouldn't be considered as a spell.
Example: Cancel spell resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetTargetCard() ~= nil then Object():GetTargetCard():CounterSpell() end </RESOLUTION_TIME_ACTION>
[edit] DealCDamage
Syntax: DealCDamage( <damage amount>, <damage source> )
Effect: Deals the specified amount of combat damage to the current object, considering the specified source as the damage source.
Notes: There's no proof of the use of this function, but it should almost surely work the same way as DealDamage, the only difference is that this function deals combat damage.
Example: No example given.
[edit] DealDamage
Syntax: DealDamage( <damage amount>, <damage source> )
Effect: Deals the specified amount of (non-combat) damage to the current object, considering the specified source as the damage source.
Notes: Nothing to add.
Example: Shock spell resolution code:
<RESOLUTION_TIME_ACTION> if ( Object():GetTargetCard() ~= nil ) then Object():GetTargetCard():DealDamage(2, Object()) elseif ( Object():GetTargetPlayer() ~= nil ) then Object():GetTargetPlayer():DealDamage(2, Object()) end </RESOLUTION_TIME_ACTION>
[edit] DealDamageFullParams
Syntax: DealDamage( <damage amount>, <damage source>, <?>, <unpreventable> )
Effect: Deals the specified amount of damage to the current object, considering the specified source as the damage source. The damage can be unpreventable by setting the last parameter to 1.
Notes: The third parameter is unknown. It could be a flag that specifies whether the damage is non-combat (0) or combat (1).
Example: Banefire spell resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetManaX() > 4 then if (Object():GetTargetCard() ~= nil) then Object():GetTargetCard():DealDamageFullParams( Object():GetManaX(), Object(), 0, 1 ) elseif (Object():GetTargetPlayer() ~= nil) then Object():GetTargetPlayer():DealDamageFullParams( Object():GetManaX(), Object(), 0, 1 ) end else if (Object():GetTargetCard() ~= nil) then Object():GetTargetCard():DealDamage(Object():GetManaX(), Object()) elseif (Object():GetTargetPlayer() ~= nil) then Object():GetTargetPlayer():DealDamage(Object():GetManaX(), Object()) end end </RESOLUTION_TIME_ACTION>
[edit] DecreaseColouredCost
Syntax: DecreaseColouredCost( <mana colour>, <decrease amount> )
Effect: Decreases the cost of the current object by the specified amount, influencing only the part of cost with the specified mana colour.
Notes: This function is not used in the core of the game, but we have working examples from the modders' community. A decrease bigger than the full coloured cost probably doesn't fall in a decrease of the colourless remaining cost, so this should be taken into account when coding dynamic cost reductions (such as Khalni Hydra).
Example: The following statement reduces the green mana cost of the current object by 2:
Object():DecreaseColouredCost( COLOUR_GREEN, 2 )
[edit] DecreaseCost
Syntax: DecreaseCost( <decrease amount> )
Effect: Decreases the cost of the current object by the specified amount, influencing only the colourless part of cost.
Notes: Nothing to add.
Example: Ruby Medallion's static ability continous code:
<FILTER> return (FilteredCard():GetColour():Test( COLOUR_RED ) ~= 0 and OwnedByYou() and InHand()) </FILTER> <CONTINUOUS_ACTION> FilteredCard():DecreaseCost( 1 ) </CONTINUOUS_ACTION>
[edit] Destroy
Syntax: Destroy()
Effect: Destroys the current object.
Notes: Nothing to add.
Example: Argentum Armor's triggered ability resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetTargetCard() ~= nil then Object():GetTargetCard():Destroy() end </RESOLUTION_TIME_ACTION>
[edit] DestroyWithoutRegenerate
Syntax: DestroyWithoutRegenerate()
Effect: Destroys the current object, without allowing regeneration.
Notes: Nothing to add.
Example: Avatar of Woe's activated ability resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetTargetCard() ~= nil then Object():GetTargetCard():DestroyWithoutRegenerate() end </RESOLUTION_TIME_ACTION>
[edit] Discard
Syntax: Discard()
Effect: Discards the current object.
Notes: It should work only for cards in hand, otherwise it would make no sense.
Example: Monomania spell resolution code (the discarding part):
<RESOLUTION_TIME_ACTION> if FilteredCard() ~= nil then FilteredCard():Discard() end </RESOLUTION_TIME_ACTION>
[edit] Enchant
Syntax: Enchant( <object to be attached to> )
Effect: Assigns the current object to the specified object as an Aura.
Notes: There's a specific sequence of functions that make an Aura work, this alone isn't enough. See the example for more details.
Example: Any aura assignment resolution code:
<RESOLUTION_TIME_ACTION> Object():AttachmentFilter_Get():Clear() Object():AttachmentFilter_Get():AddCardType( CARD_TYPE_CREATURE ) Object():Enchant( Object():GetTargetCard()) </RESOLUTION_TIME_ACTION>
[edit] Fortificate
Syntax: Fortificate( <object to be attached to> )
Effect: Assigns the current object to the specified object as a Fortification.
Notes: There's no proof of the use of this function, but it should almost surely work the same way as Attach and Enchant, the only difference is that this function assigns as a Fortification.
Example: No example given.
[edit] GetAuxFilter
Syntax: GetAuxFilter()
Effect: ?
Notes: There's no proof of the use of this function, but it should allow access to a filter that specifies the requirements for the AuxTarget (see the function below).
Example: No example given.
[edit] GetAuxTargetCard
Syntax: ?
Effect: ?
Notes: I really have no clue about the use of this kind of target.
Example: No example given.
[edit] GetBestOrWorstCounterType
Syntax: GetBestOrWorstCounterType( <best type flag> )
Effect: Points to the best (flag set to 1) or to the worst (flag set to 0) type of counter on the current object.
Notes: This function is only used by the Proliferate mechanic, in order to decide which type of counter to add (the good counters on good cards, and the bad counters on bad cards).
Example: Spread the Sickness spell's proliferate resolution code:
<RESOLUTION_TIME_ACTION> local suitable_counter_type = 0 if FilteredCard():GetPlayer():GetTeam() == Object():GetPlayer():GetTeam() then suitable_counter_type = FilteredCard():GetBestOrWorstCounterType(1) else suitable_counter_type = FilteredCard():GetBestOrWorstCounterType(0) end if suitable_counter_type ~= 0 then FilteredCard():AddCounters( suitable_counter_type, 1 ) end </RESOLUTION_TIME_ACTION>
[edit] GetBlockVictim
Syntax: ?
Effect: ?
Notes: There's no proof of it, but judging from the name, this function should point to the creature blocked by the current object. The fact that it says "victim" and not "victims" tells that there's no way in this game for a creature to block multiple creatures.
Example: No example given.
[edit] GetCardName
Syntax: GetCardName()
Effect: Returns the name of the current object.
Notes: There's no proof of the use of this function, but it should work as anybody can guess: the name returned should be the one specified in the CARDNAME tag of the object's XML file.
Example: No example given.
[edit] GetCardType
Syntax: GetCardType():Test( <requested card type> )
Effect: Used with the sub-function Test, it returns 0 if the current object doesn't contain the specified card type.
Notes: It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail.
Example: Any filter that selects the creatures controlled by the object's controller:
<FILTER> return (FilteredCard() ~= nil and FilteredCard():GetCardType():Test( CARD_TYPE_CREATURE ) ~= 0 and FilteredCard():GetZone() == ZONE_IN_PLAY and FilteredCard():GetPlayer() == Object():GetPlayer()) </FILTER>
[edit] GetColour
Syntax: GetColour():Test( <requested colour> )
Effect: Used with the sub-function Test, it returns 0 if the current object isn't of the specified color.
Notes: It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail.
Example: Brave the Elements spell filter:
<FILTER> return (FilteredCard() ~= nil and FilteredCard():GetCardType():Test( CARD_TYPE_CREATURE ) ~= 0 and FilteredCard():GetZone() == ZONE_IN_PLAY and FilteredCard():GetController() == Object():GetController() and FilteredCard():GetColour():Test( COLOUR_WHITE ) ~= 0) </FILTER>
[edit] GetController
Syntax: GetController()
Effect: Returns the controller of the current object.
Notes: This should have sense only for cards in play or on the stack. The difference between this and GetPlayer isn't totally clear. GetPlayer probably calls GetOwner or GetController according to the object's zone.
Example: Angel's Feather's triggered ability resolution code:
<RESOLUTION_TIME_ACTION> Object():GetController():GainLife(1) </RESOLUTION_TIME_ACTION>
[edit] GetConvertedManaCost
Syntax: GetConvertedManaCost()
Effect: Returns the converted mana cost of the current object.
Notes: As far as I know, there's no way to get the "non-converted" mana cost.
Example: Aether Mutation spell resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetTargetCard() ~= nil then local cmc = Object():GetTargetCard():GetConvertedManaCost() Object():GetTargetCard():ReturnToOwnersHand() if (cmc > 0) then PutTokensIntoPlay( "TOKEN_SAPROLING_1_1_247029", cmc ) end end </RESOLUTION_TIME_ACTION>
[edit] GetCurrentCharacteristics
Syntax: GetCurrentCharacteristics()
Effect: Points to the current characteristics of the current object.
Notes: See Characteristics() functions (DotP 2012) for the list of sub-functions you can use with it.
Example: Any continuous action that grants flying:
<CONTINUOUS_ACTION> local characteristics = Object():GetCurrentCharacteristics() characteristics:Badge_Set( BADGE_FLYING ) characteristics:FX_Set( SPECIAL_EFFECT_FLYING ) characteristics:CanOnlyBeBlockedBy_Set( EVASION_INDEX_FLYING ) characteristics:CanBlock_Set( EVASION_INDEX_FLYING ) </CONTINUOUS_ACTION>
[edit] GetCurrentPower
Syntax: GetCurrentPower()
Effect: Returns the current power of the current object.
Notes: Needless to say, it's made for creatures. It should be just a shortcut to get the power without using GetCurrentCharacteristics().
Example: Electropotence's triggered ability resolution code:
<RESOLUTION_TIME_ACTION conditional="if"> if ( Object():GetTargetCard() ~= nil ) then Object():GetTargetCard():DealDamage(TriggerObject():GetCurrentPower(), Object()) elseif ( Object():GetTargetPlayer() ~= nil ) then Object():GetTargetPlayer():DealDamage(TriggerObject():GetCurrentPower(), Object()) end </RESOLUTION_TIME_ACTION>
[edit] GetCurrentToughness
Syntax: GetCurrentToughness()
Effect: Returns the current toughness of the current object.
Notes: Needless to say, it's made for creatures. It should be just a shortcut to get the toughness without using GetCurrentCharacteristics().
Example: One of Engulfing Slagwurm's triggered abilities' resolution code:
<RESOLUTION_TIME_ACTION> if SecondaryObject() ~= nil then local last_known_toughness = SecondaryObject():GetCurrentToughness() SecondaryObject():Destroy() Object():GetController():GainLife(last_known_toughness) end </RESOLUTION_TIME_ACTION>
[edit] GetDataChest
Syntax: GetDataChest()
Effect: Returns nil if the current object has no data chest linked to it.
Notes: In the core of the game this function is used only to check if there's a data chest or not. The data chest itself is always accessed through MTG():ObjectDataChest(), so I guess it doesn't allow to access the data chest. Verify the inequality (~=) with nil for positive testing.
Example: Journey to Nowhere's leaving play ability resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetDataChest() and MTG():ObjectDataChest():Get_CardPtr( 1 ) ~= nil then MTG():ObjectDataChest():Get_CardPtr( 1 ):RemoveFromParent() MTG():ObjectDataChest():Get_CardPtr( 1 ):PutIntoPlay( MTG():ObjectDataChest():Get_CardPtr( 1 ):GetOwner() ) Object():ReleaseDataChest() end </RESOLUTION_TIME_ACTION>
[edit] GetErstwhileErstwhileZone
Syntax: GetErstwhileErstwhileZone()
Effect: Returns the zone where the current object was before its last 2 zone changes.
Notes: Just to be clear, think about a permanent: it's in hand, then you cast it, it goes to the stack, then it resolves and it comes into play. At this point, its "ErstwhileErstwhileZone" would be the hand.
Example: A possible condition for a trigger that starts if the object hasn't been cast from the hand:
<TRIGGER value="COMES_INTO_PLAY" simple_qualifier="self"> return (Object():GetErstwhileErstwhileZone() ~= ZONE_HAND or Object():GetErstwhileZone() ~= ZONE_STACK) </TRIGGER>
(It has been used for Phage the Untouchable in the Deck Pack 1.)
[edit] GetErstwhileZone
Syntax: GetErstwhileZone()
Effect: Returns the zone where the current object was before its last zone change.
Notes: Just to be clear, think about a permanent: it's in hand, then you cast it, it goes to the stack, then it resolves and it comes into play. At this point, its "ErstwhileZone" would be the stack.
Example: The classic condition for a trigger that starts when the object "dies":
<TRIGGER value="HIT_GRAVEYARD"> return (TriggerObject() == Object() and TriggerObject():GetErstwhileZone() == ZONE_IN_PLAY) </TRIGGER>
[edit] GetFilter
Syntax: GetFilter()
Effect: Points to the filter used by the current object.
Notes: See Filter() functions (DotP 2012) for the list of sub-functions you can use with it.
Example: The following statement stores the pointer to the object's filter in a local variable:
local filter = Object():GetFilter()
[edit] GetManaX
Syntax: GetManaX()
Effect: Returns the latest value given to an X cost requested by the current object.
Notes: Nothing to add.
Example: Blaze spell resolution code:
<RESOLUTION_TIME_ACTION> if ( Object():GetTargetCard() ~= nil ) then Object():GetTargetCard():DealDamage(Object():GetManaX(), Object()) elseif ( Object():GetTargetPlayer() ~= nil ) then Object():GetTargetPlayer():DealDamage(Object():GetManaX(), Object()) end </RESOLUTION_TIME_ACTION>
[edit] GetMultipleChoiceResult
Syntax: GetMultipleChoiceResult()
Effect: Returns the result of the latest multiple choice offered by the current object to a player: 0 for first option, 1 for second option.
Notes: The function probably returns 0 also when nothing has been asked before, so be careful about it.
Example: Bloodghast's landfall ability resolution code:
<RESOLUTION_TIME_ACTION> Object():GetPlayer():BeginNewMultipleChoice() Object():GetPlayer():AddMultipleChoiceAnswer( "CARD_QUERY_OPTION_YES" ) Object():GetPlayer():AddMultipleChoiceAnswer( "CARD_QUERY_OPTION_NO" ) Object():GetPlayer():AskMultipleChoiceQuestion( "CARD_QUERY_MC_RETURN_THIS_CARD_TO_PLAY" ) </RESOLUTION_TIME_ACTION> <RESOLUTION_TIME_ACTION> if Object():GetMultipleChoiceResult() == 0 then Object():PutIntoPlay( Object():GetOwner() ) end </RESOLUTION_TIME_ACTION>
[edit] GetNthAuxTargetCard
Syntax: ?
Effect: ?
Notes: I really have no clue about the use of this kind of target.
Example: No example given.
[edit] GetNthTargetCard
Syntax: GetNthTargetCard( <target index> )
Effect: Points to the current object's target indexed by the specified value (where 0 is the first).
Notes: Nothing to add.
Example: Default annihilator mechanic's sacrifice code:
<RESOLUTION_TIME_ACTION> local target_array = {} for i=0,8 do target_array[i] = Object():GetNthTargetCard(i) end for i=0,8 do if target_array[i] ~= nil then target_array[i]:Sacrifice() end end </RESOLUTION_TIME_ACTION>
[edit] GetNumberOfChildren
Syntax: GetNumberOfChildren( <assignment type> )
Effect:
Returns the number of objects assigned to the current object that belong to the specified type. The possible types are:
PARENT_CHILD_ATTACHED (for Equipments)
PARENT_CHILD_FORTIFIED (for Fortifications)
PARENT_CHILD_ENCHANTED (for Auras)
PARENT_CHILD_OTHER (for something that doesn't belong to any category)
Notes: Nothing to add.
Example: Kor Duelist's static ability:
<CONTINUOUS_ACTION> if Object():GetNumberOfChildren( PARENT_CHILD_ATTACHED ) > 0 then local characteristics = Object():GetCurrentCharacteristics() characteristics:Badge_Set( BADGE_DOUBLESTRIKE ) characteristics:Bool_Set( CHARACTERISTIC_DOUBLE_STRIKE, 1 ) end </CONTINUOUS_ACTION>
[edit] GetNumberOfTargets
Syntax: ?
Effect: ?
Notes: There's no proof of the use of this function. It probably returns the number of targets that the current object has.
Example: No example given.
[edit] GetOwner
Syntax: GetOwner()
Effect: Returns the owner of the current object.
Notes: The owner is the player that has the object in his deck. The controller can change, the owner cannot. Note that the GetPlayer function probably calls GetOwner or GetController according to the object's zone, but when you need the owner of an object in play, you have to call GetOwner.
Example: Any card that shuffles itself in its owner's library:
<RESOLUTION_TIME_ACTION> Object():GetOwner():ShuffleLibrary() </RESOLUTION_TIME_ACTION>
[edit] GetParent
Syntax: GetParent()
Effect: Returns the parent of the current object (in other words, the object to which the current object is assigned to).
Notes: Nothing to add.
Example: Arrest's static ability:
<CONTINUOUS_ACTION> local parent = Object():GetParent() if parent ~= nil then parent:GetCurrentCharacteristics():Bool_Set( CHARACTERISTIC_CANT_ATTACK, 1 ) parent:GetCurrentCharacteristics():Bool_Set( CHARACTERISTIC_CANT_BLOCK, 1 ) parent:GetCurrentCharacteristics():Bool_Set( CHARACTERISTIC_CANT_USE_ABILITIES, 1 ) end </CONTINUOUS_ACTION>
[edit] GetParentalNature
Syntax: GetParentalNature()
Effect:
Returns the type of assignment used to assign the current object to its parent. The possible types are:
PARENT_CHILD_NONE (probably if it's not assigned to anything)
PARENT_CHILD_ATTACHED (for Equipments)
PARENT_CHILD_FORTIFIED (for Fortifications)
PARENT_CHILD_ENCHANTED (for Auras)
PARENT_CHILD_OTHER (for something that doesn't belong to any category)
Notes: This function has never been used in the core, but it seems quite intuitive in what it does.
Example: No example given.
[edit] GetPlaneswalkerAttacked
Syntax: ?
Effect: ?
Notes: It's useless to struggle about this function: Planeswalkers are not currently supported by the game.
Example: No example given.
[edit] GetPlayer
Syntax: GetPlayer()
Effect: Returns the controller of the current object if it's in a zone where it can have a controller, otherwise it returns the owner.
Notes: The effect I wrote is just a speculation, but it seems right, since GetPlayer is widely used in the core.
Example: The following statement returns the controller/owner of the current object according to the zone:
Object():GetPlayer()
[edit] GetPlayerAttacked
Syntax: GetPlayerAttacked()
Effect: Returns the defending player during the attack made by the current object.
Notes: Needless to say, this has sense only for attacking creatures.
Example: The following statement returns the defending player:
Object():GetPlayerAttacked()
[edit] GetRef
Syntax: GetRef()
Effect: Returns an identifier that has the same meaning as the name of the card, but it's not the name itself.
Notes: I'm not really sure about what this function exactly returns, but in the old DotP this function was used in order to compare the names of 2 cards without explicitly refer to a name. Since in DotP 2012 the function GetCardName() returns the name and we can be sure about it, just use GetCardName() and you'll be fine.
Example: The following statement returns (or should return?) true when Object() has the same name as FilteredCard():
return Object():GetRef() == FilteredCard():GetRef()
[edit] GetRevealFilter
Syntax: GetRevealFilter()
Effect: Points to the filter used to reveal cards.
Notes: No card in the core reveals other cards just to reveal them without doing anything more, so this function is never used. It would be interesting to learn how to use it. Anyway, see Filter() functions (DotP 2012) for the list of sub-functions you can use with it.
Example: No example given.
[edit] GetSpec
Syntax: GetSpec()
Effect: Returns an identifier that defines how a copy of the current object should be.
Notes: I know that the effect explanation is quite cryptic, but I really don't know which other words to use. This function is used in the core when a token needs to be created as a copy of something else.
Example: Ignite the Cloneforge!'s resolution code:
<RESOLUTION_TIME_ACTION> local targetCard = Object():GetTargetCard() if targetCard ~= nil then local token = MTG():ObtainTokenFromSpec( targetCard:GetSpec(), Object():GetPlayer() ) if token ~= nil then token:PutIntoPlay( Object():GetPlayer() ) end end </RESOLUTION_TIME_ACTION>
[edit] GetSubType
Syntax: GetSubType():Test( <requested sub-type> )
Effect: Used with the sub-function Test, it returns 0 if the current object doesn't contain the specified card sub-type.
Notes: It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail.
Example: Blade of the Bloodchief's resolution code:
<RESOLUTION_TIME_ACTION> local parent = Object():GetParent() if parent ~= nil then if parent:GetSubType():Test( CREATURE_TYPE_VAMPIRE ) ~= 0 then parent:AddCounters( MTG():PlusOnePlusOneCounters(), 2 ) else parent:AddCounters( MTG():PlusOnePlusOneCounters(), 1 ) end end </RESOLUTION_TIME_ACTION>
[edit] GetSupertype
Syntax: GetSupertype():Test( <requested supertype> )
Effect: Used with the sub-function Test, it returns 0 if the current object doesn't contain the specified card supertype.
Notes: It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail. Note that this function doesn't have the capital "T" as GetCardType and GetSubType: make sure you write it correctly.
Example: The following statement returns true if FilteredCard() is legendary:
return FilteredCard():GetSupertype():Test( SUPERTYPE_LEGENDARY ) ~= 0
[edit] GetTargetCard
Syntax: GetTargetCard()
Effect: Points to the target of the current object. Returns nil if the current object has no targets, or the target is a player instead of a card.
Notes: If the object has multiple targets, this function should point to the target card 0 in the data chest 0.
Example: Aether Adept's triggered ability resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetTargetCard() ~= nil then Object():GetTargetCard():ReturnToOwnersHand() end </RESOLUTION_TIME_ACTION>
[edit] GetTargetPlayer
Syntax: GetTargetPlayer()
Effect: Points to the target of the current object. Returns nil if the current object has no targets, or the target is a card instead of a player.
Notes: If the object has multiple targets, this function should point to the target player 0 in the data chest 0.
Example: Bloodgift Demon's triggered ability resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetTargetPlayer() ~= nil then PlayerDrawCards( Object():GetTargetPlayer(), 1 ) Object():GetTargetPlayer():LoseLife( 1 ) end </RESOLUTION_TIME_ACTION>
[edit] GetZone
Syntax: GetZone()
Effect: Returns the current zone of the current object.
Notes: Be careful when using GetZone() in a triggered ability with pre_trigger="1": if the ability triggers during a zone change, the pre-trigger will start when the zone change hasn't been made yet, and GetZone() will return the original zone.
Example: Any ability that adds a +1/+1 counter to the current object:
<RESOLUTION_TIME_ACTION> if Object():GetZone() == ZONE_IN_PLAY then Object():AddCounters( MTG():PlusOnePlusOneCounters(), 1 ) end </RESOLUTION_TIME_ACTION>
[edit] GiveRegeneration
Syntax: GiveRegeneration()
Effect: Grants a regeneration to the current object.
Notes: Remember that regeneration is treated as a "one-shot" property: it doesn't need a continuous action to work. If you try to regenerate a permanent in a continuous action, you'll see its "regeneration layers" increment each time the state-based effects are checked, and that's not how regeneration works.
Example: Cudgel Troll's regeneration code:
<RESOLUTION_TIME_ACTION> Object():GiveRegeneration() </RESOLUTION_TIME_ACTION>
[edit] GuidedReveal
Syntax: GuidedReveal( <start zone>, <end zone> )
Effect: Shows to all players the current object moving from the specified start zone to the specified end zone.
Notes: Remember that the card doesn't move, you just see it moving. The real movement needs to be coded separately. It doesn't work well when one of the zones is ZONE_REMOVED_FROM_GAME (probably because the removed zone doesn't have a specific location on the field), and it's not used at all if the end zone is ZONE_IN_PLAY, since the card is automatically revealed when it enters the battlefield.
Example: Coiling Oracle's triggered ability resolution code:
<RESOLUTION_TIME_ACTION> local card = Object():GetPlayer():Library_GetNth(0) if card == nil then return end if card:GetCardType():Test(CARD_TYPE_LAND) == 1 then card:PutIntoPlay( Object():GetPlayer() ) else card:GuidedReveal( ZONE_LIBRARY, ZONE_HAND ) card:PutInHand() end </RESOLUTION_TIME_ACTION>
[edit] HasRegeneration
Syntax: HasRegeneration()
Effect: Returns 0 if the current object has no regenerations granted.
Notes: This function has never been used in the core, but it seems quite intuitive in what it does.
Example: No example given.
[edit] Hold
Syntax: Hold()
Effect: Gives the current object the property that it "doesn't untap during its controller's next untap step".
Notes: Nothing to add.
Example: Wall of Frost's triggered ability resolution code:
<RESOLUTION_TIME_ACTION> if SecondaryObject() ~= nil then SecondaryObject():Hold() end </RESOLUTION_TIME_ACTION>
[edit] IncreaseColouredCost
Syntax: IncreaseColouredCost( <mana colour>, <increase amount> )
Effect: Increases the cost of the current object by the specified amount of mana of the specified colour.
Notes: This function is not used in the core of the game, but we have working examples from the modders' community.
Example: The following statement increases the red mana cost of the current object by 2:
Object():IncreaseColouredCost( COLOUR_RED, 2 )
[edit] IncreaseCost
Syntax: IncreaseCost( <increase amount> )
Effect: Increases the cost of the current object by the specified amount of colourless mana.
Notes: Nothing to add.
Example: Lodestone Golem's static ability continous code:
<FILTER> return (NonArtifacts() and NonLands() and InHand()) </FILTER> <CONTINUOUS_ACTION> FilteredCard():IncreaseCost( 1 ) </CONTINUOUS_ACTION>
[edit] IsAttacking
Syntax: IsAttacking()
Effect: Returns 0 if the current object is not attacking at the moment.
Notes: It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail.
Example: Annihilator mechanic's trigger definition:
<TRIGGER value="ATTACKERS_DECLARED"> return TriggerPlayer() == Object():GetPlayer() and ( Object():IsAttacking() ~= 0 ) </TRIGGER>
[edit] IsBlocked
Syntax: IsBlocked()
Effect: Returns 0 if the current object is unblocked at the moment.
Notes: It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail.
Example: No example given.
[edit] IsBlocking
Syntax: IsBlocking()
Effect: Returns 0 if the current object is not blocking a creature at the moment.
Notes: It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail.
Example: No example given.
[edit] IsToken
Syntax: IsToken()
Effect: Returns 0 if the current object is not a token.
Notes: It should return 1 if the test is positive, but nobody said that. The cards usually verify the inequality (~=) with 0 when a positive test is required: do this and you won't fail.
Example: Mirrorworks' triggered ability trigger definition:
<TRIGGER value="COMES_INTO_PLAY"> return (TriggerObject():GetCardType():Test( CARD_TYPE_ARTIFACT ) ~= 0 and TriggerObject():IsToken() == 0 and TriggerObject() ~= Object() and TriggerObject():GetPlayer() == Object():GetPlayer()) </TRIGGER>
[edit] Kicked
Syntax: Kicked()
Effect: Returns the number of times the current object was kicked when it was cast.
Notes: Of course it works for the normal Kicker, too: it will just have 2 possible results (0 or 1).
Example: Bloodhusk Ritualist's triggered ability resolution code:
<RESOLUTION_TIME_ACTION> if (Object():GetTargetPlayer() ~= nil) and Object():Kicked() > 0 then Object():GetTargetPlayer():DiscardNCards( Object():Kicked(), "CARD_QUERY_CHOOSE_CARD_TO_DISCARD" ) end </RESOLUTION_TIME_ACTION>
[edit] NailOnto
Syntax: NailOnto( <object to be attached to> )
Effect: Assigns the current object to the specified object in a non-specific way.
Notes: Assigning basic lands to objects works really bad: basic lands can't stay outside their area on the battlefield, so the land will keep showing itself together with the other basic lands (and the assignment probably won't even be considered as valid).
Example: Faceless Butcher's comes-into-play ability code (after target choosing):
<PLAY_TIME_ACTION> local card = Object():GetTargetCard() if card ~= nil then card:RemoveFromGame() if card:GetZone() == ZONE_REMOVED_FROM_GAME then MTG():ObjectDataChest():Set_CardPtr( 1, card ) Object():RetainDataChest() card:NailOnto( Object() ) end end </PLAY_TIME_ACTION>
[edit] NumAttacksThisTurn
Syntax: NumAttacksThisTurn()
Effect: Returns the number of attacks made by the current object this turn.
Notes: Nothing to add.
Example: Relentless Assault's untap code:
<FILTER> return (FilteredCard() ~= nil and FilteredCard():GetCardType():Test( CARD_TYPE_CREATURE ) ~= 0 and FilteredCard():NumAttacksThisTurn() > 0) </FILTER> <RESOLUTION_TIME_ACTION> FilteredCard():Untap() </RESOLUTION_TIME_ACTION>
[edit] PlayFreeFromAnywhere
Syntax: PlayFreeFromAnywhere( <casting player> )
Effect: Makes the specified player cast the current object as a spell, for free, in any zone it is.
Notes: Apparently there's no difference between this function and "PlaySpellForFreeAtAnyTime", except for a switch between calling object and parameter.
Example: Djinn of Wishes' activated ability resolution code (after target choosing):
<RESOLUTION_TIME_ACTION> local wishSpell = Object():GetTargetCard() if (wishSpell ~= nil) then wishSpell:PlayFreeFromAnywhere( Object():GetController() ) else Object():GetController():Library_GetNth(0):RemoveFromGame() end </RESOLUTION_TIME_ACTION>
[edit] PreventDamage
Syntax: ?
Effect: ?
Notes: I'd really like to know how to use this function, but I don't. Everytime there's damage to prevent in the core cards, the damage is just lowered (or set to 0) in a triggered ability with pre_trigger="1".
Example: No example given.
[edit] PreventNextDamage
Syntax: ?
Effect: ?
Notes: I'd really like to know how to use this function, but I don't. Everytime there's damage to prevent in the core cards, the damage is just lowered (or set to 0) in a triggered ability with pre_trigger="1".
Example: No example given.
[edit] Protection
Syntax: Protection()
Effect: Gives protection from something to the current object. The kind of protection is decided by setting filter requirements before calling the function.
Notes: This is one of the most clever functions, because it allows us to give protection from anything we can represent with a Filter() object. See Filter() functions (DotP 2012) for more details.
Example: Akroma's protection from red and black:
<CONTINUOUS_ACTION> local filter = Object():GetFilter() filter:Clear() filter:AddColour( COLOUR_RED ) filter:AddColour( COLOUR_BLACK ) Object():Protection() </CONTINUOUS_ACTION>
[edit] PutInGraveyard
Syntax: PutInGraveyard()
Effect: Puts the current object in its owner's graveyard.
Notes: It doesn't count as discard, sacrifice or destruction. Anyway it can be called no matter where the object is.
Example: Beast Hunt spell resolution code:
<RESOLUTION_TIME_ACTION> local count = 0 for i=0, 2 do local card = Object():GetController():Library_GetNth( 0 ) if card == nil then return elseif card:GetCardType():Test( CARD_TYPE_CREATURE ) == 1 then card:GuidedReveal( ZONE_LIBRARY, ZONE_HAND ) card:PutInHand() else card:GuidedReveal( ZONE_LIBRARY, ZONE_GRAVEYARD ) card:PutInGraveyard() end end </RESOLUTION_TIME_ACTION>
[edit] PutInHand
Syntax: PutInHand()
Effect: Puts the current object in its owner's hand.
Notes: There could be no difference between this function and ReturnToOwnersHand, but the name of the latter suggests to use it when the card must be returned from play to its owner's hand, while PutInHand should be used in any other case.
Example: Angelic Destiny's return-to-hand resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetZone() == ZONE_GRAVEYARD then Object():GuidedReveal( ZONE_GRAVEYARD, ZONE_HAND ) Object():PutInHand() end </RESOLUTION_TIME_ACTION>
[edit] PutInLibrary
Syntax: PutInLibrary( <library position> )
Effect: Puts the current object in its owner's library at the specified position: -1 for bottom, 0 for top, any other number for a position after the top.
Notes: When using a number higher than 0, it's best practice to check if there are enough cards in the library for that position to be possible, and if there aren't, use -1.
Example: Darksteel Colossus' return-to-library resolution code:
<RESOLUTION_TIME_ACTION> Object():GuidedReveal( Object():GetErstwhileZone(), ZONE_LIBRARY ) Object():PutInLibrary( -1 ) Object():GetOwner():ShuffleLibrary() </RESOLUTION_TIME_ACTION>
[edit] PutIntoPlay
Syntax: PutIntoPlay( <controller> )
Effect: Puts the current object into play under the control of the specified player.
Notes: It doesn't count as a played spell.
Example: Elvish Piper's activated ability resolution code (after target choosing):
<RESOLUTION_TIME_ACTION> if Object():GetTargetCard() then Object():GetTargetCard():PutIntoPlay( Object():GetController() ) end </RESOLUTION_TIME_ACTION>
[edit] PutIntoPlayAttachedTo
Syntax: ?
Effect: ?
Notes: There's no proof of it, but judging from the name, this function should put the current object into play attached to another object already in play. This behaviour is usually coded by putting the current object into play and then attaching it to something else, so it can be done even without knowing about this function.
Example: No example given.
[edit] PutIntoPlayTapped
Syntax: PutIntoPlayTapped( <controller> )
Effect: Puts the current object into play under the control of the specified player, but tapped.
Notes: It doesn't count as a played spell.
Example: Reassembling Skeleton's activated ability resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetZone() == ZONE_GRAVEYARD then Object():PutIntoPlayTapped( Object():GetOwner() ) end </RESOLUTION_TIME_ACTION>
[edit] PutOnBottomOfLibrary
Syntax: PutOnBottomOfLibrary()
Effect: Puts the current object on the bottom of its owner's library.
Notes: It should give the same result as PutInLibrary(-1), but it's longer to write, so why using it? In fact, it has never been used in the core of the game.
Example: No example given.
[edit] PutOnTopOfLibrary
Syntax: PutOnTopOfLibrary()
Effect: Puts the current object on the top of its owner's library.
Notes: It should give the same result as PutInLibrary(0), but it's longer to write, so why using it? In fact, it has never been used in the core of the game.
Example: No example given.
[edit] ReleaseDataChest
Syntax: ReleaseDataChest()
Effect: Deletes the current object's data chest.
Notes: As far as I could understand, this function is automatically called everytime the current object changes zone, unless a RetainDataChest() function has been called before.
Example: Zubera creatures' zone changing resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetDataChest() ~= nil then Object():ReleaseDataChest() end </RESOLUTION_TIME_ACTION>
[edit] RemoveCounters
Syntax: RemoveCounters( <counter type identifier>, <number of counters> )
Effect: Removes the specified type of counters in the specified quantity from the current object.
Notes: The identifiers for the counter types must be taken from MTG(). See MTG() functions (DotP 2012) for more information.
Example: Fading mechanic upkeep resolution code:
<RESOLUTION_TIME_ACTION> if Object():CountCounters(MTG():GetCountersType("Fade")) > 0 then Object():RemoveCounters(MTG():GetCountersType("Fade"), 1) else Object():Sacrifice() end </RESOLUTION_TIME_ACTION>
[edit] RemoveFromGame
Syntax: RemoveFromGame()
Effect: Exiles the current object.
Notes: Nothing to add.
Example: Morningtide spell resolution code:
<FILTER> return (FilteredCard() ~= nil and FilteredCard():GetZone() == ZONE_GRAVEYARD) </FILTER> <RESOLUTION_TIME_ACTION> FilteredCard():RemoveFromGame() </RESOLUTION_TIME_ACTION>
[edit] RemoveFromParent
Syntax: RemoveFromParent()
Effect: Cancels the assignment of the current object to its parent.
Notes: Nothing to add.
Example: Oblivion Ring's leaving-play resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetDataChest() and MTG():ObjectDataChest():Get_CardPtr( 1 ) ~= nil then MTG():ObjectDataChest():Get_CardPtr( 1 ):RemoveFromParent() MTG():ObjectDataChest():Get_CardPtr( 1 ):PutIntoPlay( MTG():ObjectDataChest():Get_CardPtr( 1 ):GetOwner() ) Object():ReleaseDataChest() end </RESOLUTION_TIME_ACTION>
[edit] RetainDataChest
Syntax: RetainDataChest()
Effect: Forces the current object's data chest to persist after zone changes.
Notes: As far as I could understand, this function is needed everytime we want to preserve the data chest even after the current object changes zone.
Example: Zubera creatures' zone changing pre-trigger resolution code:
<RESOLUTION_TIME_ACTION> if Object():GetDataChest() ~= nil then Object():RetainDataChest() end </RESOLUTION_TIME_ACTION>
[edit] ReturnToOwnersHand
Syntax: ReturnToOwnersHand()
Effect: Returns the current object to its owner's hand.
Notes: There could be no difference between this function and PutInHand, but the name of this function suggests to use it when the card must be returned from play to its owner's hand, while PutInHand should be used in any other case.
Example: Aether Adept's triggered ability resolution code (after target choosing):
<RESOLUTION_TIME_ACTION> if Object():GetTargetCard() ~= nil then Object():GetTargetCard():ReturnToOwnersHand() end </RESOLUTION_TIME_ACTION>
[edit] Reveal
Syntax: ?
Effect: ?
Notes: No card in the core reveals other cards just to reveal them without doing anything more, so this function is never used. It would be interesting to learn how to use it.
Example: No example given.
[edit] Sacrifice
Syntax: Sacrifice()
Effect: Makes the current object's controller sacrifice it.
Notes: Of course the object must be in play, otherwise it would have no sense.
Example: Arc Runner's triggered ability resolution code:
<RESOLUTION_TIME_ACTION> Object():Sacrifice() </RESOLUTION_TIME_ACTION>
[edit] SetController
Syntax: SetController( <new controller> )
Effect: Makes the specified player gain control of the current object.
Notes: Of course the object must be in play, otherwise it would have no sense.
Example: Act of Treason spell control-changing continuous code:
<CONTINUOUS_ACTION> local target = Object():GetTargetCard() if target ~= nil then target:SetController( Object():GetPlayer() ) end </CONTINUOUS_ACTION>
[edit] Tap
[edit] TapAndHold
[edit] Tapped
[edit] TurnIntoCopyOf
[edit] Untap
work in progress...