LeafRTP-Pro v3.2.0

Commands (registered aliases: /rtp, /wild):

Key permission nodes (full set in plugin.yml):

LeafRTP-Pro splits configuration by concern under plugins/RTP/. Every file is hot-reloadable (/rtp reload <file>) and editable in-game via /rtp config <file>.

Confidence: measured; from plugin docs; inferred from architecture.

Metrics: Throughput (TP/s, higher better) - MSPT p99 (worst 1-in-100 main-thread tick in ms; <~50 ms = no dropped tick) - Min TPS (20.00 = no hiccup) - CPU / TP (main-thread CPU per successful teleport).

Paper 1.20.1 / 1.21.11 - recommended platform. Eight plugins, same harness, same world, same two OPed clients.

§ EssentialsX /tpr is a teleport-request command (handshake + accept), not a teleport-do command; the harness's 5 s per-attempt deadline times out a fraction of the request-accept latencies. Numbers are dispatch-shaped, not plugin-broken.

Spigot 1.20.1 - platform-wide chunk-gen ceiling caps everyone at 1-1.5 TP/s; the latency tail is what matters.

Folia 26.1 - on Folia, throughput plus the server-emitted region watchdog are the discriminators (global MSPT is a single-region sample and not meaningful).

On Folia, LeafRTP's main-thread cost per teleport drops to ~4 ms as region threads parallelize work Paper serializes onto one tick thread. EzRTP's 7 watchdog stalls (one region unresponsive 20.4 s) are the server's own record of synchronous World.loadChunk calls on region threads; LeafRTP issued none. Note the free build cleared the same run at 12.5 TP/s with zero stalls - the shared rtp-core engine, not a Pro-only adapter, carries the Folia result, and Pro's tuned adapter is built to pull further ahead as per-region contention rises.

Architecture support matrix:

Memory & TPS: queue bounded (bounded by cacheCap); each entry is a small POJO. Server TPS held at 20.00 across every Paper and Folia run. On Spigot, every plugin saturates to the same chunk-gen ceiling; LeafRTP-Pro just spends those ticks doing fewer things.

- Paper rows are 2-client runs (LeafRTP-Pro reproduced n=2; others n=1 on a single rig). The Folia run used 3 clients and its EzRTP failure is corroborated by the server's own watchdog log, independent of the harness. - JakesRTP Spigot row ran in slot 4 of a 4-phase chain - Min TPS / CPU-per-TP confounded by carry-over; dispatch-time numbers (throughput, p99) remain valid.

Caveats. Small client counts only (2 on Paper, 3 on Folia; the number is a floor, not a ceiling). Hardware, view distance, world state, and other plugins will move the numbers. Competitor plugins update frequently; corrections welcome via GitHub issue with a contradicting repro or doc link. This table measures performance only; feature breadth is not benchmarked here. LeafRTP ships the clickable GUI menu, Vault economy, the lifecycle effects engine, and eight bundled claim integrations alongside these numbers - it does not trade features for speed.

Full methodology, raw CSVs, per-run analyses: helpers/StressTestRTP/. Video benchmark of /rtp on a custom world generator: youtu.be/V0NyNK9JydM.

Five pillars:

• Deterministic spiral selection. Bounded math, uniform player distribution even on massive worlds; no unbounded re-roll loops.
• Platform-native performance. Spigot, Paper, and Folia each get the threading model that fits them - not the lowest-common-denominator.
• Active resource watchdog. Background sweep reclaims chunk tickets from abandoned teleports via WeakReferences; nothing stays force-loaded past its reservation window.
• Direct region I/O pre-filter. .mca region files parsed off-tick on a background pool, including biomes (custom namespaced biomes like Iris included). Paper-grade safety evaluation on Spigot; skips per-candidate Region-Thread hops on Folia.
• Admin-driven background mapping. /rtp scan start|pause|resume|reset|cancel walks the spiral during idle periods so spatial memory accumulates without player traffic. Fully-automatic self-warming is on the roadmap for 3.0.0 final.

Chunk loading, by platform:

