Log in
  Page  Discussion  View source  History

Object() functions (DotP 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.

Contents

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>

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>

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>

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.

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.

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.

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.

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>

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>

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>

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.

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>

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>

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 )

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>

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>

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>

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>

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>

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.

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.

GetAuxTargetCard

Syntax: ?

Effect: ?

Notes: I really have no clue about the use of this kind of target.

Example: No example given.

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>

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.

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.

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>

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>

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>

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>

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>

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>

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>

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>

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.)

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>

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()

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>

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>

GetNthAuxTargetCard

Syntax: ?

Effect: ?

Notes: I really have no clue about the use of this kind of target.

Example: No example given.

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>

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>

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)
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.

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...

Retrieved from "https://www.slightlymagic.net/mw/index.php?title=Object()_functions_(DotP_2012)&oldid=3123"