Package org.spongepowered.api.event.entity

Interface DamageEntityEvent

  • All Superinterfaces:
    Cancellable, Event
    All Known Implementing Classes:
    AbstractDamageEntityEvent
    public interface DamageEntityEvent
extends Event, Cancellable
    Represents the base event for when an Entity is being "attacked". The uniqueness of this event is that all DamageSources can deal varying amounts of damage with varying modifiers based on various reasons. Due to this ambiguous variety of information that is possible to provide, the DamageEntityEvent can be summarized as so:

    An ArrowEntity, that was shot by a Skeleton, with an enchanted ItemTypes.BOW ItemStack, when the World Difficulty was set to Difficulties.HARD, will deal possibly "5" damage to any Entity it hits.

    The issue with representing this type of "logic flow" is that a particular amount of damage from a DamageSource, even if specified to a particular DamageType, has no static finalized amount of damage to deal to a particular Entity. To properly represent this, a DamageSource has various "states" such as: DamageSource.isAbsolute(), or DamageSource.isBypassingArmor(). Quite simply, the DamageSource will always be the "first" element within a Cause that can be retrieved from Event.cause().

    Next, any additional "aides" in attacking the Entity will be included in order of "priority of relation" to "attacking" the entity. In short, if another Entity is considered a "team member" to the attacking Entity, the "team member" may be a second element within the Cause. The same can be said if an ArrowEntity was shot from a Dispenser that was triggered by a Player flipping a switch.

    Continuing with the notion of "modifiers" to damage, the "base" damage is modified or added onto after various unknown methods are called or processed on the damage. Optimally, these modifiers can be traced to a particular object, be it an ItemStack, Difficulty, or simply an an attribute. The interesting part is that these "modifiers" do not just define a static value to add to the "base" damage, they are usually a loose form of a DamageFunction that are applied to the "base" damage. Given that Cause has a unique capability of storing any and every Object willing to be passed into it, we can easily represent these "sources" of "modifiers" in a Cause. Now, knowning the "source" will not provide enough information, so a DamageModifierType is provided with a DamageModifier to paint the fullest picture of "explaining" the DamageModifier as to why it is present, and why it is "modifying" the "base" damage. Finally, we can associate a DamageModifier with a DamageFunction that is passed the current "damage" into DoubleUnaryOperator.applyAsDouble(double) , being added to the current "damage". After all DamageModifier DamageFunctions are "applied", the overall "damage" is now the final damage to actually throw a DamageEntityEvent.

    Note that due to the mechanics of the game, DamageModifiers are always ordered in the order of which they apply their modifier onto the "base" damage. The implementation for finalDamage() can be exemplified like so:

    
 double damage = this.baseDamage;<br />
 for (Map.Entry<DamageModifier, Function<? super Double, Double>> entry : this.modifierFunctions.entrySet()) {
     damage += checkNotNull(entry.getValue().apply(damage));
 }
 return damage;

    After which, the "final" damage is simply the summation of the "base" damage and all "modified damage" for each DamageModifier provided in this event.

    Coming forward, it is possible to further customize not only the "base" damage, but override pre-existing DamageModifier DamageFunctions by calling setDamage(DamageModifier, DoubleUnaryOperator) at which point the end result may be undefined. However, if a custom DamageModifier that aims to alter the "final" damage based on some custom circumstances, calling setDamage(DamageModifier, DoubleUnaryOperator) on a new DamageModifier instance, easily created from the DamageModifier.Builder, the provided pairing will be added at the "end" of the list for "modifying" the "base" damage.

    Note that this event is intended for processing incoming damage to an Entity prior to any DamageModifiers associated with the entity(). The DamageEntityEvent is used to process the various DamageModifiers of which originate or are associated with the targeted Entity.

    • Method Detail

      • entity

        Entity entity()
        Gets the Entity.
        Returns:
        The entity

      • originalDamage

        double originalDamage()
        Gets the original "raw" amount of damage to deal to the targeted Entity.
        Returns:
        The original "raw" damage

      • originalFinalDamage

        double originalFinalDamage()
        Gets the original "final" amount of damage after all original DamageModifiers are applied to originalDamage(). The "final" damage is considered the amount of health being lost by the Entity, if health is tracked.
        Returns:
        The final amount of damage to originally deal

      • originalDamages

        java.util.Map<DamageModifier,​java.lang.Double> originalDamages()
        Gets an ImmutableMap of all original DamageModifiers and their associated "modified" damage. Note that ordering is not retained.
        Returns:
        An immutable map of the original modified damages

      • originalModifierDamage

        double originalModifierDamage​(DamageModifier damageModifier)
        Gets the original damage for the provided DamageModifier. If the provided DamageModifier was not included in originalDamages(), an IllegalArgumentException is thrown.
        Parameters:
        damageModifier - The original damage modifier
        Returns:
        The original damage change

      • originalFunctions

        java.util.List<DamageFunction> originalFunctions()
        Gets the original List of DamageModifier to DamageFunction that was originally passed into the event.
        Returns:
        The list of damage modifier functions

      • baseDamage

        double baseDamage()
        Gets the "base" damage to deal to the targeted Entity. The "base" damage is the original value before passing along the chain of DamageFunctions for all known DamageModifiers.
        Returns:
        The base damage

      • setBaseDamage

        void setBaseDamage​(double baseDamage)
        Sets the "base" damage to deal to the targeted Entity. The "base" damage is the original value before passing along the chain of DamageFunctions for all known DamageModifiers.
        Parameters:
        baseDamage - The base damage

      • isModifierApplicable

        boolean isModifierApplicable​(DamageModifier damageModifier)
        Checks whether the provided DamageModifier is applicable to the current available DamageModifiers.
        Parameters:
        damageModifier - The damage modifier to check
        Returns:
        True if the damage modifier is relevant to this event

      • addDamageModifierBefore

        void addDamageModifierBefore​(DamageModifier damageModifier,
                             java.util.function.DoubleUnaryOperator function,
                             java.util.Set<DamageModifierType> before)
        Adds the provided DamageModifier and DoubleUnaryOperator to the list of modifiers, such that the Set containing DamageModifierTypes provided in before will appear after the provided damage modifier.
        Parameters:
        damageModifier - The damage modifier to add
        function - The associated function
        before - The set containing the modifier types to come after the provided modifier

      • addModifierAfter

        void addModifierAfter​(DamageModifier damageModifier,
                      java.util.function.DoubleUnaryOperator function,
                      java.util.Set<DamageModifierType> after)
        Adds the provided DamageModifier and DoubleUnaryOperator to the list of modifiers, such that the modifier will appear in order after any current modifiers whose type are included in the provided Set of DamageModifierTypes.
        Parameters:
        damageModifier - The damage modifier to add
        function - The associated function
        after - The set of modifier types to come before the new modifier

      • willCauseDeath

        boolean willCauseDeath()
        Returns whether or not this event will cause the entity to die if the event is not cancelled. Only supported for living entities, returns false if entity() is not a living entity.
        Returns:
        Whether the entity will die