Class ItemBuilder

java.lang.Object

top.magstar.framework.ItemBuilder

public class ItemBuilder
extends Object

A fluent builder utility for creating and modifying ItemStack instances in Bukkit/Spigot/Paper.

The ItemBuilder wraps an ItemStack and its ItemMeta, exposing a chainable API to conveniently customize item properties such as display name, lore, enchantments, attributes, unbreakability, and more. It supports both legacy BaseComponent and Adventure Component systems, as well as custom SmartString formatting.

Example

 ItemStack sword = new ItemBuilder(new ItemStack(Material.DIAMOND_SWORD))
         .setDisplayName(Component.text("§bEpic Sword"))
         .appendLore("§7This blade was forged in fire.", "§eSharp and deadly!")
         .addEnchants(5, Enchantment.DAMAGE_ALL)
         .setUnbreakable(true)
         .toItemStack();
 

Features

• Set display names via Strings, Adventure Components, BaseComponents, or SmartStrings.
• Set or modify lore lines with various overloads.
• Insert, append, or prepend lore at specific positions.
• Support for enchantments and attribute modifiers.
• Convenient cloning, equality comparison, and hash code computation.
• Builder-style pattern for method chaining.

Note: toItemStack() must be called to apply changes and obtain the final item.

Since:

1.0.0

Version:

1.0.0

Author:

Magstar

Constructor Summary

Constructors

Constructor	Description
ItemBuilder(org.bukkit.inventory.ItemStack originStack)	Constructs a new ItemBuilder with a given origin ItemStack.
ItemBuilder(org.bukkit.inventory.ItemStack originStack, org.bukkit.inventory.meta.ItemMeta originMeta)	Constructs a new ItemBuilder with a given origin ItemStack and explicit ItemMeta.

Method Summary

