Skip to content

RTP Architecture Catalog & Diagram Directory

This directory contains the canonical visual architecture specifications, state-machine diagrams, and lifecycle flows for the LeafRTP engine. Each document models an end-to-end subsystem or critical invariant using client-rendered Mermaid diagrams accompanied by threading rules, failure attribution vocabulary, and requirement traceability.

For a narrative walkthrough of how these diagrams connect to diagnose runtime issues, see docs/dev/CODE_TOUR.md. For module import boundaries and package separation, see docs/dev/ARCHITECTURE.md.


Architectural Diagram Catalog

# Document Primary Scope Entry Point / Core Classes Governing ADRs S-00x Rules
01 01-teleport-execution-pipeline.md End-to-end single /rtp execution (Setup → Load → Teleport → Cleanup) TeleportPipelineTask, LocationGenerator leafrtp-ADR-001, leafrtp-ADR-011, leafrtp-ADR-085, rtp-folia-ADR-002, leafrtp-ADR-086 S-001, S-002, S-004, S-005
02 02-budgeted-cache-generator.md Background speculative queue refill (keptLocations) and budget pacing SelectionAPI.compute(), RegionQueueManager, RegionCacheTask leafrtp-ADR-004, leafrtp-ADR-011, anvil-api-ADR-001, leafrtp-ADR-059, leafrtp-ADR-068, leafrtp-ADR-085 S-002, S-005
03 03-chunk-ticket-lifecycle.md Chunk reservation lifecycle, ticket registration, and guaranteed teardown ChunkReservation, ChunkSet, MemoryTracker leafrtp-ADR-011, rtp-folia-ADR-002 S-002, S-005
04 04-active-gc-sweep.md Periodic background audit and reclamation of stale tasks and orphaned tickets ActiveGCSweepTask, MemoryTracker leafrtp-ADR-011 S-002
05 05-scan-task-crawler.md Long-lived admin /rtp scan crawler, rate throttling, and .scan checkpoints ScanTask, ScanTaskProcessing, MemoryShape leafrtp-ADR-001, anvil-api-ADR-001 S-004, S-005
06 06-plugin-setup-lifecycle.md Plugin bootstrap ordering, database initialization, and adapter detection RTPBukkitPlugin.onEnable(), Configs.reload() leafrtp-ADR-003, leafrtp-ADR-013, leafrtp-ADR-016 S-006
07 07-rtp-command-region-selection.md Command parsing, world/region overrides, permission evaluation, and unqueued branch SelectionAPI.getRegion(), BukkitBaseRTPCmd leafrtp-ADR-001, leafrtp-ADR-007, leafrtp-ADR-085, leafrtp-ADR-086 S-004, S-007
08 08-location-selection-per-attempt.md Core candidate selection attempt: shape → probe-first → chunk → vert → biome → safety PregenTask.runAttempt(), LocationGenerator leafrtp-ADR-001, leafrtp-ADR-011, anvil-api-ADR-001, leafrtp-ADR-084, leafrtp-ADR-085, rtp-folia-ADR-002, leafrtp-ADR-086 S-001, S-003, S-004, S-005
09 09-configuration-load-and-reload.md Configuration loading, locale bootstrap, atomic parser swap, and dormant regions Configs.reloadAction(), ConfigParser, LanguageBootstrap leafrtp-ADR-013, leafrtp-ADR-027 S-007
10 10-shutdown-and-flush-lifecycle.md Shutdown flush ordering: task drainage → DB commit → region teardown → ticket release RTP.stop(), RTPBukkitPlugin.onDisable(), DatabaseAccessor leafrtp-ADR-006, leafrtp-ADR-011, leafrtp-ADR-016 S-002, S-004
11 11-configuration-write-and-persist.md /rtp config set/add/remove persistence pipeline, atomic rename, and rollback ConfigWritePipeline, ConfigYamlDumper leafrtp-ADR-023, leafrtp-ADR-027 S-007
12 12-network-model.md Multi-server and multi-proxy network protocol, packet sequence, and reservation tokens RTPNetworkManager, ServerTokenManager, ProxyProtocolBridge leafrtp-ADR-022 S-002, S-004
13 13-dual-layer-shape-architecture-and-l3-selection.md Dual-layer shape coordinate mapping, Chebyshev tiles, Hilbert curve, and L3 backlog CircleOptimizedDualLayer, SquareOptimizedDualLayer, SegmentedKeyRunTable leafrtp-ADR-001, leafrtp-ADR-018, leafrtp-ADR-020, leafrtp-ADR-066, leafrtp-ADR-069 S-001, S-004
14 14-group-placement-anchor-flow.md Multi-participant action placement, group anchor draw, and separated slot allocation GroupPlacementDispatcher, SubspaceAnchorResolver, ActionManager leafrtp-ADR-073, leafrtp-ADR-074, leafrtp-ADR-075 S-002, S-004
15 15-cost-governed-chunk-reads-and-native-admission.md Purpose-gated chunk resolution, thread-weighted deduplication, and in-flight admission ImmediateLoadGovernor, LiveLoadGate, ProbeFirstGovernor, AnvilRegionOccupancyCache anvil-api-ADR-001, leafrtp-ADR-049, leafrtp-ADR-084, leafrtp-ADR-085, rtp-folia-ADR-002, leafrtp-ADR-086 S-001, S-002, S-004, S-005
16 16-package-dag-and-decision-preservation-graph.md Core package hierarchy, 4-tier DAG architecture, and decision traceability hypergraph RTPArchitectureTest, RTP, MemoryTracker, CoreCommandTreeBuilder ADR-000, leafrtp-ADR-006, ADR-094, ADR-115 S-001..S-007