• Paper - World#getChunkAtAsync used directly. No pre-filter, no main-thread fallback. Reference platform.
• Paper forks (Leaf, Leaves, Purpur, Pufferfish, Airplane, DivineMC, -) - inherit the Paper code path.
• Folia - Anvil read-only pre-filter on ForkJoinPool.commonPool() before the Region Scheduler; rejected candidates never hop a thread. Confirmed candidates load through Folia's native async API; teleports dispatch through the Entity Scheduler.
• Spigot - .mca region files parsed off-tick (isAir, isSafe, surface-height, sky-light, biome). Paper-class throughput on plain Spigot.
• Mohist / Arclight - officially supported. Spigot code path applies.
• Fabric - first-class, stable, in-tree adapter; supported and regularly tested, at feature parity with the Bukkit family. Loom-remapped obf/unobf carriers cover 1.20.x, 1.21.x, and MC 26.x runtimes.

Honest fallback caveats. The Anvil pre-filter is a data source, not a universal gate. It falls through to the platform's native chunk API in two cases: (1) the chunk is already loaded (live data wins), or (2) the probe returns unknown (no region file, unsupported data version, decode error, un-populated). On Spigot the fallback is one on-tick getChunkAt. On Folia it's one Region-Scheduler hop. Custom generators (Iris, Terra, datapacks) do not trigger the fallback - populated .mca palettes are read directly, preserving modded and namespaced IDs that the Bukkit enum would collapse.

Upgrade-drift-proof biome filtering. When you bump your Paper or Folia server across MC versions, Mojang's seed-based biome assignment can change for already-written coordinates. The Anvil-first biome read keeps the .mca palette authoritative for populated chunks - the biome a player lands in is the biome your biomes: allow-list was written against. No re-pregen, no re-tuning after an upgrade.

Operator takeaway: Paper and Folia run chunk I/O fully off-tick. On vanilla Spigot the Anvil pre-filter covers the common case; rare main-thread fallback is bounded by your configured tick-budget; no platform silently blocks the tick loop without reporting it.

Without spatial indexing, teleportation is a guessing game and the numbers are ugly. A typical Overworld is only ~45% safely teleportable- (oceans, rivers, ravines, steep terrain eat the rest); the Nether is dominated by lava seas and wall-to-wall stone; the End is almost entirely void. Standard RTPs pay full chunk-load cost to rediscover this one candidate at a time, forever.

LeafRTP-Pro plots your world's geometry as it evaluates candidates. When it hits a massive ocean or unsafe biome, it remembers that sector and shrinks the searchable area, so known bad sectors never get loaded again. The longer it runs, the faster it gets - and /rtp scan keeps the learning going during idle periods.

Watch the background scan crawl the spiral and accumulate spatial memory in real time: youtu.be/Ftjy1zw_S04.

Persistence across restarts: learned bad-sector state survives a JVM bounce - MemoryShape.save / load writes per-region spatial memory to disk on shutdown and reloads on startup, alongside the configuration cache (compiled safety sets, region geometry). H2, SQLite, MySQL, and PostgreSQL backends support shared multi-server state.

- Local-profile estimate from a vanilla 1.21 seed set; Nether and End are still qualitative. Anonymous opt-in telemetry is on the roadmap to source this number properly.

safety.yml has a first-class token grammar. Six shapes can be mixed freely in unsafeBlocks and airBlocks:

• Plain material: LAVA, MAGMA_BLOCK.
• Material + state predicate: OAK_SLAB[waterlogged=true]. Multiple predicates AND together: OAK_SLAB[waterlogged=true,type=top].
• Numeric range predicate: WATER[level>=5], LIGHT[level<8]. Operators >= / <= / > / < bound fluid levels, light levels, and any integer block-state property; fail-open on an absent or non-numeric value.
• Vanilla block tag: #minecraft:leaves, #minecraft:fire, #minecraft:campfires. Live-registry expansion at config-load lands in 3.0.0 final - use explicit names alongside tag tokens during the beta.
• Tag + state predicate: #minecraft:slabs[waterlogged=true] - "any slab, but only when waterlogged".
• Wildcard + state predicate: *[waterlogged=true] - "any block, matched when waterlogged". One line replaces the entire waterloggable enumeration.

Properties:

