Skip to content

RTP Paper Adapter Requirements

This document outlines the requirements for the rtp-paper module. This adapter leverages the enhanced APIs available exclusively on Paper servers to maximize performance.

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

1. Functional Requirements

1.1 Asynchronous Chunk Operations

  • REQ-PAPER-F-001 — Non-Blocking Generation: Chunk loading and location validation shall be non-blocking with respect to the main server thread.
  • REQ-PAPER-F-002 — Deadlock Prevention: Asynchronous requests shall be handled strictly via callbacks or futures, with no synchronous waits that could deadlock the main server thread.

1.2 Performance Optimization

  • REQ-PAPER-F-003 — Platform API Utilization: The adapter shall prioritize Paper-specific capabilities over Bukkit fallbacks to ensure the highest possible teleportation throughput with minimal TPS impact.

2. Strict Architectural Requirements

2.1 Ephemeral Memory Retention (Plugin Chunk Tickets)

  • REQ-PAPER-ARCH-001 — Scoped Chunk Retention: The adapter shall use plugin-owned chunk tickets rather than permanent force-loading mechanisms.
  • REQ-PAPER-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-PAPER-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-PAPER-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-PAPER-ARCH-005 — Lifecycle Pairing: Every chunk reservation shall be explicitly released when no longer needed.
  • REQ-PAPER-ARCH-006 — Forced Reclamation: If a teleportation request is dropped, cancelled, or the associated player disconnects, all associated chunk reservations shall be immediately released.