API v1
⚠️ API v1 is no longer supported by HuskTowns v3. Please refer to the new HuskTowns API v3 for the current API specification.
The HuskTowns API v1 provides methods to get data from HuskTowns directly. API v1 has been deprecated and superseded by the HuskTownsAPI v3 (See the new API documentation for more information).
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
- Adding the API to your project
- Setup with Maven
- Setup with Gradle
- Adding a dependency
- Getting an instance
- API Examples
1. API Introduction
1.1 Setup with Maven
Maven setup information
- Add the repository to your
pom.xml
as per below.
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
- Add the dependency to your
pom.xml
as per below.
<dependency>
<groupId>net.william278</groupId>
<artifactId>HuskTowns</artifactId>
<version>1.8.2</version>
<scope>provided</scope>
</dependency>
1.2 Setup with Gradle
Gradle setup information
- Add the dependency like so to your
build.gradle
:
allprojects {
repositories {
maven { url 'https://jitpack.io' }
}
}
- Add the dependency as per below.
dependencies {
compileOnly 'net.william278:HuskTowns:1.8.2'
}
1.3 Adding HuskTowns as a dependency
- Add HuskTowns to your
softdepend
(if you want to optionally use HuskTowns) ordepend
(if your plugin relies on HuskTowns) section inplugin.yml
of your project.
name: MyPlugin
version: 1.0
main: net.william278.myplugin.MyPlugin
author: William278
description: 'A plugin that hooks with the HuskTowns v1 API!'
softdepend: # Or, use 'depend' here
- HuskTowns
1.4. Getting an instance of the API
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.
2. API Examples
2.1 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");
}
2.2 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)
}
2.3 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")
}
2.4 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)
}
2.5 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.")
}
2.6 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());
2.7 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());
2.8 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!");
}