> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.refineryteam.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Items & Messages

> Fluent ItemStack building and MiniMessage formatting helpers.

## `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.

```java ExampleItem.java icon="java" theme={"system"}
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:

```java PlayersListener.java icon="java" theme={"system"}
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(...))`).