DUXPLIMA Documentation

Events

The event bus, the 35 events, and why they may arrive off the main thread.

uxmClaims has its own event bus. These are not Bukkit events and are not registered with PluginManager.

Listening

public class ClaimListener {

    @ClaimEventHandler(priority = 5, ignoreCancelled = true)
    public void onCreate(ClaimCreateEvent event) {
        // …
    }
}

UxmClaimBukkitAPI.getInstance().registerEvent(new ClaimListener());

Unregister with api.unregisterEvent(instance).

AttributeDefaultMeaning
priority1Lower runs first
ignoreCancelledfalseSkip this handler if an earlier one cancelled the event

Note that priority runs lowest first, which is the opposite of Bukkit's EventPriority.

Cancelling

Events extending CancellableDomainEvent can be cancelled, which aborts the operation:

@ClaimEventHandler
public void onCreate(ClaimCreateEvent event) {
    if (isInsideEventArena(event)) {
        event.setCancelled(true);
    }
}

The events

AreaEvents
ClaimClaimCreateEvent, ClaimDeleteEvent, ClaimExpireEvent, ClaimRenameEvent, ClaimRelocateEvent, ClaimRescheduleEvent, ClaimFlagsUpdateEvent
ChunksClaimChunkExtendEvent, ClaimChunkShrinkEvent
MembersClaimMemberKickEvent, ClaimMemberLeaveEvent, ClaimMemberBanEvent, ClaimMemberUnbanEvent, ClaimMemberRoleAssignEvent, ClaimMemberPermissionUpdateEvent, ClaimOwnerTransferEvent
InvitesClaimInviteSendEvent, ClaimInviteAcceptEvent, ClaimInviteRevokeEvent
RolesClaimRoleCreateEvent, ClaimRoleDeleteEvent, ClaimRoleRenameEvent, ClaimRolePriorityUpdateEvent, ClaimRolePermissionUpdateEvent
WarpsClaimWarpCreateEvent, ClaimWarpDeleteEvent, ClaimWarpRenameEvent, ClaimWarpRelocateEvent, ClaimWarpVisibilityEvent
Claim blockClaimBlockPlaceEvent, ClaimBlockChangeEvent, ClaimBlockDestroyEvent
VaultClaimVaultUpdateEvent
MovementClaimMoveInsideEvent, ClaimMoveOutsideEvent

ClaimMoveInsideEvent and ClaimMoveOutsideEvent fire on border crossings, which on a busy server is often. Keep those handlers cheap, no database calls, no synchronous lookups.

Handlers may run off the main thread

uxmClaims publishes events from whichever thread performed the operation, and writes are frequently asynchronous. Touching the Bukkit API (spawning entities, changing blocks, sending packets) from a handler will throw or corrupt state on a regionised server.

Schedule back to the main thread first:

@ClaimEventHandler
public void onCreate(ClaimCreateEvent event) {
    Bukkit.getScheduler().runTask(plugin, () -> spawnCelebration(event));
}

On Folia, use the region scheduler for the claim's location rather than the global one.

Events versus webhooks

webhooks.yml posts a subset of these to Discord without any code. Reach for the event bus when you need to react (cancel the operation, mirror the change into another plugin, write an audit row) and for a notification, use the webhook.