Project Architecture¶
For a high-level overview of the plugin's reliability guarantees and bounded execution architecture, see System Architecture and High-Reliability Design. For the full requirements-to-code traceability matrix (Req ID → design decision → implementing class → test), see TRACEABILITY.md. For actor definitions and stakeholder goals, see STAKEHOLDERS.md. For term definitions, see GLOSSARY.md. For the rationale behind key architectural decisions (why, not just what), see Architecture Decision Records.
The RTP (Random Teleport) plugin is built with a multi-module architecture to ensure scalability, ease of maintenance, and compatibility across server and proxy environments: Spigot, Paper, Folia, Fabric (rtp-fabric-ADR-002), NeoForge (rtp-neoforge-ADR-002), and Velocity / BungeeCord proxies (leafrtp-ADR-022), with a Java 17 bytecode baseline for shared modules and MC 26.x+ deobfuscated runtime support (ADR-113).
Module Breakdown¶
Core & API Modules¶
Building a standalone plugin or mod? All 14
api/*libraries below are published to Maven Central and JitPack with zerortp-coredependencies. See../FOR_PLUGIN_AUTHORS.mdfor the 5-file multi-platform plugin blueprint and../../api/README.mdfor the standalone SDK catalog.
- rtp-api: Contains the public interfaces, APIs, and shared models used by the plugin and external integrations (leafrtp-ADR-008, leafrtp-ADR-034). Addon developers compile against this module.
- rtp-core: Contains the platform-neutral core logic of the plugin: region management, random location selection algorithms (shapes), 3-tier queue management (
Hot/Cold/Backlog), stochastic cost modeling (predict), database interactions, and memory tracking (MemoryTracker). Internal packages are structured in a 4-tier Directed Acyclic Graph (DAG) to eliminate SonarQube package tangles and isolate domain algorithms from execution pipelines (ADR-115; see Package Architecture). - anvil-api (
api/anvil-api): Standalone, platform-neutral off-tick region decoder and prefilter framework (anvil-api-ADR-001, anvil-api-ADR-002). Defines theRegionFileReaderSPI and ships the built-in Anvil reader (.mca/ Zlib / LZ4), decoded off the main thread. Addons may register other formats throughRegionFormatRegistryor aRegionFileReaderProviderservice; files in an unregistered format (e.g..linear) are ignored and their chunks fall back to the platform's live async chunk load. - bit-api (
api/bit-api): Standalone, plugin-agnostic Built-In Test (PBIT/CBIT/IBIT) contract, findings model, code registry, and CLI runner (leafrtp-ADR-091). - bstats-api (
api/bstats-api): Dependency-free bStats v2 metrics client SPI (bstats-api-ADR-001). - bytecode-api (
api/bytecode-api,:bytecode-api,io.github.dailystruggle.bytecode): Zero-classloading JVM.classconstant-pool, config-key, and causal-graph bytecode scanner (BytecodeConfigScanner,BytecodeCausalGraphScanner,JarConfigScanner,SchemaInferrer,ServerConfigAtlas) layered onyaml-api,server-api, andconfig-bit-api. - commands-api (
api/commands-api): Unified platform-neutral command-tree framework and Brigadier bridge (commands-api-ADR-001). - config-bit-api (
api/config-bit-api): Declarative YAML comment-directive (@type,@options,@range,@pattern), cross-file reference, distance-constraint, and locale-key parity PBIT validation library layered onyaml-api,bit-api, andunits-api(ADR-064, leafrtp-ADR-091). - effects-api (
api/effects-api): Unified cross-platform visual, sound, potion, and hologram effects framework (effects-api-ADR-003, including theeffects-api-fabric-unobfcarrier per effects-api-ADR-006). - maps-api (
api/maps-api): Platform-neutral runtime cartography, heatmap, and Mermaid chart rendering SPI (maps-api-ADR-003). - menu-api (
api/menu-api): Cross-platform declarative menu descriptor, session, token redemption, and anvil/text prompt SPI layered onserver-apiandcommands-api(ADR-035, ADR-044, leafrtp-ADR-031). - metrics-api (
api/metrics-api): Platform-portable runtime telemetry SPI (Metrics,MetricsBinding,MetricsSnapshot,FoliaRegionSample; metrics-api-ADR-001). - predict-api (
api/predict-api): Zero-dependency stochastic estimation (EwmaEstimator,BernoulliEstimator,EwmaLinearFit) and adaptive control (ComparativeCostGovernor,BudgetPacer,AimdLimiter) library (ADR-109, ADR-114, ADR-115). - server-api (
api/server-api): Platform-neutral server identity,PlatformFamilycapability gating, logging, and regional/async task scheduling SPI (ServerAccessor,ServerAccessors,TaskScheduler,TaskHandle; effects-api-ADR-008). - tags-api (
api/tags-api): Zero-dependency Minecraft block and biome tag JSON resolver (tags-api-ADR-001). - units-api (
api/units-api): Dependency-free temporal, spatial (DistanceParser), and data-size unit parsers re-exported byrtp-api(ADR-113). - yaml-api (
api/yaml-api): In-house zero-dependency YAML parser, writer, and comment-preserving configuration substrate (yaml-api-ADR-001, yaml-api-ADR-002).
Platform Adapters¶
These modules (located under platforms/) implement platform-specific features to maximize performance on their respective servers and proxies while maintaining a unified core codebase (ADR-010, ADR-103). For detailed requirements, function specifications, and lifecycle contracts when creating a new server adapter, see SERVER_ADAPTER_GUIDE.md.
* rtp-bukkit (platforms/bukkit): Adapter for standard Spigot servers, implementing Bukkit/Spigot event handling, plugin chunk tickets, and Anvil prefilter integration.
* rtp-paper (platforms/paper): Adapter for Paper servers, utilizing Paper's native asynchronous chunk loading APIs.
* rtp-folia (platforms/folia): Adapter for Folia servers, handling region-based multithreading, per-region slice budgeting (rtp-folia-ADR-002), and count-bound execution (rtp-folia-ADR-001).
* rtp-fabric (platforms/fabric): Adapter for Fabric servers across obfuscated (1.20.x, 1.21.x) and unobfuscated (26.x) carriers, bridging rtp-core to the Fabric modding runtime and Brigadier (rtp-fabric-ADR-002).
* rtp-neoforge (platforms/neoforge): Adapter for NeoForge servers (1.21.x and 26.x), compiling against Mojang-mapped runtime names and bridging rtp-core to NeoForge lifecycle events and Brigadier (rtp-neoforge-ADR-002, rtp-neoforge-ADR-001).
* rtp-proxy (platforms/proxy): Multi-server proxy coordination layer (rtp-proxy-common, rtp-proxy-velocity), providing cross-backend load balancing (BackendSelector), reservation token state machines, and Redis/SQL/in-memory network state bindings (leafrtp-ADR-022).
Plugin Entry Points & Unified Packaging¶
- rtp-plugin: The unified distribution assembly module and Bukkit-family entry point (leafrtp-ADR-003). It shades and merges
rtp-core, theapi/*SPI modules, the Bukkit/Paper/Folia adapters, the Fabric/NeoForge carriers, the Velocity proxy adapter, and the bundled addons into a single multi-loader jar. - rtp-fabric: Supplies the
ModInitializerentry point (RTPFabricMod) for the Fabric modding environment. - rtp-neoforge: Supplies the
@Modentry point (RTPNeoForgeMod) for the NeoForge modding environment. - rtp-proxy-velocity: Supplies the
@Plugin(id = "rtp")entry point (RtpVelocityPlugin) for the Velocity proxy runtime.
Addons¶
- addons: Subprojects that extend RTP via
rtp-apiand the platform-agnosticRTPAddonServiceLoader SPI (leafrtp-ADR-010, leafrtp-ADR-040). Bundled addons are packaged inside the distribution jar underbundled-addons/and self-extract into<pluginDir>/addons/on first run: - LeafRTPClaimAddon: Bundles third-party land-claim and protection checkers behind
addons/integrations.ymltoggles (leafrtp-ADR-051, superseding leafrtp-ADR-012; leafrtp-ADR-088). - LeafRTPGuiAddon: Multi-loader (
rtp-gui-common,rtp-gui-bukkit,rtp-gui-fabric,rtp-gui-neoforge,rtp-gui) destination picker GUI bound to bare/rtp(leafrtp-ADR-039). - LeafRTPActionAddon: Declarative scripted actions, subspace anchor placement, and region confinement (leafrtp-ADR-073, leafrtp-ADR-074, leafrtp-ADR-075, leafrtp-ADR-076).
- LeafRTPCountdownAddon: Canonical reference template demonstrating
rtp-apiaddon structure. - LeafRTPRiftAddon: Reference
effects-apiprototype registering the client-sideRIFTwarmup dissolve effect. - Note: The standalone
RTP_Glideaddon was folded intoeffects-apias theGLIDEeffect (effects-api-ADR-001); the experimentalRTP_Iris_integrationaddon was retired because no dedicated integration is required to teleport into Iris-generated worlds.
Module Dependency Graph¶
graph TD
subgraph SPI ["api/* (Platform-Neutral SPIs)"]
server-api
units-api
yaml-api
commands-api
bit-api
config-bit-api
bytecode-api
menu-api
predict-api
effects-api
maps-api
metrics-api
bstats-api
anvil-api
tags-api
end
server-api --> rtp-api
menu-api --> rtp-api
units-api --> rtp-api
yaml-api --> rtp-api
commands-api --> rtp-api
bit-api --> rtp-api
config-bit-api --> rtp-core
predict-api --> rtp-core
rtp-api --> rtp-core
SPI --> rtp-core
rtp-core --> rtp-bukkit
rtp-core --> rtp-paper
rtp-core --> rtp-folia
rtp-core --> rtp-fabric
rtp-core --> rtp-neoforge
rtp-api --> rtp-proxy
metrics-api --> rtp-proxy
rtp-core --> rtp-plugin
rtp-bukkit --> rtp-plugin
rtp-paper --> rtp-plugin
rtp-folia --> rtp-plugin
rtp-fabric --> rtp-plugin
rtp-neoforge --> rtp-plugin
rtp-proxy --> rtp-plugin
rtp-api --> addons
Dependency rule:
rtp-coreandrtp-apishall not import platform-specific classes (Bukkit, Spigot, Paper, Folia, Fabric, NeoForge, Velocity). This boundary is enforced mechanically by ArchUnit tests (RTPArchitectureTest).
Package Architecture (rtp-core)¶
All 78 packages within rtp-core are organized into a strict 4-tier Directed Acyclic Graph (DAG) to eliminate SonarQube package tangles and guarantee modular separation (ADR-115):
- Tier 1 (Foundation & Schemas): Immutable config records (configuration.schema), domain enums (configuration.enums), math tables, and SPI contracts (tools.contracts). Zero outgoing core dependencies.
- Tier 2 (Domain Engines & Storage): Spatial math and memory curves (selection.region.selectors.*), resource tracking (tools.MemoryTracker), and database accessors (database.*). Depends strictly on Tier 1.
- Tier 3 (Execution Pipelines): Teleport pipelines (tasks.teleport), background pregen (PregenTask), and action coordination (action.*). Depends on Tier 2 and Tier 1.
- Tier 4 (Orchestration & Ingress): Leaf command trees (commands.*), interactive book menus, web editor channels, and the composition root (RTP.java).
For the package DAG diagram, seam decoupling patterns, and decision traceability specifications, see ../architecture/16-package-dag-and-decision-preservation-graph.md.
Key Concepts¶
- Regions: The world is divided into manageable teleport regions. Each region handles its own teleport queue and shape parameters.
- Shapes: Mathematical structures (circle, square, rectangle) governing how random points are generated. They support various distributions (normal, flat, exponential) for tailored teleport selection algorithms.
- Queue System: Pre-generating and validating random locations before they are needed ensures teleports are instant for the end-user.