Party chat (#299)

api/src/main/java/net/draycia/carbon/api/event/events/PartyJoinEvent.java

@@ -0,0 +1,58 @@
+/*
+ * CarbonChat
+ *
+ * Copyright (c) 2023 Josua Parks (Vicarious)
+ *                    Contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package net.draycia.carbon.api.event.events;
+
+import java.util.UUID;
+import net.draycia.carbon.api.event.CarbonEvent;
+import net.draycia.carbon.api.users.CarbonPlayer;
+import net.draycia.carbon.api.users.Party;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.framework.qual.DefaultQualifier;
+
+/**
+ * Called when a player is added to a {@link Party}.
+ *
+ * @since 2.1.0
+ */
+@DefaultQualifier(NonNull.class)
+public interface PartyJoinEvent extends CarbonEvent {
+
+    /**
+     * ID of the player joining a party.
+     *
+     * <p>The player's {@link CarbonPlayer#party()} field is not guaranteed to be updated immediately,
+     * especially if the change needs to propagate cross-server.</p>
+     *
+     * @return player id
+     * @since 2.1.0
+     */
+    UUID playerId();
+
+    /**
+     * The party being joined.
+     *
+     * <p>{@link Party#members()} will reflect the new member.</p>
+     *
+     * @return party
+     * @since 2.1.0
+     */
+    Party party();
+
+}

api/src/main/java/net/draycia/carbon/api/event/events/PartyLeaveEvent.java

@@ -0,0 +1,58 @@
+/*
+ * CarbonChat
+ *
+ * Copyright (c) 2023 Josua Parks (Vicarious)
+ *                    Contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package net.draycia.carbon.api.event.events;
+
+import java.util.UUID;
+import net.draycia.carbon.api.event.CarbonEvent;
+import net.draycia.carbon.api.users.CarbonPlayer;
+import net.draycia.carbon.api.users.Party;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.framework.qual.DefaultQualifier;
+
+/**
+ * Called when a player is removed from a {@link Party}.
+ *
+ * @since 2.1.0
+ */
+@DefaultQualifier(NonNull.class)
+public interface PartyLeaveEvent extends CarbonEvent {
+
+    /**
+     * ID of the player leaving a party.
+     *
+     * <p>The player's {@link CarbonPlayer#party()} field is not guaranteed to be updated immediately,
+     * especially if the change needs to propagate cross-server.</p>
+     *
+     * @return player id
+     * @since 2.1.0
+     */
+    UUID playerId();
+
+    /**
+     * The party being left.
+     *
+     * <p>{@link Party#members()} will reflect the removed member.</p>
+     *
+     * @return party
+     * @since 2.1.0
+     */
+    Party party();
+
+}

api/src/main/java/net/draycia/carbon/api/users/CarbonPlayer.java

@@ -23,6 +23,7 @@
 import java.util.Locale;
 import java.util.Set;
 import java.util.UUID;
+import java.util.concurrent.CompletableFuture;
 import net.draycia.carbon.api.channels.ChatChannel;
 import net.draycia.carbon.api.util.InventorySlot;
 import net.kyori.adventure.audience.Audience;
@@ -248,7 +249,7 @@ record ChannelMessage(Component message, ChatChannel channel) {}
     /**
      * Adds the player to and removes the player from the ignore list.
      *
-     * @param player the player to be added/removed
+     * @param player      the player to be added/removed
      * @param nowIgnoring if the player should be ignored
      * @since 2.0.0
      */
@@ -257,7 +258,7 @@ record ChannelMessage(Component message, ChatChannel channel) {}
     /**
      * Adds the player to and removes the player from the ignore list.
      *
-     * @param player the player to be added/removed
+     * @param player      the player to be added/removed
      * @param nowIgnoring if the player should be ignored
      * @since 2.0.0
      */
@@ -404,4 +405,12 @@ record ChannelMessage(Component message, ChatChannel channel) {}
      */
     void leaveChannel(ChatChannel channel);
 
+    /**
+     * Get this player's current {@link Party}.
+     *
+     * @return party future
+     * @since 2.1.0
+     */
+    CompletableFuture<@Nullable Party> party();
+
 }

api/src/main/java/net/draycia/carbon/api/users/Party.java

