diff --git a/common/src/main/java/net/william278/husktowns/api/HuskTownsAPI.java b/common/src/main/java/net/william278/husktowns/api/HuskTownsAPI.java index cdec03a2..f74b87fb 100644 --- a/common/src/main/java/net/william278/husktowns/api/HuskTownsAPI.java +++ b/common/src/main/java/net/william278/husktowns/api/HuskTownsAPI.java @@ -32,6 +32,7 @@ import net.william278.husktowns.claim.*; import net.william278.husktowns.map.ClaimMap; import net.william278.husktowns.town.Member; +import net.william278.husktowns.town.Privilege; import net.william278.husktowns.town.Town; import net.william278.husktowns.user.OnlineUser; import net.william278.husktowns.user.Preferences; @@ -262,6 +263,18 @@ public Optional getClaimAt(@NotNull Chunk chunk, @NotNull World world return plugin.getClaimAt(chunk, world); } + /** + * Get whether a claim exists at a {@link Chunk} in a {@link World} + * + * @param chunk The {@link Chunk} to check + * @param world The {@link World} the {@link Chunk} is in + * @return Whether a claim exists at the chunk in the world + * @since 3.0 + */ + public boolean isClaimAt(@NotNull Chunk chunk, @NotNull World world) { + return plugin.getClaimAt(chunk, world).isPresent(); + } + /** * Get a {@link TownClaim} at a {@link Position}, if it exists. * @@ -273,6 +286,17 @@ public Optional getClaimAt(@NotNull Position position) { return plugin.getClaimAt(position); } + /** + * Get whether a claim exists at a {@link Position} + * + * @param position The {@link Position} to check + * @return Whether a claim exists at the position + * @since 3.0 + */ + public boolean isClaimAt(@NotNull Position position) { + return plugin.getClaimAt(position).isPresent(); + } + /** * Create a claim for a town * @@ -601,7 +625,7 @@ public Component getClaimMapComponent(@NotNull Position position) { } /** - * Get whether an {@link Operation} is allowed + * Get whether an {@link Operation} should be allowed to occur. * * @param operation The {@link Operation} to check against * @return Whether the {@link Operation} would be allowed @@ -613,6 +637,46 @@ public boolean isOperationAllowed(@NotNull Operation operation) { return !plugin.cancelOperation(operation); } + + /** + * Get whether an {@link Operation}, consisting of an {@link OnlineUser}, {@link OperationType} and + * {@link Position}, should be allowed to occur. + * + * @param user the user + * @param type the operation type + * @param position the position of the operation + * @return {@code true} if the operation is allowed, else {@code false} + */ + public boolean isOperationAllowed(@NotNull OnlineUser user, @NotNull OperationType type, + @NotNull Position position) { + return isOperationAllowed(Operation.of(user, type, position)); + } + + /** + * Get whether an {@link Operation}, consisting of a {@link Position} and {@link OperationType}, should be allowed + * to occur. + * + * @param position the position of the operation + * @param type the operation type + * @return {@code true} if the operation is allowed, else {@code false} + * @since 1.0 + */ + public boolean isOperationAllowed(@NotNull Position position, @NotNull OperationType type) { + return isOperationAllowed(Operation.of(type, position)); + } + + /** + * Returns whether a {@link User} can exercise a {@link Privilege}. + * + * @param privilege the privilege + * @param user the user + * @return {@code true} if the user can exercise the privilege in the claim, else {@code false} + * @since 3.0 + */ + public boolean isPrivilegeAllowed(@NotNull Privilege privilege, @NotNull User user) { + return getUserTown(user).map(m -> m.hasPrivilege(plugin, privilege)).orElse(false); + } + /** * Get a {@link Town} by its ID. * diff --git a/common/src/main/java/net/william278/husktowns/claim/Claim.java b/common/src/main/java/net/william278/husktowns/claim/Claim.java index 3df68ce6..a57f2024 100644 --- a/common/src/main/java/net/william278/husktowns/claim/Claim.java +++ b/common/src/main/java/net/william278/husktowns/claim/Claim.java @@ -21,11 +21,14 @@ import com.google.gson.annotations.Expose; import com.google.gson.annotations.SerializedName; +import lombok.AccessLevel; +import lombok.NoArgsConstructor; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; import java.util.*; +@NoArgsConstructor(access = AccessLevel.PRIVATE) public class Claim { @Expose @@ -44,10 +47,6 @@ private Claim(@NotNull Chunk chunk, @NotNull Type type, @Nullable Map from(@NotNull Map.Entry entry, @NotNull HuskTowns plugin) { return plugin.findTown(entry.getKey()).map(town -> new TownClaim(town, entry.getValue())); } + @NotNull public static TownClaim admin(@NotNull Chunk chunk, @NotNull HuskTowns plugin) { return new TownClaim(plugin.getAdminTown(), Claim.at(chunk)); } diff --git a/common/src/main/java/net/william278/husktowns/town/Role.java b/common/src/main/java/net/william278/husktowns/town/Role.java index 582c7609..8af51eed 100644 --- a/common/src/main/java/net/william278/husktowns/town/Role.java +++ b/common/src/main/java/net/william278/husktowns/town/Role.java @@ -19,6 +19,9 @@ package net.william278.husktowns.town; +import lombok.AccessLevel; +import lombok.AllArgsConstructor; +import lombok.NoArgsConstructor; import net.william278.husktowns.HuskTowns; import org.jetbrains.annotations.NotNull; @@ -27,18 +30,14 @@ /** * Represents a role in a town */ +@AllArgsConstructor(access = AccessLevel.PRIVATE) +@NoArgsConstructor(access = AccessLevel.PRIVATE) public class Role { private int weight; private String name; private List privileges; - private Role(int weight, @NotNull String name, @NotNull List privileges) { - this.weight = weight; - this.name = name; - this.privileges = privileges; - } - /** * Create a role from a weight, name and list of privileges * @@ -51,10 +50,6 @@ public static Role of(int weight, @NotNull String name, @NotNull List return new Role(weight, name, privileges); } - @SuppressWarnings("unused") - private Role() { - } - /** * Get the weight of the role, determining its position in the role hierarchy. *

diff --git a/docs/API-v1.md b/docs/API-v1.md index 449932d4..95b2d201 100644 --- a/docs/API-v1.md +++ b/docs/API-v1.md @@ -1,6 +1,6 @@ > ⚠️ **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 v2 (See the new [[API]] documentation for more information). +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. @@ -12,7 +12,7 @@ The API accesses cached data and can be used to check for things such as players 4. Getting an instance 2. API Examples -## 1 API Introduction +## 1. API Introduction ### 1.1 Setup with Maven

Maven setup information @@ -74,7 +74,7 @@ softdepend: # Or, use 'depend' here ### 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](https://javadoc.jitpack.io/com/github/WiIIiam278/HuskTowns/husktowns/1.8.2/javadoc/). -## 2 API Examples +## 2. API Examples ### 2.1 Check if a location or block is in the wilderness #### Method diff --git a/docs/Claims-API.md b/docs/Claims-API.md index 4d9e29dc..b4754da7 100644 --- a/docs/Claims-API.md +++ b/docs/Claims-API.md @@ -1 +1,138 @@ -Claims API. WIP \ No newline at end of file +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 +* 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` at the location + * With an `Optional`, 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 + +```java +void showTownWhoHasClaimedAt(org.bukkit.Location location) { + Position position = huskTowns.getPosition(location); + Optional 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. `World`s without `ClaimWorld`s 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` + +
+Example — Getting the claim world for a world + +```java +void showClaimWorld(org.bukkit.World world) { + Optional 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 + +```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!"); + } +} +``` +
+ +## 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 + +```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); +} +``` +
+ +### 3.1 Editing a claim +* You can edit a claim using `#editClaimAt(Chunk chunk, World world, Consumer editor)` +* This will allow you to edit the claim at the given chunk and world using the `Consumer` 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 + +```java +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 + +```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); +} +``` +
+ +### 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 + +```java +void highlightClaimAt(org.bukkit.Player player, org.bukkit.Location location) { + OnlineUser user = huskTowns.getOnlineUser(player); + Position position = huskTowns.getPosition(location); + Optional claim = huskTowns.getClaimAt(position); + if (claim.isPresent()) { + huskTowns.highlightClaim(user, claim.get()); + } +} +``` +
\ No newline at end of file diff --git a/docs/Towns-API.md b/docs/Towns-API.md index 542554ae..04069d43 100644 --- a/docs/Towns-API.md +++ b/docs/Towns-API.md @@ -4,6 +4,8 @@ This page assumes you have read the general [[API]] introduction and that you ha ## Table of contents * [1. Getting a Town](#1-getting-a-town) + * [1.1 Getting a user's town & role](#11-getting-a-users-town--role) + * [1.2 Checking a user's privileges](#12-checking-a-users-privileges) * [2. Editing a Town](#2-editing-a-town) * [3. Creating a Town](#3-creating-a-town) * [4. Deleting a Town](#4-deleting-a-town) @@ -12,13 +14,14 @@ This page assumes you have read the general [[API]] introduction and that you ha * You can get a town with `#getTown(String name)` * This will return an `Optional`; a town wrapped with an Optional (that will be empty if no town exists with the supplied `name`) * A `Town` object has a range of properties and methods for interacting with the town. +* You can also get the `Town` from a `TownClaim` object - see the [[Claims API]] for more information.
Example — Getting a town by name ```java void getTownByName(String townName) { - Optional town = huskTownsAPI.getTown(townName); + Optional town = huskTowns.getTown(townName); if (town.isPresent()) { // Do something with the town Town townObject = town.get(); @@ -28,7 +31,49 @@ void getTownByName(String townName) { } } ``` +
+ +### 1.1 Getting a user's town & role +* You can get a user's town with `#getUserTown(User user)`, which will return an `Optional` for the town the user is in. + * If the `Member` is present, you can use `Member#town()` to get the `Town` object + * If the `OnlineUser` is not in a town, the `Optional` will be empty (`Optional#isEmpty()`) +* You can then get the user's town `Role` via `Member#role()` +
+Example — Getting a user's town and role + +```java +void showUserTownAndRole(org.bukkit.Player player) { + OnlineUser user = huskTowns.getOnlineUser(player); + Optional 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"); + } +} +``` +
+ +### 1.2 Checking a user's privileges +* You can check what `Privilege`s a `Member` can perform with `HuskTownsAPI#isPrivilegeAllowed(Privilege privilege, User user)` + * This method will return `true` if the user has the privilege, and `false` if they do not. + +
+Example — Checking if a user can create claims + +```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"); + } +} +```
## 2. Editing a Town @@ -38,6 +83,8 @@ void getTownByName(String townName) { * You should use a relevant user for the action, such as the player who is performing the action if possible, otherwise a random user. * To get an `OnlineUser` object, use the platform modules — on the Bukkit platform, use `#getOnlineUser(org.bukkit.Player player)`. * The `#editTown(OnlineUser actor, String townName, Consumer editor)` provides a way to modify a town in a single action using a `Consumer`. + * You can use this method to add a user to a town via `Town#addMember(UUID, role)` — just be sure to make sure you don't add users to multiple towns! + * You can also use this method to modify the town's properties, such as the greeting and farewell messages. Be sure to check the Javadoc comments to make sure you properly validate user input. * This is not the API for creating claims! See the [[Claims API]] for that.
@@ -45,8 +92,8 @@ void getTownByName(String townName) { ```java void editTown(String townName, org.bukkit.Player player) { - OnlineUser online = huskTownsAPI.getOnlineUser(player); - huskTownsAPI.editTown(online, townName, town -> { + OnlineUser online = huskTowns.getOnlineUser(player); + huskTowns.editTown(online, townName, town -> { town.setGreeting("Welcome to our town!"); town.setFarewell("Goodbye!"); }); @@ -64,8 +111,8 @@ void editTown(String townName, org.bukkit.Player player) { ```java void createTown(String townName, org.bukkit.Player player) { - OnlineUser online = huskTownsAPI.getOnlineUser(player); - CompletableFuture future = huskTownsAPI.createTown(townName, online); + OnlineUser online = huskTowns.getOnlineUser(player); + CompletableFuture future = huskTowns.createTown(townName, online); future.thenAccept(town -> { System.out.println("Town created: " + town.getName()); }).exceptionally(throwable -> { @@ -85,8 +132,8 @@ void createTown(String townName, org.bukkit.Player player) { ```java void deleteTown(String townName, org.bukkit.Player player) { - OnlineUser online = huskTownsAPI.getOnlineUser(player); - huskTownsAPI.deleteTown(townName, online); + OnlineUser online = huskTowns.getOnlineUser(player); + huskTowns.deleteTown(townName, online); } ```
\ No newline at end of file