feat: add bundle behavior, terminal packets

Author: Ingrim4

src/main/java/dev/protocollib/Example.java

@@ -0,0 +1,102 @@
+package dev.protocollib;
+
+import org.bukkit.entity.Player;
+import org.bukkit.plugin.Plugin;
+import dev.protocollib.api.ProtocolLib;
+import dev.protocollib.api.listener.*;
+import dev.protocollib.api.packet.*;
+import java.util.concurrent.*;
+
+public class Example {
+ 
+    private static final ExecutorService EXECUTOR = Executors.newCachedThreadPool();
+    private static ProtocolLib protocolLib;
+    private static Plugin plugin;
+
+    // ========================
+    //  Packet Listeners
+    // ========================
+    
+    static void registerListeners() {
+        // sync read-only listener
+        protocolLib
+            .createListener(plugin)
+            .types(PacketTypes.Game.LEVEL_CHUNK)
+            .priority(PacketListenerPriority.LOW)
+            .includeCanceledPackets()
+            .bundleBehavior(PacketListenerBundleBehavior.SKIP_OUTSIDE_BUNDLE)
+            .registerSync((packet, context) -> {
+                Chunk chunk = Chunk.from(packet);
+                // Sync processing
+            });
+
+        // async modify packet on netty thread
+        protocolLib
+            .createListener(plugin)
+            .types(PacketTypes.Game.LEVEL_CHUNK)
+            .mutable()
+            .registerAsync((packet, context) -> {
+                Chunk chunk = Chunk.from(packet);
+                
+                // do processing here ...
+                // write changes to packet ...
+                
+                context.addTransmissionListener(chunk::markSent);
+                context.resumeProcessing();
+            });
+
+        // async modify packet on app thread-pool
+        protocolLib
+            .createListener(plugin)
+            .types(PacketTypes.Game.LEVEL_CHUNK)
+            .mutable()
+            .registerAsync((packet, context) -> {
+                Chunk chunk = Chunk.from(packet);
+
+                EXECUTOR.execute(() -> {
+                    
+                    // do heavy processing here ...
+                    // write changes to packet ...
+                    
+                    context.addTransmissionListener(chunk::markSent);
+                    context.resumeProcessing();
+                });
+            });
+    }
+
+    // ========================
+    //  Packet Sending
+    // ========================
+    
+    static void sendPackets(Player player, Chunk chunk) {
+        // full packet operation
+        protocolLib
+            .connection(player)
+            .packetOperation()
+            .skipProcessing()
+            .postTransmission(chunk::markSent)
+            .send(chunk.packet());
+
+        // connection shortcut
+        protocolLib
+            .connection(player)
+            .sendPacket(chunk.packet());
+
+        // direct API shortcut
+        protocolLib
+            .sendPacket(player, chunk.packet());
+    }
+
+    // ========================
+    //  Chunk Implementation
+    // ========================
+    
+    static class Chunk {
+        static Chunk from(PacketContainer packet) {
+            return new Chunk();
+        }
+        
+        PacketContainer packet() { return null; }
+        void markSent() {}
+    }
+}

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

@@ -5,6 +5,6 @@
  */
 public enum ProtocolPhase {
 
-    HANDSHAKE, PLAY, STATUS, LOGIN, CONFIGURATION, UNKNOWN;
+    HANDSHAKE, GAME, STATUS, LOGIN, CONFIGURATION, UNKNOWN;
 
 }

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

@@ -1,5 +1,7 @@
 package dev.protocollib.api.listener;
 
+import org.jetbrains.annotations.NotNull;
+
 import dev.protocollib.api.packet.PacketContainer;
 
 /**
@@ -27,6 +29,6 @@ public interface AsyncPacketListener {
      * @param packet  the packet to handle
      * @param context the context providing additional information about the packet and connection
      */
-    void handlePacket(PacketContainer packet, AsyncPacketListenerContext context);
+    void handlePacket(@NotNull PacketContainer packet, @NotNull AsyncPacketListenerContext context);
 
 }

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

@@ -1,5 +1,7 @@
 package dev.protocollib.api.listener;
 
+import org.jetbrains.annotations.NotNull;
+
 /**
  * Representing the context of an asynchronous packet listener.
  */
@@ -16,6 +18,6 @@ public interface AsyncPacketListenerContext extends SyncPacketListenerContext {
 	 * 
 	 * @param throwable the processing exception
 	 */
-	void resumeProcessingWithException(Throwable throwable);
+	void resumeProcessingWithException(@NotNull Throwable throwable);
 
 }

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

@@ -2,6 +2,9 @@
 
 import java.util.Collection;
 
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+
 import dev.protocollib.api.packet.PacketType;
 
 /**
@@ -15,15 +18,17 @@ public interface PacketListenerBuilder {
      * @param packetTypes the packet types to listen for
      * @return the same builder for further configuration
      */
-    PacketListenerBuilder.WithType types(PacketType... packetTypes);
+    @NotNull
+    PacketListenerBuilder.WithType types(@NotNull PacketType... packetTypes);
 
     /**
      * Specifies the types of packets to listen for.
      *
      * @param packetTypes the collection of packet types to listen for
      * @return the same builder for further configuration
      */
