menus

Every menu is a file in guis/. You can retheme them freely: change titles, sizes, backgrounds, buttons and the listing grid. After editing, run /ahadmin reload. A file you delete is written back with its defaults on the next start.

File	Opened by
main-menu.yml	/ah, [auctions]
listings-menu.yml	[listings] (your own active listings)
expired-menu.yml	/ah expired, [expired]
category-menu.yml	The Category button, [categories]
purchase-menu.yml	Clicking someone else’s listing. See purchase-menu.yml.
history-menu.yml	/ahadmin history [player]
removal-menu.yml	/ahadmin remove <player>, /ahadmin open <player>

How a file works

Title: "Auction House"
Size: 54
Listing-Slots: [10-16, 19-25, 28-34, 37-43]

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

  Expired-Item:
    Material: ENDER_CHEST
    Slot: 5
    Name: "&c&lExpired Auctions"
    Lore:
      - "&7Collect every listing of yours"
      - "&7that has run out of time."
      - ""
      - "&cInformation:"
      - "&4 - &7Waiting: &f{my-expired}"
      - ""
      - "&e➥ Click to view!"
    Actions:
      - "[expired]"

Temporary-Icons:
  No-Previous-Page:
    Material: BARRIER
    Name: "&c&lError!"
    Lore:
      - "&7You are already on the first page!"

Key	Description
Title	The inventory title. Tokens and %...% are filled in once, when the menu opens, so put page numbers on an item, not here.
Size	A multiple of 9, from 9 to 54.
Listing-Slots	Paged menus only: the slots listings are drawn in, in order. Numbers or a-b ranges. Required, and every slot must fit in Size. The number of slots is the page size.
Items	Fillers and buttons. Every key is an item id.
Temporary-Icons	Icons flashed in a slot for a moment when a click is refused. See Temporary icons.

Each item uses Slot: (one number) or Slots: (a list of numbers and a-b ranges). Items are painted broadest first, so a filler covering the whole menu never hides a single-slot button, and listings are drawn on top of everything in Listing-Slots.

Item fields

Field	Description
Material	Any material name. Legacy and modern names both work.
Base64	Head texture for PLAYER_HEAD. "{player}" shows the viewer’s own head.
Amount	Stack size shown.
Name, Lore	Display name and lore. Tokens and %...% work.
Glow	true adds an enchant glint.
Custom-Model-Data, Item-Model	Resource pack models.
Item-Flags	A list of Bukkit item flags, e.g. [HIDE_ATTRIBUTES, HIDE_ADDITIONAL_TOOLTIP].
Actions	What a click does, see below.

Italics are removed from names and lore automatically.

Actions

Most buttons work through their Actions list. Actions run in order.

