Skip to content

Commit 9fc6ea5

Browse files
twisti-devtwisti-dev
authored
Enhance PacketLoreListener with improved lore and snapshot management (#249)
2 parents 8346806 + ac53c1c commit 9fc6ea5

7 files changed

Lines changed: 362 additions & 92 deletions

File tree

‎gradle.properties‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,6 @@ org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
77
javaVersion=25
88
mcVersion=1.21.11
99
group=dev.slne.surf
10-
version=1.21.11-2.65.0
10+
version=1.21.11-2.66.0
1111
relocationPrefix=dev.slne.surf.surfapi.libs
1212
snapshot=false

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2155,8 +2155,10 @@ public abstract interface class dev/slne/surf/surfapi/bukkit/api/nms/listener/pa
21552155
public abstract interface class dev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi {
21562156
public static final field Companion Ldev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi$Companion;
21572157
public static fun getInstance ()Ldev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi;
2158-
public abstract fun registerPacketLoreListener (Lorg/bukkit/NamespacedKey;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandler;)V
2158+
public fun registerPacketLoreListener (Lorg/bukkit/NamespacedKey;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandler;)V
21592159
public fun registerPacketLoreListener (Lorg/bukkit/NamespacedKey;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandlerSimple;)V
2160+
public abstract fun registerPacketLoreListener (Lorg/bukkit/plugin/Plugin;Lorg/bukkit/NamespacedKey;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandler;)V
2161+
public fun registerPacketLoreListener (Lorg/bukkit/plugin/Plugin;Lorg/bukkit/NamespacedKey;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandlerSimple;)V
21602162
public abstract fun registerPacketLoreListenerGlobal (Lorg/bukkit/plugin/Plugin;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandler;)V
21612163
public fun registerPacketLoreListenerGlobal (Lorg/bukkit/plugin/Plugin;Ldev/slne/surf/surfapi/bukkit/api/packet/lore/SurfBukkitPacketLoreHandlerSimple;)V
21622164
public abstract fun unregisterPacketLoreListener (Lorg/bukkit/NamespacedKey;)V
@@ -2168,7 +2170,9 @@ public final class dev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi$C
21682170
}
21692171

21702172
public final class dev/slne/surf/surfapi/bukkit/api/packet/SurfBukkitPacketApi$DefaultImpls {
2173+
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
21712174
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
2175+
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
21722176
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
21732177
}
21742178

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

Lines changed: 85 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -2,81 +2,126 @@ package dev.slne.surf.surfapi.bukkit.api.packet
22

33
import dev.slne.surf.surfapi.bukkit.api.packet.lore.SurfBukkitPacketLoreHandler
44
import dev.slne.surf.surfapi.bukkit.api.packet.lore.SurfBukkitPacketLoreHandlerSimple
5+
import dev.slne.surf.surfapi.bukkit.api.util.getCallingPlugin
56
import dev.slne.surf.surfapi.core.api.util.requiredService
67
import org.bukkit.NamespacedKey
78
import org.bukkit.plugin.Plugin
89

910
/**
1011
* The SurfBukkitPacketApi interface extends packet handling capabilities for Bukkit environments.
1112
*
12-
* It provides methods for registering and unregistering lore listeners, enabling dynamic modification
13-
* of item stack lore based on custom logic. It also includes global registration methods for listening
14-
* to all items and utilities for managing these listeners efficiently.
13+
* Provides methods for registering and unregistering lore listeners, enabling dynamic modification
14+
* of item stack lore based on custom logic. Includes global registration for all items and utilities
15+
* for managing these listeners efficiently.
1516
*
16-
* This API allows developers to enhance item lore dynamically, providing a flexible system for plugins
17-
* that need to alter or interact with lore without directly modifying the underlying item stack data.
17+
* Prefer the overloads that accept an explicit [Plugin] parameter over the deprecated ones,
18+
* as automatic caller-plugin detection via `getCallingPlugin` is unreliable across different
19+
* call-site configurations.
1820
*/
1921
interface SurfBukkitPacketApi {
2022

2123
/**
22-
* Registers a listener for modifying the lore of a specific item stack identified by the given key.
23-
*
24-
* @param identifier A unique key representing the item to listen for. Must not be null.
25-
* @param listener The listener that modifies the lore of the item stack. Must not be null.
26-
*
27-
* Example Usage:
28-
* ```
29-
* val key = NamespacedKey("myplugin", "custom_item")
30-
* surfBukkitPacketApi.registerPacketLoreListener(key, SurfBukkitPacketLoreHandler { lore, _, _ ->
31-
* lore.add(Component.text("Special Lore!"))
32-
* })
33-
* ```
24+
* Registers a listener for modifying the lore of a specific item stack identified by [identifier].
25+
*
26+
* @param identifier A unique key representing the item to listen for.
27+
* @param listener The listener that modifies the lore of the item stack.
28+
*
29+
* @deprecated Automatic plugin detection via `getCallingPlugin` is unreliable. Use
30+
* [registerPacketLoreListener(Plugin, NamespacedKey, SurfBukkitPacketLoreHandler)] instead
31+
* and pass your plugin instance explicitly.
32+
*/
33+
@Deprecated(
34+
message = "Automatic plugin detection is unreliable. Pass your plugin instance explicitly.",
35+
replaceWith = ReplaceWith("registerPacketLoreListener(plugin, identifier, listener)")
36+
)
37+
fun registerPacketLoreListener(
38+
identifier: NamespacedKey,
39+
listener: SurfBukkitPacketLoreHandler
40+
) {
41+
registerPacketLoreListener(getCallingPlugin(2), identifier, listener)
42+
}
43+
44+
/**
45+
* Registers a listener for modifying the lore of a specific item stack identified by [identifier].
46+
*
47+
* This is the preferred overload. The [plugin] reference is used to properly manage the
48+
* listener lifecycle — all listeners registered under a plugin are automatically cleaned up
49+
* when [unregisterPacketLoreListener(Plugin)] is called.
50+
*
51+
* @param plugin The plugin registering the listener. Used for lifecycle management.
52+
* @param identifier A unique key representing the item to listen for.
53+
* @param listener The listener that modifies the lore of the item stack.
3454
*/
3555
fun registerPacketLoreListener(
56+
plugin: Plugin,
3657
identifier: NamespacedKey,
3758
listener: SurfBukkitPacketLoreHandler
3859
)
3960

4061
/**
41-
* Registers a simplified packet lore listener for a specific item.
62+
* Registers a simplified listener for modifying the lore of a specific item stack identified by [identifier].
4263
*
43-
* @param identifier A unique key representing the item to listen for. Must not be null.
44-
* @param listener The simplified packet lore listener that focuses solely on modifying the lore list.
64+
* Delegates to [registerPacketLoreListener(Plugin, NamespacedKey, SurfBukkitPacketLoreHandler)].
4565
*
46-
* This method delegates to the standard [registerPacketLoreListener] implementation.
66+
* @param identifier A unique key representing the item to listen for.
67+
* @param listener The simplified lore listener that focuses solely on modifying the lore list.
68+
*
69+
* @deprecated Automatic plugin detection is unreliable. Use
70+
* [registerPacketLoreListener(Plugin, NamespacedKey, SurfBukkitPacketLoreHandlerSimple)] instead
71+
* and pass your plugin instance explicitly.
4772
*/
73+
@Deprecated(
74+
message = "Automatic plugin detection is unreliable. Pass your plugin instance explicitly.",
75+
replaceWith = ReplaceWith("registerPacketLoreListener(plugin, identifier, listener)")
76+
)
4877
fun registerPacketLoreListener(
4978
identifier: NamespacedKey,
5079
listener: SurfBukkitPacketLoreHandlerSimple
5180
) {
52-
registerPacketLoreListener(identifier, listener as SurfBukkitPacketLoreHandler)
81+
registerPacketLoreListener(getCallingPlugin(2), identifier, listener)
5382
}
5483

5584
/**
56-
* Registers a packet lore listener globally to handle lore modifications for all items.
85+
* Registers a simplified listener for modifying the lore of a specific item stack identified by [identifier].
5786
*
58-
* @param plugin The plugin registering the listener. Used to manage lifecycle and cleanup.
59-
* @param listener The lore listener to handle lore modifications globally.
87+
* This is the preferred overload. Delegates to
88+
* [registerPacketLoreListener(Plugin, NamespacedKey, SurfBukkitPacketLoreHandler)].
89+
* The [plugin] reference is used to properly manage the listener lifecycle.
6090
*
61-
* Example Usage:
62-
* ```
63-
* surfBukkitPacketApi.registerPacketLoreListenerGlobal(myPlugin, SurfBukkitPacketLoreHandler { lore, _, _ ->
64-
* lore.add(Component.text("Global Lore Modification"))
65-
* })
66-
* ```
91+
* @param plugin The plugin registering the listener. Used for lifecycle management.
92+
* @param identifier A unique key representing the item to listen for.
93+
* @param listener The simplified lore listener that focuses solely on modifying the lore list.
94+
*/
95+
fun registerPacketLoreListener(
96+
plugin: Plugin,
97+
identifier: NamespacedKey,
98+
listener: SurfBukkitPacketLoreHandlerSimple
99+
) {
100+
registerPacketLoreListener(plugin, identifier, listener as SurfBukkitPacketLoreHandler)
101+
}
102+
103+
/**
104+
* Registers a lore listener globally to handle lore modifications for all items.
105+
*
106+
* Unlike the key-based overloads, this listener fires for every item stack regardless of
107+
* its identifier. Use this only when you genuinely need to intercept all items, as it has
108+
* a broader performance impact.
109+
*
110+
* @param plugin The plugin registering the listener. Used for lifecycle management.
111+
* @param listener The lore listener to handle lore modifications globally.
67112
*/
68113
fun registerPacketLoreListenerGlobal(
69114
plugin: Plugin,
70115
listener: SurfBukkitPacketLoreHandler
71116
)
72117

73118
/**
74-
* Registers a simplified packet lore listener globally for all items.
119+
* Registers a simplified lore listener globally for all items.
75120
*
76-
* @param plugin The plugin registering the listener. Used for proper cleanup during plugin shutdown.
77-
* @param listener The simplified lore listener that focuses solely on the lore list.
121+
* Delegates to [registerPacketLoreListenerGlobal(Plugin, SurfBukkitPacketLoreHandler)].
78122
*
79-
* This method delegates to the standard [registerPacketLoreListenerGlobal] implementation.
123+
* @param plugin The plugin registering the listener. Used for lifecycle management.
124+
* @param listener The simplified lore listener that focuses solely on the lore list.
80125
*/
81126
fun registerPacketLoreListenerGlobal(
82127
plugin: Plugin,
@@ -86,26 +131,19 @@ interface SurfBukkitPacketApi {
86131
}
87132

88133
/**
89-
* Unregisters a previously registered packet lore listener identified by the given key.
134+
* Unregisters the packet lore listener associated with the given [identifier].
90135
*
91136
* @param identifier The key identifying the listener to unregister.
92-
*
93-
* Example Usage:
94-
* ```
95-
* surfBukkitPacketApi.unregisterPacketLoreListener(NamespacedKey("myplugin", "custom_item"))
96-
* ```
97137
*/
98138
fun unregisterPacketLoreListener(identifier: NamespacedKey)
99139

100140
/**
101-
* Unregisters all packet lore listeners associated with the given plugin.
141+
* Unregisters all packet lore listeners associated with the given [plugin].
102142
*
103-
* @param plugin The plugin whose listeners should be unregistered.
143+
* Call this during plugin shutdown to ensure all listeners registered under this plugin
144+
* are properly cleaned up.
104145
*
105-
* Example Usage:
106-
* ```
107-
* surfBukkitPacketApi.unregisterPacketLoreListener(myPlugin)
108-
* ```
146+
* @param plugin The plugin whose listeners should be unregistered.
109147
*/
110148
fun unregisterPacketLoreListener(plugin: Plugin)
111149

@@ -114,5 +152,3 @@ interface SurfBukkitPacketApi {
114152
val instance = requiredService<SurfBukkitPacketApi>()
115153
}
116154
}
117-
118-
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‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,11 @@ class SurfBukkitPacketApiImpl : SurfBukkitPacketApi {
1515
}
1616

1717
override fun registerPacketLoreListener(
18+
plugin: Plugin,
1819
identifier: NamespacedKey,
1920
listener: SurfBukkitPacketLoreHandler
2021
) {
21-
PacketLoreListener.register(identifier, listener)
22+
PacketLoreListener.register(plugin, identifier, listener)
2223
}
2324

2425
override fun registerPacketLoreListenerGlobal(

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
package dev.slne.surf.surfapi.bukkit.server.packet
22

33
import com.github.retrooper.packetevents.PacketEvents
4+
import dev.slne.surf.surfapi.bukkit.api.event.register
5+
import dev.slne.surf.surfapi.bukkit.api.event.unregister
46
import dev.slne.surf.surfapi.bukkit.api.nms.NmsUseWithCaution
57
import dev.slne.surf.surfapi.bukkit.api.packet.listener.packetListenerApi
68
import dev.slne.surf.surfapi.bukkit.server.impl.glow.GlowingPacketListener
79
import dev.slne.surf.surfapi.bukkit.server.packet.listener.PlayerChannelInjector
810
import dev.slne.surf.surfapi.bukkit.server.packet.lore.PacketLoreListener
11+
import dev.slne.surf.surfapi.bukkit.server.packet.lore.PluginDisablePacketLoreListener
912
import dev.slne.surf.surfapi.bukkit.server.plugin
1013
import dev.slne.surf.surfapi.core.api.extensions.packetEvents
1114
import io.github.retrooper.packetevents.factory.spigot.SpigotPacketEventsBuilder
@@ -23,12 +26,14 @@ object PacketApiLoader {
2326
packetListenerApi.registerListeners(GlowingPacketListener)
2427

2528
PlayerChannelInjector.register()
29+
PluginDisablePacketLoreListener.register()
2630
}
2731

2832
@OptIn(NmsUseWithCaution::class)
2933
fun onDisable() {
3034
packetEvents.terminate()
3135
packetListenerApi.unregisterListeners(PacketLoreListener)
36+
PluginDisablePacketLoreListener.unregister()
3237
}
3338

3439
private fun setupPacketEvents() {

0 commit comments

Comments
 (0)