Use PaperLib's asynchronous teleports and chunk loads on 26.x (#6634)

### Information

This PR fixes #6632.

### Details

**Proposed fix:**
PaperLib 1.0.6 reads the server version from `Bukkit#getVersion()` with
a regex that only accepts a single digit major version, so on 26.x it
reads the version as 0 and selects its synchronous fallbacks. Every
`PaperLib.teleportAsync`, `getChunkAtAsync` and
`getBedSpawnLocationAsync` call in EssentialsX then loads the chunk and
teleports on the calling thread instead of using Paper's asynchronous
API.

When PaperLib has not recognised a Paper server that is newer than 1.13,
EssentialsX now installs a PaperLib environment which selects the
handlers PaperLib would have chosen for 1.15.2 and later. Nothing
changes on servers where PaperLib reads the version correctly.

**Environments tested:**
OS: Ubuntu 24.04 (WSL2)
Java version: Temurin 25.0.4.1
- [x] Most recent Paper version (26.3, git-Paper-140)
- ~~CraftBukkit/Spigot/Paper 1.12.2~~
- ~~CraftBukkit 1.8.8~~

**Demonstration:**
`ModernPaperEnvironmentTest` checks that a 26.x version string leaves
PaperLib's own environment calling `Entity#teleport` and that the new
environment calls `Entity#teleportAsync` and `World#getChunkAtAsync`.
`./gradlew build` passes.

Handlers PaperLib selected on Paper 26.3 (build 140), read from the
bundled PaperLib by a test plugin:

Before (2.x, Paper 26.3 build 140):
```
PROBE paperlib env=PaperEnvironment version=0 asyncChunksHandler=AsyncChunksSync asyncTeleportHandler=AsyncTeleportSync isGeneratedHandler=ChunkIsGeneratedUnknown bedSpawnLocationHandler=BedSpawnLocationSync
```
After (this PR):
```
PROBE paperlib env=ModernPaperEnvironment version=0 asyncChunksHandler=AsyncChunksPaper_15 asyncTeleportHandler=AsyncTeleportPaper_13 isGeneratedHandler=ChunkIsGeneratedApiExists bedSpawnLocationHandler=BedSpawnLocationPaper
```
The same scripted run of EssentialsX commands (teleports across 12000
blocks, `/tpa`, `/home`, `/spawn`, `/back` after death, a passenger, 22
checks) passes before and after.

Co-authored-by: Raw2d <255907405+Raw2d@users.noreply.github.com>

Author: lewisgibson

Essentials/src/main/java/com/earth2me/essentials/Essentials.java

@@ -46,6 +46,7 @@
 import com.earth2me.essentials.updatecheck.UpdateChecker;
 import com.earth2me.essentials.userstorage.ModernUserMap;
 import com.earth2me.essentials.utils.FormatUtil;
+import com.earth2me.essentials.utils.ModernPaperEnvironment;
 import com.earth2me.essentials.utils.PasteUtil;
 import com.earth2me.essentials.utils.VersionUtil;
 import io.papermc.lib.PaperLib;
@@ -261,6 +262,10 @@ public void onEnable() {
                 getLogger().severe(getAdventureFacet().miniToLegacy(tlLiteral("serverSnapshot")));
             }
 