-    PacketListenerBuilder.WithType types(Collection<PacketType> packetTypes);
+    @NotNull
+    PacketListenerBuilder.WithType types(@NotNull Collection<PacketType> packetTypes);
 
     /**
      * Interface for building a packet listener with specific packet types.
@@ -36,22 +41,36 @@ public interface WithType {
          * @param priority the priority to assign to the listener
          * @return the same builder for further configuration
          */
-        PacketListenerBuilder.WithType priority(PacketListenerPriority priority);
+        @Contract("_ -> this")
+        PacketListenerBuilder.WithType priority(@NotNull PacketListenerPriority priority);
 
         /**
-         * Marks the listener as immutable, preventing modifications of packets
-         * inside the listener.
+         * Allows the listener to modify packets. By default, listeners are read-only and
+         * cannot modify packets.
          *
          * @return the same builder for further configuration
          */
-        PacketListenerBuilder.WithType immutable();
+        @Contract("_ -> this")
+        PacketListenerBuilder.WithType mutable();
 
         /**
-         * Configures the listener to ignore packets that have been cancelled.
+         * Configures the bundle behavior for the listener, determining how packets in bundles are handled.
          *
+         * @param bundleBehavior the bundle behavior to apply
          * @return the same builder for further configuration
+         * @see PacketListenerBundleBehavior
          */
-        PacketListenerBuilder.WithType ignoreCancelledPackets();
+        @Contract("_ -> this")
+        PacketListenerBuilder.WithType bundleBehavior(@NotNull PacketListenerBundleBehavior bundleBehavior);
+
+        /**
+         * Configures the listener to include packets that have been canceled. By default,
+         * canceled packets are skipped.
+         *
+         * @return the same builder for further configuration
+         */
+        @Contract("_ -> this")
+        PacketListenerBuilder.WithType includeCanceledPackets();
 
         /**
          * Registers the packet listener to operate synchronously. The listener
@@ -60,15 +79,16 @@ public interface WithType {
          * @param listener the synchronous packet listener to register
          * @return the same builder for further configuration
          */
-        PacketListenerRegistration registerSync(SyncPacketListener listener);
+        @NotNull
+        PacketListenerRegistration registerSync(@NotNull SyncPacketListener listener);
 
         /**
          * Registers the packet listener to operate asynchronously.
          *
          * @param listener the asynchronous packet listener to register
          * @return the same builder for further configuration
          */
-        PacketListenerRegistration registerAsync(AsyncPacketListener listener);
+        @NotNull
+        PacketListenerRegistration registerAsync(@NotNull AsyncPacketListener listener);
     }
 }
-

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

@@ -0,0 +1,31 @@
+package dev.protocollib.api.listener;
+
+/**
+ * Controls packet processing behavior relative to packet bundles (groups of
+ * packets processed atomically).
+ * <p>
+ * Determines whether individual packets should be processed or ignored based on
+ * their membership in a packet bundle. Packet bundles typically represent
+ * groups of packets that are be processed together as an atomic unit.
+ * </p>
+ */
+public enum PacketListenerBundleBehavior {
+
+    /**
+     * Processes all packets unconditionally, regardless of whether they are part of
+     * a packet bundle.
+     */
+    ALWAYS,
+
+    /**
+     * Processes only packets that exist outside of packet bundles, ignoring those
+     * inside bundles.
+     */
+    SKIP_INSIDE_BUNDLE,
+
+    /**
+     * Processes only packets that are part of packet bundles, ignoring standalone
+     * packets.
+     */
+    SKIP_OUTSIDE_BUNDLE;
+}

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

@@ -11,4 +11,3 @@ public interface PacketListenerRegistration {
      */
     void unregister();
 }
-

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

@@ -15,4 +15,3 @@ public interface PacketTransmissionListener {
      */
     void invoke();
 }
-

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

@@ -1,5 +1,7 @@
 package dev.protocollib.api.listener;
 
+import org.jetbrains.annotations.NotNull;
+
 import dev.protocollib.api.packet.PacketContainer;
 
 /**
@@ -14,6 +16,6 @@ public interface SyncPacketListener {
      * @param packet  the packet to handle
      * @param context the context providing additional information about the packet and functions
      */
-    void handlePacket(PacketContainer packet, SyncPacketListenerContext context);
+    void handlePacket(@NotNull PacketContainer packet, @NotNull SyncPacketListenerContext context);
 
 }

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

@@ -1,5 +1,7 @@
 package dev.protocollib.api.listener;
 
+import org.jetbrains.annotations.NotNull;
+
 import dev.protocollib.api.Connection;
 
 /**
@@ -12,6 +14,7 @@ public interface SyncPacketListenerContext {
      *
      * @return the connection handling the packet
      */
+    @NotNull
     Connection connection();
 
     /**
@@ -22,15 +25,17 @@ public interface SyncPacketListenerContext {
     boolean isCancelled();
 
     /**
-     * Cancels the packet, preventing it from being processed further.
+     * Sets whether the packet handling is cancelled. If cancelled, the packet
+     * will not be processed further.
+     *
+     * @param cancelled true to cancel the packet, false to allow processing
      */
-    void cancel();
+    void setCancelled(boolean cancelled);
 
     /**
      * Adds a listener to be invoked after the packet is sent or received.
      *
      * @param listener the transmission listener to invoke
      */
-    void addTransmissionListener(PacketTransmissionListener listener);
+    void addTransmissionListener(@NotNull PacketTransmissionListener listener);
 }
-