feat: Introduce party and chat channel systems with related events and services

Author: ItsHarshXD

build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 }
 
 group = "com.github.ItsHarshXD"
-version = "90.1.0"
+version = "1.1.0"
 
 java {
     sourceCompatibility = JavaVersion.VERSION_21

src/main/java/dev/itsharshxd/zentrix/api/ZentrixAPI.java

@@ -2,12 +2,14 @@
 
 import dev.itsharshxd.zentrix.api.addon.AddonManager;
 import dev.itsharshxd.zentrix.api.broadcast.BroadcastService;
+import dev.itsharshxd.zentrix.api.chat.ChatChannelService;
 import dev.itsharshxd.zentrix.api.classes.ClassService;
 import dev.itsharshxd.zentrix.api.currency.CurrencyService;
 import dev.itsharshxd.zentrix.api.data.DataService;
 import dev.itsharshxd.zentrix.api.game.GameService;
 import dev.itsharshxd.zentrix.api.gametype.GameTypeService;
 import dev.itsharshxd.zentrix.api.item.ItemService;
+import dev.itsharshxd.zentrix.api.party.PartyService;
 import dev.itsharshxd.zentrix.api.phase.PhaseService;
 import dev.itsharshxd.zentrix.api.player.PlayerService;
 import dev.itsharshxd.zentrix.api.profile.ProfileService;
@@ -46,6 +48,8 @@
  *   <li>{@link BroadcastService} - Broadcast registration and management (since 1.1.0)</li>
  *   <li>{@link GameTypeService} - Game type registration and management (since 1.1.0)</li>
  *   <li>{@link ItemService} - Item registration and management (since 1.1.0)</li>
+ *   <li>{@link PartyService} - Party system operations (since 1.2.0)</li>
+ *   <li>{@link ChatChannelService} - Chat channel management (since 1.2.0)</li>
  * </ul>
  *
  * @author ItsHarshXD
@@ -326,4 +330,38 @@ static boolean isAvailable() {
      */
     @NotNull
     ItemService getItemService();
+
+    /**
+     * Gets the party service for party system operations.
+     * <p>
+     * Use this service to:
+     * <ul>
+     *   <li>Query party state and membership</li>
+     *   <li>Create, disband, and manage parties</li>
+     *   <li>Invite, kick, and promote members</li>
+     * </ul>
+     * </p>
+     *
+     * @return The party service instance
+     * @since 1.2.0
+     */
+    @NotNull
+    PartyService getPartyService();
+
+    /**
+     * Gets the chat channel service for chat channel management.
+     * <p>
+     * Use this service to:
+     * <ul>
+     *   <li>Get and set player chat channels</li>
+     *   <li>Toggle between available channels</li>
+     *   <li>Check channel availability (team, party)</li>
+     * </ul>
+     * </p>
+     *
+     * @return The chat channel service instance
+     * @since 1.2.0
+     */
+    @NotNull
+    ChatChannelService getChatChannelService();
 }

src/main/java/dev/itsharshxd/zentrix/api/chat/ChatChannel.java

@@ -0,0 +1,65 @@
+package dev.itsharshxd.zentrix.api.chat;
+
+/**
+ * Represents the available chat channels for players.
+ * <p>
+ * Players can switch between chat channels to communicate with
+ * different groups:
+ * <ul>
+ *   <li>{@link #GLOBAL} - All players can see messages</li>
+ *   <li>{@link #TEAM} - Only teammates in the same game can see messages</li>
+ *   <li>{@link #PARTY} - Only party members can see messages</li>
+ * </ul>
+ * </p>
+ *
+ * @author ItsHarshXD
+ * @since 1.2.0
+ */
+public enum ChatChannel {
+
+    /**
+     * Global chat channel. Messages are visible to all players.
+     */
+    GLOBAL("global"),
+
+    /**
+     * Team chat channel. Messages are visible only to teammates in the same game.
+     */
+    TEAM("team"),
+
+    /**
+     * Party chat channel. Messages are visible only to party members.
+     */
+    PARTY("party");
+
+    private final String id;
+
+    ChatChannel(String id) {
+        this.id = id;
+    }
+
+    /**
+     * Gets the string identifier for this channel.
+     *
+     * @return The channel ID (e.g., "global", "team", "party")
+     */
+    public String getId() {
+        return id;
+    }
+
+    /**
+     * Gets a ChatChannel by its ID (case-insensitive).
+     *
+     * @param id The channel ID
+     * @return The ChatChannel, or {@link #GLOBAL} if not found or null
+     */
+    public static ChatChannel fromId(String id) {
+        if (id == null) return GLOBAL;
+        for (ChatChannel channel : values()) {
+            if (channel.id.equalsIgnoreCase(id)) {
+                return channel;
+            }
+        }
+        return GLOBAL;
+    }
+}

src/main/java/dev/itsharshxd/zentrix/api/chat/ChatChannelService.java

@@ -0,0 +1,106 @@
+package dev.itsharshxd.zentrix.api.chat;
+
+import org.bukkit.entity.Player;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.UUID;
+
+/**
+ * Service for managing player chat channels in Zentrix.
+ * <p>
+ * Players can switch between global, team, and party chat channels.
+ * Channel availability depends on the player's current state (in-game,
+ * in a party, etc.).
+ * </p>
+ *
+ * <h2>Example Usage</h2>
+ * <pre>{@code
+ * ChatChannelService chatService = ZentrixAPI.get().getChatChannelService();
+ *
+ * // Get a player's current channel
+ * ChatChannel channel = chatService.getChannel(player);
+ *
+ * // Switch to team chat
+ * if (chatService.canUseTeamChat(player)) {
+ *     chatService.setChannel(player, ChatChannel.TEAM);
+ * }
+ *
+ * // Toggle through available channels
+ * ChatChannel newChannel = chatService.toggleChannel(player);
+ * player.sendMessage("Switched to " + newChannel.getId() + " chat");
+ * }</pre>
+ *
+ * @author ItsHarshXD
+ * @since 1.2.0
+ */
+public interface ChatChannelService {
+
+    /**
+     * Gets a player's current chat channel.
+     *
+     * @param player The player
+     * @return The player's current chat channel (defaults to {@link ChatChannel#GLOBAL})
+     */
+    @NotNull
+    ChatChannel getChannel(@NotNull Player player);
+
+    /**
+     * Gets a player's current chat channel by UUID.
+     *
+     * @param playerId The player's UUID
+     * @return The player's current chat channel (defaults to {@link ChatChannel#GLOBAL})
+     */
+    @NotNull
+    ChatChannel getChannel(@NotNull UUID playerId);
+
+    /**
+     * Sets a player's chat channel.
+     *
+     * @param player  The player
+     * @param channel The channel to set
+     */
+    void setChannel(@NotNull Player player, @NotNull ChatChannel channel);
+
+    /**
+     * Toggles a player's chat channel to the next available channel.
+     * <p>
+     * Cycle order: GLOBAL &rarr; TEAM &rarr; PARTY &rarr; GLOBAL,
+     * skipping channels that are not currently available to the player.
+     * </p>
+     *
+     * @param player The player
+     * @return The new chat channel after toggling
+     */
+    @NotNull
+    ChatChannel toggleChannel(@NotNull Player player);
+
+    /**
+     * Resets a player's chat channel back to {@link ChatChannel#GLOBAL}.
+     *
+     * @param player The player
+     */
+    void resetChannel(@NotNull Player player);
+
+    /**
+     * Checks if a player can use team chat.
+     * <p>
+     * Team chat requires the player to be in a game with a team size greater
+     * than 1 and not be a spectator.
+     * </p>
+     *
+     * @param player The player
+     * @return {@code true} if team chat is available
+     */
+    boolean canUseTeamChat(@NotNull Player player);
+
+    /**
+     * Checks if a player can use party chat.
+     * <p>
+     * Party chat requires the player to be in a party.
+     * </p>
+     *
+     * @param player The player
+     * @return {@code true} if party chat is available
+     */
+    boolean canUsePartyChat(@NotNull Player player);
+}

src/main/java/dev/itsharshxd/zentrix/api/events/chat/ChatChannelSwitchEvent.java

@@ -0,0 +1,124 @@
+package dev.itsharshxd.zentrix.api.events.chat;
+
+import dev.itsharshxd.zentrix.api.chat.ChatChannel;
+import dev.itsharshxd.zentrix.api.events.ZentrixEvent;
+import org.bukkit.entity.Player;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.UUID;
+
+/**
+ * Called when a player switches their chat channel.
+ * <p>
+ * This event is <b>cancellable</b>. Cancelling prevents the channel change.
+ * </p>
+ *
+ * <h2>Example Usage</h2>
+ * <pre>{@code
+ * @EventHandler
+ * public void onChannelSwitch(ChatChannelSwitchEvent event) {
+ *     if (event.getNewChannel() == ChatChannel.PARTY) {
+ *         // Block switching to party chat for certain players
+ *         if (!hasPermission(event.getPlayer())) {
+ *             event.setCancelled(true);
+ *         }
+ *     }
+ * }
+ * }</pre>
+ *
+ * @author ItsHarshXD
+ * @since 1.2.0
+ */
+public class ChatChannelSwitchEvent extends ZentrixEvent implements Cancellable {
+
+    private static final HandlerList HANDLERS = new HandlerList();
+
+    private final Player player;
+    private final ChatChannel oldChannel;
+    private ChatChannel newChannel;
+    private boolean cancelled;
+
+    public ChatChannelSwitchEvent(@NotNull Player player,
+                                  @NotNull ChatChannel oldChannel,
+                                  @NotNull ChatChannel newChannel) {
+        super(false);
+        this.player = player;
+        this.oldChannel = oldChannel;
+        this.newChannel = newChannel;
+        this.cancelled = false;
+    }
+
+    /**
+     * Gets the player switching channels.
+     *
+     * @return The player
+     */
+    @NotNull
+    public Player getPlayer() {
+        return player;
+    }
+
+    /**
+     * Gets the player's UUID.
+     *
+     * @return The player's UUID
+     */
+    @NotNull
+    public UUID getPlayerId() {
+        return player.getUniqueId();
+    }
+
+    /**
+     * Gets the channel the player is switching from.
+     *
+     * @return The old/current channel
+     */
+    @NotNull
+    public ChatChannel getOldChannel() {
+        return oldChannel;
+    }
+
+    /**
+     * Gets the channel the player is switching to.
+     *
+     * @return The new channel
+     */
+    @NotNull
+    public ChatChannel getNewChannel() {
+        return newChannel;
+    }
+
+    /**
+     * Sets the channel the player will switch to.
+     * <p>
+     * This allows addons to redirect channel switches.
+     * </p>
+     *
+     * @param newChannel The new target channel
+     */
+    public void setNewChannel(@NotNull ChatChannel newChannel) {
+        this.newChannel = newChannel;
+    }
+
+    @Override
+    public boolean isCancelled() {
+        return cancelled;
+    }
+
+    @Override
+    public void setCancelled(boolean cancel) {
+        this.cancelled = cancel;
+    }
+
+    @NotNull
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLERS;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLERS;
+    }
+}

src/main/java/dev/itsharshxd/zentrix/api/events/currency/CurrencyChangeEvent.java

@@ -13,7 +13,7 @@
 /**
  * Called when a player's currency balance is about to change.
  * <p>
- * This event is fired before the balance modification is applied, allowing
+ * This event is fired <b>before</b> the balance modification is applied, allowing
  * addons to:
  * <ul>
  *   <li>Cancel the change entirely</li>