Menus

Every menu in AT-AuctionHouse is built from gui.yml. No menu contains a hardcoded material and no menu contains a hardcoded sentence. Move a button, change what it is made of, rewrite its lore, or delete it entirely, and the plugin follows.

This is the file worth spending time in.

How a menu works

A menu has four parts.

Here is the shipped main menu, cut down:

AUCTION:
  TITLE: "&8Auction"

  STRUCTURE:
    - "#########"
    - "#.......#"
    - "#.......#"
    - "#.......#"
    - "#.......#"
    - "c<fsroi>t"

  CHARS:
    CONTENT: "."
    PREVIOUS-PAGE: "<"
    NEXT-PAGE: ">"
    FILLER: "#"
    SORT: "o"
    FILTER: "f"
    SEARCH: "s"
    REFRESH: "r"
    YOUR-LISTINGS: "i"
    COLLECTION: "c"
    TRANSACTIONS: "t"

Row 1 is slots 0 to 8, row 2 is slots 9 to 17, and so on. CONTENT is the paginated area, so the 28 dots above are 28 listings per page. Move a role's character anywhere you like, or delete it to remove that button.

Rules for STRUCTURE

• 1 to 6 rows. A chest window cannot show more than 6, so extra rows are ignored and the plugin logs a warning naming the menu.
• Rows shorter than 9 characters are padded.
• Any character not listed in CHARS becomes filler.
• More CONTENT characters means more entries per page.
• Roles are matched without regard to case, so next-page: works as well as NEXT-PAGE:.

The ITEMS block

ITEMS:
  SORT:
    MATERIAL: COMPARATOR
    NAME: "&9Sort: &f{sort}"
    LORE:
      - "&7Click to change sorting"
    AMOUNT: 1
    GLOW: false
    MODEL-DATA: 0

Two small tricks:

• MATERIAL: AIR leaves the slot genuinely empty. Set it on FILLER for an empty border.
• LORE: [] means no lore at all, as opposed to leaving LORE out, which means the same thing for a template item but leaves an existing item's own lore untouched.

FILLER

FILLER:
  MATERIAL: GRAY_STAINED_GLASS_PANE
  NAME: " "
  LORE: []

Drawn in every FILLER slot, and in every slot whose character is not listed in that menu's CHARS. It is defined once, at the top of the file, and applies to every menu.

Free-form lore blocks

Some things a menu draws are not template items. A listed diamond sword is a real diamond sword with its real enchantments, and the plugin only adds lore underneath it. Those extra lines come from free-form blocks that sit alongside ITEMS.

AUCTION:
  LISTING:
    LORE:
      - "&7Price: &a{price}"
      - "&7Seller: &f{seller}"
      - "&7Time Left: &b{time-left}"
      - ""
      - "&bClick to buy!"
    SHULKER-LORE:
      - "&7Shift + Left Click to view contents"

The item keeps its own name, enchantment lines and attribute lines. Only these lines are added, underneath.

TRANSACTIONS also has two plain strings rather than lists:

TRANSACTIONS:
  ENTRY:
    LORE:
      - "{type}"
      - "&7Price: &a{price}"
    TYPE-BOUGHT: "&aBought"
    TYPE-SOLD: "&9Sold"

{type} resolves to one or the other.

The toggle menus

FILTER and SORT are the odd ones out. Their buttons do not live under ITEMS. They live under CATEGORIES and ORDERS, one sub-block per option, and each carries a second name for when it is the active one.

FILTER:
  STATE:
    SELECTED-LORE:
      - "&a<checkmark> Selected"
    UNSELECTED-LORE:
      - "&7Click to select"
    GLOW-SELECTED: true

  CATEGORIES:
    ALL:
      MATERIAL: CHEST
      NAME: "&bAll Items"
      SELECTED-NAME: "&a&lAll Items"

Each option also accepts MATERIAL, NAME, AMOUNT, GLOW and MODEL-DATA, the same as any other item.

<checkmark> is a token that becomes a real tick mark. It is written as a token because a raw tick in a YAML file is a reliable way to get mojibake the first time somebody opens the file in an editor that is not using UTF-8.

Buttons appear in file order, not in some internal order. Reorder the blocks to reorder the buttons. Delete a block to hide that option entirely.

Valid category keys are ALL, BLOCKS, TOOLS, FOOD, COMBAT, POTIONS, BOOKS, INGREDIENTS and UTILITIES. Valid sort keys are RECENTLY_LISTED, LAST_LISTED, HIGHEST_PRICE and LOWEST_PRICE. A key that names neither is skipped with one warning listing the valid ones.

Placeholders

Anything the plugin knows is exposed as {a-placeholder}. Put it in a name, in a lore line, in both, or leave it out.

Available in every menu

Listing items

Available on AUCTION and YOUR-ITEMS content slots.

Both price formats are configurable. FORMATTING.CURRENCY-SYMBOL and FORMATTING.MAGNITUDE-SUFFIXES in config.yml decide what {price} looks like, and {price-raw} is never touched by either. See Configuration.

The countdown is translatable rather than configured, because nothing ever reads a duration back from a player. Edit the TIME block in your language file to change what {time-left} writes after each number. See Languages.

Menu specific

On the confirm and preview screens

The menus

Applying changes

/ah reload

re-reads gui.yml along with the other two files. Every open menu is closed first, and any item a player had handed to a menu is given back before anything is re-read. That is deliberate: a menu holds an inventory sized from the layout it was opened with, so redrawing it after you added a row would write past the end of it, and a moved button could turn a cancel click into a confirm click.

If gui.yml is missing a menu block entirely, the plugin logs a warning naming it and falls back to a plain single row. Restore the block, or delete gui.yml and restart to regenerate the whole file.