Perf/optimize packet listener

gradle.properties

@@ -7,6 +7,6 @@ org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
 javaVersion=25
 mcVersion=1.21.11
 group=dev.slne.surf
-version=1.21.11-2.68.0
+version=1.21.11-2.69.0
 relocationPrefix=dev.slne.surf.surfapi.libs
 snapshot=false

surf-api-bukkit/surf-api-bukkit-api/api/surf-api-bukkit-api.api

@@ -2073,6 +2073,7 @@ public final class dev/slne/surf/surfapi/bukkit/api/nms/bridges/packets/player/t
 
 public abstract interface class dev/slne/surf/surfapi/bukkit/api/nms/listener/NmsClientboundPacketListener : dev/slne/surf/surfapi/bukkit/api/nms/listener/NmsPacketListener {
 	public abstract fun handleClientboundPacket (Ldev/slne/surf/surfapi/bukkit/api/nms/listener/packets/NmsPacket;Lorg/bukkit/entity/Player;)Ldev/slne/surf/surfapi/bukkit/api/packet/listener/listener/PacketListenerResult;
+	public fun handleEarlyClientboundPacket (Ldev/slne/surf/surfapi/bukkit/api/nms/listener/packets/NmsPacket;Lorg/bukkit/entity/Player;)Ldev/slne/surf/surfapi/bukkit/api/packet/listener/listener/PacketListenerResult;
 }
 
 public abstract interface class dev/slne/surf/surfapi/bukkit/api/nms/listener/NmsPacketListener {

surf-api-bukkit/surf-api-bukkit-api/src/main/java/dev/slne/surf/surfapi/bukkit/api/nms/listener/NmsClientboundPacketListener.java

@@ -4,10 +4,28 @@
 import dev.slne.surf.surfapi.bukkit.api.nms.listener.packets.NmsPacket;
 import dev.slne.surf.surfapi.bukkit.api.packet.listener.listener.PacketListenerResult;
 import org.bukkit.entity.Player;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 @NmsUseWithCaution
+@NullMarked
 public interface NmsClientboundPacketListener<Packet extends NmsPacket> extends
-    NmsPacketListener<Packet> {
+        NmsPacketListener<Packet> {
 
-  PacketListenerResult handleClientboundPacket(Packet packet, Player player);
+    @ApiStatus.OverrideOnly
+    PacketListenerResult handleClientboundPacket(Packet packet, Player player);
+
+    @ApiStatus.OverrideOnly
+    default PacketListenerResult handleEarlyClientboundPacket(Packet packet, @Nullable Player player) {
+        if (player != null) {
+            return handleClientboundPacket(packet, player);
+        } else {
+            throw new IllegalStateException(
+                    "No player is available for this clientbound packet yet. " +
+                            "This can happen during early connection phases such as login. " +
+                            "Override handleEarlyClientboundPacket(...) if your listener should handle packets before a Player exists."
+            );
+        }
+    }
 }

surf-api-bukkit/surf-api-bukkit-api/src/main/java/dev/slne/surf/surfapi/bukkit/api/nms/listener/NmsPacketListener.java

@@ -3,14 +3,20 @@
 import com.google.common.reflect.TypeToken;
 import dev.slne.surf.surfapi.bukkit.api.nms.NmsUseWithCaution;
 import dev.slne.surf.surfapi.bukkit.api.nms.listener.packets.NmsPacket;
+import dev.slne.surf.surfapi.shared.api.util.InternalSurfApi;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
 
 @NmsUseWithCaution
+@NullMarked
 public interface NmsPacketListener<Packet extends NmsPacket> {
 
-  default Class<? super Packet> getPacketClass() {
-    TypeToken<Packet> typeToken = new TypeToken<Packet>(getClass()) {
-    };
+    @ApiStatus.Internal
+    @InternalSurfApi
+    default Class<? super Packet> getPacketClass() {
+        TypeToken<Packet> typeToken = new TypeToken<Packet>(getClass()) {
+        };
 
-    return typeToken.getRawType();
-  }
+        return typeToken.getRawType();
+    }
 }

surf-api-bukkit/surf-api-bukkit-api/src/main/java/dev/slne/surf/surfapi/bukkit/api/nms/listener/NmsServerboundPacketListener.java

@@ -5,9 +5,11 @@
 import dev.slne.surf.surfapi.bukkit.api.packet.listener.listener.PacketListenerResult;
 import org.bukkit.entity.Player;
 import org.jetbrains.annotations.ApiStatus.OverrideOnly;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 @NmsUseWithCaution
+@NullMarked
 public interface NmsServerboundPacketListener<Packet extends NmsPacket> extends
         NmsPacketListener<Packet> {
 
@@ -19,7 +21,11 @@ default PacketListenerResult handleEarlyServerboundPacket(Packet packet, @Nullab
         if (player != null) {
             return handleServerboundPacket(packet, player);
         } else {
-            return PacketListenerResult.CONTINUE;
+            throw new IllegalStateException(
+                    "No player is available for this serverbound packet yet. " +
+                            "This can happen during early connection phases such as login. " +
+                            "Override handleEarlyServerboundPacket(...) if your listener should handle packets before a Player exists."
+            );
         }
     }
 }

surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/impl/nms/SurfBukkitNmsBridgeImpl.kt

@@ -84,7 +84,15 @@ class SurfBukkitNmsBridgeImpl : SurfBukkitNmsBridge {
         var cancel = false
         for (listener in listener) {
             listener as NmsServerboundPacketListener<Packet>
-            val result = listener.handleEarlyServerboundPacket(packet, player)
+            val result = try {
+                listener.handleEarlyServerboundPacket(packet, player)
+            } catch (e: Throwable) {
+                log.atSevere()
+                    .withCause(e)
+                    .log("Failed to handle serverbound packet")
+                PacketListenerResult.CONTINUE
+            }
+
             if (result == PacketListenerResult.CANCEL) {
                 cancel = true
             }
@@ -96,7 +104,7 @@ class SurfBukkitNmsBridgeImpl : SurfBukkitNmsBridge {
     @Suppress("UNCHECKED_CAST")
     fun <Packet : NmsClientboundPacket> handleClientboundPacket(
         packet: Packet,
-        player: Player,
+        player: Player?,
     ): Packet? {
         val listeners = clientboundPacketListeners[packet.packetClass] ?: return packet
 
@@ -105,7 +113,15 @@ class SurfBukkitNmsBridgeImpl : SurfBukkitNmsBridge {
         var cancel = false
         for (listener in listeners) {
             listener as NmsClientboundPacketListener<Packet>
-            val result = listener.handleClientboundPacket(packet, player)
+            val result = try {
+                listener.handleEarlyClientboundPacket(packet, player)
+            } catch (e: Throwable) {
+                log.atSevere()
+                    .withCause(e)
+                    .log("Failed to handle clientbound packet")
+                PacketListenerResult.CONTINUE
+            }
+
             if (result == PacketListenerResult.CANCEL) {
                 cancel = true
             }