Class PetExperience
Pet owns one instance of
this class.
Experience gain flows through addExp(double) overloads, which optionally apply
registered ExperienceModifiers (global, permission-based, or custom), fire a
PetExpEvent, and then recalculate the pet's level. Level changes trigger
PetLevelUpEvent or PetLevelDownEvent as appropriate.
The static damage-map methods (addDamageToEntity(org.bukkit.entity.LivingEntity, org.bukkit.entity.LivingEntity, double), getDamageToEntityPercent(org.bukkit.entity.LivingEntity, org.bukkit.entity.LivingEntity),
etc.) track how much damage each entity has dealt to a victim. This is used by the
experience distribution system to award partial XP proportional to damage contribution
when multiple pets/players assist a kill.
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected final ExperienceCachePre-computed per-level experience thresholds.protected doubleRaw accumulated experience.protected final ExperienceCalculatorThe curve deciding how much each level costs.static final GlobalModifierSingleton global XP modifier applied to all pets (e.g.protected intThe pet's current level.protected doubleExperience needed to reach the next level.protected intHighest level the pet can reach (the level cap).protected final Map<String, ExperienceModifier> Modifiers applied to experience before it is granted.protected final PetThe pet whose experience this tracks. -
Constructor Summary
ConstructorsConstructorDescriptionPetExperience(Pet pet) Creates the experience tracker for the given pet, initializing the calculator and registering the default modifiers (global and permission-based). -
Method Summary
Modifier and TypeMethodDescriptionstatic voidaddDamageToEntity(LivingEntity damager, LivingEntity victim, double damage) Records damage dealt bydamagertovictim.doubleaddExp(double exp) Adds raw experience without applying modifiers.doubleaddExp(double exp, boolean modify) Adds experience, optionally passing it through all registered modifiers first.doubleaddExp(double baseExp, double percent, boolean modify) Awards a percentage of an ALREADY-ROLLED mob XP value, optionally with modifiers.doubleAwards experience based on the given entity's mob-type XP value (looked up viaMonsterExperience).doubleAwards experience based on the given entity's mob-type XP value, optionally applying modifiers.doubleAwards a percentage of the entity's mob-type XP value without modifiers.doubleAwards a percentage of the entity's mob-type XP value, optionally with modifiers.voidaddModifier(String id, ExperienceModifier modifier) Registers (or replaces) a named experience modifier.protected intRecalculates the level by scanning up or down from the current level until the XP thresholds bracket the pet's total XP.static doubleclampExp(double oldExp, double newExp, double maxExp, boolean capGains) Clamps a new XP total.static voidclearDamageMap(LivingEntity victim) Removes all accumulated damage records for the given victim (e.g.doubleReturns the experience gained within the current level (total XP minus the threshold to reach the current level).static doublegetDamageToEntity(LivingEntity damager, LivingEntity victim) Returns the total damage thatdamagerhas dealt tovictim, or0if no damage has been recorded.getDamageToEntityPercent(LivingEntity victim) Returns a map from damager UUID to their damage fraction (0.0 to 1.0) of total tracked damage to the given victim.static doublegetDamageToEntityPercent(LivingEntity damager, LivingEntity victim) Returns the fraction (0.0 to 1.0) of total tracked damage tovictimthat was dealt bydamager.doublegetExp()Raw accumulated experience.doublegetExpByLevel(int level) Returns the cumulative XP required to reach the given level.intgetLevel()The pet's current level.doubleExperience needed to reach the next level.getPet()The pet whose experience this tracks.doubleReturns the total experience required to advance from the current level to the next level (the "progress bar" maximum).protected doublemodifyExp(double exp) Applies all registered experience modifiers to a raw XP value.doubleremoveCurrentExp(double exp) Removes experience from the current level's progress only (will not drop below the current level's XP threshold).doubleremoveExp(double exp) Removes experience from total XP, potentially causing level-down events.removeModifier(String id) Removes a named experience modifier.voidsetExp(double exp) Sets the pet's total experience to an absolute value, firing level-change events if the resulting level differs from the current one.voidsetMaxLevel(int level) Sets the maximum achievable level for this pet.protected doubleupdateExp(double exp, boolean quiet) Core XP mutation method.protected doubleupdateExp(double exp, boolean quiet, boolean capGains) Core XP mutation, seeupdateExp(double, boolean).
-
Field Details
-
GLOBAL_MODIFIER
Singleton global XP modifier applied to all pets (e.g. event multiplier). -
pet
The pet whose experience this tracks. -
level
protected int levelThe pet's current level. -
exp
protected double expRaw accumulated experience. -
maxExp
protected double maxExpExperience needed to reach the next level. -
maxLevel
protected int maxLevelHighest level the pet can reach (the level cap). -
cache
Pre-computed per-level experience thresholds. -
expCalculator
The curve deciding how much each level costs. -
modifier
Modifiers applied to experience before it is granted.
-
-
Constructor Details
-
PetExperience
Creates the experience tracker for the given pet, initializing the calculator and registering the default modifiers (global and permission-based).- Parameters:
pet- the pet that owns this experience instance
-
-
Method Details
-
addDamageToEntity
Records damage dealt bydamagertovictim. The damage is clamped to the victim's current health (to avoid over-counting overkill) and accumulated across multiple hits.- Parameters:
damager- the entity dealing damagevictim- the entity receiving damagedamage- the raw damage amount
-
clearDamageMap
Removes all accumulated damage records for the given victim (e.g. on death).- Parameters:
victim- the entity whose damage tally to forget
-
getDamageToEntity
Returns the total damage thatdamagerhas dealt tovictim, or0if no damage has been recorded.- Parameters:
damager- who dealt the damagevictim- who took it- Returns:
- the damage that damager has dealt to that victim
-
getDamageToEntityPercent
Returns the fraction (0.0 to 1.0) of total tracked damage tovictimthat was dealt bydamager.- Parameters:
damager- who dealt the damagevictim- who took it- Returns:
- that damager's share of the victim's total damage, from 0 to 1
-
getDamageToEntityPercent
Returns a map from damager UUID to their damage fraction (0.0 to 1.0) of total tracked damage to the given victim. Useful for splitting XP rewards proportionally among multiple attackers.- Parameters:
victim- the entity to break down- Returns:
- each damager's share of the total, keyed by UUID
-
modifyExp
protected double modifyExp(double exp) Applies all registered experience modifiers to a raw XP value. Each modifier receives both the running total and the original raw value, allowing both additive and multiplicative adjustments.- Parameters:
exp- the raw experience before modification- Returns:
- the modified experience value
-
addModifier
Registers (or replaces) a named experience modifier.- Parameters:
id- unique identifier for this modifiermodifier- the modifier instance
-
removeModifier
Removes a named experience modifier.- Parameters:
id- the identifier of the modifier to remove- Returns:
- the removed modifier, or
nullif none was registered under that id
-
setMaxLevel
public void setMaxLevel(int level) Sets the maximum achievable level for this pet. The corresponding max XP is calculated on the active curve and stops further gains; XP the pet already holds above it is kept, because it is curve-relative and a curve or cap change must not delete it. The level itself is capped instead.- Parameters:
level- the maximum level (inclusive)
-
setExp
public void setExp(double exp) Sets the pet's total experience to an absolute value, firing level-change events if the resulting level differs from the current one.- Parameters:
exp- the desired total XP
-
addExp
public double addExp(double exp) Adds raw experience without applying modifiers.- Parameters:
exp- the XP to add- Returns:
- the actual amount of XP gained (after event cancellation / clamping)
-
addExp
public double addExp(double exp, boolean modify) Adds experience, optionally passing it through all registered modifiers first.- Parameters:
exp- the base XP to addmodify- iftrue, modifiers are applied before adding- Returns:
- the actual amount of XP gained
-
addExp
Awards experience based on the given entity's mob-type XP value (looked up viaMonsterExperience). Does not apply modifiers.- Parameters:
entity- the killed entity to derive XP from- Returns:
- the actual amount of XP gained
-
addExp
Awards experience based on the given entity's mob-type XP value, optionally applying modifiers.- Parameters:
entity- the killed entity to derive XP frommodify- iftrue, modifiers are applied- Returns:
- the actual amount of XP gained
-
addExp
Awards a percentage of the entity's mob-type XP value without modifiers.- Parameters:
entity- the killed entitypercent- the percentage of the mob's XP to award (0-100)- Returns:
- the actual amount of XP gained
-
addExp
public double addExp(double baseExp, double percent, boolean modify) Awards a percentage of an ALREADY-ROLLED mob XP value, optionally with modifiers.Same arithmetic as
addExp(Entity, int, boolean)-- modifiers first, then the percentage -- but the caller supplies the roll. Mob XP is a range (getRandomExp()), so a caller that has to divide one kill's award between several pets must roll once and hand the same number to each; rolling per pet would hand out different shares of a single kill.- Parameters:
baseExp- the mob's rolled XP valuepercent- the percentage of it to award (0-100), fractional shares allowedmodify- iftrue, modifiers are applied before percentage scaling- Returns:
- the actual amount of XP gained
-
addExp
Awards a percentage of the entity's mob-type XP value, optionally with modifiers.- Parameters:
entity- the killed entitypercent- the percentage of the mob's XP to award (0-100)modify- iftrue, modifiers are applied before percentage scaling- Returns:
- the actual amount of XP gained
-
removeCurrentExp
public double removeCurrentExp(double exp) Removes experience from the current level's progress only (will not drop below the current level's XP threshold).- Parameters:
exp- the amount to remove (clamped to current-level progress)- Returns:
- the actual amount of XP removed (as a negative delta)
-
removeExp
public double removeExp(double exp) Removes experience from total XP, potentially causing level-down events. The removal is clamped so total XP never drops below zero.- Parameters:
exp- the amount to remove- Returns:
- the actual amount of XP removed (as a negative delta)
-
updateExp
protected double updateExp(double exp, boolean quiet) Core XP mutation method. Fires aPetExpEvent(which may be cancelled), updates the stored total XP, recalculates the level, and dispatchesPetLevelUpEventorPetLevelDownEventif the level changed.- Parameters:
exp- the XP delta (positive to gain, negative to lose)quiet- iftrue, level-change events are marked as quiet (suppressing messages to the player)- Returns:
- the actual XP change applied
-
updateExp
protected double updateExp(double exp, boolean quiet, boolean capGains) Core XP mutation, seeupdateExp(double, boolean).- Parameters:
exp- the XP delta (positive to gain, negative to lose)quiet- iftrue, level-change events are marked as quietcapGains- iftrue, gains stop at the max-level XP;falsefor absolute sets such as restoring a stored pet- Returns:
- the actual XP change applied
-
clampExp
public static double clampExp(double oldExp, double newExp, double maxExp, boolean capGains) Clamps a new XP total. Never below zero; whencapGainsis set, a gain may not passmaxExp, but XP the pet already held above it is not cut down.- Parameters:
oldExp- the XP before the changenewExp- the XP after the changemaxExp- the max-level XP on the active curvecapGains- whether gains stop atmaxExp- Returns:
- the clamped XP total
-
calculateLevel
protected int calculateLevel()Recalculates the level by scanning up or down from the current level until the XP thresholds bracket the pet's total XP. Thresholds are resolved (and cached) viagetExpByLevel(int); the upward walk stops at the max level.- Returns:
- the computed level
-
getCurrentExp
public double getCurrentExp()Returns the experience gained within the current level (total XP minus the threshold to reach the current level). This is the "progress bar" value.- Returns:
- experience earned since the current level began
-
getRequiredExp
public double getRequiredExp()Returns the total experience required to advance from the current level to the next level (the "progress bar" maximum). Logs a warning and returnsDouble.MAX_VALUEif consecutive levels share the same XP threshold (misconfigured calculator).- Returns:
- experience still needed to reach the next level
-
getExpByLevel
public double getExpByLevel(int level) Returns the cumulative XP required to reach the given level. Results are cached in theExperienceCache; on a cache miss, theExperienceCalculatoris invoked and the result stored for future lookups.- Parameters:
level- the target level (1-based; level 1 always returns 0)- Returns:
- the total XP threshold for reaching
level
-
getPet
The pet whose experience this tracks.- Returns:
- the pet this tracker belongs to
-
getLevel
public int getLevel()The pet's current level.- Returns:
- the current level
-
getExp
public double getExp()Raw accumulated experience.- Returns:
- the total experience this pet has earned
-
getMaxExp
public double getMaxExp()Experience needed to reach the next level.- Returns:
- the experience the next level requires
-