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`

`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

​EasyMiniMessage