Merge pull request #106 from ez-plugins/fix/folia-error

fix: BukkitPlatformScheduler teleportAsync on Folia (v3.2.3)

Author: ez-plugins

.github/workflows/nightly.yml

@@ -20,6 +20,19 @@ Release tags use the `v` prefix (e.g. `v3.0.2`).
 
 ---
 
+## [3.2.3] - 2026-05-16
+
+### Fixed
+
+- **Folia teleport crash** (`UnsupportedOperationException: Must use teleportAsync while in
+  region threading`): `BukkitPlatformScheduler` now overrides `teleportAsync` and, when running
+  on Folia (`regionizedRuntime` capability), calls `player.teleportAsync(Location)` via
+  reflection instead of the forbidden synchronous `player.teleport()`. The Bukkit module was
+  the only scheduler that still used the synchronous fallback from the interface default;
+  `PaperPlatformScheduler` already called `teleportAsync` directly.
+
+---
+
 ## [3.2.2] - 2026-05-12
 
 ### Fixed

CHANGELOG.md

@@ -5,13 +5,13 @@
   <parent>
     <groupId>com.skyblockexp</groupId>
     <artifactId>ezrtp-parent</artifactId>
-    <version>3.2.2</version>
+    <version>3.2.3</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 
   <groupId>com.skyblockexp</groupId>
   <artifactId>ezrtp-api</artifactId>
-  <version>3.2.2</version>
+  <version>3.2.3</version>
   <packaging>jar</packaging>
   <name>EzRTP API</name>
   <description>Lightweight public API for EzRTP intended for third-party plugins.</description>

ezrtp-api/pom.xml

@@ -5,13 +5,13 @@
   <parent>
     <groupId>com.skyblockexp</groupId>
     <artifactId>ezrtp-parent</artifactId>
-    <version>3.2.2</version>
+    <version>3.2.3</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 
   <groupId>com.skyblockexp</groupId>
   <artifactId>ezrtp-bukkit</artifactId>
-  <version>3.2.2</version>
+  <version>3.2.3</version>
   <packaging>jar</packaging>
   <name>EzRTP (Bukkit)</name>
   <description>EzRTP Bukkit-compatible plugin module.</description>
@@ -111,7 +111,7 @@
     <dependency>
       <groupId>com.skyblockexp</groupId>
       <artifactId>ezrtp-common</artifactId>
-      <version>3.2.2</version>
+      <version>3.2.3</version>
     </dependency>
   </dependencies>
 

ezrtp-bukkit/pom.xml

@@ -1,10 +1,13 @@
 package com.skyblockexp.ezrtp.platform;
 
 import org.bukkit.Bukkit;
+import org.bukkit.Location;
 import org.bukkit.World;
+import org.bukkit.entity.Player;
 import org.bukkit.plugin.Plugin;
 
 import java.lang.reflect.Method;
+import java.util.concurrent.CompletableFuture;
 
 public final class BukkitPlatformScheduler implements PlatformScheduler {
 
@@ -95,6 +98,28 @@ public void executeRegionDelayed(
         plugin.getServer().getScheduler().runTaskLater(plugin, task, delayTicks);
     }
 
+    @Override
+    public CompletableFuture<Boolean> teleportAsync(Player player, Location destination) {
+        if (capabilities.regionizedRuntime()) {
+            // Folia forbids synchronous teleport from a region thread. Use teleportAsync
+            // via reflection so that the bukkit module works on Folia without a hard
+            // Paper/Folia compile-time dependency.
+            return invokeTeleportAsync(player, destination);
+        }
+        return CompletableFuture.completedFuture(player.teleport(destination));
+    }
+
+    @SuppressWarnings("unchecked")
+    private CompletableFuture<Boolean> invokeTeleportAsync(Player player, Location destination) {
+        try {
+            Method method = player.getClass().getMethod("teleportAsync", Location.class);
+            return (CompletableFuture<Boolean>) method.invoke(player, destination);
+        } catch (ReflectiveOperationException ignored) {
+            // teleportAsync not available (shouldn't happen on Folia); fall back to sync.
+            return CompletableFuture.completedFuture(player.teleport(destination));
+        }
+    }
+
     private boolean invokeGlobalRun(Runnable task) {
         try {
             Object globalScheduler = Bukkit.class.getMethod("getGlobalRegionScheduler").invoke(null);

ezrtp-bukkit/src/main/java/com/skyblockexp/ezrtp/platform/BukkitPlatformScheduler.java

@@ -1,6 +1,8 @@
 package com.skyblockexp.ezrtp.platform;
 
+import org.bukkit.Location;
 import org.bukkit.Server;
+import org.bukkit.entity.Player;
 import org.bukkit.plugin.Plugin;
 import org.bukkit.scheduler.BukkitScheduler;
 import org.bukkit.scheduler.BukkitTask;
@@ -14,6 +16,7 @@
 
 import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.anyLong;
 import static org.mockito.ArgumentMatchers.eq;
@@ -175,4 +178,42 @@ void executeRegionDelayed_withFoliaCapabilities_doesNotThrow() {
 
         assertDoesNotThrow(() -> scheduler.executeRegionDelayed(null, 0, 0, () -> {}, 20L));
     }
+
+    // --- teleportAsync ---
+
+    /**
+     * On Folia (regionized), teleportAsync must not call the synchronous Player.teleport().
+     * Since Player.teleportAsync() is not available in the test JVM, the reflection path
+     * falls through to the sync fallback. This test verifies the method does not throw and
+     * returns a completed future.
+     */
+    @Test
+    void teleportAsync_withFoliaCapabilities_doesNotThrow() {
+        Player player = mock(Player.class);
+        Location destination = mock(Location.class);
+        when(player.teleport(destination)).thenReturn(true);
+
+        BukkitPlatformScheduler scheduler =
+                new BukkitPlatformScheduler(plugin, PlatformRuntimeCapabilities.PAPER_FOLIA);
+
+        assertDoesNotThrow(() -> scheduler.teleportAsync(player, destination));
+    }
+
+    /**
+     * On standard Bukkit, teleportAsync delegates to the synchronous Player.teleport().
+     */
+    @Test
+    void teleportAsync_withBukkitCapabilities_callsSyncTeleport() throws Exception {
+        Player player = mock(Player.class);
+        Location destination = mock(Location.class);
+        when(player.teleport(destination)).thenReturn(true);
+
+        BukkitPlatformScheduler scheduler =
+                new BukkitPlatformScheduler(plugin, PlatformRuntimeCapabilities.BUKKIT);
+
+        Boolean result = scheduler.teleportAsync(player, destination).get();
+
+        assertTrue(result);
+        verify(player).teleport(destination);
+    }
 }

ezrtp-bukkit/src/test/java/com/skyblockexp/ezrtp/platform/BukkitPlatformSchedulerFoliaTest.java

@@ -5,13 +5,13 @@
   <parent>
     <groupId>com.skyblockexp</groupId>
     <artifactId>ezrtp-parent</artifactId>
-    <version>3.2.2</version>
+    <version>3.2.3</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 
   <groupId>com.skyblockexp</groupId>
   <artifactId>ezrtp-common</artifactId>
-  <version>3.2.2</version>
+  <version>3.2.3</version>
   <packaging>jar</packaging>
   <name>EzRTP Common</name>
   <description>Shared utilities for EzRTP (platform-independent)</description>