Skip to content

RTP Spigot Adapter Requirements

This document outlines the requirements for the rtp-bukkit module. This adapter serves standard Bukkit/Spigot server implementations where advanced asynchronous features or region-based multithreading are unavailable.

For design and implementation details that satisfy these requirements, see docs/dev/DESIGN.md.

1. Functional Requirements

1.1 Synchronous Fallback

  • REQ-SPIGOT-F-001 — Chunk Loading: The adapter shall support standard chunk loading on Bukkit/Spigot servers where async chunk APIs are unavailable.
  • REQ-SPIGOT-F-002 — Bounded Execution: Synchronous tasks shall be strictly rate-limited and bounded to prevent freezing the main server thread during location generation or validation.

1.2 Event Handling

  • REQ-SPIGOT-F-003 — Platform Events: The module shall capture Bukkit-specific events (e.g., player movement, world loading/unloading) and route them to rtp-core handlers without leaking platform-specific classes into the core module.

2. Strict Architectural Requirements

2.1 Ephemeral Memory Retention (Plugin Chunk Tickets)

  • REQ-SPIGOT-ARCH-001 — Scoped Chunk Retention: The adapter shall use plugin-owned chunk tickets rather than permanent force-loading mechanisms.
  • REQ-SPIGOT-ARCH-002 — Leak Prevention: Chunk memory shall be reclaimed by the server when the plugin is disabled or the server restarts, rather than being permanently held by the world's internal force-loaded map.

2.2 Time-Bounded Execution (Main-Thread Stewardship)

  • REQ-SPIGOT-ARCH-003 — Time-Slicing Enforcement: All background operations executed on the main server thread shall be time-sliced to yield execution before causing TPS degradation.
  • REQ-SPIGOT-ARCH-004 — Latency Protection: Task pipelines shall be bounded by wall-clock time rather than task counts, ensuring that even under high load the plugin yields to the server tick.

2.3 Ticket Lifecycle Cleansing (Automatic Release)

  • REQ-SPIGOT-ARCH-005 — Lifecycle Pairing: Every chunk reservation shall be explicitly released when no longer needed.
  • REQ-SPIGOT-ARCH-006 — Forced Reclamation: If a teleportation request is dropped, cancelled, or the associated player disconnects, all associated chunk reservations shall be immediately released.