menus

All three menus are files in guis/. You can retheme them freely: titles, sizes, backgrounds, buttons and the flash icons for refused clicks. 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 a Temporary-Icons section. The main menu also has three slot lists for the tier rows.

Every entry in Items is an item with Slot: (one number) or Slots: (a list where each entry is a number or an a-b inclusive range). Every slot must be inside Size, or the load fails.

• An item without Actions is decoration (background panes and so on).
• An item with Actions runs them on click. The menu reacts to the action, not to the item’s key, so you can rename and move items freely.
• Actions: [] renders the item with its tokens filled in but does nothing on click. The page indicator and the confirm menus’ Info-Item use this.

When two items cover the same slot, the one with fewer slots wins, so a full-size background never covers a button.

The Title is resolved once when the menu opens.

Item fields

Field	Default	Description
Material	required	Any material name; legacy and modern names both work. An unknown name fails the load.
Name	none	Item display name.
Lore	[]	Lore lines.
Amount	1	Stack size.
Base64	none	Head texture for a PLAYER_HEAD. The value "{player}" shows the viewing player’s own head.
Custom-Model-Data	none	Custom model data for resource packs.
Item-Model	none	Item model id for resource packs.
Glow	false	Adds an enchant glint.
Item-Flags	[]	Item flags, e.g. HIDE_ADDITIONAL_TOOLTIP on the potion.
Hide-Tooltip	false	Hides the whole tooltip.

Enchantments, Unbreakable, Damage and Attributes are also accepted. The same item format is used by the reward and progression icons in config.yml.

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
    Slots: [0-44]
    Name: "&r"

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

  Profile-Item:
    Material: PLAYER_HEAD
    Base64: "{player}"
    Slot: 3
    Name: "&b&lPass Profile"
    Lore:
      - "&7You can get Pass XP by farming"
      - "&7and mining blocks in any world."
      - ""
      - "&bInformation:"
      - "&3 - &7Status: {status}"
      - "&3 - &7Rewards: &a{claimed-rewards}&8/&c{total-rewards}"
      - ""
      - "&e➥ Click to purchase!"
    Actions:
      - "[buy-premium]"

  Multiplier-Item:
    Material: POTION
    Slot: 5
    Name: "&d&lPass Multiplier"
    Item-Flags: [HIDE_ADDITIONAL_TOOLTIP]
    Lore:
      - "&7Increase the speed in which you"
      - "&7get battlepass experience."
      - ""
      - "&dInformation:"
      - "&5 - &7Price: &c{multiplier-price} &4Credits"
      - "&5 - &7Multiplier: &f{multiplier}x &8-> &f{next-multiplier}x"
      - ""
      - "&e➥ Click to purchase!"
    Actions:
      - "[buy-multiplier]"

  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]"

The price lines say Credits because the default currency is RivalCredits. Change the text if you switch currency.

The three slot lists

Key	Default	Description
Free-Reward-Slots	[9-17]	Where each tier’s free reward icon goes.
Progression-Slots	[18-26]	Where each tier’s progression icon goes.
Premium-Reward-Slots	[27-35]	Where each tier’s premium reward icon goes.

All three lists must be the same length, or the load fails. The n-th entry of each list is one tier’s column. The list length is the number of tiers per page: nine by default, so 15 tiers make two pages. Adding tiers adds pages automatically.

Background items are painted first and the default Barrier-Item covers both reward rows, so a tier without a free or premium reward shows a plain pane in that slot. Clicking such a slot does nothing. On a last page with fewer tiers than slots, the leftover slots show the background too.

Every time the menu opens (including when a confirm menu returns to it), it jumps to the page with the player’s current tier.

Confirmation menus

confirm-multiplier-menu.yml and confirm-premium-menu.yml share one layout: a [confirm] button, a [cancel] button and an Info-Item with Actions: []. This is the premium one:

Title: "Confirm Purchase"
Size: 9

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

  Info-Item:
    Material: PLAYER_HEAD
    Base64: "{player}"
    Slot: 4
    Name: "&b&lPass Premium"
    Lore:
      - "&7Unlock the premium reward track and"
      - "&7claim every premium tier reward."
      - " "
      - "&3 - &bPrice: &c{price} &4Credits"
    Actions: []

  Confirm-Item:
    Material: LIME_DYE
    Slots: [0-3]
    Name: "&a&lConfirm Action"
    Lore:
      - "&8Pass Premium"
      - " "
      - "&7Complete this purchase using"
      - "&7your available credits."
      - " "
      - "&e➥ Click to confirm action!"
    Actions:
      - "[confirm]"

  Cancel-Item:
    Material: RED_DYE
    Slots: [5-8]
    Name: "&c&lCancel Action"
    Lore:
      - "&8Pass Premium"
      - " "
      - "&7Cancel this purchase and"
      - "&7return to the main menu."
      - " "
      - "&e➥ Click to cancel action!"
    Actions:
      - "[cancel]"

