ItemStack Builder

For a full list of wiki pages, see the Home page.

ItemStack Builder

The ItemStackBuilder is a utility that provides a fluent, chainable API for creating and modifying ItemStack objects. It simplifies the process of setting metadata like names, lore, enchantments, and flags.

Getting Started

You can start building an ItemStack from a Material or from an existing ItemStack instance.

// Start with a Material
ItemStackBuilder.of(Material.DIAMOND_SWORD)

// Start from an existing item
ItemStack existingItem = new ItemStack(Material.IRON_HELMET);
ItemStackBuilder.from(existingItem)

Chaining Methods

The power of the builder comes from its chainable methods. Each method modifies the item and returns the builder instance, allowing you to string calls together.

ItemStack superSword = ItemStackBuilder.of(Material.DIAMOND_SWORD)
    .name("&bSword of Legends")
    .lore("&7A blade of immense power.", "&c+10 Attack Damage")
    .enchant(Enchantment.DAMAGE_ALL, 5)
    .enchant(Enchantment.DURABILITY, 3)
    .addFlags(ItemFlag.HIDE_ENCHANTS, ItemFlag.HIDE_ATTRIBUTES)
    .unbreakable(true)
    .customModelData(1001)
    .build(); // Finally, get the ItemStack object

Key Methods

Method	Description
of(Material material)	Static: Creates a new builder from a Material.
from(ItemStack itemStack)	Static: Creates a new builder from a clone of an existing ItemStack.
amount(int amount)	Sets the item stack size.
name(String name)	Sets the display name. Color codes (& and <#RRGGBB>) are automatically translated.
lore(List<String> lore)	Sets the lore. Color codes are automatically translated.
lore(String... lore)	A varargs convenience method for setting lore.
enchant(Enchantment ench, int lvl)	Adds an unsafe enchantment to the item.
unbreakable(boolean unbreakable)	Sets the item's unbreakable tag.
customModelData(int data)	Sets the CustomModelData integer for resource packs.
addFlags(ItemFlag... flags)	Adds ItemFlags to hide information like enchantments or attributes.
removeFlags(ItemFlag... flags)	Removes ItemFlags.
damage(int damage)	Sets the durability damage on a Damageable item.
color(Color color)	Sets the color of a leather armor piece.
build()	Returns the final ItemStack object.

Example: Creating a GUI Icon

The ItemStackBuilder is perfect for creating icons for custom inventories.

import com.darksoldier1404.dppc.builder.itemstack.ItemStackBuilder;
import org.bukkit.Material;
import org.bukkit.inventory.ItemFlag;
import org.bukkit.inventory.ItemStack;

public ItemStack createProfileIcon() {
    return ItemStackBuilder.of(Material.PLAYER_HEAD)
        .name("&aMy Profile")
        .lore("&7Click to view your stats.", "&7Level: 10", "&7XP: 500/1000")
        .addFlags(ItemFlag.HIDE_ATTRIBUTES)
        .build();
}

Example: Modifying an Existing Item

You can also use the builder to easily modify an item that already exists, for example, one that a player is holding.

Player player = ...;
ItemStack itemInHand = player.getInventory().getItemInMainHand();

if (itemInHand != null && itemInHand.getType() == Material.IRON_SWORD) {
    ItemStack upgradedSword = ItemStackBuilder.from(itemInHand)
        .name("&6Upgraded Iron Sword")
        .enchant(Enchantment.DAMAGE_ALL, 2)
        .build();

    player.getInventory().setItemInMainHand(upgradedSword);
    player.sendMessage("Your sword has been upgraded!");
}