🎚️ Menus

Every menu is a file in menus/. They all share one more file, menus/templates.yml, which holds the shapes they cut their items from.

The shape of a menu file

title: '<dark_gray><b>ᴘᴏʟᴀʀᴏɪᴅ ᴄʜᴀᴛ'
size: 54                       # 9, 18, 27, 36, 45 or 54

default_template: swatch       # what a button falls back to
dynamic:
  slots: [10-16, 19-25, 28-34] # where paged content goes
filler:
  template: filler             # the backdrop

buttons:
  back:
    template: back
    slot: 45

slot: -1 hides a button without deleting it.

Templates

A back arrow, a locked button, a colour swatch — each is written once in templates.yml, and a menu that wants one names it instead of repeating it.

  back:
    template: back    # take the shape
    slot: 45          # and add what only this menu knows

A menu whose buttons mostly share a shape says so once at the top with default_template, and a button that must escape it says template: none.

What wins

The menu always wins over the template, field by field and state by state. A menu that likes the swatch template but wants a different locked material writes only that:

  ocean:
    hex: '#289bd0'
    states:
      locked:
        material: BARRIER

Everything it does not mention — the other states, their lore, their flags — stays as written in the template.

The shapes that ship

Restyle one and every menu using it changes at the same moment. That is the whole point.

{NAME}

A template writes {NAME} where the item's own name goes, so a button names itself once and still reads red while locked and green while on. This is a whole button:

  bold:
    template: toggle
    material: IRON_INGOT
    name: '<b>ʙᴏʟᴅ'
    slot: 47

extends

A template may build on another, which is how the three arrows share one material and one set of flags.

A menu's own templates

A menu may declare a templates: block of its own, laid over the shared ones. Use it to restyle a shared shape for one menu, or to add a shape only that menu needs.

States

The plugin decides which state an item is in and the menu draws that one. The names are read by the code, so renaming one turns it off. A state the plugin never asks for is never drawn.

Items

material takes more than a vanilla name:

Items from MythicMobs, ItemsAdder, Oraxen, HeadDatabase, MMOItems and others resolve the same way — the full list is in For developers.

Beyond material and name, an item takes lore, amount, glow, model, item_flags, color, enchantments, banner_patterns, potion_effects, trim_material / trim_pattern, tooltip_style and hide_tooltip.

hide_tooltip: true shows no tooltip at all, rather than an empty one — a blank name is not the same as no name. Needs 1.20.5 or newer.

Slots

slot: 5
slots: [1, 2, 3, 5]
slots: [1-3, 5]

Counting starts at 0, left to right, top to bottom. In a 54-slot menu the last row is 45–53.

Sounds

One click for the whole plugin, in config.yml under menus.sounds. The shared click is written once under states.defaults and each state moves only what it needs — locked a dull note, selected the ding of picking something up. A sound that is empty or none is silence, which is what a button that does nothing should be.

Two other ways the menu opens

As a dialog. menus.prefer_dialog opens /chat as a dialog window where the server version has them. The wording is in the language file under dialog.

As a Bedrock form. menus.bedrock_forms shows Bedrock players a native form instead. Needs Floodgate; Java players are never affected. Its wording is under form, and menus.form_icons sets each button's icon.

Neither reads menus/, so a menu you restyle there is the Java-inventory one.