Subsystem Functional Map

The diagrams form an interconnected state machine covering distinct architectural concerns:

1. Teleport Orchestration & Command Dispatch

  • 07 /rtp Command Region Selection: Evaluates player arguments, world/region permissions, override loops, and forks between hot-cache pop, public queue wait, or ad-hoc unqueued search (LoadPurpose.IMMEDIATE).
  • 01 Teleport Execution Pipeline: Orchestrates the complete player lifecycle (Setup → Load → Teleport → Cleanup), binding chunk reservations and managing regional handoffs.
  • 14 Group Placement Flow: Manages multi-player challenge, scatter, and arena placement by drawing a single anchor and distributing safe separated slots.

2. Candidate Selection & Algorithmic Geometry

  • 08 Location Selection Per Attempt: The decision core. Samples coordinates, evaluates world borders, passes probe-first gating, resolves chunks, adjusts elevation, filters biomes, and verifies environmental safety.
  • 13 Dual-Layer Shape Architecture & L3 Backlog: Eliminates random rerolls using coarse Chebyshev macro-tiles, fine Hilbert space-filling curves, dyadic downsampling, and segmented run tables.

3. Chunk Resolution, Deduplication & Lifecycle Governance

  • 15 Cost-Governed Chunk Reads & Native Admission: Implements three-tier resolution (Resident Cache, Governed Deduplication, Cost-Governed Native Load Admission), zero-decode MCA occupancy checks, and thread-weighted cost balancing ($P_{\text{reject}} > \frac{C_{\text{file, async}}}{C_{\text{native, async}} + W_{\text{tick}}(\text{MSPT}) \cdot C_{\text{native, sync}}}$).
  • 02 Budgeted Cache Generator: Manages periodic background queue refill pulses (LoadPurpose.SPECULATIVE), constrained by LiveLoadGate and HeapPressureMonitor.
  • 03 Chunk Ticket Lifecycle: Tracks allocation and guaranteed release of platform chunk tickets (ChunkReservation) through MemoryTracker.
  • 04 Active GC Sweep: Provides the active safety net that catches and reclaims stalled tasks, expired tickets, and orphaned native tickets.

4. Configuration, Persistence & Lifecycle Ordering

  • 06 Plugin Setup Lifecycle: Governs onEnable sequencing, database connection pools, config initialization, and platform adapter binding.
  • 09 Configuration Load and Reload: Manages /rtp reload mechanics, language bootstrapping, atomic parser swaps, and dormant region rebinding.
  • 10 Shutdown and Flush Lifecycle: Enforces strict four-phase shutdown ordering to prevent data loss or leaked chunk tickets on /stop and /reload.
  • 11 Configuration Write and Persist: Manages transactional /rtp config mutations with atomic temporary file swapping and rollback.

5. Multi-Server Networking & Admin Tools

  • 12 Network Model: Specifies multi-server proxy communication, heartbeat synchronization, reservation token lifecycle, and packet flows.
  • 05 Scan Task Crawler: Drives asynchronous background pre-exploration (/rtp scan) to populate persistent spatial memory with bounded tick budgets.

6. Package Architecture, Modularity & Decision Traceability

  • 16 Core Package Architecture & Decision Traceability Map: Visual specification of the 4-tier package DAG in rtp-core, acyclic dependency rules (0.0% SonarQube package tangles), decoupled structural seams, and class-to-ADR decision traceability.

Absolute Prohibition Requirements (S-00x) Reference

Every architectural flow is designed to enforce the non-negotiable prohibition requirements codified in docs/dev/REQUIREMENTS.md section 3:

  • S-001 (Destination Safety): Verified authoritatively in 08 and 15 prior to player teleportation. No secondary checks in adapters.
  • S-002 (Chunk Tickets): Framed in 03 and audited in 04 and 10. Zero permanent force-loaded chunks; reservations closed on every exit path.
  • S-003 (Claim Protection): Executed via asynchronous verifier chains in 08. Zero teleports into protected land.
  • S-004 (Failure Visibility): Enforced across 01, 07, 08, and 15. Futures always complete; errors attribute to FailTypes vocabulary without silent suppression.
  • S-005 (Async I/O): Zero synchronous chunk I/O on tick threads. Off-thread region reads (AnvilIoPool), async chunk futures, and regional handoffs are modeled in 01, 08, and 15.
  • S-006 (Fail-Closed Contract): Initialized in 06. Public APIs throw IllegalStateException if invoked pre-initialization.
  • S-007 (Configurable Messages): Handled in 07, 09, and 11. All failure and busy notifications originate from messages.yml.