Menu YAML Reference | Astral Realms Documentation

A complete annotated menu blueprint. All fields except id, title, and size are optional.

# ── Identity ────────────────────────────────────────────────────────────────

# Unique identifier used to open this menu programmatically.
id: "my-menu"

# MiniMessage title shown in the inventory window.
title: "<bold>My Menu</bold>"

# Inventory size. Must be a multiple of 9 (9–54). Use 54 for a double chest.
size: 54

# ── Optional command ────────────────────────────────────────────────────────

# Register a Bukkit command that opens this menu.
open-command:
  name: "mymenu"
  aliases:
    - "mm"

# ── Permission ──────────────────────────────────────────────────────────────

# If set, players without this permission cannot open the menu.
permission: "myplugin.menu.open"

# ── Player inventory ────────────────────────────────────────────────────────

# When true the 36 player hotbar/inventory slots (0–35) are also managed.
use-player-inventory: false

# ── Variables ───────────────────────────────────────────────────────────────

# Local mutable state. Values may use arithmetic and ternary expressions.
variables:
  page: "0"
  mode: "shop"

# ── Layouts ─────────────────────────────────────────────────────────────────

# Named dynamic item lists. See menu-layouts.md for details.
layouts:
  items:
    provider: "%param.provider%"   # placeholder that resolves to a Collection or ItemProvider
    taint: "shop-item"             # only items with this taint are placed by this layout
    view-requirements: []

# ── Open / Close actions ─────────────────────────────────────────────────────

open-actions:
  - "[sound] minecraft:block.note_block.pling"

close-actions:
  - "[sound] minecraft:entity.villager.no"

# ── Items ───────────────────────────────────────────────────────────────────

items:
  # A simple background item
  background:
    slot: 0
    priority: 0
    item-stack:
      material: "BLACK_STAINED_GLASS_PANE"
      name: " "

  # An item that appears in multiple fixed slots
  border:
    slots:
      - 9
      - 17
      - 18
      - 26
    item-stack:
      material: "GRAY_STAINED_GLASS_PANE"
      name: " "

  # A dynamic item whose slot comes from a placeholder
  cursor:
    placeholder: "%var.page%"   # resolves to an integer slot at runtime
    item-stack:
      material: "COMPASS"
      name: "<yellow>Page %var.page%"

  # A fully featured item
  profile-button:
    slot: 22
    priority: 10
    taints:
      - "nav"
    can-be-picked-up: false
    item-stack:
      material: "PLAYER_HEAD"
      name: "<gold>%player.name%"
      lore:
        - "<gray>Click to view your profile."
        - "<gray>Health: <red>%player.health%"
    view-requirements:
      - "[permission] myplugin.profile"
    clicks-requirements:
      LEFT:
        - type: compare
          value: "%var.mode% == shop"
          deny-actions:
            - "[message] <red>You are not in shop mode."
    actions:
      LEFT:
        - "[open-menu] profile:tab=stats"
      RIGHT:
        - "[message] <gray>Right clicked!"
      UNKNOWN:
        - "[sound] minecraft:ui.button.click"

Top-level Fields

Field	Type	Required	Description
`id`	String	Yes	Unique identifier for this menu.
`title`	String (MiniMessage)	Yes	Inventory window title. Supports placeholders.
`size`	int	Yes	Number of slots (multiple of 9, max 54).
`open-command`	Object	No	Register a command that opens this menu.
`permission`	String	No	Permission node required to open the menu.
`use-player-inventory`	boolean	No	Whether to include the player's 36 inventory slots. Default `false`.
`variables`	`Map<String, String>`	No	Initial local variables (key → expression).
`layouts`	`Map<String, LayoutBlueprint>`	No	Named dynamic item lists.
`open-actions`	`List<Action>`	No	Actions executed when the menu opens.
`close-actions`	`List<Action>`	No	Actions executed when the menu closes.
`items`	`Map<String, MenuItem>`	No	Named item definitions.

open-command

Field	Type	Description
`name`	String	Primary command name (without `/`).
`aliases`	`List<String>`	Alternative command names.

23 April 2026