HuskTowns

https://github.com/wiiiiam278/husktowns
Admin
HuskTowns is a simple, elegant, proxy-compatible Towny-style land protection plugin for Spigot-based...
Tokens:339,248
Snippets:1,658
Trust Score:9.9
License:Apache-2.0
Update:1 day ago
Show doc for...
Tokens:
Raw
### Example config.yml for HuskTowns

Source: https://github.com/wiiiiam278/husktowns/wiki/Config-Files

Full example configuration file for HuskTowns. Includes settings for language, database (SQLite/MySQL/MariaDB), cross-server messaging (plugin message or Redis), and general features such as claim map size, friendly fire, and hooks. Defaults include SQLite database, plugin message broker, and various enabled hooks.

```yaml
# ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
# ┃       HuskTowns Config       ┃
# ┃    Developed by William278   ┃
# ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
# ┣╸ Information: https://william278.net/project/husktowns
# ┣╸ Config Help: https://william278.net/docs/husktowns/config-files/
# ┗╸ Documentation: https://william278.net/docs/husktowns

# Locale of the default language file to use. Docs: https://william278.net/docs/husktowns/translations
language: en-gb
# Whether to automatically check for plugin updates on startup
check_for_updates: true
# Aliases to use for the /town command.
aliases:
  - t
# Database settings
database:
  # Type of database to use (SQLITE, MYSQL, MARIADB)
  type: SQLITE
  # Specify credentials here for your MYSQL or MARIADB database
  credentials:
    host: localhost
    port: 3306
    database: HuskTowns
    username: root
    password: pa55w0rd
    parameters: ?autoReconnect=true&useSSL=false&useUnicode=true&characterEncoding=UTF-8
  # MYSQL / MARIADB database Hikari connection pool properties. Don't modify this unless you know what you're doing!
  connection_pool:
    size: 10
    idle: 10
    lifetime: 1800000
    keepalive: 0
    timeout: 5000
  # Names of tables to use on your database. Don't modify this unless you know what you're doing!
  table_names:
    meta_data: husktowns_metadata
    claim_data: husktowns_claim_worlds
    user_data: husktowns_users
    town_data: husktowns_town_data
# Cross-server settings
cross_server:
  # Whether to enable cross-server mode
  enabled: false
  # The cluster ID, for if you're networking multiple separate groups of HuskTowns-enabled servers.
  # Do not change unless you know what you're doing
  cluster_id: main
  # Type of network message broker to ues for data synchronization (PLUGIN_MESSAGE or REDIS)
  broker_type: PLUGIN_MESSAGE
  # Settings for if you're using REDIS as your message broker
  redis:
    host: localhost
    port: 6379
    # Password for your Redis server. Leave blank if you're not using a password.
    password: ''
    use_ssl: false
    # Settings for if you're using Redis Sentinels.
    # If you're not sure what this is, please ignore this section.
    sentinel:
      master_name: ''
      # List of host:port pairs
      nodes: []
      password: ''
# Cross-server settings
general:
  # How many items should be displayed per-page in chat menu lists
  list_items_per_page: 6
  # Which item to use for the inspector tool; the item that displays claim information when right-clicked.
  inspector_tool: minecraft:stick
  # How far away the inspector tool can be used from a claim. (in blocks)
  max_inspection_distance: 80
  # The slot to display claim entry/teleportation notifications in. (ACTION_BAR, CHAT, TITLE, SUBTITLE, NONE)
  notification_slot: ACTION_BAR
  # The width and height of the claim map displayed in chat when running the /town map command.
  claim_map_width: 9
  claim_map_height: 9
  # Whether town spawns should be automatically created when a town's first claim is made.
  first_claim_auto_setspawn: false
  # Whether to allow players to attack other players in their town.
  allow_friendly_fire: false
  # A list of world names where claims cannot be created.
  unclaimable_worlds:
    - world_nether
    - world_the_end
  # A list of town names that cannot be used.
  prohibited_town_names:
    - Administrators
    - Moderators
    - Mods
    - Staff
    - Server
  # Adds special advancements for town progression. Docs: https://william278.net/docs/husktowns/advancements/
  do_advancements: false
  # Enable economy features. Requires Vault and a compatible economy plugin.If disabled, or if Vault is not installed, the built-in town points currency will be used instead.
  economy_hook: true
  # Hook with LuckPerms to provide town permission contexts. Docs: https://william278.net/docs/husktowns/hooks
  luckperms_contexts_hook: true
  # Hook with PlaceholderAPI to provide placeholders. Docs: https://william278.net/docs/husktowns/hooks
  placeholderapi_hook: true
  # Use HuskHomes for improved teleportation. Docs: https://william278.net/docs/husktowns/hooks
  huskhomes_hook: true
  # Show town information on your Player Analytics web panel. Docs: https://william278.net/docs/husktowns/hooks
  plan_hook: true

```

