All Known Implementing Classes:: ItemEnchantmentQueryImpl

public interface ItemEnchantmentQuery

A scoped, developer-friendly API for querying enchantments on items.

This facade provides convenient methods for checking enchantments on items without manual ItemMeta inspection. It wraps ItemStorage and provides a more ergonomic API that feels local to the item.

Null Safety: All methods in this interface are null-safe. Passing a null ItemStack will return false (for boolean methods), 0 (for level methods), or empty collections (for collection-returning methods).

Usage Examples:


 // Single enchantment check
 if (api.query().hasEnchantment(item, lifeSteal)) {
     int level = api.query().getLevel(item, lifeSteal);
 }
 
 // Check by key
 if (api.query().hasEnchantment(item, new NamespacedKey(plugin, "life_steal"))) {
     // Enchantment is present
 }
 
 // Get all enchantments
 Map<EnchantmentDefinition, Integer> enchantments = api.query().getAllEnchantments(item);
 
 // Check if any enchantment exists
 if (api.query().isEnchanted(item)) {
     // Item has at least one custom enchantment
 }
 
 // Get applicable enchantments for a material
 Set<EnchantmentDefinition> applicable = api.query().getEnchantmentsFor(Material.DIAMOND_SWORD);

Since:

0.2.0

See Also:

Method Summary

Modifier and Type

Method

Description

@NotNull Map<EnchantmentDefinition,Integer>

getAllEnchantments(@Nullable org.bukkit.inventory.ItemStack item)

Gets all artificial enchantments on an item.

@NotNull Set<EnchantmentDefinition>

getEnchantmentsFor(@Nullable org.bukkit.Material material)

Gets all enchantments that can be applied to a specific material.

int

getHighestLevel(@Nullable org.bukkit.inventory.ItemStack item)

Gets the highest enchantment level on an item.

int

getLevel(@Nullable org.bukkit.inventory.ItemStack item, @NotNull EnchantmentDefinition enchantment)

Gets the level of a specific enchantment on an item.

int

getLevel(@Nullable org.bukkit.inventory.ItemStack item, @NotNull org.bukkit.NamespacedKey key)

Gets the level of an enchantment by its registry key.

int

getTotalEnchantmentLevel(@Nullable org.bukkit.inventory.ItemStack item)

Gets the total level of all enchantments on an item.

boolean

hasAllEnchantments(@Nullable org.bukkit.inventory.ItemStack item, @NotNull EnchantmentDefinition... enchantments)

Checks if multiple enchantments are present on an item.

boolean

hasAnyEnchantment(@Nullable org.bukkit.inventory.ItemStack item, @NotNull EnchantmentDefinition... enchantments)

Checks if any of the specified enchantments are present on an item.

boolean

hasEnchantment(@Nullable org.bukkit.inventory.ItemStack item, @NotNull EnchantmentDefinition enchantment)

Checks if an item has a specific enchantment.

boolean

hasEnchantment(@Nullable org.bukkit.inventory.ItemStack item, @NotNull org.bukkit.NamespacedKey key)

Checks if an item has an enchantment by its registry key.

boolean

isEnchanted(@Nullable org.bukkit.inventory.ItemStack item)

Checks if an item has any custom enchantment.

