Astral Realms Documentation Help

Placeholders

AstralPets registers one root placeholder namespace with AstralCore (pets) and a set of chained ComplexPlaceholder types that only resolve once something registers an instance into the current placeholder container: pet, blueprint, rarity, food, skin, preset and effect. 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_presets%

ItemProvider<PetPreset>

The viewer's presets (PetPlayerData#presets()). Player context required.

%pets_blueprints%

ItemProvider<PetBlueprint>

Every loaded pet blueprint (AstralPets#blueprints().cachedPets()). No player context needed.

%pets_skins%

ItemProvider<PetSkin>

Every skin on the server, whether or not the viewer owns any — a catalogue, the way %pets_blueprints% is one for pets. No player context needed.

%pets_blueprints% and %pets_skins% are checked before anything else, so they resolve in any context (console, non-player menus, …). equipped/actives/all/presets 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.

A PetPlayerData instance registered directly on a container answers the same namespace with a slightly different key set — pets, activePets, selectedPet, hasSelectedPet, presets — and shadows the root placeholder for as long as it is registered.

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_skins%

ItemProvider<PetSkin>

The skins the pet permanently wears, in application order. Walk it with a list transformer — each line reads its skin through %parameter_skin_*%, exactly as an effect line does. A skin whose file is no longer configured is left out, so it prints nothing rather than an empty line.

%pet_skinNames%

Component

Those skins' names, comma-joined, for a lore that wants them on one line.

%pet_hasSkins%

boolean

Whether the pet wears any skin.

%pet_skinCount%

int

How many it wears (counts stored ids, including any whose file is missing).

%pet_effects%

ItemProvider<PetEffectView>

Every effect on the pet's blueprint, each bound to the pet's current level. Iterate it with a list transformer; each entry resolves as effect_*.

%pet_nextLevelEffects%

ItemProvider<PetEffectView>

The same, filtered to the effects that gain something at level + 1. Empty at max level, or when no effect gains next level.

%pet_effect_<id>%

PetEffectView?

One effect by the id it was written under in the blueprint, bound to the pet's level — for a lore line about a specific effect rather than the whole list. Chain into effect_* (%pet_effect_storage_value%). Nothing when the blueprint has no effect under that id.

Example — a blueprint's item template is rendered with its own pet as the context:

item: material: "mooshroom_spawn_egg" name: "%pet_name%" lore: - "<text_color>Niv. %pet_level% | Exp. %pet_experience%/%pet_nextLevelExperience%" - "$apply-transformer(pet-level-gauge)" - "%pet_blueprint_rarity_accent%<bold>| Effets" - "$apply-transformer(pet-effects)"

effect_* — one effect on one pet

Each entry of %pet_effects%/%pet_nextLevelEffects% is a PetEffectView: one of the blueprint's effects bound to the level the pet is actually at. Inside a list transformer it reads as %parameter_effect_…%; the namespace itself is effect.

Every value question is answered against a level that is already known, so a display line never has to feed a level back in or do arithmetic to work out whether an effect is maxed.

Placeholder

Type

Description

%effect_id%

String

The key the effect was written under in the blueprint.

%effect_label%

Component

Its label.

%effect_unit%

String

Its unit (percent, money, flag, …).

%effect_state%

LOCKED/ACTIVE/MAXED

How it reads at a glance — the one key a switch can dispatch the whole line on.

%effect_value%

String

Total granted at the pet's current level, formatted.

%effect_max-value%

String

Total at the effect's last level, formatted.

%effect_level-value%

String

What the current level alone granted, formatted.

%effect_raw-value%/%effect_raw-max-value%/%effect_raw-level-value%

double

The same three unformatted — what a requirement or $e(...) needs, since the formatted forms carry grouping spaces.

%effect_next-level%

int

The next level that grants something, or -1. Not necessarily level + 1: blueprints leave gaps.

%effect_next-value%

String?

What that level adds, formatted; nothing when there is no next gain.

%effect_next-total%

String?

What the total will stand at once that gain lands — usually the more useful number on a "next level" line.

%effect_raw-next-value%

double

The gain unformatted; 0.0 when there is none.

%effect_has-next%

boolean

Whether any further level grants something.

%effect_gains-next%

boolean

Whether the gain lands on the very next level specifically.

%effect_level%

int

The pet's level.

%effect_max-level%

int

The effect's highest configured level.

%effect_unlock-level%

int

The first level that grants anything.

%effect_maxed%/%effect_unlocked%/%effect_locked%

boolean

State as individual flags.

%effect_progress%

double

How far along, 0-1. A flag effect with no scale is 0 or 1.

%effect_percent%

long

The same, rounded to 0-100.

%effect_blueprint%

PetEffect

The effect implementation itself, for what only it knows (below).

Formatted values are space-grouped with up to two decimals (12 345.67), shared by every path a pet value reaches a player through.

Any key not listed above falls through to the effect implementation's own extraPlaceholder, so %effect_stat% and %effect_modifier_type%/%effect_modifier_key% work on a stats effect, and %effect_duration% (the interval, in milliseconds) on a money one.

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 a throwaway level-1 pet of this blueprint — not against the surrounding context. The template's lore is written in %pet_*% placeholders and transformers that read them, so without a pet in scope every one of them would stay literal and the XP gauge would fail parsing %pet_experience%. This is the same stack PetService.buildItemStack(blueprint) hands a player. Chain into item sub-keys (see Placeholders).

%blueprint_rarity%

PetRarity

Chain into rarity_*.

%blueprint_maxLevel%

int

max-level.

%blueprint_skins%

ItemProvider<PetSkin>

The skins a pet of this blueprint may still take on, resolved against the loaded skin files (ids with no file are skipped). Iterate it to list one pet's skins with the same entry template a full catalogue uses.

%blueprint_skinIds%

List<String>

The raw ids the blueprint lists — for testing membership rather than drawing entries.

%blueprint_hasSkins%

boolean

Whether it accepts any.

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 colour the rarity's name is written in.

%rarity_accent%

TextColor

The lighter tone its detail text is written in (accent-color), falling back to color when unset. This is what the shipped lore and transformers colour effect lines with, as %pet_blueprint_rarity_accent%.

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.

skin_*

A PetSkin placeholder (namespace skin), reached from %pets_skins%/%pet_skins%/%blueprint_skins%, from a skin item's own template, and from the skin messages. See Pet Skins.

Placeholder

Type

Description

%skin_id%

String

The skin id.

%skin_name%

Component

Display name.

%skin_item%

ItemStack?

The skin's item template. Null-safe — a skin file may omit item (it still dresses the pets already wearing it, it just cannot be handed out), so a catalogue walking every skin does not break on that one.

%skin_pets%

ItemProvider<PetBlueprint>

The pets this skin fits, in blueprint load order — the question a skin seen on its own, in a catalogue or a shop, cannot otherwise answer.

%skin_petNames%

Component

Those pets' default names, comma-joined.

%skin_petCount%

int

How many there are — a skin every pet shares reads better as a number than as a list of twenty.

%skin_conflicts%

ItemProvider<PetSkin>

The skins this one cannot be worn with, in both directions of the conflict.

%skin_conflictNames%

Component

Their names, comma-joined — for a lore line that warns before a player spends the item.

%skin_conflictCount%

int

How many there are.

preset_*

A PetPreset placeholder (namespace preset), reached from %pets_presets% entries. See Pet Presets.

Placeholder

Type

Description

%preset_id%

UUID

The preset's unique id.

%preset_name%

String

Its name.

%preset_petIds%

UUID[]

The raw pet ids it holds.

%preset_pets%

ItemProvider<Pet>

The viewer's pets that it names. Player context required.

Chaining and context

Unlike pets, the pet/blueprint/rarity/food/skin/preset/effect 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 example above), and inside every transformer those templates call.

  • Inside a skin's item template (with the skin registered) and its entity.equipment items (with the pet registered).

  • 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 September 2026
Pet FoodDeveloper API