--------------------------------

### Get a town by name using HuskTownsAPI#getTown(String)

Source: https://github.com/wiiiiam278/husktowns/wiki/Towns-API

Retrieves a town by its name. Returns an Optional<Town> that is empty if no town exists with the given name. Use Optional#isPresent() to check and then get the Town object.

```java
void getTownByName(String townName) {
    Optional<Town> town = huskTowns.getTown(townName);
    if (town.isPresent()) {
        // Do something with the town
        Town townObject = town.get();
        System.out.println("Town name: " + townObject.getName());
    } else {
        System.out.println("No town found with the name " + townName);
    }
}
```

--------------------------------

### Get a user's town and role using HuskTownsAPI#getUserTown(User)

Source: https://github.com/wiiiiam278/husktowns/wiki/Towns-API

Retrieves the town membership of an online user. Returns an Optional<Member> that is empty if the user is not in a town. Use Member#town() and Member#role() to get the Town and Role objects.

```java
void showUserTownAndRole(org.bukkit.Player player) {
    OnlineUser user = huskTowns.getOnlineUser(player);
    Optional<Member> member = huskTowns.getUserTown(user);
    if (member.isPresent()) {
        Town town = member.get().town();
        Role role = member.get().role();
        System.out.println("User " + player.getName() + " is in the town " + town.getName() + " with the role " + role.getName());
    } else {
        System.out.println("User " + player.getName() + " is not in a town");
    }
}
```

--------------------------------

### plugin.yml example with HuskTowns softdepend

Source: https://github.com/wiiiiam278/husktowns/wiki/API

Add HuskTowns to your softdepend (or depend) section in plugin.yml to optionally or necessarily use the HuskTowns API.

```yaml
name: MyPlugin
version: 1.0
main: net.william278.myplugin.MyPlugin
author: William278
description: 'A plugin that hooks with the HuskTowns API!'
softdepend: # Or, use 'depend' here
  - HuskTowns
```

--------------------------------

### Example web_map_hook configuration

Source: https://github.com/wiiiiam278/husktowns/wiki/Config-Files

Configuration for enabling web map hooking (Dynmap, BlueMap, Pl3xMap). Set enabled to true and specify the marker set name for claims.

```yaml
# Show town information on your server Dynmap, BlueMap or Pl3xMap. Docs: https://william278.net/docs/husktowns/hooks
  web_map_hook:
    # Enable hooking into web map plugins
    enabled: true
    # The name of the marker set to use for claims on your web map
    marker_set_name: Claims
```

--------------------------------

### Example config for automatic pruning on startup

Source: https://github.com/wiiiiam278/husktowns/wiki/Inactive-Town-Pruning

Configuration snippet showing how to enable automatic pruning on startup by setting prune_on_startup to true and prune_after_days to 90. The prune_after_days setting has a minimum of 1 day.

```yaml
town_pruning:
  prune_on_startup: true
  prune_after_days: 90
```

--------------------------------

### Getting the claim world for a world

Source: https://github.com/wiiiiam278/husktowns/wiki/Claims-API

Use huskTowns.getClaimWorld(world) to get an Optional<ClaimWorld> for a Bukkit World. If present, the world is protected by HuskTowns and you can get the claim count with getClaimCount().

```java
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!");
    }
}
```

--------------------------------

### Get HuskTownsAPI instance

Source: https://github.com/wiiiiam278/husktowns/wiki/API

Shows how to obtain the HuskTownsAPI instance using HuskTownsAPI.getInstance() inside the hook constructor. For Bukkit, BukkitHuskTownsAPI#getBukkitInstance() is recommended for the extended API.

```java
import net.william278.husktowns.api.HuskTownsAPI;

public class HuskTownsAPIHook {

    private final HuskTownsAPI huskTownsAPI;

    public HuskTownsAPIHook() {
        this.huskTownsAPI = HuskTownsAPI.getInstance();
    }

}
```

--------------------------------

### getWorld(org.bukkit.World)

Source: https://github.com/wiiiiam278/husktowns/wiki/Claims-API

Gets the HuskTowns World object for a Bukkit World.

```APIDOC
## getWorld(org.bukkit.World)

### Description
Gets the HuskTowns World object for a Bukkit World.

### Method
`World getWorld(org.bukkit.World world)`

### Parameters
- **world** (org.bukkit.World) - Required - The Bukkit world.

### Returns
- **World** - The HuskTowns World object.

### Example
```java
World world = huskTowns.getWorld(bukkitWorld);
```
```

