Interface DamageEntityEvent
-
- All Superinterfaces:
Cancellable
,Event
- All Known Implementing Classes:
AbstractDamageEntityEvent
public interface DamageEntityEvent extends Event, Cancellable
Represents the base event for when anEntity
is being "attacked". The uniqueness of this event is that allDamageSource
s 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, theDamageEntityEvent
can be summarized as so:An
ArrowEntity
, that was shot by aSkeleton
, with an enchantedItemTypes.BOW
ItemStack
, when theWorld
Difficulty
was set toDifficulties.HARD
, will deal possibly "5" damage to anyEntity
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 particularDamageType
, has no static finalized amount of damage to deal to a particularEntity
. To properly represent this, aDamageSource
has various "states" such as:DamageSource.isAbsolute()
, orDamageSource.isBypassingArmor()
. Quite simply, theDamageSource
will always be the "first" element within aCause
that can be retrieved fromEvent.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 anotherEntity
is considered a "team member" to the attackingEntity
, the "team member" may be a second element within theCause
. The same can be said if anArrowEntity
was shot from aDispenser
that was triggered by aPlayer
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 aDamageFunction
that are applied to the "base" damage. Given thatCause
has a unique capability of storing any and everyObject
willing to be passed into it, we can easily represent these "sources" of "modifiers" in aCause
. Now, knowning the "source" will not provide enough information, so aDamageModifierType
is provided with aDamageModifier
to paint the fullest picture of "explaining" theDamageModifier
as to why it is present, and why it is "modifying" the "base" damage. Finally, we can associate aDamageModifier
with aDamageFunction
that is passed the current "damage" intoDoubleUnaryOperator.applyAsDouble(double)
, being added to the current "damage". After allDamageModifier
DamageFunction
s are "applied", the overall "damage" is now the final damage to actually throw aDamageEntityEvent
.Note that due to the mechanics of the game,
DamageModifier
s are always ordered in the order of which they apply their modifier onto the "base" damage. The implementation forfinalDamage()
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
DamageFunction
s by callingsetDamage(DamageModifier, DoubleUnaryOperator)
at which point the end result may be undefined. However, if a customDamageModifier
that aims to alter the "final" damage based on some custom circumstances, callingsetDamage(DamageModifier, DoubleUnaryOperator)
on a newDamageModifier
instance, easily created from theDamageModifier.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 anyDamageModifier
s associated with theentity()
. TheDamageEntityEvent
is used to process the variousDamageModifier
s of which originate or are associated with the targetedEntity
.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
addDamageModifierBefore(DamageModifier damageModifier, DoubleUnaryOperator function, Set<DamageModifierType> before)
Adds the providedDamageModifier
andDoubleUnaryOperator
to the list of modifiers, such that theSet
containingDamageModifierType
s provided inbefore
will appear after the provided damage modifier.void
addModifierAfter(DamageModifier damageModifier, DoubleUnaryOperator function, Set<DamageModifierType> after)
Adds the providedDamageModifier
andDoubleUnaryOperator
to the list of modifiers, such that the modifier will appear in order after any current modifiers whose type are included in the providedSet
ofDamageModifierType
s.double
baseDamage()
Gets the "base" damage to deal to the targetedEntity
.double
damage(DamageModifier damageModifier)
Gets the damage for the providedDamageModifier
.Entity
entity()
Gets theEntity
.double
finalDamage()
Gets the final damage that will be passed into the proceedingDamageEntityEvent
.boolean
isModifierApplicable(DamageModifier damageModifier)
Checks whether the providedDamageModifier
is applicable to the current availableDamageModifier
s.List<DamageFunction>
modifiers()
double
originalDamage()
Gets the original "raw" amount of damage to deal to the targetedEntity
.Map<DamageModifier,Double>
originalDamages()
Gets anImmutableMap
of all originalDamageModifier
s and their associated "modified" damage.double
originalFinalDamage()
Gets the original "final" amount of damage after all originalDamageModifier
s are applied tooriginalDamage()
.List<DamageFunction>
originalFunctions()
Gets the originalList
ofDamageModifier
toDamageFunction
that was originally passed into the event.double
originalModifierDamage(DamageModifier damageModifier)
Gets the original damage for the providedDamageModifier
.void
setBaseDamage(double baseDamage)
Sets the "base" damage to deal to the targetedEntity
.void
setDamage(DamageModifier damageModifier, DoubleUnaryOperator function)
Sets the providedDamageFunction
to be used for the givenDamageModifier
.boolean
willCauseDeath()
Returns whether or not this event will cause the entity to die if the event is not cancelled.-
Methods inherited from interface org.spongepowered.api.event.Cancellable
isCancelled, setCancelled
-
-
-
-
Method Detail
-
originalDamage
double originalDamage()
Gets the original "raw" amount of damage to deal to the targetedEntity
.- Returns:
- The original "raw" damage
-
originalFinalDamage
double originalFinalDamage()
Gets the original "final" amount of damage after all originalDamageModifier
s are applied tooriginalDamage()
. The "final" damage is considered the amount of health being lost by theEntity
, if health is tracked.- Returns:
- The final amount of damage to originally deal
-
originalDamages
Map<DamageModifier,Double> originalDamages()
Gets anImmutableMap
of all originalDamageModifier
s 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 providedDamageModifier
. If the providedDamageModifier
was not included inoriginalDamages()
, anIllegalArgumentException
is thrown.- Parameters:
damageModifier
- The original damage modifier- Returns:
- The original damage change
-
originalFunctions
List<DamageFunction> originalFunctions()
Gets the originalList
ofDamageModifier
toDamageFunction
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 targetedEntity
. The "base" damage is the original value before passing along the chain ofDamageFunction
s for all knownDamageModifier
s.- Returns:
- The base damage
-
setBaseDamage
void setBaseDamage(double baseDamage)
Sets the "base" damage to deal to the targetedEntity
. The "base" damage is the original value before passing along the chain ofDamageFunction
s for all knownDamageModifier
s.- Parameters:
baseDamage
- The base damage
-
finalDamage
double finalDamage()
Gets the final damage that will be passed into the proceedingDamageEntityEvent
. The final damage is the end result of thebaseDamage()
being applied inDoubleUnaryOperator.applyAsDouble(double)
available from all theTuple
s ofDamageModifier
toDamageFunction
inoriginalFunctions()
.- Returns:
- The final damage to deal
-
isModifierApplicable
boolean isModifierApplicable(DamageModifier damageModifier)
Checks whether the providedDamageModifier
is applicable to the current availableDamageModifier
s.- Parameters:
damageModifier
- The damage modifier to check- Returns:
- True if the damage modifier is relevant to this event
-
damage
double damage(DamageModifier damageModifier)
Gets the damage for the providedDamageModifier
. Providing thatisModifierApplicable(DamageModifier)
returnstrue
, the cached "damage" for theDamageModifier
is returned.- Parameters:
damageModifier
- The damage modifier to get the damage for- Returns:
- The modifier
-
setDamage
void setDamage(DamageModifier damageModifier, DoubleUnaryOperator function)
Sets the providedDamageFunction
to be used for the givenDamageModifier
. If theDamageModifier
is already included inmodifiers()
, theDoubleUnaryOperator
replaces the existing function. If there is noTuple
for theDamageModifier
, a new one is created and added to the end of the list ofDoubleUnaryOperator
s to be applied to thebaseDamage()
.If needing to create a custom
DamageModifier
is required, usage of theDamageModifier.Builder
is recommended.- Parameters:
damageModifier
- The damage modifierfunction
- The function to map to the modifier
-
addDamageModifierBefore
void addDamageModifierBefore(DamageModifier damageModifier, DoubleUnaryOperator function, Set<DamageModifierType> before)
Adds the providedDamageModifier
andDoubleUnaryOperator
to the list of modifiers, such that theSet
containingDamageModifierType
s provided inbefore
will appear after the provided damage modifier.- Parameters:
damageModifier
- The damage modifier to addfunction
- The associated functionbefore
- The set containing the modifier types to come after the provided modifier
-
addModifierAfter
void addModifierAfter(DamageModifier damageModifier, DoubleUnaryOperator function, Set<DamageModifierType> after)
Adds the providedDamageModifier
andDoubleUnaryOperator
to the list of modifiers, such that the modifier will appear in order after any current modifiers whose type are included in the providedSet
ofDamageModifierType
s.- Parameters:
damageModifier
- The damage modifier to addfunction
- The associated functionafter
- The set of modifier types to come before the new modifier
-
modifiers
List<DamageFunction> modifiers()
Gets a list of simpleTuple
s ofDamageModifier
keyed to their representativeDamageFunction
s. AllDamageModifier
s are applicable to the entity based on theDamageSource
and any possible invulnerabilities due to theDamageSource
.- Returns:
- A list of damage modifiers to functions
-
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 ifentity()
is not a living entity.- Returns:
- Whether the entity will die
-
-