Package net.demilich.metastone.game.targeting

Class EntityReference

java.lang.Object
net.demilich.metastone.game.targeting.EntityReference
All Implemented Interfaces:
Serializable
public final class EntityReference extends Object implements Serializable
An entity reference identifies a specific game entity, like a card or minion; or, it is interpreted as a group of entities, possibly always of length 1 (like FRIENDLY_HERO) or 0 or more (FRIENDLY_MINIONS). These references are called group references, and their isTargetGroup() will return true.

Group references are appropriate to put into SpellArg.TARGET. If SpellArg.RANDOM_TARGET is specified along with a group reference, a random entity from the group will be chosen.

When Entity.getReference() is called, a specific (non-group) reference is always returned. Thus, calling Entity.getReference() will never return FRIENDLY_HERO.

When the target has been transformed, group reference resolution will always return the transformed targets using Entity.transformResolved(GameContext). Resolving a target using GameContext.resolveSingleTarget(EntityReference) will also always return the transformed target, regardless if it is a group reference or not.

All references omit Attribute.PERMANENT actors except SELF, ALL_ENTITIES, TRIGGER_HOST, OUTPUT, EVENT_SOURCE, EVENT_TARGET and TRANSFORM_REFERENCE.

Friendly versus enemy references are evaluated with respect to the calling/casting player. This includes triggers that are put on the opponent by effects cast by the player. In other words, regardless of "where" the source is, the player from whose point of view the reference is being resolved is always the caster.

This can be confusing in a situation like Loatheb, who puts a CardCostModifier on the caster's Player entity whose CardCostModifierArg.TARGET is FRIENDLY_HAND but whose CardCostModifierArg.TARGET_PLAYER is TargetPlayer.OPPONENT. In card cost modifiers, target player is used to determine if a modifier affects a card by comparing the trigger's owner to the card's owner; opponent indicates that the card's owner must not equal the trigger's owner. However, FRIENDLY_HAND is evaluated from each player's point of view separately, because card cost modifiers (GameLogic.getModifiedManaCost(Player, Card)) are evaluated by both players, always (this allows opponents to see card cost changes).

Or, for example, Temporus causes a spell to be cast during the turn of the opponent of the owner of Temporus. The source of the spell that modifies the Attribute.EXTRA_TURN of both players is cast during the opponent's turn and in an event whose TargetPlayer is the opponent. But, EnchantmentDesc.spell is always cast by the enchantment's owner, which was the caster who originally put the enchantment into play. Therefore, the source will be the same as the player who put Temporus onto the battlefield, and that's from whose point of view the FRIENDLY_PLAYER and ENEMY_PLAYER will be evaluated.