--------------------------------

### Create a town with huskTowns.createTown()

Source: https://github.com/wiiiiam278/husktowns/wiki/Towns-API

Example of creating a town asynchronously. The method returns a CompletableFuture<Town> that completes with the new town on success, or exceptionally if the town already exists. Handle the exception case as shown.

```java
void createTown(String townName, org.bukkit.Player player) {
    OnlineUser online = huskTowns.getOnlineUser(player);
    CompletableFuture<Town> future = huskTowns.createTown(townName, online);
    future.thenAccept(town -> {
        System.out.println("Town created: " + town.getName());
    }).exceptionally(throwable -> {
        System.out.println("Failed to create town: " + throwable.getMessage());
        return null;
    });
}
```

--------------------------------

### Delete a town with huskTowns.deleteTown()

Source: https://github.com/wiiiiam278/husktowns/wiki/Towns-API

Example of deleting a town. This also deletes all claims and data associated with the town.

```java
void deleteTown(String townName, org.bukkit.Player player) {
    OnlineUser online = huskTowns.getOnlineUser(player);
    huskTowns.deleteTown(townName, online);
}
```

--------------------------------

### roles.yml - Town Roles and Privileges

Source: https://github.com/wiiiiam278/husktowns/wiki/Config-Files

Example roles.yml configuration for HuskTowns. Maps role weight IDs to display names and privileges. Roles are Resident, Trustee, and Mayor with associated permissions.

```yaml
# ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
# ┃  HuskTowns town role config  ┃
# ┃    Developed by William278   ┃
# ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
# ┣╸ This file is for configuring town roles and associated privileges.
# ┣╸ Each role is mapped to a weight, identifying its hierarchical position. Each weight is also mapped to the role name.
# ┣╸ Config Help: https://william278.net/docs/husktowns/config-files
# ┗╸ Documentation: https://william278.net/docs/husktowns/roles

# Map of role weight IDs to display names
names:
  '1': Resident
  '2': Trustee
  '3': Mayor
# Map of role weight IDs to privileges
roles:
  '1':
    - deposit
    - chat
    - claim_plot
    - spawn
  '2':
    - set_farm
    - set_plot
    - manage_plot_members
    - trusted_access
    - unclaim
    - claim
    - set_greeting
    - set_farewell
    - invite
    - set_spawn
    - manage_relations
    - spawn_privacy
    - view_logs
  '3':
    - set_bio
    - evict
    - promote
    - demote
    - withdraw
    - level_up
    - set_rules
    - rename
    - set_color
    - declare_war

```

--------------------------------

### Getting if a location is claimed

Source: https://github.com/wiiiiam278/husktowns/wiki/Claims-API

Use huskTowns.getPosition(location) to convert a Bukkit Location to a Position, then getClaimAt(position) to get an Optional<TownClaim>. Check isPresent() to see if the location is claimed, and use town().getName() to get the town name.

```java
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());
    }
}
```

--------------------------------

### getClaimWorld(World)

Source: https://github.com/wiiiiam278/husktowns/wiki/Claims-API

Gets the ClaimWorld for a HuskTowns World, if it exists.

```APIDOC
## getClaimWorld(World)

### Description
Gets the ClaimWorld for a HuskTowns World, if it exists.

### Method
`Optional<ClaimWorld> getClaimWorld(World world)`

### Parameters
- **world** (World) - Required - The HuskTowns World object.

### Returns
- **Optional<ClaimWorld>** - An Optional containing the ClaimWorld if present, otherwise empty.

### Example
```java
Optional<ClaimWorld> claimWorld = huskTowns.getClaimWorld(world);
if (claimWorld.isPresent()) {
    System.out.println("This world is protected by HuskTowns, and contains " + claimWorld.get().getClaimCount() + " claims!");
}
```
```

--------------------------------

### Highlight a claim at a position

Source: https://github.com/wiiiiam278/husktowns/wiki/Claims-API

Highlights a claim for a user by displaying a particle outline. It retrieves the claim at the given position and calls highlightClaim if present. The example checks if the claim exists before highlighting.

```java
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());
    }
}
```

--------------------------------

### Create a claim at a chunk

Source: https://github.com/wiiiiam278/husktowns/wiki/Claims-API

Creates a claim for a town at the specified chunk and world. Requires an OnlineUser, a Town (obtained via getTown), and the chunk/world. The example uses a town name "townName" and assumes the town exists.

```java
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);
}
```

--------------------------------

