API Documentation/Example 04: Capturing and modifying droprates

Since version 4.9.2+, an event has been supplied by PlayerHeads named HeadRollEvent which contains information about the droprate and droproll and expected head drop success. By capturing this event you can modify droprates and success as you please.  By default, drops succeeds if the "roll" value is within (below) the droprate value - the value you set of the success controls whether a head will be dropped.

Note: "Effective" values indicate values that already have inbuilt modifiers applied to them, while "original" values rely on configured rates.


Changing droprates (4.9.2+)

Modification in early versions relies mostly on setting the success value of the event, however it's possible to read the original and effect dropRate/dropRoll values, as well as modifiers like with the method getLootingModifier, which can allow you to make an informed decision about the success.


The below example modifies the droprate of all heads with a 5% proportional buff.

public void onRoll(HeadRollEvent event){
double dropRoll = event.getEffectiveDropRoll();
double dropRate = event.getEffectiveDropRate();
double newDropRate = droprate * (1 + 0.05); //increase the droprate by 5% of the existing rate
event.setSuccess( dropRoll < newDropRate ); //update the succcess of the event

Changing droprates in 5.3 - 5.3 changes have been tabled at this time

In 5.3, it will be possible to both indicate changes in the 'effective' values by your plugin, as well as to register your own modifiers and recalculate the droprate without upsetting other plugins.

In addition to having access to setEffectiveDropRate you now can access setCustomModifier which will make modifying droprates much easier.  Other methods are available for accessing or retrieving all the modifiers affecting an event.


The following example also applies a 5% proportional buff to all head drops, but allows other plugins to know about it and not override your modifier by accident.

DropRateModifier modifier = new DropRateModifier(DropRateModifierType.ADD_MULTIPLE, 0.05); 
public void onRoll(HeadRollEvent event){
event.setCustomModifier(yourPlugin, "mybuff", modifier);//register your named modifier
event.recalculateSuccess();//update the effective droprate and determine success

 If you would like to apply your your modifier but not update the success (to test, perhaps), you can also use the applyModifiers() method.