Package dev.itsharshxd.zentrix.api.item

Class ItemBuilder

java.lang.Object
dev.itsharshxd.zentrix.api.item.ItemBuilder
public class ItemBuilder extends Object
Fluent builder for creating custom items dynamically.

This builder allows addon developers to create items that integrate with the Zentrix item system, supporting vanilla items and external sources like ItemsAdder and Nexo.

Example Usage - Vanilla 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!",
         "",
         "&#555555Cooldown: 10s"
     )
     .enchant(Enchantment.UNBREAKING, 1)
     .flag(ItemFlag.HIDE_ENCHANTS)
     .glow(true)
     .slot(4)
     .addonId(getAddonId());

 itemService.registerItem(compass);

Example Usage - External Item


 ItemBuilder customSword = new ItemBuilder()
     .id("custom-diamond-sword")
     .external("itemsadder:mynamespace:my_sword")
     .slot(0)
     .addonId(getAddonId());

 itemService.registerItem(customSword);
Since:
1.1.0
See Also:

  • Constructor Details

    • ItemBuilder

      public ItemBuilder()
      Creates a new ItemBuilder instance.

  • Method Details

    • id

      @NotNull public @NotNull ItemBuilder id(@NotNull @NotNull String id)
      Sets the unique identifier for this item.

      Item IDs must only contain lowercase letters, numbers, hyphens, and underscores.

      Parameters:
      id - The item ID (e.g., "tracking-compass", "custom_sword")
      Returns:
      This builder for chaining
      Throws:
      IllegalArgumentException - if the ID is null, empty, or contains invalid characters

    • material

      @NotNull public @NotNull ItemBuilder material(@NotNull @NotNull org.bukkit.Material material)
      Sets the material for this item.
      Parameters:
      material - The Bukkit material
      Returns:
      This builder for chaining

    • external

      @NotNull public @NotNull ItemBuilder external(@NotNull @NotNull String source)
      Sets this item to use an external source (ItemsAdder, Nexo, etc.).

      Format examples:

      • "itemsadder:namespace:item_id"
      • "nexo:item_id"

      Parameters:
      source - The external source identifier
      Returns:
      This builder for chaining

    • displayName

      @NotNull public @NotNull ItemBuilder displayName(@NotNull @NotNull String name)
      Sets the display name for this item.
      Parameters:
      name - The display name (supports color codes)
      Returns:
      This builder for chaining

    • lore

      @NotNull public @NotNull ItemBuilder lore(@NotNull @NotNull String... lines)
      Sets the lore for this item.
      Parameters:
      lines - The lore lines (varargs, supports color codes)
      Returns:
      This builder for chaining

    • addLore

      @NotNull public @NotNull ItemBuilder addLore(@NotNull @NotNull String line)
      Adds a lore line to this item.
      Parameters:
      line - The lore line to add
      Returns:
      This builder for chaining

    • amount

      @NotNull public @NotNull ItemBuilder amount(int amount)
      Sets the item amount.
      Parameters:
      amount - The amount (1-64)
      Returns:
      This builder for chaining
      Throws:
      IllegalArgumentException - if amount is not between 1 and 64

    • enchant

      @NotNull public @NotNull ItemBuilder enchant(@NotNull @NotNull org.bukkit.enchantments.Enchantment enchantment, int level)
      Adds an enchantment to this item.
      Parameters:
      enchantment - The enchantment
      level - The enchantment level
      Returns:
      This builder for chaining

    • flag

      @NotNull public @NotNull ItemBuilder flag(@NotNull @NotNull org.bukkit.inventory.ItemFlag... flags)
      Adds item flags to this item.
      Parameters:
      flags - The item flags (varargs)
      Returns:
      This builder for chaining

    • customModelData

      @NotNull public @NotNull ItemBuilder customModelData(int data)
      Sets the custom model data for this item.
      Parameters:
      data - The custom model data value
      Returns:
      This builder for chaining

    • unbreakable

      @NotNull public @NotNull ItemBuilder unbreakable(boolean unbreakable)
      Sets whether this item is unbreakable.
      Parameters:
      unbreakable - true to make unbreakable
      Returns:
      This builder for chaining

    • glow

      @NotNull public @NotNull ItemBuilder glow(boolean glow)
      Sets whether this item has a glow effect.

      If true and no enchantments are present, a dummy enchantment will be added with HIDE_ENCHANTS flag.

      Parameters:
      glow - true to enable glow
      Returns:
      This builder for chaining

    • slot

      @NotNull public @NotNull ItemBuilder slot(int slot)
      Sets the preferred inventory slot for this item.
      Parameters:
      slot - The slot index (0-8 for hotbar, -1 for no preference)
      Returns:
      This builder for chaining

    • enabled

      @NotNull public @NotNull ItemBuilder enabled(boolean enabled)
      Sets whether this item is enabled.
      Parameters:
      enabled - true to enable
      Returns:
      This builder for chaining

    • addonId

      @NotNull public @NotNull ItemBuilder addonId(@NotNull @NotNull String addonId)
      Sets the addon ID that owns this item.
      Parameters:
      addonId - The addon identifier
      Returns:
      This builder for chaining

    • customField

      @NotNull public @NotNull ItemBuilder customField(@NotNull @NotNull String key, @Nullable @Nullable Object value)
      Adds a custom metadata field to this item.
      Parameters:
      key - The field key
      value - The field value (should be serializable)
      Returns:
      This builder for chaining

    • copy

      @NotNull public @NotNull ItemBuilder copy()
      Creates a copy of this builder.
      Returns:
      A new ItemBuilder with the same configuration

    • getId

      @Nullable public @Nullable String getId()

    • getMaterial

      @NotNull public @NotNull org.bukkit.Material getMaterial()

    • getExternal

      @Nullable public @Nullable String getExternal()

    • getDisplayName

      @Nullable public @Nullable String getDisplayName()

    • getLore

      @NotNull public @NotNull List<String> getLore()

    • getAmount

      public int getAmount()

    • getEnchantments

      @NotNull public @NotNull Map<org.bukkit.enchantments.Enchantment,Integer> getEnchantments()

    • getFlags

      @NotNull public @NotNull Set<org.bukkit.inventory.ItemFlag> getFlags()

    • getCustomModelData

      public int getCustomModelData()

    • isUnbreakable

      public boolean isUnbreakable()

    • isGlow

      public boolean isGlow()

    • getSlot

      public int getSlot()

    • isEnabled

      public boolean isEnabled()

    • getAddonId

      @Nullable public @Nullable String getAddonId()

    • getCustomFields

      @NotNull public @NotNull Map<String,Object> getCustomFields()

    • validate

      public void validate() throws IllegalStateException
      Validates that this builder has all required fields set correctly.
      Throws:
      IllegalStateException - if the builder is not valid

    • isValid

      public boolean isValid()
      Checks if this builder is valid without throwing an exception.
      Returns:
      true if the builder has all required fields

    • toString

      public String toString()
      Overrides:
      toString in class Object