API
Reading the class catalogue and what a player is wearing, using abilities and moving energy on demand, and the three class events.
ClassesService is what another plugin reads and drives ExyliaClasses through: the class catalogue,
what each class can do and what it spends, and what a player is right now. It can also fire an
ability without its item and give or take energy, and three events let a plugin refuse a class or an
ability and hear when a class ends.
ExyliaAPI.get(ClassesService.class).ifPresent(classes ->
classes.classOf(player.getUniqueId())
.ifPresent(found -> player.sendMessage("Class: " + found.name())));The artifact, the repository and the plugin.yml line are the same for every Exylia plugin and live
on the public API page.
Classes are addressed by class id — the name of the class file, lowercased.
A player is in a class because their armor says so. Nothing here assigns one directly: apply asks
the plugin to enter a class the way equipping the armor would, refusal message and warm-up included,
and the class ends by itself the moment a piece comes off. A plugin that wants somebody in a class
gives them the armor PlayerClass.equipment() names.
The catalogue#
| Method | What it does |
|---|---|
classes() | Every class the server declares. A snapshot: fine for building a menu, wasteful in a loop. |
classById(String classId) | One class as an Optional<PlayerClass>. Empty when the catalogue declares no such id. |
exists(String classId) | Whether the catalogue declares that id. |
abilities(String classId) | What the class can do. Empty when the class does not exist or has no abilities. |
energy(String classId) | The resource it spends, as an Optional<ClassEnergy>. Empty when the class does not exist or spends nothing. |
Permissions#
| Method | What it does |
|---|---|
canUse(Player, String classId) | Whether they may enter the class. false when the class does not exist. |
Answers by the server's own rule, so a class the owner left open is allowed for everybody rather than refused for want of a node nobody declared.
What a player is#
| Method | What it does |
|---|---|
isInClass(UUID player) | Whether they are in a class right now. |
classOf(UUID player) | Their class as an Optional<PlayerClass>. Empty when they are in none. |
energyOf(UUID player) | How much energy they hold right now. 0 when they are in no class or their class spends none. |
marks(UUID player) | How many marks they carry. Zero is the ordinary state. |
isMarked(UUID player) | Whether they are marked at all. |
warmingUp(Player) | The class they are currently warming up into, as an Optional<PlayerClass>. Empty when they are not warming up. |
classForEquipment(Player) | The class their current armor names, whether or not they are in it. Empty when it names none. |
energyOf rises on its own between calls, at the class's own refill rate — read it when you draw
rather than caching it. isMarked is not the same as marks being above zero: a mark also belongs to
the weapon that placed it, and one whose weapon is gone no longer counts. Marks are put on a player by
somebody else's weapon and spent by it.
Between putting the armor on and the class taking effect there is a delay the owner configures, and a
player in it is in no class yet — which is why warmingUp exists, and why classForEquipment is what
tells "wearing the wrong armor" apart from "warming up". classForEquipment is also what a preview
asks: what would this set make somebody, before they wear it.
Actions#
| Method | What it does |
|---|---|
apply(Player, String classId) | Asks the player to enter a class. Returns nothing. |
remove(Player) | Takes them out of their class, with its passive effects, energy, marks and bars. Ability cooldowns keep running. |
useAbility(Player, Material trigger) | Uses one of their abilities, as right-clicking its item would. Returns an AbilityUseResult. |
apply runs the same flow equipping the armor runs: the permission is checked and refused out loud,
and the warm-up runs before the class takes effect — so nothing has happened by the time the call
returns, which is why it reports nothing back. Read classOf afterwards if you need to know. The
class still ends the moment the player's armor stops naming it, so this is not a way to put somebody
in a class they are not dressed for.
remove leaves the armor alone, so putting a piece back on puts them in the class again.
useAbility runs the whole flow a click runs: cooldown and energy are checked and refused out loud,
AbilityUseEvent fires, the energy is spent, the cooldown starts and the effects land on whoever the
ability reaches. The one thing it does not do is consume an item, and the player does not need to hold
one. The trigger is the ability's ClassAbility.trigger(). Call it on the thread that owns the player.
AbilityUseResult | Meaning |
|---|---|
USED | The ability went off. |
NOT_IN_CLASS | The player is in no class. Warming up into one counts as none. |
UNKNOWN_ABILITY | Their class has no ability on that trigger. |
ON_COOLDOWN | Still cooling down. |
NOT_ENOUGH_ENERGY | They hold less than it costs. |
CANCELLED | An AbilityUseEvent handler refused it. |
Every refusal except CANCELLED has already been told to the player in the plugin's own words.
Energy#
| Method | What it does |
|---|---|
giveEnergy(Player, double amount) | Adds energy, never past the class's max. false when they are in no class or it spends none. |
spendEnergy(Player, double amount) | Takes energy, all of it or none. false when they hold less, are in no class, or it spends none. |
Both throw on a negative amount and redraw the energy bar. Energy refills every tick on the player's
own thread, so call these from that thread: a command, a listener for that player, or a task scheduled
on them. spendEnergy is what a plugin charging energy for something of its own uses.
Events#
All three live in net.exylia.lib.api.classes.event, carry getPlayer() and getPlayerClass(), and
are called on the thread that owns the player, which on Folia is their region thread.
| Event | When | Cancellable |
|---|---|---|
ClassEquipEvent | At the end of the warm-up, the moment the class would start, before any of it is applied. | Yes: the player stays dressed for the class but not in it until their armor changes again. |
AbilityUseEvent | Once a use would go through: in the class, off cooldown, energy held. Fires for a click and for useAbility. getAbility() is the ClassAbility. | Yes: no energy spent, no cooldown, no effect, no item consumed. |
ClassRemoveEvent | After the class is taken off, by armor, death, quit, reload or remove. classOf already answers empty. | No. A server shutting down does not fire it. |
Cancelling says nothing to the player: the handler that refused is expected to tell them why. The
player in ClassRemoveEvent may be on their way out, so check isOnline() before messaging them.
Types#
PlayerClass — id, name (colour codes still in it), permission and equipment, a map of
EquipmentSlot to Material. gated() answers whether entering the class needs a node at all; an
empty permission means the class is open to everyone. equipment is part of the public shape on
purpose: a kit plugin that hands out those pieces has handed out the class, and one that takes a piece
away has taken it back.
ClassAbility — name, trigger (the Material a player holds to use it, and also its key
within the class, so no two abilities share one), type, cooldown in seconds, energyCost and
radius in blocks. What the ability actually applies is left out: those are lines the owner writes in
the plugin's own syntax. What is here is what a menu, a shop or a heads-up display needs to describe
an ability without playing it.
ClassEnergy — name (mana, focus, rage), symbol, max and regenPerTick. It belongs to the
class rather than to the player: every archer has the same ceiling and the same refill rate, and what
one of them holds right now is energyOf. regenPerTick is there so a bar can be predicted between
updates rather than polled.
AbilityType — who an ability reaches: SELF, TO_CLAN, TO_ALLY, TO_ENEMY,
TO_CLAN_AND_ALLY. The clan-aware values mean nothing on a server without clans, where they find
nobody and the ability behaves as SELF does. radius is ignored by SELF.
Everything returning a value reads the plugin's cache and is safe from a menu redraw or a
placeholder. apply, remove and useAbility run the same flow a player's own gear change or click runs — potion effects,
cooldowns, bars, the messages they see — so call those on the main thread.
What it does not expose#
What an ability actually applies, passive effects, the weapon and mark internals, and raw configuration rows are left out on purpose — a public contract cannot be broken later, so it carries what an integration needs and nothing that only made sense inside one version.
If something you need is genuinely missing, ask on Discord.
Something missing on this page? Tell us on Discord