Menu Items | Astral Realms Documentation

Each entry under items: in a menu YAML defines a MenuItem — a slot configuration that controls what appears where and what happens when a player interacts with it.

Field Reference

Field	Type	Required	Description
`slot`	int	No*	Single fixed slot index (0-based).
`slots`	List	No*	Multiple fixed slot indices or placeholder strings.
`placeholder`	String	No*	A placeholder expression resolving to an integer slot at runtime.
`priority`	int	No	Render priority when multiple items target the same slot. Higher wins. Default `0`.
`item-stack`	WrappedItemStack	No	Item appearance definition.
`taints`	`List<String>`	No	Tags used by layouts to filter which items they render.
`can-be-picked-up`	boolean	No	Allow the player to move this item with their cursor. Default `false`.
`view-requirements`	`List<Requirement>`	No	All must pass for the item to be visible.
`clicks-requirements`	`Map<ClickType, List<Requirement>>`	No	Requirements per click type before actions fire.
`actions`	`Map<ClickType, List<Action>>`	No	Actions to execute on click, keyed by click type.

*At least one of slot, slots, or placeholder should be provided.

Slot Types

Single slot

profile-button:
  slot: 22

Multiple fixed slots

border:
  slots:
    - 0
    - 8
    - 45
    - 53

Slots can also be quoted strings — useful when the value comes from a YAML anchor:

  slots:
    - "0"
    - "8"

Placeholder slot

The placeholder is resolved at compute-time via PlaceholderAPI or internal processors and must evaluate to an integer:

cursor:
  placeholder: "%var.selected_slot%"

item-stack

Field	Type	Description
`material`	String	Bukkit Material name (e.g. `DIAMOND_SWORD`).
`name`	String (MiniMessage)	Item display name. Supports all menu placeholders.
`lore`	`List<String>`	Each entry is a MiniMessage lore line.
`append-lore`	boolean	When `true` the lore is appended to the base item's existing lore instead of replacing it. Default `false`.
`copy-from`	String	Placeholder resolving to another item to copy as the base (e.g. `%param.item%`).

Custom item providers

Prefix the material value with a namespace to use a registered ItemStackSupplier:

item-stack:
  material: "itemsadder-ia_sword"   # namespace "itemsadder", key "ia_sword"

Built-in namespaces:

Namespace	Provider	Example
(none)	Vanilla Minecraft material	`DIAMOND_SWORD`
`itemsadder`	ItemsAdder	`itemsadder-ia_custom_sword`
`headdb`	HeadDatabase	`headdb-12345`
`craftengine`	CraftEngine	`craftengine-my_item`

Click Types

Standard Bukkit ClickType values used as keys in actions and clicks-requirements:

Key	Description
`LEFT`	Left mouse button
`RIGHT`	Right mouse button
`SHIFT_LEFT`	Shift + left click
`SHIFT_RIGHT`	Shift + right click
`MIDDLE`	Middle mouse button
`DROP`	Drop key (Q)
`CONTROL_DROP`	Ctrl + drop
`DOUBLE_CLICK`	Double left click
`UNKNOWN`	Fallback — matches any click type not explicitly listed

The UNKNOWN key acts as a wildcard fallback. If a player clicks with a type that has no dedicated entry, the UNKNOWN entry is used instead.

Priority

When two items target the same slot, the one with the higher priority value wins. View requirements are evaluated before priority comparison — an item that fails its view-requirements is treated as absent.

default-item:
  slot: 4
  priority: 0
  item-stack:
    material: GRAY_STAINED_GLASS_PANE

active-item:
  slot: 4
  priority: 10
  view-requirements:
    - "[permission] myplugin.vip"
  item-stack:
    material: DIAMOND

Taints

Taints are string tags that link items to layouts. A layout with taint: "shop-item" will only populate its slots with items that have "shop-item" in their taints list.

shop-item:
  taints:
    - "shop-item"
  item-stack:
    material: STONE

23 April 2026