Improved PluginMessaging API (#1254)

* Improved PluginMessaging API by adding a method to easily encode the data to be sent

* Added javadocs

* Implement PluginMessageEncoder

api/src/main/java/com/velocitypowered/api/proxy/Player.java

@@ -13,6 +13,7 @@ import com.velocitypowered.api.proxy.crypto.KeyIdentifiable;
 import com.velocitypowered.api.proxy.messages.ChannelIdentifier;
 import com.velocitypowered.api.proxy.messages.ChannelMessageSink;
 import com.velocitypowered.api.proxy.messages.ChannelMessageSource;
+import com.velocitypowered.api.proxy.messages.PluginMessageEncoder;
 import com.velocitypowered.api.proxy.player.PlayerSettings;
 import com.velocitypowered.api.proxy.player.ResourcePackInfo;
 import com.velocitypowered.api.proxy.player.TabList;
@@ -282,16 +283,42 @@ public interface Player extends
   @NotNull Collection<ResourcePackInfo> getPendingResourcePacks();
 
   /**
-   * <strong>Note that this method does not send a plugin message to the server the player
+   * {@inheritDoc}
+   *
+   * <p><strong>Note that this method does not send a plugin message to the server the player
    * is connected to.</strong> You should only use this method if you are trying to communicate
-   * with a mod that is installed on the player's client. To send a plugin message to the server
+   * with a mod that is installed on the player's client.</p>
+   *
+   * <p>To send a plugin message to the server
    * from the player, you should use the equivalent method on the instance returned by
    * {@link #getCurrentServer()}.
    *
-   * @inheritDoc
+   * <pre>
+   *    final ChannelIdentifier identifier;
+   *    final Player player;
+   *    player.getCurrentServer()
+   *          .map(ServerConnection::getServer)
+   *          .ifPresent((RegisteredServer server) -> {
+   *            server.sendPluginMessage(identifier, data);
+   *          });
+   *  </pre>
+   *
    */
   @Override
-  boolean sendPluginMessage(@NotNull ChannelIdentifier identifier, byte @NotNull[] data);
+  boolean sendPluginMessage(@NotNull ChannelIdentifier identifier, byte @NotNull [] data);
+
+  /**
+   * {@inheritDoc}
+   * <p><strong>Note that this method does not send a plugin message to the server the player
+   * is connected to.</strong> You should only use this method if you are trying to communicate
+   * with a mod that is installed on the player's client.</p>
+   *
+   * <p>To send a plugin message to the server
+   * from the player, you should use the equivalent method on the instance returned by
+   * {@link #getCurrentServer()}.
+   */
+  @Override
+  boolean sendPluginMessage(@NotNull ChannelIdentifier identifier, @NotNull PluginMessageEncoder dataEncoder);
 
   @Override
   default @NotNull Key key() {

api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelMessageSink.java

@@ -7,6 +7,9 @@
 
 package com.velocitypowered.api.proxy.messages;
 
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
 /**
  * Represents something that can be sent plugin messages.
  */
@@ -19,5 +22,26 @@ public interface ChannelMessageSink {
    * @param data the data to send
    * @return whether or not the message could be sent
    */
-  boolean sendPluginMessage(ChannelIdentifier identifier, byte[] data);
+  boolean sendPluginMessage(@NotNull ChannelIdentifier identifier, byte @NotNull[] data);
+
+  /**
+   * Sends a plugin message to this target.
+   *
+   * <pre>
+   *   final ChannelMessageSink target;
+   *   final ChannelIdentifier identifier;
+   *   final boolean result = target.sendPluginMessage(identifier, (output) -> {
+   *     output.writeUTF("some input");
+   *     output.writeInt(1);
+   *   });
+   * </pre>
+   *
+   * @param identifier the channel identifier to send the message on
+   * @param dataEncoder the encoder of the data to be sent
+   * @return whether the message could be sent
+   */
+  @ApiStatus.Experimental
+  boolean sendPluginMessage(
+          @NotNull ChannelIdentifier identifier,
+          @NotNull PluginMessageEncoder dataEncoder);
 }

api/src/main/java/com/velocitypowered/api/proxy/messages/PluginMessageEncoder.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright (C) 2024 Velocity Contributors
+ *
+ * The Velocity API is licensed under the terms of the MIT License. For more details,
+ * reference the LICENSE file in the api top-level directory.
+ */
+
+package com.velocitypowered.api.proxy.messages;
+
+import com.google.common.io.ByteArrayDataOutput;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * A data encoder to be sent via a plugin message.
+ *
+ * @since 3.3.0
+ */
+@FunctionalInterface
+@ApiStatus.Experimental
+public interface PluginMessageEncoder {
+
+  /**
+   * Encodes data into a {@link ByteArrayDataOutput} to be transmitted by plugin messages.
+   *
+   * @param output the {@link ByteArrayDataOutput} provided
+   */
+  void encode(@NotNull ByteArrayDataOutput output);
+}