Menus and GUI

Menus & GUI

Every screen is a file in plugins/RoyalAuctions/gui/, authored in the EcoMenus dialect — the same shape you know from EcoMenus/EcoShop. Run /ah reload after editing.

File	Menu
hub.yml	The landing menu (/ah)
browse.yml	The Auction Browser
bids.yml	View Bids
manage.yml / seller.yml	Manage your listings / a player's listings
create.yml	Create Auction
duration.yml	Duration picker
bid.yml	Place Bid
collection.yml	Claim purchases / returned items
confirm-purchase.yml	Buy-It-Now confirmation
confirm-auction.yml	Final create confirmation
confirm-bid.yml	Bid confirmation
confirm-cancel.yml	Cancel confirmation

Anatomy of a menu

title: "&8Auction Browser"
rows: 6

mask:
  items:
    - red_stained_glass_pane      # 1 — mask.items filler, referenced by digit
    - black_stained_glass_pane    # 2
  pattern:
    - "A10000000"                 # digits = mask.items; 0/letters = dynamic regions
    - "A67777777"

regions:
  category-slots: "A"             # a named dynamic region
  content-slots: "0"             # the listings grid

slots:
  - id: sort
    item: 'hopper name:"&eSort: &f%sort%"'
    lore:
      - "&7Click to change sorting."
    row: 6                        # 1-based row/column, placed directly on the slot
    column: 6
    left-click:
      - id: ah_sort

• mask.pattern — one line per row, 9 chars each. A digit places the matching mask.items entry; a 0 or letter marks a dynamic region.
• regions — names a mask letter/0 so code can fill it (the category column, the listings grid).
• slots — hand-placed buttons, positioned by 1-based row/column placed directly on the slot (row 1 = top).
• item — an inline spec: material name:"..." with flags like hide_attributes. Vanilla, an ecoitem: id, or a player head.
• left-click / right-click — lists of effects; each effect is an id: (see below) with optional args:.

Two extensions over stock EcoMenus

• Named mask regions — one menu can have several dynamic areas (the browser has both category-slots and content-slots), not just one.
• Per-click actions — left-click: and right-click: can do different things. A button with no right-click: behaves the same on both, so nothing changes for buttons that don't care.

Player heads

Custom-textured heads work exactly the way the eco suite does them:

- 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

Use these in any slot's item (no eco dependency needed for the head itself). A custom eco item that is a head (ecoitem:my_head) renders its own texture automatically — just use its id.

List placeholders

A lore line that is exactly %tier_list% (or %type_list%) expands into one line per option, with the current one marked. That's how the filter buttons show their whole list instead of just the current value:

  - id: tier
    item: 'nether_star hide_attributes name:"&eItem Tier"'
    lore:
      - "&7Filter listings by item tier."
      - ""
      - "%tier_list%"             # -> one line per tier, selected one marked
      - ""
      - "&eLeft-click &7to go up"
      - "&eRight-click &7to go down"
    left-click:
      - id: ah_tier_prev
    right-click:
      - id: ah_tier_next          # swap these two to reverse the direction

Effect ids

Wire a button to a behavior with an effect id::

ah_hub  ah_browse  ah_bids  ah_manage  ah_collection  ah_create  ah_search
ah_sort  ah_prev_page  ah_next_page
ah_tier_prev  ah_tier_next  ah_type_prev  ah_type_next
ah_set_price  ah_set_duration  ah_toggle_type  ah_remove_item
ah_bid_min  ah_bid_custom
ah_continue  ah_confirm  ah_confirm_purchase  ah_confirm_bid  ah_confirm_cancel
ah_back  ah_cancel
close_inventory  play_sound

play_sound takes args: (sound, pitch, volume). A button with an unrecognized or missing effect is decorative.

Placeholders

Available in menu titles and lore (per menu — not all apply everywhere):

%category% %count% %page% %pages% %search% %sort% %tier% %type%
%active% %my_listings% %total_bids% %top_bids% %outbid% %player% %balance%
%price% %starting_price% %current_bid% %min_bid% %bid% %bids% %top% %top_bidder%
%seller% %ends_in% %duration% %fee% %bid_label% %click_hint% %toggle_hint%
%type_name% %type_desc% %type_material% %tier_list% %type_list%

Listing lore (Hypixel-style)

browse.yml has a listing-lore block appended below each listing's own item lore, with separate templates for buy-it-now and auction:

listing-lore:
  buy-it-now:
    - ""
    - "&7Seller: &f%seller%"
    - "&6Buy it now: &e%price% coins"
    - ""
    - "&7Ends in: &f%ends_in%"
    - ""
    - "%click_hint%"
  auction:
    - ""
    - "&7Seller: &f%seller%"
    - "&6%bid_label%: &e%price% coins"
    - "&7Top bidder: &f%top_bidder%"
    - "&7Bids: &f%bids%"
    - ""
    - "&7Ends in: &f%ends_in%"
    - ""
    - "%click_hint%"

Placeholders here: %seller% %price% %starting_price% %bids% %top_bidder% %ends_in% %bid_label% %tier% %click_hint%.

⚠️ The one YAML gotcha

An inline item spec containing a colon followed by a space must be quoted, or SnakeYAML reads it as a mapping and the whole file fails to load:

item: 'hopper name:"&eSort: &f%sort%"'    # quoted — correct
item: hopper name:"&eSort: &f%sort%"      # BREAKS the file