DUXPLIMA Documentation

The API

The entry point, the two facades, and every operation they expose.

Everything starts at UxmClaimBukkitAPI, which hands you ClaimFacade for claims and PlayerFacade for the plugin's player records. Reads are plain methods; writes take a command object.

Entry point

UxmClaimBukkitAPI api = UxmClaimBukkitAPI.getInstance();

ClaimFacade claims   = api.claimFacade();
PlayerFacade players = api.playerFacade();
MethodReturns
getInstance() (static)The API, or IllegalStateException before uxmClaims has started
claimFacade()ClaimFacade
playerFacade()PlayerFacade
eventBusPort()EventBusPort, the event bus
registerEvent(Object) / unregisterEvent(Object)Adds or removes an event listener
getInstance(Class<T>) / getInstance(Class<T>, String)Any object from the plugin's container, such as ClaimPermissionPolicy

Domain coordinates

The facades take the plugin's own Location and Chunk (package com.uxplima.claim.domain.model.vo), not Bukkit's. BukkitConverter translates in both directions.

MethodConverts
toDomainLocation(org.bukkit.Location)Bukkit location to domain Location
toDomainChunk(org.bukkit.Chunk) / toDomainChunk(org.bukkit.Location)Bukkit chunk or location to domain Chunk
toBukkitLocation(Location) / toBukkitChunk(Chunk)Back to Bukkit, null when the world is not loaded

Reading

MethodReturns
findById(UUID) / findByChunk(Chunk) / findByLocation(Location)Optional<Claim>
getById / getByChunk / getByLocationClaim, or ClaimException (ERROR_CLAIM_NOT_FOUND) when absent
getByIdUnsafe / getByChunkUnsafe / getByLocationUnsafeClaim or null
existsById / existsByChunk / existsByLocation / existsByWarpName(String)boolean
findByOwnerUid(UUID) / findByMemberUid(UUID) / findByInvitedUid(UUID)List<Claim>
countByOwnerUid(UUID) / countByMemberUid(UUID)int
findAllClaims() / findExpiredClaims()List<Claim>
findPublicWarps()List<ClaimWarp>

Reads come from memory, not the database, and every Claim returned is a copy. Prefer find…; use get…Unsafe only after a check.

Location here = BukkitConverter.toDomainLocation(player.getLocation());

boolean canBuild = claims.findByLocation(here)
        .map(claim -> claim.hasPermission(player.getUniqueId(), ClaimPermission.BLOCK_PLACE))
        .orElse(true);   // wilderness is not protected

hasPermission resolves bans, ownership, per-member overrides and the role chain. It ignores uxmclaims.admin; see Domain model for the check that includes it.

Writing

try {
    Claim renamed = claims.renameClaim(ClaimRenameCommand.builder()
            .claimId(claim.getId())
            .actorUid(player.getUniqueId())
            .name("Harbour")
            .build());
} catch (ClaimException e) {
    getLogger().info("Rename refused: " + e.getStatus());
}

Every command is a record in com.uxplima.claim.app.command with a Lombok builder. Its constructor validates the fields and throws ClaimException (ERROR_INVALID_INPUT) for a missing one. A refused write throws ClaimException too, and getStatus() names the reason.

