Placeholders

AstralHeads registers three placeholder namespaces. heads is globally registered (RootPlaceholderContainer.get().registerPlaceholder(new HeadsPlaceholders(this))) and resolvable anywhere; head and category are ComplexPlaceholders carried by HeadEntity/HeadCategory instances themselves — they only become resolvable once an instance is placed into scope (e.g. a rendered head/category item in a menu, or an action argument like %head_id%). For the placeholder syntax itself (%namespace_key%, chaining, $e(...)) see Placeholders.

`heads_*`

Backed by HeadsPlaceholders, namespace heads.

Placeholder	Type	Description
`%heads_categories%`	list (chain point)	Every configured category (`categories.yml`'s values), wrapped via `ItemProvider`.
`%heads_heads%`	list (chain point)	An arbitrary 10 heads from the in-memory cache (`heads().stream().limit(10).sorted()` — the limit is applied before the sort, so this is not the alphabetically-first 10 overall, only those 10 sorted by name relative to each other).
`%heads_favorites%`	list (chain point)	The viewing player's favorited heads (`HeadPlayerData` via AstralSync). Resolves to `null` if the context isn't a `Player`, or if no `HeadPlayerData` is loaded for them.

Any other sub-key (or none) resolves to null.

lines:
  - "<gray>Categories: %heads_categories%"

`head_*`

HeadEntity itself is a ComplexPlaceholder (namespace head). A bare %head% (no sub-key) resolves to the HeadEntity object itself.

Placeholder	Type	Description
`%head_id%`	`UUID`	The head's `uniqueId`.
`%head_number%`	`Long`	The human-friendly sequential id, or `null` if the row hasn't been persisted yet.
`%head_name%`	String	Catalog display name, or the player's username.
`%head_category%`	String	`CATALOG` only — matches a `categories.yml` id.
`%head_tags%`	`JsonArray`	`CATALOG` only — the head's search tags.
`%head_item%`	`ItemStackPlaceholder`	The rendered `PLAYER_HEAD` `ItemStack` (`HeadEntity#itemStack()`).
`%head_favorite%`	boolean	Whether the viewing player has this head favorited. Resolves to `null` if the context isn't a `Player`, `false` if that player has no `HeadPlayerData` loaded.
`%head_price%`	double	The configured price for this head's `Source` (`config.yml`'s `prices` map), or `-1` if unpriced.
`%head_currency%`	`ComponentWrapper` result	The configured `currency-display` for this head's `Source`, or `null` if unpriced.

lore:
  - "<gray>#%head_number% <white>%head_name%"
  - "<gray>Price: <gold>%head_price% %head_currency%"
actions:
  LEFT:
    - "[buy-head] %head_id%"
  RIGHT:
    - "[toggle-favorite] %head_id%"

`category_*`

HeadCategory itself is a ComplexPlaceholder (namespace category). A bare %category% (no sub-key) resolves to the HeadCategory object itself.

Placeholder	Type	Description
`%category_id%`	String	The category's id (`categories.yml` key).
`%category_item%`	`ItemStackPlaceholder`	The category's configured icon (`categories.yml`'s `item`).
`%category_heads%`	list (chain point)	Every head whose `category` matches this id, via `HeadService#findByCategory`, wrapped in `ItemProvider`.

lines:
  - "<gray>Browsing: <white>%category_id%"

Any other sub-key (or none, for any of the three namespaces) resolves to null.

Last modified: 25 July 2026