Claims-API.md

HuskClaims provides API for getting, creating resizing, & deleting [[claims]], child claims, and admin claims, and managing [[claim blocks]].

This page assumes you have read the general [[API]] introduction and that you have both imported HuskClaims into your project and added it as a dependency.

Table of Contents

• 1. Getting if a location is claimed
  • 1.1 Getting the ClaimWorld for a World
• 2. Checking what a user can do at a location
• 3. Editing claims
  • 3.1 Resizing & deleting claims
• 4. Checking & updating a user's claim blocks

1. Getting if a location is claimed

• On the Bukkit platform, get a Position object using #getPosition(org.bukkit.Location location)
• Use #isClaimAt(Position position) to check if the location has been claimed
• Or, use #getClaimAt(Position position) to get the Optional<Claim> at the location
  • With an Optional<Claim>, you can use Optional#isPresent() to check if a claim exists at the location
  • With a Claim object, you can also check if it's an admin claim (#isAdminClaim()) or a child claim (#isChildClaim(ClaimWorld)) — more on claim worlds in a bit!
• You can get the displayed name of who owns the claim using #getClaimOwnerNameAt(Position position), returning an Optional<String>
  • If the claim is an admin claim, the owner name will be an administrator (or whatever you have set in the locales)
• Check the [[Trust API]] for trusting users in a claim.

Example — Getting if a location is claimed

void showClaimerNameAt(org.bukkit.Location location) {
    Position position = huskClaims.getPosition(location);
    Optional<Claim> claim = huskClaims.getClaimAt(position);
    if (claim.isPresent()) {
        System.out.println("This location is claimed by " + huskClaims.getClaimOwnerNameAt(position).get());
    }
}

1.1 Getting the ClaimWorld for a World

• Claims exist within a ClaimWorld in HuskClaims. Worlds without ClaimWorlds are not protected by HuskClaims.
• On the Bukkit platform, get a World object from a Bukkit World using #getWorld(org.bukkit.World) (or call #getWorld() on a Position object)
• You can then get the ClaimWorld for a world using #getClaimWorld(World world) which will return an Optional<ClaimWorld>

Example — Getting the claim world for a world

void showClaimWorld(org.bukkit.World world) {
    Optional<ClaimWorld> claimWorld = huskClaims.getClaimWorld(world);
    if (claimWorld.isPresent()) {
        System.out.println("This world is protected by HuskClaims, and contains " + claimWorld().getClaimCount() + " claims!");
    }
}

2. Checking what a user can do at a location

• On the Bukkit platform, get an OnlineUser object using #getOnlineUser(@NotNull org.bukkit.Player player)
  • Use #getPosition() to get the Position of an OnlineUser to check if there's a claim where they stand (see #1)
• Check if a user can perform OperationTypes using isOperationAllowed(user, type, position)
  • Note that by default checks are not silent - the user will be informed if your check fails; there's no need to display a message yourself.
  • Use the #isOperationAllowed method that accepts and build an Operation via Operation.of() for more complex operation checks
• Additionally, we can check if a user has a TrustLevel.Privileges at a location using #isPrivilegeAllowed(TrustLevel.Privilege privilege, User user, Position position)
• Finally, we can also look up a user''s [[trust]] level in a claim using #getTrustLevelAt(Position position, Trustable user) (User and OnlineUser implement Trustable!)
  • This will return an Optional<TrustLevel>, which you can check if it is present using Optional#isPresent(), or through the #ifPresent((trustLevel) -> {}) lambda syntax.

Example — Checking what a user can do at a location

void checkUserAccessAt(org.bukkit.Player player, org.bukkit.Location location) {
    OnlineUser user = huskClaims.getOnlineUser(player);
    Position position = huskClaims.getPosition(location);
    if (huskClaims.isOperationAllowed(user, OperationType.BREAK_BLOCKS, position)) {
        System.out.println("User can build here!");
    }
    if (huskClaims.isOperationAllowed(Operation.of(user, OperationType.PLACE_BLOCKS, position, true))) {
        System.out.println("'true' sets this operation to be done silently.");
    }
    if (huskClaims.isPrivilegeAllowed(TrustLevel.Privilege.MANAGE_CHILD_CLAIMS, user, position)) {
        System.out.println("User can manage child claims here!");
    }
    huskClaims.getTrustLevelAt(position, user).ifPresent((level) -> {
        System.out.println("User has " + level.name() + " trust here!"); // "User has Build Trust here!"
    });
}

