Enhance PacketLoreListener with improved lore and snapshot management

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.65.0
+version=1.21.11-2.66.0
 relocationPrefix=dev.slne.surf.surfapi.libs
 snapshot=false

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

@@ -2155,8 +2155,10 @@ public abstract interface class dev/slne/surf/surfapi/bukkit/api/nms/listener/pa
 public abstract interface class dev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi {
 	public static final field Companion Ldev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi$Companion;
 	public static fun getInstance ()Ldev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi;
-	public abstract fun registerPacketLoreListener (Lorg/bukkit/NamespacedKey;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandler;)V
+	public fun registerPacketLoreListener (Lorg/bukkit/NamespacedKey;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandler;)V
 	public fun registerPacketLoreListener (Lorg/bukkit/NamespacedKey;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandlerSimple;)V
+	public abstract fun registerPacketLoreListener (Lorg/bukkit/plugin/Plugin;Lorg/bukkit/NamespacedKey;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandler;)V
+	public fun registerPacketLoreListener (Lorg/bukkit/plugin/Plugin;Lorg/bukkit/NamespacedKey;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandlerSimple;)V
 	public abstract fun registerPacketLoreListenerGlobal (Lorg/bukkit/plugin/Plugin;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandler;)V
 	public fun registerPacketLoreListenerGlobal (Lorg/bukkit/plugin/Plugin;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandlerSimple;)V
 	public abstract fun unregisterPacketLoreListener (Lorg/bukkit/NamespacedKey;)V
@@ -2168,7 +2170,9 @@ public final class dev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi$C
 }
 
 public final class dev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi$DefaultImpls {
+	public static fun registerPacketLoreListener (Ldev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi;Lorg/bukkit/NamespacedKey;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandler;)V
 	public static fun registerPacketLoreListener (Ldev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi;Lorg/bukkit/NamespacedKey;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandlerSimple;)V
+	public static fun registerPacketLoreListener (Ldev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi;Lorg/bukkit/plugin/Plugin;Lorg/bukkit/NamespacedKey;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandlerSimple;)V
 	public static fun registerPacketLoreListenerGlobal (Ldev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi;Lorg/bukkit/plugin/Plugin;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandlerSimple;)V
 }
 

surf-api-bukkit/surf-api-bukkit-api/src/main/kotlin/dev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi.kt

@@ -2,81 +2,126 @@ package dev.slne.surf.surfapi.bukkit.api.packet
 
 import dev.slne.surf.surfapi.bukkit.api.packet.lore.SurfBukkitPacketLoreHandler
 import dev.slne.surf.surfapi.bukkit.api.packet.lore.SurfBukkitPacketLoreHandlerSimple
