API

HuskTowns banner

HuskTowns API v1

The HuskTowns API provides methods to get data from HuskTowns directly.

The API accesses cached data and can be used to check for things such as players being able to build on certain chunks, etc. This page contains how to use the API and provides example usages for developers.

Table of Contents

Getting the API

HuskTownsAPI is available from JitPack.

Gradle

Add the JitPack repository in your root build.gradle at the end of repositories:

	allprojects {
		repositories {
			maven { url 'https://jitpack.io' }
		}
	}

Add the dependency, replacing Tag with the latest version of HuskTowns

	dependencies {
	        implementation 'net.william278:HuskTowns:Tag'
	}

Maven

Add the JitPack repository to your pom.xml

	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Add the dependency, replacing Tag with the latest version of HuskTowns

	<dependency>
	    <groupId>net.william278</groupId>
	    <artifactId>HuskTowns</artifactId>
	    <version>Tag</version>
	</dependency>

HuskTownsAPI.getInstance()

Once you have added the API dependency, you can get an instance of it using HuskTownsAPI.getInstance(). This is the entrypoint for utilising the various methods, which you can look at on the Javadoc.

Using the API

Check if a location or block is in the wilderness

Method

/**
* Check if the specified {@link Block} is in the wilderness (outside of a claim).
* @param block {@link Block} to check.
* @return true if the {@link Block} is in the wilderness; otherwise return false.
*/
boolean isWilderness = HuskTownsAPI.getInstance().isWilderness(Block block);

or

/**
* Check if the specified {@link Location} is in the wilderness (outside of a claim).
* @param location {@link Location} to check.
* @return true if the {@link Location} is in the wilderness; otherwise return false.
*/
boolean isWilderness = HuskTownsAPI.getInstance().isWilderness(Location location);

Example

Location location = player.getLocation();
if (isWilderness(location)) {
  player.sendMessage("In wilderness");
} else {
  player.sendMessage("In a claim");
}

Get the name of a town at a location

Method

/**
* Returns the name of the town at the specified {@link Location}.
* @param location {@link Location} to check.
* @return the name of the town who has a claim at the specified {@link Location}; null if there is no claim there.
*/
String town = HuskTownsAPI.getInstance().getTownAt(Location location);

Example

String townName = HuskTownsAPI.getInstance().getTownAt(player.getLocation());
if (townName == null) {
  player.sendMessage("In wilderness")
} else {
  player.sendMessage("You're standing in " + townName)
}

Get whether a player is in a town

Method

/**
* Returns true if the {@link Player} is in a town; false if not.
* @param player {@link Player} to check.
* @return true if the {@link Player} is in a town; false otherwise.
*/
boolean inTown = HuskTownsAPI.getInstance().isInTown(Player player);

Example

boolean inTown = HuskTownsAPI.getInstance().isInTown(player);
if (inTown) {
  player.sendMessage("You're a member of a town")
} else {
  player.sendMessage("You're not a member of a town")
}

Get the name of a town a player is in

Method

/**
* Returns the name of the town the {@link Player} is currently in; null if they are not in a town
* @param player {@link Player} to check.
* @return the name of the town the {@link Player} is currently in; null if they are not in a town.
*/
String town = HuskTownsAPI.getInstance().getPlayerTown(Player player);

Example

String townName = HuskTownsAPI.getInstance().getPlayerTown(player);
if (townName == null) {
  player.sendMessage("You're not in a town")
} else {
  player.sendMessage("You're a member of " + townName)
}

Get whether the player can build at a location. There are also methods for checking if a player can open containers / interact with the environment.

Method

/**
* Returns whether or not the specified {@link Player} can build at the specified {@link Location}.
* @param player {@link Player} to check.
* @param location {@link Location} to check.
* @return true if the player can build at the specified {@link Location}; false otherwise.
*/
boolean canBuild = HuskTownsAPI.getInstance().canBuild(Player player, Location location);

Example

boolean canBuild = HuskTownsAPI.getInstance().canBuild(player, player.getLocation());
if (canBuild) {
  player.sendMessage("You can build here!")
} else {
  player.sendMessage("You don't have access to build here.")
}

Get a list of all the town names

Method

/**
* Get a list of the names of all towns
* @return A HashSet of all town names
*/
HashSet<String>  towns = HuskTownsAPI.getInstance().getTowns();

Example

HashSet<String>  towns = HuskTownsAPI.getInstance().getTowns();
StringJoiner joiner = new StringJoiner(", ");
for (String townName : towns) {
  joiner.add(townName);
}
player.sendMessage("Towns on the server: " + joiner.toString());

Get a list of all the town names who have a public spawn

Method

/**
* Get a list of the names of all towns who have their town spawn set to public
* @return A HashSet of the names of all towns with their spawn set to public
*/
HashSet<String>  publicSpawnTowns = HuskTownsAPI.getInstance().getTownsWithPublicSpawn();

Example

HashSet<String>  publicSpawnTowns = HuskTownsAPI.getInstance().getTownsWithPublicSpawn();
StringJoiner joiner = new StringJoiner(", ");
for (String townName : publicSpawnTowns ) {
  joiner.add(townName);
}
player.sendMessage("Towns you can build in: " + joiner.toString());

Get town bio / greeting / farewell message

Methods

/**
* Returns the message sent to players when they enter a town's claim
* @param townName The name of the town
* @return The town's greeting message.
*/
String  welcomeMessage = HuskTownsAPI.getInstance().getTownGreetingMessage(String townName);

/**
* Returns the message sent to players when they leave a town's claim
* @param townName The name of the town
* @return The town's farewell message.
*/
String  farewellMessage = HuskTownsAPI.getInstance().getTownFarewellMessage(String townName);

/**
* Returns the bio of a town
* @param townName The name of the town
* @return The town's bio.
*/
String  bio = HuskTownsAPI.getInstance().getTownBio(String townName);

Example

HuskTownsAPI huskTownsAPI = HuskTownsAPI.getInstance();
Player player = e.getPlayer();

if (huskTownsAPI.isInTown(player) {
  final String townName = huskTownsAPI.getPlayerTown(player)
  player.sendMessage("You are in the town, " + townName);
  player.sendMessage(huskTownsAPI.getBio("Bio: " + townName));
  player.sendMessage(huskTownsAPI.getWelcomeMessage("Greeting message: " + townName));
  player.sendMessage(huskTownsAPI.getFarewellMessage("Farewell message: " + townName));
} else {
  player.sendMessage("You are not in a town!");
}