menus

The /milestones menu is guis/milestones-menu.yml. You can retheme it freely: title, size, background, page buttons and the icons flashed on refused clicks. After editing, run /milestonesadmin reload.

Category positions are not in this file. Each category carries its own Menu.Slot in its own file, so this file describes the grid and the frame around it.

How the file works

Title: "Milestones"
Size: 45
Milestone-Slots: [10-16, 19-25, 28-34]

Items:
  Filler-Item:
    Material: BLACK_STAINED_GLASS_PANE
    Slots: [0-44]
    Name: "&r"

  Barrier-Item:
    Material: GLASS_PANE
    Slots: [10-16, 19-25, 28-34]
    Name: "&r"

  Previous-Item:
    Material: ARROW
    Slot: 39
    Name: "&c&l<- Previous Page"
    Lore:
      - "&7Click to view previous page"
    Actions:
      - "[previous]"

  Page-Indicator:
    Material: CLOCK
    Slot: 40
    Name: "&e&lPage: &6#{page}"
    Lore:
      - "&7Viewing page &f{page} &7out of &f{pages}&7."
    Actions: []

  Next-Item:
    Material: ARROW
    Slot: 41
    Name: "&a&lNext Page ->"
    Lore:
      - "&7Click to view next page"
    Actions:
      - "[next]"

Temporary-Icons:
  Locked: { ... }
  Already-Claimed: { ... }
  Already-Selected: { ... }
  No-Previous-Page: { ... }
  No-Next-Page: { ... }

Key	Description
Title	The inventory title. Rendered once when the menu opens; see tokens.
Size	Inventory size: a multiple of 9, from 9 to 54.
Milestone-Slots	The slots milestones are drawn in. See below.
Items	Decoration and buttons.
Temporary-Icons	Icons flashed when a click is refused. See below.

Inside Items, every entry is an item at one or more slots:

• An entry without Actions is pure decoration.
• An entry with an Actions list runs those actions on click. Actions: [] renders the item (with tokens filled in) but clicking does nothing - that is how the page indicator works.

The entry names (Filler-Item, Next-Item, …) are only labels. The menu reacts to the actions, not the names, so you can rename, add and remove entries freely.

Slots use either Slot: (one number) or Slots: (a list where each entry is a number or an a-b inclusive range). A slot outside Size fails the load.

Item fields

The same item format is used by menu items, temporary icons, category selector icons and milestone state icons.

Field	Default	Description
Material	required	Any material name. An unknown name fails the load.
Amount	1	Stack size. Ignored on milestone icons, whose stack size is the milestone number.
Name	none	Display name.
Lore	[]	Lore lines.
Base64	none	Head texture value, for PLAYER_HEAD items. Texture is accepted as well.
Custom-Model-Data	0	0 leaves it unset.
Item-Model	none	An item model key, for resource packs.
Glow	false	Adds an enchant glint.
Color	none	Dye color for leather armor and similar items.
Unbreakable	false	Marks the item unbreakable.
Hide-Tooltip	false	Hides the whole tooltip.
Item-Flags	[]	Bukkit item flags, e.g. HIDE_ATTRIBUTES.

Milestone-Slots

The list length is the page size. The default 21 slots mean 21 milestones per page, so the 24-milestone blocks category has two pages.

The default file uses two decoration items on purpose: a black border over the whole inventory, then plain glass panes over the grid. On a page with fewer milestones than slots, the empty grid slots still look intentional.

Render order

1. Menu items. The broadest item (most slots) paints first, and the item with the fewest slots wins a shared slot, so a full-size background never covers a button.
2. The category selector icons, each at its category’s Menu.Slot. The one being viewed glows.
3. The milestones of the current page in Milestone-Slots.

A background item covering a milestone or category slot is harmless, the dynamic content always wins.

The menu opens on the page holding the player’s first unclaimed milestone. Switching category does the same for the new category. The menu redraws after a claim, a page turn or a category switch; it does not tick on its own while open.

Clicks

