Placeholders

AstralPets registers one root placeholder namespace with AstralCore (pets) and four chained ComplexPlaceholder types that only resolve once something registers an instance into the current placeholder container: pet, blueprint, rarity, and food. For the placeholder syntax itself (%a_b_c%, %a_{b_c}%, $e(...)) see Placeholders.

`pets_*` (root)

Resolved by PetsPlaceholder, registered globally on RootPlaceholderContainer — usable anywhere AstralCore evaluates a placeholder.

Placeholder	Type	Description
`%pets_equipped%`	Optional<Pet>	The viewer's currently-selected pet, from `PetPlayerData#selectedPet()`. Player context required.
`%pets_actives%`	ItemProvider<Pet>	The viewer's active pets (`PetPlayerData#activePets()`). Player context required.
`%pets_all%`	ItemProvider<Pet>	Every pet the viewer owns (`PetPlayerData#pets()`). Player context required.
`%pets_blueprints%`	ItemProvider<PetBlueprint>	Every loaded pet blueprint (`AstralPets#blueprints().cachedPets()`). No player context needed.

%pets_blueprints% is checked before anything else, so it resolves in any context (console, non-player menus, …). equipped/actives/all additionally require context.context() to be a Player and that player's PetPlayerData to be loaded via SyncAPI.findData — either check failing makes the whole placeholder resolve to null.

`pet_*`

A Pet placeholder (namespace pet). Only resolves where something has registered a Pet instance into the container — see Chaining and context below.

Placeholder	Type	Description
`%pet_id%`	UUID	The pet's unique id.
`%pet_name%`	Component	The pet's current display name (set at creation, changeable via rename).
`%pet_rawName%`	String	Plain-text serialization of `name` (formatting stripped).
`%pet_blueprint%`	PetBlueprint	Chain into `blueprint_*`.
`%pet_item%`	ItemStack	The blueprint's `item` template, rendered with this `Pet` registered as the `%pet_*%` context — so `%pet_name%`/`%pet_level%`/ etc. inside the template resolve against this instance. Chain into item sub-keys (see Placeholders).
`%pet_experience%`	double	Current accumulated experience.
`%pet_level%`	int	Current level.
`%pet_nextLevelExperience%`	double	Experience required to reach `level + 1`, evaluated from the pet's rarity `level-expression`.
`%pet_inventory%`	PetInventory	Chain into `inventory_size` (int), `inventory_items` (ItemProvider), `inventory_contents` (raw `ItemStack[]`).
`%pet_hasInventory%`	boolean	`true` when the pet's inventory size is greater than 0 (i.e. its current level grants storage).
`%pet_isSpawned%`	boolean	`true` when the pet currently has a spawned entity in the world.
`%pet_selected%`	boolean?	`true`/`false` when this pet is the viewer's selected pet; `null` without a player context.
`%pet_active%`	boolean?	`true`/`false` when this pet is in the viewer's active-pets list; `null` without a player context.
`%pet_effects%`	List<Component>	Rendered current-level effect lines — see Effect display sub-keys.
`%pet_nextLevelEffects%`	List<Component> / empty	Rendered next-level preview lines — see Effect display sub-keys.

Example — blueprints/simple.yml uses the pet's own context inside its item template:

item:
  material: "stone"
  name: "%pet_name% Lvl %pet_level%"
  lore:
    - "Level: %pet_level%"
    - "Experience: %pet_experience%"
    - "Effects"
    - "%pet_effects%"

Effect display sub-keys

%pet_effects% renders one line per effect configured on the pet's blueprint, using each effect's display template (or its displayStatsMax template instead, when the effect is maxed for the pet's current level and displayStatsMax is set). Two placeholders are available inside that template:

%value% — the effect's cumulative value at the pet's current level.
%maxValue% — the effect's cumulative value at the effect's own maxLevel.

Both are formatted with a thousands separator (space-grouped, up to 2 decimals — e.g. 12 345.67).

%pet_nextLevelEffects% renders a preview of the next level using each effect's next-level-display template with a single %value% bound to the effect's incremental value for level + 1 (not cumulative). Effects whose next-level value is 0 are skipped. The whole placeholder resolves to an empty component when the pet is already at its blueprint's max-level, or when every effect's next-level value is 0.

`blueprint_*`

A PetBlueprint placeholder (namespace blueprint). See Pet Blueprints for the blueprints/*.yml shape this reflects.

Placeholder	Type	Description
`%blueprint_id%`	String	The blueprint's id (its `id` key / registry key).
`%blueprint_name%`	Component	`default-name` — the name a freshly-built pet starts with.
`%blueprint_item%`	ItemStack	The blueprint's `item` template, rendered against the current context. Chain into item sub-keys (see Placeholders).
`%blueprint_rarity%`	PetRarity	Chain into `rarity_*`.
`%blueprint_maxLevel%`	int	`max-level`.

`rarity_*`

A PetRarity placeholder (namespace rarity), reached from blueprint_rarity/pet_blueprint_rarity.

Placeholder	Type	Description
`%rarity_id%`	String	The rarity id (e.g. `common`, `legendary`).
`%rarity_display%`	Component	The rarity's rendered display name (e.g. `<#357df8>Rare`).
`%rarity_color%`	TextColor	The rarity's configured color.

The rarity's level-expression (the Crunch math expression that derives XP requirements) is not exposed as a placeholder.

`food_*`

A FoodBlueprint placeholder (namespace food). See Pet Food.

Placeholder	Type	Description
`%food_id%`	String	The food blueprint's id.
`%food_item%`	ItemStack	The food's `item` template. Chain into item sub-keys (see Placeholders).
`%food_experience%`	double	Experience granted to a pet fed this item.

Chaining and context

Unlike pets, the pet/blueprint/rarity/food namespaces are not registered on RootPlaceholderContainer — they only resolve where the surrounding code has explicitly registered an instance into the placeholder container being evaluated. In practice that happens:

Inside a blueprint's own item/entity.name/entity.sub-name templates, evaluated with that Pet registered (see the simple.yml example above).
In command feedback — /pets give and /pets food build a container from AstralPaperAPI.createPlaceholderContainer(target) (giving %player_name% etc.) and register the resolved blueprint on top, so give-success/give-food-success can reference %player_name% and %blueprint_name%/%food_item_name% together:

give-success: "<success><#26d971>%blueprint_name% <#80ed99>a été donné avec succès à <#26d971>%player_name%<#80ed99>."
give-food-success: "<success><#26d971>%food_item_name% <#80ed99>a été donné avec succès à <#26d971>%player_name%<#80ed99>."

In menus and other pet-related messages (pet added/removed/spawned/leveled-up, etc.), where the relevant Pet is registered before the message is sent.

Chains compose across namespaces: %blueprint_rarity_display% reads a blueprint's rarity display, and %pet_blueprint_rarity_id% walks pet → blueprint → rarity from a single Pet instance. Any *_item% key (pet_item, blueprint_item, food_item) resolves to an ItemStackPlaceholder — see Placeholders for its sub-keys.

Last modified: 25 July 2026

Placeholders

pets_* (root)

pet_*