### Check if a user can create claims using HuskTownsAPI#isPrivilegeAllowed(Privilege, User)

Source: https://github.com/wiiiiam278/husktowns/wiki/Towns-API

Checks whether a user has a specific privilege. Returns true if allowed, false otherwise. This example checks the CLAIM privilege for an online player.

```java
void showCanCreateTownClaims(org.bukkit.Player player) {
    boolean allowed = huskTowns.isPrivilegeAllowed(Privilege.CLAIM, huskTowns.getOnlineUser(player));
    if (allowed) {
        System.out.println("User " + player.getName() + " can create claims");
    } else {
        System.out.println("User " + player.getName() + " cannot create claims");
    }
}
```

--------------------------------

### TownWarCreateEvent

Source: https://github.com/wiiiiam278/husktowns/wiki/API-Events

Called when a town war starts. Not cancellable.

```APIDOC
## TownWarCreateEvent

### Description
Called when a town war starts.

### Event Class
`TownWarCreateEvent`

### Since
3.0.6

### Cancellable
No

```

--------------------------------

### levels.yml - Town Level Requirements and Rewards

Source: https://github.com/wiiiiam278/husktowns/wiki/Config-Files

Example levels.yml configuration for HuskTowns. Defines money requirements, member limits, claim limits, and bonus rates for town levels 1-20. The Level 1 cost is used to create a town if require_first_level_collateral is enabled in config.yml.

```yaml
# ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
# ┃    HuskTowns Levels Config   ┃
# ┃    Developed by William278   ┃
# ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
# ┣╸ This file is for configuring town level requirements and rewards
# ┗╸ Config Help: https://william278.net/docs/husktowns/config-files

# The amount of money required to level up towns. The Level 1 cost will be taken to create a town if require_first_level_collateral is enabled in config.yml.
level_money_requirements:
  '1': 2000.0
  '2': 4000.0
  '3': 8000.0
  '4': 16000.0
  '5': 32000.0
  '6': 64000.0
  '7': 128000.0
  '8': 256000.0
  '9': 512000.0
  '10': 1024000.0
  '11': 2048000.0
  '12': 4096000.0
  '13': 8192000.0
  '14': 1.6384E7
  '15': 3.2768E7
  '16': 6.5536E7
  '17': 1.31072E8
  '18': 2.62144E8
  '19': 5.24288E8
  '20': 1.048576E9
# The maximum number of members a town can have at each level
level_member_limits:
  '1': 5
  '2': 10
  '3': 15
  '4': 20
  '5': 25
  '6': 30
  '7': 35
  '8': 40
  '9': 45
  '10': 50
  '11': 55
  '12': 60
  '13': 65
  '14': 70
  '15': 75
  '16': 80
  '17': 85
  '18': 90
  '19': 95
  '20': 100
# The maximum number of claims a town can have at each level
level_claim_limits:
  '1': 6
  '2': 12
  '3': 18
  '4': 24
  '5': 30
  '6': 36
  '7': 42
  '8': 48
  '9': 54
  '10': 60
  '11': 66
  '12': 72
  '13': 78
  '14': 84
  '15': 90
  '16': 96
  '17': 102
  '18': 108
  '19': 114
  '20': 120
# The bonus crop growth rate percentage a town has at each level (e.g. 105 is 5% faster crop growth)
level_crop_growth_rate_bonus:
  '1': 105.0
  '2': 110.0
  '3': 115.0
  '4': 120.0
  '5': 125.0
  '6': 130.0
  '7': 135.0
  '8': 140.0
  '9': 145.0
  '10': 150.0
  '11': 155.0
  '12': 160.0
  '13': 165.0
  '14': 170.0
  '15': 175.0
  '16': 180.0
  '17': 185.0
  '18': 190.0
  '19': 195.0
  '20': 200.0
# The bonus mob spawner rate percentage a town has at each level
level_mob_spawner_rate_bonus:
  '1': 102.5
  '2': 105.0
  '3': 107.5
  '4': 110.0
  '5': 112.5
  '6': 115.0
  '7': 117.5
  '8': 120.0
  '9': 122.5
  '10': 125.0
  '11': 127.5
  '12': 130.0
  '13': 132.5
  '14': 135.0
  '15': 137.5
  '16': 140.0
  '17': 142.5
  '18': 145.0
  '19': 147.5
  '20': 150.0

```

--------------------------------

### Default roles.yml configuration

Source: https://github.com/wiiiiam278/husktowns/wiki/Roles

Defines the default town roles (Mayor, Trustee, Resident) with their weight IDs and associated privileges. This is the default setup; you can customize role names and privileges, but the weightings are stored in the database and cannot be changed without a data reset.