Clicked	Result
A milestone	Claim it. Refused: DENY sound and the Locked or Already-Claimed flash.
Another category’s icon	Switch to it in place, CATEGORY-CHANGED sound.
The category being viewed	DENY sound and the Already-Selected flash.
A page button	Turn the page (PAGE-CHANGED), or NO-PAGE-FOUND and the matching edge flash.

Page turns and category switches redraw the open inventory; it is not reopened.

Actions

Menu actions:

Action	Does
[previous]	Back one page. [previous-page] works too.
[next]	Forward one page. [next-page] works too.
[open-milestones] / [milestones]	Reopen the menu on the default category.

General actions:

Action	Does
[command] <cmd>	Run a command from console.
[console] <cmd>	Run a command from console.
[player] <cmd>	Run a command as the player.
[message] <text>	Send the player a chat message.
[broadcast] <text>	Send a message to everyone.
[actionbar] <text>	Show text above the hotbar.
[title] <title>;<subtitle>;<fade-in>;<stay>;<fade-out>	Show a screen title. Everything after the title is optional; times are ticks (defaults 10, 60, 10).
[sound] <NAME;volume;pitch>	Play a sound to the player.
[close]	Close the menu.

The argument is the text after ]. {player}, {uuid}, the menu tokens and, with PlaceholderAPI, %...% are resolved in it. An item may list several actions; they run in order.

A line without a [type], or with a type that is not listed here, does nothing.

Tokens

Title and every Items entry get the viewed category’s tokens:

Token	Value
{category}	The category’s Display-Name.
{complete}	Milestones claimed in it.
{total}	Milestones in it.
{reached}	Thresholds met, claimed or not.
{progress}	The player’s progress, comma-grouped.
{percent} / {progress-bar}	Claimed out of total.
{page}	Current page, from 1.
{pages}	Number of pages in the category.

Items additionally get {max-page} (same as {pages}) and {results} (the number of milestones in the category).

Title is rendered once when the menu opens, so it shows the category and page the menu opened on and does not change on a page turn or category switch. Put live values on items instead - they are redrawn every time the menu redraws.

Category selector icons and milestone icons have their own token sets, documented in milestones.

Temporary-Icons

Icons that flash for two seconds in the clicked slot when a click is refused, then restore the real item. While a slot is flashing it ignores clicks, so the deny sound can’t be spammed. A claim or a category switch clears every flash.

Temporary-Icons:
  Locked:
    Material: BARRIER
    Name: "&c&lError!"
    Lore:
      - "&7You need to meet requirements!"
  Already-Claimed:
    Material: RED_STAINED_GLASS_PANE
    Name: "&c&lError!"
    Lore:
      - "&7You already claimed this reward!"
  Already-Selected:
    Material: BARRIER
    Name: "&c&lError!"
    Lore:
      - "&7You are already viewing this category!"
  No-Previous-Page:
    Material: BARRIER
    Name: "&c&lError!"
    Lore:
      - "&7You are already on the first page!"
  No-Next-Page:
    Material: BARRIER
    Name: "&c&lError!"
    Lore:
      - "&7You are already on the last page!"

Key	Flashed when	Tokens
Locked	A milestone below its threshold is clicked.	{category}, {milestone}, {number}, {progress}, {required}
Already-Claimed	A claimed milestone is clicked.	none
Already-Selected	The category being viewed is clicked.	{category}, {complete}, {total}, {reached}, {progress}, {percent}, {progress-bar}
No-Previous-Page	Previous page is clicked on page 1.	the menu tokens
No-Next-Page	Next page is clicked on the last page.	the menu tokens

Every icon is optional and the keys are not case-sensitive. Delete one and that refusal only plays its sound (and, for claims, sends its message) without a flash. Each icon uses the standard item fields.

The sounds the menu plays are set in config.yml.

Older menu files keep working

Menu files from earlier versions, with Filler-Item2, Previous-Page and Next-Page entries and the [previous-page] / [next-page] actions, load unchanged. If your Temporary-Icons are still in config.yml from an older version, move them into this file.