Package io.artificial.enchantments.internal

Class ItemEnchantmentService

java.lang.Object
io.artificial.enchantments.internal.ItemEnchantmentService
public class ItemEnchantmentService extends Object
Service for mutating item enchantment state.

This is the primary implementation of item mutation operations for the Artificial Enchantments library. It coordinates between the native ItemMeta (source of truth) and auxiliary NBT metadata storage.

All operations are atomic - either fully succeed or leave the item unchanged. The native ItemMeta is always the source of truth for enchantment state; NBT is used only for auxiliary metadata like display flags.

Since:
0.1.0

  • Constructor Details

    • ItemEnchantmentService

      public ItemEnchantmentService(@NotNull @NotNull ItemStorage itemStorage, @NotNull @NotNull EnchantmentRegistryManager registryManager)
      Creates a new item enchantment service.
      Parameters:
      itemStorage - the item storage implementation for applying/removing enchantments
      registryManager - the registry manager for looking up enchantment definitions
      Since:
      0.1.0

  • Method Details

    • applyEnchantment

      @NotNull public @NotNull org.bukkit.inventory.ItemStack applyEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment, int level)
      Applies an enchantment to an item at the specified level.

      Validates the level against the enchantment's min/max bounds before application. Returns the enchanted item (may be a new instance).

      Parameters:
      item - the item to enchant
      enchantment - the enchantment to apply
      level - the enchantment level
      Returns:
      the enchanted item
      Throws:
      IllegalArgumentException - if item is null, air, level invalid, or enchantment not applicable
      IllegalStateException - if the enchantment is not registered

    • applyEnchantment

      @NotNull public @NotNull org.bukkit.inventory.ItemStack applyEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key, int level)
      Applies an enchantment by its registry key.
      Parameters:
      item - the item to enchant
      key - the enchantment's namespaced key
      level - the enchantment level
      Returns:
      the enchanted item
      Throws:
      IllegalArgumentException - if enchantment not registered or invalid parameters

    • removeEnchantment

      @NotNull public @NotNull org.bukkit.inventory.ItemStack removeEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
      Removes an enchantment from an item.

      If the item does not have the enchantment, returns the item unchanged.

      Parameters:
      item - the item to modify
      enchantment - the enchantment to remove
      Returns:
      the modified item

    • removeEnchantment

      @NotNull public @NotNull org.bukkit.inventory.ItemStack removeEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key)
      Removes an enchantment by its registry key.
      Parameters:
      item - the item to modify
      key - the enchantment's namespaced key
      Returns:
      the modified item

    • removeAllEnchantments

      @NotNull public @NotNull org.bukkit.inventory.ItemStack removeAllEnchantments(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Removes all artificial enchantments from an item.

      Preserves vanilla enchantments and the item's base properties.

      Parameters:
      item - the item to clear
      Returns:
      the modified item

    • getEnchantmentLevel

      public int getEnchantmentLevel(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
      Gets the level of a specific enchantment on an item.
      Parameters:
      item - the item to query
      enchantment - the enchantment to check
      Returns:
      the enchantment level, or 0 if not present

    • getEnchantmentLevel

      public int getEnchantmentLevel(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key)
      Gets the level of an enchantment by its registry key.
      Parameters:
      item - the item to query
      key - the enchantment's namespaced key
      Returns:
      the enchantment level, or 0 if not present or not registered

    • getEnchantments

      @NotNull public @NotNull Map<EnchantmentDefinition,Integer> getEnchantments(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Gets all artificial enchantments on an item.

      Returns a map of enchantment definitions to their levels. Only enchantments registered through this API are included.

      Parameters:
      item - the item to query
      Returns:
      unmodifiable map of enchantments to levels (never null)

    • getEnchantmentKeys

      @NotNull public @NotNull Map<org.bukkit.NamespacedKey,Integer> getEnchantmentKeys(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Gets all artificial enchantment keys on an item.

      Lower-level alternative that returns raw keys rather than definitions.

      Parameters:
      item - the item to query
      Returns:
      unmodifiable map of keys to levels (never null)

    • hasEnchantment

      public boolean hasEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
      Checks if an item has a specific enchantment.
      Parameters:
      item - the item to check
      enchantment - the enchantment to look for
      Returns:
      true if the item has the enchantment at any level

    • hasEnchantment

      public boolean hasEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key)
      Checks if an item has an enchantment by its registry key.
      Parameters:
      item - the item to check
      key - the enchantment's namespaced key
      Returns:
      true if the item has the enchantment

    • getEnchantmentsForMaterial

      @NotNull public @NotNull Set<EnchantmentDefinition> getEnchantmentsForMaterial(@NotNull @NotNull org.bukkit.Material material)
      Gets all enchantments applicable to a material.
      Parameters:
      material - the material to check
      Returns:
      unmodifiable set of applicable enchantment definitions

    • getAllEnchantments

      @NotNull public @NotNull Collection<EnchantmentDefinition> getAllEnchantments()
      Gets all registered enchantment definitions.
      Returns:
      unmodifiable collection of all enchantments

    • getEnchantment

      @NotNull public Optional<EnchantmentDefinition> getEnchantment(@NotNull @NotNull org.bukkit.NamespacedKey key)
      Gets an enchantment definition by key.
      Parameters:
      key - the enchantment's namespaced key
      Returns:
      the definition, or empty if not registered

    • registerEnchantment

      @NotNull public @NotNull EnchantmentDefinition registerEnchantment(@NotNull @NotNull EnchantmentDefinition definition)
      Registers a new enchantment definition.
      Parameters:
      definition - the enchantment to register
      Returns:
      the registered definition
      Throws:
      IllegalArgumentException - if already registered or invalid
      IllegalStateException - if Paper's native registry compose window has closed

    • unregisterEnchantment

      public boolean unregisterEnchantment(@NotNull @NotNull org.bukkit.NamespacedKey key)
      Unregisters an enchantment.
      Parameters:
      key - the enchantment's namespaced key
      Returns:
      true if removed, false if not found

    • setAuxiliaryMetadata

      @NotNull public @NotNull org.bukkit.inventory.ItemStack setAuxiliaryMetadata(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull String key, String value)
      Sets auxiliary metadata on an item.

      This stores non-enchantment data in NBT for compatibility or display.

      Parameters:
      item - the item to modify
      key - the metadata key
      value - the value to store
      Returns:
      the modified item

    • getAuxiliaryMetadata

      public String getAuxiliaryMetadata(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull String key)
      Gets auxiliary metadata from an item.
      Parameters:
      item - the item to query
      key - the metadata key
      Returns:
      the stored value, or null if not present