Astral Realms Documentation Help

Placeholders

AstralShop exposes two ComplexPlaceholder namespaces, shop and item, wrapping ShopConfiguration and ShopItem respectively. Neither is registered globally with AstralCore — both only exist inside the placeholder context MenuService#openShopMenu builds for the shop menu blueprint (plus wherever PaperShopService registers a ShopItem directly, e.g. buy/sell messages — see below). For the placeholder syntax itself (%a_b_c%, chaining, $e(...)) see Placeholders.

shop_* (ShopConfiguration)

ShopConfiguration implements ComplexPlaceholder under namespace shop.

Placeholder

Type

Description

%shop_id%

String

The shop's id.

%shop_title%

Component

The shop's title (ComponentWrapper, MiniMessage).

%shop_slots%

List<String>

The shop's configured slots.

%shop_items%

ItemProvider (of ShopItem)

Every ShopItem in the shop's items map, wrapped in an ItemProvider — use as a layout provider: to iterate each item's %item_*% placeholders into a menu. See Menu Layouts.

Any sub-key other than id, title, slots, or items resolves to null (the switch's case null, default branch). See Shop Configuration for the YAML these fields come from.

item_* (ShopItem)

ShopItem implements ComplexPlaceholder under namespace item. Reached by iterating %shop_items%, or wherever a ShopItem is registered directly into a placeholder container.

Placeholder

Type

Description

%item_id%

String

The item's id (its key in the shop's items map).

%item_buyPrice%

double

The buy price, recomputed with the viewing player's price modifiers (ModifierService#computePrice, ShopModifierScope.BUY) on top of the configured buy-price. Returns 0 when the placeholder context isn't a Player (e.g. resolved for console).

%item_sellPrice%

double

The sell price, recomputed the same way for ShopModifierScope.SELL on top of sell-price. Also 0 outside a Player context.

%item_display%

ItemStackPlaceholder

The configured display item stack. A chain point — drill into it with %item_display_material%, %item_display_name%, %item_display_lore%, %item_display_amount%, etc. (see Placeholders — Equipment sub-keys for the full ItemStackPlaceholder sub-key list).

%item_buyable%

boolean

Whether the item can be bought.

%item_sellable%

boolean

Whether the item can be sold.

%item_giveItem%

boolean

Whether buying gives the display stack directly (true) or runs buy-actions instead (false).

Any other sub-key (including name) falls through to null.

How these are wired

MenuService#openShopMenu hands the opened ShopConfiguration to AstralCore's MenuContainer as the shop menu parameter:

this.container.computeAndOpen(player, "shop", Map.of("shop", configuration));

That makes %shop_*% available anywhere in the shop menu blueprint's placeholder context. A layout then iterates %shop_items% and renders each element's %item_*% placeholders per slot — AstralShop itself does not ship a menus/shop.yml blueprint (see Shop Configuration — Menu rendering), so this is illustrative of what such a blueprint would look like:

layouts: shop-items: provider: "%shop_items%" taint: "shop-item" items: shop-item-slots: slots: [10, 11, 12, 13, 14, 15, 16] taints: - "shop-item" copy-from: "%item_display%" lore: - "<gray>Buy: <gold>%item_buyPrice%" - "<gray>Sell: <gold>%item_sellPrice%" actions: LEFT: - "[buy-shop-item] %shop_id% %item_id% 1" RIGHT: - "[sell-shop-item] %shop_id% %item_id% 1"

Item placeholders in messages

PaperShopService also registers the item placeholder directly (registerPlaceholder(item)) into the placeholder container used for the buy/sell message flows, alongside %amount% and %price%. That means every %item_*% sub-key documented above also resolves inside the item-bought, item-sold, and not-enough-items message templates. See Messages — Placeholders for the full breakdown, including a shipped-default inconsistency: messages.yml uses %item_name%, which is not a valid item_* sub-key (the working equivalent is %item_display_name%).

Summary

Placeholder

Returns

%shop_id%

The shop's id.

%shop_title%

The shop's title component.

%shop_slots%

The shop's configured slot list.

%shop_items%

ItemProvider of the shop's ShopItems, for menu iteration.

%item_id%

The item's id.

%item_buyPrice%

Buy price, player-modifier-adjusted; 0 outside a Player context.

%item_sellPrice%

Sell price, player-modifier-adjusted; 0 outside a Player context.

%item_display%

The item's display ItemStack (chain-able).

%item_buyable%

Whether the item can be bought.

%item_sellable%

Whether the item can be sold.

%item_giveItem%

Whether buying gives the item directly instead of running buy-actions.

See also

  • Shop Configuration — the shop/items YAML these placeholders read from.

  • Messages — where %item_*% also resolves, and the %item_name% inconsistency.

  • Actions — [buy-shop-item]/[sell-shop-item], the actions typically triggered from a rendered %item_*% slot.

  • Developer API — ShopBuyEvent/ShopSellEvent, fired before the placeholders above are used to build a message.

Last modified: 25 July 2026
ActionsDeveloper API