menus

All three menus are files in guis/. You can retheme them freely - titles, sizes, backgrounds and buttons. After editing, run /battlepassadmin reload.

File	Menu
battlepass-menu.yml	The /battlepass menu.
confirm-multiplier-menu.yml	Confirmation before buying a multiplier step.
confirm-premium-menu.yml	Confirmation before buying the Premium Pass.

How a menu file works

The root holds Title, Size (a multiple of 9), an Items section, and (in the main menu) three slot lists. 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. Both the page indicator and the confirm menus’ Information item use that.

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.

Item fields

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. The literal string "{player}" uses the viewing player’s own 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_ADDITIONAL_TOOLTIP on the potion.

battlepass-menu.yml

Title: "Battle Pass"
Size: 45
Free-Reward-Slots: [9-17]
Progression-Slots: [18-26]
Premium-Reward-Slots: [27-35]

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

  Filler-Item2:
    Material: GLASS_PANE
    Name: "&r"
    Slots: [9, 10, 11, 12, 13, 14, 15, 16, 17, 27, 28, 29, 30, 31, 32, 33, 34, 35]

  Profile:
    Material: PLAYER_HEAD
    Base64: "{player}"
    Slot: 3
    Name: "&b&lPass Profile"
    Lore:
      - "&3 - &7Status: {status}"
      - "&3 - &7Rewards: &a{claimed-rewards}&8/&c{total-rewards}"
      - ""
      - "&e➥ Click to purchase!"
    Actions:
      - "[buy-premium]"

  Multiplier:
    Material: POTION
    Slot: 5
    Name: "&d&lPass Multiplier"
    Item-Flags:
      - "HIDE_ADDITIONAL_TOOLTIP"
    Lore:
      - "&5 - &7Price: &c{multiplier-price} &4Credits"
      - "&5 - &7Multiplier: &f{multiplier}x &8-> &f{next-multiplier}x"
      - ""
      - "&e➥ Click to purchase!"
    Actions:
      - "[buy-multiplier]"

  Previous-Page: { … Actions: ["[previous-page]"] }
  Page-Indicator: { … Actions: [] }
  Next-Page:     { … Actions: ["[next-page]"] }

The three slot lists

Free-Reward-Slots, Progression-Slots and Premium-Reward-Slots must be equal length. The n-th entry of each is one tier’s column: its free reward on top, its progress bar in the middle, its premium reward below.

The list length is the tiers per page. Nine by default, so 15 tiers become two pages.

Fillers are painted first and deliberately cover the two reward rows, so a tier with no reward on one track shows clean filler rather than an empty slot. The progression icon always renders.

The menu opens on the page containing the player’s current tier.

Confirmation menus

Both confirm files share one layout: Title, Size, and Items holding a [confirm] button, a [cancel] button and an Information display with Actions: [].

Title: "Confirm Purchase"
Size: 9

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

  Information:
    Material: PLAYER_HEAD
    Base64: "{player}"
    Slot: 4
    Name: "&b&lPass Premium"
    Lore:
      - "&3 - &bPrice: &c{price} &4Credits"
    Actions: []

  Confirm:
    Material: LIME_DYE
    Slots: [0-3]
    Name: "&a&lConfirm Action"
    Actions:
      - "[confirm]"

  Cancel:
    Material: RED_DYE
    Slots: [5-8]
    Name: "&c&lCancel Action"
    Actions:
      - "[cancel]"

A button can occupy several slots via Slots, which is how the defaults give confirm and cancel four slots each.

Which purchase a confirm menu performs is decided by which file it is, not by the item - the multiplier file always buys a multiplier step. {price} resolves to that purchase’s price.

Closing a confirm menu reopens the battle pass

Any close - [cancel], a completed purchase, or pressing Escape - returns the player to the main menu. That is why the cancel and success paths just close the inventory.

Built-in actions

Action	Menu	Does
[previous-page]	main	Back one page. At page 1: NO-PAGE-FOUND + the No-Previous-Page flash.
[next-page]	main	Forward one page. At the last page: NO-PAGE-FOUND + the No-Next-Page flash.
[buy-multiplier]	main	Validate, then open the multiplier confirm menu. Refusals flash Multiplier-Maxed or Insufficient-Funds on the clicked item.
[buy-premium]	main	Validate, then open the premium confirm menu. Refusals flash Premium-Owned or Insufficient-Funds.
[confirm]	confirm	Run the purchase. On success, plays PURCHASE and closes.
[cancel]	confirm	Close, which returns to the battle pass.

Page turns re-render in place. No money moves until [confirm] - the main-menu buttons only check.

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-battlepass] / [battlepass] - reopen the battle pass menu

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

Every Items entry in the main menu gets:

Token	Value
{exp}	Pass EXP, comma-grouped.
{tier}	Current tier (0 before tier 1).
{multiplier}	Current multiplier, e.g. 1.1.
{next-multiplier}	What the next purchase would give, capped at Max.
{multiplier-price}	Price per multiplier step.
{premium-price}	Premium Pass price.
{page} / {pages}	Pagination.
{status}	Free-Status or Premium-Status from config.yml.
{claimed-rewards} / {total-rewards}	Rewards claimed and available. Premium rewards only count once the player owns the pass.

Confirm menu items get the same set minus the pagination and status tokens, plus:

Token	Value
{price}	That menu’s purchase price.

Title is rendered once when the menu opens, so it does not update on a page turn.

Reward and progression icons get their own token sets, documented in config.yml.

Blocked clicks

The icons flashed on a refused click, and the sounds the menus play, live in config.yml, not in these files.