Class PetExperience

java.lang.Object
de.Keyle.MyPet.api.skill.PetExperience

public class PetExperience extends Object
Manages a pet's experience points, level progression, and the damage-tracking maps used to attribute kills for XP distribution. Each 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

    Fields
    Modifier and Type
    Field
    Description
    protected final ExperienceCache
    Pre-computed per-level experience thresholds.
    protected double
    Raw accumulated experience.
    protected final ExperienceCalculator
    The curve deciding how much each level costs.
    static final GlobalModifier
    Singleton global XP modifier applied to all pets (e.g.
    protected int
    The pet's current level.
    protected double
    Experience needed to reach the next level.
    protected int
    Highest level the pet can reach (the level cap).
    protected final Map<String,ExperienceModifier>
    Modifiers applied to experience before it is granted.
    protected final Pet
    The pet whose experience this tracks.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Creates the experience tracker for the given pet, initializing the calculator and registering the default modifiers (global and permission-based).
  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    addDamageToEntity(LivingEntity damager, LivingEntity victim, double damage)
    Records damage dealt by damager to victim.
    double
    addExp(double exp)
    Adds raw experience without applying modifiers.
    double
    addExp(double exp, boolean modify)
    Adds experience, optionally passing it through all registered modifiers first.
    double
    addExp(double baseExp, double percent, boolean modify)
    Awards a percentage of an ALREADY-ROLLED mob XP value, optionally with modifiers.
    double
    addExp(Entity entity)
    Awards experience based on the given entity's mob-type XP value (looked up via MonsterExperience).
    double
    addExp(Entity entity, boolean modify)
    Awards experience based on the given entity's mob-type XP value, optionally applying modifiers.
    double
    addExp(Entity entity, int percent)
    Awards a percentage of the entity's mob-type XP value without modifiers.
    double
    addExp(Entity entity, int percent, boolean modify)
    Awards a percentage of the entity's mob-type XP value, optionally with modifiers.
    void
    Registers (or replaces) a named experience modifier.
    protected int
    Recalculates the level by scanning up or down from the current level until the XP thresholds bracket the pet's total XP.
    static double
    clampExp(double oldExp, double newExp, double maxExp, boolean capGains)
    Clamps a new XP total.
    static void
    Removes all accumulated damage records for the given victim (e.g.
    double
    Returns the experience gained within the current level (total XP minus the threshold to reach the current level).
    static double
    Returns the total damage that damager has dealt to victim, or 0 if no damage has been recorded.
    static Map<UUID,Double>
    Returns a map from damager UUID to their damage fraction (0.0 to 1.0) of total tracked damage to the given victim.
    static double
    Returns the fraction (0.0 to 1.0) of total tracked damage to victim that was dealt by damager.
    double
    Raw accumulated experience.
    double
    getExpByLevel(int level)
    Returns the cumulative XP required to reach the given level.
    int
    The pet's current level.
    double
    Experience needed to reach the next level.
    The pet whose experience this tracks.
    double
    Returns the total experience required to advance from the current level to the next level (the "progress bar" maximum).
    protected double
    modifyExp(double exp)
    Applies all registered experience modifiers to a raw XP value.
    double
    removeCurrentExp(double exp)
    Removes experience from the current level's progress only (will not drop below the current level's XP threshold).
    double
    removeExp(double exp)
    Removes experience from total XP, potentially causing level-down events.
    Removes a named experience modifier.
    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.
    void
    setMaxLevel(int level)
    Sets the maximum achievable level for this pet.
    protected double
    updateExp(double exp, boolean quiet)
    Core XP mutation method.
    protected double
    updateExp(double exp, boolean quiet, boolean capGains)
    Core XP mutation, see updateExp(double, boolean).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • GLOBAL_MODIFIER

      public static final GlobalModifier GLOBAL_MODIFIER
      Singleton global XP modifier applied to all pets (e.g. event multiplier).
    • pet

      protected final Pet pet
      The pet whose experience this tracks.
    • level

      protected int level
      The pet's current level.
    • exp

      protected double exp
      Raw accumulated experience.
    • maxExp

      protected double maxExp
      Experience needed to reach the next level.
    • maxLevel

      protected int maxLevel
      Highest level the pet can reach (the level cap).
    • cache

      protected final ExperienceCache cache
      Pre-computed per-level experience thresholds.
    • expCalculator

      protected final ExperienceCalculator expCalculator
      The curve deciding how much each level costs.
    • modifier

      protected final Map<String,ExperienceModifier> modifier
      Modifiers applied to experience before it is granted.
  • Constructor Details

    • PetExperience

      public PetExperience(Pet pet)
      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

      public static void addDamageToEntity(LivingEntity damager, LivingEntity victim, double damage)
      Records damage dealt by damager to victim. 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 damage
      victim - the entity receiving damage
      damage - the raw damage amount
    • clearDamageMap

      public static void clearDamageMap(LivingEntity victim)
      Removes all accumulated damage records for the given victim (e.g. on death).
      Parameters:
      victim - the entity whose damage tally to forget
    • getDamageToEntity

      public static double getDamageToEntity(LivingEntity damager, LivingEntity victim)
      Returns the total damage that damager has dealt to victim, or 0 if no damage has been recorded.
      Parameters:
      damager - who dealt the damage
      victim - who took it
      Returns:
      the damage that damager has dealt to that victim
    • getDamageToEntityPercent

      public static double getDamageToEntityPercent(LivingEntity damager, LivingEntity victim)
      Returns the fraction (0.0 to 1.0) of total tracked damage to victim that was dealt by damager.
      Parameters:
      damager - who dealt the damage
      victim - who took it
      Returns:
      that damager's share of the victim's total damage, from 0 to 1
    • getDamageToEntityPercent

      public static Map<UUID,Double> 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. 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

      public void addModifier(String id, ExperienceModifier modifier)
      Registers (or replaces) a named experience modifier.
      Parameters:
      id - unique identifier for this modifier
      modifier - the modifier instance
    • removeModifier

      public ExperienceModifier removeModifier(String id)
      Removes a named experience modifier.
      Parameters:
      id - the identifier of the modifier to remove
      Returns:
      the removed modifier, or null if 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 add
      modify - if true, modifiers are applied before adding
      Returns:
      the actual amount of XP gained
    • addExp

      public double addExp(Entity entity)
      Awards experience based on the given entity's mob-type XP value (looked up via MonsterExperience). Does not apply modifiers.
      Parameters:
      entity - the killed entity to derive XP from
      Returns:
      the actual amount of XP gained
    • addExp

      public double addExp(Entity entity, boolean modify)
      Awards experience based on the given entity's mob-type XP value, optionally applying modifiers.
      Parameters:
      entity - the killed entity to derive XP from
      modify - if true, modifiers are applied
      Returns:
      the actual amount of XP gained
    • addExp

      public double addExp(Entity entity, int percent)
      Awards a percentage of the entity's mob-type XP value without modifiers.
      Parameters:
      entity - the killed entity
      percent - 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 value
      percent - the percentage of it to award (0-100), fractional shares allowed
      modify - if true, modifiers are applied before percentage scaling
      Returns:
      the actual amount of XP gained
    • addExp

      public double addExp(Entity entity, int percent, boolean modify)
      Awards a percentage of the entity's mob-type XP value, optionally with modifiers.
      Parameters:
      entity - the killed entity
      percent - the percentage of the mob's XP to award (0-100)
      modify - if true, 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 a PetExpEvent (which may be cancelled), updates the stored total XP, recalculates the level, and dispatches PetLevelUpEvent or PetLevelDownEvent if the level changed.
      Parameters:
      exp - the XP delta (positive to gain, negative to lose)
      quiet - if true, 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, see updateExp(double, boolean).
      Parameters:
      exp - the XP delta (positive to gain, negative to lose)
      quiet - if true, level-change events are marked as quiet
      capGains - if true, gains stop at the max-level XP; false for 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; when capGains is set, a gain may not pass maxExp, but XP the pet already held above it is not cut down.
      Parameters:
      oldExp - the XP before the change
      newExp - the XP after the change
      maxExp - the max-level XP on the active curve
      capGains - whether gains stop at maxExp
      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) via getExpByLevel(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 returns Double.MAX_VALUE if 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 the ExperienceCache; on a cache miss, the ExperienceCalculator is 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

      public Pet 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