Class HeadRollEvent


  • public class HeadRollEvent
    extends Event
    Event created by PlayerHeads (4.9.2+) to indicate that a head dropchance roll has occurred and the success/failure has been determined. This event allows third-party plugin authors to analyze and modify drop chance success with all factors considered by PlayerHeads available. If the success of this event is set to false, no head will be dropped. If it is set to true, a head will be dropped. Changing the droprate here does not impact plugin function, so you should use the apply/recalculate methods to update the success or set the success value yourself.
    Since:
    4.9.2-SNAPSHOT
    Author:
    crashdemons (crashenator at gmail.com)
    • Nested Class Summary

    • Constructor Summary

      Constructors 
      Constructor Description
      HeadRollEvent​(Entity killer, Entity target, boolean killerAlwaysBeheads, double originalDropRoll, double originalDropRate)
      Creates the Head dropchance event for PlayerHeads without precalculation, allowing for event-based recalculation.
      HeadRollEvent​(Entity killer, Entity target, boolean killerAlwaysBeheads, double originalDropRoll, double effectiveDropRoll, double originalDropRate, double effectiveDropRate, boolean dropSuccess)
      Creates the Head dropchance event for PlayerHeads with values precalaculated by the plugin.
      HeadRollEvent​(Entity killer, Entity target, boolean killerAlwaysBeheads, double lootingModifier, double originalDropRoll, double effectiveDropRoll, double originalDropRate, double effectiveDropRate, boolean dropSuccess)
      Deprecated.
      HeadRollEvent​(Entity killer, Entity target, boolean killerAlwaysBeheads, double lootingModifier, double slimeModifier, double originalDropRoll, double effectiveDropRoll, double originalDropRate, double effectiveDropRate, boolean dropSuccess)
      Deprecated.
      HeadRollEvent​(Entity killer, Entity target, boolean killerAlwaysBeheads, double lootingModifier, double slimeModifier, double chargedCreeperModifier, double originalDropRoll, double effectiveDropRoll, double originalDropRate, double effectiveDropRate, boolean dropSuccess)
      Deprecated.
    • Constructor Detail

      • HeadRollEvent

        public HeadRollEvent​(Entity killer,
                             Entity target,
                             boolean killerAlwaysBeheads,
                             double originalDropRoll,
                             double originalDropRate)
        Creates the Head dropchance event for PlayerHeads without precalculation, allowing for event-based recalculation. Success is disabled by default. Note: this method does not add any modifier values by default. 5.2.2+ API
        Parameters:
        killer - the Entity beheading another
        target - the Entity being beheaded
        killerAlwaysBeheads - whether the killer has the always-behead permission
        originalDropRoll - the randomized PRNG double droproll value inclusively between 0 to 1. logic was applied (alwaysbehead sets to 0)
        originalDropRate - the configured droprate of the target as a fraction (0.01 = 1%)
        Since:
        5.2.16-SNAPSHOT
      • HeadRollEvent

        public HeadRollEvent​(Entity killer,
                             Entity target,
                             boolean killerAlwaysBeheads,
                             double originalDropRoll,
                             double effectiveDropRoll,
                             double originalDropRate,
                             double effectiveDropRate,
                             boolean dropSuccess)
        Creates the Head dropchance event for PlayerHeads with values precalaculated by the plugin. Note: this method does not add any modifier values by default. 5.2.2+ API
        Parameters:
        killer - the Entity beheading another
        target - the Entity being beheaded
        killerAlwaysBeheads - whether the killer has the always-behead permission
        originalDropRoll - the randomized PRNG double droproll value inclusively between 0 to 1.
        effectiveDropRoll - the modified droproll value after permission logic was applied (alwaysbehead sets to 0)
        originalDropRate - the configured droprate of the target as a fraction (0.01 = 1%)
        effectiveDropRate - the effective droprate of the target as a fraction (0.01 = 1%), as modified by looting.
        dropSuccess - whether the droproll was determined to be initially a successful roll.
        Since:
        5.2.16-SNAPSHOT
      • HeadRollEvent

        @Deprecated
        public HeadRollEvent​(Entity killer,
                             Entity target,
                             boolean killerAlwaysBeheads,
                             double lootingModifier,
                             double slimeModifier,
                             double chargedCreeperModifier,
                             double originalDropRoll,
                             double effectiveDropRoll,
                             double originalDropRate,
                             double effectiveDropRate,
                             boolean dropSuccess)
        Deprecated.
        Creates the Head dropchance event for PlayerHeads. 5.2+ API
        Parameters:
        killer - the Entity beheading another
        target - the Entity being beheaded
        killerAlwaysBeheads - whether the killer has the always-behead permission
        originalDropRoll - the randomized PRNG double droproll value inclusively between 0 to 1.
        slimeModifier - the fraction of the slime/magmacube drop rate that is applicable at this size, modifuing the effective droprate (0.5 is 50% of the base rate). This should be 1.0 when there is no effect or the entity is not a slime.
        lootingModifier - the fractional probability modifier (greater than or equal to 1.0) of looting, as applied by PlayerHeads to the effective droprate.
        chargedCreeperModifier - the multiplier effect that charged creepers have on normal droprates
        effectiveDropRoll - the modified droproll value after permission logic was applied (alwaysbehead sets to 0)
        originalDropRate - the configured droprate of the target as a fraction (0.01 = 1%)
        effectiveDropRate - the effective droprate of the target as a fraction (0.01 = 1%), as modified by looting.
        dropSuccess - whether the droproll was determined to be initially a successful roll.
        Since:
        5.2.0-SNAPSHOT
      • HeadRollEvent

        @Deprecated
        public HeadRollEvent​(Entity killer,
                             Entity target,
                             boolean killerAlwaysBeheads,
                             double lootingModifier,
                             double slimeModifier,
                             double originalDropRoll,
                             double effectiveDropRoll,
                             double originalDropRate,
                             double effectiveDropRate,
                             boolean dropSuccess)
        Deprecated.
        Creates the Head dropchance event for PlayerHeads.
        Parameters:
        killer - the Entity beheading another
        target - the Entity being beheaded
        killerAlwaysBeheads - whether the killer has the always-behead permission
        originalDropRoll - the randomized PRNG double droproll value inclusively between 0 to 1.
        slimeModifier - the fraction of the slime/magmacube drop rate that is applicable at this size, modifuing the effective droprate (0.5 is 50% of the base rate). This should be 1.0 when there is no effect or the entity is not a slime.
        lootingModifier - the fractional probability modifier (greater than or equal to 1.0) of looting, as applied by PlayerHeads to the effective droprate.
        effectiveDropRoll - the modified droproll value after permission logic was applied (alwaysbehead sets to 0)
        originalDropRate - the configured droprate of the target as a fraction (0.01 = 1%)
        effectiveDropRate - the effective droprate of the target as a fraction (0.01 = 1%), as modified by looting.
        dropSuccess - whether the droproll was determined to be initially a successful roll.
        Since:
        5.1.0-SNAPSHOT
      • HeadRollEvent

        @Deprecated
        public HeadRollEvent​(Entity killer,
                             Entity target,
                             boolean killerAlwaysBeheads,
                             double lootingModifier,
                             double originalDropRoll,
                             double effectiveDropRoll,
                             double originalDropRate,
                             double effectiveDropRate,
                             boolean dropSuccess)
        Deprecated.
        Creates the Head dropchance event for PlayerHeads.
        Parameters:
        killer - the Entity beheading another
        target - the Entity being beheaded
        killerAlwaysBeheads - whether the killer has the always-behead permission
        originalDropRoll - the randomized PRNG double droproll value inclusively between 0 to 1.
        lootingModifier - the fractional probability modifier (greater than or equal to 1.0) of looting, as applied by PlayerHeads to the effective droprate.
        effectiveDropRoll - the modified droproll value after permission logic was applied (alwaysbehead sets to 0)
        originalDropRate - the configured droprate of the target as a fraction (0.01 = 1%)
        effectiveDropRate - the effective droprate of the target as a fraction (0.01 = 1%), as modified by looting.
        dropSuccess - whether the droproll was determined to be initially a successful roll.
    • Method Detail

      • getModifiers

        @NotNull
        public Map<String,​DropRateModifier> getModifiers()
        Gets the list of modifiers to the effective droprate. This map will be in order that the modifiers are applied.
        Returns:
        map containing the droprate modifiers by name.
        Since:
        5.2.16-SNAPSHOT
      • applyDropRate

        public void applyDropRate()
        Re-apply the current effective droproll and effective droprate values to make a new determination of the head drop's success. Modifiers are not considered by this method, only the two effective values. Note: if killerAlwaysBeheads is enabled, the effective droproll will be set to 0. This is equivalent to recalculateSuccess(false).
        Since:
        5.2.16-SNAPSHOT
      • applyModifiers

        public void applyModifiers()
        Re-apply all droprate modifiers to the original droprate and recalculate the effective droprate. This method will discard the current effective droprate, if you want to retain the original values, you should copy them before calling this method. Success is not updated by this method.
        Since:
        5.2.16-SNAPSHOT
      • recalculateSuccess

        public void recalculateSuccess()
        Re-apply all factors (droprate modifiers then effective values) to determine suuccess. This method will discard the current effective droprate, if you want to retain the original values, you should copy them before calling this method. This is equivalent to recalculateSuccess(true) or applyModifiers();applyDropRate();
        Since:
        5.2.16-SNAPSHOT
      • recalculateSuccess

        public void recalculateSuccess​(boolean applyModifiers)
        Re-apply all relevant factors (droprate modifiers then effective values) to determine suuccess. This method will discard the current effective droprate (if set), if you want to retain the original values, you should copy them before calling this method. When the applyModifiers is true, this is equivalent to recalculateSuccess() or applyModifiers();applyDropRate(). When the applyModifiers is false, this is equivalent to applyDropRate().
        Parameters:
        applyModifiers - If this is set, the current effective droprate will be discarded and recalculated from modifiers.
        Since:
        5.2.17-SNAPSHOT
      • getModifier

        @Nullable
        public DropRateModifier getModifier​(String modifierName)
        Retrieve the value of a modifier of the effective droprate. Note: this value does not impact calculations or success and is for you to use as a courtesy to other plugins at this point. This method can retrieve both internal and custom plugin modifiers (if the prefix is included).
        Parameters:
        modifierName - the name of the modifier
        Returns:
        the value of the modifier, or null if it is not present.
        Since:
        5.2.16-SNAPSHOT
      • setModifier

        public void setModifier​(String modifierName,
                                DropRateModifier value)
        Deprecated.
        using this method to modify existing modifiers should be avoided - use setCustomModifier to note new ones.
        Sets a note about an internal modifier of the effective droprate. Note: this value does not impact calculations or success unless applyModifiers+applyDropRate or recalculateSuccess is called Note: new modifies are generally applied AFTER other modifiers
        Parameters:
        modifierName - the name of the modifier to set.
        value - the value of the modifier to set
        Since:
        5.2.16-SNAPSHOT
      • setModifiers

        public void setModifiers​(Map<String,​DropRateModifier> entries)
        Deprecated.
        using this method to modify existing modifiers should be avoided - use setCustomModifier to note new ones.
        Replaces notes about an internal modifiers of the effective droprate. Note: this value does not impact calculations or success unless applyModifiers+applyDropRate or recalculateSuccess is called Note: new modifies are generally applied AFTER other modifiers; this method will overwrite existing modifiers.
        Parameters:
        entries - the modifiers to set
        Since:
        5.2.16-SNAPSHOT
      • getCustomModifierName

        public static String getCustomModifierName​(String pluginName,
                                                   String modifierName)
        Constructs the internal name of a custom droprate modifier, provided the name of the plugin and modifier.
        Parameters:
        pluginName - The name of the plugin that added the modifier
        modifierName - The name of the modifier
        Returns:
        the internal name of the modifier;
        Since:
        5.2.16-SNAPSHOT
      • setCustomModifier

        public void setCustomModifier​(Plugin yourPlugin,
                                      String modifierName,
                                      DropRateModifier modifierValue)
        Add or change a note about your custom modifier to the head-roll event. Note: this value does not impact calculations unless applyModifiers+applyDropRate or recalculateSuccess is called.
        Note: the name of the modifier will be prepended with "PluginName:" depending on your plugin's name.
        Note: new modifies are generally applied AFTER other modifiers
        Parameters:
        yourPlugin - the plugin adding the modifier
        modifierName - the name of the modifier, excluding any prefix
        modifierValue - the value of the modifier
        Since:
        5.2.16-SNAPSHOT
      • setCustomModifier

        public void setCustomModifier​(Plugin yourPlugin,
                                      String modifierName,
                                      DropRateModifier modifierValue,
                                      boolean recalculateSuccess)
        Add or change a note about your custom modifier to the head-roll event. Note: this value does not impact calculations unless applyModifiers+applyDropRate or recalculateSuccess is called.
        Note: the name of the modifier will be prepended with "PluginName:" depending on your plugin's name.
        Note: new modifies are generally applied AFTER other modifiers
        Parameters:
        yourPlugin - the plugin adding the modifier
        modifierName - the name of the modifier, excluding any prefix
        modifierValue - the value of the modifier
        recalculateSuccess - whether to force recalculation of success by applying this modifier. Note: this will erase any changes to the effective droprate.
        Since:
        5.2.17-SNAPSHOT
      • getCustomModifier

        public DropRateModifier getCustomModifier​(Plugin yourPlugin,
                                                  String modifierName)
        Gets a custom (plugin-added) modifier to the head-roll event. Note: this value does not impact calculations or success and is for you to use as a courtesy to other plugins at this point. Note: the name of the modifier will be prepended with "PluginName:" depending on your plugin's name.
        Parameters:
        yourPlugin - the plugin which added the modifier
        modifierName - the name of the modifier, excluding any prefix
        Returns:
        the value of the modifier, or the null if it is not found.
        Since:
        5.2.16-SNAPSHOT
      • getCustomModifier

        public DropRateModifier getCustomModifier​(String yourPluginName,
                                                  String modifierName)
        Gets a custom (plugin-added) modifier to the head-roll event. Note: this value does not impact calculations or success and is for you to use as a courtesy to other plugins at this point. Note: the name of the modifier will be prepended with "PluginName:" depending on your plugin's name.
        Parameters:
        yourPluginName - the plugin name which added the modifier
        modifierName - the name of the modifier, excluding any prefix
        Returns:
        the value of the modifier, or the null if it is not found.
        Since:
        5.2.16-SNAPSHOT
      • getChargedCreeperModifier

        @NotNull
        public double getChargedCreeperModifier()
        Deprecated.
        use getModifier("chargedcreeper") instead
        Gets the charged creeper modifier (multiplier) that modified the effective droprate. Generally this is 1 (no effect) when the mob was not detected to be killed by a charged creeper. 5.2+ API
        Returns:
        the multiplier
        Since:
        5.2.0-SNAPSHOT
        See Also:
        getModifier(java.lang.String)
      • getSlimeModifier

        @NotNull
        public double getSlimeModifier()
        Deprecated.
        use getModifier("slime") instead
        Gets the slime/magmacube size modifier (multiplier) that modified the effective droprate. Generally this is 1 (no effect) when not a slime.
        Returns:
        the looting modifier
        Since:
        5.1.0-SNAPSHOT
        See Also:
        getModifier(java.lang.String)
      • getLootingModifier

        public double getLootingModifier()
        Deprecated.
        use getModifier("looting") instead
        Gets the effective looting modifier (multiplier) that modified the effective droprate. Generally this is 1 (no effect) or greater. Note: lootingmodifier = (1 + Config_lootingrate * Entity_Looting_Enchantment_Level)
        Returns:
        the looting modifier
        See Also:
        getModifier(java.lang.String)
      • getKiller

        public Entity getKiller()
        Get the Killer's entity that may have done the beheading.
        Returns:
        the entity of the killer, or null if the killer was a mob.
      • getTarget

        public Entity getTarget()
        Get the Target's entity that may have been beheaded
        Returns:
        the entity of the target
      • getKillerAlwaysBeheads

        public boolean getKillerAlwaysBeheads()
        Gets whether the killer was configured to always behead this type of target. Note: this may differ on whether the target was a player or mob. If this is true, the effective droproll may have been set to 0 to force success.
        Returns:
        Whether the killer was configured to always behead
      • getOriginalDropRoll

        public double getOriginalDropRoll()
        Gets the original PRNG-generated random value of the drop roll, uniform between 0 and 1 inclusively. When this value is lower than the droprate value by chance, the roll is considered successful.
        Returns:
        the drop roll value in the range [0,1]
      • setEffectiveDropRoll

        public void setEffectiveDropRoll​(double effectiveRoll)
        Sets the effective droproll value for the event. Note: this value will not impact the success value or calculations unless applyDropRate() or recalculateSuccess() is called.
        Parameters:
        effectiveRoll - the value between 0.0 and 1.0 to use as the drop roll.
        Since:
        5.2.16-SNAPSHOT
      • setEffectiveDropRate

        public void setEffectiveDropRate​(double effectiveRate)
        Deprecated.
        this value is very likely to be overwritten by other plugins (or applyModifiers/recalculateSuccess) - use setCustomModifier instead.
        Sets the effective droprate value for the event. Note: this value will be overwritten by applyModifiers and recalculateSuccess methods and does not impact the success of the event unless you run applyDropRate(). Since other plugins are likely to overwrite this change, you are strongly recommended to use a Modifier instead (which is not likely to be erased) to get the result you want.
        Parameters:
        effectiveRate - the effective droprate/fractional-chance value to set (0.0-1.0 inclusive)
        Since:
        5.2.16-SNAPSHOT
      • getEffectiveDropRoll

        public double getEffectiveDropRoll()
        Gets the effective drop roll value after modification by PlayerHeads. The droproll will normally be reflected by the original random droproll, except if the killer always beheads, then this may be 0. If this is below the droprate, the roll would have been determined to be a success.
        Returns:
        the effective drop roll.
        See Also:
        getOriginalDropRoll()
      • getOriginalDropRate

        public double getOriginalDropRate()
        Gets the configured droprate for the target as a fractional probability, unmodified.
        Returns:
        the droprate
      • getEffectiveDropRate

        public double getEffectiveDropRate()
        Gets the configured droprate for the target as a fractional probability, after modification by looting and slime size modifier. Note: effectiveDroprate = originalDropRate * lootingModifier * slimeModifier.
        Returns:
        the droprate
      • getDropSuccess

        public boolean getDropSuccess()
        Whether the effective drop roll was determined to be a success.
        Returns:
        the success of the drop roll
      • setDropSuccess

        public void setDropSuccess​(boolean value)
        Sets whether the drop roll should be considered a success.
        Parameters:
        value - whether the head drop should succeed or fail.
      • succeeded

        public boolean succeeded()
        Whether the effective drop roll was determined to be a success. Alias of getDropSuccess
        Returns:
        the success of the drop roll
        See Also:
        getDropSuccess()
      • getHandlers

        public HandlerList getHandlers()
        Get a list of handlers for the event.
        Specified by:
        getHandlers in class Event
        Returns:
        a list of handlers for the event
      • getHandlerList

        public static HandlerList getHandlerList()
        Get a list of handlers for the event.
        Returns:
        a list of handlers for the event