Astral Realms Documentation Help

Placeholders

AstralClasses registers three placeholder namespaces with AstralCore: classes (player context), class (AstralClass instance), and skill-entry (ability metadata). All three participate in the standard AstralCore placeholder system — %outer_{inner}%, $e(...), and chaining into other namespaces via variables.

classes_* (player context)

These placeholders require a Player in the placeholder context and access the player's current class state via ClassPlayerData. ClassExpansion checks for a Player in context before dispatching, so every classes_* placeholder resolves to null if there is no player in context. If a player is present but their ClassPlayerData hasn't synced yet, the placeholder throws an IllegalStateException.

Placeholder

Returns

Notes

%classes_toggle%

Boolean

Player's auto-attack toggle setting.

%classes_ability_<abilityId>%

String

The skill-id of the ability <abilityId> in the player's currently selected subclass, or null if not found.

%classes_cooldown_<abilityId>%

String

Remaining cooldown for ability <abilityId> in seconds, rounded up with Math.ceil. Returns "0" once expired.

%classes_cooldown_<abilityId>_max%

String

Maximum (configured) cooldown for ability <abilityId> in seconds, rounded up.

%classes_class_id%

String

ID of the player's currently selected class.

%classes_class_raw%

AstralClass

The player's selected class as an object — chain into class_* keys to access its properties.

%classes_class%

Component

Display name of the player's selected class.

%classes_subclass%

String

ID of the player's currently selected subclass (defaults to "default").

%classes_level%

String

Player's level within the selected class.

%classes_skill-level_<abilityId>%

String

Player's unlock level for ability <abilityId> (0 if not unlocked).

%classes_<classId>%

AstralClass

Lookup any class by ID — e.g. %classes_knight% returns the Knight class object.

Context requirement

All classes_* placeholders require a Player in the resolution context. When used in:

  • Menus (via AstralPaperAPI.createPlaceholderContainer(player)): Player is provided automatically.

  • Chat, scoreboards (via PlaceholderAPI fallback): Player is implicit from the formatter's context.

  • Bare containers (new PlaceholderContainer() without player setup): Resolves to null.

Cooldown semantics

Cooldowns are not the raw configured duration — they reflect the ATTACK_SPEED-scaled effective cooldown:

modifiedCooldownMs = (baseCooldownMs / attackSpeed) remaining = Math.ceil((modifiedCooldownMs - elapsed) / 1000.0)

A higher ATTACK_SPEED stat shortens the reported remaining cooldown. See Abilities & Input for input binding semantics.

class_* (AstralClass)

An AstralClass is itself a ComplexPlaceholder. It is typically reached via %classes_class_raw% or %classes_<classId>%, and may be bound to a variable for convenient chaining (see Example below).

Static metadata (no player required)

Placeholder

Returns

Notes

%class_id%

String

Class identifier.

%class_name%, %class_display-name%

Component

Display name (MiniMessage).

%class_weapon%, %class_weapon-item%

ItemStack

The equippable weapon carried by players of this class.

%class_weapon-display%

ItemStack

Cosmetic weapon shown in the class selection menu.

%class_experience-to-level-up%, %class_xp-to-level-up%, %class_max-experience%

PlaceholderWrapper<Integer>

XP required per level (may be a placeholder expression).

Subclasses (no player required)

Placeholder

Returns

Notes

%class_subclasses%

String

Comma-separated list of subclass IDs.

%class_subclasses_count%

int

Total subclass count.

%class_has-subclass_<id>%

Boolean

Whether the class has a subclass with ID <id>.

%class_unlocked%

Boolean

Whether the player has unlocked this class. Requires a player in context — unlike the other static-metadata keys, AstralClass#get() does not null-check the player here before resolving progress data, so resolving this without a player throws a NullPointerException rather than returning null.

Abilities

Placeholder

Returns

Notes

%class_abilities%

String

Comma-separated list of ability IDs in the currently-selected subclass. Without a player, falls back to the "default" subclass rather than erroring.

%class_abilities_<subClassId>%

String

Comma-separated list of ability IDs in subclass <subClassId>.

%class_abilities_<subClassId>_count%

int

Count of abilities in subclass <subClassId>.

%class_skill-id_<abilityId>%, %class_selected-skill_<abilityId>%

String

The underlying skill-id for ability <abilityId> in the currently-selected subclass, or null if not in that subclass. Without a player, falls back to the "default" subclass rather than erroring.

%class_skill-entry_<abilityId>%

SkillEntry

The ability's metadata object — chain into skill-entry_* keys for properties like name, cooldown, and display damage. Without a player, falls back to the "default" subclass rather than erroring.

Ability properties