Modifier and Type	Method	Description
ItemBuilder	addEnchants(int level, org.bukkit.enchantments.Enchantment... enchantment)	Adds one or more enchantments to the item with given level.
ItemBuilder	appendLore(String... lore)	Appends lore to the end of the current lore list.
ItemBuilder	appendLore(net.md_5.bungee.api.chat.BaseComponent[]... lore)	Appends lore as BaseComponent lines.
ItemBuilder	appendLore(SmartString... lore)	Appends lore using SmartString.
ItemBuilder	clone()	Creates a deep clone of this builder, including meta.
static org.bukkit.inventory.ItemStack	deserialize(String serialized)
ItemBuilder	dropChanges()	Discards unsaved changes and restores the original ItemMeta.
boolean	equals(Object obj)	To check if the two ItemBuilders will produce same results.
static ItemBuilder	fromCustomStack(dev.lone.itemsadder.api.CustomStack customStack)
static ItemBuilder	fromCustomStack(String key)
org.bukkit.inventory.meta.ItemMeta	getMeta()	Returns the current ItemMeta in use.
<T> T	getNBT(String key, Class<T> clazz)
boolean	getNBTBoolean(String key)
byte[]	getNBTByte(String key)
byte[]	getNBTByteArray(String key)
<E extends Enum<E>> E	getNBTEnum(String key, Class<E> clazz)
float	getNBTFloat(String key)
int	getNBTInt(String key)	获取 NBT 整数值
int	getNBTInt(String key, int defaultValue)	获取 NBT 整数值，带默认值
int[]	getNBTIntArray(String key)
org.bukkit.inventory.ItemStack	getNBTItemStack(String key)
org.bukkit.inventory.ItemStack[]	getNBTItemStackArray(String key)
long	getNBTLong(String key)
long[]	getNBTLongArray(String key)
short	getNBTShort(String key)
String	getNBTString(String key)	获取 NBT 字符串值
String	getNBTString(String key, String defaultValue)	获取 NBT 字符串值，带默认值
int	hashCode()	Computes the hash code based on the built ItemStack.
boolean	hasNBTTag(String key)	检查是否存在指定的 NBT 标签
ItemBuilder	insertLoreAt(int position, String... lore)	Insert a series of things into the lore at a specified position.
ItemBuilder	insertLoreAt(int position, net.md_5.bungee.api.chat.BaseComponent[]... lore)	Inserts lore as BaseComponent lines at a specified position.
ItemBuilder	insertLoreAt(int position, SmartString... lore)	Inserts SmartString lore at a specified position.
ItemBuilder	modifyNBT(Consumer<de.tr7zw.nbtapi.iface.ReadWriteItemNBT> modifier)	修改物品的 NBT 数据
<T> T	modifyNBT(Function<de.tr7zw.nbtapi.iface.ReadWriteItemNBT,T> modifier)	修改 NBT 并返回结果
ItemBuilder	prependLore(String... lore)	Prepends lore to the beginning of the current lore list.
ItemBuilder	prependLore(net.md_5.bungee.api.chat.BaseComponent[]... lore)	Prepends BaseComponent lore at the beginning.
ItemBuilder	prependLore(SmartString... lore)	Prepends SmartString lore at the beginning.
<T> T	readNBT(Function<de.tr7zw.nbtapi.iface.ReadableItemNBT,T> reader)	只读取 NBT 数据，不修改
ItemBuilder	removeEnchants(org.bukkit.enchantments.Enchantment... enchantment)	Removes one or more enchantments from the item.
ItemBuilder	removeNBTTag(String key)	移除 NBT 标签
String	serialize()
static String	serialize(org.bukkit.inventory.ItemStack itemStack)
ItemBuilder	setAmount(int amount)	Sets the stack size.
ItemBuilder	setAttributeModifier(org.bukkit.attribute.Attribute attribute, org.bukkit.attribute.AttributeModifier am)	Assigns or removes an AttributeModifier for a specific Attribute.
ItemBuilder	setDisplayName(String name)	Sets the display name using a legacy String.
ItemBuilder	setDisplayName(net.kyori.adventure.text.Component component)	Sets the display name using Adventure Component.
ItemBuilder	setDisplayName(net.md_5.bungee.api.chat.BaseComponent... name)	Sets the display name using Bungee BaseComponent
ItemBuilder	setDisplayName(SmartString name)	Sets the display name using a SmartString.
ItemBuilder	setLore(String... lore)	Sets the lore using raw strings (one line per entry).
ItemBuilder	setLore(net.md_5.bungee.api.chat.BaseComponent[]... lore)	Sets the lore using Bungee BaseComponent lines.
ItemBuilder	setLore(SmartString... lore)	Sets the lore using SmartString lines.
ItemBuilder	setLoreByLines(String lore)	Splits a long string into multiple lines by newline markers and sets them as lore.
<T> ItemBuilder	setNBT(String key, T value, Class<T> clazz)
ItemBuilder	setNBTBoolean(String key, boolean value)	设置自定义 NBT 布尔值
ItemBuilder	setNBTByte(String key, byte value)
ItemBuilder	setNBTByteArray(String key, byte[] value)
ItemBuilder	setNBTDouble(String key, double value)	设置自定义 NBT 双精度值
<E extends Enum<?>> ItemBuilder	setNBTEnum(String key, E value)
ItemBuilder	setNBTFloat(String key, float value)
ItemBuilder	setNBTInt(String key, int value)	设置自定义 NBT 整数值
ItemBuilder	setNBTIntArray(String key, int[] value)
ItemBuilder	setNBTItemStack(String key, org.bukkit.inventory.ItemStack value)
ItemBuilder	setNBTItemStackArray(String key, org.bukkit.inventory.ItemStack[] value)
ItemBuilder	setNBTLong(String key, long value)
ItemBuilder	setNBTLongArray(String key, long[] value)
ItemBuilder	setNBTShort(String key, short value)
ItemBuilder	setNBTString(String key, String value)	设置自定义 NBT 字符串值
ItemBuilder	setUnbreakable(boolean unbreakable)	Sets whether the item is unbreakable.
org.bukkit.inventory.ItemStack	toItemStack()	Builds and returns the final ItemStack with applied changes.
<T extends org.bukkit.inventory.meta.ItemMeta> ItemBuilder	withMeta(Class<T> metaClass, Function<T,ItemBuilder> modifier)	修改特定类型的 ItemMeta

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ItemBuilder

@ParametersAreNonnullByDefault
public ItemBuilder(org.bukkit.inventory.ItemStack originStack)

Constructs a new ItemBuilder with a given origin ItemStack. If the stack has no ItemMeta, a default one is created.

Parameters:

originStack - the base ItemStack

ItemBuilder

@ParametersAreNonnullByDefault
public ItemBuilder(org.bukkit.inventory.ItemStack originStack,
 org.bukkit.inventory.meta.ItemMeta originMeta)

Constructs a new ItemBuilder with a given origin ItemStack and explicit ItemMeta.

Parameters:

originStack - the base ItemStack

originMeta - the ItemMeta to use

Method Details

toItemStack

@Nonnull
public org.bukkit.inventory.ItemStack toItemStack()

Builds and returns the final ItemStack with applied changes.

Returns:

the updated ItemStack

setDisplayName

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder setDisplayName(net.kyori.adventure.text.Component component)

Sets the display name using Adventure Component.

setDisplayName

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder setDisplayName(String name)

