Astral Realms Documentation Help

Placeholders

AstralScrolls registers two ComplexPlaceholder namespaces with AstralCore — scroll on Scroll and rarity on RarityBlueprint. For the general %namespace_key_subkey% syntax, inner placeholders, and expressions, see Placeholders.

Both namespaces are contextual, not global — neither is registered against RootPlaceholderContainer, so %scroll_*% and %rarity_*% only resolve inside the specific container AstralScrolls hands them to. Outside those places the placeholders simply won't resolve.

scroll_*

Scroll implements ComplexPlaceholder with namespace() returning "scroll". It's registered directly (registerPlaceholder(scroll)) into two containers:

  • Item display. MainConfiguration.ItemInfo#apply builds a fresh container carrying only the scroll and renders scroll-item/completed-item's name/lore against it — see Configuration.

  • Completion actions. ScrollService#update registers the completing scroll on top of the player's normal placeholder container (so %player_*% is also available) before running completion-actions — see Configuration.

Sub-key (context.next())

Placeholder

Returns

current

%scroll_current%

The scroll's current progress value (int).

total

%scroll_total%

The scroll's target value (int), rolled once at build time between the blueprint's min/max for its rarity.

context

%scroll_context%

The goal's context() component — a comma-joined, translatable list of the goal's targets (materials/entities). null for enchant, empty for travel.

type

%scroll_type%

The goal's name() component — the localized goal-type label from messages.yml (see Messages).

rarity

%scroll_rarity_*%

The scroll's RarityBlueprint, chainable into any rarity_* sub-key below.

Any other sub-key falls to the default branch and returns null.

lore: - "%scroll_rarity_subColor%%scroll_current%/%scroll_total% %scroll_type% - %scroll_context%"

rarity_*

RarityBlueprint implements ComplexPlaceholder with namespace() returning "rarity". It's registered directly into two containers:

  • Chained off a scroll, as %scroll_rarity_*% (see scroll above).

  • Top-level, as %rarity_*%, in /scrolls give's message container (alongside %target_*% and %amount%) — see Commands. /scrolls rewards and scroll redemption run reward-group actions against a plain player-only placeholder container (PaperActionList#run(Player)), so %rarity_*% is not available there.

Sub-key (context.next())

Placeholder

Returns

id

%rarity_id%

The rarity's id (String), the same key used under config.yml's rarities map.

displayName

%rarity_displayName%

The rarity's display-name (Component).

color

%rarity_color%

The rarity's color (TextColor).

subColor

%rarity_subColor%

The rarity's sub-color (TextColor).

item

%rarity_item%

The rarity's base ItemStackWrapper, resolved into an ItemStack and wrapped as an ItemStackPlaceholder — chainable like any runtime item placeholder (_name, _material, _lore, _amount, …; see Equipment sub-keys).

Any other sub-key returns null — rewards is not exposed as a placeholder sub-key.

gave: "<success>You gave %rarity_color%<bold>%rarity_displayName% <gray>(x%amount%) </bold>to <#26d971>%target_name%!"

%target_*% and %amount% in gave/received

/scrolls give's message container also registers target directly (a PlayerPlaceholder wrapping the recipient, giving %target_name% and the rest of the standard player sub-keys) and amount as a plain int value. See Messages for where these are used.

Last modified: 25 July 2026
CommandsMessages