GUI Customization

GUI Customization

Every menu is a file in plugins/RoyalBank/gui/, written in the EcoMenus dialect shared across the Royal suite (RoyalAuctions, RoyalBazaar). Run /bank reload after editing.

File	Menu
main.yml	The main bank screen (/bank)
deposit.yml	Deposit amount picker
withdraw.yml	Withdraw amount picker
transactions.yml	Recent transactions view
confirm-upgrade.yml	Upgrade confirmation

File structure

title: "&6&lBank"
rows: 4

sounds:
  open:    { enabled: true, name: UI_BUTTON_CLICK, volume: 0.7, pitch: 1.2 }
  success: { enabled: true, name: ENTITY_EXPERIENCE_ORB_PICKUP, volume: 0.8, pitch: 1.4 }
  fail:    { enabled: true, name: ENTITY_VILLAGER_NO, volume: 0.7, pitch: 1.0 }
  prompt:  { enabled: true, name: BLOCK_NOTE_BLOCK_PLING, volume: 0.7, pitch: 1.5 }

pages:
  - page: 1
    mask:
      items:
        - gray_stained_glass_pane    # filler item
      pattern:                        # 1 = filler, 0 = a content slot (e.g. the transaction list)
        - "111111111"
        - "111111111"
        - "111111111"
        - "111111111"

slots:
  - item: chest name:"&a&lDeposit Coins"
    lore:
      - "&7Purse: &6%purse%"
      - "&7Bank: &6%balance%&7/&6%max_balance%"
      - ""
      - "&eClick to deposit!"
    row: 2
    column: 3
    left-click:
      - id: open_menu
        args:
          menu: deposit

Top-level keys

Key	Meaning
title	Inventory title (& colour codes; supports %placeholders%).
rows	Menu height, 1–6.
sounds	Sounds for open / success / fail / prompt events. Each has enabled, name (a Bukkit Sound), volume, pitch.
pages[].mask	The background: items (filler) painted onto every 1 in pattern; 0 marks a content slot (the transaction grid fills these).
slots	The buttons — a list, each positioned by row/column.

Slot keys

Key	Meaning
item	Inline item spec: material [hide_enchants] [hide_attributes] name:"...". A vanilla material, an ecoitems:<id> (resolved via eco when installed), or a player head.
lore	Lore lines (support %placeholders%).
row / column	1-based position, placed directly on the slot (row 1 = top).
left-click / right-click	Effect lists run on click (see below). If right-click is omitted, a right-click runs the left-click list.
id	Optional tag. id: upgrade marks the upgrade button so it can show a locked state.
locked-item / locked-lore	Alternate appearance for the upgrade slot before upgrades are unlocked.

Effects

Each left-click / right-click entry is id: + optional args:.

Effect	Args	Does
open_menu	menu: main|deposit|withdraw|transactions|confirm-upgrade	Open another bank menu
deposit	amount: all | half | custom | <number>	Deposit (custom prompts in chat)
withdraw	amount: all | half | twenty | custom | <number>	Withdraw (custom prompts in chat)
upgrade	—	Open the upgrade confirmation
confirm_upgrade	—	Perform the tier upgrade
claim_interest	—	Claim available interest
close_inventory	—	Close the menu
play_sound	sound, volume, pitch	Play a sound

  - item: hopper name:"&a&lDeposit All"
    row: 2
    column: 3
    left-click:
      - id: deposit
        args:
          amount: all

A slot with no effect list is decorative (an info panel). The chat-prompt (amount: custom) listens for settings.custom-amount-timeout-seconds before it stops capturing input.

Player heads

Custom-textured heads work the same way the eco suite does them — no eco dependency required:

- item: player_head texture:<base64>      # a custom head from a base64 texture value
- item: player_head head:%player%         # the viewing player's own head
- item: player_head head:Notch            # a specific player's head
- item: player_head texture:<base64> name:"&aDeposit"   # combined with a name

Use these in any slot's item. A malformed texture safely falls back to a plain head rather than breaking the menu.

Eco items & upgrade-cost icons

When eco is installed, an item: ecoitems:<id> in any slot renders the real custom item (texture and all). Without eco, it falls back to a plain item.

The confirm-upgrade menu goes a step further: its 0 mask slots are filled automatically with an icon per required item from the tier's upgrade-cost.items — the real item, with live Required / You have counts. You don't hand-place these; edit the cost in config and the icons follow.

Placeholders

Menu text uses %token% placeholders (the same %...% style as the eco suite):

Token	Value		Token	Value
%balance%	Bank balance		%half_purse%	Half the purse
%max_balance%	Tier max balance		%half_balance%	Half the balance
%bank_space%	Remaining room		%twenty_balance%	20% of the balance
%purse%	Vault purse		%account_level%	Tier number
%next_interest%	Next interest amount		%account_name%	Tier display name
%interest_time%	Time until next claim		%combined_balance%	Bank + purse
%max_interest%	Interest cap		%upgrade_unlock_balance%	Combined balance to unlock upgrades
%player%	Player name		%upgrade_info%	Multi-line next-tier summary (expands to several lore lines)

These %token% values are RoyalBank's own GUI placeholders. PlaceholderAPI's %royalbank_...% placeholders (for scoreboards, chat, holograms) are separate — see PlaceholderAPI.

Permission-aware buttons

Buttons enforce the same permissions as their command. A player without royalbank.deposit sees the Deposit button but can't use it — restrict via permissions, not by editing the menu, so the layout stays consistent across ranks.