```yaml
# ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
# ┃  HuskTowns town role config  ┃
# ┃    Developed by William278   ┃
# ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
# ┣╸ This file is for configuring town roles and associated privileges.
# ┣╸ Each role is mapped to a weight, identifying its hierarchical position. Each weight is also mapped to the role name.
# ┣╸ Config Help: https://william278.net/docs/husktowns/config-files
# ┗╸ Documentation: https://william278.net/docs/husktowns/town-roles
# Map of role weight IDs to display names
names:
  '3': Mayor
  '2': Trustee
  '1': Resident
# Map of role weight IDs to privileges
roles:
  '3':
  - set_bio
  - evict
  - promote
  - demote
  - withdraw
  - level_up
  - set_rules
  - rename
  - set_color
  - declare_war
  '2':
  - set_farm
  - set_plot
  - manage_plot_members
  - trusted_access
  - unclaim
  - claim
  - set_greeting
  - set_farewell
  - invite
  - set_spawn
  - manage_relations
  - spawn_privacy
  - view_logs
  '1':
  - deposit
  - chat
  - claim_plot
  - spawn

```

--------------------------------

### getClaimAt(Position)

Source: https://github.com/wiiiiam278/husktowns/wiki/Claims-API

Gets the Optional<TownClaim> at a location, if any.

```APIDOC
## getClaimAt(Position)

### Description
Gets the Optional<TownClaim> at a location, if any.

### Method
`Optional<TownClaim> getClaimAt(Position position)`

### Parameters
- **position** (Position) - Required - The position to query.

### Returns
- **Optional<TownClaim>** - An Optional containing the TownClaim if present, otherwise empty.

### Example
```java
Optional<TownClaim> claim = huskTowns.getClaimAt(position);
if (claim.isPresent()) {
    System.out.println("This location is claimed by " + claim.get().town().getName());
}
```
```

--------------------------------

### getTown(String name)

Source: https://github.com/wiiiiam278/husktowns/wiki/Towns-API

Gets a town by its name. Returns an Optional<Town> that is empty if no town exists with the given name.

```APIDOC
## getTown(String name)

### Description
Gets a town by its name. Returns an Optional<Town> that is empty if no town exists with the given name.

### Method
`Optional<Town> getTown(String name)`

### Parameters
- **name** (String) - Required - The name of the town to retrieve.

### Returns
- `Optional<Town>` - The town if found, otherwise empty.

### Example
```java
void getTownByName(String townName) {
    Optional<Town> town = huskTowns.getTown(townName);
    if (town.isPresent()) {
        // Do something with the town
        Town townObject = town.get();
        System.out.println("Town name: " + townObject.getName());
    } else {
        System.out.println("No town found with the name " + townName);
    }
}
```
```

--------------------------------

### Create HuskTownsAPIHook class

Source: https://github.com/wiiiiam278/husktowns/wiki/API

Defines a simple HuskTownsAPIHook class to interface with the HuskTowns API. Recommended to keep API calls out of the main plugin class to avoid ClassNotFoundException if HuskTowns is not installed.

```java
public class HuskTownsAPIHook {

    public HuskTownsAPIHook() {
        // Ready to do stuff with the API
    }

}
```

--------------------------------

### getUserTown(User user)

Source: https://github.com/wiiiiam278/husktowns/wiki/Towns-API

Gets the town membership of a user. Returns an Optional<Member> that is empty if the user is not in a town.

```APIDOC
## getUserTown(User user)

### Description
Gets the town membership of a user. Returns an Optional<Member> that is empty if the user is not in a town.

### Method
`Optional<Member> getUserTown(User user)`

### Parameters
- **user** (User) - Required - The user whose town membership to retrieve.

### Returns
- `Optional<Member>` - The member object if the user is in a town, otherwise empty.

### Member Methods
- `Member#town()` - Returns the `Town` object.
- `Member#role()` - Returns the user's `Role` in the town.

