GUI Presets & Animation - Refinery WIKI

Beyond building GUIs from scratch, xyz.refineryteam.refinerycore.api.gui ships presets for the most common menu flows, a binder that keeps paginated menus in sync with live data, and an animator for animated decorations — so you often don’t need to write a subclass at all.

`ListPickerGUI<T>` — pick one item from a list

xyz.refineryteam.refinerycore.api.gui.preset.ListPickerGUI is a ready-made paginated picker covering the extremely common “pick a player / kit / warp / home from a menu” flow, with no GUI subclass required:

WarpCommand.java

ListPickerGUI.of(
        "<dark_gray>Select a warp",
        warps,
        warp -> ItemBuilder.of(Material.ENDER_PEARL)
            .name("<gold>" + warp.name())
            .build(),
        (player, warp) -> teleport(player, warp))
    .open(player);

Factory	Description
`of(title, items, renderer, onSelect)`	Picker with the default 3-row content area (21 items per page)
`of(title, items, renderer, onSelect, contentSlots)`	Custom content slot layout; the page size derives from the number of slots

The renderer turns each element into its clickable ItemStack; onSelect fires after the GUI closes automatically. Navigation buttons (◀ Previous page / Next page ▶) are provided and wired up for you.

`TextInputGUI` — anvil text input as a preset

xyz.refineryteam.refinerycore.api.gui.preset.TextInputGUI is a thin composition over AnvilPrompt with a simpler signature for the common “ask for a string” case:

KitCommand.java

TextInputGUI.of(plugin, "<gray>Name your kit")
    .initialText("my-kit")
    .validate(text -> text.length() <= 16, "<red>Max 16 characters.")
    .onInput((player, text) -> createKit(player, text))
    .onCancel(player -> player.sendMessage("Cancelled."))
    .open(player);

Builder method	Description
`initialText(String)`	Pre-fills the anvil’s rename field
`validate(Predicate<String>, String failMessage)`	If the predicate fails on submit, the anvil stays open and the message is shown instead of resolving
`onInput(BiConsumer<Player, String>)`	Submit handler; receives the player and validated text
`onCancel(Consumer<Player>)`	Invoked when the player closes the anvil without submitting
`open(Player)`	Opens the input UI for the given player

`CollectionBinder<T>` — live data without manual refreshes

Instead of copying a list into a PaginatedGUI once at construction, xyz.refineryteam.refinerycore.api.gui.pagination.CollectionBinder re-reads it from a supplier on every render — so GUIs showing “all online players” or “all warps” stay current:

OnlinePlayersGUI.java

public class OnlinePlayersGUI extends PaginatedGUI<Player> {

    public OnlinePlayersGUI() {
        super(45, "<dark_gray>Online players",
              List.of(), Bukkit.getMaxPlayers());
        CollectionBinder.bind(this, () -> new ArrayList<>(Bukkit.getOnlinePlayers()));
    }
}

Or standalone, with change notifications:

LiveSearchGUI.java

CollectionBinder<Player> binder = CollectionBinder.of(() -> fetchItems());
binder.onChange(gui::refreshFor); // fires whenever snapshot() sees a change

Method	Description
`bind(gui, source)`	Creates a binder around a live supplier and immediately pushes its first snapshot into the GUI
`of(source)`	Creates an unbound binder; call `snapshot()` yourself (e.g. at the top of `onInitialize`)
`snapshot()`	Re-reads the backing collection, notifies change listeners if it differs from the last read, and returns an immutable copy
`onChange(listener)`	Registers a listener fired by `snapshot()` when the data changed
`lastSnapshot()`	The most recent snapshot without re-reading the source

The supplier should return a fresh copy of the items each time — never a live view being mutated elsewhere.

`GUIAnimator` — animated menus

xyz.refineryteam.refinerycore.api.gui.animation.GUIAnimator drives periodic item updates for any RefineryGUI: animated borders, blinking buttons, countdown indicators, rotating decorations.

AnimatedMenu.java

GUIAnimator.forGui(plugin, gui)
    .every(5) // ticks between frames
    .updater((gui, frame) -> {
        int slot = BORDER_SLOTS[(int) (frame % BORDER_SLOTS.length)];
        gui.setItem(slot, glowPane);
    })
    .start();

Method	Description
`forGui(plugin, gui)`	Creates an animator for the given GUI
`every(long periodTicks)`	Ticks between frames (default 1); must be ≥ 1
`updater(FrameUpdater)`	Registers a per-frame updater receiving the frame number; multiple updaters run in registration order
`stopWhenIdleAfter(int frames)`	Consecutive zero-viewer frames tolerated before auto-stop (default 100, ~5s at 20 TPS)
`start()`	Begins the animation; safe to call twice

The animator runs a repeating sync task and stops itself when the GUI is destroyed or has had no viewers past the idle grace period — you never leak tasks.

​ListPickerGUI<T> — pick one item from a list

​TextInputGUI — anvil text input as a preset

​CollectionBinder<T> — live data without manual refreshes

​GUIAnimator — animated menus

`ListPickerGUI<T>` — pick one item from a list

`TextInputGUI` — anvil text input as a preset

`CollectionBinder<T>` — live data without manual refreshes

`GUIAnimator` — animated menus