Events & Listeners
MCIdentity has two sides to its listener system: the events other plugins can react to, and the internal gameplay listeners that translate player actions into profession experience.
How events work
Whenever something happens to an identity, MCIdentity announces it as a server event that any other plugin can listen for. The events work the same on SpigotMC, PaperMC, and Folia. On Folia an event may arrive on a region thread instead of the main thread, so a listening plugin must be safe to run there and should hand main-thread-only work back to the right scheduler.
Some events can be cancelled. Cancelling one stops the action it announces, which is how another plugin can add its own rules, such as "this identity needs an active membership".
Identity events
| Event | When it fires | What it tells you | Cancellable |
|---|---|---|---|
| Identity created | A new identity is created, for example the first time an unbound identity key is used. | The new identity, its profession, and its starting properties and stats. | No |
| Before equip | A player tries to equip an identity, before anything changes. | The player, the identity key, and whether they used the item directly or the menu. A plugin that cancels it can give the player a reason. | Yes |
| Equip | A player puts an identity on. | The player, the identity, and its key item. This is the moment to load data kept for that identity. | Yes |
| Unequip | A player takes an identity off. | The player and the identity. This is the moment to save that identity's data. | Yes |
| Death | A player wearing an identity dies. | The player, the identity, the key item, and whether it drops. A plugin can change whether it drops. | No |
| Stat added | One of an identity's stats is raised or lowered. | The identity, which stat, and by how much. The player is missing when the change came from the system rather than a player. | Yes |
For how equip and unequip fit into a full integration, see the Developer API page.
Internal gameplay listeners
Alongside the public events, MCIdentity runs a set of modular gameplay listeners that award profession experience for what players do. They are grouped by category so each stays focused on one kind of action, and every reward respects anti-farm safeguards (location-once rewards, rate limiting, and vanilla gating). The exact EXP values are set per profession in each profession's file — see Professions & EXP.
EXP-gain listeners
Modular listeners grouped by category (combat, defense, gathering, crafting, exploration, farming, and more) translate player actions into profession EXP according to each profession's configuration.
Identity, inventory & stats listeners
Handle equipping and unequipping identities, isolating each identity's inventory and ender chest, and applying stat-driven behaviour.
Respawn stat restoration
Restores an identity's stats after respawn, keeping health, energy, and food consistent with the active identity.
Cold-boot login protection
While a player is logging in, and only when the central server is the backend, checks that the central server is reachable and politely turns players away while a cold-started server is still waking up or storage is still initializing.