### Example
```java
void showUserTownAndRole(org.bukkit.Player player) {
    OnlineUser user = huskTowns.getOnlineUser(player);
    Optional<Member> member = huskTowns.getUserTown(user);
    if (member.isPresent()) {
        Town town = member.get().town();
        Role role = member.get().role();
        System.out.println("User " + player.getName() + " is in the town " + town.getName() + " with the role " + role.getName());
    } else {
        System.out.println("User " + player.getName() + " is not in a town");
    }
}
```
```

--------------------------------

### Edit a claim type

Source: https://github.com/wiiiiam278/husktowns/wiki/Claims-API

Edits an existing claim at a chunk and world using a Consumer<TownClaim>. The example changes the claim type to FARM. The consumer receives the TownClaim object to modify.

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

--------------------------------

### Delete a claim at a position

Source: https://github.com/wiiiiam278/husktowns/wiki/Claims-API

Deletes a claim at the given position. Requires an OnlineUser and a Position. The example converts a player and location to the required objects and calls deleteClaimAt.

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

--------------------------------

### Check user operation permission at a location

Source: https://github.com/wiiiiam278/husktowns/wiki/Claims-API

Use this to determine if a user can perform a specific operation (e.g., breaking blocks) at a given location. It retrieves the OnlineUser and Position, then calls isOperationAllowed. The example prints a message based on the result.

```java
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!");
    }
}
```

--------------------------------

### Edit a town with editTown(OnlineUser, String, Consumer<Town>)

Source: https://github.com/wiiiiam278/husktowns/wiki/Towns-API

Use this method to modify a town in a single action. Requires an OnlineUser actor, which can be obtained via huskTowns.getOnlineUser(player) on the Bukkit platform. The example sets the town's greeting and farewell messages.

```java
void editTown(String townName, org.bukkit.Player player) {
    OnlineUser online = huskTowns.getOnlineUser(player);
    huskTowns.editTown(online, townName, town -> {
        town.setGreeting("Welcome to our town!");
        town.setFarewell("Goodbye!");
    });
}
```

--------------------------------

### Build HuskTowns with Gradle

Source: https://github.com/wiiiiam278/husktowns/blob/master/README.md

Run this command in the repository root to build the HuskTowns plugin. It executes the Gradle wrapper's clean and build tasks.

```bash
./gradlew clean build
```

--------------------------------

### createTown(String name, OnlineUser user)

Source: https://github.com/wiiiiam278/husktowns/wiki/Towns-API

Creates a new town with the specified name and user. Returns a CompletableFuture that completes with the new Town if successful, or exceptionally if the town could not be created (e.g., name already exists).

```APIDOC
## createTown(String name, OnlineUser user)

### Description
Creates a new town with the specified name and user. Returns a CompletableFuture that completes with the new Town if successful, or exceptionally if the town could not be created (e.g., name already exists).

### Method
createTown

### Parameters
- **name** (String) - Required - The name of the town to create.
- **user** (OnlineUser) - Required - The user who is creating the town.

### Returns
CompletableFuture<Town> - Completes with the new Town if created successfully, or completes exceptionally if creation fails.

### Example
```java
void createTown(String townName, org.bukkit.Player player) {
    OnlineUser online = huskTowns.getOnlineUser(player);
    CompletableFuture<Town> future = huskTowns.createTown(townName, online);
    future.thenAccept(town -> {
        System.out.println("Town created: " + town.getName());
    }).exceptionally(throwable -> {
        System.out.println("Failed to create town: " + throwable.getMessage());
        return null;
    });
}
```
```

--------------------------------

### Getting the OperationTypeRegistry

Source: https://github.com/wiiiiam278/husktowns/wiki/Operations-API

Retrieves the OperationTypeRegistry instance from HuskTowns. This is the entry point for accessing registered OperationTypes and the Handler class.

```java
void getRegistry() {
    final OperationTypeRegistry reg = HuskTowns.getOperationTypeRegistry();
}
```

--------------------------------

### createClaimAt(OnlineUser actor, Town town, Chunk chunk, World world)

Source: https://github.com/wiiiiam278/husktowns/wiki/Claims-API

Creates a claim for a town at the specified chunk and world. This is the primary method for creating new claims.

```APIDOC
## createClaimAt(OnlineUser actor, Town town, Chunk chunk, World world)

### Description
Creates a claim for a town at the specified chunk and world. This is the primary method for creating new claims.

### Method
Java Method

### Endpoint
`#createClaimAt(OnlineUser actor, Town town, Chunk chunk, World world)`

### Parameters
- **actor** (OnlineUser) - Required - The user creating the claim.
- **town** (Town) - Required - The town that the claim will belong to.
- **chunk** (Chunk) - Required - The chunk to claim.
- **world** (World) - Required - The world of the chunk.

### Example
```java
huskTowns.createClaimAt(user, town, chunk, world);
```
```

--------------------------------

### createClaimAt

Source: https://github.com/wiiiiam278/husktowns/blob/master/docs/Claims-API.md

Creates a new claim at a specified chunk and world for a given town. An admin claim variant is also available.

```APIDOC
## createClaimAt

### Description
Creates a new claim at a specified chunk and world for a given town. An admin claim variant is also available.

### Method
createClaimAt

