Menus

Every HireHall menu is a yml file in plugins/HireHall/menus. You can move any button, change every name, lore line, icon and sound, add your own buttons with actions, and even add whole new menus.

The bundled menus come in English, French and Spanish, picked by menu-language when the files are first made. /hirehall admin resetmenus backs up your menus and makes a fresh set, see Menu language.

Changes apply after /hirehall admin reload. Mistakes (a slot outside the menu, an unknown action, a missing template) are logged once in the console with the file and the key, and the rest of the menu still works.

The file

menu-version: 1
title: "<#e8a021>Job Board <white>(%page%/%pages%)"
rows: 6
open-sound: "BLOCK_NOTE_BLOCK_HARP"
click-sound: "UI_BUTTON_CLICK"

fillers:
  border:
    material: GRAY_STAINED_GLASS_PANE
    name: " "
    slots: [0-8, 45-53]
    priority: 1

items:
  close:
    slot: 49
    material: BARRIER
    name: "<#e8a021>Close"
    actions:
      left: "[close]"

templates:
  job:
    material: "%icon%"
    name: "<#e8a021>%type% <white>#%id%"

pagination:
  content-slots: [10-16, 19-25, 28-34, 37-43]
  previous:
    slot: 45
    material: ARROW
    name: "<#e8a021>Previous Page"
  next:
    slot: 53
    material: ARROW
    name: "<#e8a021>Next Page"

Sounds are sound names like UI_BUTTON_CLICK or full keys like minecraft:ui.button.click, so resource pack sounds work too.

Slots

Slots count from 0 in the top left corner, left to right, top to bottom. A 6 row menu has slots 0 to 53.

All of these are valid:

slot: 13
slots: [10, 11, 12]
slots: [0-8, 45-53]
slots: "10-16, 19-25"

Buttons accept slot or slots, fillers and content-slots use slots. A slot outside the menu is skipped with a warning.

Fillers

Fillers are background items. They cannot be clicked and never do anything.

A menu is drawn in this order, each step covering the one before:

1. fillers with slots, lowest priority first, so a higher priority wins where they overlap
2. items
3. entries of slotted templates
4. list entries in pagination.content-slots
5. the previous and next page buttons
6. fillers with fill-empty: true, which only fill what is still empty (the lowest priority one gets there first)

Input slots are never filled.

Items

Items are the fixed buttons.

Built in buttons

Some item keys have a job in HireHall itself, for example take in job-details.yml takes the job. For these:

• Move them, restyle them, add actions to them: all fine. Your actions run first, then the built in behaviour.
• Do not rename the key, or the button loses its behaviour.
• HireHall decides when they show. take only shows on an open job for other players, hand-in only when a task job is ready, community and contribute only on community jobs, and so on.

The custom buttons on the amount and currency menus open the typed number input. pricing switches between a price per unit and one total price, and is hidden for community jobs. The total item on the currency menu is a plain item that shows %total%.

An item keyed empty is special in menus with a list: it only shows when the list has no entries.

Templates

A template is the layout for one entry of a list, like one job on the board. It takes the same keys as an item, and has placeholders for that entry (%id%, %pay%, %employer% and so on, see the menu reference).

There are two kinds:

• Paged templates fill pagination.content-slots, one entry per slot, over as many pages as needed. Their own slots key is not used.
• Slotted templates fill their own slots list, in order, one entry per slot. The posting menus use these for the plus and minus steps and the deadline choices. If there are more entries than slots, the extra ones do not show.

templates:
  increase:
    slots: [14, 15, 16]
    material: LIME_STAINED_GLASS_PANE
    name: "<#8ce99a>+%step%"

Here posting.quantity-steps: [1, 10, 100] gives three entries, placed in slots 14, 15 and 16. Add a fourth step and a fourth slot together.

Template names are fixed per menu. A missing template is logged and its entries do not show.

Pagination

The page buttons only show when there is a page to go to. %page% and %pages% work in the title and every item. Actions on the page buttons run before the page turns.

Input slots

input-slots: [10-16, 19-25, 28-34]

Input slots are real empty slots players can put items into. They are used by post-job-items.yml (items to pay with) and deliver.yml (items to hand in).

• Shift clicking an item in the player's inventory moves it into the input slots.
• Double click collecting and dragging into other slots are blocked.
• Leaving the menu takes the items out and gives them back (or keeps them for the next posting step). Nothing is dropped.

Actions

actions:
  left: "[menu] job-board"
  right:
    - "[message] <white>Opening your profile"
    - "[command] hirehall profile"

Clicks are left, right, shift-left, shift-right and middle. Each takes one action or a list.

Menu placeholders work in every action. In [command] and [console], %hirehall_...% and PlaceholderAPI placeholders work too.

Conditions

There is no general condition system in the menu files. What decides whether a button shows is:

• view-permission together with hide-if-no-permission
• the empty item, for menus with a list
• the built in rules of the built in buttons, which you cannot change

To show something only to some players, give them a permission and use view-permission.

Custom items

material on items, templates and fillers accepts:

A material that cannot be found shows as a barrier named after the bad value, with one warning in the console. ItemsAdder and Nexo items show as barriers while those plugins are still loading their items, reopen the menu once they are done. See ItemsAdder and Nexo.

Text

Names, lore and titles use MiniMessage, for example <#e8a021> or <bold>. Placeholders use %name%:

• %player%, %page% and %pages% in every menu
• the placeholders of that menu, see below
• all %hirehall_...% placeholders, with or without PlaceholderAPI
• any PlaceholderAPI placeholder, when PlaceholderAPI is installed

Menus showing jobs or claims update by themselves while open, for example when a worker makes progress.

Your own menus

Any extra .yml file dropped into menus/ is loaded too. Open it with [menu] <file name> from any button, for example a rules menu opened from main.yml. Your own menus support fillers, items, view-permission, actions, custom items and placeholders. Built in buttons, templates, pagination and input slots do nothing there, since HireHall has no list or items to give them.

Menu reference

Placeholders by menu