3. Editing claims

• Create a region using Region.from(BlockPosition pos1, BlockPosition pos2)
  • Position extends BlockPosition, so you can use Position objects for this
  • Or, get a BlockPosition using #getBlockPosition(x, z)
  • You can also create a region from a square radial selection using Region.from(BlockPosition center, int radius)
• Check if a region contains claims using #isRegionClaimed(World world, Region region) or #isRegionClaimed(ClaimWorld world, Region region)
• If not, create an admin claim using #createAdminClaim(ClaimWorld world, Region region)
  • This method returns a CompletableFuture<Claim>, which you can use to get the created claim when it has been created asynchronously
• You can also create regular claims through the API using #createClaim(ClaimWorld world, Region region, User user) — note that the user needs claim blocks for this (more on how to check/update this below)

Example — Creating an admin claim

void createAdminClaimAround(org.bukkit.Player player, org.bukkit.Location location) {
    OnlineUser user = huskClaims.getOnlineUser(player);
    Position position = huskClaims.getPosition(location);
    Region region = Region.from(position, 100); // Create a 100-block radius region around the player
    if (!huskClaims.isRegionClaimed(position.getWorld(), region)) {
        huskClaims.createAdminClaim(position.getWorld(), region).thenAccept((claim) -> {
            // This future will complete when the claim has been created
            System.out.println("Created admin claim at " + claim.getCenter().toString());
        }).exceptionally((e) -> { 
            // This future can also complete exceptionally if the claim could not be created
            System.out.println("Failed to create admin claim: " + e.getMessage());
            return null;
        }); 
    } else {
        System.out.println("This region is already claimed!");
    }
}

3.1 Resizing & deleting claims

• You can resize claims using #resizeClaim(Claim claim, Region region), or #resizeChildClaim(Claim claim, Region region) for child claims
  • These methods return a CompletableFuture<Claim>, which you can use to get the resized claim when it has been resized asynchronously
• You can delete claims using #deleteClaim(Claim claim), or #deleteChildClaim(Claim claim) for child claims

Example — Resizing a claim

void resizeClaim(org.bukkit.Player player, org.bukkit.Location location) {
    OnlineUser user = huskClaims.getOnlineUser(player);
    Position position = huskClaims.getPosition(location);
    Optional<Claim> claim = huskClaims.getClaimAt(position);
    if (claim.isPresent()) {
        Region region = Region.from(position, 100); // Create a 100-block radius region around the player
        if (huskClaims.isRegionClaimed(position.getWorld(), region)) {
            System.out.println("This region is already claimed!");
            return;
        }
        huskClaims.resizeClaim(claim.get(), region).thenAccept((resizedClaim) -> {
            // This future will complete when the claim has been resized
            System.out.println("Resized claim at " + resizedClaim.getCenter().toString());
        }).exceptionally((e) -> { 
            // This future can also complete exceptionally if the claim could not be resized
            System.out.println("Failed to resize claim: " + e.getMessage());
            return null;
        }); 
    } else {
        System.out.println("This region is not claimed!");
    }
}

4. Checking & updating a user's claim blocks

• You can get an OnlineUser's claim block balance using #getClaimBlocks(OnlineUser user)
  • For offline users, use the #getClaimBlocks(User user) or #getClaimBlocks(UUID uuid) methods which will return a CompletableFuture<Long> with their claim block count.
  • You can also quickly check if a user has enough claim blocks using #hasClaimBlocks(OnlineUser user, long amount)
• You can update a user's claim block balance using the #giveClaimBlocks, #takeClaimBlocks and #setClaimBlocks methods which accept a User and a long amount
• Note that these methods will fire the platform ClaimBlocksChangeEvent, which you can listen to for when a user's claim block balance changes
• Also note a player cannot have a negative claim block balance and #takeClaimBlocks will throw an IllegalArgumentException if you attempt to take more claim blocks than the user has

Example — Checking & updating a user's claim blocks

void giveClaimBlocks(org.bukkit.Player player, long amount) {
    OnlineUser user = huskClaims.getOnlineUser(player);
    if (huskClaims.hasClaimBlocks(user, amount)) {
        huskClaims.takeClaimBlocks(user, amount); // This will empty the user's claim block balance
        System.out.println("Took " + amount + " claim blocks from " + player.getName());
    } else {
        System.out.println(player.getName() + " does not have enough claim blocks!");
    }
}