+            if (PaperLib.isPaper() && !PaperLib.isVersion(13) && VersionUtil.getServerBukkitVersion().isHigherThanOrEqualTo(VersionUtil.v1_13_0_R01)) {
+                PaperLib.setCustomEnvironment(new ModernPaperEnvironment());
+            }
+
             final PluginManager pm = getServer().getPluginManager();
             for (final Plugin plugin : pm.getPlugins()) {
                 if (plugin.getDescription().getName().startsWith("Essentials") && !plugin.getDescription().getVersion().equals(this.getDescription().getVersion()) && !plugin.getDescription().getName().equals("EssentialsAntiCheat")) {

Essentials/src/main/java/com/earth2me/essentials/utils/ModernPaperEnvironment.java

@@ -0,0 +1,23 @@
+package com.earth2me.essentials.utils;
+
+import io.papermc.lib.environments.PaperEnvironment;
+import io.papermc.lib.features.asyncchunks.AsyncChunksPaper_15;
+import io.papermc.lib.features.asyncteleport.AsyncTeleportPaper_13;
+import io.papermc.lib.features.bedspawnlocation.BedSpawnLocationPaper;
+import io.papermc.lib.features.chunkisgenerated.ChunkIsGeneratedApiExists;
+
+/**
+ * A PaperLib environment for Paper servers whose version PaperLib cannot read.
+ * <p>
+ * PaperLib 1.0.6 expects a single digit major version in {@code Bukkit#getVersion()}, so it reads 26.x as version 0 and
+ * selects its synchronous fallbacks for chunk loading, teleporting and bed lookups. All of those exist on every Paper
+ * version that reports a year based version.
+ */
+public class ModernPaperEnvironment extends PaperEnvironment {
+    public ModernPaperEnvironment() {
+        asyncChunksHandler = new AsyncChunksPaper_15();
+        asyncTeleportHandler = new AsyncTeleportPaper_13();
+        isGeneratedHandler = new ChunkIsGeneratedApiExists();
+        bedSpawnLocationHandler = new BedSpawnLocationPaper();
+    }
+}

Essentials/src/test/java/com/earth2me/essentials/utils/ModernPaperEnvironmentTest.java

@@ -0,0 +1,62 @@
+package com.earth2me.essentials.utils;
+
+import io.papermc.lib.environments.PaperEnvironment;
+import org.bukkit.Bukkit;
+import org.bukkit.Location;
+import org.bukkit.World;
+import org.bukkit.entity.Entity;
+import org.bukkit.event.player.PlayerTeleportEvent.TeleportCause;
+import org.junit.jupiter.api.Test;
+import org.mockito.MockedStatic;
+
+import java.util.function.Consumer;
+import java.util.function.Supplier;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.mockStatic;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+public class ModernPaperEnvironmentTest {
+    private static final String YEAR_VERSION = "26.3-140-main@a1b2c3d (2026-09-30T10:00:00Z) (MC: 26.3)";
+
+    @Test
+    public void testPaperLibFallsBackToSynchronousTeleportOnYearVersions() {
+        // Documents why ModernPaperEnvironment exists: PaperLib itself picks the synchronous handlers here.
+        withVersion(YEAR_VERSION, PaperEnvironment::new, env -> {
+            final Entity entity = mock(Entity.class);
+            final Location location = new Location(mock(World.class), 0, 64, 0);
+            env.teleport(entity, location, TeleportCause.PLUGIN);
+            verify(entity).teleport(location, TeleportCause.PLUGIN);
+            verify(entity, never()).teleportAsync(any(Location.class), any(TeleportCause.class));
+        });
+    }
+
+    @Test
+    public void testTeleportsAsynchronouslyOnYearVersions() {
+        withVersion(YEAR_VERSION, ModernPaperEnvironment::new, env -> {
+            final Entity entity = mock(Entity.class);
+            final Location location = new Location(mock(World.class), 0, 64, 0);
+            env.teleport(entity, location, TeleportCause.PLUGIN);
+            verify(entity).teleportAsync(location, TeleportCause.PLUGIN);
+            verify(entity, never()).teleport(any(Location.class), any(TeleportCause.class));
+        });
+    }
+
+    @Test
+    public void testLoadsChunksAsynchronouslyOnYearVersions() {
+        withVersion(YEAR_VERSION, ModernPaperEnvironment::new, env -> {
+            final World world = mock(World.class);
+            env.getChunkAtAsync(world, 1, 2, true);
+            verify(world).getChunkAtAsync(1, 2, true, false);
+        });
+    }
+
+    private static <E extends PaperEnvironment> void withVersion(final String version, final Supplier<E> create, final Consumer<E> test) {
+        try (MockedStatic<Bukkit> bukkit = mockStatic(Bukkit.class)) {
+            bukkit.when(Bukkit::getVersion).thenReturn(version);
+            test.accept(create.get());
+        }
+    }
+}