Action	Does
[auctions]	Open the main board.
[listings]	Open your own active listings.
[expired]	Open your expired listings.
[categories]	Open the category menu.
[search]	Ask the player for search text (chat or anvil), then show the board filtered by it.
[collect]	Collect every expired listing, like /ah collect.
[previous], [next]	Turn the page. On the first or last page they play NO-PAGE-FOUND and flash No-Previous-Page / No-Next-Page.
[back]	Go back to the menu this one was opened from.
[close]	Close the menu.
[player] <command> / [command] <command>	Run a command as the player.
[console] <command>	Run a command from console.
[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 screen title. Times are in ticks and optional.
[sound] <NAME;volume;pitch>	Play a sound.

{player}, the menu’s tokens and (with PlaceholderAPI) %...% are filled in the argument. An item with Actions: [] is a display item: clicking it does nothing. An unknown action type throws an error when clicked.

Buttons that work by id

A few buttons are recognized by their item id rather than an action, so keep these ids:

Item id	Menu	Does
Sort-Item	main	Left-click: next sort order. Right-click: previous.
Category-Item	main	Opens the category menu. Shift-click clears the category and search. With categories disabled, any click clears them.
Collect-All-Item	expired	Collects every expired listing.

Any item in category-menu.yml with a Category: key selects that category.

Main menu

main-menu.yml is the board. On top of the standard keys it holds the sort and search labels:

Sort-Selected: "&4 - &f{sort} &c&l<"
Sort-Entry: "&4 - &7{sort}"
Sort-Names:
  Recent: "Recent"
  Lowest-Price: "Lowest Price"
  Highest-Price: "Highest Price"
  Oldest: "Oldest"
No-Search: "None"

Key	Description
Sort-Selected	The {sorts} line for the active order. {sort} is its name.
Sort-Entry	The {sorts} line for every other order.
Sort-Names	What {sort} shows for each order. All four are required.
No-Search	What {search} shows when no search is active.

The Sort-Item lore line "{sorts}" expands into four lines, one per order, in the order Recent, Lowest Price, Highest Price, Oldest.

Shipped buttons: Listings-Item (your head, slot 3, [listings]), Expired-Item (5, [expired]), Category-Item (46), Previous-Item (48), Page-Indicator (49), Next-Item (50) and Sort-Item (52). The search button ships in the category menu; add an item with [search] here if you want one on the board too.

Clicking someone else’s listing opens the purchase menu. Clicking your own listing cancels it (left-click) or bumps it (right-click).

Token	Value
{listings}	Active listings on the whole board.
{results}	Listings matching the current category and search.
{category}	The selected category’s Display-Name, the search text while searching, or All-Items.
{search}	The search text, or No-Search.
{sort}, {sorts}	The current order and the full order list.
{my-listings}, {my-expired}, {limit}	The viewer’s active listings, expired listings and listing cap.
{page}, {pages}	Current page and page count.
{player}	The viewer’s name.

Listings menu

listings-menu.yml (“Your Auctions”) shows the viewer’s active listings with Own-Lore. Left-click cancels, right-click bumps. Tokens: {my-listings}, {my-expired}, {limit}, {page}, {pages}, {results}, {player}.

Expired menu

expired-menu.yml shows the viewer’s expired listings with Expired-Lore. Clicking one collects it; Collect-All-Item (slot 4) collects them all. Tokens: {my-expired}, {page}, {pages}, {results}, {player}.

Category menu

category-menu.yml is a plain (not paged) menu, 36 slots by default. Each category button carries a Category: key naming an id from categories.yml:

  Weapons-Category:
    Material: IRON_SWORD
    Slot: 14
    Name: "&d&lWeapons"
    Item-Flags: [HIDE_ADDITIONAL_TOOLTIP, HIDE_ATTRIBUTES]
    Lore:
      - "&7View every &fweapon &7currently"
      - "&7listed on the auction house."
      - ""
      - "&e➥ Click to select!"
    Category: weapons

Clicking it selects that category (all clears the filter), clears any search and returns to the board. Category buttons need no Actions. The menu also ships Back-Item ([back]), Listings-Item ([listings]), Expired-Item ([expired]) and Search-Item ([search]).

Tokens: {category}, {listings}, {my-listings}, {my-expired}, {player}.

History menu

history-menu.yml lists sales with History-Lore, newest first. It is read-only: clicking a sale does nothing. It also holds:

Key	Default	Description
Everyone-Subject	Everyone	What {subject} shows for /ahadmin history without a player. Required.

Tokens: {subject}, {page}, {pages}, {results}, {player}.

Removal menu

removal-menu.yml lists a player’s active listings with Removal-Lore. Clicking one takes it off the market and moves it to the seller’s expired menu. Tokens: {subject} (the player’s name), {page}, {pages}, {results}, {player}.

Temporary icons

Each file has its own Temporary-Icons. They use the item fields above and the menu’s tokens. Delete one and that refusal simply plays DENIED without a flash.

Icon	Flashed when	Shipped in
No-Previous-Page, No-Next-Page	A page arrow is clicked on the first or last page.	Every paged menu
Inventory-Full	Cancelling or collecting is refused (no room, or the listing is gone).	Main, listings, expired
Bump-Cooldown	A bump is refused (cooldown, unpaid bump cost, listing gone).	Main, listings
Listing-Gone	The listing was already sold, expired or removed.	Removal, purchase

The purchase menu has its own set, see purchase-menu.yml.

Live refresh

Paged menus redraw every Menu-Refresh-Ticks (see config.yml), so {expires}, stock and counters stay current while the menu is open.