Object() functions (DotP 2012)
Summary
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.
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 DotP 2012 MTG() functions 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 DotP 2012 Filter() functions 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 DotP 2012 MTG() functions 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 DotP 2012 Characteristics() functions 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, his "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, his "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 DotP 2012 Filter() functions 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>
work in progress...