Package dev.itsharshxd.zentrix.api.item

Interface ItemService

public interface ItemService
Service for managing custom items within Zentrix.

This service allows registration, querying, and retrieval of custom items. It supports vanilla items, custom items, and external items from plugins like ItemsAdder and Nexo.

Example Usage


 ItemService itemService = ZentrixAPI.get().getItemService();

 // Register a custom item
 ItemBuilder compass = new ItemBuilder()
     .id("tracking-compass")
     .material(Material.COMPASS)
     .displayName("&#FFD700&l Tracking Compass")
     .lore("", "&#AAAAAA Right-click to track", "&#AAAAAA the nearest player!")
     .enchant(Enchantment.UNBREAKING, 1)
     .flag(ItemFlag.HIDE_ENCHANTS)
     .glow(true)
     .slot(4)
     .addonId(getAddonId());

 itemService.registerItem(compass);

 // Retrieve and use the item
 itemService.getItem("tracking-compass").ifPresent(item -> {
     player.getInventory().addItem(item);
 });

 // Identify items for custom behavior
 itemService.identifyItem(heldItem).ifPresent(itemId -> {
     if (itemId.equals("tracking-compass")) {
         // Custom tracking logic
     }
 });
Since:
1.1.0

  • Method Details

    • registerItem

      boolean registerItem(@NotNull @NotNull ItemBuilder builder)
      Registers a custom item from a builder.

      This method performs in-memory registration only.

      Parameters:
      builder - The item builder with configuration
      Returns:
      true if registration was successful
      Throws:
      IllegalArgumentException - if the builder is invalid

    • registerItemAsync

      @NotNull @NotNull CompletableFuture<Boolean> registerItemAsync(@NotNull @NotNull ItemBuilder builder)
      Registers a custom item asynchronously with persistence.

      The item is registered and saved to the items.yml configuration file.

      Parameters:
      builder - The item builder with configuration
      Returns:
      A future that completes with true if successful
      Throws:
      IllegalArgumentException - if the builder is invalid

    • registerItems

      int registerItems(@NotNull @NotNull Collection<ItemBuilder> builders)
      Registers multiple items at once.

      This method performs in-memory registration only.

      Parameters:
      builders - Collection of item builders
      Returns:
      The number of successfully registered items

    • unregisterItem

      boolean unregisterItem(@NotNull @NotNull String itemId)
      Unregisters an item by ID.

      This method performs in-memory removal only.

      Parameters:
      itemId - The ID of the item to unregister
      Returns:
      true if the item was found and removed

    • updateItem

      boolean updateItem(@NotNull @NotNull ItemBuilder builder)
      Updates an existing item with new configuration.

      The item must already exist.

      Parameters:
      builder - The item builder with updated configuration
      Returns:
      true if the item was found and updated

    • getItem

      @NotNull @NotNull Optional<org.bukkit.inventory.ItemStack> getItem(@NotNull @NotNull String itemId)
      Gets an ItemStack for a registered item.

      The returned ItemStack is a clone and safe to modify.

      Parameters:
      itemId - The item ID
      Returns:
      Optional containing the ItemStack, or empty if not found

    • getItemOrDefault

      @NotNull @NotNull org.bukkit.inventory.ItemStack getItemOrDefault(@NotNull @NotNull String itemId, @NotNull @NotNull org.bukkit.Material fallback)
      Gets an ItemStack for a registered item, or a fallback material.

      The returned ItemStack is a clone and safe to modify.

      Parameters:
      itemId - The item ID
      fallback - The fallback material if item not found
      Returns:
      The ItemStack (never null)

    • resolveItem

      @NotNull @NotNull Optional<org.bukkit.inventory.ItemStack> resolveItem(@NotNull @NotNull String itemIdentifier)
      Resolves an item from any supported identifier format.

      Supported formats:

      • "custom:item_id" - Custom Zentrix items
      • "itemsadder:namespace:id" - ItemsAdder items
      • "nexo:id" - Nexo items
      • "MATERIAL_NAME" - Vanilla materials

      Parameters:
      itemIdentifier - The item identifier
      Returns:
      Optional containing the resolved ItemStack, or empty if not found

    • resolveItemOrDefault

      @NotNull @NotNull org.bukkit.inventory.ItemStack resolveItemOrDefault(@NotNull @NotNull String itemIdentifier, @NotNull @NotNull org.bukkit.Material fallback)
      Resolves an item from any supported identifier format, with fallback.
      Parameters:
      itemIdentifier - The item identifier
      fallback - The fallback material if resolution fails
      Returns:
      The ItemStack (never null)

    • getItemDefinition

      @NotNull @NotNull Optional<ZentrixItem> getItemDefinition(@NotNull @NotNull String itemId)
      Gets the item definition for a registered item.
      Parameters:
      itemId - The item ID
      Returns:
      Optional containing the item definition, or empty if not found

    • getAllItems

      @NotNull @NotNull Collection<ZentrixItem> getAllItems()
      Gets all registered item definitions.
      Returns:
      An unmodifiable collection of all items (never null, may be empty)

    • getItemsByAddon

      @NotNull @NotNull Collection<ZentrixItem> getItemsByAddon(@NotNull @NotNull String addonId)
      Gets all items registered by a specific addon.
      Parameters:
      addonId - The addon identifier
      Returns:
      Collection of items registered by the addon (never null, may be empty)

    • itemExists

      boolean itemExists(@NotNull @NotNull String itemId)
      Checks if an item exists with the given ID.
      Parameters:
      itemId - The item ID to check
      Returns:
      true if the item exists

    • getItemIds

      @NotNull @NotNull Collection<String> getItemIds()
      Gets all item IDs.
      Returns:
      Collection of item IDs (never null, may be empty)

    • matchesItem

      boolean matchesItem(@NotNull @NotNull org.bukkit.inventory.ItemStack itemStack, @NotNull @NotNull String itemId)
      Checks if an ItemStack matches a registered item.
      Parameters:
      itemStack - The ItemStack to check
      itemId - The item ID to match against
      Returns:
      true if the ItemStack matches the item definition

    • identifyItem

      @NotNull @NotNull Optional<String> identifyItem(@NotNull @NotNull org.bukkit.inventory.ItemStack itemStack)
      Identifies what registered item an ItemStack represents.

      Useful for implementing custom item behavior in event handlers.

      Parameters:
      itemStack - The ItemStack to identify
      Returns:
      Optional containing the item ID, or empty if not a registered item

    • getItemSlot

      int getItemSlot(@NotNull @NotNull String itemId)
      Gets the configured slot for an item.
      Parameters:
      itemId - The item ID
      Returns:
      The slot index, or -1 if not configured or item not found

    • isItemEnabled

      boolean isItemEnabled(@NotNull @NotNull String itemId)
      Checks if an item is enabled.
      Parameters:
      itemId - The item ID
      Returns:
      true if the item exists and is enabled

    • createItemBuilder

      @NotNull default @NotNull ItemBuilder createItemBuilder()
      Creates a new ItemBuilder instance.
      Returns:
      A new ItemBuilder