Package io.artificial.enchantments.internal

Class ArtificialEnchantmentsAPIImpl

java.lang.Object
io.artificial.enchantments.internal.ArtificialEnchantmentsAPIImpl
All Implemented Interfaces:
ArtificialEnchantmentsAPI
public class ArtificialEnchantmentsAPIImpl extends Object implements ArtificialEnchantmentsAPI
Implementation of ArtificialEnchantmentsAPI.

This class provides the concrete implementation of the public API, delegating operations to ItemEnchantmentService and other internal components.

Since:
0.2.0

  • Method Details

    • create

      @NotNull public static @NotNull ArtificialEnchantmentsAPIImpl create(@NotNull @NotNull org.bukkit.plugin.Plugin plugin)
      Creates a new API instance bound to the specified plugin.
      Parameters:
      plugin - the plugin requesting the API
      Returns:
      a new API instance

    • getInstance

      @NotNull public static @NotNull ArtificialEnchantmentsAPIImpl getInstance()
      Gets the shared API instance.
      Returns:
      the shared API instance
      Throws:
      IllegalStateException - if not initialized

    • registerEnchantment

      @NotNull public @NotNull ArtificialEnchantmentsAPI registerEnchantment(@NotNull @NotNull EnchantmentDefinition definition)
      Description copied from interface: ArtificialEnchantmentsAPI
      Registers a new enchantment definition with the library.

      The enchantment becomes available for application to items immediately. On Paper 1.21+, native client visibility requires the definition to be queued during bootstrap via ArtificialEnchantmentsAPI.registerBootstrapEnchantment(EnchantmentDefinition). Calling this after Paper's registry compose event has closed fails fast because the native registry can no longer accept new enchantments.

      Thread Safety: This operation is thread-safe.

      Specified by:
      registerEnchantment in interface ArtificialEnchantmentsAPI
      Parameters:
      definition - the enchantment definition to register (must not be null)
      Returns:
      this API instance for chaining

    • unregisterEnchantment

      public boolean unregisterEnchantment(@NotNull @NotNull org.bukkit.NamespacedKey key)
      Description copied from interface: ArtificialEnchantmentsAPI
      Unregisters an enchantment by its key.

      Removes the enchantment from the registry. Items already enchanted with this enchantment retain their effects until the items are modified.

      Thread Safety: This operation is thread-safe.

      Specified by:
      unregisterEnchantment in interface ArtificialEnchantmentsAPI
      Parameters:
      key - the enchantment's namespaced key (must not be null)
      Returns:
      true if an enchantment was removed, false if not found

    • getEnchantment

      @NotNull public @NotNull Optional<EnchantmentDefinition> getEnchantment(@NotNull @NotNull org.bukkit.NamespacedKey key)
      Description copied from interface: ArtificialEnchantmentsAPI
      Gets an enchantment definition by its key.
      Specified by:
      getEnchantment in interface ArtificialEnchantmentsAPI
      Parameters:
      key - the enchantment's namespaced key (must not be null)
      Returns:
      the definition if found, empty otherwise

    • getAllEnchantments

      @NotNull public @NotNull Collection<EnchantmentDefinition> getAllEnchantments()
      Description copied from interface: ArtificialEnchantmentsAPI
      Gets all registered enchantment definitions.
      Specified by:
      getAllEnchantments in interface ArtificialEnchantmentsAPI
      Returns:
      an unmodifiable collection of all enchantments

    • getEnchantmentsFor

      @NotNull public @NotNull Set<EnchantmentDefinition> getEnchantmentsFor(@NotNull @NotNull org.bukkit.Material material)
      Description copied from interface: ArtificialEnchantmentsAPI
      Gets all enchantments applicable to a specific material.
      Specified by:
      getEnchantmentsFor in interface ArtificialEnchantmentsAPI
      Parameters:
      material - the material to check (must not be null)
      Returns:
      a set of enchantments that can be applied to this material

    • applyEnchantment

      @NotNull public @NotNull org.bukkit.inventory.ItemStack applyEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment, int level)
      Description copied from interface: ArtificialEnchantmentsAPI
      Applies an enchantment to an item at the specified level.

      The item's ItemMeta is updated with the enchantment. The level must be within the enchantment's defined min/max bounds.

      Native-First Policy: The enchantment is stored in native ItemMeta, not duplicated in NBT.

      Specified by:
      applyEnchantment in interface ArtificialEnchantmentsAPI
      Parameters:
      item - the item to enchant (must not be null or air)
      enchantment - the enchantment to apply (must not be null)
      level - the level to apply (must be within bounds)
      Returns:
      the enchanted item (may be same instance)

    • applyEnchantment

      @NotNull public @NotNull org.bukkit.inventory.ItemStack applyEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key, int level)
      Description copied from interface: ArtificialEnchantmentsAPI
      Applies an enchantment by its registry key.

      Convenience method that looks up the definition before application.

      Specified by:
      applyEnchantment in interface ArtificialEnchantmentsAPI
      Parameters:
      item - the item to enchant (must not be null or air)
      key - the enchantment's namespaced key (must not be null)
      level - the level to apply
      Returns:
      the enchanted item

    • removeEnchantment

      @NotNull public @NotNull org.bukkit.inventory.ItemStack removeEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
      Description copied from interface: ArtificialEnchantmentsAPI
      Removes an enchantment from an item.
      Specified by:
      removeEnchantment in interface ArtificialEnchantmentsAPI
      Parameters:
      item - the item to modify (must not be null)
      enchantment - the enchantment to remove (must not be null)
      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)
      Description copied from interface: ArtificialEnchantmentsAPI
      Removes an enchantment by its key.
      Specified by:
      removeEnchantment in interface ArtificialEnchantmentsAPI
      Parameters:
      item - the item to modify (must not be null)
      key - the enchantment's namespaced key (must not be null)
      Returns:
      the modified item

    • removeAllEnchantments

      @NotNull public @NotNull org.bukkit.inventory.ItemStack removeAllEnchantments(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Description copied from interface: ArtificialEnchantmentsAPI
      Removes all artificial enchantments from an item.

      Vanilla enchantments are preserved. Only enchantments registered through this API are removed.

      Specified by:
      removeAllEnchantments in interface ArtificialEnchantmentsAPI
      Parameters:
      item - the item to clear (must not be null)
      Returns:
      the modified item

    • getEnchantmentLevel

      public int getEnchantmentLevel(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
      Description copied from interface: ArtificialEnchantmentsAPI
      Gets the level of an enchantment on an item.
      Specified by:
      getEnchantmentLevel in interface ArtificialEnchantmentsAPI
      Parameters:
      item - the item to check (must not be null)
      enchantment - the enchantment to look for (must not be null)
      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)
      Description copied from interface: ArtificialEnchantmentsAPI
      Gets the level of an enchantment by its key.
      Specified by:
      getEnchantmentLevel in interface ArtificialEnchantmentsAPI
      Parameters:
      item - the item to check (must not be null)
      key - the enchantment's namespaced key (must not be null)
      Returns:
      the enchantment level, or 0 if not present

    • getEnchantments

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

      Returns a map of enchantment definitions to their levels. The map is unmodifiable and represents a snapshot of the item's state.

      Specified by:
      getEnchantments in interface ArtificialEnchantmentsAPI
      Parameters:
      item - the item to query (must not be null)
      Returns:
      map of enchantments to levels (never null, may be empty)

    • hasEnchantment

      public boolean hasEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
      Description copied from interface: ArtificialEnchantmentsAPI
      Checks if an item has a specific enchantment.
      Specified by:
      hasEnchantment in interface ArtificialEnchantmentsAPI
      Parameters:
      item - the item to check (must not be null)
      enchantment - the enchantment to look for (must not be null)
      Returns:
      true if the enchantment is present at any level

    • hasEnchantment

      public boolean hasEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key)
      Description copied from interface: ArtificialEnchantmentsAPI
      Checks if an item has an enchantment by its key.
      Specified by:
      hasEnchantment in interface ArtificialEnchantmentsAPI
      Parameters:
      item - the item to check (must not be null)
      key - the enchantment's namespaced key (must not be null)
      Returns:
      true if the enchantment is present at any level

    • getEventBus

      @NotNull public @NotNull EnchantmentEventBus getEventBus()
      Description copied from interface: ArtificialEnchantmentsAPI
      Gets the event bus for subscribing to enchantment effects.

      Use this to listen for enchantment-triggered events without implementing a full effect handler.

      Specified by:
      getEventBus in interface ArtificialEnchantmentsAPI
      Returns:
      the event bus instance

    • getItemStorage

      @NotNull public @NotNull ItemStorage getItemStorage()
      Description copied from interface: ArtificialEnchantmentsAPI
      Gets the item storage for direct access to item enchantment operations.

      Use this for advanced item manipulation or when you need to perform batch operations on items.

      Specified by:
      getItemStorage in interface ArtificialEnchantmentsAPI
      Returns:
      the item storage instance

    • query

      @NotNull public @NotNull ItemEnchantmentQuery query()
      Description copied from interface: ArtificialEnchantmentsAPI
      Gets the query facade for convenient enchantment lookups on items.

      This provides a scoped, developer-friendly API for checking enchantments without manual ItemMeta inspection. All methods are null-safe and return sensible defaults for null inputs.

      Example Usage: 

      
 // Check if item has an enchantment
 if (api.query().hasEnchantment(item, lifeSteal)) {
     int level = api.query().getLevel(item, lifeSteal);
 }

 // Get all enchantments
 Map<EnchantmentDefinition, Integer> enchantments = api.query().getAllEnchantments(item);

 // Check material applicability
 Set<EnchantmentDefinition> applicable = api.query().getEnchantmentsFor(Material.DIAMOND_SWORD);
      Specified by:
      query in interface ArtificialEnchantmentsAPI
      Returns:
      the query facade instance

    • getPlugin

      @NotNull public @NotNull org.bukkit.plugin.Plugin getPlugin()
      Description copied from interface: ArtificialEnchantmentsAPI
      Gets the plugin that owns this API instance.
      Specified by:
      getPlugin in interface ArtificialEnchantmentsAPI
      Returns:
      the owning plugin

    • isFolia

      public boolean isFolia()
      Description copied from interface: ArtificialEnchantmentsAPI
      Checks if running on a Folia server.
      Specified by:
      isFolia in interface ArtificialEnchantmentsAPI
      Returns:
      true if Folia region threading is detected

    • getVersion

      @NotNull public @NotNull String getVersion()
      Description copied from interface: ArtificialEnchantmentsAPI
      Gets the library version string.
      Specified by:
      getVersion in interface ArtificialEnchantmentsAPI
      Returns:
      the version in semantic format (e.g., "1.0.0")

    • getScalingRegistry

      @NotNull public @NotNull ScalingAlgorithmRegistry getScalingRegistry()
      Description copied from interface: ArtificialEnchantmentsAPI
      Gets the scaling algorithm registry.

      Use this to register custom scaling algorithms or retrieve built-in ones. The registry is pre-populated with all built-in algorithms on startup.

      Specified by:
      getScalingRegistry in interface ArtificialEnchantmentsAPI
      Returns:
      the scaling algorithm registry instance

    • getLootModifierRegistry

      @NotNull public @NotNull LootModifierRegistry getLootModifierRegistry()
      Description copied from interface: ArtificialEnchantmentsAPI
      Gets the loot modifier registry for block-break loot modifications.

      Use this registry to register LootModifier instances that can modify drops when blocks are broken with enchanted tools.

      Explicit Ownership: Only enchantments with explicitly registered modifiers affect loot drops. Non-targeted loot remains untouched unless opted in.

      Usage Example: 

      
 LootModifierRegistry registry = api.getLootModifierRegistry();

 LootModifier myModifier = context -> {
     // Double drops based on level
     int multiplier = 1 + context.getLevel();
     for (ItemStack drop : context.getDrops()) {
         drop.setAmount(drop.getAmount() * multiplier);
     }
 };

 registry.register(myEnchantment, myModifier);
      Specified by:
      getLootModifierRegistry in interface ArtificialEnchantmentsAPI
      Returns:
      the loot modifier registry instance

    • getScheduler

      @NotNull public @NotNull FoliaScheduler getScheduler()
      Description copied from interface: ArtificialEnchantmentsAPI
      Gets the Folia-compatible scheduler for thread-safe task execution.

      Use this scheduler to run tasks on the appropriate threads:

      • Global region thread - for non-location-dependent operations
      • Region thread - for location-dependent operations
      • Entity scheduler - for entity-specific operations

      Usage Example: 

      
 // Run later on global region thread
 api.getScheduler().runGlobalDelayed(plugin, () -> {
     // Task here
 }, 20L);

 // Run at a specific location's region thread
 api.getScheduler().runAtLocation(plugin, location, () -> {
     // Location-dependent task
 });
      Specified by:
      getScheduler in interface ArtificialEnchantmentsAPI
      Returns:
      the scheduler instance