Skip to content

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 zero rtp-core dependencies. See ../FOR_PLUGIN_AUTHORS.md for the 5-file multi-platform plugin blueprint and ../../api/README.md for the standalone SDK catalog.

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, the api/* 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 ModInitializer entry point (RTPFabricMod) for the Fabric modding environment.
  • rtp-neoforge: Supplies the @Mod entry 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-api and the platform-agnostic RTPAddon ServiceLoader SPI (leafrtp-ADR-010, leafrtp-ADR-040). Bundled addons are packaged inside the distribution jar under bundled-addons/ and self-extract into <pluginDir>/addons/ on first run:
  • LeafRTPClaimAddon: Bundles third-party land-claim and protection checkers behind addons/integrations.yml toggles (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-api addon structure.
  • LeafRTPRiftAddon: Reference effects-api prototype registering the client-side RIFT warmup dissolve effect.
  • Note: The standalone RTP_Glide addon was folded into effects-api as the GLIDE effect (effects-api-ADR-001); the experimental RTP_Iris_integration addon 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-core and rtp-api shall 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.