Package net.pottercraft.ollivanders2.item.enchantment

Class EnchantedItems

java.lang.Object
net.pottercraft.ollivanders2.item.enchantment.EnchantedItems
All Implemented Interfaces:
org.bukkit.event.Listener
public class EnchantedItems extends Object implements org.bukkit.event.Listener
Manager for enchanted items and their magical properties.

Enchantments are magical effects applied to items using NBT (Named Binary Tag) data stored in item metadata. This class handles:

  • Creating and tracking enchanted items with unique identifiers
  • Storing enchantment metadata (type, magnitude, arguments) as NBT tags
  • Retrieving enchantment objects from items
  • Handling enchantment event listeners (pickup, drop, despawn, item held)
  • Managing cursed item detection with level-based awareness

Enchantments are stored as NBT tags on ItemStack metadata, allowing them to persist across server restarts and item operations. Each enchantment is cached by its unique ID for efficient event handling.

Examples: broom flight (VOLATUS), port keys (PORTUS), item duplication (GEMINO), concealment (CELATUM).

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static org.bukkit.NamespacedKey
    enchantmentArgs
    Namespace key for storing enchantment arguments in item NBT tags.
    static org.bukkit.NamespacedKey
    enchantmentID
    Namespace key for storing enchantment ID in item NBT tags.
    static org.bukkit.NamespacedKey
    enchantmentMagnitude
    Namespace key for storing enchantment magnitude in item NBT tags.
    static org.bukkit.NamespacedKey
    enchantmentType
    Namespace key for storing enchantment type in item NBT tags.

  • Constructor Summary

    Constructors
    Constructor
    Description
    EnchantedItems(@NotNull Ollivanders2 plugin)
    Constructor for creating a new EnchantedItems manager.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addEnchantedItem(@NotNull org.bukkit.entity.Item item, @NotNull ItemEnchantmentType eType, int magnitude, @Nullable String args)
    Apply an enchantment to an Item entity in the world.
    void
    addEnchantedItem(@NotNull org.bukkit.inventory.ItemStack itemStack, @NotNull ItemEnchantmentType eType, int magnitude, @NotNull String eid, @Nullable String args)
    Apply an enchantment to an ItemStack and register it in the enchantment cache.
    static boolean
    areBroomsEnabled()
    Check if broomstick enchantments are enabled in the plugin configuration.
    @Nullable Enchantment
    createEnchantment(@NotNull String eType, @NotNull Integer magnitude, @Nullable String args)
    Create an Enchantment object from type, magnitude, and arguments.
    @Nullable Enchantment
    getEnchantment(@NotNull org.bukkit.inventory.ItemStack itemStack)
    Get the Enchantment object for an ItemStack.
    @Nullable String
    getEnchantmentArgs(@NotNull org.bukkit.inventory.ItemStack itemStack)
    Get the optional arguments for an enchantment from an ItemStack.
    @Nullable String
    getEnchantmentID(@NotNull org.bukkit.entity.Item item)
    Get the unique ID of an enchantment from an Item entity.
    @Nullable String
    getEnchantmentID(@NotNull org.bukkit.inventory.ItemStack itemStack)
    Get the unique ID of an enchantment from an ItemStack.
    @Nullable Integer
    getEnchantmentMagnitude(@NotNull org.bukkit.inventory.ItemStack itemStack)
    Get the enchantment magnitude from an ItemStack.
    @Nullable ItemEnchantmentType
    getEnchantmentType(@NotNull org.bukkit.inventory.ItemStack itemStack)
    Get the enchantment type enum from an ItemStack.
    @Nullable String
    getEnchantmentTypeKey(@NotNull org.bukkit.inventory.ItemStack itemStack)
    Get the enchantment type string from an ItemStack's NBT tags.
    boolean
    isCursed(@NotNull org.bukkit.entity.Item item)
    Check if an Item entity is cursed.
    boolean
    isCursed(@NotNull org.bukkit.inventory.ItemStack itemStack)
    Check if an ItemStack is cursed.
    boolean
    isCursedLevelBased(@NotNull org.bukkit.entity.Item item, @NotNull MagicLevel level)
    Check if an Item is cursed and if the curse can be detected by the given magic level.
    boolean
    isEnchanted(@NotNull org.bukkit.entity.Item item)
    Check if an Item entity has an enchantment applied.
    boolean
    isEnchanted(@NotNull org.bukkit.inventory.ItemStack itemStack)
    Check if an ItemStack has an enchantment applied.
    void
    onEnable()
    Initialize enchantment configuration when the plugin is enabled.
    void
    onEntityPickupItem(@NotNull org.bukkit.event.entity.EntityPickupItemEvent event)
    Handle entity pickup events for enchanted items.
    void
    onInventoryItemPickup(@NotNull org.bukkit.event.inventory.InventoryPickupItemEvent event)
    Handle inventory pickup events for enchanted items.
    void
    onItemDespawn(@NotNull org.bukkit.event.entity.ItemDespawnEvent event)
    Handle item despawn events for enchanted items.
    void
    onItemDrop(@NotNull org.bukkit.event.player.PlayerDropItemEvent event)
    Handle item drop events for enchanted items.
    void
    onItemHeld(@NotNull org.bukkit.event.player.PlayerItemHeldEvent event)
    Handle item held events (hotbar slot changes) for enchanted items.
    @NotNull org.bukkit.inventory.ItemStack
    removeEnchantment(@NotNull org.bukkit.entity.Item enchantedItem)
    Remove an enchantment from an Item entity.
    @NotNull org.bukkit.inventory.ItemStack
    removeEnchantment(@NotNull org.bukkit.inventory.ItemStack enchantedItemStack)
    Remove an enchantment from an ItemStack completely.
    static org.bukkit.inventory.ItemStack
    removeEnchantmentNBT(org.bukkit.inventory.ItemStack enchantedItemStack)
    Remove enchantment NBT tags from an ItemStack without affecting the cache.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • enchantmentType

      public static org.bukkit.NamespacedKey enchantmentType
      Namespace key for storing enchantment type in item NBT tags.

      Stores the ItemEnchantmentType enum name as a string (e.g., "GEMINO", "VOLATUS", "PORTUS").

    • enchantmentMagnitude

      public static org.bukkit.NamespacedKey enchantmentMagnitude
      Namespace key for storing enchantment magnitude in item NBT tags.

      Stores the power level of the enchantment as an integer (1 or greater).

    • enchantmentID

      public static org.bukkit.NamespacedKey enchantmentID
      Namespace key for storing enchantment ID in item NBT tags.

      Stores the unique identifier (typically a UUID string) used to look up the enchantment in the cache.

    • enchantmentArgs

      public static org.bukkit.NamespacedKey enchantmentArgs
      Namespace key for storing enchantment arguments in item NBT tags.

      Stores optional enchantment-specific configuration arguments as a string (e.g., PORTUS destination coordinates).

  • Constructor Details

    • EnchantedItems

      public EnchantedItems(@NotNull @NotNull Ollivanders2 plugin)
      Constructor for creating a new EnchantedItems manager.

      Initializes the enchantment system and sets up the NamespacedKey instances used to store enchantment metadata in item NBT tags. The keys use the plugin as their namespace to avoid conflicts with other plugins.

      Parameters:
      plugin - the Ollivanders2 plugin instance providing access to configuration and logging

  • Method Details

    • onEnable

      public void onEnable()
      Initialize enchantment configuration when the plugin is enabled.

      Loads configuration settings from the plugin's config file, such as whether broomstick items should be enabled. This method is called once during plugin startup.

    • addEnchantedItem

      public void addEnchantedItem(@NotNull @NotNull org.bukkit.entity.Item item, @NotNull @NotNull ItemEnchantmentType eType, int magnitude, @Nullable @Nullable String args)
      Apply an enchantment to an Item entity in the world.

      This convenience method applies an enchantment to a dropped Item entity by delegating to addEnchantedItem(ItemStack, ItemEnchantmentType, int, String, String) using the item's unique ID as the enchantment ID.

      Parameters:
      item - the item entity to enchant
      eType - the type of enchantment to apply
      magnitude - the power level of the enchantment (1+)
      args - optional enchantment-specific arguments (null if not needed)

    • addEnchantedItem

      public void addEnchantedItem(@NotNull @NotNull org.bukkit.inventory.ItemStack itemStack, @NotNull @NotNull ItemEnchantmentType eType, int magnitude, @NotNull @NotNull String eid, @Nullable @Nullable String args)
      Apply an enchantment to an ItemStack and register it in the enchantment cache.

      This method:

      • Stores enchantment metadata (type, magnitude, ID, args) as NBT tags in the item's metadata
      • Creates an Enchantment object from the enchantment type and caches it by ID
      • Adds custom lore to the item if the enchantment has associated text

      The enchantment ID uniquely identifies this enchanted item instance and is used for efficient lookup during event handling. It should typically be a UUID or unique identifier.

      Parameters:
      itemStack - the ItemStack to enchant
      eType - the type of enchantment to apply
      magnitude - the power level of the enchantment (1+)
      eid - the unique identifier for this enchantment instance
      args - optional enchantment-specific arguments (null if not needed)

    • isEnchanted

      public boolean isEnchanted(@NotNull @NotNull org.bukkit.entity.Item item)
      Check if an Item entity has an enchantment applied.
      Parameters:
      item - the item entity to check
      Returns:
      true if the item has enchantment NBT tags, false otherwise

    • isEnchanted

      public boolean isEnchanted(@NotNull @NotNull org.bukkit.inventory.ItemStack itemStack)
      Check if an ItemStack has an enchantment applied.

      Examines the item's NBT metadata to determine if any enchantment has been applied. This is a quick check that doesn't require creating an Enchantment object.

      Parameters:
      itemStack - the ItemStack to check
      Returns:
      true if the ItemStack has enchantment NBT tags, false otherwise

    • isCursed

      public boolean isCursed(@NotNull @NotNull org.bukkit.entity.Item item)
      Check if an Item entity is cursed.

      A cursed item has an enchantment that is marked as a curse (harmful magical effect).

      Parameters:
      item - the item entity to check
      Returns:
      true if the item is cursed, false otherwise

    • isCursed

      public boolean isCursed(@NotNull @NotNull org.bukkit.inventory.ItemStack itemStack)
      Check if an ItemStack is cursed.

      A cursed item has an enchantment that is marked as a curse (harmful magical effect). Examples: GEMINO (duplication), FLAGRANTE (burning).

      Parameters:
      itemStack - the ItemStack to check
      Returns:
      true if the ItemStack is cursed, false otherwise

    • isCursedLevelBased

      public boolean isCursedLevelBased(@NotNull @NotNull org.bukkit.entity.Item item, @NotNull @NotNull MagicLevel level)
      Check if an Item is cursed and if the curse can be detected by the given magic level.

      This method determines not only if an item is cursed, but also whether the detecting spell or person is powerful enough to recognize the curse. Curses that are too high-level will not be detected by lower-level detection spells.

      Detection succeeds if: curse_level <= detection_level + 1

      Parameters:
      item - the item to check for curses
      level - the magic level attempting to detect the curse
      Returns:
      true if the item is cursed AND the curse level is detectable by the given level, false otherwise

    • getEnchantmentTypeKey

      @Nullable public @Nullable String getEnchantmentTypeKey(@NotNull @NotNull org.bukkit.inventory.ItemStack itemStack)
      Get the enchantment type string from an ItemStack's NBT tags.

      Returns the string name of the enchantment type (e.g., "GEMINO", "VOLATUS", "PORTUS") without parsing it into an enum. Useful for quick checks or for storing the type.

      Parameters:
      itemStack - the ItemStack to retrieve the enchantment type from
      Returns:
      the enchantment type string if present, null if item is not enchanted

    • getEnchantmentType

      @Nullable public @Nullable ItemEnchantmentType getEnchantmentType(@NotNull @NotNull org.bukkit.inventory.ItemStack itemStack)
      Get the enchantment type enum from an ItemStack.

      Retrieves and parses the enchantment type from the item's NBT tags, returning the corresponding ItemEnchantmentType enum value. Returns null if the item is not enchanted or if the stored type string is invalid.

      Parameters:
      itemStack - the ItemStack to retrieve the enchantment type from
      Returns:
      the ItemEnchantmentType enum if present and valid, null otherwise

    • getEnchantmentID

      @Nullable public @Nullable String getEnchantmentID(@NotNull @NotNull org.bukkit.entity.Item item)
      Get the unique ID of an enchantment from an Item entity.

      This convenience method retrieves the enchantment ID from a dropped Item entity by delegating to getEnchantmentID(ItemStack).

      Parameters:
      item - the item entity to retrieve the enchantment ID from
      Returns:
      the unique enchantment ID if present, null if item is not enchanted

    • getEnchantmentID

      @Nullable public @Nullable String getEnchantmentID(@NotNull @NotNull org.bukkit.inventory.ItemStack itemStack)
      Get the unique ID of an enchantment from an ItemStack.

      Each enchanted item has a unique ID that is used to look up the cached Enchantment object. This ID is typically a UUID string that uniquely identifies this specific enchantment instance.

      Parameters:
      itemStack - the ItemStack to retrieve the enchantment ID from
      Returns:
      the unique enchantment ID if present, null if item is not enchanted

    • getEnchantmentMagnitude

      @Nullable public @Nullable Integer getEnchantmentMagnitude(@NotNull @NotNull org.bukkit.inventory.ItemStack itemStack)
      Get the enchantment magnitude from an ItemStack.

      Magnitude represents the power level of the enchantment (1+ for valid enchantments).

      Parameters:
      itemStack - the ItemStack to retrieve the enchantment magnitude from
      Returns:
      the magnitude (1+) if the item is enchanted, null otherwise

    • getEnchantmentArgs

      @Nullable public @Nullable String getEnchantmentArgs(@NotNull @NotNull org.bukkit.inventory.ItemStack itemStack)
      Get the optional arguments for an enchantment from an ItemStack.

      Enchantments can have optional configuration arguments that customize their behavior. For example, PORTUS portkey enchantments use args to store the destination coordinates.

      Parameters:
      itemStack - the ItemStack to retrieve the enchantment arguments from
      Returns:
      the enchantment arguments string if present, null if item is not enchanted or has no args

    • getEnchantment

      @Nullable public @Nullable Enchantment getEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack itemStack)
      Get the Enchantment object for an ItemStack.

      Looks up the Enchantment in the cache by ID, or creates a new one from NBT tags if not cached. This method is the primary way to retrieve an Enchantment object that can handle item events.

      Creation from NBT is used when an enchanted item is first loaded (e.g., from a player's inventory on login), allowing enchantments to be persistent across server restarts.

      Parameters:
      itemStack - the ItemStack to retrieve the enchantment from
      Returns:
      the Enchantment object if the item is enchanted, null if not enchanted or invalid

    • createEnchantment

      @Nullable public @Nullable Enchantment createEnchantment(@NotNull @NotNull String eType, @NotNull @NotNull Integer magnitude, @Nullable @Nullable String args)
      Create an Enchantment object from type, magnitude, and arguments.

      Uses reflection to instantiate the correct Enchantment subclass for the given type. Returns null if the type is invalid, magnitude is less than 1, or the subclass cannot be instantiated.

      This is typically called when an enchanted item is loaded from NBT data for the first time, or when creating enchantments on-the-fly.

      Parameters:
      eType - the enchantment type string (e.g., "GEMINO", "VOLATUS")
      magnitude - the power level of the enchantment (must be 1 or greater)
      args - optional enchantment-specific configuration arguments
      Returns:
      the created Enchantment object if valid, null if type is invalid or instantiation fails

    • removeEnchantment

      @NotNull public @NotNull org.bukkit.inventory.ItemStack removeEnchantment(@NotNull @NotNull org.bukkit.entity.Item enchantedItem)
      Remove an enchantment from an Item entity.

      This convenience method removes the enchantment from an Item entity by delegating to removeEnchantment(ItemStack). Also removes the enchantment from the cache.

      Parameters:
      enchantedItem - the enchanted item entity to remove the enchantment from
      Returns:
      the ItemStack with the enchantment removed

    • removeEnchantment

      @NotNull public @NotNull org.bukkit.inventory.ItemStack removeEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack enchantedItemStack)
      Remove an enchantment from an ItemStack completely.

      This method:

      • Removes the Enchantment object from the cache
      • Removes all enchantment NBT tags from the item's metadata

      Use this to completely disenchant an item. For simply removing NBT tags without touching the cache, use removeEnchantmentNBT(ItemStack) instead.

      Parameters:
      enchantedItemStack - the ItemStack to remove the enchantment from
      Returns:
      the ItemStack with the enchantment removed

    • removeEnchantmentNBT

      public static org.bukkit.inventory.ItemStack removeEnchantmentNBT(org.bukkit.inventory.ItemStack enchantedItemStack)
      Remove enchantment NBT tags from an ItemStack without affecting the cache.

      This method strips all enchantment metadata from an item without removing the Enchantment object from the cache. Use this for creating unenchanted copies of enchanted items, such as GEMINO duplicates that should not trigger further duplication.

      For complete enchantment removal (both cache and NBT), use removeEnchantment(ItemStack) instead.

      Parameters:
      enchantedItemStack - the ItemStack with enchantment NBT tags to remove
      Returns:
      a new ItemStack with all enchantment NBT tags removed

    • onItemDespawn

      public void onItemDespawn(@NotNull @NotNull org.bukkit.event.entity.ItemDespawnEvent event)
      Handle item despawn events for enchanted items.

      When an enchanted item is about to despawn (due to inactivity timeout), this handler prevents the despawn by cancelling the event and setting unlimited lifetime. Enchanted items are too valuable to be lost to despawning.

      Parameters:
      event - the item despawn event

    • onEntityPickupItem

      public void onEntityPickupItem(@NotNull @NotNull org.bukkit.event.entity.EntityPickupItemEvent event)
      Handle entity pickup events for enchanted items.

      When a player or entity picks up an enchanted item, this handler retrieves the corresponding Enchantment object and delegates to its Enchantment.doEntityPickupItem(EntityPickupItemEvent) method to trigger the enchantment's pickup effect.

      Parameters:
      event - the entity item pickup event

    • onInventoryItemPickup

      public void onInventoryItemPickup(@NotNull @NotNull org.bukkit.event.inventory.InventoryPickupItemEvent event)
      Handle inventory pickup events for enchanted items.

      When a hopper or other block-based inventory attempts to pick up an enchanted item, this handler retrieves the Enchantment and delegates to its Enchantment.doInventoryPickupItem(InventoryPickupItemEvent) method. Most enchantments prevent hoppers from picking up items to protect them from automated systems.

      Parameters:
      event - the inventory item pickup event

    • onItemDrop

      public void onItemDrop(@NotNull @NotNull org.bukkit.event.player.PlayerDropItemEvent event)
      Handle item drop events for enchanted items.

      When a player drops an enchanted item, this handler retrieves the Enchantment and delegates to its Enchantment.doItemDrop(PlayerDropItemEvent) method to trigger any drop-related effects.

      Parameters:
      event - the player item drop event

    • onItemHeld

      public void onItemHeld(@NotNull @NotNull org.bukkit.event.player.PlayerItemHeldEvent event)
      Handle item held events (hotbar slot changes) for enchanted items.

      When a player changes which item slot is active in their hotbar, this handler checks both the newly held item and the previously held item. If either contains an enchantment, the Enchantment's Enchantment.doItemHeld(PlayerItemHeldEvent) method is called to trigger any hold-related effects (e.g., toggling broom flight).

      Parameters:
      event - the player item held event (slot change event)

    • areBroomsEnabled

      public static boolean areBroomsEnabled()
      Check if broomstick enchantments are enabled in the plugin configuration.

      Broomstick items (using VOLATUS enchantments) are optional and can be disabled via the plugin config. This method provides a quick way to check if they are enabled before triggering broom-related effects.

      Returns:
      true if broomstick enchantments are enabled, false otherwise