Skip to content

Commit 8a33d9d

Browse files
actions-userdependabot[bot]
actions-user
and
dependabot[bot]
committed
build(deps): bump maven.modrinth:pl3xmap from 1.20.4-482 to 1.20.4-483 (WiIIiam278#411)
Bumps maven.modrinth:pl3xmap from 1.20.4-482 to 1.20.4-483. --- updated-dependencies: - dependency-name: maven.modrinth:pl3xmap dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
1 parent 843403f commit 8a33d9d

24 files changed

+2216
-0
lines changed

‎temp_wiki_843403f30fe43a8d2b948aab09b5f91588b0b0ae/API-Events.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
HuskTowns provides several API events your plugin can listen to when players do certain town-related things. These events deal in HuskTowns class types, so you may want to familiarize yourself with the [API basics](API) first. Note that on cross-server setups, events only fire on the *server the event occurred on* and will not fire as a result of API calls/updates.
2+
3+
Consult the Javadocs for more information&mdash;and don't forget to register your listener when listening for these event calls.
4+
5+
## List of API Events
6+
| Bukkit Event class | Since | Cancellable | Description |
7+
|-------------------------|:-----:|:-----------:|--------------------------------------------------------------------------------|
8+
| `TownCreateEvent` | 1.8 | ✅ | Called when a town is created |
9+
| `PostTownCreateEvent` | 2.6 | ❌ | Called after a town is created |
10+
| `TownDisbandEvent` | 1.8 | ✅ | Called when a town is deleted |
11+
| `ClaimEvent` | 1.8 | ✅ | Called when a player claims a chunk for a town |
12+
| `UnClaimEvent` | 1.8 | ✅ | Called when a player deletes a claim |
13+
| `UnClaimAllEvent` | 2.1 | ✅ | Called when a player deletes all of a town's claims |
14+
| `PlayerEnterTownEvent` | 2.0 | ✅ | Called when a player walks into a town claim from wilderness or another town |
15+
| `PlayerLeaveTownEvent` | 2.0 | ✅ | Called when a player walks out of a town claim into wilderness or another town |
16+
| `MemberJoinEvent` | 2.0 | ✅ | Called when a player joins a town |
17+
| `MemberLeaveEvent` | 2.0 | ✅ | Called when a player leaves or is evicted from a town |
18+
| `MemberRoleChangeEvent` | 2.0 | ✅ | Called when a player is promoted or demoted within a town |

‎temp_wiki_843403f30fe43a8d2b948aab09b5f91588b0b0ae/API-v1.md

+277
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
> ⚠️ **API v1 is no longer supported by HuskTowns v3**. Please refer to the new HuskTowns [[API]] v3 for the current API specification.
2+
3+
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).
4+
5+
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.
6+
7+
## Table of contents
8+
1. Adding the API to your project
9+
1. Setup with Maven
10+
2. Setup with Gradle
11+
3. Adding a dependency
12+
4. Getting an instance
13+
2. API Examples
14+
15+
## 1. API Introduction
16+
### 1.1 Setup with Maven
17+
<details>
18+
<summary>Maven setup information</summary>
19+
20+
- Add the repository to your `pom.xml` as per below.
21+
```xml
22+
<repositories>
23+
<repository>
24+
<id>jitpack.io</id>
25+
<url>https://jitpack.io</url>
26+
</repository>
27+
</repositories>
28+
```
29+
- Add the dependency to your `pom.xml` as per below.
30+
```xml
31+
<dependency>
32+
<groupId>net.william278</groupId>
33+
<artifactId>HuskTowns</artifactId>
34+
<version>1.8.2</version>
35+
<scope>provided</scope>
36+
</dependency>
37+
```
38+
</details>
39+
40+
### 1.2 Setup with Gradle
41+
<details>
42+
<summary>Gradle setup information</summary>
43+
44+
- Add the dependency like so to your `build.gradle`:
45+
```groovy
46+
allprojects {
47+
repositories {
48+
maven { url 'https://jitpack.io' }
49+
}
50+
}
51+
```
52+
- Add the dependency as per below.
53+
54+
```groovy
55+
dependencies {
56+
compileOnly 'net.william278:HuskTowns:1.8.2'
57+
}
58+
```
59+
</details>
60+
61+
### 1.3 Adding HuskTowns as a dependency
62+
- Add HuskTowns to your `softdepend` (if you want to optionally use HuskTowns) or `depend` (if your plugin relies on HuskTowns) section in `plugin.yml` of your project.
63+
64+
```yaml
65+
name: MyPlugin
66+
version: 1.0
67+
main: net.william278.myplugin.MyPlugin
68+
author: William278
69+
description: 'A plugin that hooks with the HuskTowns v1 API!'
70+
softdepend: # Or, use 'depend' here
71+
- HuskTowns
72+
```
73+
74+
### 1.4. Getting an instance of the API
75+
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](https://javadoc.jitpack.io/com/github/WiIIiam278/HuskTowns/husktowns/1.8.2/javadoc/).
76+
77+
## 2. API Examples
78+
### 2.1 Check if a location or block is in the wilderness
79+
80+
#### Method
81+
```java
82+
/**
83+
* Check if the specified {@link Block} is in the wilderness (outside of a claim).
84+
* @param block {@link Block} to check.
85+
* @return true if the {@link Block} is in the wilderness; otherwise return false.
86+
*/
87+
boolean isWilderness = HuskTownsAPI.getInstance().isWilderness(Block block);
88+
```
89+
or
90+
```java
91+
/**
92+
* Check if the specified {@link Location} is in the wilderness (outside of a claim).
93+
* @param location {@link Location} to check.
94+
* @return true if the {@link Location} is in the wilderness; otherwise return false.
95+
*/
96+
boolean isWilderness = HuskTownsAPI.getInstance().isWilderness(Location location);
97+
```
98+
99+
#### Example
100+
```java
101+
Location location = player.getLocation();
102+
if (isWilderness(location)) {
103+
player.sendMessage("In wilderness");
104+
} else {
105+
player.sendMessage("In a claim");
106+
}
107+
```
108+
109+
### 2.2 Get the name of a town at a location
110+
111+
#### Method
112+
```java
113+
/**
114+
* Returns the name of the town at the specified {@link Location}.
115+
* @param location {@link Location} to check.
116+
* @return the name of the town who has a claim at the specified {@link Location}; null if there is no claim there.
117+
*/
118+
String town = HuskTownsAPI.getInstance().getTownAt(Location location);
119+
```
120+
121+
#### Example
122+
```java
123+
String townName = HuskTownsAPI.getInstance().getTownAt(player.getLocation());
124+
if (townName == null) {
125+
player.sendMessage("In wilderness")
126+
} else {
127+
player.sendMessage("You're standing in " + townName)
128+
}
129+
```
130+
131+
### 2.3 Get whether a player is in a town
132+
133+
#### Method
134+
```java
135+
/**
136+
* Returns true if the {@link Player} is in a town; false if not.
137+
* @param player {@link Player} to check.
138+
* @return true if the {@link Player} is in a town; false otherwise.
139+
*/
140+
boolean inTown = HuskTownsAPI.getInstance().isInTown(Player player);
141+
```
142+
143+
#### Example
144+
```java
145+
boolean inTown = HuskTownsAPI.getInstance().isInTown(player);
146+
if (inTown) {
147+
player.sendMessage("You're a member of a town")
148+
} else {
149+
player.sendMessage("You're not a member of a town")
150+
}
151+
```
152+
153+
### 2.4 Get the name of a town a player is in
154+
155+
#### Method
156+
```java
157+
/**
158+
* Returns the name of the town the {@link Player} is currently in; null if they are not in a town
159+
* @param player {@link Player} to check.
160+
* @return the name of the town the {@link Player} is currently in; null if they are not in a town.
161+
*/
162+
String town = HuskTownsAPI.getInstance().getPlayerTown(Player player);
163+
```
164+
165+
#### Example
166+
```java
167+
String townName = HuskTownsAPI.getInstance().getPlayerTown(player);
168+
if (townName == null) {
169+
player.sendMessage("You're not in a town")
170+
} else {
171+
player.sendMessage("You're a member of " + townName)
172+
}
173+
```
174+
175+
### 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.
176+
177+
#### Method
178+
```java
179+
/**
180+
* Returns whether or not the specified {@link Player} can build at the specified {@link Location}.
181+
* @param player {@link Player} to check.
182+
* @param location {@link Location} to check.
183+
* @return true if the player can build at the specified {@link Location}; false otherwise.
184+
*/
185+
boolean canBuild = HuskTownsAPI.getInstance().canBuild(Player player, Location location);
186+
```
187+
188+
#### Example
189+
```java
190+
boolean canBuild = HuskTownsAPI.getInstance().canBuild(player, player.getLocation());
191+
if (canBuild) {
192+
player.sendMessage("You can build here!")
193+
} else {
194+
player.sendMessage("You don't have access to build here.")
195+
}
196+
```
197+
198+
### 2.6 Get a list of all the town names
199+
#### Method
200+
```java
201+
/**
202+
* Get a list of the names of all towns
203+
* @return A HashSet of all town names
204+
*/
205+
HashSet<String> towns = HuskTownsAPI.getInstance().getTowns();
206+
```
207+
208+
#### Example
209+
```java
210+
HashSet<String> towns = HuskTownsAPI.getInstance().getTowns();
211+
StringJoiner joiner = new StringJoiner(", ");
212+
for (String townName : towns) {
213+
joiner.add(townName);
214+
}
215+
player.sendMessage("Towns on the server: " + joiner.toString());
216+
```
217+
218+
### 2.7 Get a list of all the town names who have a public spawn
219+
#### Method
220+
```java
221+
/**
222+
* Get a list of the names of all towns who have their town spawn set to public
223+
* @return A HashSet of the names of all towns with their spawn set to public
224+
*/
225+
HashSet<String> publicSpawnTowns = HuskTownsAPI.getInstance().getTownsWithPublicSpawn();
226+
```
227+
228+
#### Example
229+
```java
230+
HashSet<String> publicSpawnTowns = HuskTownsAPI.getInstance().getTownsWithPublicSpawn();
231+
StringJoiner joiner = new StringJoiner(", ");
232+
for (String townName : publicSpawnTowns ) {
233+
joiner.add(townName);
234+
}
235+
player.sendMessage("Towns you can build in: " + joiner.toString());
236+
```
237+
238+
### 2.8 Get town bio / greeting / farewell message
239+
#### Methods
240+
```java
241+
/**
242+
* Returns the message sent to players when they enter a town's claim
243+
* @param townName The name of the town
244+
* @return The town's greeting message.
245+
*/
246+
String welcomeMessage = HuskTownsAPI.getInstance().getTownGreetingMessage(String townName);
247+
248+
/**
249+
* Returns the message sent to players when they leave a town's claim
250+
* @param townName The name of the town
251+
* @return The town's farewell message.
252+
*/
253+
String farewellMessage = HuskTownsAPI.getInstance().getTownFarewellMessage(String townName);
254+
255+
/**
256+
* Returns the bio of a town
257+
* @param townName The name of the town
258+
* @return The town's bio.
259+
*/
260+
String bio = HuskTownsAPI.getInstance().getTownBio(String townName);
261+
```
262+
263+
#### Example
264+
```java
265+
HuskTownsAPI huskTownsAPI = HuskTownsAPI.getInstance();
266+
Player player = e.getPlayer();
267+
268+
if (huskTownsAPI.isInTown(player) {
269+
final String townName = huskTownsAPI.getPlayerTown(player)
270+
player.sendMessage("You are in the town, " + townName);
271+
player.sendMessage(huskTownsAPI.getBio("Bio: " + townName));
272+
player.sendMessage(huskTownsAPI.getWelcomeMessage("Greeting message: " + townName));
273+
player.sendMessage(huskTownsAPI.getFarewellMessage("Farewell message: " + townName));
274+
} else {
275+
player.sendMessage("You are not in a town!");
276+
}
277+
```

0 commit comments

Comments
 (0)