Installation

1. Pre-flight

Dependency	Required	Why
AstralCore	Yes	Configuration loading, command framework, menu system.
packetevents	Yes	Input detection (`InputPacketListener`) operates at the packet level.
AstralStats	Yes	Skill cooldowns scale by the player's `ATTACK_SPEED` stat.
AstralSync	Yes	Player class data stored as `ClassPlayerData` snapshot.
AstralSkill	No	The skill engine that abilities cast into. Soft dependency.
AstralHud	No	Soft dependency.
Paper api-version	Yes	Requires `1.21`.

2. Drop the JAR

Place AstralClasses-<version>.jar in your server's plugins/ directory alongside AstralCore, packetevents, AstralStats, and AstralSync.

3. First start

On first start the plugin copies its bundled default config.yml and double-jump.yml, and creates empty classes/ and menus/ directories (these two are loaded with AstralCore's recursive folder loader, which does not seed default files — you populate them yourself, see steps 5–6 below):

plugins/AstralClasses/
├── config.yml
├── double-jump.yml
├── classes/
└── menus/

4. Configure per-group enablement

Abilities and double-jump are per-group optional. Edit config.yml:

# Default class for new players (must exist in classes/)
default-class: "mage"

# Starting class level for new players
starting-level: 1

# Server groups where double jump is active
double-jump-enable-groups:
  - tower

# Server groups where skills (abilities) are active
# If a group is not listed, plugin logs "Skills are disabled for this server group"
# and the skill service does not initialize
skill-enable-groups:
  - tower

Per-group behavior:

Not in skill-enable-groups: No input packet listeners register; SkillService is skipped entirely — abilities, cooldowns, and double jump are all unavailable, regardless of double-jump-enable-groups.
In skill-enable-groups but not in double-jump-enable-groups: Abilities work normally; double jump specifically does not activate (see Double Jump for this dependency).
Set default-class: Must match an existing class id — used via ClassSnapshotAdapter.create() to auto-grant new players that class at starting-level.

Additional options

# Optional: enable verbose per-trigger debug logging
verbose-running: false

5. Add classes

Create YAML files in plugins/AstralClasses/classes/ — one file per class, keyed by the id field.
Reload at runtime with /class reload (permission: class.command.reload).

Example (trimmed from the shipped mage.yml):

id: "mage"
name: "<bold><primary_color>Classe Mage de feu"

weapon-item:
  material: "turtle_scute"
  item-model: "tower:fire_wand"
  name: "<red>Fire wand"

weapon-display:
  material: "turtle_scute"
  item-model: "tower:fire_wand_display"
  name: "<red>Fire wand"

experience-to-level-up: 150

sub-classes-abilities:
  default:
    - id: attack-1
      name: "Lance Flamme"
      info: "Tire une ligne de feu infligeant de légers dégâts."
      skill-id: mage-attack-1-laser
      unlockable-levels: [1, 2, 3]
      unlockable-boost-level: 5
      cooldown: 350
      default-input: LEFT_CLICK
      force-input-binding: true

sub-classes-actions:
  default:
    - "[console] stats modifiers add %player_name% class astralstats:max_health FLAT 280"
    - "[console] stats resource add %player_name% shield 190"

See Classes for the full schema.

6. Customize menus

The class selection menu is plugins/AstralClasses/menus/main.yml — a standard AstralCore menu. Edit freely. Requires the %classes_*% placeholder family for class rendering; see Placeholders.

Permissions

Node	Usage
`class.command.open`	Open the class menu.
`class.command.reload`	Reload configuration with `/class reload`.
`class.command.toggle`	Toggle auto-attack mode.
`class.command.reset`	Reset a player's class data with `/class reset <player>`.
`class.command.modifiers`	Apply an ad-hoc stat modifier with `/class modifier`.

Last modified: 25 July 2026