Class Entity

java.lang.Object
net.demilich.metastone.game.logic.CustomCloneable
net.demilich.metastone.game.entities.Entity
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<Entity>, HasCard
Direct Known Subclasses:
Actor, Card, Enchantment, Player

public abstract class Entity
extends CustomCloneable
implements java.io.Serializable, HasCard, java.lang.Comparable<Entity>
An in-game entity.

Entities are targetable objects in a match. The player, hero, hero power card, minions, cards in hand, cards in deck, cards in graveyard, secrets and certain kinds of triggers are all entities.

Entities are only created, never destroyed. Entities have a EntityLocation; each location (index, zone and player) can have only one entity occupying it at any time. Destroyed entities go to the Zones.GRAVEYARD or Zones.REMOVED_FROM_PLAY zone. EntityZone lists located in the Player objects are reponsible for making sure entities are in only one place at a time.

Entities all have attributes, which contain their state. As simple maps, entity attributes can be manipulated, copied, etc. Most effects interact with an entity's attributes.

Entities are mutable. Use clone() to create an "immutable" view of an entity. However, for effects that need copies of entities, typically a getCopy() method is used, like Card.getCopy().

This entity class will contain all the game engine information. It is not suitable to show to clients directly, because it may contain information that should be secret from an opponent. For example, Secret entities should have their description or card IDs visible to their opponents.