Sets the display name using a legacy String.

setDisplayName

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder setDisplayName(SmartString name)

Sets the display name using a SmartString.

setDisplayName

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder setDisplayName(net.md_5.bungee.api.chat.BaseComponent... name)

Sets the display name using Bungee BaseComponent

setLore

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder setLore(String... lore)

Sets the lore using raw strings (one line per entry).

setLore

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder setLore(net.md_5.bungee.api.chat.BaseComponent[]... lore)

Sets the lore using Bungee BaseComponent lines.

setLore

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder setLore(SmartString... lore)

Sets the lore using SmartString lines.

insertLoreAt

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder insertLoreAt(int position,
 String... lore)

Insert a series of things into the lore at a specified position.

Parameters:

position - Where to insert, negative to count from back.

lore - What to insert.

Returns:

The builder.

insertLoreAt

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder insertLoreAt(int position,
 net.md_5.bungee.api.chat.BaseComponent[]... lore)

Inserts lore as BaseComponent lines at a specified position.

insertLoreAt

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder insertLoreAt(int position,
 SmartString... lore)

Inserts SmartString lore at a specified position.

setLoreByLines

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder setLoreByLines(String lore)

Splits a long string into multiple lines by newline markers and sets them as lore.

Parameters:

lore - multiline string separated by "\\n"

Returns:

this builder

appendLore

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder appendLore(String... lore)

Appends lore to the end of the current lore list.

Parameters:

lore - What to append.

Returns:

The builder.

appendLore

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder appendLore(net.md_5.bungee.api.chat.BaseComponent[]... lore)

Appends lore as BaseComponent lines.

appendLore

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder appendLore(SmartString... lore)

Appends lore using SmartString.

prependLore

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder prependLore(String... lore)

Prepends lore to the beginning of the current lore list.

Parameters:

lore - What to prepend.

Returns:

The builder.

prependLore

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder prependLore(net.md_5.bungee.api.chat.BaseComponent[]... lore)

Prepends BaseComponent lore at the beginning.

prependLore

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder prependLore(SmartString... lore)

Prepends SmartString lore at the beginning.

dropChanges

@Nonnull
public ItemBuilder dropChanges()

Discards unsaved changes and restores the original ItemMeta.

Returns:

this builder

setAmount

@Nonnull
public ItemBuilder setAmount(int amount)

Sets the stack size.

clone

@Nonnull
public ItemBuilder clone()

Creates a deep clone of this builder, including meta.

Overrides:

clone in class Object

Returns:

a new ItemBuilder with the same stack and metadata

equals

@ParametersAreNonnullByDefault
public boolean equals(Object obj)

To check if the two ItemBuilders will produce same results.

Overrides:

equals in class Object

Parameters:

obj - The object to compare.

Returns:

If the stacks are same.

hashCode

public int hashCode()

Computes the hash code based on the built ItemStack.

Overrides:

hashCode in class Object

addEnchants

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder addEnchants(int level,
 org.bukkit.enchantments.Enchantment... enchantment)

Adds one or more enchantments to the item with given level.

Parameters:

level - enchantment level

enchantment - enchantments to apply

Returns:

this builder

removeEnchants

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder removeEnchants(org.bukkit.enchantments.Enchantment... enchantment)

Removes one or more enchantments from the item.

Parameters:

enchantment - enchantments to remove

Returns:

this builder

setUnbreakable

@Nonnull
public ItemBuilder setUnbreakable(boolean unbreakable)

Sets whether the item is unbreakable.

Parameters:

unbreakable - true to make the item unbreakable

Returns:

this builder

setAttributeModifier

@Nonnull
@ParametersAreNullableByDefault
public ItemBuilder setAttributeModifier(org.bukkit.attribute.Attribute attribute,
 org.bukkit.attribute.AttributeModifier am)

Assigns or removes an AttributeModifier for a specific Attribute.

If the modifier is null, it removes the modifier for the attribute.

Parameters:

attribute - the attribute

am - the modifier (or null to remove)

Returns:

this builder

getMeta

@Nonnull
public org.bukkit.inventory.meta.ItemMeta getMeta()

Returns the current ItemMeta in use.

Returns:

the ItemMeta

withMeta

@Nonnull
public <T extends org.bukkit.inventory.meta.ItemMeta>
ItemBuilder withMeta(Class<T> metaClass,
 Function<T,ItemBuilder> modifier)

修改特定类型的 ItemMeta

Type Parameters:

T - ItemMeta 的子类型

Parameters:

metaClass - 期望的 ItemMeta 类型

modifier - 修改操作的函数

Returns:

this builder

modifyNBT

