feat(api): add send/receive packet methods

build.gradle

@@ -52,8 +52,8 @@ dependencies {
 }
 
 java {
-    sourceCompatibility = JavaVersion.VERSION_1_8
+    sourceCompatibility = JavaVersion.VERSION_17
-    targetCompatibility = JavaVersion.VERSION_1_8
+    targetCompatibility = JavaVersion.VERSION_17
 
     withJavadocJar()
     withSourcesJar()

src/main/java/dev/protocollib/api/Connection.java

@@ -5,24 +5,31 @@ import java.util.Optional;
 
 import org.bukkit.entity.Player;
 
-import dev.protocollib.api.listener.PacketSentListener;
+import dev.protocollib.api.packet.PacketLike;
+import dev.protocollib.api.packet.PacketOperationBuilder;
 
 /**
- * Representing a connection of a player.
+ * Represents a connection associated with a player.
+ * 
+ * <p>This interface provides methods to interact with the player's network connection,
+ * including retrieving the player's information, connection address, protocol version,
+ * and current connection state. It also allows for sending and receiving packets
+ * through the connection.</p>
  */
 public interface Connection {
 
+
     /**
      * Retrieves the player associated with the connection, if available.
      *
-     * @return an optional containing the player, or empty if the player is not present
+     * @return an {@link Optional} containing the player, or empty if the player is not present
      */
     Optional<Player> player();
 
     /**
      * Retrieves the address of the connection.
      *
-     * @return the remote address of the connection
+     * @return the remote {@link InetSocketAddress} of the connection
      */
     InetSocketAddress address();
 
@@ -37,53 +44,37 @@ public interface Connection {
      * Retrieves the current protocol phase of the connection for a given direction.
      *
      * @param packetDirection the direction of the packet (clientbound or serverbound)
-     * @return the protocol phase of the connection
+     * @return the {@link ProtocolPhase} representing the current phase of the connection
      */
     ProtocolPhase protocolPhase(ProtocolDirection packetDirection);
 
     /**
      * Checks if the connection is currently open.
      *
-     * @return true if the connection is open, false otherwise
+     * @return {@code true} if the connection is open, {@code false} otherwise
      */
     boolean isConnected();
 
     /**
-     * Sends a binary packet over the connection.
+     * Initiates a packet operation, which can involve sending or receiving a packet.
      *
-     * @param packet the binary packet to send
+     * @return a {@link PacketOperationBuilder} to configure the packet operation
      */
-    void sendPacket(BinaryPacket packet);
+    PacketOperationBuilder packetOperation();
 
     /**
-     * Sends a binary packet over the connection and registers a listener for when the packet is sent.
+     * Sends a packet to the client.
      *
-     * @param packet   the binary packet to send
+     * @param packet the packet to send
-     * @param listener the listener to invoke once the packet is sent
      */
-    void sendPacket(BinaryPacket packet, PacketSentListener listener);
+    void sendPacket(PacketLike packet);
 
     /**
-     * Sends a packet container over the connection.
+     * Receives a packet as if the client had sent it.
      *
-     * @param packet the packet container to send
+     * @param packet the received packet
      */
-    void sendPacket(PacketContainer packet);
+    void receivePacket(PacketLike packet);
-
-    /**
-     * Sends a packet container over the connection and registers a listener for when the packet is sent.
-     *
-     * @param packet   the packet container to send
-     * @param listener the listener to invoke once the packet is sent
-     */
-    void sendPacket(PacketContainer packet, PacketSentListener listener);
-
-    /**
-     * Receives a packet container from the connection.
-     *
-     * @param packet the packet container received
-     */
-    void receivePacket(PacketContainer packet);
 
     /**
      * Disconnects the connection with the specified reason.

src/main/java/dev/protocollib/api/ProtocolLib.java

@@ -4,6 +4,10 @@ import org.bukkit.entity.Player;
 import org.bukkit.plugin.Plugin;
 
 import dev.protocollib.api.listener.PacketListenerBuilder;
+import dev.protocollib.api.packet.BinaryPacket;
+import dev.protocollib.api.packet.PacketContainer;
+import dev.protocollib.api.packet.PacketLike;
+import dev.protocollib.api.packet.PacketType;
 
 /**
  * Representing the main entry point for the ProtocolLib API.
@@ -26,6 +30,24 @@ public interface ProtocolLib {
      */
     Connection connection(Player player);
 
+    /**
+     * Sends a packet to the player.
+     *
+     * @param packet the packet to send
+     */
+    default void sendPacket(Player player, PacketLike packet) {
+        connection(player).sendPacket(packet);
+    }
+
+    /**
+     * Receives a packet as if the player had sent it.
+     *
+     * @param packet the received packet
+     */
+    default void receivePacket(Player player, PacketLike packet) {
+        connection(player).receivePacket(packet);
+    }
+
     /**
      * Creates a new binary packet with the given type and payload.
      *

src/main/java/dev/protocollib/api/listener/AsyncPacketListener.java

@@ -1,6 +1,6 @@
 package dev.protocollib.api.listener;
 
-import dev.protocollib.api.PacketContainer;
+import dev.protocollib.api.packet.PacketContainer;
 
 /**
  * Functional interface for handling packets asynchronously.

src/main/java/dev/protocollib/api/listener/PacketListenerBuilder.java

@@ -2,7 +2,7 @@ package dev.protocollib.api.listener;
 
 import java.util.Collection;
 
-import dev.protocollib.api.PacketType;
+import dev.protocollib.api.packet.PacketType;
 
 /**
  * Builder for creating and registering packet listeners.

src/main/java/dev/protocollib/api/listener/PacketTransmissionListener.java

@@ -1,12 +1,14 @@
 package dev.protocollib.api.listener;
 
 /**
- * Functional interface for a listener that is invoked when a packet has been sent.
+ * Functional interface for a listener that is invoked when a packet has been sent
+ * (according to the underlying write's ChannelFuture) or received (just before the
+ * packet gets processed by mojangs packet handlers).
  * 
  * This method will get invoked on the underlying channel's event-loop.
  */
 @FunctionalInterface
-public interface PacketSentListener {
+public interface PacketTransmissionListener {
 
     /**
      * Invoked when a packet has been successfully sent.

src/main/java/dev/protocollib/api/listener/SyncPacketListener.java

@@ -1,6 +1,6 @@
 package dev.protocollib.api.listener;
 
-import dev.protocollib.api.PacketContainer;
+import dev.protocollib.api.packet.PacketContainer;
 
 /**
  * Functional interface for handling packets synchronously.

src/main/java/dev/protocollib/api/listener/SyncPacketListenerContext.java

@@ -27,10 +27,10 @@ public interface SyncPacketListenerContext {
     void cancel();
 
     /**
-     * Adds a listener to be invoked after the packet is sent.
+     * Adds a listener to be invoked after the packet is sent or received.
      *
-     * @param listener the post-sent listener
+     * @param listener the transmission listener to invoke
      */
-    void addPostSentListener(PacketSentListener listener);
+    void addTransmissionListener(PacketTransmissionListener listener);
 }
 

src/main/java/dev/protocollib/api/packet/BinaryPacket.java

@@ -1,9 +1,9 @@
-package dev.protocollib.api;
+package dev.protocollib.api.packet;
 
 /**
  * Representing a raw binary packet with a packet id and payload.
  */
-public interface BinaryPacket {
+public non-sealed interface BinaryPacket extends PacketLike {
 
     /**
      * Retrieves the packet id.
@@ -19,4 +19,3 @@ public interface BinaryPacket {
      */
     byte[] payload();
 }
-

src/main/java/dev/protocollib/api/packet/PacketContainer.java

@@ -1,9 +1,9 @@
-package dev.protocollib.api;
+package dev.protocollib.api.packet;
 
 /**
  * Representing a container for a packet.
  */
-public interface PacketContainer {
+public non-sealed interface PacketContainer extends PacketLike {
 
     /**
      * Retrieves the type of the packet.
@@ -19,4 +19,11 @@ public interface PacketContainer {
      */
     Object packet();
 
+    /**
+     * Creates and returns a mutable copy of this packet.
+     * 
+     * @return a clone of this instance.
+     */
+    PacketContainer clone();
+
 }

src/main/java/dev/protocollib/api/packet/PacketLike.java

@@ -0,0 +1,5 @@
+package dev.protocollib.api.packet;
+
+public sealed interface PacketLike permits BinaryPacket, PacketContainer {
+
+}

src/main/java/dev/protocollib/api/packet/PacketOperationBuilder.java

@@ -0,0 +1,44 @@
+package dev.protocollib.api.packet;
+
+import dev.protocollib.api.listener.PacketTransmissionListener;
+
+/**
+ * Builder interface for constructing packet operations.
+ * 
+ * <p>This interface provides methods to configure how packets are sent
+ * or received within ProtocolLib.</p>
+ */
+public interface PacketOperationBuilder {
+
+    /**
+     * Skips processing the packet in ProtocolLib's pipeline.
+     * 
+     * <p>This method allows the caller to prevent further handling of the packet 
+     * by other plugin listeners in the pipeline.</p>
+     *
+     * @return the same builder for further configuration
+     */
+    PacketOperationBuilder skipProcessing();
+
+    /**
+     * Registers a listener to be called once the packet has been sent or received.
+     * 
+     * @param listener the listener to be notified upon packet transmission
+     * @return the same builder for further configuration
+     */
+    PacketOperationBuilder postTransmission(PacketTransmissionListener listener);
+
+    /**
+     * Sends a packet to the client.
+     * 
+     * @param packet the {@link PacketContainer} to send
+     */
+    void send(PacketLike packet);
+
+    /**
+     * Receives a packet as if the client had sent it.
+     * 
+     * @param packet the {@link PacketContainer} to receive
+     */
+    void receive(PacketLike packet);
+}

src/main/java/dev/protocollib/api/packet/PacketType.java

@@ -1,7 +1,8 @@
-package dev.protocollib.api;
+package dev.protocollib.api.packet;
 
 import java.util.Optional;
 
+import dev.protocollib.api.ProtocolDirection;
 import net.kyori.adventure.key.Keyed;
 
 /**

src/main/java/dev/protocollib/api/packet/PacketTypes.java

@@ -1,4 +1,4 @@
-package dev.protocollib.api;
+package dev.protocollib.api.packet;
 
 public class PacketTypes {