11 | * This interface extends {@link Keyed}, which provides a mechanism for providing 12 | * unique identifiers for each capability. 13 | *
14 | * Implementations of this interface can be used in conjunction with capability 15 | * providers or related systems to organize and query available functionalities. 16 | */ 17 | public interface Capability extends Keyed { 18 | } 19 | -------------------------------------------------------------------------------- /src/main/java/net/thenextlvl/service/api/capability/CapabilityException.java: -------------------------------------------------------------------------------- 1 | package net.thenextlvl.service.api.capability; 2 | 3 | import org.jspecify.annotations.NullMarked; 4 | import org.jspecify.annotations.Nullable; 5 | 6 | /** 7 | * An exception that indicates a problem related to a specific {@link Capability}. 8 | * This exception is typically thrown when there is an issue or unsupported operation 9 | * associated with a particular capability in the system. 10 | */ 11 | @NullMarked 12 | public class CapabilityException extends RuntimeException { 13 | private final Capability capability; 14 | 15 | /** 16 | * Creates a new {@code CapabilityException} with the specified detail message and 17 | * the related capability that caused this exception. 18 | * 19 | * @param message the detail message, providing additional information about the exception. 20 | * @param capability the {@link Capability} instance associated with this exception, 21 | * indicating the capability that caused the issue. 22 | */ 23 | public CapabilityException(String message, Capability capability) { 24 | super(message); 25 | this.capability = capability; 26 | } 27 | 28 | /** 29 | * Constructs a new {@code CapabilityException} with a specified detail message, cause, 30 | * and the associated capability that led to the exception. 31 | * 32 | * @param message the detail message, providing additional information about the exception. 33 | * @param cause the cause of the exception, which may be {@code null} to indicate no specific cause. 34 | * @param capability the {@link Capability} instance associated with this exception, 35 | * indicating the capability that caused the issue. 36 | */ 37 | public CapabilityException(String message, @Nullable Throwable cause, Capability capability) { 38 | super(message, cause); 39 | this.capability = capability; 40 | } 41 | 42 | /** 43 | * Retrieves the capability associated with this exception. 44 | * 45 | * @return the {@link Capability} instance that caused this exception, 46 | * representing a specific feature or limitation. 47 | */ 48 | public Capability getCapability() { 49 | return this.capability; 50 | } 51 | } 52 | -------------------------------------------------------------------------------- /src/main/java/net/thenextlvl/service/api/capability/CapabilityProvider.java: -------------------------------------------------------------------------------- 1 | package net.thenextlvl.service.api.capability; 2 | 3 | import org.jetbrains.annotations.Unmodifiable; 4 | import org.jspecify.annotations.NullMarked; 5 | 6 | import java.util.Collection; 7 | import java.util.Set; 8 | 9 | /** 10 | * A generic interface providing methods to query and check support for specific capabilities. 11 | *
12 | * The {@code CapabilityProvider} interface allows implementing classes to define a set of supported
13 | * capabilities and provides mechanisms to check whether the provider supports individual or multiple capabilities.
14 | *
15 | * @param
54 | * This method requires the provider to support the {@link CharacterCapability#ACTUAL_ENTITIES} capability.
55 | *
56 | * @return an {@code Optional} containing the associated entity, or an empty {@code Optional}
57 | * if no entity is associated with the character.
58 | */
59 | Optional
82 | * This method requires the provider to support the {@link CharacterCapability#HEALTH} capability.
83 | *
84 | * @return {@code true} if the character is invulnerable, otherwise {@code false}
85 | */
86 | boolean isInvulnerable();
87 |
88 | /**
89 | * Checks if the character is currently spawned in the world.
90 | *
91 | * @return {@code true} if the character is spawned, otherwise {@code false}
92 | */
93 | boolean isSpawned();
94 |
95 | /**
96 | * Checks whether the tablist entry for the character is currently hidden.
97 | *
98 | * @return {@code true} if the tablist entry is hidden, otherwise {@code false}
99 | */
100 | boolean isTablistEntryHidden();
101 |
102 | /**
103 | * Respawns the character, bringing it back to the world if it was previously despawned.
104 | *
105 | * @return {@code true} if the character was successfully respawned, otherwise {@code false}
106 | */
107 | boolean respawn();
108 |
109 | /**
110 | * Spawns the character at the specified location.
111 | *
112 | * @param location the {@code Location} where the character will be spawned
113 | * @return {@code true} if the character was successfully spawned, otherwise {@code false}
114 | */
115 | boolean spawn(Location location);
116 |
117 | /**
118 | * Adjusts the character's orientation to face the given entity.
119 | *
120 | * @param entity the {@code Entity} that the character should face
121 | */
122 | void lookAt(Entity entity);
123 |
124 | /**
125 | * Adjusts the character's orientation to face the specified location.
126 | *
127 | * @param location the {@code Location} that the character should face
128 | */
129 | void lookAt(Location location);
130 |
131 | /**
132 | * Permanently removes the character, rendering it inaccessible and removing all associated data.
133 | * After invoking this method, the character can't be respawned or interacted with.
134 | */
135 | void remove();
136 |
137 | /**
138 | * Sets whether the character is collidable, controlling its ability to physically interact
139 | * with other entities in the world.
140 | *
141 | * @param collidable {@code true} to make the character collidable, allowing physical interactions
142 | */
143 | void setCollidable(boolean collidable);
144 |
145 | /**
146 | * Sets the display name for the character.
147 | *
148 | * @param displayName the {@code Component} representing the new display name to be set
149 | */
150 | void setDisplayName(Component displayName);
151 |
152 | /**
153 | * Sets whether the character can take damage.
154 | *
155 | * This method requires the provider to support the {@link CharacterCapability#HEALTH} capability.
156 | *
157 | * @param invulnerable {@code true} if the character should be invulnerable, {@code false} otherwise
158 | */
159 | void setInvulnerable(boolean invulnerable);
160 |
161 | /**
162 | * Sets the visibility state of the character's tablist entry.
163 | *
164 | * @param hidden {@code true} to hide the tablist entry, {@code false} to make it visible
165 | */
166 | void setTablistEntryHidden(boolean hidden);
167 | }
168 |
--------------------------------------------------------------------------------
/src/main/java/net/thenextlvl/service/api/character/CharacterCapability.java:
--------------------------------------------------------------------------------
1 | package net.thenextlvl.service.api.character;
2 |
3 | import net.kyori.adventure.key.Key;
4 | import net.thenextlvl.service.api.capability.Capability;
5 | import org.jspecify.annotations.NullMarked;
6 |
7 | import java.lang.Character;
8 |
9 | /**
10 | * An enum representing various capabilities a {@link Character} might possess.
11 | *
12 | * Each capability indicates a specific feature or limitation
13 | * in how characters can be represented or interacted with.
14 | *
15 | * The enum constant values represent specific capabilities that can be
16 | * queried or utilized to determine the functionality of particular
17 | * implementations.
18 | *
19 | * Each capability is associated with a unique {@link Key} that acts as an
20 | * identifier for the capability.
21 | */
22 | @NullMarked
23 | public enum CharacterCapability implements Capability {
24 | /**
25 | * Represents the capability for a character to have a health attribute.
26 | *
27 | * This capability indicates that the character can make use of features related
28 | * to health, such as taking damage or recovering health.
29 | */
30 | HEALTH(Key.key("capability", "health")),
31 |
32 | /**
33 | * Represents the capability for a character to handle
34 | * interactions such as left, and right-click actions.
35 | */
36 | INTERACTIONS(Key.key("capability", "interactions")),
37 |
38 | /**
39 | * Represents the capability for supporting non-player entities such as pigs or zombies.
40 | * This indicates whether the provider can handle entity types beyond player characters.
41 | */
42 | NON_PLAYER_ENTITIES(Key.key("capability", "non_player_entities")),
43 |
44 | /**
45 | * Represents the capability to utilize actual entity objects.
46 | *
47 | * This capability indicates that the character provider supports using real, tangible entities
48 | * within the game world.
49 | * Such entities are recognized by the server and may be subject to various
50 | * physical interactions, such as collisions, gravity, or other in-game mechanics.
51 | */
52 | ACTUAL_ENTITIES(Key.key("capability", "actual_entities"));
53 |
54 | private final Key key;
55 |
56 | CharacterCapability(Key key) {
57 | this.key = key;
58 | }
59 |
60 | @Override
61 | public Key key() {
62 | return this.key;
63 | }
64 | }
65 |
--------------------------------------------------------------------------------
/src/main/java/net/thenextlvl/service/api/character/event/CharacterDamageEvent.java:
--------------------------------------------------------------------------------
1 | package net.thenextlvl.service.api.character.event;
2 |
3 | import net.thenextlvl.service.api.character.Character;
4 | import net.thenextlvl.service.api.character.CharacterCapability;
5 | import net.thenextlvl.service.api.character.CharacterController;
6 | import org.bukkit.event.Cancellable;
7 | import org.bukkit.event.entity.EntityDamageEvent;
8 | import org.jspecify.annotations.NullMarked;
9 |
10 | /**
11 | * The CharacterDamageEvent represents an event triggered when a character takes damage.
12 | *
13 | * The event allows for inspecting and modifying the damage dealt, determining the cause of
14 | * the damage, and controlling whether the event should be cancelled.
15 | *
16 | * This event will only be fired for providers that support the {@link CharacterCapability#HEALTH} capability.
17 | */
18 | @NullMarked
19 | public class CharacterDamageEvent extends CharacterEvent implements Cancellable {
20 | private final EntityDamageEvent.DamageCause cause;
21 | private boolean cancelled;
22 | private double damage;
23 |
24 | /**
25 | * Constructs a new CharacterDamageEvent representing damage dealt to a character.
26 | *
27 | * @param controller the character controller managing the character
28 | * @param character the character that is taking damage
29 | * @param cause the cause of the damage
30 | * @param damage the amount of damage dealt to the character
31 | */
32 | public CharacterDamageEvent(CharacterController controller, Character character, EntityDamageEvent.DamageCause cause, double damage) {
33 | super(controller, character);
34 | this.cause = cause;
35 | this.damage = damage;
36 | }
37 |
38 | /**
39 | * Retrieves the cause of the damage associated with this event.
40 | *
41 | * @return the {@link EntityDamageEvent.DamageCause} that represents the underlying cause of the damage
42 | */
43 | public EntityDamageEvent.DamageCause getCause() {
44 | return cause;
45 | }
46 |
47 | /**
48 | * Retrieves the amount of damage associated with this event.
49 | *
50 | * @return the damage value as a double
51 | */
52 | public double getDamage() {
53 | return damage;
54 | }
55 |
56 | /**
57 | * Sets the amount of damage for this event.
58 | *
59 | * @param damage the new damage value to be set
60 | */
61 | public void setDamage(double damage) {
62 | this.damage = damage;
63 | }
64 |
65 | @Override
66 | public boolean isCancelled() {
67 | return cancelled;
68 | }
69 |
70 | @Override
71 | public void setCancelled(boolean cancelled) {
72 | this.cancelled = cancelled;
73 | }
74 | }
75 |
--------------------------------------------------------------------------------
/src/main/java/net/thenextlvl/service/api/character/event/CharacterEvent.java:
--------------------------------------------------------------------------------
1 | package net.thenextlvl.service.api.character.event;
2 |
3 | import net.thenextlvl.service.api.character.Character;
4 | import net.thenextlvl.service.api.character.CharacterController;
5 | import org.bukkit.event.Event;
6 | import org.bukkit.event.HandlerList;
7 | import org.jspecify.annotations.NullMarked;
8 |
9 | /**
10 | * Represents a base class for events related to a character in the game.
11 | *
12 | * This class serves as a foundation for character-based events, providing
13 | * common functionality through the controller and character references.
14 | * It allows for tracking the controller, managing the character, and the target character
15 | * involved in the event.
16 | *
17 | * Subclasses can make use of these common properties while implementing specific
18 | * character-related event functionalities.
19 | */
20 | @NullMarked
21 | public abstract class CharacterEvent extends Event {
22 | private static final HandlerList handlers = new HandlerList();
23 | private final CharacterController controller;
24 | private final Character character;
25 |
26 | /**
27 | * Constructs a new CharacterEvent.
28 | *
29 | * @param controller the character controller responsible for managing the character
30 | * @param character the character instance involved in the event
31 | */
32 | public CharacterEvent(CharacterController controller, Character character) {
33 | super(!character.getServer().isPrimaryThread());
34 | this.controller = controller;
35 | this.character = character;
36 | }
37 |
38 | /**
39 | * Retrieves the character controller associated with this event.
40 | *
41 | * @return the {@code CharacterController} responsible for managing the character in this event.
42 | */
43 | public CharacterController getController() {
44 | return controller;
45 | }
46 |
47 | /**
48 | * Retrieves the character associated with this event.
49 | *
50 | * @return the {@code Character} instance involved in this event
51 | */
52 | public Character getCharacter() {
53 | return character;
54 | }
55 |
56 | @Override
57 | public HandlerList getHandlers() {
58 | return handlers;
59 | }
60 |
61 | public static HandlerList getHandlerList() {
62 | return handlers;
63 | }
64 | }
65 |
--------------------------------------------------------------------------------
/src/main/java/net/thenextlvl/service/api/character/event/EntityDamageCharacterEvent.java:
--------------------------------------------------------------------------------
1 | package net.thenextlvl.service.api.character.event;
2 |
3 | import net.thenextlvl.service.api.character.Character;
4 | import net.thenextlvl.service.api.character.CharacterCapability;
5 | import net.thenextlvl.service.api.character.CharacterController;
6 | import org.bukkit.entity.Entity;
7 | import org.bukkit.event.entity.EntityDamageEvent;
8 | import org.jspecify.annotations.NullMarked;
9 |
10 | /**
11 | * Represents an event triggered when an entity damages a character.
12 | *
13 | * This event extends {@link CharacterDamageEvent} and provides additional details
14 | * about the attacker and whether the damage dealt is critical.
15 | * It can be used to inspect and modify the damage attributed to an entity's attack and to check the critical status.
16 | *
17 | * This event will only be fired for providers that support the {@link CharacterCapability#HEALTH} capability.
18 | */
19 | @NullMarked
20 | public class EntityDamageCharacterEvent extends CharacterDamageEvent {
21 | private final Entity attacker;
22 | private final boolean critical;
23 |
24 | /**
25 | * Constructs an EntityDamageCharacterEvent.
26 | *
27 | * @param controller the CharacterController managing the character involved in the event
28 | * @param character the character that is being damaged
29 | * @param attacker the entity causing the damage to the character
30 | * @param cause the cause of the damage
31 | * @param damage the amount of damage dealt to the character
32 | * @param critical whether the damage dealt is a critical hit
33 | */
34 | public EntityDamageCharacterEvent(CharacterController controller, Character character, Entity attacker,
35 | EntityDamageEvent.DamageCause cause, double damage, boolean critical) {
36 | super(controller, character, cause, damage);
37 | this.attacker = attacker;
38 | this.critical = critical;
39 | }
40 |
41 | /**
42 | * Determines whether the damage associated with this event is critical.
43 | *
44 | * @return {@code true} if the damage is a critical hit; {@code false} otherwise
45 | */
46 | public boolean isCritical() {
47 | return critical;
48 | }
49 |
50 | /**
51 | * Retrieves the entity responsible for causing the damage in this event.
52 | *
53 | * @return the {@code Entity} that attacked the character, causing the damage
54 | */
55 | public Entity getAttacker() {
56 | return attacker;
57 | }
58 | }
59 |
--------------------------------------------------------------------------------
/src/main/java/net/thenextlvl/service/api/character/event/PlayerInteractCharacterEvent.java:
--------------------------------------------------------------------------------
1 | package net.thenextlvl.service.api.character.event;
2 |
3 | import net.thenextlvl.service.api.character.Character;
4 | import net.thenextlvl.service.api.character.CharacterCapability;
5 | import net.thenextlvl.service.api.character.CharacterController;
6 | import org.bukkit.entity.Player;
7 | import org.bukkit.event.Cancellable;
8 | import org.jspecify.annotations.NullMarked;
9 |
10 | /**
11 | * Represents an event triggered when a player interacts with a character.
12 | *
13 | * This event occurs when a player performs an interaction with a specific character,
14 | * such as a left-click or a right-click.
15 | * It encapsulates information about the player performing the interaction,
16 | * the type of interaction, and the character involved.
17 | *
18 | * This event is cancellable, meaning that handling methods may prevent
19 | * the interaction from proceeding by setting the event's cancelled state.
20 | *
21 | * This event will only be fired for providers that support the {@link CharacterCapability#INTERACTIONS} capability.
22 | */
23 | @NullMarked
24 | public class PlayerInteractCharacterEvent extends CharacterEvent implements Cancellable {
25 | private final Player player;
26 | private final InteractionType type;
27 | private boolean cancelled;
28 |
29 | /**
30 | * Constructs an event representing a player's interaction with a character.
31 | *
32 | * @param controller the character controller managing the character involved in the event
33 | * @param character the character being interacted with
34 | * @param player the player performing the interaction
35 | * @param type the type of interaction performed by the player
36 | */
37 | public PlayerInteractCharacterEvent(CharacterController controller, Character character,
38 | Player player, InteractionType type) {
39 | super(controller, character);
40 | this.player = player;
41 | this.type = type;
42 | }
43 |
44 | /**
45 | * Retrieves the player involved in the event.
46 | *
47 | * @return the {@code Player} instance that is performing the interaction in this event
48 | */
49 | public Player getPlayer() {
50 | return player;
51 | }
52 |
53 | /**
54 | * Retrieves the type of interaction performed during the event.
55 | *
56 | * @return the {@code InteractionType} representing the type of interaction
57 | */
58 | public InteractionType getType() {
59 | return type;
60 | }
61 |
62 | @Override
63 | public boolean isCancelled() {
64 | return cancelled;
65 | }
66 |
67 | @Override
68 | public void setCancelled(boolean cancelled) {
69 | this.cancelled = cancelled;
70 | }
71 |
72 | /**
73 | * Represents the type of interaction performed by a player.
74 | */
75 | public enum InteractionType {
76 | /**
77 | * Represents a left-click interaction performed by a player.
78 | *
79 | * This type of interaction occurs when a player attacks.
80 | */
81 | LEFT_CLICK,
82 |
83 | /**
84 | * Represents a right-click interaction performed by a player.
85 | *
86 | * This type of interaction occurs when a player interacts.
87 | */
88 | RIGHT_CLICK,
89 |
90 | /**
91 | * Represents a shift-left-click interaction performed by a player.
92 | *
93 | * This type of interaction occurs when a player attacks while sneaking.
94 | */
95 | SHIFT_LEFT_CLICK,
96 |
97 | /**
98 | * Represents a shift-right-click interaction performed by a player.
99 | *
100 | * This type of interaction occurs when a player interacts while sneaking.
101 | */
102 | SHIFT_RIGHT_CLICK;
103 |
104 | /**
105 | * Checks if the interaction type is a left-click.
106 | *
107 | * @return whether this interaction represents a left-click
108 | */
109 | public boolean isLeftClick() {
110 | return equals(LEFT_CLICK) || equals(SHIFT_LEFT_CLICK);
111 | }
112 |
113 | /**
114 | * Checks if the interaction type is a right-click.
115 | *
116 | * @return whether this interaction represents a right-click
117 | */
118 | public boolean isRightClick() {
119 | return equals(RIGHT_CLICK) || equals(SHIFT_RIGHT_CLICK);
120 | }
121 |
122 | /**
123 | * Checks if the interaction type is a shift-click.
124 | *
125 | * @return whether this interaction represents either a shift-left-click or a shift-right-click
126 | */
127 | public boolean isShiftClick() {
128 | return equals(SHIFT_LEFT_CLICK) || equals(SHIFT_RIGHT_CLICK);
129 | }
130 | }
131 | }
132 |
--------------------------------------------------------------------------------
/src/main/java/net/thenextlvl/service/api/chat/ChatController.java:
--------------------------------------------------------------------------------
1 | package net.thenextlvl.service.api.chat;
2 |
3 | import net.thenextlvl.service.api.Controller;
4 | import org.bukkit.OfflinePlayer;
5 | import org.bukkit.World;
6 | import org.jspecify.annotations.NullMarked;
7 |
8 | import java.util.Optional;
9 | import java.util.UUID;
10 | import java.util.concurrent.CompletableFuture;
11 |
12 | /**
13 | * The ChatController interface provides methods to retrieve a chat profile of a player.
14 | */
15 | @NullMarked
16 | public interface ChatController extends Controller {
17 | /**
18 | * Loads the chat profile for the given OfflinePlayer.
19 | *
20 | * @param player The OfflinePlayer whose ChatProfile is to be retrieved.
21 | * @return a CompletableFuture that will complete with the chat profile
22 | */
23 | default CompletableFuture