Items & Messages - Refinery WIKI

`ItemBuilder`

xyz.refineryteam.refinerycore.api.item.ItemBuilder is a fluent wrapper around ItemStack/ItemMeta, so item construction reads top-to-bottom instead of a sequence of meta.set... calls with manual null-checking.

ExampleItem.java

ItemStack sword = ItemBuilder.of(Material.DIAMOND_SWORD)
    .name("<gradient:red:gold><bold>Blazing Edge")
    .lore(
        "<gray>A sword forged in dragon fire.",
        "",
        "<yellow>Right-click to ignite nearby enemies"
    )
    .enchant(Enchantment.FIRE_ASPECT, 2)
    .unbreakable()
    .glint()
    .build();

Creating a builder

Method	Description
`ItemBuilder.of(Material)`	New item of the given material, amount 1
`ItemBuilder.of(Material, int amount)`	New item with a specific amount
`ItemBuilder.of(ItemStack)`	Wraps a clone of an existing stack (the original is untouched)
`ItemBuilder.skull()`	Shorthand for `of(Material.PLAYER_HEAD)`

Display & lore

Method	Description
`name(String)`	Sets the display name from a MiniMessage string
`name(Component)`	Sets the display name from an Adventure `Component`
`lore(String...)`	Sets lore lines from MiniMessage strings (replaces existing lore)
`lore(List<Component>)`	Sets lore from Components directly
`appendLore(String...)`	Appends lines to any existing lore instead of replacing it

Enchantments & flags

Method	Description
`enchant(Enchantment, int level)`	Adds an enchantment, ignoring level restrictions
`enchant(Enchantment, int level, boolean ignoreLevelRestriction)`	Same, with explicit control over the restriction flag
`removeEnchant(Enchantment)`	Removes an enchantment
`flags(ItemFlag...)`	Adds the given item flags (e.g. hide enchantments/attributes)
`hideAll()`	Adds every `ItemFlag` value
`glint()`	Adds an invisible enchantment (`Enchantment.INFINITY`) plus `hideAll()`, producing the enchanted glint effect without a visible enchantment in the tooltip

Other properties

Method	Description
`amount(int)`	Sets the stack size
`unbreakable(boolean)` / `unbreakable()`	Sets/enables the unbreakable flag
`customModelData(int)`	Sets custom model data for resource-pack item overrides

Player heads

Method	Description
`skullOwner(String name)`	Sets the head’s owner by player name (uses `Bukkit.getOfflinePlayer`)
`skullOwner(UUID uuid)`	Same, by UUID
`skullTexture(String textureUrl)`	Applies a custom skin texture URL directly via a generated player profile, without needing the owner to have a cached Mojang profile

Escape hatches

Method	Description
`meta(Consumer<ItemMeta>)`	Runs arbitrary logic against the item’s `ItemMeta` for anything not covered above
`specificMeta(Class<M>, Consumer<M>)`	Same, but cast to a specific `ItemMeta` subtype (e.g. `SkullMeta`, `BannerMeta`) — no-ops if the item’s meta isn’t an instance of that type
`build()`	Returns a clone of the built `ItemStack`

`ItemSerializer`

xyz.refineryteam.refinerycore.api.item.ItemSerializer serializes ItemStacks to compact Base64 strings so they can be stored in a database column, config, or plugin message. It uses Paper’s native DataComponent-based serialization — full fidelity including components, enchantments, and custom model data on 1.20.5+.

ItemStorage.java

String encoded = ItemSerializer.encode(stack);
ItemStack restored = ItemSerializer.decode(encoded);

// Whole inventories (semicolon-separated segments, empty slots preserved):
String inv = ItemSerializer.encodeArray(player.getInventory().getContents());
ItemStack[] contents = ItemSerializer.decodeArray(inv);

Method	Description
`encode(ItemStack)`	Encodes a single stack; returns an empty string for `null`/empty stacks
`decode(String)`	Decodes a single stack; blank input yields `null`, corrupt data throws `IllegalArgumentException`
`encodeArray(ItemStack[])` / `decodeArray(String)`	Array round-trip with null/empty slots preserved as empty segments

For capturing a player’s entire inventory (storage + armor + off hand) as one string, see InventorySnapshot.

`EasyMiniMessage`

xyz.refineryteam.refinerycore.api.minimessage.EasyMiniMessage is a thin static wrapper around Adventure’s MiniMessage, used throughout RefineryCore (commands, GUIs, scoreboards) so every plugin formats text consistently:

PlayersListener.java

Component message = EasyMiniMessage.format("<gradient:#A78BFA:#7F77DD>Hello!</gradient>");

// With placeholders via TagResolver:
Component withPlaceholder = EasyMiniMessage.format(
    "<gray>Welcome, <white><name></white>!",
    Placeholder.unparsed("name", player.getName())
);

Method	Description
`format(String content)`	Deserializes a MiniMessage string into a `Component`
`format(String content, TagResolver... resolvers)`	Same, with one or more tag resolvers (e.g. `Placeholder.unparsed(...)`) for dynamic values

Since every RefineryCore subsystem (commands, GUIs, scoreboards, prompts) accepts plain MiniMessage strings and formats them through this helper internally, you rarely need to call EasyMiniMessage.format yourself — pass MiniMessage strings directly to those APIs. Reach for it directly when sending a message outside of those APIs (e.g. player.sendMessage(EasyMiniMessage.format(...))).

​ItemBuilder

​Creating a builder

​Display & lore

​Enchantments & flags

​Other properties

​Player heads

​Escape hatches

​ItemSerializer

​EasyMiniMessage