Placeholders

AstralItems registers a root items placeholder for global lookups and exposes per-context placeholders through PipelineContext, ItemInstance, and the item data adapters. Every placeholder participates in the standard AstralCore placeholder system — %name%, %outer_{inner}%, $e(...).

Global

These resolve through RootPlaceholderContainer — usable anywhere AstralCore evaluates a placeholder (menus, dialogs, action arguments, lore templates).

Placeholder	Returns	Notes
`%items_rarities%`	Iterable of every loaded `ItemRarity`	Wrapped in an `ItemProvider` — pass through to a layout `provider:` to list rarities in a menu.
`%items_blueprints%`	Iterable of every loaded `ItemBlueprint`	Wrapped in an `ItemProvider`.

Example — populate a menu layout with every rarity:

layouts:
  rarities:
    provider: "%items_rarities%"
    taint: "rarity"

Rarity

A rarity is itself a ComplexPlaceholder (namespace rarity). It is most often reached through a menu parameter or via the iterable above.

Placeholder	Returns
`%rarity_id%`	The rarity id.
`%rarity_display%`	The display `ItemStack`.
`%rarity_blueprints%`	Iterable of every blueprint registered under this rarity.

Blueprint

A blueprint is a ComplexPlaceholder (namespace blueprint).

Placeholder	Returns
`%blueprint_id%`	The blueprint's composite `Key` (`<rarity-id>:<id>`).
`%blueprint_item%`	The blueprint's display `ItemStack`, resolved against the current placeholder context.
`%blueprint_version%`	The blueprint's version as `"major.minor.patch"`.
`%blueprint_metadata%`	The `ItemMetadata` record (rarely useful as a leaf).
`%blueprint_rarity%`	The blueprint's `ItemRarity`.
`%blueprint_stats%`	Iterable of the blueprint's stat templates, wrapped in an `ItemProvider`. Iterate to read `%stat_key%`/`%stat_min%`/`%stat_max%`.

Item instance

Inside a pipeline run, instance_* resolves the ItemInstance of the triggering custom item.

Placeholder	Returns
`%instance_id%`	The per-item `UUID`.
`%instance_blueprint%`	The blueprint (chain into `blueprint_*` fields).
`%instance_version%`	The version captured when the item was created.
`%instance_data%`	The typed item-data bag (chain into per-key namespaces).
`%instance_stats%`	Iterable of the item's rolled stats.
`%instance_stat_<key>%`	The rolled stat for `<key>` (e.g. `%instance_stat_astralstats:attack_damage%`), or empty.

The data bag is reached as %instance_data_<key>_<subkey>% — the <key> is whichever string the data class returns from ComplexPlaceholder.namespace(). Built-in keys:

Chain	Resolves to
`%instance_data_scalable_level%`	Current level on a `scalable` item.
`%instance_data_scalable_experience%`	Accumulated XP on a `scalable` item.
`%instance_data_stored-material%`	Stored `Material` (or `AIR`).
`%instance_data_stored-material_name%`	Translatable display name of the stored material — or the `none` message when unset.
`%instance_data_stored-material_sprite%`	Inline sprite component for the stored material.

Pipeline context

PipelineContext itself is a Function<String, Object> — any placeholder accepted by the underlying container resolves against it. The container is pre-populated with:

player_* (AstralCore + PAPI fallback) for the triggering player.
item_* for context.itemStack() via ItemStackPlaceholder.
instance_* for context.instance().
location_* for context.location() if any was captured.
extra-context_* for adapter-supplied extras.

That means component config can reference any of these in placeholder fields:

links:
  durability:
    type: take-durability
    amount: "%instance_data_scalable_level% / 5"

Extra context

Every entry added to PipelineContext.extraContext() that implements ComplexPlaceholder is reachable through the extra-context_<namespace>_… chain. This is how heads expose event-specific data without polluting the main context.

Extra	Namespace	Placeholders
`DragAndDropContext`	`drag-and-drop`	`%extra-context_drag-and-drop_cursor_material%`, `%extra-context_drag-and-drop_cursor%` (full `ItemStack` placeholder), `%extra-context_drag-and-drop_instance_*%` (cursor's `ItemInstance` if any).

Example — read the cursor material into a set-stored-material link:

head:
  type: drag-and-drop
links:
  store:
    type: set-stored-material
    material: "%extra-context_drag-and-drop_cursor_material%"

Lore-template placeholders

ItemService.updateLore exposes three extra placeholders that are only meaningful inside a blueprint's display.lore template:

Placeholder	Returns
`%enchantments%`	A list of `<enchant> <current>/<max>` lines, one per enchantment defined in `metadata.available-enchantments`.
`%unbreakableStatus%`	A single-line list containing the `unbreakable` message — empty when the item isn't unbreakable.
`%repairableStatus%`	The `not-repairable` or `repairable` message — surfaced when the blueprint declares `repairable: false`, or when the item is at max damage.

Use them inline:

display:
  lore:
    - "%enchantments%"
    - ""
    - "<gray>Breaks blocks in a 3×3 area."
    - ""
    - "%unbreakableStatus%"
    - "%repairableStatus%"

Last modified: 25 July 2026