Package com.kamikazejam.kamicommon.item

Interface IBuilder<T extends IBuilder<T>>

All Superinterfaces:
Cloneable
All Known Implementing Classes:
ItemBuilder
public sealed interface IBuilder<T extends IBuilder<T>> extends Cloneable permits ItemBuilder

  • Method Summary

    Modifier and Type
    Method
    Description
    T
    addGlow()
    PATCH FUNCTION - Sets whether the item should have an added glow effect.

    Clear this patch by calling removeGlow().
    T
    addItemFlag(@NotNull com.cryptomorin.xseries.XItemFlag flag)
    PATCH FUNCTION - Adds an item flag to the item.

    Remove an item flag via removeItemFlag(XItemFlag).
    T
    addItemFlags(@NotNull Collection<com.cryptomorin.xseries.XItemFlag> flags)
    PATCH FUNCTION - Adds several item flags to the item.

    Remove an item flag via removeItemFlag(XItemFlag).
    default T
    addLoreComponents(@NotNull VersionedComponent... lines)
    PATCH FUNCTION - Appends additional lines to the current lore.
    If no lore patch is currently set, this will create a new lore patch with the provided lines.
    If a lore patch is already set, the new lines will be added to the end of the existing lore.

    Colors are assumed to be already handled in the components.
    Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).
    T
    addLoreComponents(@NotNull List<@NotNull VersionedComponent> lines)
    PATCH FUNCTION - Appends additional lines to the current lore.
    If no lore patch is currently set, this will create a new lore patch with the provided lines.
    If a lore patch is already set, the new lines will be added to the end of the existing lore.

    Colors are assumed to be already handled in the components.
    Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).
    default T
    addLoreLines(@NotNull String... lines)
    Deprecated.
    As of 5.0.0-alpha.26, replaced by addLoreComponents(VersionedComponent...)
    default T
    addLoreLines(@NotNull List<@NotNull String> lines)
    Deprecated.
    As of 5.0.0-alpha.26, replaced by addLoreComponents(List)
    default @NotNull ItemStack
    build()
    Compiles the patches, applying them on top of the prototype.
    @NotNull ItemStack
    build(@Nullable Player viewer)
    Compiles the patches, applying them on top of the prototype.
    @NotNull ItemBuilder
    clone()
     
    default @NotNull ItemBuilder
    cloneWithNewPrototype(@NotNull com.cryptomorin.xseries.XMaterial newPrototype)
    Create a clone of this builder with all the same patches, but a different prototype ItemStack.
    This method uses XMaterial.parseItem() to convert the XMaterial to an ItemStack.
    default @NotNull ItemBuilder
    cloneWithNewPrototype(@NotNull Material newPrototype)
    Create a clone of this builder with all the same patches, but a different prototype ItemStack.
    This method uses XMaterial.matchXMaterial(Material) to convert the Material to an XMaterial,
    then uses XMaterial.parseItem() to convert that to an ItemStack.
    @NotNull ItemBuilder
    cloneWithNewPrototype(@NotNull ItemStack newPrototype)
    Create a clone of this builder with all the same patches, but a different prototype ItemStack.
    @Nullable VersionedComponent
    customName()
    Get the custom display name for the item.
    Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).

    If the patch name is null (not set), the prototype's name will be returned (if available).
    default T
    disableGlow()
    Alias of removeGlow().
    default @Nullable VersionedComponent
    displayName()
    Get the custom display name for the item.
    Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).

    If the patch name is null (not set), the prototype's name will be returned (if available).
    T
    displayName(@NotNull VersionedComponent name)
    PATCH FUNCTION - Applies a custom display name for the item.
    Colors are assumed to be already handled in the component.
    Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).

    Clear this patch by calling resetName().
    int
    getAmount()
    Get the amount of items in the stack.
    Range: 1 to ItemStack.getMaxStackSize() (inclusive) of the prototype.

    If the patch amount is null (not set), the prototype's amount is returned.
    int
    getDamage()
    Get the damage of a damageable item, or 0 if not damageable / undamaged.

    NOTE: This will always return 0 if willUseDamage() returns false.
    int
    getEnchantmentLevel(@NotNull com.cryptomorin.xseries.XEnchantment enchant)
    Get the level of an enchantment on the item, or 0 if the item does not have this enchantment.

    If the patch does not specify a level for this enchantment, the prototype's value will be returned.
    @NotNull Map<com.cryptomorin.xseries.XEnchantment,Integer>
    getEnchantments()
    Get a map of ALL enchantments on the item.

    This is the combination of the prototype's enchantments and the patch enchantment overrides.
    This map is never null, but can be empty if no enchantments are present on the prototype or patch.
    @NotNull Set<com.cryptomorin.xseries.XItemFlag>
    getItemFlags()
    Get a set of ALL item flags on the item.

    This is the combination of the prototype's item flags and the patch item flag overrides.
    This set is never null, but can be empty if no item flags are present on the prototype or patch.
    default @Nullable List<@NotNull String>
    getLore()
    Deprecated.
    As of 5.0.0-alpha.26, replaced by lore() which returns components.
    default @NotNull com.cryptomorin.xseries.XMaterial
    getMaterial()
    Get the XMaterial of the prototype item this builder is based on.

    This is a convenience method, equivalent to calling XMaterial.matchXMaterial(ItemStack) on the prototype.
    default @Nullable String
    getName()
    Deprecated.
    As of 5.0.0-alpha.26, replaced by displayName() which returns a component.
    @NotNull ItemStack
    getPrototype()
    Get the prototype ItemStack this builder is based on.

    The prototype is never modified, it is immutable, and accessed via this method.
    Use build() to get the final version of the item with all patches applied.
    @Nullable String
    getSkullOwner()
    Get the owner of a player head item, or null if not set / not a player head.

    NOTE: This will always return null if willUseSkullOwner() returns false.
    boolean
    hasGlow()
    Get if the item has an added glow effect.

    If the patch glow is null (not set), the prototype's glow value will be returned.
    boolean
    hasItemFlag(@NotNull com.cryptomorin.xseries.XItemFlag flag)
    Get if the item has the specified item flag.

    If the patch does not specify the presence of this flag, the prototype's value will be returned.
    default T
    hideAttributes()
    PATCH FUNCTION HELPER - Convenience method to hide common item attributes by adding multiple item flags.
    This method adds the following XItemFlags to the item:
    - XItemFlag.HIDE_ATTRIBUTES
    - XItemFlag.HIDE_ENCHANTS
    - XItemFlag.HIDE_PLACED_ON
    - XItemFlag.HIDE_UNBREAKABLE
    - XItemFlag.HIDE_ADDITIONAL_TOOLTIP

    This is equivalent to calling addItemFlag(XItemFlag) for each of the above flags.
    default boolean
    isAddGlow()
    Alias of hasGlow().
    boolean
    isUnbreakable()
    Get if the item is unbreakable or not.

    If the patch unbreakable is null (not set), the prototype's unbreakable value will be returned.
    @Nullable List<@NotNull VersionedComponent>
    lore()
    Get the custom lore for the item.

    If the patch lore is null (not set), the prototype's lore will be returned (if available).
    default T
    lore(@NotNull VersionedComponent... lines)
    PATCH FUNCTION - Sets the custom lore for the item.
    Colors are assumed to be already handled in the components.
    Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).

    Clear this patch by calling resetLore().
    T
    lore(@NotNull List<@NotNull VersionedComponent> lines)
    PATCH FUNCTION - Sets the custom lore for the item.
    Colors are assumed to be already handled in the components.
    Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).

    Clear this patch by calling resetLore().
    T
    removeEnchantment(@NotNull com.cryptomorin.xseries.XEnchantment enchant)
    PATCH FUNCTION - Remove an enchantment from the item.

    Other Methods:
    - ADD or UPDATE an enchantment via setEnchantment(XEnchantment, int)
    - RESET an enchantment (remove patch) via resetEnchantment(XEnchantment)
    T
    removeGlow()
    PATCH FUNCTION - Removes the glow effect patch, the Builder will then use the prototype's value.

    NOTE: The prototype's glow value is now used by the builder, this only removes any existing glow patch.
    NOTE: Even when the glow patch is removed, the item may still glow if the prototype has enchantments or a glow effect.
    T
    removeItemFlag(@NotNull com.cryptomorin.xseries.XItemFlag flag)
    PATCH FUNCTION - Removes an item flag from the item.

    Add an item flag via addItemFlag(XItemFlag).
    T
    removeItemFlags(@NotNull Collection<com.cryptomorin.xseries.XItemFlag> flags)
    PATCH FUNCTION - Removes several item flags from the item.

    Add an item flag via addItemFlag(XItemFlag).
    default T
    removeLore()
    PATCH FUNCTION - Sets the lore to an empty list, effectively removing all lore from the item.
    This is equivalent to calling setLore(List) with an empty list.

    This differs from resetLore() which clears the patch and uses the prototype's lore.
    default T
    replaceBoth(@NotNull String find, @NotNull VersionedComponent replacement)
    PATCH PROPERTY HELPER - Convenience method to replace a substring in both name and lore.
    This is equivalent to calling replaceName(String, VersionedComponent) followed by replaceLore(String, VersionedComponent).

    This transformation only applies to existing patches, if no name or lore patches are set those won't be affected.
    It does NOT modify the prototype's name or lore.
    default T
    replaceBoth(@NotNull String find, @NotNull String replacement)
    Deprecated.
    As of 5.0.0-alpha.26, replaced by replaceBoth(String, VersionedComponent) which supports components.
    default T
    replaceBothPAPI()
    Alias of replaceBothPAPI(OfflinePlayer) with a null player.
    default T
    replaceBothPAPI(@Nullable OfflinePlayer player)
    PATCH PROPERTY HELPER - Convenience method to replace PlaceholderAPI placeholders in both name and lore.
    This is equivalent to calling replaceNamePAPI(OfflinePlayer) followed by replaceLorePAPI(OfflinePlayer).

    This transformation only applies to existing patches, if no name or lore patches are set those won't be affected.
    It does NOT modify the prototype's name or lore.
    T
    replaceLore(@NotNull String find, @NotNull VersionedComponent replacement)
    PATCH PROPERTY HELPER - Replaces all occurrences of a substring in each lore line with another component.
    This transformation only applies to the lore patch, if no lore patch is set this does nothing.
    It does NOT modify the prototype's lore.

    It will serialize each lore line into mini message format, perform the replacement, then deserialize it back to a component.
    default T
    replaceLore(@NotNull String find, @NotNull String replacement)
    Deprecated.
    As of 5.0.0-alpha.26, replaced by replaceLore(String, VersionedComponent) which supports components.
    default T
    replaceLoreLine(@NotNull String find, @NotNull List<@NotNull String> replacements)
    Deprecated.
    As of 5.0.0-alpha.26, replaced by replaceLoreLineComponent(String, List) which supports components.
    default T
    replaceLoreLineComponent(@NotNull String find, @NotNull List<@NotNull VersionedComponent> replacements)
    PATCH PROPERTY HELPER - Searches for a substring in the lore and replaces that entire line with replacement lines.
    This transformation only applies to the lore patch, if no lore patch is set this does nothing.
    It does NOT modify the prototype's lore.

    For each line, it checks if the component plain text OR the component mini message contains the find string.
    If either matches, that line is substituted with the replacement lines.
    T
    replaceLoreLineComponent(@NotNull Predicate<@NotNull VersionedComponent> filter, @NotNull List<@NotNull VersionedComponent> replacements)
    PATCH PROPERTY HELPER - Replaces all occurrences of lines matching the given predicate in the lore with replacement lines.
    This transformation only applies to the lore patch, if no lore patch is set this does nothing.
    It does NOT modify the prototype's lore.

    For each line, it checks if the predicate returns true, and if so that line is replaced with the replacement lines.
    default T
    replaceLorePAPI()
    Alias of replaceLorePAPI(OfflinePlayer) with a null player.
    T
    replaceLorePAPI(@Nullable OfflinePlayer player)
    PATCH PROPERTY HELPER - Replaces all PlaceholderAPI placeholders in the lore with their respective values.
    This transformation only applies to the lore patch, if no lore patch is set this does nothing.
    It does NOT modify the prototype's lore.
    T
    replaceName(@NotNull String find, @NotNull VersionedComponent replacement)
    PATCH PROPERTY HELPER - Replaces all occurrences of a substring in the name with another component.
    This transformation only applies to the name patch, if no name patch is set this does nothing.
    It does NOT modify the prototype's name.
    default T
    replaceName(@NotNull String find, @NotNull String replacement)
    Deprecated.
    As of 5.0.0-alpha.26, replaced by replaceName(String, VersionedComponent) which supports components.
    default T
    replaceNamePAPI()
    Alias of replaceNamePAPI(OfflinePlayer) with a null player.
    T
    replaceNamePAPI(@Nullable OfflinePlayer player)
    PATCH PROPERTY HELPER - Replaces all PlaceholderAPI placeholders in the name with their respective values.
    This transformation only applies to the name patch, if no name patch is set this does nothing.
    It does NOT modify the prototype's name.
    T
    resetAllEnchantments()
    PATCH FUNCTION - Clears all enchantment patches, the Builder will then use the prototype's values.

    NOTE: The prototype's enchantments will still be applied, this only clears the patches.
    T
    resetAllItemFlags()
    PATCH FUNCTION - Clears all item flag patches, the Builder will then use the prototype's values.

    NOTE: The prototype's item flags will still be applied, this only clears the patches.
    T
    resetAmount()
    PATCH FUNCTION - Clears the amount patch, the Builder will then use the prototype's value.

    NOTE: The prototype's amount is now used by the builder, this only removes any existing amount patch.
    T
    resetDamage()
    PATCH FUNCTION - Clears the damage patch, the Builder will then use the prototype's value.

    NOTE: This function has no effect on the item unless willUseDamage() returns true, otherwise the item will be unaffected and getDamage() will always return 0.

    NOTE: The prototype's damage is now used by the builder (if applicable), this only removes any existing damage patch.
    T
    resetEnchantment(@NotNull com.cryptomorin.xseries.XEnchantment enchant)
    PATCH FUNCTION - Reset an enchantment patch, the Builder will then use the prototype's value for this enchantment.

    Other Methods:
    - ADD or UPDATE an enchantment via setEnchantment(XEnchantment, int)
    - REMOVE an enchantment via removeEnchantment(XEnchantment)
    T
    resetItemFlag(@NotNull com.cryptomorin.xseries.XItemFlag flag)
    PATCH FUNCTION - Resets an item flag patch, the Builder will then use the prototype's value for this flag.

    Other Methods:
    - ADD an item flag via addItemFlag(XItemFlag)
    - REMOVE an item flag via removeItemFlag(XItemFlag)
    T
    resetLore()
    PATCH FUNCTION - Clears the lore patch, the Builder will then use the prototype's value.

    NOTE: The prototype's lore is now used by the builder, this only removes any existing lore patch.
    T
    resetName()
    PATCH FUNCTION - Clears the name patch, the Builder will then use the prototype's value.

    NOTE: The prototype's name is now used by the builder, this only removes any existing name patch.
    T
    resetSkullOwner()
    PATCH FUNCTION - Clears the skull owner patch, the Builder will then use the prototype's value.

    NOTE: This function has no effect on the item unless willUseSkullOwner() returns true, otherwise the item will be unaffected and getSkullOwner() will always return null.

    NOTE: The prototype's skull owner is now used by the builder (if applicable), this only removes any existing skull owner patch.
    T
    resetUnbreakable()
    PATCH FUNCTION - Clears the unbreakable patch, the Builder will then use the prototype's value.

    NOTE: The prototype's unbreakable value is now used by the builder, this only removes any existing unbreakable patch.
    T
    setAmount(int amount)
    PATCH FUNCTION - Sets the amount of items in the stack.
    Range: 1 to ItemStack.getMaxStackSize() (inclusive) of the prototype.

    Clear this patch by calling resetAmount().
    T
    setDamage(int damage)
    PATCH FUNCTION - Sets the damage of a damageable item.

    NOTE: This function has no effect on the item unless willUseDamage() returns true, otherwise the item will be unaffected and getDamage() will always return 0.

    Clear this patch by calling resetDamage().
    default T
    setDisplayName(@NotNull String name)
    Deprecated.
    As of 5.0.0-alpha.26, replaced by displayName(VersionedComponent).
    default T
    setDurability(int dur)
    Deprecated.
    As of 5.0.0-alpha.17, replaced by setDamage(int).
    default T
    setDurability(short dur)
    Deprecated.
    As of 5.0.0-alpha.17, replaced by setDamage(int).
    T
    setEnchantment(@NotNull com.cryptomorin.xseries.XEnchantment enchant, int level)
    PATCH FUNCTION - Sets the level of an enchantment on the item.

    Other Methods:
    - REMOVE an enchantment via removeEnchantment(XEnchantment)
    - RESET an enchantment (remove patch) via resetEnchantment(XEnchantment)
    T
    setEnchantments(@NotNull Map<com.cryptomorin.xseries.XEnchantment,Integer> enchantments)
    PATCH FUNCTION - Sets the level of several enchantments on the item.

    Other Methods:
    - REMOVE an enchantment via removeEnchantment(XEnchantment)
    - RESET an enchantment (remove patch) via resetEnchantment(XEnchantment)
    default T
    setGlow(boolean glow)
    PATCH FUNCTION - Toggle the glow effect patch on or off.

    default T
    setItemFlag(@NotNull com.cryptomorin.xseries.XItemFlag flag, boolean present)
    PATCH FUNCTION - Sets the presence of an item flag on the item.

    default T
    setLore(@NotNull String... line)
    Deprecated.
    As of 5.0.0-alpha.26, replaced by lore(VersionedComponent...).
    default T
    setLore(@NotNull List<@NotNull String> lore)
    Deprecated.
    As of 5.0.0-alpha.26, replaced by lore(List)
    default T
    setName(@NotNull String name)
    Deprecated.
    As of 5.0.0-alpha.26, replaced by displayName(VersionedComponent).
    T
    setSkullOwner(@NotNull String owner)
    PATCH FUNCTION - Sets the owner of a player head item.

    NOTE: This function has no effect on the item unless willUseSkullOwner() returns true, otherwise the item will be unaffected and getSkullOwner() will always return null.

    Clear this patch by calling resetSkullOwner().
    T
    setUnbreakable(boolean unbreakable)
    PATCH FUNCTION - Sets if the item is unbreakable or not.

    Clear this patch by calling resetUnbreakable().
    default @NotNull ItemStack
    toItemStack()
    Alias of build().
    default @NotNull ItemStack
    toItemStack(@Nullable Player player)
    Alias of build(Player).
    boolean
    willUseDamage()
    Check if the prototype item supports setting damage (is damageable).

    If this returns true, then the following methods will modify the item:
    - setDamage(int)
    - resetDamage()
    - getDamage()
    If this returns false, calling those methods have no effect and getDamage() will always return 0.
    boolean
    willUseSkullOwner()
    Check if the prototype item supports setting a skull owner (is a player head).

    If this returns true, then the following methods will modify the item:
    - setSkullOwner(String)
    - resetSkullOwner()
    - getSkullOwner()
    If this returns false, calling those methods have no effect and getSkullOwner() will always return null.

  • Method Details

    • getPrototype

      @NotNull @NotNull ItemStack getPrototype()
      Get the prototype ItemStack this builder is based on.

      The prototype is never modified, it is immutable, and accessed via this method.
      Use build() to get the final version of the item with all patches applied.
      Returns:
      The prototype ItemStack this builder is based on.

    • getMaterial

      @NotNull default @NotNull com.cryptomorin.xseries.XMaterial getMaterial()
      Get the XMaterial of the prototype item this builder is based on.

      This is a convenience method, equivalent to calling XMaterial.matchXMaterial(ItemStack) on the prototype.
      Returns:
      The XMaterial of the prototype item this builder is based on.

    • setAmount

      @NotNull T setAmount(int amount)
      PATCH FUNCTION - Sets the amount of items in the stack.
      Range: 1 to ItemStack.getMaxStackSize() (inclusive) of the prototype.

      Clear this patch by calling resetAmount().
      (If the amount is out of range, it will be clamped within the valid range.)
      Returns:
      This builder, for chaining

    • resetAmount

      @NotNull T resetAmount()
      PATCH FUNCTION - Clears the amount patch, the Builder will then use the prototype's value.

      NOTE: The prototype's amount is now used by the builder, this only removes any existing amount patch.
      Returns:
      This builder, for chaining

    • setDamage

      @NotNull T setDamage(int damage)
      PATCH FUNCTION - Sets the damage of a damageable item.

      NOTE: This function has no effect on the item unless willUseDamage() returns true, otherwise the item will be unaffected and getDamage() will always return 0.

      Clear this patch by calling resetDamage().
      Parameters:
      damage - The damage value to set (0 = undamaged)
      Returns:
      This builder, for chaining

    • setDurability

      @Deprecated(since="5.0.0-alpha.17") @NotNull default T setDurability(short dur)
      Deprecated.
      As of 5.0.0-alpha.17, replaced by setDamage(int).
      Alias of setDamage(int).

    • setDurability

      @Deprecated(since="5.0.0-alpha.17") @NotNull default T setDurability(int dur)
      Deprecated.
      As of 5.0.0-alpha.17, replaced by setDamage(int).
      Alias of setDamage(int).

    • resetDamage

      @NotNull T resetDamage()
      PATCH FUNCTION - Clears the damage patch, the Builder will then use the prototype's value.

      NOTE: This function has no effect on the item unless willUseDamage() returns true, otherwise the item will be unaffected and getDamage() will always return 0.

      NOTE: The prototype's damage is now used by the builder (if applicable), this only removes any existing damage patch.
      Returns:
      This builder, for chaining

    • setName

      @Deprecated @NotNull default T setName(@NotNull @NotNull String name)
      Deprecated.
      As of 5.0.0-alpha.26, replaced by displayName(VersionedComponent).
      Alias of setDisplayName(String).
      Returns:
      This builder, for chaining

    • setDisplayName

      @Deprecated @NotNull default T setDisplayName(@NotNull @NotNull String name)
      Deprecated.
      As of 5.0.0-alpha.26, replaced by displayName(VersionedComponent).
      PATCH FUNCTION - Applies a custom display name for the item.
      Colors are translated automatically via LegacyColors.t(String).
      Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).

      Clear this patch by calling resetName().
      Returns:
      This builder, for chaining

    • displayName

      @NotNull T displayName(@NotNull @NotNull VersionedComponent name)
      PATCH FUNCTION - Applies a custom display name for the item.
      Colors are assumed to be already handled in the component.
      Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).

      Clear this patch by calling resetName().
      Returns:
      This builder, for chaining

    • resetName

      @NotNull T resetName()
      PATCH FUNCTION - Clears the name patch, the Builder will then use the prototype's value.

      NOTE: The prototype's name is now used by the builder, this only removes any existing name patch.
      Returns:
      This builder, for chaining

    • setLore

      @Deprecated @NotNull default T setLore(@NotNull @NotNull String... line)
      Deprecated.
      As of 5.0.0-alpha.26, replaced by lore(VersionedComponent...).
      PATCH FUNCTION - Sets the custom lore for the item.
      Colors are translated automatically via LegacyColors.t(String).
      Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).

      Clear this patch by calling resetLore().
      Returns:
      This builder, for chaining

    • setLore

      @Deprecated @NotNull default T setLore(@NotNull @NotNull List<@NotNull String> lore)
      Deprecated.
      As of 5.0.0-alpha.26, replaced by lore(List)
      PATCH FUNCTION - Sets the custom lore for the item.
      Colors are translated automatically via LegacyColors.t(String).
      Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).

      Clear this patch by calling resetLore().
      Returns:
      This builder, for chaining

    • lore

      @NotNull default T lore(@NotNull @NotNull VersionedComponent... lines)
      PATCH FUNCTION - Sets the custom lore for the item.
      Colors are assumed to be already handled in the components.
      Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).

      Clear this patch by calling resetLore().
      Returns:
      This builder, for chaining

    • lore

      @NotNull T lore(@NotNull @NotNull List<@NotNull VersionedComponent> lines)
      PATCH FUNCTION - Sets the custom lore for the item.
      Colors are assumed to be already handled in the components.
      Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).

      Clear this patch by calling resetLore().
      Returns:
      This builder, for chaining

    • resetLore

      @NotNull T resetLore()
      PATCH FUNCTION - Clears the lore patch, the Builder will then use the prototype's value.

      NOTE: The prototype's lore is now used by the builder, this only removes any existing lore patch.
      Returns:
      This builder, for chaining

    • removeLore

      @NotNull default T removeLore()
      PATCH FUNCTION - Sets the lore to an empty list, effectively removing all lore from the item.
      This is equivalent to calling setLore(List) with an empty list.

      This differs from resetLore() which clears the patch and uses the prototype's lore.
      Returns:
      This builder, for chaining

    • addLoreLines

      @Deprecated @NotNull default T addLoreLines(@NotNull @NotNull List<@NotNull String> lines)
      Deprecated.
      As of 5.0.0-alpha.26, replaced by addLoreComponents(List)
      PATCH FUNCTION - Appends additional lines to the current lore.
      If no lore patch is currently set, this will create a new lore patch with the provided lines.
      If a lore patch is already set, the new lines will be added to the end of the existing lore.

      Colors are translated automatically via LegacyColors.t(String).
      Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).
      Parameters:
      lines - The lore lines to append
      Returns:
      This builder, for chaining

    • addLoreLines

      @Deprecated @NotNull default T addLoreLines(@NotNull @NotNull String... lines)
      Deprecated.
      As of 5.0.0-alpha.26, replaced by addLoreComponents(VersionedComponent...)
      PATCH FUNCTION - Appends additional lines to the current lore.
      If no lore patch is currently set, this will create a new lore patch with the provided lines.
      If a lore patch is already set, the new lines will be added to the end of the existing lore.

      Colors are translated automatically via LegacyColors.t(String).
      Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).
      Parameters:
      lines - The lore lines to append
      Returns:
      This builder, for chaining

    • addLoreComponents

      @NotNull T addLoreComponents(@NotNull @NotNull List<@NotNull VersionedComponent> lines)
      PATCH FUNCTION - Appends additional lines to the current lore.
      If no lore patch is currently set, this will create a new lore patch with the provided lines.
      If a lore patch is already set, the new lines will be added to the end of the existing lore.

      Colors are assumed to be already handled in the components.
      Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).
      Parameters:
      lines - The lore lines to append
      Returns:
      This builder, for chaining

    • addLoreComponents

      @NotNull default T addLoreComponents(@NotNull @NotNull VersionedComponent... lines)
      PATCH FUNCTION - Appends additional lines to the current lore.
      If no lore patch is currently set, this will create a new lore patch with the provided lines.
      If a lore patch is already set, the new lines will be added to the end of the existing lore.

      Colors are assumed to be already handled in the components.
      Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).
      Parameters:
      lines - The lore lines to append
      Returns:
      This builder, for chaining

    • setUnbreakable

      @NotNull T setUnbreakable(boolean unbreakable)
      PATCH FUNCTION - Sets if the item is unbreakable or not.

      Clear this patch by calling resetUnbreakable().
      Returns:
      This builder, for chaining

    • resetUnbreakable

      @NotNull T resetUnbreakable()
      PATCH FUNCTION - Clears the unbreakable patch, the Builder will then use the prototype's value.

      NOTE: The prototype's unbreakable value is now used by the builder, this only removes any existing unbreakable patch.
      Returns:
      This builder, for chaining

    • addItemFlag

      @NotNull T addItemFlag(@NotNull @NotNull com.cryptomorin.xseries.XItemFlag flag)
      PATCH FUNCTION - Adds an item flag to the item.

      Remove an item flag via removeItemFlag(XItemFlag).
      Returns:
      This builder, for chaining

    • addItemFlags

      @NotNull T addItemFlags(@NotNull @NotNull Collection<com.cryptomorin.xseries.XItemFlag> flags)
      PATCH FUNCTION - Adds several item flags to the item.

      Remove an item flag via removeItemFlag(XItemFlag).
      Returns:
      This builder, for chaining

    • removeItemFlag

      @NotNull T removeItemFlag(@NotNull @NotNull com.cryptomorin.xseries.XItemFlag flag)
      PATCH FUNCTION - Removes an item flag from the item.

      Add an item flag via addItemFlag(XItemFlag).
      Returns:
      This builder, for chaining

    • removeItemFlags

      @NotNull T removeItemFlags(@NotNull @NotNull Collection<com.cryptomorin.xseries.XItemFlag> flags)
      PATCH FUNCTION - Removes several item flags from the item.

      Add an item flag via addItemFlag(XItemFlag).
      Returns:
      This builder, for chaining

    • setItemFlag

      @NotNull default T setItemFlag(@NotNull @NotNull com.cryptomorin.xseries.XItemFlag flag, boolean present)
      PATCH FUNCTION - Sets the presence of an item flag on the item.

      Parameters:
      present - If true, the flag will be added, if false it will be removed.
      Returns:
      This builder, for chaining

    • resetItemFlag

      @NotNull T resetItemFlag(@NotNull @NotNull com.cryptomorin.xseries.XItemFlag flag)
      PATCH FUNCTION - Resets an item flag patch, the Builder will then use the prototype's value for this flag.

      Other Methods:
      - ADD an item flag via addItemFlag(XItemFlag)
      - REMOVE an item flag via removeItemFlag(XItemFlag)
      Returns:
      This builder, for chaining

    • resetAllItemFlags

      @NotNull T resetAllItemFlags()
      PATCH FUNCTION - Clears all item flag patches, the Builder will then use the prototype's values.

      NOTE: The prototype's item flags will still be applied, this only clears the patches.

    • hideAttributes

      @NotNull default T hideAttributes()
      PATCH FUNCTION HELPER - Convenience method to hide common item attributes by adding multiple item flags.
      This method adds the following XItemFlags to the item:
      - XItemFlag.HIDE_ATTRIBUTES
      - XItemFlag.HIDE_ENCHANTS
      - XItemFlag.HIDE_PLACED_ON
      - XItemFlag.HIDE_UNBREAKABLE
      - XItemFlag.HIDE_ADDITIONAL_TOOLTIP

      This is equivalent to calling addItemFlag(XItemFlag) for each of the above flags.
      Returns:
      This builder, for chaining

    • setEnchantment

      @NotNull T setEnchantment(@NotNull @NotNull com.cryptomorin.xseries.XEnchantment enchant, int level)
      PATCH FUNCTION - Sets the level of an enchantment on the item.

      Other Methods:
      - REMOVE an enchantment via removeEnchantment(XEnchantment)
      - RESET an enchantment (remove patch) via resetEnchantment(XEnchantment)
      Parameters:
      level - The level of the enchantment to set (MUST be greater than 0)
      Returns:
      This builder, for chaining

    • setEnchantments

      @NotNull T setEnchantments(@NotNull @NotNull Map<com.cryptomorin.xseries.XEnchantment,Integer> enchantments)
      PATCH FUNCTION - Sets the level of several enchantments on the item.

      Other Methods:
      - REMOVE an enchantment via removeEnchantment(XEnchantment)
      - RESET an enchantment (remove patch) via resetEnchantment(XEnchantment)
      Parameters:
      enchantments - The map of enchantments to their levels to set (all levels MUST be greater than 0)
      Returns:
      This builder, for chaining

    • removeEnchantment

      @NotNull T removeEnchantment(@NotNull @NotNull com.cryptomorin.xseries.XEnchantment enchant)
      PATCH FUNCTION - Remove an enchantment from the item.

      Other Methods:
      - ADD or UPDATE an enchantment via setEnchantment(XEnchantment, int)
      - RESET an enchantment (remove patch) via resetEnchantment(XEnchantment)
      Returns:
      This builder, for chaining

    • resetEnchantment

      @NotNull T resetEnchantment(@NotNull @NotNull com.cryptomorin.xseries.XEnchantment enchant)
      PATCH FUNCTION - Reset an enchantment patch, the Builder will then use the prototype's value for this enchantment.

      Other Methods:
      - ADD or UPDATE an enchantment via setEnchantment(XEnchantment, int)
      - REMOVE an enchantment via removeEnchantment(XEnchantment)
      Returns:
      This builder, for chaining

    • resetAllEnchantments

      @NotNull T resetAllEnchantments()
      PATCH FUNCTION - Clears all enchantment patches, the Builder will then use the prototype's values.

      NOTE: The prototype's enchantments will still be applied, this only clears the patches.
      Returns:
      This builder, for chaining

    • addGlow

      @NotNull T addGlow()
      PATCH FUNCTION - Sets whether the item should have an added glow effect.

      Clear this patch by calling removeGlow().
      Returns:
      This builder, for chaining

    • removeGlow

      @NotNull T removeGlow()
      PATCH FUNCTION - Removes the glow effect patch, the Builder will then use the prototype's value.

      NOTE: The prototype's glow value is now used by the builder, this only removes any existing glow patch.
      NOTE: Even when the glow patch is removed, the item may still glow if the prototype has enchantments or a glow effect.
      Returns:
      This builder, for chaining

    • disableGlow

      @NotNull default T disableGlow()
      Alias of removeGlow().

    • setGlow

      @NotNull default T setGlow(boolean glow)
      PATCH FUNCTION - Toggle the glow effect patch on or off.

      Parameters:
      glow - If true, the glow effect patch will be added, if false it will be removed.
      Returns:
      This builder, for chaining

    • setSkullOwner

      @NotNull T setSkullOwner(@NotNull @NotNull String owner)
      PATCH FUNCTION - Sets the owner of a player head item.

      NOTE: This function has no effect on the item unless willUseSkullOwner() returns true, otherwise the item will be unaffected and getSkullOwner() will always return null.

      Clear this patch by calling resetSkullOwner().
      Returns:
      This builder, for chaining

    • resetSkullOwner

      @NotNull T resetSkullOwner()
      PATCH FUNCTION - Clears the skull owner patch, the Builder will then use the prototype's value.

      NOTE: This function has no effect on the item unless willUseSkullOwner() returns true, otherwise the item will be unaffected and getSkullOwner() will always return null.

      NOTE: The prototype's skull owner is now used by the builder (if applicable), this only removes any existing skull owner patch.
      Returns:
      This builder, for chaining

    • getAmount

      int getAmount()
      Get the amount of items in the stack.
      Range: 1 to ItemStack.getMaxStackSize() (inclusive) of the prototype.

      If the patch amount is null (not set), the prototype's amount is returned.

    • getDamage

      int getDamage()
      Get the damage of a damageable item, or 0 if not damageable / undamaged.

      NOTE: This will always return 0 if willUseDamage() returns false.

    • willUseDamage

      boolean willUseDamage()
      Check if the prototype item supports setting damage (is damageable).

      If this returns true, then the following methods will modify the item:
      - setDamage(int)
      - resetDamage()
      - getDamage()
      If this returns false, calling those methods have no effect and getDamage() will always return 0.

    • getName

      @Deprecated @Nullable default @Nullable String getName()
      Deprecated.
      As of 5.0.0-alpha.26, replaced by displayName() which returns a component.
      Get the custom display name for the item.

      If the patch name is null (not set), the prototype's name will be returned (if available).

    • displayName

      @Nullable default @Nullable VersionedComponent displayName()
      Get the custom display name for the item.
      Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).

      If the patch name is null (not set), the prototype's name will be returned (if available).

    • customName

      @Nullable @Nullable VersionedComponent customName()
      Get the custom display name for the item.
      Placeholders are set automatically via SoftPlaceholderAPI.setPlaceholders(OfflinePlayer, String).

      If the patch name is null (not set), the prototype's name will be returned (if available).

    • getLore

      @Deprecated @Nullable default @Nullable List<@NotNull String> getLore()
      Deprecated.
      As of 5.0.0-alpha.26, replaced by lore() which returns components.
      Get the custom lore for the item.

      If the patch lore is null (not set), the prototype's lore will be returned (if available).

    • lore

      @Nullable @Nullable List<@NotNull VersionedComponent> lore()
      Get the custom lore for the item.

      If the patch lore is null (not set), the prototype's lore will be returned (if available).

    • isUnbreakable

      boolean isUnbreakable()
      Get if the item is unbreakable or not.

      If the patch unbreakable is null (not set), the prototype's unbreakable value will be returned.

    • hasItemFlag

      boolean hasItemFlag(@NotNull @NotNull com.cryptomorin.xseries.XItemFlag flag)
      Get if the item has the specified item flag.

      If the patch does not specify the presence of this flag, the prototype's value will be returned.

    • getItemFlags

      @NotNull @NotNull Set<com.cryptomorin.xseries.XItemFlag> getItemFlags()
      Get a set of ALL item flags on the item.

      This is the combination of the prototype's item flags and the patch item flag overrides.
      This set is never null, but can be empty if no item flags are present on the prototype or patch.

    • getEnchantmentLevel

      int getEnchantmentLevel(@NotNull @NotNull com.cryptomorin.xseries.XEnchantment enchant)
      Get the level of an enchantment on the item, or 0 if the item does not have this enchantment.

      If the patch does not specify a level for this enchantment, the prototype's value will be returned.

    • getEnchantments

      @NotNull @NotNull Map<com.cryptomorin.xseries.XEnchantment,Integer> getEnchantments()
      Get a map of ALL enchantments on the item.

      This is the combination of the prototype's enchantments and the patch enchantment overrides.
      This map is never null, but can be empty if no enchantments are present on the prototype or patch.

    • hasGlow

      boolean hasGlow()
      Get if the item has an added glow effect.

      If the patch glow is null (not set), the prototype's glow value will be returned.

    • isAddGlow

      default boolean isAddGlow()
      Alias of hasGlow().

    • getSkullOwner

      @Nullable @Nullable String getSkullOwner()
      Get the owner of a player head item, or null if not set / not a player head.

      NOTE: This will always return null if willUseSkullOwner() returns false.

    • willUseSkullOwner

      boolean willUseSkullOwner()
      Check if the prototype item supports setting a skull owner (is a player head).

      If this returns true, then the following methods will modify the item:
      - setSkullOwner(String)
      - resetSkullOwner()
      - getSkullOwner()
      If this returns false, calling those methods have no effect and getSkullOwner() will always return null.

    • build

      @NotNull default @NotNull ItemStack build()
      Compiles the patches, applying them on top of the prototype.
      Returns:
      The final ItemStack with all patches applied.

    • build

      @NotNull @NotNull ItemStack build(@Nullable @Nullable Player viewer)
      Compiles the patches, applying them on top of the prototype.
      Parameters:
      viewer - The Player viewing this item, for PlaceholderAPI support. (Can be null)
      Returns:
      The final ItemStack with all patches applied.

    • toItemStack

      @NotNull default @NotNull ItemStack toItemStack()
      Alias of build().
      Returns:
      The final ItemStack with all patches applied.

    • toItemStack

      @NotNull default @NotNull ItemStack toItemStack(@Nullable @Nullable Player player)
      Alias of build(Player).
      Parameters:
      player - The Player viewing this item, for PlaceholderAPI support. (Can be null)
      Returns:
      The final ItemStack with all patches applied.

    • replaceName

      @Deprecated @NotNull default T replaceName(@NotNull @NotNull String find, @NotNull @NotNull String replacement)
      Deprecated.
      As of 5.0.0-alpha.26, replaced by replaceName(String, VersionedComponent) which supports components.
      PATCH PROPERTY HELPER - Replaces all occurrences of a substring in the name with another string.
      This transformation only applies to the name patch, if no name patch is set this does nothing.
      It does NOT modify the prototype's name.
      Parameters:
      find - The substring to find
      replacement - The sub
      Returns:
      This builder, for chaining

    • replaceName

      @NotNull T replaceName(@NotNull @NotNull String find, @NotNull @NotNull VersionedComponent replacement)
      PATCH PROPERTY HELPER - Replaces all occurrences of a substring in the name with another component.
      This transformation only applies to the name patch, if no name patch is set this does nothing.
      It does NOT modify the prototype's name.
      It will serialize the name into message format, perform the replacement, then deserialize it back to a component.
      Parameters:
      find - The substring to find
      replacement - The component to replace each occurrence with
      Returns:
      This builder, for chaining

    • replaceNamePAPI

      @NotNull default T replaceNamePAPI()
      Alias of replaceNamePAPI(OfflinePlayer) with a null player.

    • replaceNamePAPI

      @NotNull T replaceNamePAPI(@Nullable @Nullable OfflinePlayer player)
      PATCH PROPERTY HELPER - Replaces all PlaceholderAPI placeholders in the name with their respective values.
      This transformation only applies to the name patch, if no name patch is set this does nothing.
      It does NOT modify the prototype's name.
      Parameters:
      player - The player to use for PlaceholderAPI replacements, or null to skip player-specific placeholders
      Returns:
      This builder, for chaining

    • replaceLoreLine

      @Deprecated @NotNull default T replaceLoreLine(@NotNull @NotNull String find, @NotNull @NotNull List<@NotNull String> replacements)
      Deprecated.
      As of 5.0.0-alpha.26, replaced by replaceLoreLineComponent(String, List) which supports components.
      PATCH PROPERTY HELPER - Searches for a substring in the lore and replaces that entire line with replacement lines.
      This transformation only applies to the lore patch, if no lore patch is set this does nothing.
      It does NOT modify the prototype's lore.

      For each line, it checks if the component plain text OR the component mini message contains the find string.
      If either matches, that line is substituted with the replacement lines.
      Parameters:
      find - The string to search for in the lore (color codes will be stripped for comparison)
      replacements - The lines to swap in, in place of the entire line containing the find string
      Returns:
      This builder, for chaining

    • replaceLoreLineComponent

      @NotNull default T replaceLoreLineComponent(@NotNull @NotNull String find, @NotNull @NotNull List<@NotNull VersionedComponent> replacements)
      PATCH PROPERTY HELPER - Searches for a substring in the lore and replaces that entire line with replacement lines.
      This transformation only applies to the lore patch, if no lore patch is set this does nothing.
      It does NOT modify the prototype's lore.

      For each line, it checks if the component plain text OR the component mini message contains the find string.
      If either matches, that line is substituted with the replacement lines.
      Parameters:
      find - The string to search for in the lore
      replacements - The lines to swap in, in place of the entire line containing the find string
      Returns:
      This builder, for chaining

    • replaceLoreLineComponent

      @NotNull T replaceLoreLineComponent(@NotNull @NotNull Predicate<@NotNull VersionedComponent> filter, @NotNull @NotNull List<@NotNull VersionedComponent> replacements)
      PATCH PROPERTY HELPER - Replaces all occurrences of lines matching the given predicate in the lore with replacement lines.
      This transformation only applies to the lore patch, if no lore patch is set this does nothing.
      It does NOT modify the prototype's lore.

      For each line, it checks if the predicate returns true, and if so that line is replaced with the replacement lines.
      Parameters:
      filter - The predicate to test each lore line against, if it returns true that line is replaced
      replacements - The lines to swap in, in place of the entire line containing the find string
      Returns:
      This builder, for chaining

    • replaceLore

      @Deprecated @NotNull default T replaceLore(@NotNull @NotNull String find, @NotNull @NotNull String replacement)
      Deprecated.
      As of 5.0.0-alpha.26, replaced by replaceLore(String, VersionedComponent) which supports components.
      PATCH PROPERTY HELPER - Replaces all occurrences of a substring in each lore line with another string.
      This transformation only applies to the lore patch, if no lore patch is set this does nothing.
      It does NOT modify the prototype's lore.
      Parameters:
      find - The substring to find in each lore line
      replacement - The string to replace each occurrence with
      Returns:
      This builder, for chaining

    • replaceLore

      T replaceLore(@NotNull @NotNull String find, @NotNull @NotNull VersionedComponent replacement)
      PATCH PROPERTY HELPER - Replaces all occurrences of a substring in each lore line with another component.
      This transformation only applies to the lore patch, if no lore patch is set this does nothing.
      It does NOT modify the prototype's lore.

      It will serialize each lore line into mini message format, perform the replacement, then deserialize it back to a component.
      Parameters:
      find - The substring to find in each lore line
      replacement - The component to replace each occurrence with
      Returns:
      This builder, for chaining

    • replaceLorePAPI

      @NotNull default T replaceLorePAPI()
      Alias of replaceLorePAPI(OfflinePlayer) with a null player.

    • replaceLorePAPI

      @NotNull T replaceLorePAPI(@Nullable @Nullable OfflinePlayer player)
      PATCH PROPERTY HELPER - Replaces all PlaceholderAPI placeholders in the lore with their respective values.
      This transformation only applies to the lore patch, if no lore patch is set this does nothing.
      It does NOT modify the prototype's lore.
      Parameters:
      player - The player to use for PlaceholderAPI replacements, or null to skip player-specific placeholders
      Returns:
      This builder, for chaining

    • replaceBoth

      @Deprecated @NotNull default T replaceBoth(@NotNull @NotNull String find, @NotNull @NotNull String replacement)
      Deprecated.
      As of 5.0.0-alpha.26, replaced by replaceBoth(String, VersionedComponent) which supports components.
      PATCH PROPERTY HELPER - Convenience method to replace a substring in both name and lore.
      This is equivalent to calling replaceName(String, String) followed by replaceLore(String, String).

      This transformation only applies to existing patches, if no name or lore patches are set those won't be affected.
      It does NOT modify the prototype's name or lore.
      Parameters:
      find - The substring to find in name and lore
      replacement - The string to replace each occurrence with
      Returns:
      This builder, for chaining

    • replaceBoth

      @NotNull default T replaceBoth(@NotNull @NotNull String find, @NotNull @NotNull VersionedComponent replacement)
      PATCH PROPERTY HELPER - Convenience method to replace a substring in both name and lore.
      This is equivalent to calling replaceName(String, VersionedComponent) followed by replaceLore(String, VersionedComponent).

      This transformation only applies to existing patches, if no name or lore patches are set those won't be affected.
      It does NOT modify the prototype's name or lore.
      Parameters:
      find - The substring to find in name and lore
      replacement - The component to replace each occurrence with
      Returns:
      This builder, for chaining

    • replaceBothPAPI

      @NotNull default T replaceBothPAPI()
      Alias of replaceBothPAPI(OfflinePlayer) with a null player.

    • replaceBothPAPI

      @NotNull default T replaceBothPAPI(@Nullable @Nullable OfflinePlayer player)
      PATCH PROPERTY HELPER - Convenience method to replace PlaceholderAPI placeholders in both name and lore.
      This is equivalent to calling replaceNamePAPI(OfflinePlayer) followed by replaceLorePAPI(OfflinePlayer).

      This transformation only applies to existing patches, if no name or lore patches are set those won't be affected.
      It does NOT modify the prototype's name or lore.
      Parameters:
      player - The player to use for PlaceholderAPI replacements, or null to skip player-specific placeholders
      Returns:
      This builder, for chaining

    • clone

      @NotNull @NotNull ItemBuilder clone()

    • cloneWithNewPrototype

      @NotNull @NotNull ItemBuilder cloneWithNewPrototype(@NotNull @NotNull ItemStack newPrototype)
      Create a clone of this builder with all the same patches, but a different prototype ItemStack.
      Since:
      5.0.0-alpha.17

    • cloneWithNewPrototype

      @NotNull default @NotNull ItemBuilder cloneWithNewPrototype(@NotNull @NotNull com.cryptomorin.xseries.XMaterial newPrototype)
      Create a clone of this builder with all the same patches, but a different prototype ItemStack.
      This method uses XMaterial.parseItem() to convert the XMaterial to an ItemStack.
      Since:
      5.0.0-alpha.17

    • cloneWithNewPrototype

      @NotNull default @NotNull ItemBuilder cloneWithNewPrototype(@NotNull @NotNull Material newPrototype)
      Create a clone of this builder with all the same patches, but a different prototype ItemStack.
      This method uses XMaterial.matchXMaterial(Material) to convert the Material to an XMaterial,
      then uses XMaterial.parseItem() to convert that to an ItemStack.
      Since:
      5.0.0-alpha.17