Lore Pages

A blueprint can declare extra lore pages that the holder cycles through in-place, without opening a menu. Useful for items whose full description (stats, ability list, upgrade path) does not fit in one tooltip.

Authoring

Add a top-level lore-pages: map to the blueprint. Each entry is one extra page — a list of MiniMessage lines, exactly like display.lore:

display:
  material: DIAMOND_PICKAXE
  name: "<aqua>Marteau des Abîmes"
  lore:
    - "<gray>Breaks blocks in a 3×3 area."
    - ""
    - "<dark_gray>Page %instance_lore-pages_current%/%instance_lore-pages_total% — <gray>press <white>F"

lore-pages:
  0:
    - "%enchantments%"
    - ""
    - "<dark_gray>Page %instance_lore-pages_current%/%instance_lore-pages_total%"
  1:
    - "<gray>Level: <white>%instance_data_scalable_level%"
    - "<gray>XP: <white>%instance_data_scalable_experience%"
    - ""
    - "<dark_gray>Page %instance_lore-pages_current%/%instance_lore-pages_total%"

Field	Type	Default	Description
`lore-pages`	`Map<int, List<String>>`	`{}`	Extra lore pages, keyed by a 0-based index. Empty (or absent) disables the whole feature for that blueprint.

Keys must be contiguous from 0. The renderer looks page n up as lore-pages[n - 1], so a sparse map (0 and 2, say) leaves a hole: landing on the missing page renders nothing new and the tooltip keeps whatever lore the stack physically carries.

Pages are resolved through the same path as the main lore, so the display's lore-modifiers apply to every page, and any placeholder available to display.lore works inside a page.

Cycling

LorePageListener handles the swap-offhand click (F by default) on a stack inside any inventory:

The click must be SWAP_OFFHAND, and the inventory must not be an AstralCore menu — menus keep their own click semantics.
The clicked stack must be a custom item whose blueprint declares at least one lore page.
The click is cancelled (nothing is swapped to the offhand), the page index advances as (index + 1) % (pages + 1) — wrapping back to the main lore after the last page — and the item is rewritten through ItemService.updateItemStack.

The listener runs at LOWEST priority, so a plugin listening later can still veto or repurpose the click.

Rendering

The current page is not baked into the stack. ItemService always writes display.lore onto the item; LorePagePacketListener then rewrites the LORE component on outgoing SET_SLOT packets, per viewer, at MONITOR priority.

That has a few practical consequences:

The page a player sees is per-viewer and purely visual. Anything reading the item server-side — hoppers, other plugins, ItemStack#isSimilar comparisons — sees page 0's lore regardless of the page on screen.
Rewriting is skipped entirely while the player has an AstralCore menu open, so menu items render their own lore untouched.
Only SET_SLOT is rewritten — bulk window-content packets are not. The page on screen therefore updates whenever the server re-sends that individual slot.

Persistence

The page index is stored on the item in the instance PDC under astralitems:lore_page_index (PersistentDataType.INTEGER), written only when it is greater than 0 — so an item sitting on its main lore carries no extra data. See Developer API › ItemStack PDC layout.

Placeholders

Placeholder	Resolves to
`%instance_lore-pages%`	The blueprint's raw page map (rarely useful as a leaf).
`%instance_lore-pages_current%`	The page the item is on, 1-based — `1` while on `display.lore`.
`%instance_lore-pages_total%`	Total page count, i.e. `lore-pages` size + 1 for the main lore.

Both counters are meant for a footer line repeated on every page:

- "<dark_gray>Page %instance_lore-pages_current%/%instance_lore-pages_total%"

Astral Realms Documentation Help