### Endpoint
#createClaimAt(OnlineUser actor, Town town, Chunk chunk, World world)

### Parameters
#### Parameters
- **actor** (OnlineUser) - Required - The user creating the claim.
- **town** (Town) - Required - The town the claim is being created for.
- **chunk** (Chunk) - Required - The chunk to claim.
- **world** (World) - Required - The world of the chunk.

### Request Example
```java
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);
}
```

### Response
#### Success Response
- **void** - This method does not return a value.
```

--------------------------------

### Configure claim inspection tool in config.yml

Source: https://github.com/wiiiiam278/husktowns/wiki/Claims

Sets the item used to inspect claims. The default is minecraft:stick, changeable to any Minecraft item ID.

```yaml
general:
  # Change this to a different Minecraft item ID if you wish.
  inspector_tool: minecraft:stick
```

--------------------------------

### rules.yml - Rule Presets Configuration

Source: https://github.com/wiiiiam278/husktowns/wiki/Config-Files

Defines default flag rules for towns and public rules outside towns. Includes presets for wilderness, admin claims, unclaimable worlds, wartime, and default rules for claim types (claims, farms, plots).

```yaml
# ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
# ┃    HuskTowns Rule Presets    ┃
# ┃    Developed by William278   ┃
# ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
# ┣╸ This file is for configuring the default flag rule rulePresets within towns and the public rules outside of towns.
# ┗╸ Config Help: https://william278.net/docs/husktowns/config-files

# Rules for the wilderness (claimable chunks outside of towns)
wilderness_rules:
  public_farm_access: true
  explosion_damage: true
  pvp: true
  monster_spawning: true
  public_build_access: true
  public_interact_access: true
  public_container_access: true
  fire_damage: true
  mob_griefing: true
# Rules for admin claims (created with /admintown claim)
admin_claim_rules:
  public_farm_access: true
  explosion_damage: false
  pvp: false
  monster_spawning: false
  public_build_access: false
  public_interact_access: true
  public_container_access: false
  fire_damage: false
  mob_griefing: false
# Rules for worlds where claims cannot be created (as defined in unclaimable_worlds)
unclaimable_world_rules:
  public_farm_access: true
  explosion_damage: true
  pvp: true
  monster_spawning: true
  public_build_access: true
  public_interact_access: true
  public_container_access: true
  fire_damage: true
  mob_griefing: true
# Default rules when a town is at war (only used during a town war)
wartime_rules:
  public_farm_access: true
  explosion_damage: true
  pvp: true
  monster_spawning: true
  public_build_access: true
  public_interact_access: true
  public_container_access: true
  fire_damage: true
  mob_griefing: true
# The default rules for different town claim types
default_rules:
  # Default rules for normal claims
  claims:
    public_farm_access: false
    explosion_damage: false
    pvp: false
    monster_spawning: true
    public_build_access: false
    public_interact_access: false
    public_container_access: false
    fire_damage: false
    mob_griefing: false
  # Default rules for farm claims
  farms:
    public_farm_access: true
    explosion_damage: false
    pvp: false
    monster_spawning: true
    public_build_access: false
    public_interact_access: false
    public_container_access: false
    fire_damage: false
    mob_griefing: false
  # Default rules for plot claims
  plots:
    public_farm_access: false
    explosion_damage: false
    pvp: false
    monster_spawning: false
    public_build_access: false
    public_interact_access: false
    public_container_access: false
    fire_damage: false
    mob_griefing: false

```

--------------------------------

### Gradle repository configuration for HuskTowns API

Source: https://github.com/wiiiiam278/husktowns/wiki/API

Add the repository to your build.gradle to use the HuskTowns API. You can alternatively specify /snapshots for the repository containing the latest development builds (not recommended).

```groovy
allprojects {
	repositories {
		maven { url 'https://repo.william278.net/releases' }
	}
}
```

--------------------------------

### MemberJoinEvent

Source: https://github.com/wiiiiam278/husktowns/wiki/API-Events

Called when a player joins a town. Cancellable.

```APIDOC
## MemberJoinEvent

### Description
Called when a player joins a town.

### Event Class
`MemberJoinEvent`

### Since
2.0

### Cancellable
Yes

```

--------------------------------

### Checking if Operations are allowed with Handler

Source: https://github.com/wiiiiam278/husktowns/wiki/Operations-API

Uses the Handler to cancel an Operation with a custom OperationType. The cancelOperation method returns a boolean indicating whether the operation should be allowed. The example shows how to check the result and conditionally continue logic.

```java
private OperationType releaseMonOpType;

