Current Version: 3.0.0-beta.1 —
A high-performance random teleportation plugin for Bukkit-derived Minecraft servers (Spigot, Paper, Folia).
Most random teleport plugins work by repeatedly rolling random coordinates until they find a valid spot, a naive approach that can stall the server under load. RTP takes a different approach, rooted in a mathematical proof that maps the 2D teleport region onto a 1D curve, which eliminates rerolling entirely and guarantees uniform spatial distribution:
- Bounded algorithms, not rerolling. Location selection runs in deterministic time (O(log n)) by preemptively subtracting known-invalid sectors from the candidate space. See the original mathematical writeup and ADR-001 for the full rationale.
- Pre-generation queue. Safe locations are validated asynchronously before a player asks for one, so teleports resolve in 0–2 game ticks (≤ 100 ms) on average.
- Spatial Memory. The plugin maps the entire teleport region and remembers invalid areas, such as oceans, solid blocks, and claims. Use
/rtp scanto proactively map out a region, ensuring deterministic performance and instant skips of unsafe territory. - Multi-region support. A single world can have any number of independent teleport regions, each with its own shape, distribution, permissions, and queue.
- Platform-aware concurrency. Separate adapters for Spigot, Paper, and Folia ensure correct thread-safety on each server type, including Folia's region-based multithreading.
- Extensible API. Addon developers can register custom shapes, vertical adjustors, and claim-check hooks without modifying the plugin.
| Platform | Min Version | Notes |
|---|---|---|
| Spigot | 1.20 | Baseline adapter |
| Paper | 1.20 | Uses async chunk loading APIs |
| Folia | 1.20 | Full regional-thread scheduling support |
| Fabric | 1.21 | Native mod support — targeted for 3.0.0 final, not functional in 3.0.0-beta.1 (roadmap) |
| Forge / NeoForge | — | No native adapter planned. Use a Bukkit-compatibility launcher (e.g. Arclight or Mohist) and run the Spigot/Paper build. |
Runtime: Java 21+
RTP loads chunks asynchronously on demand (S-005 — never sync chunk I/O on the main thread). On a freshly-explored world, the first teleports and the first /rtp scan are bound by the host server's chunk-generation throughput, not by RTP. On suboptimal server software — most notably stock Fabric / vanilla chunk systems on 1.20.1 — generation runs largely on the tick thread and can take several seconds per chunk, which will stall the queue (and even mass-pregeneration tools such as Chunky can stall the server on the same hardware).
Strongly recommended:
- Use a server software with a parallel chunk system for production traffic. Paper and Folia scale well; vanilla Fabric is supported but is single-tick-thread bound for FULL-status generation and will struggle on cold worlds regardless of how RTP is tuned.
- Pregenerate every world you'll add to RTP (e.g. with Chunky or WorldBorder) sized to match each region's configured radius before putting RTP into production traffic. On Fabric specifically, expect pregeneration itself to be slow and to require a maintenance window — not something to do on a live server. See QUICK_START Step 0 for sizing guidance.
If you're on Fabric and the world is not pregenerated, RTP will keep working, but /rtp attempt rates and queue fill rates will be capped by the server's generation throughput, not by RTP's pipeline.
- Shapes: Circle, square, rectangle, each supporting flat, normal, and exponential distributions.
- Distributions: Tune where players land, such as uniform spread, center-weighted, or ring-shaped.
- Biome filters: Exclude specific biomes (e.g., ocean, nether_wastes) per region.
- Claim integration: Works with GriefPrevention, WorldGuard, Towny, and any addon implementing the validation hook.
- Economy support: Optional Vault integration to charge players per teleport.
- Per-region permissions: Fine-grained permission nodes per region and per world.
- Runtime config reload: Adjust region settings by command without restarting the server.
- Persistent state: Spatial memory and region shape data survive server restarts, avoiding cold-start rebuild penalties.
Circle with exponential distribution (σ = 0.1, 1.0, 10.0):
Square with exponential distribution (σ = 0.1, 1.0, 10.0):
Circle with normal distribution:
Square with normal distribution:
Rectangle with flat distribution and rotation:
Custom shapes can be registered at runtime via the rtp-api. See the addons/ directory for examples.
| Directory | Purpose |
|---|---|
rtp-api/ |
Public API and shared models. Compile addons against this module only. |
commands-api/ |
Unified multi-platform command framework. |
effects-api/ |
Unified multi-platform visual/particle effects framework. |
rtp-core/ |
Platform-agnostic core logic: regions, shapes, queues, database, memory tracking. |
rtp-plugin/ |
Plugin entry point for Bukkit platforms. Bridges core with Spigot/Paper/Folia adapters. |
rtp-spigot/ |
Spigot platform adapter. |
rtp-paper/ |
Paper platform adapter (async chunk loading). |
rtp-folia/ |
Folia platform adapter (regional thread scheduling). |
rtp-fabric/ |
Fabric platform adapter and mod entry point (Planned). |
addons/ |
Example addons: Iris integration, Glide. (Claim plugin integrations are folded into the core). |
Python Test Scripts/ |
Visualisation scripts for distribution math and geometry validation. |
Choose your path:
| I am a… | Start here |
|---|---|
| Server administrator installing or operating RTP | docs/FOR_SERVER_ADMINS.md |
Addon developer extending RTP via rtp-api |
docs/FOR_ADDON_DEVELOPERS.md |
Core contributor to rtp-core, rtp-api, or a platform adapter |
docs/FOR_CONTRIBUTORS.md |
See docs/MAP.md for a one-line catalog of every document, or docs/dev/INDEX.md for a task-to-file router. Root-level: CONTRIBUTING.md, CHANGELOG.md, SECURITY.md.
I am a solo engineer, and I use AI coding assistants (LLM-based pair-programming tools) for scaffolding, refactoring, test generation, and documentation drafting. Every line that ships is reviewed, tested, and signed off by me — architecture, safety invariants (thread model, chunk-ticket lifecycle, claim checks), and release decisions are mine alone. No AI output is published without human verification against the requirements in docs/dev/REQUIREMENTS.md and the test suite. If you prefer plugins written without AI tooling in the loop at all, RTP is not that plugin, and I would rather you know up front.
See CONTRIBUTING.md for build instructions, code style rules, and the workflow for adding requirements.
New to the plugin? Start with docs/FOR_SERVER_ADMINS.md. Want to extend it? See docs/FOR_ADDON_DEVELOPERS.md.
The short version:
./gradlew build(compile and run all tests)./gradlew spotlessApply(format code before pushing)- If you add a requirement, add a row to
docs/dev/TRACEABILITY.mdin the same commit, as CI will fail otherwise.