@Nonnull
public ItemBuilder modifyNBT(Consumer<de.tr7zw.nbtapi.iface.ReadWriteItemNBT> modifier)

修改物品的 NBT 数据

Parameters:

modifier - NBT 修改操作

Returns:

this builder

modifyNBT

@Nonnull
public <T> T modifyNBT(Function<de.tr7zw.nbtapi.iface.ReadWriteItemNBT,T> modifier)

修改 NBT 并返回结果

Type Parameters:

T - 返回值类型

Parameters:

modifier - NBT 修改操作，可以返回值

Returns:

修改操作的返回值

readNBT

public <T> T readNBT(Function<de.tr7zw.nbtapi.iface.ReadableItemNBT,T> reader)

只读取 NBT 数据，不修改

Type Parameters:

T - 返回值类型

Parameters:

reader - NBT 读取操作

Returns:

读取操作的返回值

setNBTString

@Nonnull
public ItemBuilder setNBTString(String key,
 String value)

设置自定义 NBT 字符串值

setNBTInt

@Nonnull
public ItemBuilder setNBTInt(String key,
 int value)

设置自定义 NBT 整数值

setNBTBoolean

@Nonnull
public ItemBuilder setNBTBoolean(String key,
 boolean value)

设置自定义 NBT 布尔值

setNBTDouble

@Nonnull
public ItemBuilder setNBTDouble(String key,
 double value)

设置自定义 NBT 双精度值

setNBTFloat

@Nonnull
public ItemBuilder setNBTFloat(String key,
 float value)

setNBTLong

@Nonnull
public ItemBuilder setNBTLong(String key,
 long value)

setNBTIntArray

@Nonnull
public ItemBuilder setNBTIntArray(String key,
 int[] value)

setNBTLongArray

@Nonnull
public ItemBuilder setNBTLongArray(String key,
 long[] value)

setNBTByteArray

@Nonnull
public ItemBuilder setNBTByteArray(String key,
 byte[] value)

setNBTByte

@Nonnull
public ItemBuilder setNBTByte(String key,
 byte value)

setNBTShort

@Nonnull
public ItemBuilder setNBTShort(String key,
 short value)

setNBTItemStack

@Nonnull
public ItemBuilder setNBTItemStack(String key,
 org.bukkit.inventory.ItemStack value)

setNBTItemStackArray

@Nonnull
public ItemBuilder setNBTItemStackArray(String key,
 org.bukkit.inventory.ItemStack[] value)

setNBTEnum

@Nonnull
public <E extends Enum<?>> ItemBuilder setNBTEnum(String key,
 E value)

setNBT

@Nonnull
public <T> ItemBuilder setNBT(String key,
 T value,
 Class<T> clazz)

getNBTString

public String getNBTString(String key)

获取 NBT 字符串值

getNBTFloat

public float getNBTFloat(String key)

getNBTLong

public long getNBTLong(String key)

getNBTIntArray

public int[] getNBTIntArray(String key)

getNBTLongArray

public long[] getNBTLongArray(String key)

getNBTByteArray

public byte[] getNBTByteArray(String key)

getNBTByte

public byte[] getNBTByte(String key)

getNBTShort

public short getNBTShort(String key)

getNBTItemStack

public org.bukkit.inventory.ItemStack getNBTItemStack(String key)

getNBTItemStackArray

public org.bukkit.inventory.ItemStack[] getNBTItemStackArray(String key)

getNBTBoolean

public boolean getNBTBoolean(String key)

getNBTEnum

public <E extends Enum<E>> E getNBTEnum(String key,
 Class<E> clazz)

getNBT

public <T> T getNBT(String key,
 Class<T> clazz)

getNBTString

public String getNBTString(String key,
 String defaultValue)

获取 NBT 字符串值，带默认值

getNBTInt

public int getNBTInt(String key)

获取 NBT 整数值

getNBTInt

public int getNBTInt(String key,
 int defaultValue)

获取 NBT 整数值，带默认值

hasNBTTag

public boolean hasNBTTag(String key)

检查是否存在指定的 NBT 标签

removeNBTTag

@Nonnull
public ItemBuilder removeNBTTag(String key)

移除 NBT 标签

serialize

@Nonnull
public String serialize()

serialize

@Nonnull
public static String serialize(org.bukkit.inventory.ItemStack itemStack)

deserialize

@Nullable
public static org.bukkit.inventory.ItemStack deserialize(@Nonnull
 String serialized)

fromCustomStack

@Nonnull
public static ItemBuilder fromCustomStack(dev.lone.itemsadder.api.CustomStack customStack)

fromCustomStack

@Nullable
public static ItemBuilder fromCustomStack(String key)