feat: add mapAsync utility and improve player-related API functions

- Introduced `Iterable<E>.mapAsync()` for parallel processing of async transformations.
- Enhanced `forEachPlayerInRegion` to support explicit plugin parameter and deprecated inefficient overload.
- Added utility methods to convert UUID collections to offline players.
- Added deprecation notices for inefficient dispatcher helper methods.

Author: twisti-dev

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

@@ -2043,7 +2043,9 @@ public final class dev/slne/surf/surfapi/bukkit/api/util/UtilBukkit {
 	public static synthetic fun dispatcher$default (Lorg/bukkit/entity/Entity;Lcom/github/shynixn/mccoroutine/folia/SuspendingPlugin;ILjava/lang/Object;)Lkotlin/coroutines/CoroutineContext;
 	public static final fun distanceSqt (Lorg/bukkit/Location;Lorg/bukkit/Location;)D
 	public static final fun forEachPlayer (Lkotlin/jvm/functions/Function1;)V
+	public static final fun forEachPlayerInRegion (Lcom/github/shynixn/mccoroutine/folia/SuspendingPlugin;Lkotlin/jvm/functions/Function2;ZLkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static final fun forEachPlayerInRegion (Lkotlin/jvm/functions/Function2;ZLkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static synthetic fun forEachPlayerInRegion$default (Lcom/github/shynixn/mccoroutine/folia/SuspendingPlugin;Lkotlin/jvm/functions/Function2;ZLkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
 	public static synthetic fun forEachPlayerInRegion$default (Lkotlin/jvm/functions/Function2;ZLkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
 	public static final fun getCallingPlugin (I)Lorg/bukkit/plugin/java/JavaPlugin;
 	public static synthetic fun getCallingPlugin$default (IILjava/lang/Object;)Lorg/bukkit/plugin/java/JavaPlugin;
@@ -2056,6 +2058,8 @@ public final class dev/slne/surf/surfapi/bukkit/api/util/UtilBukkit {
 	public static final fun isChunkVisible (Lorg/bukkit/entity/Player;Lorg/bukkit/Location;)Z
 	public static final fun isChunkVisible (Lorg/bukkit/entity/Player;Lorg/bukkit/World;II)Z
 	public static final fun key (Ljava/lang/String;)Lorg/bukkit/NamespacedKey;
+	public static final fun toOfflinePlayers (Ljava/lang/Iterable;)Ljava/util/List;
+	public static final fun toOfflinePlayers (Lkotlin/sequences/Sequence;)Lkotlin/sequences/Sequence;
 	public static final fun toPlayers (Ljava/lang/Iterable;)Ljava/util/List;
 	public static final fun toPlayers (Lkotlin/sequences/Sequence;)Lkotlin/sequences/Sequence;
 	public static final fun toVector3d (Lorg/bukkit/Location;)Lorg/spongepowered/math/vector/Vector3d;
@@ -5953,6 +5957,7 @@ public final class dev/slne/surf/surfapi/core/api/util/SurfUtil {
 	public static final fun getValue (Ljava/lang/ref/WeakReference;Ljava/lang/Object;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 	public static final fun logIf (Lcom/google/common/flogger/LoggingApi;Lkotlin/jvm/functions/Function0;Lkotlin/jvm/functions/Function1;)V
 	public static final fun logger ()Lcom/google/common/flogger/FluentLogger;
+	public static final fun mapAsync (Ljava/lang/Iterable;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static final fun setFinalField (Ljava/lang/reflect/Field;Ljava/lang/Object;B)V
 	public static final fun setFinalField (Ljava/lang/reflect/Field;Ljava/lang/Object;C)V
 	public static final fun setFinalField (Ljava/lang/reflect/Field;Ljava/lang/Object;D)V

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

@@ -54,13 +54,27 @@ fun forEachPlayer(action: (player: Player) -> Unit) {
     Bukkit.getOnlinePlayers().forEach(action)
 }
 
+@Deprecated(
+    message = "Use the overload with an explicit plugin parameter; this version relies on inefficient stacktrace inspection.",
+    replaceWith = ReplaceWith("forEachPlayerInRegion(plugin, action, concurrent)")
+)
+suspend fun forEachPlayerInRegion(
+    action: suspend (player: Player) -> Unit,
+    concurrent: Boolean = false,
+) = forEachPlayerInRegion(
+    plugin = getCallingSuspendingPlugin(),
+    action = action,
+    concurrent = concurrent,
+)
+
 /**
  * Executes a suspendable action on each online player, optionally concurrently.
  *
  * @param action The suspendable action to perform on each player.
  * @param concurrent If `true`, actions will run concurrently; otherwise, sequentially. Default is `false`.
  */
 suspend fun forEachPlayerInRegion(
+    plugin: SuspendingPlugin,
     action: suspend (player: Player) -> Unit,
     concurrent: Boolean = false,
 ) {
@@ -69,15 +83,15 @@ suspend fun forEachPlayerInRegion(
             Bukkit.getOnlinePlayers()
                 .map {
                     async {
-                        withContext(it.dispatcher(getCallingSuspendingPlugin())) {
+                        withContext(plugin.entityDispatcher(it)) {
                             action(it)
                         }
                     }
                 }.awaitAll()
         }
     } else {
         for (player in Bukkit.getOnlinePlayers()) {
-            withContext(player.dispatcher(getCallingSuspendingPlugin())) {
+            withContext(plugin.entityDispatcher(player)) {
                 action(player)
             }
         }
@@ -124,6 +138,8 @@ fun Location.toVector3d(): Vector3d {
  */
 fun Iterable<UUID>.toPlayers() = mapNotNull { Bukkit.getPlayer(it) }
 
+fun Iterable<UUID>.toOfflinePlayers() = mapNotNull { Bukkit.getOfflinePlayer(it) }
+
 /**
  * Converts a sequence of UUIDs to a sequence of online [Player] instances.
  *
@@ -132,6 +148,8 @@ fun Iterable<UUID>.toPlayers() = mapNotNull { Bukkit.getPlayer(it) }
  */
 fun Sequence<UUID>.toPlayers() = mapNotNull { Bukkit.getPlayer(it) }
 
+fun Sequence<UUID>.toOfflinePlayers() = mapNotNull { Bukkit.getOfflinePlayer(it) }
+
 /**
  * Checks if the player can see the specified location.
  *
@@ -155,7 +173,7 @@ fun Player.isChunkVisible(world: World, chunkX: Int, chunkZ: Int): Boolean {
  * @param plugin The suspending plugin instance. Defaults to the calling suspending plugin.
  * @return The entity's coroutine dispatcher.
  */
-@Deprecated("Stacktrace depth is inefficient")
+@Deprecated("Use 'plugin.entityDispatcher(this)' directly instead of relying on this helper, as it uses inefficient stacktrace inspection.")
 fun Entity.dispatcher(
     plugin: SuspendingPlugin = getCallingSuspendingPlugin(),
 ) = plugin.entityDispatcher(this)
@@ -167,6 +185,7 @@ fun Entity.dispatcher(
  * @param plugin The suspending plugin instance. Defaults to the calling suspending plugin.
  * @return The region's coroutine dispatcher.
  */
+@Deprecated("Use 'plugin.regionDispatcher(this)' directly instead of relying on this helper, as it uses inefficient stacktrace inspection.")
 fun Location.dispatcher(
     plugin: SuspendingPlugin = getCallingSuspendingPlugin(),
 ) = plugin.regionDispatcher(this)
@@ -191,7 +210,7 @@ fun getZFromChunkKey(key: Long): Int {
 
 fun ChunkSnapshot.getHighestBlockYAtBlockCoordinates(
     blockX: Int,
-    blockZ: Int
+    blockZ: Int,
 ): Int {
     return getHighestBlockYAt(blockX and 15, blockZ and 15)
 }

surf-api-core/surf-api-core-api/api/surf-api-core-api.api

@@ -4328,6 +4328,7 @@ public final class dev/slne/surf/surfapi/core/api/util/SurfUtil {
 	public static final fun getValue (Ljava/lang/ref/WeakReference;Ljava/lang/Object;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 	public static final fun logIf (Lcom/google/common/flogger/LoggingApi;Lkotlin/jvm/functions/Function0;Lkotlin/jvm/functions/Function1;)V
 	public static final fun logger ()Lcom/google/common/flogger/FluentLogger;
+	public static final fun mapAsync (Ljava/lang/Iterable;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static final fun setFinalField (Ljava/lang/reflect/Field;Ljava/lang/Object;B)V
 	public static final fun setFinalField (Ljava/lang/reflect/Field;Ljava/lang/Object;C)V
 	public static final fun setFinalField (Ljava/lang/reflect/Field;Ljava/lang/Object;D)V

surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/util/util.kt

@@ -14,6 +14,9 @@ import it.unimi.dsi.fastutil.ints.Int2ObjectOpenHashMap
 import it.unimi.dsi.fastutil.objects.Object2ObjectMap
 import it.unimi.dsi.fastutil.objects.Object2ObjectMaps
 import it.unimi.dsi.fastutil.objects.Object2ObjectOpenHashMap
+import kotlinx.coroutines.async
+import kotlinx.coroutines.awaitAll
+import kotlinx.coroutines.coroutineScope
 import sun.misc.Unsafe
 import java.lang.ref.SoftReference
 import java.lang.ref.WeakReference
@@ -382,4 +385,14 @@ operator fun <T> WeakReference<T>.getValue(thisRef: Any?, property: KProperty<*>
 
 operator fun <T> SoftReference<T>.getValue(thisRef: Any?, property: KProperty<*>): T? {
     return get()
+}
+
+suspend inline fun <E, R> Iterable<E>.mapAsync(crossinline transform: suspend (E) -> R): List<R> {
+    return coroutineScope {
+        map { element ->
+            async {
+                transform(element)
+            }
+        }.awaitAll()
+    }
 }

surf-api-velocity/surf-api-velocity-api/api/surf-api-velocity-api.api

@@ -4529,6 +4529,7 @@ public final class dev/slne/surf/surfapi/core/api/util/SurfUtil {
 	public static final fun getValue (Ljava/lang/ref/WeakReference;Ljava/lang/Object;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 	public static final fun logIf (Lcom/google/common/flogger/LoggingApi;Lkotlin/jvm/functions/Function0;Lkotlin/jvm/functions/Function1;)V
 	public static final fun logger ()Lcom/google/common/flogger/FluentLogger;
+	public static final fun mapAsync (Ljava/lang/Iterable;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static final fun setFinalField (Ljava/lang/reflect/Field;Ljava/lang/Object;B)V
 	public static final fun setFinalField (Ljava/lang/reflect/Field;Ljava/lang/Object;C)V
 	public static final fun setFinalField (Ljava/lang/reflect/Field;Ljava/lang/Object;D)V