menus

The /milestones menu is guis/milestones-menu.yml. You can retheme it freely - title, size, background, page buttons. 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

The root holds Title, Size (a multiple of 9), Milestone-Slots and an Items section. Inside Items there are two kinds of entry, told apart by one thing only:

• Fillers - any entry with no Actions key. Painted into its slots as background.
• Action items - any entry with an Actions list. The menu dispatches on the action, not the entry’s key, so you can rename and move these freely.

An entry with Actions: [] is an action item with nothing to do: it renders with tokens filled in but clicking it does nothing. That is how the page indicator works.

Slots use either Slot: (a single number) or Slots: (a list where each entry is a number or an a-b inclusive range). An entry with neither is skipped.

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

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

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

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

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

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

Item fields

The same shape is used by the category selector icons and the temporary icons.

Field	Default	Description
Material	required	Any material name; resolved through XSeries. An unknown name fails the load.
Amount	1	Stack size.
Base64	none	Head texture value, applied when the material is a player head.
Custom-Model-Data	0	0 leaves it unset.
Name	none	Item display name.
Lore	[]	Lore lines.
Glow	false	Adds an enchant glint.
Item-Flags	[]	Bukkit item flags, e.g. HIDE_ATTRIBUTES.

Milestone state icons take a slightly different set - they add Primary and Secondary and drop Amount (the stack size is the milestone number). See icon fields.

Milestone-Slots

The list length is the page size. The default 21 slots mean 21 milestones per page, so a 24-entry category paginates into two pages.

The default file ships two fillers on purpose: a black border over the whole inventory, then a gray pane over the grid itself. A page with fewer milestones than slots still looks intentional, because the gray panes stay where a milestone would be.

Render order

Fillers first, then action items, then the category selector row, then the milestone grid. A filler covering a milestone slot or a category slot is harmless - the dynamic content always wins.

The menu opens on the page containing the player’s first unclaimed milestone, so long tracks land where the player actually is. Switching category recalculates that.

Built-in actions

Action	Does
[previous-page]	Back one page. At page 1: NO-PAGE-FOUND + the No-Previous-Page flash.
[next-page]	Forward one page. At the last page: NO-PAGE-FOUND + the No-Next-Page flash.

Page turns re-render in place - the inventory is not reopened.

Generic actions

Available on any item, run when the click isn’t a built-in action:

• [command] / [console] <cmd> - run as console
• [player] <cmd> - run as the player
• [message] <text> - send a chat message
• [close] - close the menu
• [open-milestones] / [milestones] - reopen the menu on the default category

The argument is the text after ]. {player} and, with PlaceholderAPI installed, %...% are resolved in it.

An item may list several actions; they run in order on click.

Tokens

Title and every Items entry get the active category’s tokens plus the pagination pair:

Token	Value
{page}	Current page, 1-based.
{pages}	Total pages in the active category.
{category}	The active category’s Display-Name.
{complete}	Milestones claimed in it.
{total}	Milestones in it.
{reached}	Thresholds met, claimed or not.
{progress}	Current progress, comma-grouped.
{percent} / {progress-bar}	Claimed ÷ total for the active category.

Title is rendered once when the menu opens, so it does not update on a page turn or a category switch. Put live values in Items instead - those repaint every render.

Milestone icons and category selector icons get their own, richer token sets, documented in milestones.

Clicks

Clicked	Behaviour
A milestone in the grid	Claim it. Refusals flash Locked or Already-Claimed.
Another category’s icon	Switch to it in place, reset to its first unclaimed page, CATEGORY-CHANGED.
The current category’s icon	Already-Selected flash + deny sound.
A page button	Turn the page, or flash the matching edge icon.

Blocked clicks

The icons flashed on a refused click, and the sounds the menu plays, live in config.yml, not in this file.