rtp-paper-ADR-001 — Removal of PaperLib in Favour of Native Paper APIs¶
Status: Accepted (amended 2026-10-08, see Amendments 1 and 2) Formerly: ADR-005 Date: 2026-04-15
Amendment 2 (2026-10-08): Same-tick teleport for resident destinations (teleportPath)¶
Context¶
Amendment 1 recorded teleportAsync as "0-1 tick, 6-14 ms". Paper's source shows why the upper end is the common case: CraftEntity.teleportAsync always goes through loadChunksForMoveAsync, then scheduleOnMain, which queues the move on MinecraftServer.processQueue. That queue is drained once per tick in tickChildren, after the Bukkit scheduler heartbeat. A call made after the drain therefore waits for the next tick even when the chunk is already loaded. This is the 6 ms p50 dispatch-to-arrival latency in the Paper benchmarks, against about 1 ms for the earlier inline player.teleport.
The inline teleport was dropped because of the isInWall -> syncLoad stall. Its root cause was the arrival chunk ticket being released in the teleport tick (RTP-4), and decision 4 of Amendment 1 (holdArrivalReservation) removes it. An inline teleport is safe again when the destination chunk is already loaded.
Decision¶
PaperRTPPlayer#setLocationand the reflective Paper path inBukkitRTPPlayer#setLocationcallplayer.teleport(location)inline and complete the future at once whenTeleportPathSelector.canTeleportDirectholds: modeAUTO, caller on the primary thread, not Folia, andWorld#isChunkLoadedtrue for the destination chunk. Otherwise they useteleportAsyncas in Amendment 1.- The player is placed at block centre, so the bounding box (+/-0.3) stays inside that one chunk. The inline path therefore cannot trigger a chunk load (S-005), and the arrival hold keeps the chunk loaded through the player's first tick.
- Folia always uses
teleportAsync: a cross-region teleport must not run inline. Spigot (noteleportAsync), Fabric and NeoForge are unchanged. - S-004: an inline
falseresult (for example a cancelledPlayerTeleportEvent) completes the futurefalse, and the pipeline sends the configurableunsafemessage. An inline throw is logged and falls back toteleportAsync. advanced/performance.ymlteleportPath: AUTO | ASYNC(defaultAUTO).ASYNCrestores Amendment 1 behaviour exactly.
Consequences¶
- Positive: Kept-queue hits dispatched on the main thread arrive in the dispatch tick, removing up to one tick of latency per teleport. In a closed-loop load, throughput is in-flight attempts divided by latency, so it also raises the achievable teleport rate.
- Negative / Trade-offs: The teleport's work (event, entity move, tracking updates) now runs inside the caller's tick slice instead of the process-queue drain, so MSPT accounting moves between the two. Dispatches from async threads still take the
teleportAsyncpath and its tick wait. - Verification:
PaperRTPPlayerSetLocationTest(inline when resident on main; async when unloaded, off-main, on Folia, or withASYNC; inlinefalseand throw handling) andBukkitRTPPlayerSetLocationTest(reflective path). Latency gain to be confirmed in a bench run.
Amendment 1 (2026-10-08): Native Asynchronous Entity Teleportation (teleportAsync) and S-005 Arrival Tick Protection¶
Context and Problem¶
The original decision in ADR-005 focused on native asynchronous chunk loading (World#getChunkAtAsync), removing PaperLib. However, PaperLib's second core capability — PaperLib.teleportAsync for entity teleportation — was omitted from rtp-paper. Entity teleportation remained in BukkitRTPPlayer.setLocation(RTPLocation) (in rtp-bukkit-common, compiled against the Spigot API). While an if (IS_FOLIA) check was later added to reflectively call teleportAsync on Folia to avoid cross-region sync teleport exceptions, Paper was routed to legacy Spigot synchronous player.teleport(Location) on the primary server thread. When PaperRTPPlayer was introduced in ADR-072 for view-distance clamping, it only overrode view-distance accessors and inherited synchronous setLocation by omission.
Empirical profiling on Paper 26.2 (spark analysis during burst saturation benchmark run 20261008-111241, Linear issue RTP-4) revealed that synchronous player.teleport(Location) places the player into destination chunk coordinates before Paper's chunk system (Chunk System v2) has completed promoting the chunk to full ENTITY_TICKING status. Later in the arrival gametick, entity collision processing:
net.minecraft.world.entity.LivingEntity.baseTick
net.minecraft.world.entity.LivingEntity.isInWall
net.minecraft.world.entity.Entity.isInWall
net.minecraft.server.level.ServerChunkCache.getChunk
net.minecraft.server.level.ServerChunkCache.getChunkFallback
net.minecraft.server.level.ServerChunkCache.syncLoad
teleportAsync and incurred only ~0.1 ms/min on this path.
Analysis of teleportAsync Mechanics & Scheduling Latency¶
A concern was evaluated: does Paper's Entity#teleportAsync(Location) inherently delay the teleport or push it into a deferred background task?
- No Artificial Timer or Delay:
teleportAsyncdoes not inject arbitrary sleeps, timers, or artificial delays. Its completion is tied strictly to the destination chunk's readiness atENTITY_TICKINGstatus. - Pre-Verified Cache Resident Chunks: In LeafRTP, candidate destinations are served from pre-verified background queues where the target chunk is already loaded and pinned via a plugin ticket (
ChunkReservation). Because the underlying chunk future is already completed (isDone() == true), Paper's entity transition callback runs immediately on the main-thread task drain: - If dispatched early in the tick, execution completes within the same gametick.
- If dispatched after the current tick's task drain, execution completes at the start of the very next gametick (a transition window of 0–1 ticks, or 6–14 ms wall-clock latency).
- True Cost Comparison: While legacy synchronous
player.teleporttechnically executed on the current tick's call stack, it stalled that tick by 15.4 ms waiting on synchronous chunk loading. NativeteleportAsyncoffloads chunk readiness verification and executes without stalling the tick loop.
Decisions Landed¶
PaperRTPPlayer#setLocationNative Override:PaperRTPPlayer(inplatforms/rtp-paper/rtp-paper-common) overridessetLocation(RTPLocation)to directly invoke Paper's nativePlayer#teleportAsync(Location)API, completing the returnedCompletableFuture<Boolean>upon transition completion. Preserves player yaw and pitch rotation on arrival.BukkitRTPPlayer#setLocationDynamic Discovery & Fallback:BukkitRTPPlayer(inplatforms/rtp-bukkit/rtp-bukkit-common) dynamically resolves and cachesteleportAsync(Location)via reflection on any supporting Bukkit platform (Paper, Purpur, Folia), preserving rotation. It falls back to synchronousplayer.teleporton the scheduler only on pure Spigot / CraftBukkit runtimes whereteleportAsyncis absent.- S-004 Auditing & Fail-Safe Fallback:
Exceptional completions of
teleportAsynclog a warning viaRTP.logand complete the futurefalse(never hanging or silently swallowed). IfteleportAsyncthrows synchronously on invocation, it safely catches, logs, and falls back to a scheduled synchronous teleport. - Arrival Ticket Retention (
holdArrivalReservation): ComplementsteleportAsyncby retaining the destinationChunkReservationinTeleportPipelineTaskforARRIVAL_HOLD_TICKS = 20ticks post-arrival. This ensures the landing chunk remains pinned against aggressive chunk eviction policies (such as Paper'sdelay-chunk-unloads-by: 0s) until player-connection chunk tickets take over.
Consequences¶
- Positive: Eliminates the
isInWall -> syncLoadstall on Paper, restoring compliance with REQ-RTP-S-005 (zero main-thread chunk loading). - Positive: Completes the removal of PaperLib started in ADR-005 by adopting Paper's native async entity teleportation API across the Paper platform adapter.
- Positive:
BukkitRTPPlayergracefully accelerates on modern Paper/Purpur runtimes when running the Spigot adapter jar without requiring platform-specific recompilation. - Negative / Trade-offs: Entity transition completes asynchronously across a 0–1 tick boundary rather than inline synchronously; the teleport pipeline already expects asynchronous completion via
CompletableFuture<Boolean>, so no pipeline changes were required.
Context¶
PaperLib is a cross-platform compatibility shim (async chunk loading, etc.) intended for plugins that run on both Paper and plain Spigot. RTP maintains separate adapter modules (rtp-bukkit, rtp-paper) for each platform, so the Paper adapter has no Spigot code path to shim and a cross-platform compatibility library adds no value there.
Decision¶
rtp-paper shall not depend on PaperLib. It calls Paper's native async chunk loading APIs directly.
Because rtp-paper is loaded only on Paper servers, a compatibility shim is unnecessary. Direct native calls remove a runtime dependency, eliminate an indirection layer, and keep the adapter on the current, non-deprecated Paper API surface.
Consequences¶
- Positive:
- Removes a runtime dependency; operators no longer need PaperLib on their server when running the Paper adapter.
- The adapter uses Paper's current, actively maintained async chunk loading API directly, without a deprecated shim in the call path.
-
Reduces indirection and simplifies the call stack for async chunk operations.
-
Negative / Trade-offs:
- The
rtp-paperadapter is now strictly Paper-only at compile time; it cannot be loaded on a plain Spigot server (this was already the intended deployment model). - Any future Paper API changes shall be handled directly in
rtp-paperrather than being absorbed by a compatibility library.
References¶
- PaperLib repository: https://github.com/PaperMC/PaperLib
- Implementing modules:
rtp-paper(all version submodules),rtp-bukkit(BukkitRTPPlayer) - Implementing classes:
PaperRTPPlayer,BukkitRTPPlayer,TeleportPathSelector,TeleportPipelineTask(holdArrivalReservation) - Tests:
PaperRTPPlayerSetLocationTest,BukkitRTPPlayerSetLocationTest,ReqRtpS005ArrivalChunkHoldTest - Changelog entry:
CHANGELOG.md— 2.0.18 - Upgrade notes for operators:
MIGRATION.md - Related ADRs: leafrtp-ADR-009 (
ChunkReservationabstraction), leafrtp-ADR-011 (stale-chunk guard), leafrtp-ADR-054 (view-distance clamp andPaperRTPPlayer) - Issue tracking: Linear
RTP-4 - Requirements:
REQ-RTP-S-001(platform compatibility),REQ-RTP-S-004(no silent teleport failures),REQ-RTP-S-005(zero main-thread chunk loading),REQ-PAPER-F-001(Paper async chunk load and entity teleport),REQ-SPIGOT-F-001(Spigot chunk load and entity teleport)