Chain %class_ability_<abilityId>_<property>% to access individual ability settings:

Property

Returns

Notes

id

String

Ability identifier.

name

Component

Ability display name.

skill-id, skill

String

Underlying skill-id.

cooldown

Long

Cooldown in milliseconds (resolved with player context if player present).

default-input

String

Default input binding (e.g. "LEFT_CLICK"), or null.

force-input-binding, force-binding

Boolean

Whether the player can rebind this ability.

boost-level, unlockable-boost-level

Integer

Class level at which the boosted version unlocks.

unlock-levels, unlockable-levels

String

Comma-separated class levels at which this ability unlocks.

Player-specific progress (require player)

Placeholder

Returns

Notes

%class_level%

int

Player's level within this class, or 0 if no progress data.

%class_experience%, %class_xp%

int

Total experience accumulated in this class.

%class_selected-subclass%, %class_subclass%

String

Player's selected subclass ID (falls back to "default").

%class_skill-level_<abilityId>%

int

Player's unlock level for ability <abilityId> (0 if not unlocked).

%class_boosted_<abilityId>%

Boolean

Whether ability <abilityId> is currently boosted for the player.

skill-entry_* (ability metadata)

A SkillEntry represents a single ability within a subclass. It is reached via %class_skill-entry_<abilityId>% or directly from class configuration.

Placeholder

Returns

Notes

%skill-entry_id%

String

Ability identifier.

%skill-entry_name%

Component

Ability display name (MiniMessage).

%skill-entry_info%

Component

Ability description/flavor text.

%skill-entry_skill-id%, %skill-entry_skill%

String

Underlying skill-id — e.g. "knight-attack-1". Cross-reference with AstralSkill for skill behavior.

%skill-entry_cooldown%

Long

Cooldown in milliseconds (resolved against current placeholder context).

%skill-entry_display-damage%

Component

Cosmetic damage range shown in menus — display-only; actual damage comes from the skill.

%skill-entry_default-input%

String

Default input binding (e.g. "LEFT_CLICK"), or null.

%skill-entry_force-input-binding%, %skill-entry_force-binding%

Boolean

Whether the player cannot rebind this ability.

%skill-entry_boost-level%, %skill-entry_unlockable-boost-level%

Integer

Class level at which the boosted version unlocks.

%skill-entry_unlock-levels%, %skill-entry_unlockable-levels%

String

Comma-separated class levels at which this ability unlocks.

Example usage

The class selection menu (menus/main.yml) demonstrates real-world chaining:

variables: selected: "%classes_class_raw%" items: class-display: slots: [20] copy-from: "%variables_selected_weapon-display%" name: "%variables_selected_name%" skill-1: slots: [5] copy-from: "%stacksuppliers_ce_skills:{variables_selected_skill-id_attack-1}%" name: "<bold><primary_color>%variables_selected_skill-entry_attack-1_name%" lore: - "" - "<color:#FFAA33><bold>| Infos" - " <secondary_color><text_color>%variables_selected_skill-entry_attack-1_info%" - "" - "<secondary_color><bold>| Caractéristiques" - " <secondary_color>Dégats: <text_color>%variables_selected_skill-entry_attack-1_display-damage%" - " <secondary_color>Cooldown: <text_color>$e(%variables_selected_skill-entry_attack-1_cooldown%/1000) secondes" - "" equip-class-available: slot: 7 priority: 1 name: "<bold><primary_color>Équiper cette classe." view-requirements: - "[compare] %variables_selected_unlocked% == true" actions: - "[equip-class] %variables_selected_id%"

Breakdown:

  • %classes_class_raw% → the AstralClass object, bound to variable selected.

  • %variables_selected_weapon-display% → chains into class_weapon-display, fetching the cosmetic weapon.

  • %variables_selected_name% → chains into class_name, fetching the display name.

  • %variables_selected_skill-id_attack-1% → chains into class_skill-id_attack-1, returning the skill-id (e.g. "knight-attack-1").

  • %variables_selected_skill-entry_attack-1_name% → chains into class_skill-entry_attack-1, then skill-entry_name, fetching the ability's display name.

  • %variables_selected_skill-entry_attack-1_cooldown% → fetches the ability's cooldown in milliseconds, divided by 1000 inline with $e(...).

  • %variables_selected_unlocked% → chains into class_unlocked, checking if the player has unlocked this class.

  • %variables_selected_id% → chains into class_id, fetching the class id for the equip command.

See also

  • Classes — class configuration schema and fields these placeholders read.

  • Abilities & Input — input binding and ability selection.

  • AstralSkill — skill definitions and execution.

Last modified: 25 July 2026
CommandsActions