Claims API

HuskTowns provides API for getting, creating, changing the type of, & deleting claims and admin claims.

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

Table of contents

1. Getting if a location is claimed
   1. Getting the ClaimWorld for a World
2. Checking what a user can do at a location
3. Creating a claim
   1. Editing a claim
   2. Deleting a claim
4. Highlighting a claim

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<TownClaim> at the location
  • With an Optional<TownClaim>, you can use Optional#isPresent() to check if a claim exists at the location
  • With a TownClaim object, you can get the associated Town object (see Towns API) using #town(), and the Claim itself using #claim()
  • The Claim object has a range of properties describing the claim.

Example — Getting if a location is claimed

void showTownWhoHasClaimedAt(org.bukkit.Location location) {
    Position position = huskTowns.getPosition(location);
    Optional<TownClaim> claim = huskTowns.getClaimAt(position);
    if (claim.isPresent()) {
        System.out.println("This location is claimed by " + claim.get().town().getName());
    }
}

1.1 Getting the ClaimWorld for a World

• Claims exist within a ClaimWorld in HuskTowns. Worlds without ClaimWorlds are not protected by HuskTowns.
• 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 = huskTowns.getClaimWorld(world);
    if (claimWorld.isPresent()) {
        System.out.println("This world is protected by HuskTowns, and contains " + claimWorld.get().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(OnlineUser user, OperationType type, Position position)
  • Use the #isOperationAllowed method that accepts and build an Operation via Operation.builder() for more complex operation checks!

Example — Checking what a user can do at a location

void checkUserAccessAt(org.bukkit.Player player, org.bukkit.Location location) {
    OnlineUser user = huskTowns.getOnlineUser(player);
    Position position = huskTowns.getPosition(location);
    if (huskTowns.isOperationAllowed(user, OperationType.BREAK_BLOCKS, position)) {
        System.out.println("User can build here!");
    } else {
        System.out.println("User can't build here!");
    }
}

3. Creating a claim

• You can create a claim using #createClaimAt(OnlineUser actor, Town town, Chunk chunk, World world)
  • You may also create an admin claim using #createAdminClaimAt(OnlineUser actor, Chunk chunk, World world)
• This will create a claim at that position. You can then use #getClaimAt(Position position) to get the TownClaim object for the claim you just created (see #1)
• You can also create a claim at the chunk at a position using #createClaimAt(OnlineUser actor, Town town, Position position)

Example — Creating a claim

void createClaimAt(org.bukkit.Player player, org.bukkit.Chunk chunk, org.bukkit.World world) {
    OnlineUser user = huskTowns.getOnlineUser(player);
    Town town = huskTowns.getTown("townName").get();
    huskTowns.createClaimAt(user, town, chunk, world);
}

3.1 Editing a claim

• You can edit a claim using #editClaimAt(Chunk chunk, World world, Consumer<TownClaim> editor)
• This will allow you to edit the claim at the given chunk and world using the Consumer<TownClaim> to modify the TownClaim object
  • For example, you can do townClaim.claim().setType(Claim.Type type) to change the type of the claim

Example — Editing a claim

void editClaimAt(org.bukkit.Chunk chunk, org.bukkit.World world) {
    huskTowns.editClaimAt(chunk, world, townClaim -> {
        townClaim.claim().setType(Claim.Type.FARM);
    });
}

3.2 Deleting a claim

• You can delete a claim using #deleteClaimAt(OnlineUser actor, Position position)
  • A method that accepts a Chunk and a World is also available

Example — Deleting a claim

void deleteClaimAt(org.bukkit.Player player, org.bukkit.Location location) {
    OnlineUser user = huskTowns.getOnlineUser(player);
    Position position = huskTowns.getPosition(location);
    huskTowns.deleteClaimAt(user, position);
}

4. Highlighting a claim

• You can "highlight" a claim for an OnlineUser (displaying the outline particle effect) using #highlightClaim(OnlineUser actor, TownClaim claim)
• You may additionally specify the duration, and use #highlightClaimAt to attempt to highlight a claim at a specified Position

Example — Highlighting a claim

void highlightClaimAt(org.bukkit.Player player, org.bukkit.Location location) {
    OnlineUser user = huskTowns.getOnlineUser(player);
    Position position = huskTowns.getPosition(location);
    Optional<TownClaim> claim = huskTowns.getClaimAt(position);
    if (claim.isPresent()) {
        huskTowns.highlightClaim(user, claim.get());
    }
}