Menus
Everything a menu file can say: windows, lists, groups, templates, fillers, conditions, clicks, sounds and redrawing.
A menu is a YAML file, compiled once and opened cheaply. Nothing about it is written in Java except the data that fills its lists.
PluginMenus menus = Menus.of(this);
menus.load("kits", YamlConfiguration.loadConfiguration(file)); // once
menus.open(player, "kits"); // wheneverThree things kept apart#
| What it is | Lifetime | |
|---|---|---|
UiDefinition | What the file says, compiled | One per menu, shared by everyone |
UiSession | One player's open window | Until they close it |
UiEntry | One row of a list | Until the list is replaced |
Reading the file is the expensive half and happens once. Opening renders the slots that are shown and nothing else.
Loading and opening#
| Call | What it does |
|---|---|
load(id, section) | Compile a menu, reporting bad parts to the console. |
load(id, section, problems) | The same, reporting them where you want. |
check(section) | The problems load would report, one where: what line each, registering nothing. |
register(definition) | Register an already-compiled menu. |
definition(id) | Get one back. |
unload() | Forget them all, for a reload. |
sounds(UiSounds) | What this plugin's menus sound like. |
refreshBundledDirectory(class, path) | Replace a packaged directory nobody edits with the jar's copy at startup. |
refreshVersionedDirectory(class, path) | Install and update a directory of menus the server owner edits. |
open(player, id) | Open it. Safe from any thread. |
open(player, id, context) | Open it with context values. |
open(player, id, context, rows) | Open it with its only list read from a lambda on every redraw. |
openNow(player, definition, context) | Open and return the session. Player's thread only. |
openNow(player, definition, context, sections) | The same, with the lists filled before the first draw. |
update(player, id, context, rows) | Redraw the menu already open from new values. Player's thread only. |
back(player) / close(player) | Where they came from, or shut it. |
session(player) | The open session, if it is one of ours. |
sessions() | Every menu of this plugin somebody has open, for a timer that redraws them. |
open moves itself onto the thread that owns the player, so a caller returning from a database query
does not have to. openNow cannot, because it hands back the session it opened.
A part that will not compile — an action that does not exist, a mistyped enchantment — becomes a dead button and a line in the console, and the rest of the menu still opens. A file that is empty or missing is reported too (Bukkit reads a missing file as an empty one, which used to open a blank chest titled "Menu" without a word).
Bundled menu files#
menus.refreshVersionedDirectory(MyPlugin.class, "menus"); // menus players see
menus.refreshBundledDirectory(MyPlugin.class, "menus/admin"); // the jar's, rewritten every startrefreshVersionedDirectory writes missing files, adds keys that are new in the plugin, and leaves a
changed default — a slot moved, a lore line reworded — waiting in /exylialib updates instead of
overwriting a value the owner may have chosen. A change the old file cannot survive is declared with a
higher menu-version in the packaged file: an untouched file is replaced at once, an edited one waits
in /exylialib updates as one change, and applying it keeps the old file as <name>.v<old version>.
A file on disk that does not parse is never overwritten.
Redrawing from new values#
A screen is drawn from the snapshot it was opened with, so session.refresh() redraws the old values.
When they changed — a field was edited, a row added — update writes the new snapshot into the open
session instead of opening it again, which would re-send every slot, replay the open sound and put a
reader on page two back on page one:
Map<String, Object> context = Map.of("mine_id", mine.id());
if (!menus.update(player, "mine_levels", context, rows)) {
menus.openNow(player, definition, context, Map.of(UiSection.MAIN, rows));
}
menus.update(player, "mine_detail", context); // a menu with no listOnly the context keys given are replaced; rows replaces the main list, and null keeps it. It answers
false and touches nothing when that menu is not the one open — the cue to open it.
Context#
Context values fill placeholders everywhere the menu draws — the title, every fixed slot, every row:
menus.open(player, "leaderboard", Map.of("kit_name", kit.name()));Context values are parsed, unlike row values: whoever wrote the menu also wrote them, usually in
the same file, so "{success}&lNEW SHIELD" arrives as a green button. A row naming the same key
shadows the context and keeps its own rule.
The window#
type: SIMPLE # a chest; the default
size: 54 # only a chest is resizable; rows: 6 says the sameSIMPLE, PAGINATION, MULTI_PAGINATION, ITEM_INPUT and STATIC are all chests — whether a menu
paginates is decided by whether it has a list, which is the only thing that ever decided it.
Any other container works and brings its own fixed size: BARREL, HOPPER, DROPPER, DISPENSER,
ANVIL, ENCHANTING, FURNACE, BREWING, BEACON, CRAFTING, MERCHANT, SMITHING,
GRINDSTONE, CARTOGRAPHY, LOOM, STONECUTTER.
Creating an inventory whose size disagrees with its type throws, so the menu never opens at all. A barrel looks like a chest and is not: it is always twenty-seven slots.
The page in the title#
title: '{primary}&lMY SHIELDS {muted}%current_page%/%total_pages%'%current_page%, %total_pages% and the shorter %page% and %pages% are supplied by the list
itself — the section knows how many rows it has, so a context value of the same name never shadows
them.
The title follows the reader through the list, which Bukkit cannot do: the new title goes out as a packet the client accepts as a retitle of the window it already has open. It is sent only when the title names a page and the text actually changed.
The retitle goes through PacketEvents, which ExyliaLib requires.
Opening, closing and going up#
open-actions: ["practice:mark_seen"]
close-actions: ["practice:save_draft"]
parent: main # where back goes when the player has no historyopen-actions and close-actions are action lines run when the menu opens and closes. parent names
the menu back opens for a player who arrived some other way, such as a command.
Lists#
A menu can have several paginated lists on one screen, each paging independently.
pagination:
slots: '10-16,19-25,28-34'
item_template:
material: "%kit_icon%"
name: "{warning}&l%kit_name%"
actions:
- "practice:select %kit_id%"
navigation:
previous: { slot: 45, material: ARROW }
next: { slot: 53, material: ARROW }Several lists are written as named sections instead:
sections:
players:
slots: "1-7,10-16,19-25,28-34"
player_template: { ... }
navigation: { previous: { slot: 37 }, next: { slot: 43 } }
stat_types:
slots: "46-52"
not_selected_template: { ... }
selected_template: { ... }
navigation: { previous: { slot: 45 }, next: { slot: 53 } }A pagination block is one section named main, so a menu with one list never has to know section
names exist. An arrow inside a navigation block pages its own section — the actions are implied.
Filling one#
session.entries(kits.stream()
.map(kit -> UiEntry.of(kit)
.with("kit_name", kit.name())
.with("kit_icon", kit.icon())
.template(kit.equals(selected) ? "selected" : "not_selected")
.build())
.toList());A row can carry its own item for lists no template could describe:
session.entries("items", stored.stream()
.map(stack -> UiEntry.of(stack).item(stack).build())
.toList());UiEntry.of(kit) keeps the object itself on the row, so a handler reads back which kit was
clicked instead of working it out from the item that was drawn:
actions.registerSync("select", (context, args) -> {
Kit kit = (Kit) context.require(UiKeys.ENTRY);
...
});Replacing the rows keeps the reader where they were, clamped to what still exists — a leaderboard refreshing under somebody on page three leaves them on page three.
A handler behind a button the menu only shows to some players can take the permission at registration:
actions.registerSync("delete_mine", "mines.admin", (context, args) -> { ... });Without the permission the handler does not run and the action answers success, so the rest of the sequence carries on as if the button were a decoration.
Literal values, and the ones that are not#
with() inserts a value as text; withFormatted() parses it. Same rule as everywhere else in the
library: the question is whose value it is.
UiEntry.of(player)
.with("player_name", player.getName()) // a player typed it
.withFormatted("rank", config.rankDisplay()) // an owner wrote it
.build();Values that move while the menu is open#
A value is decided once, when the menu opens. Anything that changes while somebody looks — a countdown, a stock, a player count, the members of a list — is handed over as a lambda instead:
UiEntry.of(mine)
.with("mine_name", mine.name()) // read once
.withFormatted("next_reset", () -> MineStatus.nextReset(mine)) // read every redraw
menus.open(player, "mine_hub", Map.of(
"mine_id", mine.id(),
"next_reset", (Supplier<String>) () -> MineStatus.nextReset(mine))); // live context
menus.open(player, "mine_list", Map.of(),
() -> mines.all().stream().map(MineListMenu::row).toList()); // a list that follows
// or on a session: session.entries("mines", () -> rows());- The file needs nothing. A menu holding a live value or a followed list redraws every second as
SMARTwhen the file has norefreshblock. A file that writesmode: DISABLEDis obeyed. - A slot that would come out identical is not drawn again. A list of forty rows with one countdown renders one item a second. A slot showing a placeholder nobody handed over (PlaceholderAPI) cannot be judged that way and is redrawn on every timed refresh.
- A followed list keeps the reader's page, and a row created or deleted shows up without reopening.
- Lambdas run on the viewer's thread, every redraw. Read what is in memory, never a database.
- Titles do not re-read live values every second; they read them when sent (opening, turning a page).
live(name, supplier) and liveFormatted(...) are the older spellings and still work.
Several lore lines from one value#
A value containing <nl> becomes several lore lines, each keeping whatever the template puts around
the placeholder:
lore:
- "{muted} ┃ {letters}%description%" # one written line, two drawnname: "%name_color%&l%kit_name%" does not work and cannot. Substitution happens on the parsed
component tree — that is what lets a template be parsed once and shared by every row — and a bare
colour parses to an empty component carrying a colour, which does not reach the text beside it.
Pass the whole coloured phrase, or say which state the row is in and let a named template decide.
Templates by name#
Any key ending in template is one, named by what comes before it:
| Written | Named |
|---|---|
item_template | the default |
selected_template | selected |
no_permissions_template | no_permissions |
They are read by shape rather than from a fixed list, so a plugin invents whatever names it needs. A name the file does not declare draws the ordinary row rather than leaving an empty slot.
Groups: a row that closes ranks#
Cards that hide themselves — a feature switched off — leave holes when each has a fixed slot. Give
them a group instead, and the visible ones are laid out centred in the group's slots on every draw:
groups:
sections:
slots: "19-25" # order is the layout order
spacing: auto # auto (default), or a fixed gap such as 0 or 1
items:
land:
group: sections # instead of slot
condition: "%land_enabled% == true"
people:
group: sectionsMembers whose condition passes are placed in file order. With auto they keep one empty slot between
them while that fits, and sit side by side otherwise — on seven slots: one card at 22, two at 21 and 23,
three at 20, 22, 24, five at 20–24. An odd leftover leans left, and group slots left over are background.
An item takes slot/slots or group, never both. A group that names no slots, or an item naming
an undefined group, is reported and skipped. More visible members than slots: the extras are not drawn,
and the load warns when that can happen.
Fillers#
Three different jobs, not one list:
filler:
global: # everything left over
material: BLACK_STAINED_GLASS_PANE
hide_tooltip: true
pagination: # a list's empty slots, when it is short
material: LIGHT_GRAY_STAINED_GLASS_PANE
name: "{muted}No kits available"
custom: # named panels, each with its own slots
header:
material: GRAY_STAINED_GLASS_PANE
slots: "0-8"The pagination filler usually says something — it is what somebody with an empty list sees, and
treating it as another background tells them nothing.
Panels are drawn before the background, in file order, so the first to claim a slot keeps it.
A page button with nowhere to go is not drawn at all, and its slot goes back to whatever would otherwise cover it. An arrow that is there and does nothing is the same lie in every menu with a single page.
Conditions#
join:
slot: 10
material: LIME_DYE
condition: "%lfc_state% == none"Operators: == != > < >= <= contains startsWith endsWith, and a bare value read as a
boolean.
Two items may claim the same slot: they are one button in two states, and the first whose condition passes is drawn.
A slot whose condition fails is not blank — it is not there, so clicking it does nothing. A condition that cannot be read hides the slot, because failing the other way would hand a button to somebody who should not have it.
Clicks#
actions:
- "left: practice:adjust_priority 1"
- "right: practice:adjust_priority -1"
- "left,right: practice:open_details"Kinds: left, right, middle, shift_left, shift_right, drop, control_drop, swap,
double, number_key, and any for a line with no prefix.
Every decision is made against the session, never against the item the client says it clicked: the packet carries a slot number, and the server already knows what it drew there. A button is never picked up, and a drag touching any button is refused.
A slot outside the window — left behind by a smaller size — is reported when the file loads and
skipped, and the rest of the menu opens.
One click, one run#
Some single gestures reach the server as a burst: a shift-double-click sends one shift-click on press
and another for every matching slot on release, and a double-click follows its click with a
DOUBLE_CLICK. Every menu goes through ClickGuard, so a button runs at most once per player per
cooldown — 150 ms by default — and a DOUBLE_CLICK never runs anything. A refused click is still
cancelled.
click_cooldown: 250 # milliseconds for this menu; 0 turns the guard offClickGuard.cooldown(Duration) changes the server-wide default. A plugin with its own Bukkit inventory
uses the same guard:
event.setCancelled(true);
if (!ClickGuard.tryClick(event)) return; // DOUBLE_CLICK, or inside the cooldownBuilt-in actions#
Registered for every plugin that asks for menus, because turning a page is nobody's feature:
| Action | What it does |
|---|---|
next_page, previous_page | Move the only list, or a named one: next_page players. |
back | The menu they came from, at the page they left it. |
close | Shut the window. |
refresh | Redraw everything. |
A plugin registering its own action by one of these names wins.
Editable slots#
size: 54
editable_slots: '0-4,9-44'Slots listed here stay the player's. Buttons around them make it an editor rather than a drop box:
session.input(slot, null); // clear one
session.inputs(fromInventory(player)); // fill from what they carry
Map<Integer, ItemStack> layout = session.inputs(); // read it back to saveBoth writers refuse a slot that is not an input slot, and inputs(map) checks every slot before
writing any of them — a half-applied layout is one the player cannot tell from the one they asked for.
That is how a kit layout, a shop's stock or an arena loadout is edited: the slots themselves are the record, so armour stays in the armour slots and the hotbar stays the hotbar.
Redrawing#
A slot declares what it is derived from:
elo:
slot: 22
material: DIAMOND
name: "{letters}Rating: {highlight}%elo%"
depends-on:
- statssession.invalidate("stats"); // only slots that said they depend on stats
session.invalidateSlot(13); // one slot
session.refresh(); // everything — rarely the right answerA menu can also redraw itself:
refresh:
mode: SMART # DISABLED | FULL | SMART | ON_CLICK
interval: 20 # ticks, for the timed modes; 1s says the same
click_delay: 4 # ticks after a click, for ON_CLICK and SMART| Mode | When |
|---|---|
DISABLED | Only when a plugin asks. The default — except a menu holding a live value, which redraws every second as SMART. |
FULL | Everything, on the interval. |
SMART | On the interval, but only slots that can differ — and after a click. |
ON_CLICK | After a click, once click_delay has passed. |
A timer that redraws static decorations is packets for an identical item. SMART only starts a timer
if the menu has something that could change, and it dies with the player.
A click redraws everything that can change, not only the slot it landed on: adding a layer moves a counter, a preview and a list, and none of those is the slot that was clicked.
Where a player was#
A player who closes a menu and opens it again is put back where they were: the page of every list is restored on its own. Anything else worth keeping — the tab that was open, a filter — is marked by the menu and read back before it opens, because which tab is open decides which rows there are:
session.remember("category"); // while it is open
Object tab = menus.remembered(player, "effects").get("category"); // before opening it againReading does not consume it, and nothing is put back behind the caller's back: what to do with it is the menu's decision. Check it against the catalogue as it is now — a tab that was renamed between two visits would otherwise draw an empty grid with no way out.
The click before it already ran the button, so delivering the pair would run it twice — a toggle clicked quickly would turn itself back off. It is refused before it reaches a handler.
Sounds#
sounds:
open: "minecraft:block.ender_chest.open|1.0|1.4"
click: "minecraft:block.note_block.hat|1.0|1.0"
denied: "" # silence, which is not the same as absentNames: open, close, click, denied, failed. The older root lists (open_sounds,
click_sounds, close_sounds…) also work, only their first entry is played, and the block wins where a
file has both.
Anything not written falls back to the defaults:
| Sound | Default |
|---|---|
open | minecraft:block.ender_chest.open|1.0|1.4 |
close | minecraft:block.barrel.close|1.0|0.7 |
click | minecraft:block.note_block.hat|1.0|1.0 |
denied | BLOCK_NOTE_BLOCK_BASS|0.6|0.8 |
failed | ENTITY_VILLAGER_NO|0.6|1 |
A button can sound like itself instead of the click — page arrows and back buttons carry theirs:
pagination:
navigation:
next:
slot: 50
sound: "minecraft:item.book.page_turn|1.0|1.0"
items:
back:
slot: 49
sound: "minecraft:item.bundle.remove_one|1.0|0.5"sound: "" makes a button silent; no sound means the menu's click.
One menu replacing another — a button, a command, back — is one screen changing: the old menu's close
sound and the new one's open sound are both skipped, so the click is heard on its own. A button whose
action makes a menu sound (close, a refusal) plays that instead of the click, not on top of it.
denied and failed play when a button refuses, so a click that did nothing sounds different from
one that worked — the single most common "the menu is broken" report.
Lifecycle#
Nothing outlives its screen. An action sequence with a delayed step, started by a button, is cancelled when the menu closes. Disabling a plugin closes its windows before releasing its tasks.
Menus are found through the window's holder rather than a map keyed by player, so a player opening a chest on top of a menu is not mistaken for one of ours. The holder is read without touching the world, so a chest closing on Folia — a player leaving or teleported away — never throws off its region thread.
Menus no longer animate when they open: every slot appears at once. An animation key left in an old
file is ignored.
Something missing on this page? Tell us on Discord