Architecture Decision Records¶
This directory contains Architecture Decision Records (ADRs) for the RTP project.
An ADR captures a significant architectural decision: the context that forced it, the decision made, the alternatives considered, and the consequences. They are numbered sequentially and never deleted — superseded records are marked as such.
Index¶
| # | Title | Status |
|---|---|---|
| ADR-000 | Development Workflow (meta: how a developer ought to work in this repo and why - full lifecycle from intake through self-maintenance, D-005 guard rail, divergence handling, optional AI tooling) | Accepted |
| ADR-001 | Archimedean Spiral 1D Mapping for Location Selection | Accepted |
| ADR-002 | H2/SQLite for Spatial Memory Persistence Over Flat-File Cache | Accepted |
| ADR-003 | rtp-plugin as a Separate Bridge Module from rtp-core | Accepted |
| ADR-004 | CountBoundTaskPipe Instead of TimeBoundTaskPipe on Folia Regional Threads | Accepted |
| ADR-005 | Removal of PaperLib in Favour of Native Paper APIs | Accepted |
| ADR-006 | Async Queue Pre-Generation Over On-Demand Async Selection | Accepted |
| ADR-007 | Per-User Isolated Queues Alongside the Global Queue | Accepted (operational details superseded by ADR-043) |
| ADR-008 | MemoryTracker as Active Task GC with WeakReference Deallocation | Accepted |
| ADR-009 | Configurable Spatial Distributions: Flat, Normal, Exponential | Accepted |
| ADR-010 | Versioned Platform Adapter Submodules | Accepted |
| ADR-011 | rtp-api as a Separately Published Addon Interface |
Accepted |
| ADR-012 | ChunkReservation as an Internal Chunk Ticket Abstraction |
Accepted |
| ADR-013 | Addons as External Gradle Projects Rather Than Built-In Optional Modules | Accepted (partially superseded by ADR-019) |
| ADR-015 | Stale-Chunk Guard for Count-Bound Pipes | Accepted |
| ADR-016 | Anvil Read-Only Subsystem (Prefilter, Backed Chunk View, Shared Module) | Accepted |
| ADR-017 | Block Tags and Block-State Predicates in Safety Lists | Accepted |
| ADR-018 | AGENTS.md Public Release Structure: Thin Router + Canonical Sources |
Accepted |
| ADR-019 | Claim-Plugin Integrations Folded Into rtp-plugin; Example Addon Retained |
Superseded by ADR-069 |
| ADR-020 | Language Bootstrap and Locale-Aware ConfigParser | Accepted |
| ADR-021 | Legacy Minecraft and Java Support Are Out of Scope | Accepted |
| ADR-022 | Region Shape Cache Key: Seed + Canonical Config Hash | Accepted |
| ADR-023 | Login Reserve Cache for Join-Time RTP | Accepted |
| ADR-024 | RTP Lite Assembly Variant | Superseded by ADR-100 |
| ADR-025 | Replace SimpleYaml with an Internal SnakeYAML-Backed YAML Wrapper | Proposed |
| ADR-026 | External Hook API Surface | Accepted |
| ADR-028 | L3 Backlog Cache (backlogLocations) |
Accepted |
| ADR-032 | Teleport Pipeline Latency Histogram: 256-Sample Wait-Free Ring, Never Reset | Proposed (extended by ADR-053) |
| ADR-033 | NeoForge Platform Is In Scope (Per-MC-Version Submodule Layout, Mojmap-at-Runtime) | Accepted |
| ADR-034 | Memory Shape Catalog and Polygon Shape | Accepted |
| ADR-035 | Interactive Menus via Written Book (Book-First, Chat Fallback; Optional User GUI via Addon) | Accepted (token-registry sections superseded by ADR-050) |
| ADR-036 | Network Mode: Multi-Server, Multi-Proxy RTP | Accepted (2026-05-14) |
| ADR-037 | Harden RTP Config Commands (Prerequisite for /rtpadmin Setup Wizards) |
Accepted |
| ADR-038 | /rtpadmin Setup Wizards (Book-Menu Driven, Config-Transaction Backed) |
Proposed |
| ADR-039 | /rtpadmin Diagnostic Surfaces (Biome Map, Bad-Selection Heatmap, Metrics Readouts) |
Proposed |
| ADR-040 | Cross-Backend Metric Time-Series Publication via MemoryTracker Tier Promotion |
Proposed |
| ADR-041 | /rtp config Command and Save Mechanics: Implementation Strategy (companion to ADR-037) |
Proposed |
| ADR-042 | YAML Comment Preservation (Block-Only) | Proposed |
| ADR-043 | rtp.personalqueue Permission Semantics: Bucket-Only Opt-In (supersedes operational details of ADR-007) |
Accepted |
| ADR-044 | menu-api Module for Generalized Interactive Menus |
Proposed |
| ADR-045 | /rtp docs Menu Consumer (Markdown -> MenuModel, converted at config load) |
Proposed |
| ADR-046 | maps-api Module for Runtime Cartography Chart Generation |
Accepted (amended 2026-06-04) |
| ADR-047 | Declarative Chart Composition Bridge (ChartSpec + ChartSpecResolver + MapDispatch) |
Accepted |
| ADR-048 | Move menu page builders into rtp-api behind RTPServerAccessor (four default methods + MenuPlatformView snapshot record; no new Gradle module) |
Proposed |
| ADR-049 | Lift network-mode plumbing (NetworkModeBootstrap + 12 helpers) from rtp-plugin/bukkit/network/ to rtp-core; new PlayerLifecycleHook SPI on RTPServerAccessor; supersedes rtp-fabric-ADR-013 |
Accepted |
| ADR-050 | Concrete Menu Commands Supersede Token Registries | Accepted |
| ADR-051 | Two-Tier API Extension Model | Accepted |
| ADR-052 | Outcome Metrics and Cause-Tagged Bad Locations | Accepted |
| ADR-053 | Pipeline Latency Percentiles and Slow-Teleport Audit (extends ADR-032; /rtp info readout) |
Accepted |
| ADR-054 | RTPRunnable Self-Scheduling Thread Routing (target/location + schedule() entity/region/async dispatch) |
Accepted |
| ADR-055 | PvP Combat Gate | Accepted |
| ADR-056 | Pluggable bare-/rtp root action (enables optional user GUI via example addon) |
Accepted |
| ADR-057 | Platform-agnostic addon SPI (RTPAddon + AddonRegistry ServiceLoader discovery; replaces Bukkit JavaPlugin addon loading) |
Accepted |
| ADR-058 | Region-Specific Schematic (.schem) Paste at the Arrival Location (SchematicPaster SPI + swappable per-adapter getter; load-async/paste-on-region-thread) |
Accepted (amended 2026-05-30) |
| ADR-059 | Relative Ground-Distance Safety Predicate (synthetic _groundDistance block-state property consumed by the ADR-017 numeric-range grammar; ground leaves/roots safe, tall-tree canopy unsafe) |
Proposed |
| ADR-060 | Emergency-Platform Block-Restoration Timeout (safety.yml platformRestoreSeconds, -1 disables; per-coordinate diff capture; DB-persisted, chunk-loaded countdown reaper; row removed on completion) |
Accepted |
| ADR-061 | Open-Core Dual Licensing (MIT for rtp-api, rtp-core, and the RTP lite binary; PolyForm Noncommercial for Pro-only source) |
Superseded by ADR-108 |
| ADR-062 | Biome-Probability Weighting for Location Selection (Anvil-sourced per-region biome occupancy map + bounded weighted draw; steering distinct from existing bad-sector avoidance) | Accepted |
| ADR-063 | Biome-First Menu with Auto-Region Selection by Biome Availability (observed-biome list from MemoryShape.getObservedBiomes(), BiomeColorSource row coloring, shared /rtp biome:<x> auto-region for CLI/menu parity, no player-controlled disk writes) |
Accepted |
| ADR-064 | Config-Comment Format: Summary Line as Menu Hover Text (fixed two-part template — standalone first-line summary + prose + @type/@options/@range/@unit/@default/@source directives; canonical style guide docs/dev/CONFIG_COMMENT_STYLE.md) |
Accepted (amended 2026-08-14) |
| ADR-065 | World-Override Regions and the /rtp World Menu (shared world:<x> override builds a cached <region>_<world> region so rtp world:nether and rtp region:r world:nether actually land in the target world; adds the front-page world picker row) |
Accepted (amended 2026-06-18) |
| ADR-066 | Foreign Config Importer (rtp config import <plugin>: one-shot, non-destructive, dry-run/confirm migration aid; generic ConfigImporter seam in rtp-core reading competitor YAML via the in-house parser; BetterRTP/EzRTP/JakesRTP sources; MAPPED/APPROXIMATED/DEFERRED/DROPPED classification; SetAsRespawn/LockAfter deferred until parity lands) |
Accepted |
| ADR-067 | Automatic PRESCAN, Adaptive Scan Rate Control, and .mca-Header Generation Check (three disk-/generation-neutral safety-map tiers: scheduled PRESCAN-only auto-scan that never promotes to FULLSCAN, opportunistic bounded on-load PRESCAN clipped to region boundaries, and live verification fallback; two-axis MSPT-headroom + queue-pressure per-tick budget; check-then-allocate predictive bound using per-class ChunkLoadProfile floors; Option B per-chunk generated/ungenerated read from the cached region-file sector-offset table via an anvil-api helper, reusing ScanTask's existing region-file binning; all behaviour configurable via performance.yml keys, off by default) |
Proposed |
| ADR-068 | Cross-Server Persisted Teleport Limits (two orthogonal axes: durability local always-on + optional proxy durable store, file-backed YAML/JSON in lite and Redis/SQL in Pro; swappable transport reusing NetworkTransport; push-on-connect snapshot instead of poll-per-teleport; relative-duration wire format to neutralize clock skew; usage-cap persistence parity with the already-persisted cooldown; fail-open-to-local) |
Accepted |
| ADR-069 | Claim Integrations Extracted to Bundled Addon (LeafRTPClaimAddon) |
Accepted (supersedes ADR-019) |
| ADR-070 | Platform-neutral /rtp command root (CoreRtpRoot) for Brigadier-bridged platforms (collapses the duplicated Fabric / NeoForge roots into thin subclasses of one rtp-core root; accessor-backed ServerAccessorCommandParameters for player/world; new default RTPServerAccessor.getOnlinePlayerNames() SPI; Bukkit root left bespoke) |
Accepted |
| ADR-071 | Config Organization and Discoverability (keep split-by-concern files; virtual Teleport/Safety/Economy/... grouping in menu+docs rather than physical YAML merges; relevance ordering of keys; staged messages.yml plan: section refinement now, planned messages/-directory split later via a merge-loader that keeps the closed MessagesKeys enum + legacy flat-file fallback; read-legacy-warn-prefer-new migration on key moves; first action de-duplicates config.yml's network.redis against the authoritative network.yml) |
Proposed (top-level directory layout in rule 1 superseded by ADR-076) |
| ADR-072 | Teleport View-Distance Clamp and Steady Restore (per-player delivery view distance clamped to the viewDistanceTeleport preload radius, floored at MIN_VD=2, on arrival; one new performance.yml#viewDistanceRestoreInterval total-time ramp key, default 200 ticks, 0 disables; single-chunk increments deferring to any larger concurrent view distance; platform-neutral getViewDistance/setViewDistance SPI; RTP.scheduler-driven, session-scoped, no DB persistence) |
Accepted |
| ADR-073 | Config Default Inheritance via @<file> References (region/world settings may resolve to a global default owned by a named file instead of a literal; the @<file> token names the owning file so each default stays in its concern file - price -> @economy, shape/vert/cache caps/spatialResolution/world requirePermission -> @config#defaults; type-bearing shape/vert inherit as whole named blocks, type-free scalars inherit individually; shipped regions/worlds defaults use the reference; read-time fail-safe resolution with warn-on-missing/unknown-file; non-rewriting opt-in migration + version bumps; menu inherit/override toggle; extends ADR-071, builds on the ADR-034 shape catalog) |
Accepted |
| ADR-074 | Operator-Facing RTP Throughput and Cost Metrics (end-to-end command latency + cost-per-valid-location reusing the ADR-032 ring; always-paired usage/refill EWMA rates over a shared named window with backlog fill %/state label to disambiguate hysteresis-driven zero refill; usage/refill ratio headline; green/amber/red color coding via the ADR-053 threshold mechanism; extends ADR-032/ADR-053) | Proposed |
| ADR-075 | Platform-Neutral Player-Move Event SPI (normalized block-granularity move signal in rtp-api, dispatched by rtp-core, implemented per adapter - Bukkit PlayerMoveEvent, Fabric/NeoForge server-tick position diff; opt-in per-player subscription so cost scales with watched players not total; enables cross-platform region confinement/tether and future move-driven features without a WorldGuard dependency) |
Accepted (2026-07-25) |
| ADR-076 | Config Folder Consolidation (reduce the operator-facing top level from 12 to a small tiered surface: everyday YAMLs at root + addons/ + definitions/ grouping the MultiConfigParser sets regions/worlds/effects + one advanced/ door absorbing schematics/messages alongside the tuning YAMLs; the lang/ locale value tree stays at root, and rename-maps become co-located dotfile siblings mirroring the default tree; database/ stays at root as runtime state; supersedes ADR-071's top-level layout only, all other ADR-071 rules retained; read-legacy folder-relocation migration + version bumps) |
Accepted (2026-07-26) |
| ADR-077 | Multi-Format Region Support: Pluggable Region Readers, Linear via Addon (generalizes anvil-api to a pluggable RegionFileReader SPI with RegionFormatRegistry / ServiceLoader registration; Anvil .mca is the only built-in format; unregistered formats are never decoded and fall through to the live async load; a guarded Linear reader ships later as an addon; preserves zero main-thread chunk I/O and zero-RTP-dependency module boundary; extends ADR-016) |
Accepted (2026-08-26; revised 2026-10-06) |
| ADR-078 | Composable Cache Pipeline Stages, Domain Stage Nomenclature, and Dynamic Hot Quota Allocation (Backlog/Cold/Hot replace L1/L2/L3; generic bounded CacheStage<T> with terminal onDispose as the single ticket-disposal path; HotSink transfer eligibility by resident-chunk recheck; max-cached-chunks pulse allocator; per-access-method sinks retained; extends ADR-006, ADR-023, ADR-028) |
Accepted (2026-09-03) |
| ADR-079 | Cause-Based TTL and Staged Expiration on Spatial Memory Segments (volatility tiers; selective coalescing avoiding static/dynamic merge; staged probation buffer with double-TTL lazy restore; backward-compatible RegionVerifierRegistry overloads accepting name and duration; advanced/ttl.yml overrides; extends ADR-001, ADR-026, ADR-052) |
Accepted (2026-09-03) |
| ADR-080 | Opt-In Simulation Benchmark Tier (third instrument alongside the real-server harness: @Tag("simulation") tests under rtp-core/.../common/benchmark/, excluded from test via class-file patterns and run only by :rtp-core:simulationBenchmark; mandatory MEASURED/DERIVED/MODELED provenance per reported row; shared measured cost oracle with common random numbers; self-consistency assertions only; publication rules covering validation gates, parity disclosure, strategy-class naming for unmeasured competitors, and pregenerated-world supersession) |
Accepted (2026-09-04) |
| ADR-081 | Unified Blocked Biome Run Table in MemoryShape (one immutable blocked union replaces per-biome long[] tables plus a coalesced duplicate; merging on biome identity rather than proximity; last-observation-wins resolved by clipping so the union is a partition and getEffectiveGoodCount() is invariant; long per-block key/sum bases with int in-block offsets and a short biome id, blocks closing early so overflow is structural rather than radius-bounded; per-block copy-on-write; attributed per-biome extents; .bin version 4 storing a name table plus one LEB128 (key delta, width, id) run stream, with version <= 3 ingested through the same merge helper) |
Accepted (2026-09-05) |
| ADR-082 | Cache-Conscious B+ Tree of Primitive Array Pages for Spatial Run Memory (immutable B+ tree with flat primitive array leaf pages; logarithmic $O(K \log_B N)$ incremental rebuilds; zero object-pointer overhead; supports scaling to native Minecraft world border $\pm 30,000,000$ blocks) | Not adopted - alternative considered (never implemented) |
| ADR-083 | Two-Tier Hierarchical Cell Routing: Probabilistic Macro-Cell Selection to Intra-Macro-Cell Manifold (stated in unitless cells with macro-cell edge B = M * r as a power-of-two knob, no block/chunk/region-file constants; Horvitz-Thompson compensated integer subsampling with systematic rotational phase inclusion and a PI_MIN starvation floor; SplitMix64 mixer, W = 2^20, rebuild-driven epoch counter; Morton micro-cell order; rand() overridden wholesale while xzToLocation/locationToXZ stay the canonical key so learned state and the .bin format are unbroken; per-micro-cell count table with local prefix sums; volatile immutable snapshot publication; ADR-080 comparison plan with split unsubsampled chi-square and subsampled coverage acceptance) |
Superseded by ADR-084, then declined by ADR-085 - alternative considered |
| ADR-084 | Layered Learned-State Index: Coarse Spiral Directory over Per-Cell Hilbert RLE Blobs (retains the ADR-001 spiral as the addressing and expansion curve but coarsened by a derived outer-cell edge, so xzToLocation is a per-selection rather than per-cell cost and expand stays supported on measured good-cell counts; Fenwick directory of per-outer-cell good counts as the only resident structure; per-outer-cell pageable blobs holding bad cells as coalesced runs over Hilbert order with rank/select; exact per-epoch uniformity with no subsampling and no precision discard; coalescing expressed as low-order Hilbert-bit truncation so merges are quadtree-aligned; reconciliation local to one blob, measured at radius^-1.417 against the spiral's radius^+1.421; supersedes ADR-083 as a decision) |
Rejected - superseded by ADR-085; alternative considered |
| ADR-085 | Spiral-Addressed Hilbert Key Space for Learned State (the ADR-001 spiral orders coarse points and each point's slice of the key space expands in place into that point's Hilbert traversal of the chunks inside it, so key = spiralIndex(point) * P^2 + hilbertIndex(chunk) stays one contiguous interval at one-chunk precision; only xzToLocation/locationToXZ change, so marks, probation, spatialResolution coalescing, rebuild, badSum, expand, mode and single-binary-search selection are inherited unchanged, with no directory, no second table and no new uniformity argument; point orientation derived from the spiral's local travel direction through the eight symmetries of the square so cross-point runs merge on the straight sides; measured 3.3x-5.8x smaller table under a stated loss cap and, at an identical coalescing gap, 2.2x fewer runs while discarding 3.8x less usable ground, against 1.01x-1.16x more runs at full precision; .bin header extension - curve, P, keyWidth - rather than a new format; declines ADR-083 and ADR-084 with cause) |
Accepted (2026-09-06) |
| ADR-086 | External Web Map Integration via anvil-api, maps-api, and Spatial Memory (on-demand raster tile provider for Pl3xMap/Dynmap; vector volumes and dispersion radar for BlueMap; cartography pre-filter via setTileFilter; zero main-thread chunk I/O; clean addon boundaries per ADR-013/ADR-057) |
Proposed |
| ADR-087 | Adaptive Tick-Budget, Memory Backpressure, and Dynamic Workload Regulation for Folia Execution (empirical before/after differential telemetry, budget-driven period and cacheCap floating, multi-region concurrency bounding to prevent EzRTP-style region freezes, spatial distribution balancing via candidate compute reordering and anti-starvation pacing, operator visibility and audit logging) |
Proposed |
| ADR-088 | Configurable Downsampling Stride Filter for Spatial Candidate Selection (operator-configurable Hilbert/grid sampling stride for deterministic inter-player separation and accelerated safety scanning; consumption-driven phase alternation for ergodic coverage; preserves 1-chunk safety run tables) | Accepted |
| ADR-089 | Universal MapCanvas Bridge, Biome-Hazard Composite Overlays, and Visual Pipeline Gauges (bidirectional ImageMapCanvas bridge enabling in-game map items and PNG/BMP export; composite desaturated biome backdrop with red hazard wash and outlined candidate dots; color-synchronized L1/L2/L3 queue capacity health bars; typed /rtp visualization export <type> sub-commands) |
Accepted |
| ADR-090 | Test-Driver, Synthetic MCA Generator, and Dimension Benchmark Dataset (two-tier architecture: 6 curated authentic Folia MCA region slices across Overworld, Nether, and End + parametric zero-dependency SyntheticRegionBuilder for property tests + headless Folia regional concurrency simulation for ADR-087) |
Proposed |
| ADR-091 | Automated Headless Client for Devstack via Mineflayer (replaces manual roundtrip checkpoint with an autonomous headless Node/Mineflayer protocol client; asserts proxy transfer packets, destination region coordinates, and < 5000ms arrival latency in CI) |
Proposed |
| ADR-092 | Hybrid Bit-Packed and 16-Bit Run Container Hazard Table (1:1 Anvil region binning matching P=32 Hilbert manifold; discarded regions treated as "Full Bins" covered=1024 with zero internal storage; hierarchical "Bin of Bins" Macro-Sectors for massive scale; two-tier architecture separating permanent terrain base from ephemeral TTL overlay; 76% to 94% hazard size cut) | Accepted (2026-10-05; in production as the MemoryShape hazard mirror and stride-group residency) |
| ADR-093 | Declarative Scripted Actions via Core Confinement, Subspace Placement, and Minecraft Command Lifecycle (capability not catalogue - folds group placement and tethering into core primitives while shipping no game; explicit MVP/deferred scope partition; MVP is four gate types scoreboard/spatial/time/predicate with the API predicate as the growth escape hatch; startup-only Brigadier alias registration, no re-registration on reload; live MemoryShape.contains boundary evaluation inheriting expand with no session snapshot; guarded non-fatal dispatch with guaranteed teardown, mandatory startup orphan-state reaper and UUID-sanitized placeholders; bi-directional callback hooks on rtp-api) |
Proposed (targeted at the release after the current spatial-memory line) |
| ADR-094 | Quality-Engineering Gates: Tiered Logic Tests, Local Static Analysis, and Changed-Line Coverage (opt-in, local-first gates wired into the root build.gradle subprojects block: purpose-based JUnit-tag test tiers with untagged = default logic/coverage tier and slow/edge/simulation/drawing/demo excluded, -PfullTests runs all; opt-in PMD static-analysis gate -PstaticAnalysis over an appendable, programmable config/pmd/ruleset.xml incl. the PreferNonLockingExecution custom rule; server-less changed-line coverage gate scripts/diff-coverage.py against a baseline ref; SonarQube/LAN remote gate explicitly deferred; realises docs/dev/ENTERPRISE_READINESS.md, references ADR-080's simulation tier) |
Accepted (2026-09-11) |
| ADR-095 | Subspace Anchor Providers, Near-Teleport Primitives, and External Verifier Perimeter Extraction | Accepted (2026-09-22) |
| ADR-097 | Per-Action Pre-Validated Caches and Bounded Subspace Placement Retries | Accepted (2026-09-23) |
| ADR-098 | Declarative Command Parameters, Per-Parameter Permissions, and Authoritative Defaults (extends ADR-093; parameters: under an action's command: block declare name/type/required/permission/default; naming a specific player requires the parameter permission - closing the arbitrary-teleport hole - while the declared default (self/any/literal) is the single authoritative source for the no-argument case; fail-fast validation at config load) |
Accepted (2026-09-26) |
| ADR-099 | Zero-Overhead Visual Region Creation via Ecosystem Selection Bridges and Cartography Models (platform-neutral SelectionBridge for WorldEdit/FAWE across Bukkit/Folia/Fabric/NeoForge and FTB Chunks on modded; zero-server interactive web map drawing with clipboard YAML/command hand-off; in-game visual boundary verification via maps-api RegionBoundary cartography items) |
Proposed |
| ADR-100 | Superseding ADR-024: Technical Parity and Pro as SLA & Support Tier (100% technical and database parity between distributions; Pro re-framed as SLA, Support Agreement, commercial indemnity, and verified sponsor tier; marketplace DRM used to route priority support) | Accepted (2026-10-01; commercial-grant bullet withdrawn by ADR-108) |
| ADR-101 | In-House SQL Connection Pool and Retirement of HikariCP (zero-dependency lightweight pool replacing HikariCP in MySQL/PostgreSQL accessors; complete removal of shaded HikariCP from rtp-core) | Accepted (2026-10-02) |
| ADR-102 | Coverage-Guided Fuzz Testing and Parser Input Hardening (Jazzer in-process fuzzing for Anvil/Linear chunk decoders and RespProtocol wire codec; bounded payload allocations) | Accepted (2026-10-02) |
| ADR-103 | Multi-Version Platform Adapter Deduplication and Runtime Coverage Normalization (Active baseline normalization for JaCoCo server coverage; excludes dormant isomorphic NMS/carrier shims and shaded LZ4) | Accepted (2026-10-02) |
| ADR-104 | Ephemeral Web Editor and In-Game Packed Docs Integration (zero-port outbound HTTPS editor session + zero-IO in-game Markdown lowering to book menus; simultaneous read & edit for remote operators) | Accepted (2026-10-03) |
| ADR-105 | Intent-Based Documentation Architecture, Operator-Centric Routing, and Documentation Lifecycle Refinement (four intent pillars: Get Started, Configure, Operate, Extend; MkDocs navigation overhaul; wiki stubs targeting live docs site; untracked scratch hygiene) | Accepted (2026-10-03) |
| ADR-106 | Shape Curve Helpers, Curve-Space Run Layers, and the Signed Two-Way Editor Channel (extends ADR-104; each shape supplies its curve as JavaScript via MemoryShape.toJavaScript() / editor-curve/<SimpleClassName>.js, with settings as inputs and optional curveState(); helpers run only in a sandboxed opaque-origin iframe/Worker, checked by SHA-256 and a 256-sample FNV-1a curve hash, failing closed to the sketch or tiles; typed settings form from getParameters(); hazards as curve-space runs with uniquePlacement filtered; LuckPerms-style {msg, signature} SHA256withRSA channel with in-game key trust, over bytesocks (hosted), the loopback (local) or in memory (tests); 32 KiB frames, 2 MiB/min outbound, bytebin hand-off, snapshot-only fallback on relay failure; generated helpers, more run layers, binary frames and a self-hosted relay deferred) |
Accepted (2026-10-04) |
| ADR-107 | Addon Editor Extensions: Shared Data, Addon Tabs and Protocol Negotiation (extends ADR-106; RTPHooks.editorExtensions() registry with an EditorExtension contract in rtp-api instead of publishing EditorChannel; core keeps schedule, transport, signing and caps; dotted <id>.<type> namespace with undotted types reserved to core; protocol {channel, extensions} and extensions[] descriptors in the snapshot and hello-reply; per-type latest / ordered delivery replacing the fixed bundle sets, with tolerant page dispatch of unknown items; per-extension budget shares; tier 1 declarative page-rendered tabs, tier 2 sandboxed opaque-origin iframe contract; addon YAML only through Hot-Apply with extension validate; map overlays, frame runner and per-extension permissions deferred) |
Accepted (2026-10-05) |
| ADR-108 | All-MIT Licensing; Pro as Support, Not Source (root LICENSE becomes MIT for all source and both jars; Pro sells priority support, early access and sponsorship with no extra licence; withdraws ADR-100's commercial-grant bullet; the lite tags-api exclusion recorded as the one remaining parity follow-up) |
Accepted (2026-10-05; supersedes ADR-061) |
Spatial-memory lineage (production). Two designs ship: the original Archimedean spiral (ADR-001, kept as the *_DEPRECATED_PURE_SPIRAL shapes for benchmarking and rollback) and the dual-layer model - spiral-addressed Hilbert key space (ADR-085) with the dyadic stride filter (ADR-088) and the hybrid hazard table (ADR-092), over the blocked run table (ADR-081). ADR-082, ADR-083 and ADR-084 are research records kept as alternatives considered; new spatial-memory work shall extend this lineage or supersede it by ADR, not open a parallel design.
ADR-084 is Rejected as a decision, superseded by ADR-085: its resident-fraction claim was voided by a sub-chunk addressing unit, its accuracy metric divided by bad area rather than usable ground, and its absent model boundary was an artifact of an asymmetric objective. Its measurement sections are retained as the evidence that redirected the work.
Subproject ADRs¶
ADRs whose scope is confined to a single subproject (module / addon) live next to that subproject's source under <subproject>/docs/adr/ rather than in this directory. They follow the same numbering sequence and template as the project-wide ADRs above. Catalog of known subproject ADR directories:
| Subproject | Path | ADRs |
|---|---|---|
LeafRTPActionAddon |
addons/LeafRTPActionAddon/ |
ADR-093 Declarative Scripted Actions via Core Confinement, Subspace Placement, and Minecraft Command Lifecycle (Supersedes LeafRTPGroupAddon / leafrtp-group-addon-ADR-001 & ADR-002) |
LeafRTPTetherAddon |
addons/LeafRTPTetherAddon/docs/adr/ |
leafrtp-tether-addon-ADR-001 Tether: Cross-Platform Region Confinement Composed From RTP Primitives (No WorldGuard Trap) (Proposed) |
commands-api |
api/commands-api/docs/adr/ |
commands-api-ADR-001 Brigadier Bridge via commands-api Adapter Layer (Proposed); commands-api-ADR-002 Message-delivery seam via a MessageSink SPI (Accepted); commands-api-ADR-003 Registration seam via a CommandRegistrar (Bukkit), neutral command roots (Accepted) |
effects-api |
api/effects-api/docs/adr/ |
effects-api-ADR-001 Glide Effect in effects-api (Proposed); effects-api-ADR-002 Type-Driven Adaptive Reading Order (Accepted; amended by ADR-004); effects-api-ADR-003 Platform Split Bukkit/Fabric (Accepted); effects-api-ADR-004 ValueCoercer SPI: Per-Platform Type Binding for the Adaptive Reading Order (Accepted); effects-api-ADR-005 effects.yml: Group-Centric, Stage-Bound Effect Configuration (Proposed); effects-api-ADR-006 Fabric obf/unobf Split (Accepted); effects-api-ADR-007 Command Effect and Death Stage in the Effects Engine (Accepted) |
rtp-fabric |
platforms/rtp-fabric/docs/adr/ |
rtp-fabric-ADR-001 Fabric Multiversion Submodule Layout (Accepted); rtp-fabric-ADR-002 Fabric Platform Is In Scope (Accepted; renumbered from ADR-022 on 2026-05-05 to resolve a numbering collision); rtp-fabric-ADR-003 Non-persistent chunk tickets via DistanceManager.addRegionTicket (Accepted); rtp-fabric-ADR-004 DistanceManager API split at MC 1.21.5 (Accepted); rtp-fabric-ADR-005 Fabric anvil pre-filter parity (Accepted); rtp-fabric-ADR-006 Chunk-ticket radius is 3, not 31 (Accepted); rtp-fabric-ADR-007 Decouple FabricVersionAdapter from Mojmap type names (Accepted); rtp-fabric-ADR-008 Non-blocking chunk generation via ServerChunkCache#getChunkFuture (Accepted); rtp-fabric-ADR-009 Obf/unobf common module split (Accepted); rtp-fabric-ADR-010 Typed block-tag snapshot via per-version SPI; reflection demoted to fallback (Accepted); rtp-fabric-ADR-011 Effective-permission enumeration on Fabric (LuckPerms-Fabric primary, registry-probe fallback; covers rtp.effect.* + rtp.onevent.* + numeric tails) (Accepted 2026-05-22); rtp-fabric-ADR-012 Menu renderer parity on Fabric (chat-first via obf/unobf carrier split; book renderer deferred; PromptAnvilInput substituted by chat-prompt callback) (Proposed 2026-05-22); rtp-fabric-ADR-013 Network-mode backend parity on Fabric (reimplementation as FabricNetworkModeBootstrap + FabricJoinTriggerSource; pulls pure-I/O helpers up to a shared utility; reuses ADR-011 resolver for reservation-token auth) (Proposed 2026-05-22); rtp-fabric-ADR-014 Early/experimental MC 26.2 pre-release adapter (rtp-fabric-v26_2_R1, cloned from v26_1_R1; deobf/JDK-25; startsWith("26.2") dispatch) (Accepted 2026-05-31); rtp-fabric-ADR-015 Maps API parity (vanilla filled-map path; FabricMapBinding + FabricVersionAdapter.renderMapChart seam, 26.2_R1 carrier) (Accepted 2026-05-31); rtp-fabric-ADR-016 Kept-cache chunks pin at non-entity-ticking level (32), not ENTITY_TICKING (30) (Accepted 2026-06-02) |
maps-api |
api/maps-api/docs/adr/ |
maps-api-ADR-001 Module Bootstrap, Package Layout, and Palette Policy (Accepted); maps-api-ADR-002 GUI-Slot Map Delivery and a Future Off-Main Raw-Packet Render Path (Proposed) |
metrics-api |
api/metrics-api/docs/adr/ |
metrics-api-ADR-001 Module Extraction from rtp-core (Accepted) |
bstats-api |
api/bstats-api/docs/adr/ |
bstats-api-ADR-001 Dependency-free bStats Client Module (Accepted) |
rtp-neoforge |
platforms/rtp-neoforge/docs/adr/ |
rtp-neoforge-ADR-001 NeoForge Platform Is In Scope (Per-MC-Version Submodule Layout, Mojmap-at-Runtime) (Accepted 2026-06-01) |
rtp-proxy |
platforms/rtp-proxy/docs/adr/ |
See subdirectory index. Highlights: rtp-proxy-ADR-001 SPI Shape (Proposed); rtp-proxy-ADR-002 network.yml Schema (Accepted 2026-05-14, amended 2026-05-18); rtp-proxy-ADR-003 In-Memory Binding (Proposed); rtp-proxy-ADR-004 Weighted-Average Selector (Proposed); rtp-proxy-ADR-005 Redis Binding (Accepted 2026-05-18); rtp-proxy-ADR-006 Velocity Bootstrap (Accepted 2026-05-18); rtp-proxy-ADR-007 Postgres Binding (Proposed, superseded-sketch by ADR-011); rtp-proxy-ADR-008 Bungee Bootstrap (Proposed); rtp-proxy-ADR-009 Generic SQL Binding (Proposed, superseded-sketch by ADR-011); rtp-proxy-ADR-010 Security Hardening (Accepted 2026-05-18); rtp-proxy-ADR-011 SQL Network State Binding (Accepted 2026-05-18); rtp-proxy-ADR-012 Proxy Role: Participant Default (Proposed); rtp-proxy-ADR-013 RTPProxyAccessor Registration (Proposed); rtp-proxy-ADR-014 Backend-Owned /rtp with Network Wait-Queue (L6) (Accepted 2026-05-21, supersedes rtp-proxy-ADR-006 Command Hosting); rtp-proxy-ADR-015 Shared Network Waitlist and Dynamic Batched Dispatch (Proposed 2026-05-21); rtp-proxy-ADR-016 Plugin-Message Default Transport (tier-1, non-durable, ships in lite; amends ADR-036) (Accepted 2026-06-12); rtp-proxy-ADR-017 Proxy-Direct Transport (player-independent socket; amends ADR-036) (Accepted 2026-06-13); rtp-proxy-ADR-018 Cross-Server Teleport Execution on Proxy-Direct (amends ADR-036; superseded by ADR-019); rtp-proxy-ADR-019 Proxy-Direct as Remote View of In-Memory Store (amends ADR-036; supersedes teleport leg of ADR-018) (Accepted 2026-06-13); rtp-proxy-ADR-020 Direct Database Cross-Server Dispatch Mode (refines ADR-036) (Proposed 2026-10-02); rtp-proxy-ADR-021 Seamless In-Play Velocity Transfers with Zero-Trust Hardening (refines ADR-036) (Proposed 2026-10-02) |
When adding a new subproject ADR, also add a row here so the global index remains a one-stop catalog.
Template¶
Use ADR-TEMPLATE.md when recording a new decision.