public interface DamageEntityEvent extends TargetEntityEvent, Cancellable
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 Arrow,
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.getCause().
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 Arrow 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 getFinalDamage() can be
exemplified like so:
double damage = this.baseDamage;
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 TargetEntityEvent.getTargetEntity(). The DamageEntityEvent is used
to process the various DamageModifiers of which originate or are
associated with the targeted Entity.
| Modifier and Type | Method and Description |
|---|---|
void |
addDamageModifierBefore(DamageModifier damageModifier,
DoubleUnaryOperator function,
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. |
void |
addModifierAfter(DamageModifier damageModifier,
DoubleUnaryOperator function,
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. |
double |
getBaseDamage()
Gets the "base" damage to deal to the targeted
Entity. |
double |
getDamage(DamageModifier damageModifier)
Gets the damage for the provided
DamageModifier. |
double |
getFinalDamage()
Gets the final damage that will be passed into the proceeding
DamageEntityEvent. |
List<DamageFunction> |
getModifiers()
|
double |
getOriginalDamage()
Gets the original "raw" amount of damage to deal to the targeted
Entity. |
Map<DamageModifier,Double> |
getOriginalDamages()
Gets an
ImmutableMap of all original DamageModifiers
and their associated "modified" damage. |
double |
getOriginalFinalDamage()
Gets the original "final" amount of damage after all original
DamageModifiers are applied to getOriginalDamage(). |
List<DamageFunction> |
getOriginalFunctions()
Gets the original
List of DamageModifier to
DamageFunction that was originally passed into the event. |
double |
getOriginalModifierDamage(DamageModifier damageModifier)
Gets the original damage for the provided
DamageModifier. |
boolean |
isModifierApplicable(DamageModifier damageModifier)
Checks whether the provided
DamageModifier is applicable to the
current available DamageModifiers. |
void |
setBaseDamage(double baseDamage)
Sets the "base" damage to deal to the targeted
Entity. |
void |
setDamage(DamageModifier damageModifier,
DoubleUnaryOperator function)
Sets the provided
DamageFunction to be used for the given
DamageModifier. |
boolean |
willCauseDeath()
Returns whether or not this event will cause the entity to die if the
event is not cancelled.
|
getTargetEntitygetCause, getContext, getSourceisCancelled, setCancelleddouble getOriginalDamage()
Entity.double getOriginalFinalDamage()
DamageModifiers are applied to getOriginalDamage().
The "final" damage is considered the amount of health being lost by
the Entity, if health is tracked.Map<DamageModifier,Double> getOriginalDamages()
ImmutableMap of all original DamageModifiers
and their associated "modified" damage. Note that ordering is not
retained.double getOriginalModifierDamage(DamageModifier damageModifier)
DamageModifier. If
the provided DamageModifier was not included in
getOriginalDamages(), an IllegalArgumentException is
thrown.damageModifier - The original damage modifierList<DamageFunction> getOriginalFunctions()
List of DamageModifier to
DamageFunction that was originally passed into the event.double getBaseDamage()
Entity. The
"base" damage is the original value before passing along the chain of
DamageFunctions for all known DamageModifiers.void setBaseDamage(double baseDamage)
Entity. The
"base" damage is the original value before passing along the chain of
DamageFunctions for all known DamageModifiers.baseDamage - The base damagedouble getFinalDamage()
DamageEntityEvent. The final damage is the end result of the
getBaseDamage() being applied in DoubleUnaryOperator.applyAsDouble(double)
available from all the Tuples of DamageModifier to
DamageFunction in getOriginalFunctions().boolean isModifierApplicable(DamageModifier damageModifier)
DamageModifier is applicable to the
current available DamageModifiers.damageModifier - The damage modifier to checkdouble getDamage(DamageModifier damageModifier)
DamageModifier. Providing that
isModifierApplicable(DamageModifier) returns true,
the cached "damage" for the DamageModifier is returned.damageModifier - The damage modifier to get the damage forvoid setDamage(DamageModifier damageModifier, DoubleUnaryOperator function)
DamageFunction to be used for the given
DamageModifier. If the DamageModifier is already
included in getModifiers(), the DoubleUnaryOperator replaces
the existing function. If there is no Tuple for the
DamageModifier, a new one is created and added to the end
of the list of DoubleUnaryOperators to be applied to the
getBaseDamage().
If needing to create a custom DamageModifier is required,
usage of the DamageModifier.Builder is recommended.
damageModifier - The damage modifierfunction - The function to map to the modifiervoid addDamageModifierBefore(DamageModifier damageModifier, DoubleUnaryOperator function, Set<DamageModifierType> before)
DamageModifier and DoubleUnaryOperator to the
list of modifiers, such that the Set containing
DamageModifierTypes provided in before will appear
after the provided damage modifier.damageModifier - The damage modifier to addfunction - The associated functionbefore - The set containing the modifier types to come after
the provided modifiervoid addModifierAfter(DamageModifier damageModifier, DoubleUnaryOperator function, Set<DamageModifierType> after)
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.damageModifier - The damage modifier to addfunction - The associated functionafter - The set of modifier types to come before the new modifierList<DamageFunction> getModifiers()
Tuples of DamageModifier keyed to
their representative DamageFunctions. All DamageModifiers are
applicable to the entity based on the DamageSource and any
possible invulnerabilities due to the DamageSource.boolean willCauseDeath()
TargetEntityEvent.getTargetEntity() is not a living entity.