See Also:

  • Field Details

    • NONE

      public static final EntityReference NONE
      Indicates a spell should take no target. It will receive null as its target argument.

    • ENEMY_CHARACTERS

      public static final EntityReference ENEMY_CHARACTERS
      References all the enemy characters (the opponent's hero and minions).

    • ENEMY_MINIONS

      public static final EntityReference ENEMY_MINIONS
      References all the enemy's minions.

    • ENEMY_HERO

      public static final EntityReference ENEMY_HERO
      References a list with a single element, the enemy's hero. This list may extremely rarely be empty if the target evaluation is being performed after the hero is destroyed.

    • FRIENDLY_CHARACTERS

      public static final EntityReference FRIENDLY_CHARACTERS
      References all the friendly characters (the player's hero and minions).

    • FRIENDLY_MINIONS

      public static final EntityReference FRIENDLY_MINIONS
      References all the player's minions.

    • OTHER_FRIENDLY_MINIONS

      public static final EntityReference OTHER_FRIENDLY_MINIONS
      References all the player's minions except the source of this targeting resolution. For example, battlecries often specify other friendly minions to give a bonus to any friendly minion besides itself.

    • ADJACENT_MINIONS

      public static final EntityReference ADJACENT_MINIONS
      References a possibly zero-length list of minions adjacent to the source of this targeting resolution.

    • FRIENDLY_HERO

      public static final EntityReference FRIENDLY_HERO
      References the friendly hero.

    • ALL_MINIONS

      public static final EntityReference ALL_MINIONS
      References all the minions on the board.

    • ALL_CHARACTERS

      public static final EntityReference ALL_CHARACTERS
      References both heroes and all the minions on the board.

    • ALL_OTHER_CHARACTERS

      public static final EntityReference ALL_OTHER_CHARACTERS
      References all the heroes and minions excluding the source of this targeting resolution.

    • ALL_OTHER_MINIONS

      public static final EntityReference ALL_OTHER_MINIONS
      References all the minions excluding the source of this targeting resolution.

    • FRIENDLY_WEAPON

      public static final EntityReference FRIENDLY_WEAPON
      References the Weapon of the friendly hero, or a zero-length list if one isn't equipped.

    • ENEMY_WEAPON

      public static final EntityReference ENEMY_WEAPON
      References the weapon of the enemy hero, or a zero-length list if one isn't equipped.

    • FRIENDLY_HAND

      public static final EntityReference FRIENDLY_HAND
      References all the cards in the player's hand.

    • ENEMY_HAND

      public static final EntityReference ENEMY_HAND
      References all the cards in the enemy player's hand./

    • OPPOSITE_MINIONS

      public static final EntityReference OPPOSITE_MINIONS
      References zero, one or two minions opposite of this source minion.

    • LEFTMOST_FRIENDLY_MINION

      public static final EntityReference LEFTMOST_FRIENDLY_MINION
      References the friendly minion whose index in the minions zone is 0, which can possibly be the source minion. Or, a zero length list if no friendly minions are on the board.

    • LEFTMOST_ENEMY_MINION

      public static final EntityReference LEFTMOST_ENEMY_MINION
      References the enemy minion whose index in the minions zone is 0. Or, a zero length list if no enemy minions are on the board.

    • FRIENDLY_PLAYER

      public static final EntityReference FRIENDLY_PLAYER
      References the friendly Player entity. This entity is a useful host for enchantments and attributes like Attribute.EXTRA_TURN.

    • ENEMY_PLAYER

      public static final EntityReference ENEMY_PLAYER
      References the enemy Player entity. This entity is a useful host for enchantments and attributes like Attribute.EXTRA_TURN.

    • MINIONS_TO_LEFT

      public static final EntityReference MINIONS_TO_LEFT
      References the minions with an index less than the source minion.

      The client will appear to be targeting to the minions on-screen to the right of the source.

    • MINIONS_TO_RIGHT

      public static final EntityReference MINIONS_TO_RIGHT
      References the minions with an index greater than the source minion.

      The client will appear to be targeting to the minions on-screen to the left of the source.

    • TARGET

      public static final EntityReference TARGET
      When the player performs a GameAction that has a target choice, like a physical attack, a targeted battlecry, casting a targeted spell or summoning a minion (interpreted as the minion the player is summoning next to), this reference will return the target that the player originally chose regardless of target overriding effects or effects in the sequence that may later destroy or transform the target.

    • SPELL_TARGET

      public static final EntityReference SPELL_TARGET
      This reference allows you to distinguish the target of an effect (the spell target) versus the target selected by a player (the TARGET).

      When an effect like a spell card, a battlecry or an enchantment casts a Spell with a group reference, the spell is cast separately for each entity in the list of entities after that group reference is resolved. Use this reference to retrieve the specific entity (rather than the group reference) that the spell is currently being evaluated against.

      For example, suppose you had a spell, "Choose a minion. For each other minion, you have a 50% of dealing damage equal to the minion's attack or the chosen minion's hitpoints". You need some way of referencing the minion being damaged versus the minion that was chosen by the player. Spell target is the minion currently being damaged, while TARGET (or inherited from the topmost spell) is the minion that was chosen: 

           "targetSelection": "MINIONS",
     "spell": {
         "class": "EitherOrSpell",
         "target": "ALL_OTHER_MINIONS",
         "condition": {"class": "RandomCondition"},
         "spell1": {
             "class": "DamageSpell",
             "value": {
                 "class": "AttributeValueProvider",
                 "target": "SPELL_TARGET",
                 "attribute": "ATTACK"
             }
         },
         "spell2": {
             "class": "DamageSpell",
             "value": {
                 "class": "AttributeValueProvider",
                 "target": "TARGET",
                 "attribute": "HP"
             }
         }
     }

    • EVENT_TARGET

      public static final EntityReference EVENT_TARGET
      This reference retrieves the (possibly null) entity pointed to by GameEvent.getTarget(). An event target is never itself a group reference; it always retrieves a specific entity.

      To see which game events generate targets, which can be counter-intuitive, look at the constructors of the various GameEvent classes and see how they're called.

      Some important event targets include:

    • SELF

      public static final EntityReference SELF
      Returns the source of the target resolution.

      Inside an enchantment's EventTriggerArg.FIRE_CONDITION and EventTriggerArg.QUEUE_CONDITION, which are the conditions that evaluate whether or not the trigger for the enchantment should fire, the source entity is the GameEvent.getSource(); it is not the entity hosting the trigger. To get the entity hosting the trigger, use TRIGGER_HOST instead.

    • KILLED_MINION

      public static final EntityReference KILLED_MINION
      Retrieves a reference to the minion destroyed by a DestroySpell.

    • ATTACKER

      public static final EntityReference ATTACKER
      This references the attacker during a PhysicalAttackAction or GameLogic.fight(Player, Actor, Actor, PhysicalAttackAction) invocation (i.e., a FightSpell).

    • OUTPUT

      public static final EntityReference OUTPUT
      Use this reference to apply effects to new entities created by spells.

      For example, to apply a buff to a newly summoned minion: 

           "spell": {
         "class": "SummonSpell",
         "card": "minion_bloodfen_raptor",
         "spell": {
             "class": "BuffSpell",
             "target": "OUTPUT",
             "attackBonus": 2
         }
     }
      Like SPELL_TARGET, this reference helps you distinguish between the player's chosen TARGET, which will be propagated downwards to child spells, and the entity created by something like a SummonSpell.
      See Also:

    • FRIENDLY_DECK

      public static final EntityReference FRIENDLY_DECK
      References all the cards in the player's deck.

    • ENEMY_DECK

      public static final EntityReference ENEMY_DECK
      References all the card's in the enemy player's deck.

    • BOTH_DECKS

      public static final EntityReference BOTH_DECKS
      References all the cards in both decks.

    • BOTH_HANDS

      public static final EntityReference BOTH_HANDS
      References all the cards in both hands.

    • TRANSFORM_REFERENCE

      @Deprecated public static final EntityReference TRANSFORM_REFERENCE
      Deprecated.
      When a minion gets transformed while it is being summoned, the result of the transformation of the minion is found with this reference.

      Deprecated by Entity.transformResolved(GameContext).

    • RIGHTMOST_FRIENDLY_MINION

      public static final EntityReference RIGHTMOST_FRIENDLY_MINION
      References the friendly minion with the largest index in the minions zone, or an empty list if the minion zone is empty.

      The rightmost minion in the client will appear to be the leftmost one.

    • RIGHTMOST_ENEMY_MINION

      public static final EntityReference RIGHTMOST_ENEMY_MINION
      References the enemy minion with the largest index in the minions zone, or an empty list if the minion zone is empty.

      The rightmost minion in the client will appear to be the leftmost one.

    • ATTACKER_ADJACENT_MINIONS

      public static final EntityReference ATTACKER_ADJACENT_MINIONS
      References the minions adjancent to the attacker during a GameLogic.fight(Player, Actor, Actor, PhysicalAttackAction) sequence.

    • FRIENDLY_SET_ASIDE

      public static final EntityReference FRIENDLY_SET_ASIDE
      References the cards and actors located in the friendly set aside zone. Rarely used.

    • ENEMY_SET_ASIDE

      public static final EntityReference ENEMY_SET_ASIDE
      References the cards and actors located in the enemy set aside zone. Rarely used.

    • FRIENDLY_GRAVEYARD

      public static final EntityReference FRIENDLY_GRAVEYARD
      References the cards and actors in the friendly graveyard.

      TODO: It is not easy to distinguish between cards and actors in the graveyard.

      To retrieve cards, use the GraveyardCardsSource. To retrieve actors (weapons, minions and heroes that have been destroyed), use GraveyardActorsSource.

    • ENEMY_GRAVEYARD

      public static final EntityReference ENEMY_GRAVEYARD
      References the cards and actors in the enemy graveyard.

      TODO: It is not easy to distinguish between cards and actors in the graveyard.

      To retrieve cards, use the GraveyardCardsSource. To retrieve actors (weapons, minions and heroes that have been destroyed), use GraveyardActorsSource.

    • ALL_ENTITIES

      public static final EntityReference ALL_ENTITIES
      References all entities in the game, including transformed ones and permanents. Typically used to find attributes about specific cards played or used in the past; or to find specific permanents in play.
      See Also:

    • EVENT_SOURCE

      public static final EntityReference EVENT_SOURCE
      References the GameEvent.getSource() entity when a trigger/enchantment is being evaluated.
      See Also:

    • FRIENDLY_TOP_CARD

      public static final EntityReference FRIENDLY_TOP_CARD
      References the next card the friendly player will draw, or an empty list if no cards remain in the player's deck.

    • ENEMY_TOP_CARD

      public static final EntityReference ENEMY_TOP_CARD
      References the next card the opponent will draw, or an empty list if no cards remain in the player's deck.

    • FRIENDLY_HERO_POWER

      public static final EntityReference FRIENDLY_HERO_POWER
      References the card that is currently the friendly player's hero power.

    • ENEMY_HERO_POWER

      public static final EntityReference ENEMY_HERO_POWER
      References the card that is currently the enemey player's hero power.

    • OTHER_ENEMY_MINIONS

      public static final EntityReference OTHER_ENEMY_MINIONS
      References all the enemy minions excluding the source.

      Implements Frost Bomb.

    • LEFTMOST_FRIENDLY_CARD_HAND

      public static final EntityReference LEFTMOST_FRIENDLY_CARD_HAND
      References the card in the friendly player's hand with the lowest index in the friendly player's hand.

      Implements Antique Collector and Ironforge Baker.

    • LAST_CARD_PLAYED

      public static final EntityReference LAST_CARD_PLAYED
      References the last card played by either player. It will typically be in the player's hand (before it is casted) or in the graveyard (at most other times).

      Implements Shadow of the Past.

    • FRIENDLY_LAST_CARD_PLAYED

      public static final EntityReference FRIENDLY_LAST_CARD_PLAYED
      References the last card played by the friendly player.

    • ENEMY_LAST_CARD_PLAYED

      public static final EntityReference ENEMY_LAST_CARD_PLAYED
      References the last card played by the opponent.

    • TRIGGER_HOST

      public static final EntityReference TRIGGER_HOST
      References the Entity that hosts the Enchantment whose fire condition or spell is currently being evaluated.

      During a condition evaluation on an EventTrigger, SELF refers to GameEvent.getSource(), not the host of the trigger whose condition is being evaluated. Use this reference to get the host of the trigger currently being evaluated.

      See Also:

    • ENEMY_MINIONS_LEFT_TO_RIGHT

      public static final EntityReference ENEMY_MINIONS_LEFT_TO_RIGHT
      References all the enemy's minions, except ordered by their location on the board instead of their order of play.

    • PHYSICAL_ATTACK_TARGETS

      public static final EntityReference PHYSICAL_ATTACK_TARGETS
      References the enemy minions and hero which would ordinarily be targetable by a physical attack from the friendly player's point of view.

    • LEFT_ADJACENT_MINION

      public static final EntityReference LEFT_ADJACENT_MINION
      References the minion to the left of the source of this targeting resolution, or a zero-length list if there isn't one

    • RIGHT_ADJACENT_MINION

      public static final EntityReference RIGHT_ADJACENT_MINION
      References the minion to the right of the source of this targeting resolution, or a zero-length list if there isn't one

    • LAST_CARD_PLAYED_BEFORE_CURRENT_SEQUENCE

      public static final EntityReference LAST_CARD_PLAYED_BEFORE_CURRENT_SEQUENCE
      References the last card played by either player before the end of this current sequence.

      Implements Study.

    • FRIENDLY_LAST_CARD_PLAYED_BEFORE_CURRENT_SEQUENCE

      public static final EntityReference FRIENDLY_LAST_CARD_PLAYED_BEFORE_CURRENT_SEQUENCE
      References the last card played by the friendly player before this current sequence.

    • ENEMY_LAST_CARD_PLAYED_BEFORE_CURRENT_SEQUENCE

      public static final EntityReference ENEMY_LAST_CARD_PLAYED_BEFORE_CURRENT_SEQUENCE
      References the last card played by the opponent before this current sequence.

    • FRIENDLY_MINIONS_LEFT_TO_RIGHT

      public static final EntityReference FRIENDLY_MINIONS_LEFT_TO_RIGHT
      References all the friendly minions, except ordered by their location on the board instead of their order of play.

    • ADJACENT_TO_TARGET

      public static final EntityReference ADJACENT_TO_TARGET
      References the minions adjacent to the current TARGET, i.e., the currently selected target in the pending action.

    • FRIENDLY_LAST_DIED_MINION

      public static final EntityReference FRIENDLY_LAST_DIED_MINION
      References the last minion belonging to the friendly player that died.

    • FRIENDLY_DECK_FROM_TOP

      public static final EntityReference FRIENDLY_DECK_FROM_TOP
      References all the cards in the player's deck, ordered from the top of the deck towards the bottom.

    • CURRENT_SUMMONING_MINION

      public static final EntityReference CURRENT_SUMMONING_MINION
      References the minion that is currently being summoned.

      This entry is valid from just before BeforeSummonEvent is fired and just after AfterSummonEvent is fired. Since battlecries are resolved between BeforeSummonEvent and SummonEvent, this reference may change to the minion being summoned by a battlecry rather than the battlecrying minion itself, depending on when this reference resolved.

    • FRIENDLY_CARDS

      public static final EntityReference FRIENDLY_CARDS
      References all entities that are "in play" for the friendly player i.e. cards in hand, deck, set aside + minions + hero.

    • ENEMY_CARDS

      public static final EntityReference ENEMY_CARDS
      References all entities that are "in play" for the enemy player i.e. cards in hand, deck, set aside + minions + hero.

    • ENEMY_MIDDLE_MINIONS

      public static final EntityReference ENEMY_MIDDLE_MINIONS
      References the minions that are in the middle of the enemy's battlefield. This will return two minions when the number of minions on the opponent's battlefield is even.

    • FRIENDLY_LAST_MINION_PLAYED

      public static final EntityReference FRIENDLY_LAST_MINION_PLAYED
      References the last minion card played before this current sequence.

    • OTHER_FRIENDLY_CHARACTERS

      public static final EntityReference OTHER_FRIENDLY_CHARACTERS
      References a combination of OTHER_FRIENDLY_MINIONS and the FRIENDLY_HERO.

    • RIGHTMOST_FRIENDLY_CARD_HAND

      public static final EntityReference RIGHTMOST_FRIENDLY_CARD_HAND
      References the card in the friendly player's hand with the highest index.

      Implements Mutamite Terror.

    • LEFTMOST_ENEMY_CARD_HAND

      public static final EntityReference LEFTMOST_ENEMY_CARD_HAND
      References the card in the enemy player's hand with the lowest index in the enemy player's hand.

      Implements Mindswapper.

    • FRIENDLY_LAST_SPELL_PLAYED_THIS_TURN

      public static final EntityReference FRIENDLY_LAST_SPELL_PLAYED_THIS_TURN
      References the last spell played by this player this turn only.

      Implements Recurring Torrent.

    • OPPOSITE_CHARACTERS

      public static final EntityReference OPPOSITE_CHARACTERS
      Returns the opposing characters from the source. If there is no minion opposite of the source, returns the opposing champion instead.

    • FRIENDLY_SIGNATURE

      public static final EntityReference FRIENDLY_SIGNATURE

    • ENEMY_SIGNATURE

      public static final EntityReference ENEMY_SIGNATURE

    • FRIENDLY_SECRETS

      public static final EntityReference FRIENDLY_SECRETS

    • PLAYER_1

      public static final EntityReference PLAYER_1

    • PLAYER_2

      public static final EntityReference PLAYER_2

  • Constructor Details

    • EntityReference

      public EntityReference(int key)

  • Method Details

    • pointTo

      @NotNull public static @NotNull EntityReference pointTo(Entity entity)

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • getId

      public int getId()

    • setId

      public void setId(int key)

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • isTargetGroup

      public boolean isTargetGroup()
      When true, indicates that this entity reference references not to a specific Entity but to a pointer to an entity, like SELF.
      Returns:
      true if the id is negative, which all the special EntityReference static elements are.

    • toString

      public String toString()
      Overrides:
      toString in class Object