void onMonReleased(Player bukkitPlayer, Location releasedAt) {
  final OperationTypeRegistry reg = HuskTowns.getOperationTypeRegistry();
  final boolean cancelled = reg.getHandler().cancelOperation(Operation.of(
        HuskTowns.getPlayer(bukkitPlayer), // OnlineUser implements OperationUser
        releaseMonOpType,
        HuskTowns.getPosition(releasedAt) // Position implements OperationPosition
    ));
    if (cancelled) {
        // Don't continue with the action
        return;
    }
    // Logic would continue if the operation wasn't cancelled...
}
```

--------------------------------

### createAdminClaimAt(OnlineUser actor, Chunk chunk, World world)

Source: https://github.com/wiiiiam278/husktowns/wiki/Claims-API

Creates an admin claim at the specified chunk and world. Admin claims are typically used for special areas.

```APIDOC
## createAdminClaimAt(OnlineUser actor, Chunk chunk, World world)

### Description
Creates an admin claim at the specified chunk and world. Admin claims are typically used for special areas.

### Method
Java Method

### Endpoint
`#createAdminClaimAt(OnlineUser actor, Chunk chunk, World world)`

### Parameters
- **actor** (OnlineUser) - Required - The user creating the admin claim.
- **chunk** (Chunk) - Required - The chunk to claim.
- **world** (World) - Required - The world of the chunk.

### Example
```java
huskTowns.createAdminClaimAt(user, chunk, world);
```
```

--------------------------------

### Maven repository configuration for HuskTowns API

Source: https://github.com/wiiiiam278/husktowns/wiki/API

Add the repository to your pom.xml to use the HuskTowns API. You can alternatively specify /snapshots for the repository containing the latest development builds (not recommended).

```xml
<repositories>
    <repository>
        <id>william278.net</id>
        <url>https://repo.william278.net/releases</url>
    </repository>
</repositories>
```

--------------------------------

### Default Wartime Town Rules (rules.yml)

Source: https://github.com/wiiiiam278/husktowns/wiki/Wars

YAML configuration for wartime town rules, used only during a town war. By default, these rules permit PvP and enable various interactions and events. Configure in the rules.yml file.

```yaml
# Default rules when a town is at war (only used during a town war)
wartime_rules:
  public_interact_access: true
  public_build_access: true
  monster_spawning: true
  pvp: true
  explosion_damage: true
  public_farm_access: true
  mob_griefing: true
  fire_damage: true
  public_container_access: true
```

--------------------------------

### Database options in config.yml

Source: https://github.com/wiiiiam278/husktowns/wiki/Database

YAML configuration for the HuskTowns database. Set the type to SQLITE, MYSQL, or MARIADB. For MySQL/MariaDB, provide credentials and optionally adjust HikariCP connection pool properties.

```yaml
database:
  # Type of database to use (SQLITE, MYSQL or MARIADB)
  type: SQLITE
  mysql:
    credentials:
      # Specify credentials here if you are using MYSQL or MARIADB as your database type
      host: localhost
      port: 3306
      database: HuskTowns
      username: root
      password: pa55w0rd
      parameters: ?autoReconnect=true&useSSL=false&useUnicode=true&characterEncoding=UTF-8
    connection_pool:
      # MYSQL database Hikari connection pool properties. Don't modify this unless you know what you're doing!
      size: 10
      idle: 10
      lifetime: 1800000
      keepalive: 30000
      timeout: 20000
```

--------------------------------

### Town Wars Configuration (config.yml)

Source: https://github.com/wiiiiam278/husktowns/wiki/Wars

YAML configuration block for town wars, placed under the 'relations' section in config.yml. Includes settings for enabling wars, cooldown hours, declaration expiry, minimum wager, boss bar color, required online membership percentage, and war zone radius.

```yaml
wars:
    # Allow mutual enemy towns to agree to go to war. Requires town relations to be enabled. Wars consist of a battle between members, to take place at the spawn of the defending townDocs: https://william278.net/docs/husktowns/town-wars/
    enabled: false
    # The number of hours before a town can be involved with another war after finishing one
    cooldown: 48
    # How long before pending declarations of war expire
    declaration_expiry: 10
    # The minimum wager for a war. This is the amount of money each town must pay to participate in a war. The winner of the war will receive both wagers.
    minimum_wager: 5000.0
    # The color of the boss bar displayed during a war
    boss_bar_color: RED
    # The minimum number of members online in a town for it to be able to participate in a war (%).
    required_online_membership: 50.0
    # The radius around the defending town's spawn, in blocks, where battle can take place. (Min: 16)
    war_zone_radius: 128
```
Tokens:
Raw