Menu System

AstralCore's menu system provides YAML-driven inventory UIs with a rich feature set: dynamic slot assignment, paginated layouts, per-click actions and requirements, template variables, and full placeholder support.

Concepts

Term	Description
Blueprint	The parsed YAML definition. Immutable; shared across all players.
Menu	A per-player runtime instance computed from a blueprint. Holds inventory state.
MenuItem	A single slot configuration inside a blueprint.
Layout	A dynamic list of items filling a set of slots (used for pagination).
Variable	A mutable string stored in a menu instance, usable as a placeholder.

File Layout

Place menu YAML files in:

plugins/AstralCore/AstralMenus/
├── main-menu.yml
├── shop/
│   ├── weapons.yml
│   └── armor.yml
└── profile.yml

Sub-folders are scanned recursively. The file name does not matter — the id field inside the YAML is the identifier used to open the menu.

Lifecycle

load()         ─── YAML → MenuBlueprint (once, async)
                          │
computeAndOpen()          ▼
   async   ──────── Menu.compute()
                     ├── computeVariables()
                     ├── computeInventories()
                     ├── computeLayouts()
                     └── computeItems()
                          │
   sync    ──────── Menu.open()
                     ├── fire MenuOpenEvent (cancellable)
                     ├── open inventories
                     └── execute openActions
                          │
                    Player interacts
                     └── handleClick(slot, clickType)
                          ├── resolve MenuItem
                          ├── check clicksRequirements
                          └── execute actions
                          │
                    Menu.close()
                     ├── fire MenuCloseEvent (cancellable)
                     ├── remove inventories
                     └── execute closeActions

Via command

If the menu blueprint defines an open-command, it is registered as a Bukkit command automatically:

open-command:
  name: "shop"
  aliases:
    - "store"
    - "s"

Players run /shop or /store.

Via action

Use the open-menu action inside another menu or dialog:

actions:
  LEFT:
    - "[open-menu] shop"
    - "[open-menu] profile:tab=stats"   # with parameters

Via API

AstralCore.get().menus().computeAndOpen(player, "shop", Map.of("tab", "stats"));

Incremental Refresh

Menus support partial updates without re-computing the entire inventory:

Method	Description
`refreshSlot(int)`	Re-render a single slot
`refreshItem(MenuItem)`	Re-render all slots occupied by an item
`refreshLayout(LayoutInstance)`	Re-render a layout and redistribute its items
`setVariable(String, String)`	Update a variable and re-render dependent slots

These are typically triggered from set-variable or refresh-* actions.

23 April 2026

Astral Realms Documentation Help