Developer API Usage
MCIdentity lets other plugins build on its identities: an economy, a bank, a guild or membership system, a region guard. This page explains what a plugin author can do with it and the one rule every integration must follow. It describes the library in plain language; it is not a coding tutorial.
Looking for the events your plugin can react to? See Events & Listeners.
1 · Getting the library
The core plugin publishes its developer library to GitHub Packages, under the MCOriax mcidentity repository. Every release is published automatically when it reaches the main branch, so the library always matches the plugin. The current version is 4.7.0.
- Three modules. The api module holds the data types, the common module holds the provider and the shared data layer, and the bukkit module holds the events and server-side helpers.
- Compile against it, do not bundle it. MCIdentity is already installed on the server, so your plugin only needs the library while it is being built. Packing a second copy into your own jar causes conflicts.
- A token is required. GitHub Packages asks for a login even for public packages, so your build needs a GitHub account and a personal access token allowed to read packages. Keep that token outside your project, never in a file you commit.
- Load after MCIdentity. Declare MCIdentity as a dependency of your plugin so the server starts it first. Use a soft dependency instead if your plugin should also run without it.
The add-ons in this project consume the library exactly this way, which is how they share the core plugin's central server connection and its Folia-aware scheduling instead of carrying copies of their own.
2 · What you can do
Everything goes through one entry point, the MCIdentity provider. It becomes available once MCIdentity has connected to its storage, and a plugin should check that it is ready before using it.
Everything that touches storage runs in the background. Such calls hand back their answer later rather than immediately, so the game never waits on a database. When the answer arrives, switch back to the server's own thread (or the right region thread on Folia) before changing inventories, entities, or anything else the server only allows on that thread.
| Area | What a plugin can do |
|---|---|
| Professions | List every profession, and register new ones. |
| Identities | Create an identity, look one up by its ID, and read or update its level, experience, stat points, and head texture. |
| Aliases | Find an identity by its alias, and set, correct, or release an alias. The one-time rule players follow applies to the command only, so administrative tools can still fix a name. |
| Stats | Read all nine stats or a single one, replace them, or add to one stat safely even while other changes happen at the same time. |
| Active identity | Find which identity a player is wearing, read their session, equip or clear an identity for them, and write entries to the audit log. |
| Active profession | Ask which profession a player is playing right now. This answer comes straight from memory, so it is cheap enough for frequent checks such as letting only Guards into a region or keeping Merchants out. |
| Base identity slots | Read how many extra base identities a player owns, and grant more, either of random professions or of a chosen one. |
| Inventories | Read and save each identity's own inventory and ender chest. |
| Swap cooldowns | Check, start, or clear the cooldown between identity swaps, and show how long is left in a readable form. |
Profession names are stored in lower case, so compare them without regard to capital letters.
3 · Reacting to identity changes
MCIdentity announces what happens to identities through server events, on SpigotMC, PaperMC, and Folia alike. For most integrations two of them matter most:
- Equip is the moment to load whatever your plugin keeps for that identity, such as its bank account.
- Unequip is the moment to save it and let it go.
Both can be cancelled. A membership plugin, for example, can refuse to let a player wear an identity until its membership is active.
On Folia these events can arrive on a region thread rather than the main thread, so a listening plugin must be safe to run there and should hand any main-thread-only work back to the right scheduler.
The full list, including creation, death, stat changes, and the check that runs before an equip, is on the Events & Listeners page.
4 · Architecture warning — one identity is one account
Each identity is an entirely separate character. Store your data against the identity's ID, never against the player's own Minecraft ID.
One player owns many identities, and each has its own ID. Only one is active at a time, and switching is a full change of character, as if the player logged into a different account.
If a plugin stores data against the player instead:
- Bank balances, memberships, ranks, and cooldowns leak between characters that are meant to be independent.
- Money or perks earned on one identity show up on all of the player's other identities.
- Per-character progression and economy balancing become impossible.
Rules for other plugins:
- Find the player's current identity, from the provider or from the equip and unequip events, and use its ID as the key for all of your data.
- Load a character's data when it is equipped, and save it when it is unequipped.
- Even the default Player identity has its own ID, so there is never a reason to fall back to the player's Minecraft ID. If no identity is active, wait until one is.
Every MCOriax add-on follows these rules, which is why runes and cosmetics, and the upcoming perks, all change when a player switches identity.