Menu Layouts | Astral Realms Documentation

Layouts dynamically fill a set of slots with items from a collection — the primary tool for building paginated lists, inventories, leaderboards, and any other variable-length content.

How Layouts Work

A LayoutBlueprint is defined in the menu's layouts: map.
At compute time a LayoutInstance is created and bound to a data provider.
Items tagged with the layout's taint are distributed across the layout's slots.
Pagination is handled via next-page, previous-page, and first-page actions.

Blueprint Fields

layouts:
  items:                              # layout identifier
    provider: "%parameters_items%"    # placeholder that resolves to the data source
    taint: "shop-item"                # items with this taint tag are rendered here
    view-requirements: []             # optional — hide the layout entirely when these fail

Field	Type	Description
`provider`	String (placeholder)	Resolves to a `Collection<Placeholder>`, `Map<?, ?>`, or `ItemProvider`.
`taint`	String	Only `MenuItem` entries with this taint string are placed inside this layout.
`view-requirements`	`List<Requirement>`	When any fails the layout renders nothing.
`refresh`	object	Optional timer that re-runs the provider and redistributes items (see Auto-refresh).

Data Providers

The provider placeholder must resolve to one of:

Type	Description
`Collection<Placeholder>`	Each element is rendered as one layout slot. The element's placeholder context is active while rendering that slot's item.
`Map<?, ?>`	Each key-value pair is exposed as a placeholder context per slot.
`ItemProvider`	Custom Java interface for programmatic item generation.

Providers are typically passed as parameters when opening the menu:

menus.computeAndOpen(player, "shop", Map.of("items", myItemCollection));

Slot Assignment

Layout slots are defined by associating items with the layout's taint. The slots those items occupy become the layout's available slots. Items are distributed in slot-index order.

items:
  shop-row-1:
    slots: [10, 11, 12, 13, 14, 15, 16]
    taints:
      - "shop-item"
    item-stack:
      material: "STONE"   # placeholder/template item — overridden by layout data

Pagination

When the provider has more items than available slots, the layout is automatically paginated.

items:
  next-page-btn:
    slot: 53
    item-stack:
      material: "ARROW"
      name: "<green>Next page"
    actions:
      LEFT:
        - "[next-page] items"

  prev-page-btn:
    slot: 45
    item-stack:
      material: "ARROW"
      name: "<red>Previous page"
    actions:
      LEFT:
        - "[previous-page] items"

The current page number is accessible via %layouts_items_page% and the total page count via %layouts_items_maxPages%.

Auto-refresh

A layout can re-run its provider and redistribute items on a repeating timer via a refresh: block — the layout-level analogue of item auto-refresh. Useful for live lists (online players, leaderboards, market listings) that change without a click.

layouts:
  items:
    provider: "%parameters_items%"
    taint: "shop-item"
    refresh:
      delay: 2.0            # seconds — required to activate
      requirements: []      # optional
      actions: []           # optional

Field	Type	Description
`delay`	double (seconds)	Interval between refreshes, in seconds. Accepts a placeholder / `$e(...)`. Inactive if absent or `<= 0`.
`requirements`	`List<Requirement>`	Optional. Evaluated every tick; if any fails, that tick is skipped (the timer keeps running).
`actions`	`List<Action>`	Optional. Run every tick that requirements pass, immediately before the layout is re-rendered.

Each tick re-resolves the provider and redistributes items across the layout's slots — the timer-driven equivalent of a refresh-layout action.

Layout Placeholders

%layouts_<id>% resolves to the live layout instance, and any remaining tokens drill into it.

Placeholder	Description
`%layouts_<id>_id%`	Layout identifier
`%layouts_<id>_page%`	Current page index (0-based)
`%layouts_<id>_maxPages%`	Total number of pages
`%layouts_<id>_hasNextPage%`	`true` when a next page exists
`%layouts_<id>_hasPreviousPage%`	`true` when a previous page exists

These keys are commonly combined with view-requirements to hide navigation buttons when no further pages exist, e.g. [compare] %layouts_items_hasNextPage% == true.

Last modified: 25 July 2026