@@ -0,0 +1,85 @@
+/*
+ * CarbonChat
+ *
+ * Copyright (c) 2023 Josua Parks (Vicarious)
+ *                    Contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package net.draycia.carbon.api.users;
+
+import java.util.Set;
+import java.util.UUID;
+import net.kyori.adventure.text.Component;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.framework.qual.DefaultQualifier;
+
+/**
+ * Reference to a chat party.
+ *
+ * @see UserManager#createParty(Component)
+ * @see UserManager#party(UUID)
+ * @since 2.1.0
+ */
+@DefaultQualifier(NonNull.class)
+public interface Party {
+
+    /**
+     * Get the name of this party.
+     *
+     * @return party name
+     * @since 2.1.0
+     */
+    Component name();
+
+    /**
+     * Get the unique id of this party.
+     *
+     * @return party id
+     * @since 2.1.0
+     */
+    UUID id();
+
+    /**
+     * Get a snapshot of the current party members.
+     *
+     * @return party members
+     * @since 2.1.0
+     */
+    Set<UUID> members();
+
+    /**
+     * Add a user to this party. They will automatically be removed from their previous party if necessary.
+     *
+     * @param id user id
+     * @since 2.1.0
+     */
+    void addMember(UUID id);
+
+    /**
+     * Remove a user from this party.
+     *
+     * @param id user id
+     * @since 2.1.0
+     */
+    void removeMember(UUID id);
+
+    /**
+     * Disband this party. Will remove all members and delete persistent data.
+     *
+     * @since 2.1.0
+     */
+    void disband();
+
+}

api/src/main/java/net/draycia/carbon/api/users/UserManager.java

@@ -21,7 +21,9 @@
 
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
+import net.kyori.adventure.text.Component;
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 import org.checkerframework.framework.qual.DefaultQualifier;
 
 /**
@@ -45,4 +47,29 @@ public interface UserManager<C extends CarbonPlayer> {
      */
     CompletableFuture<C> user(UUID uuid);
 
+    /**
+     * Create a new {@link Party} with the specified name.
+     *
+     * <p>Parties with no users will not be saved. Use {@link Party#disband()} to discard.</p>
+     * <p>The returned reference will expire after one minute, store {@link Party#id()} rather than the instance and use {@link #party(UUID)} to retrieve.</p>
+     *
+     * @param name party name
+     * @return new party
+     * @since 2.1.0
+     */
+    Party createParty(Component name);
+
+    /**
+     * Look up an existing party by its id.
+     *
+     * <p>As parties that have never had a user are not saved, they are not retrievable here.</p>
+     * <p>The returned reference will expire after one minute, do not cache it. The implementation handles caching as is appropriate.</p>
+     *
+     * @param id party id
+     * @return existing party
+     * @see #createParty(Component)
+     * @since 2.1.0
+     */
+    CompletableFuture<@Nullable Party> party(UUID id);
+
 }

common/src/main/java/net/draycia/carbon/common/CarbonCommonModule.java

@@ -58,12 +58,14 @@
 import net.draycia.carbon.common.messages.CarbonMessageSender;
 import net.draycia.carbon.common.messages.CarbonMessageSource;
 import net.draycia.carbon.common.messages.CarbonMessages;
+import net.draycia.carbon.common.messages.Option;
 import net.draycia.carbon.common.messages.SourcedReceiverResolver;
 import net.draycia.carbon.common.messages.StandardPlaceholderResolverStrategyButDifferent;
 import net.draycia.carbon.common.messages.placeholders.BooleanPlaceholderResolver;
 import net.draycia.carbon.common.messages.placeholders.ComponentPlaceholderResolver;
 import net.draycia.carbon.common.messages.placeholders.IntPlaceholderResolver;
 import net.draycia.carbon.common.messages.placeholders.KeyPlaceholderResolver;
+import net.draycia.carbon.common.messages.placeholders.OptionPlaceholderResolver;
 import net.draycia.carbon.common.messages.placeholders.StringPlaceholderResolver;
 import net.draycia.carbon.common.messages.placeholders.UUIDPlaceholderResolver;
 import net.draycia.carbon.common.messaging.ServerId;
@@ -160,6 +162,7 @@ public CarbonMessages carbonMessages(
             .weightedPlaceholderResolver(Integer.class, intPlaceholderResolver, 0)
             .weightedPlaceholderResolver(Key.class, keyPlaceholderResolver, 0)
             .weightedPlaceholderResolver(Boolean.class, booleanPlaceholderResolver, 0)
+            .weightedPlaceholderResolver(Option.class, new OptionPlaceholderResolver<>(), 0)
             .create(this.getClass().getClassLoader());
     }