Merge branch 'version/1.21.11' into feat/add-surf-core

Author: TheBjoRedCraft

build.gradle.kts

@@ -2,7 +2,7 @@ import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar.Companion.shad
 import kotlinx.validation.KotlinApiBuildTask
 
 plugins {
-    id("io.papermc.paperweight.userdev") version "2.0.0-beta.17" apply false
+    id("io.papermc.paperweight.userdev") version "2.0.0-beta.19" apply false
     id("org.jetbrains.kotlinx.binary-compatibility-validator") version "0.18.1"
 //    alias(libs.plugins.dokka)
 }

buildSrc/src/main/kotlin/core-convention.gradle.kts

@@ -29,7 +29,7 @@ dependencies {
     compileOnly(libs.auto.service.annotations)
     ksp(project(":surf-api-gradle-plugin:surf-api-processor"))
 
-    compileOnlyApi("org.jetbrains:annotations:24.1.0")
+    compileOnlyApi("org.jetbrains:annotations:26.0.2-1")
 }
 
 ksp {

gradle.properties

@@ -5,8 +5,8 @@ kapt.use.k2=true
 org.gradle.jvmargs=-Xmx4G
 org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
 javaVersion=21
-mcVersion=1.21.10
+mcVersion=1.21.11
 group=dev.slne.surf
-version=1.21.10-2.43.0
+version=1.21.11-2.49.1
 relocationPrefix=dev.slne.surf.surfapi.libs
-snapshot=false
+snapshot=false

gradle/libs.versions.toml

@@ -1,15 +1,15 @@
 [versions]
 # Paper
-paper-api = "1.21.10-R0.1-SNAPSHOT"
+paper-api = "1.21.11-R0.1-SNAPSHOT"
 
 # Kolin
-kotlinVersion = "2.2.20"
+kotlinVersion = "2.3.0"
 kotlinxCoroutines = "1.10.2"
 kotlinx-serialization = "1.9.0"
 
 # Packet Events
-packetevents = "2.10.0"
-packetevents-plugin = "2.10.0"
+packetevents = "2.11.0"
+packetevents-plugin = "2.11.0"
 
 # Command API
 commandapi = "11.0.0"
@@ -19,8 +19,8 @@ luckperms = "v5.5.0-bukkit"
 
 # Scoreboard Library
 scoreboard-library = "2.4.3"
-scoreboard-library-implementation = "2.4.2"
-scoreboard-library-modern = "2.4.2"
+scoreboard-library-implementation = "2.4.3"
+scoreboard-library-modern = "2.4.3"
 
 # Adventure
 adventure-api = "4.25.0"
@@ -36,38 +36,38 @@ mccoroutine = "2.22.0"
 
 # Miscellaneous Libraries
 guava = "33.5.0-jre"
-caffeine = "3.2.1"
-caffeine-courotines = "2.0.2"
+caffeine = "3.2.3"
+caffeine-courotines = "3.0.1"
 gson = "2.13.2"
-commons-lang3 = "3.19.0"
-commons-text = "1.14.0"
+commons-lang3 = "3.20.0"
+commons-text = "1.15.0"
 commons-math4-core = "4.0-beta1"
 plugin-yml-paper = "0.8.0"
 spongepowered-math = "2.0.1"
 fastutil = "8.5.18"
-okhttp = "5.1.0"
+okhttp = "5.3.2"
 dazzleconf = "1.4.0-M1"
 reflection-remapper = "0.1.3"
 brigadier = "1.0.500"
 datafixerupper = "8.0.16"
 configurate = "4.2.0"
 more-persistent-data-types = "2.4.0"
-stefvanschie-if = "0.11.3"
-inventory-framework = "3.5.4"
+stefvanschie-if = "0.11.6"
+inventory-framework = "3.7.1"
 flogger = "0.9"
 aide-reflection = "1.3"
 auto-service = "1.1.1"
 auto-service-ksp = "1.2.0"
-ktor = "3.3.1"
-glm = "0.9.9.1-12"
-ksp-version = "2.2.20-2.0.4"
-reactor-netty = "1.3.0"
+ktor = "3.3.3"
+glm = "0.9.9.1-15"
+ksp-version = "2.3.3"
+reactor-netty = "1.3.1"
 
 # Plugin versions
 maven-repo-auth = "3.0.4"
-shadow-gradle-plugin = "9.2.2"
-run-paper-gradle-plugin = "3.0.1"
-dokka = "2.0.0"
+shadow-gradle-plugin = "9.3.0"
+run-paper-gradle-plugin = "3.0.2"
+dokka = "2.1.0"
 
 
 [libraries]
@@ -187,4 +187,4 @@ ktor-client = ["ktor-client-core", "ktor-client-okhttp", "ktor-client-content-ne
 inventory-framework = ["inventory-framework-platform-paper", "inventory-framework-platform-bukkit"]
 reactor-netty = ["reactor-netty-core", "reactor-netty-http"]
 kotlin-coroutines = ["kotlinxCoroutines-core", "kotlinxCoroutines-reactor", "kotlinxCoroutines-reactive"]
-kotlin-serialization = ["kotlin-serialization-json", "kotlin-serialization-protobuf"]
+kotlin-serialization = ["kotlin-serialization-json", "kotlin-serialization-protobuf"]

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

@@ -0,0 +1,106 @@
+package dev.slne.surf.surfapi.bukkit.api.command.args
+
+import com.github.shynixn.mccoroutine.folia.SuspendingPlugin
+import com.github.shynixn.mccoroutine.folia.scope
+import com.mojang.brigadier.context.CommandContext
+import dev.jorel.commandapi.CommandAPIBukkit
+import dev.jorel.commandapi.CommandAPIHandler
+import dev.jorel.commandapi.arguments.Argument
+import dev.jorel.commandapi.arguments.CustomArgument
+import dev.jorel.commandapi.executors.CommandArguments
+import dev.slne.surf.surfapi.bukkit.api.util.getCallingPlugin
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Deferred
+import kotlinx.coroutines.async
+
+/**
+ * Base class for custom CommandAPI arguments whose parsing logic is executed asynchronously
+ * using Kotlin coroutines.
+ *
+ * This abstraction allows implementing suspendable parsing logic while still integrating
+ * with CommandAPI's synchronous argument parsing pipeline by returning a [Deferred].
+ *
+ * @param T The final parsed argument type.
+ * @param B The base argument type produced by the underlying [Argument].
+ * @property base The underlying base argument used for initial parsing.
+ * @property scope The [CoroutineScope] used to execute the suspendable parsing logic.
+ */
+abstract class SuspendCustomArgument<T, B>(
+    private val base: Argument<B>,
+    private val scope: CoroutineScope = extractCallingPluginScopeOrThrow()
+) : CustomArgument<Deferred<T>, B>(base, { _ ->
+    throw UnsupportedOperationException("Parsing is performed asynchronously via the overridden parse method")
+}) {
+
+    /**
+     * Parses the argument asynchronously.
+     *
+     * This method is executed inside the provided [CoroutineScope] and may perform
+     * suspendable or asynchronous operations such as database lookups or network calls.
+     *
+     * Implementations should throw [CustomArgumentException] to signal a user-facing
+     * parsing error.
+     *
+     * @param info Contextual information about the argument being parsed.
+     * @return The parsed argument value.
+     * @throws CustomArgumentException If parsing fails with a user-facing error.
+     */
+    abstract suspend fun CoroutineScope.parse(info: CustomArgumentInfo<B>): T
+
+    /**
+     * Synchronously invoked by CommandAPI to parse the argument.
+     *
+     * Internally, this method delegates to [parse] by launching a coroutine in [scope]
+     * and returning a [Deferred] representing the eventual parsing result.
+     *
+     * Any thrown [CustomArgumentException] is converted into a Brigadier
+     * [com.mojang.brigadier.exceptions.CommandSyntaxException].
+     *
+     * @param cmdCtx The Brigadier command context.
+     * @param key The argument node name.
+     * @param previousArgs Previously parsed command arguments.
+     * @return A [Deferred] that completes with the parsed argument value.
+     */
+    final override fun <CommandSourceStack : Any> parseArgument(
+        cmdCtx: CommandContext<CommandSourceStack>,
+        key: String,
+        previousArgs: CommandArguments
+    ): Deferred<T> {
+        val customResult = CommandAPIHandler.getRawArgumentInput(cmdCtx, key)
+        val parsedInput = base.parseArgument(cmdCtx, key, previousArgs)
+
+        return scope.async {
+            try {
+                val sender = CommandAPIBukkit.get<CommandSourceStack>()
+                    .getCommandSenderFromCommandSource(cmdCtx.source).source
+                val info = CustomArgumentInfo(sender, previousArgs, customResult, parsedInput)
+                parse(info)
+            } catch (e: CustomArgumentException) {
+                throw e.toCommandSyntax(customResult, cmdCtx)
+            }
+        }
+    }
+
+    companion object {
+        /**
+         * Extracts the [CoroutineScope] of the calling plugin.
+         *
+         * The calling plugin must implement [SuspendingPlugin]. If it does not,
+         * an exception is thrown to prevent executing coroutines without
+         * proper lifecycle management.
+         *
+         * @return The plugin's coroutine scope.
+         * @throws IllegalArgumentException If the plugin does not implement [SuspendingPlugin].
+         */
+        private fun extractCallingPluginScopeOrThrow(): CoroutineScope {
+            val plugin = getCallingPlugin(2)
+
+            require(plugin is SuspendingPlugin) {
+                "Failed to extract CoroutineScope: plugin '${plugin.name}' does not implement SuspendingPlugin. " +
+                        "Provide a CoroutineScope explicitly or use a SuspendingPlugin."
+            }
+
+            return plugin.scope
+        }
+    }
+}