✨ feat(events): add new player-related events for gameplay interactions

gradle.properties

@@ -7,6 +7,6 @@ org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
 javaVersion=25
 mcVersion=26.1.2
 group=dev.slne.surf.api
-version=3.13.0
+version=3.13.1
 relocationPrefix=dev.slne.surf.api.libs
 snapshot=false

surf-api-paper/surf-api-paper-plugin-test/src/main/kotlin/dev/slne/surf/surfapi/bukkit/test/command/subcommands/eventhandler/SurfSyncEventHandlerTest.kt

@@ -5,7 +5,7 @@ import dev.jorel.commandapi.kotlindsl.anyExecutor
 import dev.jorel.commandapi.kotlindsl.playerExecutor
 import dev.jorel.commandapi.kotlindsl.subcommand
 import dev.slne.surf.api.core.messages.adventure.sendText
-import dev.slne.surf.api.paper.event.common.PlayerAfkStateChangeEvent
+import dev.slne.surf.api.paper.event.playtime.AfkStateChangeEvent
 import dev.slne.surf.surfapi.bukkit.test.command.subcommands.eventhandler.listener.PlayerAfkStateChangeEventListener
 
 class SurfSyncEventHandlerTest(name: String) : CommandAPICommand(name) {
@@ -34,7 +34,7 @@ class SurfSyncEventHandlerTest(name: String) : CommandAPICommand(name) {
         subcommand("dispatch") {
             playerExecutor { sender, _ ->
                 val playerUuid = sender.uniqueId
-                val event = PlayerAfkStateChangeEvent(playerUuid, fromState = false, toState = true)
+                val event = AfkStateChangeEvent(playerUuid, fromState = false, toState = true)
                 event.call()
                 sender.sendText {
                     appendInfoPrefix()

surf-api-paper/surf-api-paper-plugin-test/src/main/kotlin/dev/slne/surf/surfapi/bukkit/test/command/subcommands/eventhandler/listener/PlayerAfkStateChangeEventListener.kt

@@ -2,10 +2,10 @@ package dev.slne.surf.surfapi.bukkit.test.command.subcommands.eventhandler.liste
 
 import dev.slne.surf.api.core.event.SurfEventBus
 import dev.slne.surf.api.core.event.SurfEventHandler
-import dev.slne.surf.api.paper.event.common.PlayerAfkStateChangeEvent
+import dev.slne.surf.api.paper.event.playtime.AfkStateChangeEvent
 
 object PlayerAfkStateChangeEventListener {
-    private var lastEvent: PlayerAfkStateChangeEvent? = null
+    private var lastEvent: AfkStateChangeEvent? = null
 
     fun register() {
         SurfEventBus.registerListeners(this)
@@ -15,14 +15,14 @@ object PlayerAfkStateChangeEventListener {
         SurfEventBus.unregisterListeners(this)
     }
 
-    fun getLastEvent(): PlayerAfkStateChangeEvent? = lastEvent
+    fun getLastEvent(): AfkStateChangeEvent? = lastEvent
 
     fun clearLastEvent() {
         lastEvent = null
     }
 
     @SurfEventHandler
-   private fun onPlayerAfkStateChange(event: PlayerAfkStateChangeEvent) {
+    private fun onPlayerAfkStateChange(event: AfkStateChangeEvent) {
         lastEvent = event
     }
 }

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/captcha/CaptchaFailEvent.kt

@@ -0,0 +1,19 @@
+package dev.slne.surf.api.paper.event.captcha
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.entity.Player
+
+/**
+ * Fired when a player fails a CAPTCHA verification.
+ *
+ * This synchronous event is triggered when a player fails to complete or verify a CAPTCHA challenge.
+ *
+ * @property player The player who failed the CAPTCHA
+ * @property size The size/difficulty rating of the CAPTCHA
+ * @property timePerPage The time allowed per CAPTCHA page in milliseconds
+ */
+data class CaptchaFailEvent(
+    val player: Player,
+    val size: Int,
+    val timePerPage: Long
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/captcha/CaptchaSuccessEvent.kt

@@ -0,0 +1,19 @@
+package dev.slne.surf.api.paper.event.captcha
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.entity.Player
+
+/**
+ * Fired when a player successfully completes a CAPTCHA verification.
+ *
+ * This synchronous event is triggered when a player successfully completes and verifies a CAPTCHA challenge.
+ *
+ * @property player The player who passed the CAPTCHA
+ * @property size The size/difficulty rating of the CAPTCHA
+ * @property timePerPage The time allowed per CAPTCHA page in milliseconds
+ */
+data class CaptchaSuccessEvent(
+    val player: Player,
+    val size: Int,
+    val timePerPage: Long
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/chat/ChatAiModerateEvent.kt

@@ -0,0 +1,17 @@
+package dev.slne.surf.api.paper.event.chat
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.entity.Player
+
+/**
+ * Fired when a chat message is moderated by AI.
+ *
+ * This synchronous event is triggered when an AI moderation system processes and filters a player's chat message.
+ *
+ * @property player The player who wrote the chat message
+ * @property message The chat message that was moderated
+ */
+data class ChatAiModerateEvent(
+    val player: Player,
+    val message: String
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/chat/ChatDirectMessageEvent.kt

@@ -0,0 +1,20 @@
+package dev.slne.surf.api.paper.event.chat
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.entity.Player
+import java.util.*
+
+/**
+ * Fired when a player sends a direct message to another player.
+ *
+ * This synchronous event is triggered when a player sends a private message to another player.
+ *
+ * @property player The player who sent the direct message
+ * @property targetUuid The UUID of the player receiving the direct message
+ * @property message The direct message content
+ */
+data class ChatDirectMessageEvent(
+    val player: Player,
+    val targetUuid: UUID,
+    val message: String
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/chat/ChatIgnoreEvent.kt

@@ -0,0 +1,19 @@
+package dev.slne.surf.api.paper.event.chat
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.entity.Player
+import java.util.*
+
+/**
+ * Fired when a player ignores another player.
+ *
+ * This synchronous event is triggered when a player adds another player to their ignore list,
+ * preventing them from receiving messages from that player.
+ *
+ * @property player The player who is ignoring someone
+ * @property ignoredPlayerUuid The UUID of the player being ignored
+ */
+data class ChatIgnoreEvent(
+    val player: Player,
+    val ignoredPlayerUuid: UUID
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/chat/ChatUnIgnoreEvent.kt

@@ -0,0 +1,19 @@
+package dev.slne.surf.api.paper.event.chat
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.entity.Player
+import java.util.*
+
+/**
+ * Fired when a player stops ignoring another player.
+ *
+ * This synchronous event is triggered when a player removes another player from their ignore list,
+ * allowing them to receive messages from that player again.
+ *
+ * @property player The player who is removing someone from their ignore list
+ * @property ignoredPlayerUuid The UUID of the player being un-ignored
+ */
+data class ChatUnIgnoreEvent(
+    val player: Player,
+    val ignoredPlayerUuid: UUID
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/chat/DisabledChatBlockMessageEvent.kt

@@ -0,0 +1,18 @@
+package dev.slne.surf.api.paper.event.chat
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.entity.Player
+
+/**
+ * Fired when a player's chat message is blocked due to chat being disabled.
+ *
+ * This synchronous event is triggered when a player attempts to send a chat message,
+ * but the message is blocked because chat is currently disabled on the server.
+ *
+ * @property player The player whose message was blocked
+ * @property message The message that was blocked
+ */
+data class DisabledChatBlockMessageEvent(
+    val player: Player,
+    val message: String
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/chat/SlowChatBlockMessageEvent.kt

@@ -0,0 +1,18 @@
+package dev.slne.surf.api.paper.event.chat
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.entity.Player
+
+/**
+ * Fired when a player's chat message is blocked due to slow chat rate limiting.
+ *
+ * This synchronous event is triggered when a player attempts to send a chat message,
+ * but the message is blocked because the player is sending messages too quickly (slow chat cooldown).
+ *
+ * @property player The player whose message was blocked
+ * @property message The message that was blocked
+ */
+data class SlowChatBlockMessageEvent(
+    val player: Player,
+    val message: String
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/clan/ClanCreatedEvent.kt

@@ -0,0 +1,19 @@
+package dev.slne.surf.api.paper.event.clan
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.entity.Player
+
+/**
+ * Fired when a clan is created.
+ *
+ * This synchronous event is triggered when a player successfully creates a new clan.
+ *
+ * @property player The player who created the clan
+ * @property clanName The name of the newly created clan
+ * @property clanTag The tag of the newly created clan
+ */
+data class ClanCreatedEvent(
+    val player: Player,
+    val clanName: String,
+    val clanTag: String
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/clan/ClanDeleteEvent.kt

@@ -0,0 +1,19 @@
+package dev.slne.surf.api.paper.event.clan
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.entity.Player
+
+/**
+ * Fired when a clan is deleted.
+ *
+ * This synchronous event is triggered when a clan is dissolved or deleted from the server.
+ *
+ * @property player The player who deleted the clan
+ * @property clanName The name of the deleted clan
+ * @property clanTag The tag of the deleted clan
+ */
+data class ClanDeleteEvent(
+    val player: Player,
+    val clanName: String,
+    val clanTag: String
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/clan/ClanDemotedEvent.kt

@@ -0,0 +1,20 @@
+package dev.slne.surf.api.paper.event.clan
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.OfflinePlayer
+
+/**
+ * Fired when a player is demoted within their clan.
+ *
+ * This synchronous event is triggered when a player receives a demotion to a lower rank
+ * or role within their clan.
+ *
+ * @property player The player who was demoted
+ * @property clanName The name of the clan
+ * @property newRole The new role the player was demoted to
+ */
+data class ClanDemotedEvent(
+    val player: OfflinePlayer,
+    val clanName: String,
+    val newRole: String
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/clan/ClanInviteCountChangeEvent.kt

@@ -0,0 +1,20 @@
+package dev.slne.surf.api.paper.event.clan
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.OfflinePlayer
+
+/**
+ * Fired when the invite count of a clan changes.
+ *
+ * This synchronous event is triggered when the number of pending invitations in a clan changes,
+ * typically when a player sends or receives a clan invitation.
+ *
+ * @property player The player associated with the invite count change
+ * @property clanName The name of the clan
+ * @property newInviteCount The new total invite count of the clan
+ */
+data class ClanInviteCountChangeEvent(
+    val player: OfflinePlayer,
+    val clanName: String,
+    val newInviteCount: Int
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/clan/ClanMemberCountChangeEvent.kt

@@ -0,0 +1,20 @@
+package dev.slne.surf.api.paper.event.clan
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.OfflinePlayer
+
+/**
+ * Fired when the member count of a clan changes.
+ *
+ * This synchronous event is triggered when the number of members in a clan changes,
+ * typically when a player joins or leaves the clan.
+ *
+ * @property player The player associated with the member count change
+ * @property clanName The name of the clan
+ * @property newMemberCount The new total member count of the clan
+ */
+data class ClanMemberCountChangeEvent(
+    val player: OfflinePlayer,
+    val clanName: String,
+    val newMemberCount: Int
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/clan/ClanPromotedEvent.kt

@@ -0,0 +1,20 @@
+package dev.slne.surf.api.paper.event.clan
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.OfflinePlayer
+
+/**
+ * Fired when a player is promoted within their clan.
+ *
+ * This synchronous event is triggered when a player receives a promotion to a higher rank
+ * or role within their clan.
+ *
+ * @property player The player who was promoted
+ * @property clanName The name of the clan
+ * @property newRole The new role the player was promoted to
+ */
+data class ClanPromotedEvent(
+    val player: OfflinePlayer,
+    val clanName: String,
+    val newRole: String
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/enchantment/CombineMendingEvent.kt

@@ -0,0 +1,16 @@
+package dev.slne.surf.api.paper.event.enchantment
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.entity.Player
+
+/**
+ * Fired when a player combines items with the Mending enchantment.
+ *
+ * This synchronous event is triggered when a player combines items in an anvil or crafting
+ * interface, resulting in an item with the Mending enchantment applied.
+ *
+ * @property player The player who combined the items
+ */
+data class CombineMendingEvent(
+    val player: Player
+) : SurfSyncEvent()

surf-api-paper/surf-api-paper/src/main/kotlin/dev/slne/surf/api/paper/event/enchantment/CombineNemoEvent.kt

@@ -0,0 +1,16 @@
+package dev.slne.surf.api.paper.event.enchantment
+
+import dev.slne.surf.api.core.event.SurfSyncEvent
+import org.bukkit.entity.Player
+
+/**
+ * Fired when a player combines items with the Nemo enchantment.
+ *
+ * This synchronous event is triggered when a player combines items in an anvil or crafting
+ * interface, resulting in an item with the Nemo enchantment applied.
+ *
+ * @property player The player who combined the items
+ */
+data class CombineNemoEvent(
+    val player: Player
+) : SurfSyncEvent()