Placeholders

AstralCrates registers two ComplexPlaceholder namespaces with AstralCore — crate on CrateConfiguration and reward on CrateReward. 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 %crate_*% and %reward_*% only resolve inside the specific container AstralCrates hands them to: crate as a menu parameter (see below), reward via a direct registerPlaceholder call. Outside those places the placeholders simply won't resolve.

`crate_*`

CrateConfiguration implements ComplexPlaceholder with namespace() returning "crate". It's supplied to exactly one container: the crate preview menu, opened by CrateService#openCratePreview when a player left-clicks (or otherwise non-right-clicks) a crate block:

this.plugin.menus().computeAndOpen(player, menu.id(), Map.of("crate", configuration));

Because the configuration is handed in under the key "crate" of the parameters map, it's reached through AstralCore's parameters_* namespace — the full placeholder path inside that preview menu's YAML is %parameters_crate_<key>% (shortened to crate_<key> in the table below). It is not available inside CrateOpenMenu (the reward-spin UI) — that menu resolves item stacks and its title against a plain per-player container with no crate parameter registered.

Sub-key (`context.next()`)	Placeholder	Returns
`id`	`%parameters_crate_id%`	The crate's `id` (`String`).
`key`	`%parameters_crate_key%`	The configured key, built from the `key:` `ItemStackWrapper` into an `ItemStack`. Resolves immediately to the finished item — use it as an `item-stack:` value. It does not chain further into item sub-keys such as `_name`/`_material`; any trailing tokens after `key` are ignored once the wrapper resolves (unlike `%player_equipment_HEAD_name%`, which chains into a live `ItemStackPlaceholder`).
`rewards`	`%parameters_crate_rewards%`	An `ItemProvider` over `rewards().values()`. Chainable like any `ItemProvider`: `_size`, `_max-index`, `_at_<i>`, `_iterator`, `_list` — pass it through to a layout `provider:` to list every reward in the menu.
`menu`	`%parameters_crate_menu%`	The `Menu` record itself — rarely useful as a bare leaf; chain `_title` or `_size` below.
`menu` → `title`	`%parameters_crate_menu_title%`	The preview menu's own `menu.title` (`ComponentWrapper`).
`menu` → `size`	`%parameters_crate_menu_size%`	The preview menu's `menu.size` (`int`).

Any other sub-key falls to the default branch and returns null — locations, hologram, open-actions/win-actions are not exposed as placeholder sub-keys, only id, key, rewards, and menu.

# a preview-menu blueprint referenced by a crate's menu.id
title: "%parameters_crate_menu_title%"
size: "%parameters_crate_menu_size%"
items:
  info:
    slot: 4
    item-stack:
      material: PAPER
      name: "<gold>%parameters_crate_id%"
  reward-list:
    provider: "%parameters_crate_rewards%"
    taint: "reward"

`reward_*`

CrateReward implements ComplexPlaceholder with namespace() returning "reward". Unlike crate_* above, it is registered directly into a container — registerPlaceholder(Placeholder) stores an entry keyed by the placeholder's own namespace(), so no parameters_ prefix is needed. CrateListener does this once, right after CrateOpenMenu picks a winner, so the crate's win-actions can reference the reward the player just won:

winActions.run(new DefaultPaperActionContext(player, List.of(), AstralPaperAPI.createPlaceholderContainer(player)
        .registerPlaceholder(crateReward)));

%reward_*% therefore only resolves inside win-actions. It is not available to open-actions (which run once per key, independent of which reward was drawn) or to the reward's own actions list (run with a plain per-player container, before win-actions), nor inside CrateOpenMenu's spin animation itself.

Sub-key (`context.next()`)	Placeholder	Returns
`item`	`%reward_item%`	The reward's `itemStack` field, built into an `ItemStack`. Resolves immediately, same non-chaining behavior as `%crate_key%` above — it does not drill into `_name`/`_material`.
`chance`	`%reward_chance%`	The reward's relative weight (`double`), as set under its `chance:` key.

Any other sub-key returns null — actions and requirements are not exposed as placeholder sub-keys.

win-actions:
  - "[broadcast] <gold>%player_name% <gray>won %reward_item%<gray> (weight: %reward_chance%)!"

`%item_name%` in `key-needed`

When a player right-clicks a crate block without holding a valid key, CrateListener#onInteract sends the key-needed message against a container built just for that call:

CratesMessages.KEY_NEEDED.message(player, AstralPaperAPI.createPlaceholderContainer(player)
        .registerPlaceholder(new ItemStackPlaceholder(crate.key().get())));

new ItemStackPlaceholder(itemStack) (the one-argument constructor) registers under the default namespace "item", wrapping the crate's already-built key ItemStack — this is AstralCore's generic runtime item placeholder (distinct from the config-time ItemStackWrapper behind %crate_key%/%reward_item%, and it does support full sub-key chaining). key-needed's shipped text only uses %item_name%, but any of the sub-keys documented under Equipment sub-keys (material, name, hover-name, lore, amount, custom-model-data, durability, damage, enchantments, unbreakable) resolve the same way here. Like crate_*/reward_*, this item registration is local to this one message send — it is not available anywhere else in the plugin.

key-needed: "<warning>Vous devez avoir une <#26d971>%item_name% <#ffd60a>pour ouvrir cette caisse !"

Last modified: 25 July 2026

Placeholders

crate_*

reward_*

%item_name% in key-needed

`crate_*`

`reward_*`

`%item_name%` in `key-needed`