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: "%param.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.

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 %layout.items.page% and the total page count via %layout.items.pages%.

Layout Placeholders

Inside items that belong to a layout the following placeholders are available:

Placeholder	Description
`%layout.<id>.page%`	Current page index (0-based)
`%layout.<id>.pages%`	Total number of pages
`%layout.<id>.size%`	Total number of items in the provider
`%layout.<id>.index%`	Index of the current item within the full provider

23 April 2026