Package io.artificial.enchantments.internal

Class AttributeModifierHelper

java.lang.Object
io.artificial.enchantments.internal.AttributeModifierHelper
public final class AttributeModifierHelper extends Object
Helper for managing attribute modifiers on entities and items.

Provides pure functions for adding/removing attribute modifiers with proper UUID tracking. All operations are thread-safe and idempotent where possible.

Common attributes:

  • ATTACK_DAMAGE - Melee damage
  • ATTACK_SPEED - Attack cooldown speed
  • ARMOR - Damage reduction
  • ARMOR_TOUGHNESS - Armor effectiveness
  • MAX_HEALTH - Maximum health
  • MOVEMENT_SPEED - Movement speed
  • KNOCKBACK_RESISTANCE - Knockback reduction

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    addItemModifier(@NotNull org.bukkit.inventory.ItemStack item, @NotNull org.bukkit.attribute.Attribute attribute, @NotNull UUID uuid, double amount, org.bukkit.attribute.AttributeModifier.Operation operation, @Nullable org.bukkit.inventory.EquipmentSlot slot)
    Adds an attribute modifier to an item stack.
    static boolean
    addModifier(@NotNull org.bukkit.entity.LivingEntity entity, @NotNull org.bukkit.attribute.Attribute attribute, @NotNull UUID uuid, double amount, org.bukkit.attribute.AttributeModifier.Operation operation)
    Adds a temporary attribute modifier to a living entity.
    static boolean
    applyArmorBonus(@NotNull org.bukkit.entity.LivingEntity entity, @NotNull String enchantmentKey, double armorBonus)
    Applies armor bonus modifier to an entity.
    static boolean
    applyAttackSpeedBonus(@NotNull org.bukkit.entity.LivingEntity entity, @NotNull String enchantmentKey, double speedBonus)
    Applies attack speed modifier to an entity.
    static boolean
    applyDamageBonus(@NotNull org.bukkit.entity.LivingEntity entity, @NotNull String enchantmentKey, double damageBonus)
    Applies attack damage modifier to an entity.
    static boolean
    applyMovementSpeedBonus(@NotNull org.bukkit.entity.LivingEntity entity, @NotNull String enchantmentKey, double speedMultiplier)
    Applies movement speed modifier to an entity.
    static @NotNull UUID
    armorModifierUuid(@NotNull String enchantmentKey)
    Creates a modifier UUID for armor modifiers.
    static @NotNull UUID
    attackSpeedModifierUuid(@NotNull String enchantmentKey)
    Creates a modifier UUID for attack speed modifiers.
    static @NotNull UUID
    damageModifierUuid(@NotNull String enchantmentKey)
    Creates a modifier UUID for damage modifiers.
    static @NotNull UUID
    generateModifierUuid(@NotNull String enchantmentKey, @NotNull String target)
    Generates a unique UUID for attribute modifiers.
    static @NotNull Map<org.bukkit.attribute.Attribute,List<UUID>>
    getActiveModifiers(@NotNull org.bukkit.entity.LivingEntity entity)
    Gets all active modifiers created by this helper on an entity.
    static double
    getBaseValue(@NotNull org.bukkit.entity.LivingEntity entity, @NotNull org.bukkit.attribute.Attribute attribute)
    Gets the base value of an attribute without modifiers.
    static double
    getTotalValue(@NotNull org.bukkit.entity.LivingEntity entity, @NotNull org.bukkit.attribute.Attribute attribute)
    Gets the total value of an attribute including all modifiers.
    static @NotNull UUID
    movementSpeedModifierUuid(@NotNull String enchantmentKey)
    Creates a modifier UUID for movement speed modifiers.
    static int
    removeAllModifiers(@NotNull org.bukkit.entity.LivingEntity entity)
    Removes all modifiers created by this helper from an entity.
    static boolean
    removeItemModifier(@NotNull org.bukkit.inventory.ItemStack item, @NotNull org.bukkit.attribute.Attribute attribute, @NotNull UUID uuid)
    Removes an attribute modifier from an item stack.
    static boolean
    removeModifier(@NotNull org.bukkit.entity.LivingEntity entity, @NotNull org.bukkit.attribute.Attribute attribute, @NotNull UUID uuid)
    Removes an attribute modifier by UUID.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • addModifier

      public static boolean addModifier(@NotNull @NotNull org.bukkit.entity.LivingEntity entity, @NotNull @NotNull org.bukkit.attribute.Attribute attribute, @NotNull @NotNull UUID uuid, double amount, @NotNull org.bukkit.attribute.AttributeModifier.Operation operation)
      Adds a temporary attribute modifier to a living entity.

      If a modifier with the same UUID already exists, it will be removed and replaced with the new value.

      Parameters:
      entity - the entity to modify
      attribute - the attribute to modify
      uuid - unique identifier for this modifier (for tracking/removal)
      amount - the amount to add
      operation - the operation type (ADD_NUMBER, ADD_SCALAR, MULTIPLY_SCALAR_1)
      Returns:
      true if the modifier was applied successfully

    • removeModifier

      public static boolean removeModifier(@NotNull @NotNull org.bukkit.entity.LivingEntity entity, @NotNull @NotNull org.bukkit.attribute.Attribute attribute, @NotNull @NotNull UUID uuid)
      Removes an attribute modifier by UUID.
      Parameters:
      entity - the entity to modify
      attribute - the attribute to modify
      uuid - the UUID of the modifier to remove
      Returns:
      true if a modifier was found and removed

    • removeAllModifiers

      public static int removeAllModifiers(@NotNull @NotNull org.bukkit.entity.LivingEntity entity)
      Removes all modifiers created by this helper from an entity.

      Only removes modifiers whose names start with "artificial_enchantment_"

      Parameters:
      entity - the entity to clean up
      Returns:
      number of modifiers removed

    • getTotalValue

      public static double getTotalValue(@NotNull @NotNull org.bukkit.entity.LivingEntity entity, @NotNull @NotNull org.bukkit.attribute.Attribute attribute)
      Gets the total value of an attribute including all modifiers.
      Parameters:
      entity - the entity to check
      attribute - the attribute to check
      Returns:
      the total attribute value, or 0 if the entity doesn't have the attribute

    • getBaseValue

      public static double getBaseValue(@NotNull @NotNull org.bukkit.entity.LivingEntity entity, @NotNull @NotNull org.bukkit.attribute.Attribute attribute)
      Gets the base value of an attribute without modifiers.
      Parameters:
      entity - the entity to check
      attribute - the attribute to check
      Returns:
      the base attribute value, or 0 if the entity doesn't have the attribute

    • addItemModifier

      public static boolean addItemModifier(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.attribute.Attribute attribute, @NotNull @NotNull UUID uuid, double amount, @NotNull org.bukkit.attribute.AttributeModifier.Operation operation, @Nullable @Nullable org.bukkit.inventory.EquipmentSlot slot)
      Adds an attribute modifier to an item stack.

      Item modifiers persist when the item is held/worn in the specified slot.

      Parameters:
      item - the item to modify
      attribute - the attribute to modify
      uuid - unique identifier for this modifier
      amount - the amount to add
      operation - the operation type
      slot - the equipment slot this modifier applies to
      Returns:
      true if the modifier was applied

    • removeItemModifier

      public static boolean removeItemModifier(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.attribute.Attribute attribute, @NotNull @NotNull UUID uuid)
      Removes an attribute modifier from an item stack.
      Parameters:
      item - the item to modify
      attribute - the attribute to modify
      uuid - the UUID of the modifier to remove
      Returns:
      true if a modifier was found and removed

    • generateModifierUuid

      @NotNull public static @NotNull UUID generateModifierUuid(@NotNull @NotNull String enchantmentKey, @NotNull @NotNull String target)
      Generates a unique UUID for attribute modifiers.

      The UUID is derived from the enchantment key and target to ensure consistent IDs across server restarts.

      Parameters:
      enchantmentKey - the enchantment identifier
      target - the target attribute or context
      Returns:
      a deterministic UUID for the modifier

    • damageModifierUuid

      @NotNull public static @NotNull UUID damageModifierUuid(@NotNull @NotNull String enchantmentKey)
      Creates a modifier UUID for damage modifiers.
      Parameters:
      enchantmentKey - the enchantment identifier
      Returns:
      a deterministic UUID for damage modifiers

    • attackSpeedModifierUuid

      @NotNull public static @NotNull UUID attackSpeedModifierUuid(@NotNull @NotNull String enchantmentKey)
      Creates a modifier UUID for attack speed modifiers.
      Parameters:
      enchantmentKey - the enchantment identifier
      Returns:
      a deterministic UUID for attack speed modifiers

    • armorModifierUuid

      @NotNull public static @NotNull UUID armorModifierUuid(@NotNull @NotNull String enchantmentKey)
      Creates a modifier UUID for armor modifiers.
      Parameters:
      enchantmentKey - the enchantment identifier
      Returns:
      a deterministic UUID for armor modifiers

    • movementSpeedModifierUuid

      @NotNull public static @NotNull UUID movementSpeedModifierUuid(@NotNull @NotNull String enchantmentKey)
      Creates a modifier UUID for movement speed modifiers.
      Parameters:
      enchantmentKey - the enchantment identifier
      Returns:
      a deterministic UUID for movement speed modifiers

    • applyDamageBonus

      public static boolean applyDamageBonus(@NotNull @NotNull org.bukkit.entity.LivingEntity entity, @NotNull @NotNull String enchantmentKey, double damageBonus)
      Applies attack damage modifier to an entity.
      Parameters:
      entity - the entity to modify
      enchantmentKey - the enchantment identifier
      damageBonus - the damage amount to add
      Returns:
      true if applied successfully

    • applyAttackSpeedBonus

      public static boolean applyAttackSpeedBonus(@NotNull @NotNull org.bukkit.entity.LivingEntity entity, @NotNull @NotNull String enchantmentKey, double speedBonus)
      Applies attack speed modifier to an entity.
      Parameters:
      entity - the entity to modify
      enchantmentKey - the enchantment identifier
      speedBonus - the speed amount to add (negative for slower)
      Returns:
      true if applied successfully

    • applyArmorBonus

      public static boolean applyArmorBonus(@NotNull @NotNull org.bukkit.entity.LivingEntity entity, @NotNull @NotNull String enchantmentKey, double armorBonus)
      Applies armor bonus modifier to an entity.
      Parameters:
      entity - the entity to modify
      enchantmentKey - the enchantment identifier
      armorBonus - the armor amount to add
      Returns:
      true if applied successfully

    • applyMovementSpeedBonus

      public static boolean applyMovementSpeedBonus(@NotNull @NotNull org.bukkit.entity.LivingEntity entity, @NotNull @NotNull String enchantmentKey, double speedMultiplier)
      Applies movement speed modifier to an entity.
      Parameters:
      entity - the entity to modify
      enchantmentKey - the enchantment identifier
      speedMultiplier - the speed multiplier (e.g., 0.1 for +10%)
      Returns:
      true if applied successfully

    • getActiveModifiers

      @NotNull public static @NotNull Map<org.bukkit.attribute.Attribute,List<UUID>> getActiveModifiers(@NotNull @NotNull org.bukkit.entity.LivingEntity entity)
      Gets all active modifiers created by this helper on an entity.
      Parameters:
      entity - the entity to check
      Returns:
      map of attribute to list of modifier UUIDs