Skip to content

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

Open
lewisgibson wants to merge 1 commit into
EssentialsX:2.xfrom
lewisgibson:fix-paperlib-26x
Open

lewisgibson wants to merge 1 commit into
EssentialsX:2.xfrom
lewisgibson:fix-paperlib-26x

Conversation

@lewisgibson

Copy link
Copy Markdown

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

  • 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.

PaperLib 1.0.6 reads the server version with a regex that only accepts a single digit major version, so on 26.x it sees version 0 and falls back to its synchronous handlers. Every PaperLib.teleportAsync, getChunkAtAsync and getBedSpawnLocationAsync call in EssentialsX then ran a blocking teleport or chunk load instead of the asynchronous Paper API.

When PaperLib cannot read the version of a server that is newer than 1.13, install an environment that selects the handlers PaperLib would have chosen for a modern Paper.

Co-authored-by: Raw2d <255907405+Raw2d@users.noreply.github.com>
@lewisgibson lewisgibson mentioned this pull request Oct 1, 2026
3 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Teleports and chunk loads are synchronous on Paper 26.x

1 participant