{"id":49558202,"url":"https://github.com/dailystruggle/rtp","last_synced_at":"2026-05-27T07:00:39.897Z","repository":{"id":45238704,"uuid":"390862071","full_name":"DailyStruggle/RTP","owner":"DailyStruggle","description":"fun with spatial math","archived":false,"fork":false,"pushed_at":"2026-05-22T01:05:43.000Z","size":10688,"stargazers_count":28,"open_issues_count":0,"forks_count":10,"subscribers_count":2,"default_branch":"V3-beta","last_synced_at":"2026-05-22T10:46:30.904Z","etag":null,"topics":["bukkit-plugin","java","minecraft","minecraft-plugin","spigot","spigot-plugin"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DailyStruggle.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG-lite.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-07-29T22:09:13.000Z","updated_at":"2026-05-22T01:05:48.000Z","dependencies_parsed_at":"2024-07-14T04:47:37.955Z","dependency_job_id":null,"html_url":"https://github.com/DailyStruggle/RTP","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/DailyStruggle/RTP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DailyStruggle%2FRTP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DailyStruggle%2FRTP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DailyStruggle%2FRTP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DailyStruggle%2FRTP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DailyStruggle","download_url":"https://codeload.github.com/DailyStruggle/RTP/tar.gz/refs/heads/V3-beta","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DailyStruggle%2FRTP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33554780,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bukkit-plugin","java","minecraft","minecraft-plugin","spigot","spigot-plugin"],"created_at":"2026-05-03T06:18:19.838Z","updated_at":"2026-05-27T07:00:39.891Z","avatar_url":"https://github.com/DailyStruggle.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RTP — Random Teleport\n\nThe Folia-native, region-aware random teleport plugin for production Minecraft servers. Pre-generated, pre-validated locations resolve in 0-2 ticks with no main-thread chunk I/O and no region thrashing under load.\n\n**Supported:** Spigot, Paper, Folia 1.20+ (stable). Fabric 1.21+ (in development).\n\n🔗 **[Get RTP Pro on BuiltByBit](https://builtbybit.com/resources/rtp-pro.105418/)** — supports continued development and unlocks the Pro feature set.\n\n[![Build](https://github.com/DailyStruggle/RTP/actions/workflows/gradle.yml/badge.svg)](https://github.com/DailyStruggle/RTP/actions/workflows/gradle.yml)\n[![Release](https://img.shields.io/github/v/release/DailyStruggle/RTP)](https://github.com/DailyStruggle/RTP/releases)\n[![Java](https://img.shields.io/badge/Java-21-blue)](https://adoptium.net/)\n[![SpigotMC](https://img.shields.io/badge/SpigotMC-RTP-orange)](https://www.spigotmc.org/resources/rtp.94812/)\n[![BuiltByBit](https://img.shields.io/badge/BuiltByBit-RTP%20Pro-blue)](https://builtbybit.com/resources/rtp-pro.105418/)\n\n🔗 [SpigotMC Resource Page](https://www.spigotmc.org/resources/rtp.94812/)\n🔗 [BuiltByBit Resource Page](https://builtbybit.com/resources/rtp-pro.105418/)\n\n---\n\n## Why RTP?\n\nLegacy random-teleport plugins reroll random coordinates until one lands somewhere safe. Under load on Folia, each candidate triggers cross-region API calls (chunk lookups, block checks, biome queries), thrashing region threads and stretching teleports to seconds. RTP is designed the opposite way: every served location is pre-computed, pre-validated, and ready to hand out in 0-2 ticks.\n\n- **Built for Folia, not retrofitted.** Region-aware scheduling end-to-end. No synchronous chunk I/O on the main thread, no foreign-region API calls in the hot path, no `ThreadAccessException` fallbacks dragging down teleport latency. Spigot and Paper adapters share the same bounded pipeline with platform-correct concurrency.\n- **Pre-generation queue.** Safe locations are validated asynchronously *before* a player asks for one. Teleports resolve in 0-2 game ticks (≤ 100 ms) on average regardless of region size, biome complexity, or player count.\n- **Bounded algorithms, not rerolling.** Location selection runs in deterministic time via a 2D-to-1D Archimedean-spiral mapping that preemptively subtracts known-invalid sectors from the candidate space. See the [mathematical writeup](https://www.reddit.com/r/admincraft/comments/owgvzz/too_much_math/) and [ADR-001](docs/adr/ADR-001-archimedean-spiral-1d-mapping.md).\n- **Spatial memory.** The plugin maps every region it serves and remembers what's invalid (oceans, solid blocks, claims, biome exclusions). `/rtp scan` proactively maps a region for deterministic performance and instant skips of unsafe territory. Memory survives server restarts.\n- **Custom polygons.** Define teleport regions with any closed concave or convex polygon, not just circles and squares. Polygon shapes use the same spatial-memory and pre-validation pipeline as the built-in shapes.\n- **Void-world and SkyBlock support.** The `vert:fixed` adjustor places players at a configured Y for void worlds, SkyBlock servers, and any region where the platform creates the foothold rather than the terrain.\n- **Multi-region per world.** A single world can host any number of independent teleport regions, each with its own shape, distribution, permissions, queue, and economy cost.\n- **Production diagnostics.** `MemoryTracker` accounts for chunk tickets and pipeline allocations on every exit path; spark-compatible profiling surface; per-region MSPT and queue telemetry for tuning under live load.\n- **Extensible API.** Addon developers register custom shapes, vertical adjustors, and claim-check hooks without modifying the plugin.\n\n---\n\n## Supported Platforms\n\n| Platform | Min Version | Notes |\n|---|---|---|\n| Spigot | 1.20 | Baseline adapter |\n| Paper | 1.20 | Uses async chunk loading APIs |\n| Folia | 1.20 | Full regional-thread scheduling support |\n| Fabric | 1.21 | Native mod support — **targeted for `3.0.0` final**, not functional in `3.0.0-beta.1` ([roadmap](docs/dev/MULTI_PLATFORM_PLAN.md)) |\n| Forge / NeoForge | — | No native adapter planned. Use a Bukkit-compatibility launcher (e.g. **Arclight** or **Mohist**) and run the Spigot/Paper build. |\n\n**Runtime:** Java 21+\n\n---\n\n## Pregenerate First\n\nFor best results, pregenerate each RTP world (Chunky / WorldBorder) sized to your region radius before going live. RTP's pipeline is bounded by your server's chunk-generation throughput on first touch; pregeneration removes that bottleneck. See [QUICK_START Step 0](docs/admin/QUICK_START.md#step-0--prerequisites--pregenerate-the-world).\n\n---\n\n## Features\n\n- **Shapes:** Circle, square, rectangle, and admin-authored **custom polygons** (convex or concave), each supporting flat, normal, and exponential distributions.\n- **Distributions:** Tune where players land, such as uniform spread, center-weighted, or ring-shaped.\n- **Biome filters:** Exclude specific biomes (e.g., ocean, nether_wastes) per region.\n- **Void-world / SkyBlock support:** `vert:fixed` adjustor places players at a configured Y for void worlds, SkyBlock servers, and any region where the platform creates the foothold instead of the terrain.\n- **Claim integration:** Works with GriefPrevention, WorldGuard, Towny, and any addon implementing the validation hook.\n- **Economy support:** Optional Vault integration to charge players per teleport.\n- **Per-region permissions:** Fine-grained permission nodes per region and per world.\n- **Runtime config reload:** Adjust region settings by command without restarting the server.\n- **Persistent state:** Spatial memory and region shape data survive server restarts, avoiding cold-start rebuild penalties.\n- **Built-in diagnostics:** `MemoryTracker` accounts for chunk tickets and pipeline allocations on every exit path; spark-compatible profiling surface for production tuning.\n\n---\n\n## Shapes\n\nCircle with exponential distribution (σ = 0.1, 1.0, 10.0):\n![circle-exponential](https://user-images.githubusercontent.com/28832622/210043913-fd624a9f-8bdd-45de-b877-6a5f5e3bf40a.png)\n\nSquare with exponential distribution (σ = 0.1, 1.0, 10.0):\n![square-exponential](https://user-images.githubusercontent.com/28832622/210043922-4d94e3d6-e829-4adc-a21a-74cce484f8e6.png)\n\nCircle with normal distribution:\n![circle-normal](https://user-images.githubusercontent.com/28832622/210043926-5c5013cf-032e-444c-9397-e381c17a4752.png)\n\nSquare with normal distribution:\n![square-normal](https://user-images.githubusercontent.com/28832622/210043956-df964dde-4c70-460b-a377-ffd49a365e69.png)\n\nRectangle with flat distribution and rotation:\n![rectangle-flat](https://user-images.githubusercontent.com/28832622/210043964-ca9725b8-be25-4e3c-a460-90f8b81326cb.png)\n\nCustom shapes can be registered at runtime via the `rtp-api`. See the `addons/` directory for examples.\n\n---\n\n## Repository Structure\n\n| Directory | Purpose |\n|---|---|\n| `rtp-api/` | Public API and shared models. Compile addons against this module only. |\n| `commands-api/` | Unified multi-platform command framework. |\n| `effects-api/` | Unified multi-platform visual/particle effects framework. |\n| `rtp-core/` | Platform-agnostic core logic: regions, shapes, queues, database, memory tracking. |\n| `rtp-plugin/` | Plugin entry point for Bukkit platforms. Bridges core with Spigot/Paper/Folia adapters. |\n| `rtp-bukkit/` | Spigot platform adapter. |\n| `rtp-paper/` | Paper platform adapter (async chunk loading). |\n| `rtp-folia/` | Folia platform adapter (regional thread scheduling). |\n| `rtp-fabric/` | Fabric platform adapter and mod entry point (Planned). |\n| `addons/` | Example addons: Iris integration, Glide. (Claim plugin integrations are folded into the core). |\n| `Python Test Scripts/` | Visualisation scripts for distribution math and geometry validation. |\n\n---\n\n## Documentation\n\n**Choose your path:**\n\n| I am a… | Start here |\n|---|---|\n| Server administrator installing or operating RTP | [docs/FOR_SERVER_ADMINS.md](docs/FOR_SERVER_ADMINS.md) |\n| Addon developer extending RTP via `rtp-api` | [docs/FOR_ADDON_DEVELOPERS.md](docs/FOR_ADDON_DEVELOPERS.md) |\n| Core contributor to `rtp-core`, `rtp-api`, or a platform adapter | [docs/FOR_CONTRIBUTORS.md](docs/FOR_CONTRIBUTORS.md) |\n\n### Full Reference Index\n\nSee [docs/MAP.md](docs/MAP.md) for a one-line catalog of every document, or [docs/dev/INDEX.md](docs/dev/INDEX.md) for a task-to-file router. Root-level: [CONTRIBUTING.md](CONTRIBUTING.md), [CHANGELOG.md](CHANGELOG.md), [SECURITY.md](SECURITY.md).\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions, code style rules, and the workflow for adding requirements.\n\nNew to the plugin? Start with [docs/FOR_SERVER_ADMINS.md](docs/FOR_SERVER_ADMINS.md). Want to extend it? See [docs/FOR_ADDON_DEVELOPERS.md](docs/FOR_ADDON_DEVELOPERS.md).\n\nThe short version:\n1. `./gradlew build` (compile and run all tests)\n2. `./gradlew spotlessApply` (format code before pushing)\n3. If you add a requirement, add a row to `docs/dev/TRACEABILITY.md` in the same commit, as CI will fail otherwise.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdailystruggle%2Frtp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdailystruggle%2Frtp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdailystruggle%2Frtp/lists"}