Placeholders

AstralCollections registers two placeholder namespaces with AstralCore. They are available in messages, menus, completion actions, and anywhere else AstralCore resolves placeholders.

For the underlying placeholder syntax (%a_b_c%, %a_{b_c}%, $e(...)), see Placeholders.

`collection_*`

A CollectionBlueprint placeholder. The base form %collection% returns the blueprint itself; the keys below drill into it.

Placeholder	Type	Description
`%collection_id%`	String	Blueprint identifier.
`%collection_display%`	ItemStack	Display item — chain further keys like `_name`, `_lore`, `_material`.
`%collection_entries%`	ItemProvider	Every entry, suitable as a layout `provider`.
`%collection_progress%`	Integer	Number of entries the viewer has discovered (0 if no viewer context).
`%collection_total%`	Integer	Total number of entries in the blueprint.
`%collection_progressBar%`	Component	A 20-character progress bar (green/grey) for the viewer.
`%collection_completed%`	Boolean	`true` when the viewer has discovered every entry.

The blueprint is typically reached through a layout that exposes one collection per slot, so the namespace is most often used inside the layout item template:

items:
  collection-item:
    taints: [ "collection" ]
    item-stack:
      copy-from: "%collection_display%"
      lore:
        - "<gray>Progress: %collection_progress% / %collection_total%"
        - "%collection_progressBar%"
    actions:
      LEFT:
        - "[open-menu] collection-detail:id=%collection_id%"

`entry_*`

A CollectionEntry placeholder.

Placeholder	Type	Description
`%entry_id%`	String	Entry identifier.
`%entry_collectionId%`	String	ID of the parent collection.
`%entry_collection%`	CollectionBlueprint	The parent blueprint — chain `%entry_collection_display_name%`, etc.
`%entry_item%`	ItemStack	The item to discover.
`%entry_completed%`	Boolean	`true` when the viewer has discovered this entry.

The default entry-discovered message demonstrates a typical chain:

entry-discovered: "<success>You discovered <secondary_color>%entry_item_name% \
  <success>in <secondary_color>%entry_collection_display_name% \
  <success>(<secondary_color>%entry_collection_progress%<success>/\
  <secondary_color>%entry_collection_total%<success>)!"

Each chain resolves left-to-right: %entry_collection_progress% walks entry → collection (the parent blueprint) → progress (current viewer's count).

Context requirements

The placeholders that read player state — collection_progress, collection_progressBar, collection_completed, entry_completed — need a player in the placeholder context. They return 0 or false when no player is available (e.g. when used in console-side computation).

The menu and message pipelines always pass the viewing player as context, so this only matters if you resolve placeholders manually from Java without a player.

Last modified: 25 July 2026