MethodCommandFieldsReturns
createClaimClaimCreateCommandactorUid, ownerUid, claimName, spawnLocationClaim
deleteClaimClaimDeleteCommandclaimId, actorUidClaim
expireClaimClaimExpireCommandclaimIdClaim
renameClaimClaimRenameCommandclaimId, actorUid, nameClaim
relocateClaimClaimRelocateCommandclaimId, actorUid, locationClaim
rescheduleClaimClaimRescheduleCommandclaimId, actorUid, adjustment (Duration)Claim
updateClaimFlagsClaimFlagsUpdateCommandclaimId, actorUid, flagsClaim
inviteMemberClaimInviteSendCommandclaimId, actorUid, invitedUidClaimInvite
revokeInviteClaimInviteRevokeCommandclaimId, actorUid, invitedUidClaimInvite
acceptInviteClaimInviteAcceptCommandclaimId, invitedUidClaimMember
kickMemberClaimMemberKickCommandclaimId, actorUid, memberUidClaimMember
leaveMemberClaimMemberLeaveCommandclaimId, memberUidClaimMember
banMemberClaimMemberBanCommandclaimId, actorUid, bannedUid, reasonClaimBan
unbanMemberClaimMemberUnbanCommandclaimId, actorUid, bannedUidClaimBan
updateMemberPermsClaimMemberPermissionUpdateCommandclaimId, actorUid, memberUid, deniedPermissions, allowedPermissionsClaimMember
assignMemberRoleClaimMemberRoleAssignCommandclaimId, actorUid, memberUid, roleIdClaimMember
transferOwnershipClaimOwnerTransferCommandclaimId, actorUid, newOwnerUidClaimMember
extendClaimClaimChunkExtendCommandclaimId, actorUid, chunkClaimChunk
shrinkClaimClaimChunkShrinkCommandclaimId, actorUid, chunkClaimChunk
placeBlockClaimBlockPlaceCommandclaimId, actorUid, blockKeyId, locationClaimBlock
changeBlockClaimBlockChangeCommandclaimId, actorUid, blockKeyIdClaimBlock
destroyBlockClaimBlockDestroyCommandclaimId, actorUidClaimBlock
updateVaultClaimVaultUpdateCommandclaimId, actorUid, items (List<Item> of slot and serialised stack)ClaimVault
createRoleClaimRoleCreateCommandclaimId, actorUid, nameClaimRole
deleteRoleClaimRoleDeleteCommandclaimId, actorUid, roleIdClaimRole
renameRoleClaimRoleRenameCommandclaimId, actorUid, roleId, nameClaimRole
updateRolePriorityClaimRolePriorityUpdateCommandclaimId, actorUid, roleId, priorityClaimRole
updateRolePermissionClaimRolePermissionUpdateCommandclaimId, actorUid, roleId, permissionsClaimRole
createWarpClaimWarpCreateCommandclaimId, actorUid, name, isPublic, locationClaimWarp
deleteWarpClaimWarpDeleteCommandclaimId, actorUid, warpIdClaimWarp
renameWarpClaimWarpRenameCommandclaimId, actorUid, warpId, nameClaimWarp
relocateWarpClaimWarpRelocateCommandclaimId, actorUid, warpId, locationClaimWarp
updateWarpVisibilityClaimWarpVisibilityCommandclaimId, actorUid, warpId, isPublicClaimWarp

blockKeyId is a key from the blocks section of config.yml, such as block1. expireClaim refuses a claim whose time has not run out (ERROR_CLAIM_NOT_EXPIRED); use deleteClaim to remove one early.

Controlling side effects

Every write has a second overload taking ClaimCommandOptions. The one-argument form runs every side effect, as if a player had typed the command.

claims.createClaim(command, ClaimCommandOptions.builder()
        .without(ClaimSideEffect.ECONOMY)
        .without(ClaimSideEffect.WEBHOOK)
        .build());
EffectSkipping it means
PERMISSIONRole permissions and ability nodes are not checked
LIMITATIONEntitlement limits are not enforced
ECONOMYNothing is charged
COOLDOWNCooldowns are neither checked nor started
REGIONWorldGuard regions and disabledWorlds are not checked
WEBHOOKDiscord is not notified
FactoryEnabled effects
all(), forPlayer()All six
forAdmin()REGION, WEBHOOK
forSystem()WEBHOOK
none()None
builder()All six, minus each without(…); with(…) replaces the set

ClaimCommandOptions.of(ActorKind) gives the same presets, and ActorKind.PLAYER_PREAUTHORIZED is every effect except PERMISSION. Prefer removing effects one at a time over none(), which also removes the permission check.

Threading

A write takes a per-claim lock, publishes its events, then saves to the database before it returns. Call writes off the main thread, the way the plugin's own commands do. Reads are served from memory and are safe on any thread.

PlayerFacade

MethodReturns
findByUid(UUID) / findByName(String)Optional<CPlayer>
getByUid / getByNameCPlayer, throwing when absent
getByUidUnsafe / getByNameUnsafeCPlayer or null
existsByUid / existsByNameboolean
loginPlayer(PlayerLoginCommand) / registerPlayer(PlayerRegisterCommand)CPlayer

Use findByName to turn a name typed in chat into the UUID the command objects need. The plugin calls the login and register commands itself on join.

Related: Events, Domain model, Architecture