The multiplier file is the same with a POTION Info-Item showing {multiplier-price}, {multiplier} and {next-multiplier}.

Which purchase a confirm menu makes is decided by which file it is: the multiplier file always buys a multiplier step, the premium file always buys the pass.

• A successful [confirm] takes the money, plays PURCHASE and returns to the battle pass menu.
• A refused [confirm] plays DENY and flashes a temporary icon on the button.
• [cancel] and closing the menu with Escape both return to the battle pass menu.

Built-in actions

Action	Menu	Does
[previous]	main	Back one page. On page 1: NO-PAGE-FOUND sound and the No-Previous-Page flash.
[next]	main	Forward one page. On the last page: NO-PAGE-FOUND sound and the No-Next-Page flash.
[buy-multiplier]	main	Checks the purchase, then opens the multiplier confirm menu. Refusals flash Multiplier-Maxed or Insufficient-Funds on the clicked item.
[buy-premium]	main	Checks the purchase, then opens the premium confirm menu. Refusals flash Premium-Owned or Insufficient-Funds.
[confirm]	confirm	Makes the purchase.
[cancel]	confirm	Back to the battle pass menu.

[previous-page] and [next-page] work as aliases of [previous] and [next]. Page turns repaint in place. No money moves until [confirm]: the main-menu buttons only check.

Clicking a reward icon in the free or premium row claims it; that needs no action.

When a purchase is disabled (Purchasable: false) or its currency is unavailable, the click sends the matching message and plays DENY without a flash.

Generic actions

Available on any item in any of the three menus:

Action	Does
[command] <cmd> / [console] <cmd>	Run a command as 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 an action bar message.
[title] title;subtitle;in;stay;out	Show a title.
[sound] <sound>	Play a sound.
[close]	Close the menu.
[back]	Go back to the previous menu.
[open-battlepass] / [battlepass]	Open the battle pass menu.

The argument is the text after ]. {player}, {uuid}, the menu’s own 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

Every item in battlepass-menu.yml 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.
{status}	Free-Status or Premium-Status from config.yml.
{claimed-rewards} / {total-rewards}	Rewards claimed and rewards on the track. Premium rewards only count once the player owns the pass.
{page} / {pages}	Current page and page count. {max-page} is the same as {pages}.
{results}	Number of enabled tiers.

Confirm menu items get {price} (the price of that menu’s purchase), {exp}, {tier}, {multiplier}, {next-multiplier}, {multiplier-price} and {premium-price}.

Reward and progression icons have their own token sets, see config.yml.

Temporary icons

Each menu file has a Temporary-Icons section: icons that flash for about two seconds in the clicked slot when a click is refused, then restore the real icon. While a slot is flashing, clicks on it are ignored, so the deny sound and message can’t be spammed. A successful click never flashes.

Each entry is a normal item. Remove one and that refusal just plays DENY and sends its message without a flash.

battlepass-menu.yml

Temporary-Icons:
  Locked:
    Material: BARRIER
    Name: "&c&lError!"
    Lore:
      - "&7You need &f{required} EXP &7to unlock this tier!"
  Already-Claimed: { ... }
  Premium-Required: { ... }
  Insufficient-Funds: { ... }
  Multiplier-Maxed:
    Material: BARRIER
    Name: "&c&lError!"
    Lore:
      - "&7Your multiplier is already maxed at &f{max}x&7!"
  Premium-Owned: { ... }
  No-Previous-Page: { ... }
  No-Next-Page: { ... }

Key	Flashed when	Extra tokens
Locked	A reward of a tier the player has not reached is clicked.	{tier}, {required}, {exp}
Already-Claimed	A reward that was already claimed is clicked.
Premium-Required	A premium reward is clicked without the Premium Pass.
Insufficient-Funds	A purchase button is clicked without enough money.	{price}
Multiplier-Maxed	The multiplier button is clicked at Max.	{max}
Premium-Owned	The pass button is clicked by a player who already owns it.
No-Previous-Page	[previous] on the first page.
No-Next-Page	[next] on the last page.

Turning a page drops any flash on the three tier rows, so a flash never sits on a different tier.

Confirm menus

File	Keys
confirm-multiplier-menu.yml	Insufficient-Funds, Multiplier-Maxed
confirm-premium-menu.yml	Insufficient-Funds, Premium-Owned

These flash on the confirm button when the purchase fails at the last moment (for example, the player spent the money between opening the confirm menu and clicking). They get every confirm menu token plus {max}.