Events

Everything uxmEssentials does is published as an ordinary Bukkit event. What can be refused cleanly is published twice: once as a question you may cancel, once as the fact afterwards.

All of them live under com.uxplima.uxmessentials.api.bukkit.event, one package per context. You listen to them the way you listen to anything else:

@EventHandler
public void onHomeCreated(UxmHomeCreateEvent event) {
    getLogger().info(event.getPlayerName() + " set home " + event.getSlotNumber());
}

The two kinds

Every context publishes notifications. Only nine operations have a pre-event, and that is deliberate: a veto point is a promise that the operation can be refused with nothing half-done and nothing charged, and most of what a server does cannot be taken back that way. A mail already read, a punishment already served, a warp already walked to.

What you can cancel

A cancelled operation fails cleanly. Nothing is written, nothing is charged, no cooldown is stamped, and the player is told the action was blocked. It is not treated as an error, so nothing is logged as one. If you want them to know why, tell them yourself.

UxmPlayerPreTeleportEvent is asked at the one point every voluntary teleport passes through, so a listener that refuses teleports refuses /home, /warp, /spawn, /back, /tpa and /rtp alike, including whatever is added later. Two things are deliberately not asked: an arrival after respawn or first join, since there would be nowhere to leave the player, and a staff hard-delete of a player warp by id, since clearing an abusive warp must not be blockable by whatever else happens to be installed.

@EventHandler(ignoreCancelled = true)
public void onHomeCreating(UxmHomePreCreateEvent event) {
    // No Bukkit API here: this is not a tick thread.
    if (event.getLocation().world().endsWith("_nether")) {
        event.setCancelled(true);
    }
}

Threading

Notification events are delivered on the tick thread that owns their subject: the player's region on Folia, the main thread on Paper. Use the Bukkit API freely in those handlers.

Pre-events are different, and the difference is not cosmetic. The operation is blocked on your answer, so the event fires on whichever thread the operation is on, which is usually a database thread. In those handlers:

• do not touch the Bukkit API, and
• keep it quick, because a player is waiting.

Read the event, decide, return. If you need to do something afterwards, schedule it.

Nothing costs anything when nobody is listening. Both paths check for listeners before they build anything, so on a server with no plugin listening the whole mechanism is a map lookup: about 7 ns, no allocation, nothing scheduled. You never need to worry that adding a listener for one event makes the rest of the plugin slower.

Shared shapes

Most events carry a subject player, and those extend a common base:

Positions arrive as UxmLocation, a plain record of world, x, y, z, yaw and pitch. The world is its name rather than a Bukkit handle, because an event can describe a place in a world that is not loaded; turn it into a real location with Bukkit.getWorld(loc.world()), which answers null for an unloaded one. Money arrives as UxmMoney, an amount and its currency id, because a server can run more than one currency.

The catalogue

Homes

Teleport

getKind() tells you which door the teleport came through: REQUEST, BACK, RANDOM, SPAWN, HOME, WARP, RESPAWN, ADMIN or POSITIONAL.

Warps and player warps

Economy

getReason() on a rejection is either INSUFFICIENT_FUNDS or BALANCE_MAX_EXCEEDED.

Kits

Vaults

Moderation

getIssuer() returns a UxmIssuer, which is a name plus an optional UUID, because the console issues punishments too and it has no UUID.

Player state

Messaging, presence and communication

Staff, scoreboard and poses

Worlds

Holograms and NPCs

Trade

Both name two players rather than one, so they extend UxmEvent and not the player event. A cancel covers a cancel, a closed window and a disconnect alike: which of the three it was is not carried, because all three reach the same path. The completion event fires whether or not the operator has the trade audit switched on.

Ranks

A rankup fires after the new rank is stored and its actions have run. UxmRankSetEvent may be about a player who is offline, and getPreviousRank() is empty for one who had never been ranked before.

Discord links

The code is redeemed on Discord's side, so the link event very often fires for a player who is not online. Do not assume a live player from it. The unlink event carries the account that was bound because by the time it fires there is nowhere left to look it up, and it covers all three ways a binding ends: the player, an operator, or a plugin.

Inventory snapshots

Fires after the items are set, so a listener reading the inventory sees the restored one. The safety copy taken of what was there before is a capture rather than a restore, and fires nothing.

Security

The attempt that spends the last try fires the lockout rather than another failure, so one submission never fires both. Which factor was presented is not carried, because the verification does not learn it either: that is what makes the comparison constant-time.

A pass fires only for a proof that was actually made. A player holding no factor is never asked for one, and one waved through by a remembered device proved nothing this time.

Vanish

Fires for every door into vanish: the command, the staff-mode toggle, the presence panel, and a plugin calling the published action. By the time it fires the player is already hidden or already visible, so a listener mirroring the state elsewhere can read it straight off the event.

The level is the tier they are hidden at, counting from one. On a reveal it is the tier they were hidden at until a moment ago, which is what a listener needs to undo whatever it did when they vanished.

A quit does not fire it. A player who logs out hidden logs back in hidden, and treating a disconnect as a reveal would make every listener flicker on a server hop.

Voting and item or world utilities

Registering your listener

Nothing special is needed. There is no guard, no soft dependency, no load-order dance:

@Override
public void onEnable() {
    getServer().getPluginManager().registerEvents(new MyListener(), this);
}

Your listener's signatures name uxmEssentials classes, which resolve from the API artifact you compiled against and are present at runtime inside the plugin jar. If uxmEssentials is not installed, your listener simply never fires.

Next steps

• Adding the dependency
• Menu API to extend the GUI engine
• The sample consumer, a compiling example