Items and icons¶

Any icon can be a vanilla material, a head, or an item from another plugin.

      material: DIAMOND_SWORD
      material: "DIAMOND_SWORD:5"        # with custom model data 5
      material: "head:%player_name%"     # the viewer's own head
      material: "hdb:1234"               # HeadDatabase
      material: "itemsadder:mypack:ruby"

The field is a placeholder field like any other, so an icon can change with the player looking at it.

References¶

Form
`MATERIAL`	Any vanilla material
`MATERIAL:n`	With custom model data `n`
`head:<name>`	A player head by name
`head:%player_name%`	The viewer's head
`head:self`	The same thing, shorter
`texture:<base64>`	A head from a texture value
`hdb:<id>`	HeadDatabase by id
`itemsadder:<ns>:<id>`	ItemsAdder
`oraxen:<id>`	Oraxen
`nexo:<id>`	Nexo
`mmoitems:<TYPE>:<ID>`	MMOItems
`ecoitems:<id>`	EcoItems
`main_hand` / `off_hand`	Whatever the viewer is holding

Every hook is optional and looked up at runtime. A reference to a plugin you do not run draws a placeholder and logs one warning, rather than taking the menu down or filling the console.

Materials that got renamed¶

Mojang renames things. GRASS became SHORT_GRASS, SIGN became OAK_SIGN, GRASS_PATH became DIRT_PATH.

Both spellings resolve. A menu written years ago opens correctly today, and a menu you write today will keep working when the next rename happens.

Animated icons¶

An icon can cycle through frames.

corners:
  material: GREEN_STAINED_GLASS_PANE
  display_name: " "
  slots: "0, 8, 27, 35"
  frame_interval: 6
  frames:
    - GREEN_STAINED_GLASS_PANE
    - LIME_STAINED_GLASS_PANE
    - WHITE_STAINED_GLASS_PANE
    - LIME_STAINED_GLASS_PANE

frame_interval is in ticks and defaults to 4, a fifth of a second. One tick is the floor.

A frame overrides, it does not replace¶

Each frame changes only what it names. Everything else falls through to the icon above it, so the display name, lore, requirements, click actions, priority and slots keep working on every frame. That is the whole point: four frames of a colour cycle are four material names, not four copies of the same icon that can drift apart when you edit one of them.

A frame can be a bare material, or a map when you want to change more than the material:

frames:
  - REDSTONE_BLOCK
  - material: REDSTONE_LAMP
    name: "&e&lCLICK ME"
    glow: true

A frame accepts material, name (or display_name), lore, model_data, glow and rgb. A frame that names none of them is ignored, because it would show the base icon for its slice of the cycle and read as a stutter.

What it costs¶

Animating repaints only the animated slots, on the shortest frame interval on screen. It does not re-run view requirements or re-evaluate placeholders; that is what the menu's own update_interval is for. So a spinning border is cheap even when the menu behind it is expensive.

The two are independent and can both be on. Use update_interval for a balance that has to stay current, and frames for the picture.

Everyone sees the same frame

The current frame comes from the clock, not from a counter kept per player. Two people looking at the same menu are in step, and a menu reopened half way through a cycle picks it up where it already is.

Slots¶

      slot: 13
      slots: [0, 8, 45, 53]
      slots: "0-8, 45-53"

The range form exists because painting a border by hand otherwise means typing twenty-odd numbers, which is where mistakes come from.

Slots are numbered left to right, top to bottom, starting at 0.

Making it look right¶

Field
`display_name`	Colour codes and placeholders
`lore`	The grey lines underneath
`amount`	The number in the corner
`glow`	The enchanted shimmer, no real enchantment
`model_data`	Custom model data from your pack
`unbreakable`
`hide_attributes`	Hides the damage and speed lines
`decoration`	Scenery: players cannot click it at all
`rgb`	`"#ff8f00"` or `"255,143,0"`, for leather armour and potions
`enchantments`	`["SHARPNESS;3"]`
`item_flags`	`[HIDE_ENCHANTS, HIDE_ATTRIBUTES]`

glow uses the proper toggle on 1.20.5 and newer, and falls back to a hidden enchantment below that. Either way you do not have to think about it.

Enchantment and flag names are resolved across versions too, so DURABILITY and UNBREAKING both work, as do HIDE_POTION_EFFECTS and HIDE_ADDITIONAL_TOOLTIP.

Colours¶

Three spellings, all accepted anywhere text is:

&a&lGreen and bold
&#ff8f00Hex
{#ff8f00}Hex, the other way

Hex works on every version this supports.

Keep titles short

Older clients refuse an inventory title longer than 32 characters and drop the player out of the menu. We trim rather than let that happen, so a long title is a shortened title. Colour codes count toward the limit, and each hex code costs fourteen characters.