Actions

AstralClasses registers three global actions that manage class progression and equipment. These actions are available wherever AstralCore actions are used: menu item callbacks, ability triggers, dialog buttons, and other configuration-driven contexts.

All class actions require the executor to have loaded ClassPlayerData from AstralSync. If the player's data is not yet synchronized, the action throws an IllegalStateException.

`equip-class`

Sets the player's currently equipped class, but only if the class is already in their unlocked collection.

Field	Description
Argument	Class ID (resolved as a placeholder-wrapped string)
Behavior	If the class is unlocked, updates `selectedClassId`. If not unlocked, the action is a no-op (silently fails).
Failure	No error is raised if the class is not unlocked; the action simply does nothing.

left-click-actions:
  - "[equip-class] %variables_selected_id%"
  - "[message] <info>You have equipped the <secondary_color>%variables_selected_name%<#a2d2ff>."
  - "[refresh]"

In the example above (from the classes menu), %variables_selected_id% resolves to the class ID before the action executes. The menu's view-requirement gates this item to only show when %variables_selected_unlocked% == true, ensuring the action will succeed.

`unlock-class`

Adds a class to the player's unlocked collection and initializes their progress for that class.

Field	Description
Argument	Class ID (resolved as a placeholder-wrapped string)
Behavior	If the class is not yet unlocked, adds it to `unlockedClassIds` and creates a new `ClassProgressData` entry seeded at the plugin's configured `starting-level` (see Configuration). If already unlocked, the action is a no-op.
Default Level	Progress data is initialized with level = `configuration.startingLevel()`, experience = 0, and empty ability/modifier maps.

- "[unlock-class] warrior"
- "[message] <success>You have unlocked the <bold>Warrior</bold> class!"

This action is typically triggered by progression systems (quests, dungeons, events) to grant new classes to players.

`debug-class`

Logs the player's complete ClassPlayerData to the server console. This is a debugging aid with no arguments or configuration.

Field	Description
Argument	None
Behavior	Fetches the player's `ClassPlayerData` and logs the full object state (including selected class, unlocked classes, progress data, abilities, modifiers) at INFO level.
Use Case	Troubleshooting class progression, inspecting player state, and development testing.

- "[debug-class]"

The output appears in the server log with the format:

DebugClassAction executed for player: <player_name>
<full ClassPlayerData toString()>

Action Summary

Action	Argument	Description
`equip-class`	class-id	Set the player's equipped class (requires already unlocked)
`unlock-class`	class-id	Add a class to unlocked collection and initialize progress
`debug-class`	—	Log the player's complete class data to the server console

Requirements & Synchronization

All three actions depend on ClassPlayerData being loaded and synchronized via AstralSync. The player must have completed the initial Sync handshake with the backend. If data is missing when the action runs, an IllegalStateException is thrown and the action is aborted:

Player data not found for player: <uuid>

When used in menus or action chains, ensure downstream actions account for the possibility that a player may not have synced data (e.g., guard with a [compare] requirement that checks a class placeholder before attempting to equip or unlock).

Cross-links

Placeholders — class and progress placeholders for use in actions and menus
Configuration — starting-level and other configuration keys
Classes — class structure and unlocking mechanics

Last modified: 25 July 2026