• Fail-open on unknown tags/properties - missing tags on older MC versions silently reduce coverage rather than breaking startup. Configs stay portable.
• Never silent on malformed tokens - typos like OAK_SLAB[waterlogged=true[/I] surface as [WARNING] [safety.yml] rejected token '<token>': <reason>.
  [*]Zero hot-path cost when unused - block-state extraction only fires when a token actually needs it; plain-material configs pay nothing.
  [*]Platform-portable tag resolution - Bukkit reads from Bukkit.getTag; the standalone rtp-tags module parses tag JSON directly from data packs and jars for future non-Bukkit platforms.

Default safety.yml is ~25% shorter: FIRE+SOUL_FIRE -> #minecraft:fire; every waterloggable block -> *[waterlogged=true]; dozens of decorative plants -> #minecraft:flowers, #minecraft:saplings, #minecraft:crops, etc.

Engine:

• Any number of teleport regions per world; per-region shape (Square, Circle, Rectangle), radius, center, curve weighting, vertical bounds, world override, permission gates.
• Vertical adjustors (Linear, Jump, Fixed) for sky islands, void worlds, Nether ceilings.
• Multi-dimensional (Overworld, Nether, End, custom).
• Hot-reloadable YAML; clickable /rtp menu (book on Paper / Folia, chat-paginated fallback elsewhere) hardened in 3.0.0-beta.3, with /rtp config <file> view as a per-file deep-link.
• Fully async chunk loading on Paper / Folia; off-tick Anvil pre-filter on Spigot.
• Per-player isolated queues alongside a global queue - one player's bad luck never starves another's teleport.
• Administrative scan lifecycle (start/pause/resume/reset/cancel) to pre-populate spatial memory without teleporting players.
• Persistent learned state via H2 / SQLite / MySQL / PostgreSQL.
• Per-tick time budgets and (on Folia) per-tick task-count caps on the region-bound pipe.

Player polish (UX):

• Configurable countdown/warmup messages during pre-teleport.
• Particles, sounds, fireworks, potions, note-block effects via effects-api, attached to lifecycle phases, gated by rtp.effects.<name> permissions.
• Movement-cancel, damage-cancel, invulnerability-after-teleport timers.
• Optional PvP / combat-tag gate. Off by default; when enabled, /rtp is refused or delayed for players who recently dealt or took PvP damage, so a teleport can't be used to escape a fight. Native combat tracking works out of the box, with optional PvPManager / CombatLogX / Simple Combat Log integration; the refusal message is fully localizable (messages.yml).
• Optional landing platform with configurable material and decay timer.
• Per-region arrival schematics. Drop a .schem named after a region into plugins/RTP/schematics/ (e.g. schematics/default.schem) and every teleport into that region pastes it - a lobby pad, arrival shrine, or custom platform - centered on the landing spot. Cross-platform Sponge .schem, decoded in-house (no WorldEdit required), claim-aware (never overwrites protected land) and audited; the bundled Skyblock prefab ships one ready to go.
• PlaceholderAPI: queue depth (total/public/personal), last-teleport coordinates, player status.
• Public rtp-api (same surface as Free) - trigger LeafRTP from GUI, NPC, quest reward; build your own UX without forking.
• Platform-agnostic addons - addons compile against rtp-api only and load through the RTPAddon ServiceLoader SPI, so one addon module runs unchanged on Spigot, Paper, Folia, Fabric, and NeoForge. Config, safety hooks, teleport-pipeline callbacks, and scheduling are reached through platform-neutral APIs; you only add a platform module when the addon opens a platform-native UI. See the bundled RTP_ExampleAddon.

Bundled claim integrations (no extra download, folded in per ADR-019): Factions, GriefDefender, GriefPrevention, HuskTowns, Lands, RedProtect, TownyAdvanced, WorldGuard.

Pro-only configuration: Vault per-region pricing, complete localization (lang/**), login-reserve cache, visitor mode.

What's on deck, with direction:

• Fully-automatic self-warming - background spatial-memory accumulation without the /rtp scan verb.
• Anonymous opt-in telemetry - reference benchmark sourced from real deployments.
• Chunky-driven scan generation - optionally let a bulk pre-generator (Chunky or similar) lay a region's chunks down first, then scan reads them cheaply through the Anvil pre-filter; one command surface instead of juggling two tools, with the current generate-as-you-go scan as the fallback.
• Leaner scan path - measure how accurately the off-tick Anvil pre-filter alone trims candidates and, where it's accurate enough, skip the heavier full-load verification pass during scans.
• Accelerated scan compute (exploration) - investigating offloading the bulk safety pre-filter sweep to a high-throughput compute backend (native SIMD, GPU/OpenCL, or an external accelerated generator), with a clean fallback to the current path when none is present.

File a GitHub issue if you hit something not on the list.

Q: How do I stop /rtp from lagging my server, and why is LeafRTP-Pro faster than other random teleport plugins?
A: Pre-warmed queue. In most cases a verified destination is ready before you type /rtp. Two design choices keep that queue cheap to refill: a persistent spatial memory per region (the plugin remembers which sectors failed safety checks, so the spiral selector skips known-bad ground instead of rerolling indefinitely) and an off-tick async pre-filter (Anvil region files are read directly to reject unsafe biomes/blocks before any chunk is loaded, so candidate verification never blocks the main thread).

Q: How do I set up teleportation between worlds?
A: See the admin guide. Resolution order: player's current world (or world: param) -> world's target region -> region's target world.

Q: Does LeafRTP work on Folia?
A: Yes, on both editions. The free build runs on Folia out of the box with a basic regionized scheduler (correctness-first: global/region/entity scheduling + async teleport). LeafRTP-Pro adds the tuned Folia adapter - the Region Scheduler with an off-tick pre-filter so no region stalls. Measured on Folia 26.1 under a 3-client burst, LeafRTP-Pro sustained 13.5 TP/s at ~100 % success with 3.96 ms of main-thread cost per teleport and zero region watchdog stalls; the free build cleared the same run at 12.5 TP/s. Pro's tuned adapter is built to pull further ahead as per-region contention rises.

Q: Do you support triangle / diamond region shapes?
A: Use the Polygon shape. A triangle is a 3-vertex polygon and a diamond is a rotated square, so both are already expressible without a dedicated shape type - define the vertices you want and the bounded spiral fills it.

Q: Do I need Chunky (or another pre-generator)?
A: No, but they work well together. /rtp scan start|pause|resume|reset|cancel walks a region off-tick, verifies safety, and generates any chunks it reaches that aren't on disk yet (via the server's own world generator) while recording which sectors are unsafe in persistent spatial memory. So a separate pre-generator stays optional: run Chunky (or any pre-generator) first if you want the whole map on disk up front, and scan will then read those chunks cheaply through the Anvil pre-filter instead of generating them as it goes.

Q: How does biome targeting behave on a pregenerated or upgraded world?
A: LeafRTP reads biome data from the populated .mca region files via the Anvil pre-filter, so /rtp biome:<x> reflects the biomes actually written to disk. Plugins that lean on the live generator/noise-map biome lookup can return the wrong biome on a world that was pregenerated elsewhere or migrated across a Minecraft version, where seed-based assignment has drifted - the Anvil-first read stays authoritative in those cases.

Q: Iris / Terra / custom datapack generators?
A: Yes - deliberate 3.0 design goal. The Anvil pre-filter reads .mca palette data directly, so populated custom-generator chunks evaluate off-tick like vanilla. That's strictly more accurate than the live Bukkit view, which collapses modded IDs to vanilla cousins. Un-populated chunks fall through to a live load as the authoritative safety net.

Q: Existing safety.yml on upgrade?
A: Plain-material entries keep working unchanged; the new grammar is strictly additive.

Q: Best LeafRTP plugin / setup for Paper 1.21 performance?
A: Paper, with memory to spare for the location cache. LeafRTP works particularly well on pre-generated worlds.

Q: Can I downgrade to the free LeafRTP build?
A: Yes - same configuration, same data files, same commands. The free build still runs on Folia (basic regionized scheduling); what you give up is the tuned Folia adapter, plus proxy, SQL/Redis, Vault, multilingual, and the tag/state-predicate grammar.

The whole point of Pro is that you stop thinking about /rtp. It drops in, it works, and on the rare day it doesn't, a maintainer who actually owns the code answers you - not a community thread that goes quiet. That is the part the benchmark can't show: the other plugins' numbers (second-scale ticks, region stalls, sync chunk loads) are not a bad afternoon, they are the ceiling of how good your players' experience can get on that engine. With LeafRTP you are not giving anything up to get that - everything those plugins advertise (GUI, economy, effects, claim support, cross-server) is already in the box - you are just removing the lag and the unanswered ticket.

• Priority support. Pro tickets jump the queue ahead of the free build - this is the support tier the early-access platforms and scaling backends are guaranteed on.
• Bug reports and configuration questions are welcome - the admin guide answers most setup questions, and a clear repro (server version, plugin version, platform, relevant configs and log lines) gets a fast resolution.
• Response time: 24-72 h on weekdays. Critical safety issues jump the queue.
• Feature requests via GitHub issues. Priority follows the published roadmap.
• Native NeoForge is supported on Minecraft 1.21.x / 26.1.x. Native Forge is not supported - use Arclight or Mohist with the Spigot/Paper jar.