GUI Framework - Refinery WIKI

xyz.refineryteam.refinerycore.api.gui provides an inventory GUI framework built around InventoryHolder, so you never write raw InventoryClickEvent boilerplate per-menu.

How click routing works

RefineryCore registers a single shared listener, GUIHandlerListener, once (in RefineryCorePlugin#onEnable). For every inventory click/drag/close event, it checks whether the inventory’s holder is a RefineryGUI — if so, it delegates to that GUI instance. This means you never register your own inventory listener — just extend RefineryGUI and it’s handled automatically.

Basic usage

ExampleGUI.java

public class ExampleGUI extends RefineryGUI {

    private final Player target;

    public ExampleGUI(Player target) {
        super(27, "<bold>Example</bold>"); // 27 slots (3 rows), MiniMessage title
        this.target = target;
    }

    @Override
    public GUILayout[] layouts() {
        return new GUILayout[]{ GUILayout.border(3, new ItemStack(Material.BLACK_STAINED_GLASS_PANE)) };
    }

    @SlotItem(slots = { 13 })
    public ItemStack profileItem() {
        return ItemBuilder.of(Material.PLAYER_HEAD)
            .name("<yellow>" + target.getName())
            .build();
    }

    @SlotAction(slots = { 13 })
    public void onProfileClick(@NonNull Player clicker) {
        clicker.sendMessage(EasyMiniMessage.format("<green>Clicked profile!"));
    }

    @Override
    public void onInitialize(Player player) {}
}

Open it with:

ExampleClass.java

RefineryGUI.open(player, new ExampleGUI(player));

Annotations

`@SlotItem`

Applied to a no-argument method returning an ItemStack. The method is invoked during GUI initialization, and its result is placed at every slot listed in slots.

`@SlotAction`

Applied to a method handling clicks on the given slots. The method can take any of these parameter shapes:

No parameters
Player
InventoryClickEvent
Player, InventoryClickEvent

ExampleGUI.java

@SlotAction(slots = { 22 })
public void onCloseClick(Player player, InventoryClickEvent event) {
    player.closeInventory();
}

Lifecycle methods

Override these on your RefineryGUI subclass as needed:

Method	Called when
`onInitialize(Player player)`	Required. Called before the inventory is shown — set static items/layouts here
`onOpen(Player player)`	After initialization completes and the inventory has been populated
`onClose(Player player)`	When the player closes the inventory
`onDestroy()`	When `destroy()` is called explicitly
`cancelClicks()`	Return `false` to allow normal inventory interaction (e.g. item pickup); defaults to `true`, cancelling every click
`layouts()`	Return an array of `GUILayout`s applied automatically after `onInitialize`

Manually setting items

Beyond @SlotItem/@SlotAction, you can set items imperatively:

ExampleGUI.java

setItem(11, someItem, (player, event) -> {
    player.sendMessage("Clicked!");
});

setItem(15, anotherItem); // no click handler
onSlot(20, (player, event) -> { /* just a handler, item set elsewhere */ });

`GUILayout`

A reusable, composable way to describe static filler/border patterns without repeating setItem calls across every GUI:

ExampleGUI.java

GUILayout layout = GUILayout.border(3, fillerItem)   // border of a 3-row inventory
    .merge(GUILayout.fill(9, otherFiller))            // combine with another layout
    .slot(4, someSpecificItem);                       // and a one-off slot

GUILayout.border(rows, filler) — fills the outer ring of a rows-row inventory
GUILayout.fill(size, filler) — fills every slot from 0 to size - 1
.slot(int, ItemStack) — sets a specific static item
.slot(int, Consumer<RefineryGUI>) — runs custom logic against the GUI for a specific slot
.merge(GUILayout) — combines two layouts (later layout’s entries win on conflict)

Return one or more layouts from layouts() and they’re applied automatically after onInitialize.

Pagination — `PaginatedGUI<T>`

For menus displaying a list of items across multiple pages (players, kits, warps, etc.), extend PaginatedGUI<T> instead of RefineryGUI directly:

KitsGUI.java

public class KitsGUI extends PaginatedGUI<Kit> {

    public KitsGUI(List<Kit> kits) {
        super(54, "<bold>Kits</bold>", kits, 45); // 45 content slots per page
    }

    @Override
    protected int[] contentSlots() {
        return IntStream.range(0, 45).toArray();
    }

    @Override
    protected ItemStack renderItem(Player player, Kit kit, int index) {
        return ItemBuilder.of(kit.icon()).name(kit.displayName()).build();
    }

    @Override
    protected void onItemClick(Player player, Kit kit, int index, InventoryClickEvent event) {
        kit.giveTo(player);
    }

    @Override
    protected ItemStack previousPageItem() {
        return ItemBuilder.of(Material.ARROW).name("<gray>Previous Page").build();
    }

    @Override
    protected ItemStack nextPageItem() {
        return ItemBuilder.of(Material.ARROW).name("<gray>Next Page").build();
    }
}

Required abstract methods:

Method	Purpose
`contentSlots()`	The slots available for paginated content, in display order
`renderItem(player, item, index)`	The `ItemStack` to display for a given item
`onItemClick(player, item, index, event)`	Click handler for a content item
`previousPageItem()` / `nextPageItem()`	Navigation button items (return `null` to hide when unavailable — handled automatically based on `hasPrevious()`/`hasNext()`)

Optional overrides:

Method	Default
`onPageInitialize(player, context)`	No-op — set static items alongside the paginated content
`emptySlotItem(slot)`	`null` — item shown in unused content slots on a partially-filled page
`previousSlot()` / `nextSlot()`	Bottom-left / bottom-right slot of the inventory

Navigation, page-index tracking, and re-rendering on page change are handled internally via PageContext<T>. Call updateItems(List<T>) to refresh the underlying list (e.g. after a kit is added) without recreating the GUI.

Confirmation dialogs — `ConfirmationGUI`

A ready-made yes/no screen so you don’t rebuild a confirm/cancel inventory for every destructive action:

BanCommand.java

ConfirmationGUI.builder()
    .title("<red>Confirm ban")
    .description(ItemBuilder.of(Material.PLAYER_HEAD)
        .name("<red>Ban " + target.getName() + "?")
        .lore("<gray>This action cannot be undone.")
        .build())
    .onConfirm(player -> banPlayer(target))
    .onCancel(player -> player.sendMessage("Cancelled."))
    .open(player);

Builder options:

Method	Description
`title(String)`	MiniMessage title, default `<gray>Confirm?`
`description(ItemStack)`	Optional item shown between the confirm/cancel buttons
`confirmItem(ItemStack)` / `cancelItem(ItemStack)`	Override the default green/red glass pane buttons
`onConfirm(handler)` / `onCancel(handler)`	Callbacks — closing the inventory without choosing also triggers `onCancel`
`closeOnChoice(boolean)`	Default `true`. Set `false` if your handler opens another GUI immediately and you want to avoid a flicker-close

See also Interaction Prompts for chat- and anvil-based text input, which pairs well with confirmation flows.

​How click routing works

​Basic usage

​Annotations

​@SlotItem

​@SlotAction

​Lifecycle methods

​Manually setting items

​GUILayout

​Pagination — PaginatedGUI<T>

​Confirmation dialogs — ConfirmationGUI

How click routing works

Basic usage

Annotations

`@SlotItem`

`@SlotAction`

Lifecycle methods

Manually setting items

`GUILayout`

Pagination — `PaginatedGUI<T>`

Confirmation dialogs — `ConfirmationGUI`