See Also:
Serialized Form
  • Field Details

  • Constructor Details

  • Method Details

    • hasEntityType

      public static boolean hasEntityType​(com.hiddenswitch.spellsource.client.models.EntityType thisEntity, com.hiddenswitch.spellsource.client.models.EntityType other)
    • clone

      public Entity clone()
      Clone an entity, including its ID and location.

      Use this method for emulating an "immutable" view on an entity. This kind of cloning is not suitable for most gameplay situations, because using the clone will cause two entities with identical IDs and locations to exist. Instead, a subclass will provide a getCopy() method that is more helpful for gameplay.

      Overrides:
      clone in class CustomCloneable
      Returns:
      An exact clone.
    • getAttribute

      public java.lang.Object getAttribute​(Attribute attribute)
      Gets the specified attribute.

      Attributes are Integer, String, String array or Enum types.

      Parameters:
      attribute - The attribute to look up.
      Returns:
      The value of the attribute.
      See Also:
      to get the value of attributes., for a list of attributes.
    • getAttributes

      public AttributeMap getAttributes()
      Gets the complete attribute map reference (not a copy). This can be mutated like a normal Map.
      Returns:
      The AttributeMap.
    • getAttributeValue

      public int getAttributeValue​(Attribute attribute)
      Gets the specified attribute as an Integer value or 0 if the specified attribute is of the wrong type or is not found.
      Parameters:
      attribute - The Attribute to look up.
      Returns:
      The attribute's value or 0 if it isn't set.
    • getAttributeValue

      public int getAttributeValue​(Attribute attribute, int defaultValue)
      Gets the specified attribute as an Integer value, defaulting to the specified value if the value is not an integer.
      Parameters:
      attribute - The Attribute to look up.
      Returns:
      The attribute's value or 0 if it isn't set.
    • getEntityType

      public abstract com.hiddenswitch.spellsource.client.models.EntityType getEntityType()
      Gets the type of entity this is. These will very nearly match up with the classes, but are primarily used for filters that e.g. draw a Spell or destroy all Secrets.
      Returns:
      An EntityType
    • getId

      public int getId()
      The entity's ID in the match.

      IDs are set by default to IdFactory.UNASSIGNED. This means entity IDs are mutable; entity IDs must be mutable because entities can be cloned with clone(). In practice, once an entity's ID is set, it is not set again.

      Returns:
      The entity's ID, or IdFactory.UNASSIGNED if it is unassigned.
      See Also:
      for the class that generates IDs., for the place where minion IDs are set., for the place where IDs are set for all the cards that start in the game., for a class used to store the notion of a "target."
    • getName

      public java.lang.String getName()
      Gets the name of the entity (typically the name of the card that created this entity). Or, overridden by the Attribute.NAME attribute set in this entity's attributes.
      Returns:
      The name.
    • getOwner

      public int getOwner()
      Gets the owner of this entity, or IdFactory.UNASSIGNED if it has no owner.

      Owners are mutable because the owner of an entity, especially minions, can change.

      The owner should match the getEntityLocation()'s owner. The minion's location should be changed first, then its owner.

      Returns:
      GameContext.PLAYER_1, GameContext.PLAYER_2, or IdFactory.UNASSIGNED.
    • getReference

      @NotNull public @NotNull EntityReference getReference()
      Gets an EntityReference that points to this entity.
      Returns:
      An EntityReference.
      See Also:
      for a better understanding of how references can point to a specific entity or to some notion of a group of entities (like ).
    • hasAttribute

      public boolean hasAttribute​(Attribute attribute)
      Checks if the Entity has the specified Attribute.
      Parameters:
      attribute - The Attribute.
      Returns:
      true if it has the attribute.
    • getMaxNumberOfAttacks

      public int getMaxNumberOfAttacks()
    • isDestroyed

      public boolean isDestroyed()
      Checks if the entity is destroyed. Overridden to take into account entities with hitpoints.
      Returns:
      true if it is destroyed.
      See Also:
      for a more complete implementation.
    • modifyAttribute

      public void modifyAttribute​(Attribute attribute, int value)
      Increments or decrements the specified Integer Attribute by the value given.
      Parameters:
      attribute - The attribute.
      value - The amount to increment or decrement the attribute by.
    • modifyHpBonus

      public void modifyHpBonus​(int value)
      Modifies the HP bonus for the given entity.
      Parameters:
      value - The amount to increment or decrement the HP bonus by.
    • setAttribute

      public void setAttribute​(Attribute attribute)
      Sets an attribute. This will remove silencing when it is called. Since boolean values are not stored in attributes, attributes that are "boolean" are just set to 1. Setting the value to 0 is not equivalent to not having the attribute.
      Parameters:
      attribute - The attribute to set.
    • setAttribute

      public void setAttribute​(Attribute attribute, int value)
      Sets an attribute to a specific integer value. This will remove silencing when it is called. It does not enforce that the attribute is something that only accepts Integer values.
      Parameters:
      attribute - The attribute to set.
      value - The value.
    • setAttribute

      public void setAttribute​(Attribute attribute, java.lang.Object value)
      Sets an attribute to a generic object, like a string. This clears silencing when it is called.
      Parameters:
      attribute - The attribute to set.
      value - Its new object value.
    • setId

      public void setId​(int id)
    • setName

      public void setName​(java.lang.String name)
    • setOwner

      public void setOwner​(int ownerIndex)
    • hasPersistentEffects

      public boolean hasPersistentEffects()
      Entities with persistent effects need their events to be processed differently in order to record those persistent values to a database.
      Returns:
      true if the entity needs to have its persistent effects persisted.
      See Also:
      for an example of a persistent attribute that needs to be stored between matches.
    • getUserId

      public java.lang.String getUserId()
      Gets the user ID of the owner of this card.
      Returns:
      The user ID.
    • setUserId

      protected void setUserId​(java.lang.String userId)
    • getCardInventoryId

      public java.lang.String getCardInventoryId()
      Gets the card's inventory ID (unique instance of the card).
      Returns:
      The card inventory ID.
    • getEntityLocation

      public EntityLocation getEntityLocation()
      Gets the EntityLocation of the entity, which includes its EntityLocation.zone, EntityLocation.player and EntityLocation.index.

      Returns:
      The entity's location in the match encoded as a EntityLocation, or EntityLocation.UNASSIGNED if the entity has not yet been assigned a location or placed into an EntityZone.
      See Also:
      for a complete description of how to use objects.
    • setEntityLocation

      public void setEntityLocation​(EntityLocation entityLocation)
      Should not be called.

      Sets the entity location. Typically only called by an EntityZone.

      Parameters:
      entityLocation - The new location of the entity.
    • resetEntityLocations

      public void resetEntityLocations()
      Should not be called.

      Resets the entity's location by setting it to EntityLocation.UNASSIGNED. Typically only called by an EntityZone.

    • moveOrAddTo

      public void moveOrAddTo​(GameContext context, Zones destination) throws java.lang.ArrayStoreException
      Moves this entity to a new zone (Zones) belonging to the Player indexed by getOwner().
      Parameters:
      context - The game context this entity is in.
      destination - The destination zone belonging to the player to move to.
      Throws:
      java.lang.ArrayStoreException - if the entity has no owner; or if the entity already exists in the destination.
    • moveOrAddTo

      public void moveOrAddTo​(GameContext context, Zones destination, int index) throws java.lang.ArrayStoreException
      Moves this entity to a new zone (Zones) belonging to the Player indexed by getOwner().
      Parameters:
      context - The game context this entity is in.
      destination - The destination zone belonging to the player to move to.
      index - The location in the zone to move or add to
      Throws:
      java.lang.ArrayStoreException - if the entity has no owner; or if the entity already exists in the destination.
    • getZone

      public Zones getZone()
      Gets the current zone the entity is located in.
      Returns:
      The Zones zone.
    • transformResolved

      public Entity transformResolved​(GameContext context)
      Follows Attribute.TRANSFORM_REFERENCE until the resolved entity is found.

      Limits the number of transformations to follow to 14.

      Parameters:
      context - A GameContext to perform lookups in.
      Returns:
      This entity if no transform is found, otherwise follows the chain of resolved entities until no transformed entity is found.
    • transformResolved

      protected Entity transformResolved​(GameContext context, int depth)
    • getDescription

      public java.lang.String getDescription()
      Gets the possibly modified description of the entity to render to the end user.
      Returns:
      The getSourceCard()'s Card.getDescription() field, or the value specified in Attribute.DESCRIPTION.
    • setDescription

      public Entity setDescription​(java.lang.String description)
      Sets the description by setting the Attribute.DESCRIPTION attribute.
      Parameters:
      description -
      Returns:
    • getCopy

      public abstract Entity getCopy()
    • getCopySource

      public EntityReference getCopySource()
      Gets a reference to the entity that this entity was potentially copied from.
      Returns:
      null if this entity was not copied from another entity in the game, or an EntityReference of another entity.
    • getGameTriggers

      public EnchantmentDesc[] getGameTriggers()
      Gets a list of triggers that are active as soon as the game starts.
      Returns:
      The entity's defined game triggers
      See Also:
      for the place to activate these triggers.
    • getDynamicDescription

      public DynamicDescriptionDesc[] getDynamicDescription()
    • evaluateDescriptions

      public java.lang.String[] evaluateDescriptions​(GameContext context, Player player)
    • compareTo

      public int compareTo​(@NotNull @NotNull Entity o)
      Specified by:
      compareTo in interface java.lang.Comparable<Entity>
    • getRace

      @NotNull public @NotNull java.lang.String getRace()
    • isInPlay

      public boolean isInPlay()
      Indicates that the entity is in play by being in an in-play zone.
      Returns:
      true if the entity is visible to both players
    • getIndex

      public int getIndex()
      The entity's index in its zone.
      Returns:
      EntityLocation.UNASSIGNED 's index if it isn't yet in a zone (typically -1), or the index in the getZone() this entity is in.
    • isRemovedPeacefully

      public boolean isRemovedPeacefully()
      Is this entity removed peacefully?
      Returns:
      true if it's in the graveyard and didn't die violently, otherwise false.
    • getDescription

      public java.lang.String getDescription​(GameContext context, Player player)
      Gets an entity's description applying its CardDesc.getDynamicDescription() fields and parsing spell damage and health restoration.
      Parameters:
      context - The context
      player - The player whose POV this description should be evaluated
      Returns:
      The dynamic description if this entity is a card, otherwise the getDescription().
    • diedOnBattlefield

      public boolean diedOnBattlefield()
      Indicates whether the minion died a natural death (not removed peacefully, not removed by spells, not a permanent) on the battlefield.
      Returns:
      true if this minion died a natural death on the battlefield, is not a permanent, is in the graveyard and is definitely a minion.
    • getSourceCard

      public Card getSourceCard()
      Specified by:
      getSourceCard in interface HasCard
    • setSourceCard

      public Entity setSourceCard​(Card sourceCard)
    • getEffectSource

      public Entity getEffectSource()
    • setEffectSource

      public Entity setEffectSource​(Entity effectSource)