AstralClasses Overview

AstralClasses is a Paper plugin that provides character class progression for the AstralRealms network. Players select a class (such as mage or knight), which grants them a weapon item and up to four abilities bound to input actions. Abilities are bound to skill IDs that live in AstralSkill; AstralClasses is the input binding and progression layer, not the skill engine.

What it does

Class selection menu (via /class) displays available classes and player progress.
Weapon items are unique items associated with each class, resolvable through the classes.weapon itemstack supplier and matched back to a class via ClassService.findByWeaponItem(). Equipping a class (the equip-class action) only updates the player's selected class — handing out the physical weapon item is left to menus/actions.
Abilities (up to 4 per subclass) are bound to input actions — LEFT_CLICK, RIGHT_CLICK, SWAP_HANDS, DROP, SPACE, SNEAK, or hotbar slots (HOTBAR_1 through HOTBAR_8).
Skill resolution receives an input, resolves it to an ability ID, then looks up the bound skill ID and triggers the skill via AstralSkill's SkillAPI.service().castAtPos().
Progression tracking stores per-player class selection, unlocked classes, level, experience, per-ability skill levels, and boost flags.
Subclasses allow multiple ability sets per class; the default subclass is named default.
Double jump is a built-in traversal feature, configurable per server group via double-jump-enable-groups.
Per-group gating restricts skills to designated server groups using skill-enable-groups. Double jump has its own double-jump-enable-groups key, but it is only checked for groups that already pass the skill-enable-groups gate — see Configuration.

Requirements

Dependency	Required	Notes
Paper 1.21	Yes	—
AstralCore	Yes	Configuration, menus, actions, placeholders, context resolvers.
packetevents	Yes	Input packet interception (clicks, sneaks, hand swaps, hotbar).
AstralStats	Yes	Attack-speed stat used for cooldown scaling.
AstralSync	Yes	Player-data persistence via `ClassSnapshotAdapter`.
AstralSkill	Soft (`plugin.yml`)	Skills are cast by ID via `SkillAPI.service().castAtPos(...)`. `SkillAPI.service()` throws `IllegalStateException` if AstralSkill never called `SkillAPI.initialize()` — i.e. ability triggers are not silently ignored if the soft-dependency is missing at runtime; casting will error.
AstralHud	Soft	Optional display integration.

Architecture at a glance

plugins/AstralClasses/
├── config.yml            ← default-class, level/exp curves, group gating
├── double-jump.yml       ← double-jump configuration
├── classes/              ← one YAML per class (id, weapon-item, abilities, actions)
│   └── mage.yml
└── menus/
    └── main.yml          ← class-selection UI (id: classes-main)

Services and Components

Service	Responsibility
`ClassService`	Loads class definitions from `classes/` folder; provides `findByPlayer()`, `findByWeaponItem()`, and subclass selection.
`SkillService`	Triggers skills via input events. Manages `CooldownManager` (attack-speed-scaled), `SkillTriggerManager` (per-tick throttle), and double-jump.
`MenuService`	Loads and opens the classes-main menu.

Listener	Trigger
`InputPacketListener`	PacketEvents hook; decodes `USE_ITEM`, `PLAYER_DIGGING`, `PLAYER_INPUT`, `INTERACT_ENTITY`, and `ANIMATION` client packets and calls `SkillService.tryTriggerSkill()`/`tryTriggerSpace()` directly for each resolved `InputType`.
`SkillTriggerListener`	A separate Bukkit listener: calls `SkillService.tryTriggerSkill()` on `PlayerSwapHandItemsEvent` (for `SWAP_HANDS`), and cancels weak (< 2.0 damage) player melee hits on `EntityDamageByEntityEvent`.
`PlayerListener`	Cleanup and player-specific hooks.
`DoubleJump`	Loaded from `double-jump.yml`; listens to `PlayerMoveEvent` and handles space-bar traversal.

Player Data

Persistence is handled by ClassPlayerData, persisted by the ClassSnapshotAdapter registered with AstralSync under key astralclasses:player_data. Per-player data includes:

Selected class ID
Unlocked class IDs
Per-class ClassProgressData (level, experience, per-ability skill levels, boost flags, subclass selection)
Input bindings (mapping InputType → ability ID)
Class settings (e.g., toggle auto-attack)

Registered Surfaces

Type	Name	Notes
Command	`/class`, `/classes`, `/classe`	Base commands (aliases).
Command modifier	`class`	Argument modifier for commands.
Placeholder	`classes`, `class`, `skill-entry`	Namespaces under the `ClassExpansion`.
ItemStack supplier	`classes.weapon`	Resolved via `WeaponClassItemSupplier`.
Action	`equip-class`, `unlock-class`, `debug-class`	Registered globally with AstralCore.
Completion	`inputType`	Lists `InputType` enum values.
Context	`Key.class`	For command argument resolution.
API	`ClassAPI`	Static accessors; see Developer API.

Cross-Product Note: Skills

Skills themselves (cast behaviour, projectiles, impacts, damage calculation) are defined and documented in AstralSkill. AstralClasses only references skills by string ID and calls the AstralSkill service to cast them. For skill DSL details, mechanics, and trigger types, refer to the AstralSkill documentation.

Last modified: 25 July 2026