+import dev.slne.surf.surfapi.bukkit.api.util.getCallingPlugin
 import dev.slne.surf.surfapi.core.api.util.requiredService
 import org.bukkit.NamespacedKey
 import org.bukkit.plugin.Plugin
 
 /**
  * The SurfBukkitPacketApi interface extends packet handling capabilities for Bukkit environments.
  *
- * It provides methods for registering and unregistering lore listeners, enabling dynamic modification
- * of item stack lore based on custom logic. It also includes global registration methods for listening
- * to all items and utilities for managing these listeners efficiently.
+ * Provides methods for registering and unregistering lore listeners, enabling dynamic modification
+ * of item stack lore based on custom logic. Includes global registration for all items and utilities
+ * for managing these listeners efficiently.
  *
- * This API allows developers to enhance item lore dynamically, providing a flexible system for plugins
- * that need to alter or interact with lore without directly modifying the underlying item stack data.
+ * Prefer the overloads that accept an explicit [Plugin] parameter over the deprecated ones,
+ * as automatic caller-plugin detection via `getCallingPlugin` is unreliable across different
+ * call-site configurations.
  */
 interface SurfBukkitPacketApi {
 
     /**
-     * Registers a listener for modifying the lore of a specific item stack identified by the given key.
-     *
-     * @param identifier A unique key representing the item to listen for. Must not be null.
-     * @param listener   The listener that modifies the lore of the item stack. Must not be null.
-     *
-     * Example Usage:
-     * ```
-     * val key = NamespacedKey("myplugin", "custom_item")
-     * surfBukkitPacketApi.registerPacketLoreListener(key, SurfBukkitPacketLoreHandler { lore, _, _ ->
-     *     lore.add(Component.text("Special Lore!"))
-     * })
-     * ```
+     * Registers a listener for modifying the lore of a specific item stack identified by [identifier].
+     *
+     * @param identifier A unique key representing the item to listen for.
+     * @param listener The listener that modifies the lore of the item stack.
+     *
+     * @deprecated Automatic plugin detection via `getCallingPlugin` is unreliable. Use
+     * [registerPacketLoreListener(Plugin, NamespacedKey, SurfBukkitPacketLoreHandler)] instead
+     * and pass your plugin instance explicitly.
+     */
+    @Deprecated(
+        message = "Automatic plugin detection is unreliable. Pass your plugin instance explicitly.",
+        replaceWith = ReplaceWith("registerPacketLoreListener(plugin, identifier, listener)")
+    )
+    fun registerPacketLoreListener(
+        identifier: NamespacedKey,
+        listener: SurfBukkitPacketLoreHandler
+    ) {
+        registerPacketLoreListener(getCallingPlugin(2), identifier, listener)
+    }
+
+    /**
+     * Registers a listener for modifying the lore of a specific item stack identified by [identifier].
+     *
+     * This is the preferred overload. The [plugin] reference is used to properly manage the
+     * listener lifecycle — all listeners registered under a plugin are automatically cleaned up
+     * when [unregisterPacketLoreListener(Plugin)] is called.
+     *
+     * @param plugin The plugin registering the listener. Used for lifecycle management.
+     * @param identifier A unique key representing the item to listen for.
+     * @param listener The listener that modifies the lore of the item stack.
      */
     fun registerPacketLoreListener(
+        plugin: Plugin,
         identifier: NamespacedKey,
         listener: SurfBukkitPacketLoreHandler
     )
 
     /**
-     * Registers a simplified packet lore listener for a specific item.
+     * Registers a simplified listener for modifying the lore of a specific item stack identified by [identifier].
      *
-     * @param identifier A unique key representing the item to listen for. Must not be null.
-     * @param listener   The simplified packet lore listener that focuses solely on modifying the lore list.
+     * Delegates to [registerPacketLoreListener(Plugin, NamespacedKey, SurfBukkitPacketLoreHandler)].
      *
-     * This method delegates to the standard [registerPacketLoreListener] implementation.
+     * @param identifier A unique key representing the item to listen for.
+     * @param listener The simplified lore listener that focuses solely on modifying the lore list.
+     *
+     * @deprecated Automatic plugin detection is unreliable. Use
+     * [registerPacketLoreListener(Plugin, NamespacedKey, SurfBukkitPacketLoreHandlerSimple)] instead
+     * and pass your plugin instance explicitly.
      */
+    @Deprecated(
+        message = "Automatic plugin detection is unreliable. Pass your plugin instance explicitly.",
+        replaceWith = ReplaceWith("registerPacketLoreListener(plugin, identifier, listener)")
+    )
     fun registerPacketLoreListener(
         identifier: NamespacedKey,
         listener: SurfBukkitPacketLoreHandlerSimple
     ) {
-        registerPacketLoreListener(identifier, listener as SurfBukkitPacketLoreHandler)
+        registerPacketLoreListener(getCallingPlugin(2), identifier, listener)
     }
 
     /**
-     * Registers a packet lore listener globally to handle lore modifications for all items.
+     * Registers a simplified listener for modifying the lore of a specific item stack identified by [identifier].
      *
-     * @param plugin   The plugin registering the listener. Used to manage lifecycle and cleanup.
-     * @param listener The lore listener to handle lore modifications globally.
+     * This is the preferred overload. Delegates to
+     * [registerPacketLoreListener(Plugin, NamespacedKey, SurfBukkitPacketLoreHandler)].
+     * The [plugin] reference is used to properly manage the listener lifecycle.
      *
-     * Example Usage:
-     * ```
-     * surfBukkitPacketApi.registerPacketLoreListenerGlobal(myPlugin, SurfBukkitPacketLoreHandler { lore, _, _ ->
-     *     lore.add(Component.text("Global Lore Modification"))
-     * })
-     * ```
+     * @param plugin The plugin registering the listener. Used for lifecycle management.
+     * @param identifier A unique key representing the item to listen for.
+     * @param listener The simplified lore listener that focuses solely on modifying the lore list.
+     */
+    fun registerPacketLoreListener(
+        plugin: Plugin,
+        identifier: NamespacedKey,
+        listener: SurfBukkitPacketLoreHandlerSimple
+    ) {
+        registerPacketLoreListener(plugin, identifier, listener as SurfBukkitPacketLoreHandler)
+    }
+
+    /**
+     * Registers a lore listener globally to handle lore modifications for all items.
+     *
+     * Unlike the key-based overloads, this listener fires for every item stack regardless of
+     * its identifier. Use this only when you genuinely need to intercept all items, as it has
+     * a broader performance impact.
+     *
+     * @param plugin The plugin registering the listener. Used for lifecycle management.
+     * @param listener The lore listener to handle lore modifications globally.
      */
     fun registerPacketLoreListenerGlobal(
         plugin: Plugin,
         listener: SurfBukkitPacketLoreHandler
     )
 
     /**
-     * Registers a simplified packet lore listener globally for all items.
+     * Registers a simplified lore listener globally for all items.
      *
-     * @param plugin   The plugin registering the listener. Used for proper cleanup during plugin shutdown.
-     * @param listener The simplified lore listener that focuses solely on the lore list.
+     * Delegates to [registerPacketLoreListenerGlobal(Plugin, SurfBukkitPacketLoreHandler)].
      *
-     * This method delegates to the standard [registerPacketLoreListenerGlobal] implementation.
+     * @param plugin The plugin registering the listener. Used for lifecycle management.
+     * @param listener The simplified lore listener that focuses solely on the lore list.
      */
     fun registerPacketLoreListenerGlobal(
         plugin: Plugin,
@@ -86,26 +131,19 @@ interface SurfBukkitPacketApi {
     }
 
     /**
-     * Unregisters a previously registered packet lore listener identified by the given key.
+     * Unregisters the packet lore listener associated with the given [identifier].
      *
      * @param identifier The key identifying the listener to unregister.
-     *
-     * Example Usage:
-     * ```
-     * surfBukkitPacketApi.unregisterPacketLoreListener(NamespacedKey("myplugin", "custom_item"))
-     * ```
      */
     fun unregisterPacketLoreListener(identifier: NamespacedKey)
 
     /**
-     * Unregisters all packet lore listeners associated with the given plugin.
+     * Unregisters all packet lore listeners associated with the given [plugin].
      *
-     * @param plugin The plugin whose listeners should be unregistered.
+     * Call this during plugin shutdown to ensure all listeners registered under this plugin
+     * are properly cleaned up.
      *
-     * Example Usage:
-     * ```
-     * surfBukkitPacketApi.unregisterPacketLoreListener(myPlugin)
-     * ```
+     * @param plugin The plugin whose listeners should be unregistered.
      */
     fun unregisterPacketLoreListener(plugin: Plugin)
 
@@ -114,5 +152,3 @@ interface SurfBukkitPacketApi {
         val instance = requiredService<SurfBukkitPacketApi>()
     }
 }
-
-val surfBukkitPacketApi get() = SurfBukkitPacketApi.instance

surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/impl/packet/SurfBukkitPacketApiImpl.kt

@@ -15,10 +15,11 @@ class SurfBukkitPacketApiImpl : SurfBukkitPacketApi {
     }
 
     override fun registerPacketLoreListener(
+        plugin: Plugin,
         identifier: NamespacedKey,
         listener: SurfBukkitPacketLoreHandler
     ) {
-        PacketLoreListener.register(identifier, listener)
+        PacketLoreListener.register(plugin, identifier, listener)
     }
 
     override fun registerPacketLoreListenerGlobal(

surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/packet/PacketApiLoader.kt

@@ -1,11 +1,14 @@
 package dev.slne.surf.surfapi.bukkit.server.packet
 
 import com.github.retrooper.packetevents.PacketEvents
+import dev.slne.surf.surfapi.bukkit.api.event.register
+import dev.slne.surf.surfapi.bukkit.api.event.unregister
 import dev.slne.surf.surfapi.bukkit.api.nms.NmsUseWithCaution
 import dev.slne.surf.surfapi.bukkit.api.packet.listener.packetListenerApi
 import dev.slne.surf.surfapi.bukkit.server.impl.glow.GlowingPacketListener
 import dev.slne.surf.surfapi.bukkit.server.packet.listener.PlayerChannelInjector
 import dev.slne.surf.surfapi.bukkit.server.packet.lore.PacketLoreListener
+import dev.slne.surf.surfapi.bukkit.server.packet.lore.PluginDisablePacketLoreListener
 import dev.slne.surf.surfapi.bukkit.server.plugin
 import dev.slne.surf.surfapi.core.api.extensions.packetEvents
 import io.github.retrooper.packetevents.factory.spigot.SpigotPacketEventsBuilder
@@ -23,12 +26,14 @@ object PacketApiLoader {
         packetListenerApi.registerListeners(GlowingPacketListener)
 
         PlayerChannelInjector.register()
+        PluginDisablePacketLoreListener.register()
     }
 
     @OptIn(NmsUseWithCaution::class)
     fun onDisable() {
         packetEvents.terminate()
         packetListenerApi.unregisterListeners(PacketLoreListener)
+        PluginDisablePacketLoreListener.unregister()
     }
 
     private fun setupPacketEvents() {