Method Details
- hasEnchantment
  
  boolean hasEnchantment(@Nullable @Nullable org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
  
  Checks if an item has a specific enchantment.
  Returns false if the item is null or the enchantment is not present.
  
  Parameters:
  
  item - the item to check (null-safe)
  
  enchantment - the enchantment to look for (must not be null)
  
  Returns:
  
  true if the item has the enchantment at any level
  
  Throws:
  
  IllegalArgumentException - if enchantment is null
  
  Since:
  
  0.2.0
- hasEnchantment
  
  boolean hasEnchantment(@Nullable @Nullable org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key)
  
  Checks if an item has an enchantment by its registry key.
  Returns false if the item is null, the key is not found in the registry, or the enchantment is not present on the item.
  
  Parameters:
  
  item - the item to check (null-safe)
  
  key - the enchantment's namespaced key (must not be null)
  
  Returns:
  
  true if the item has the enchantment at any level
  
  Throws:
  
  IllegalArgumentException - if key is null
  
  Since:
  
  0.2.0
- getLevel
  
  int getLevel(@Nullable @Nullable org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
  
  Gets the level of a specific enchantment on an item.
  Returns 0 if the item is null, doesn't have the enchantment, or the enchantment is not registered.
  
  Parameters:
  
  item - the item to query (null-safe)
  
  enchantment - the enchantment to check (must not be null)
  
  Returns:
  
  the enchantment level, or 0 if not present
  
  Throws:
  
  IllegalArgumentException - if enchantment is null
  
  Since:
  
  0.2.0
- getLevel
  
  int getLevel(@Nullable @Nullable org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key)
  
  Gets the level of an enchantment by its registry key.
  Returns 0 if the item is null, the enchantment is not found in the registry, or the enchantment is not present on the item.
  
  Parameters:
  
  item - the item to query (null-safe)
  
  key - the enchantment's namespaced key (must not be null)
  
  Returns:
  
  the enchantment level, or 0 if not present
  
  Throws:
  
  IllegalArgumentException - if key is null
  
  Since:
  
  0.2.0
- getAllEnchantments
  
  @NotNull @NotNull Map<EnchantmentDefinition,Integer> getAllEnchantments(@Nullable @Nullable 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; vanilla enchantments are excluded.
  The returned map is unmodifiable and represents a snapshot of the item's state at the time of the call. Returns an empty map if the item is null.
  
  Parameters:
  
  item - the item to query (null-safe)
  
  Returns:
  
  an unmodifiable map of enchantments to levels (never null)
  
  Since:
  
  0.2.0
- isEnchanted
  
  boolean isEnchanted(@Nullable @Nullable org.bukkit.inventory.ItemStack item)
  
  Checks if an item has any custom enchantment.
  Returns true if the item has at least one artificial enchantment registered through this API. Returns false if the item is null or has no custom enchantments.
  
  Parameters:
  
  item - the item to check (null-safe)
  
  Returns:
  
  true if the item has any custom enchantment
  
  Since:
  
  0.2.0
- getEnchantmentsFor
  
  @NotNull @NotNull Set<EnchantmentDefinition> getEnchantmentsFor(@Nullable @Nullable org.bukkit.Material material)
  
  Gets all enchantments that can be applied to a specific material.
  Returns a set of all registered enchantments that are applicable to the given material. This is useful for enchanting interfaces or checking what enchantments are available for a tool type.
  The returned set is unmodifiable. Returns an empty set if the material is null or no enchantments are applicable.
  
  Parameters:
  
  material - the material to check (null-safe)
  
  Returns:
  
  an unmodifiable set of applicable enchantments (never null)
  
  Since:
  
  0.2.0
- hasAllEnchantments
  
  boolean hasAllEnchantments(@Nullable @Nullable org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition... enchantments)
  
  Checks if multiple enchantments are present on an item.
  Returns true only if ALL specified enchantments are present on the item. Returns false if the item is null, the enchantments array is empty, or any enchantment is missing.
  
  Parameters:
  
  item - the item to check (null-safe)
  
  enchantments - the enchantments to look for (must not be null or empty)
  
  Returns:
  
  true if all enchantments are present
  
  Throws:
  
  IllegalArgumentException - if enchantments is null or empty
  
  Since:
  
  0.2.0
- hasAnyEnchantment
  
  boolean hasAnyEnchantment(@Nullable @Nullable org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition... enchantments)
  
  Checks if any of the specified enchantments are present on an item.
  Returns true if AT LEAST ONE of the specified enchantments is present on the item. Returns false if the item is null, the enchantments array is empty, or none of the enchantments are present.
  
  Parameters:
  
  item - the item to check (null-safe)
  
  enchantments - the enchantments to look for (must not be null or empty)
  
  Returns:
  
  true if any enchantment is present
  
  Throws:
  
  IllegalArgumentException - if enchantments is null or empty
  
  Since:
  
  0.2.0
- getTotalEnchantmentLevel
  
  int getTotalEnchantmentLevel(@Nullable @Nullable org.bukkit.inventory.ItemStack item)
  
  Gets the total level of all enchantments on an item.
  Returns the sum of all enchantment levels. Returns 0 if the item is null or has no enchantments.
  
  Parameters:
  
  item - the item to query (null-safe)
  
  Returns:
  
  the sum of all enchantment levels
  
  Since:
  
  0.2.0
- getHighestLevel
  
  int getHighestLevel(@Nullable @Nullable org.bukkit.inventory.ItemStack item)
  
  Gets the highest enchantment level on an item.
  Returns the maximum level among all enchantments on the item. Returns 0 if the item is null or has no enchantments.
  
  Parameters:
  
  item - the item to query (null-safe)
  
  Returns:
  
  the highest enchantment level, or 0 if none
  
  Since:
  
  0.2.0

Interface ItemEnchantmentQuery

Method Summary

Method Details

hasEnchantment

hasEnchantment

getLevel

getLevel

getAllEnchantments

isEnchanted

getEnchantmentsFor

hasAllEnchantments

hasAnyEnchantment

getTotalEnchantmentLevel

getHighestLevel