Skip to content

Changelog

All notable changes to RTP are documented here.

Format follows Keep a Changelog; versioning follows SemVer.

One changelog covers both the free and Pro jars, which ship the same code.


[Unreleased]

[3.3.3] - Unreleased

Fixed

  • Regions with an explicit block radius such as radius: 16384b could be shrunk to a 64-chunk ring and warn that they exceeded a 256-chunk world border. The SQUARE world-border lookup left the border shape at its 256-chunk (4,096-block) default instead of reading the world's WorldBorder size, and spatialResolution: auto converted radius: 16384b to a plain chunk count (1024) before the unit check ran, causing 1024 chunks to be re-interpreted as 1,024 blocks (64 chunks). Native world-border shapes on Paper, Folia, Spigot, Fabric, and NeoForge now read the world's actual WorldBorder size and center, and unit checks run before spatialResolution: auto caches the converted chunk count.

  • .lca region files could be treated as ungenerated chunks during random teleports, and evicting open .lca regions on large world borders could stall chunk reads. Chunk-existence checks read the first 4 KiB of .lca files as a legacy .mca header, and opening a clean 1,024-chunk .lca region read every chunk header individually and ran unpromoted FIFO cache eviction. .lca existence checks now read the .lca pointer directory, clean region opens verify the header parity table without per-chunk reads, and region caches use Second-Chance Clock promotion with coalesced compaction before cache removal.

  • On-demand random teleports (rtp.unqueued or empty cache queues) could decode candidate chunks twice when anvilPrefilterEnabled was active. When the on-demand load governor selected a direct chunk load (or after an offline region prefilter check passed), the live chunk loader re-entered the offline region-file prefilter before loading the chunk on the server. Direct and post-prefilter chunk loads now load the live server chunk once without re-reading the region file.

  • Chunk-load listeners on Fabric could stall the server thread when reading neighboring chunks, and Paper 26.x+ time-skip events and subcommand tab completion could miss lookups. Fabric CHUNK_LOAD callbacks now run on the next server tick instead of inside ServerChunkCache chunk promotion, Bukkit TimeSkipEvent skip-reason lookups resolve across Paper's relocated SkipReason enum without throwing IncompatibleClassChangeError, and Bukkit tab completion checks both subcommand maps when suggesting parameter=value arguments.

3.3.2 - 2026-10-30

Added

  • Litematica schematics (.litematic, ADR-058). Regions (schematic in definitions/regions/*.yml) and action PASTE_SCHEMATIC steps now accept .litematic files in schematics/ alongside .schem and .schematic, including multi-region Litematica files, negative region sizes and block entities. Config and action BIT checks accept .litematic paths as well.

Changed

  • Action name collisions with /rtp, /wild or another action are now BIT errors (ACTADDON_NAME_COLLISION, ADR-121). /rtp test action-setup reports ACTADDON_NAME_COLLISION as an ERROR instead of a WARNING when an action's name or command alias collides with /rtp, /wild or another action, and names the existing owner in the message.

  • /rtp reload reads and checks config files off the main thread. Full and single-section reloads (such as /rtp reload regions or /rtp reload worlds) now parse files and run config BIT checks asynchronously before swapping the active configuration on the main thread, and a reload started while another is already running replies with alreadyReloading instead of overlapping.

  • /rtp config search expands multi-word queries and falls back to an online thesaurus. Multi-word searches strip punctuation before matching, and when local keys and the bundled thesaurus return no matches, /rtp config search queries an online synonym fallback off-thread.

  • For addon developers. RTPPlayer adds default sendTitle(title, subtitle, fadeIn, stay, fadeOut) and sendActionbar(message) methods. In-session onStart and onBoundaryViolation action gates now pass the session's ActionContext to registered custom gate validators, and RTPRuntime.setServerAccessor keeps RTPAPI.serverAccessor in sync.

Fixed

  • Background cache fill on NeoForge 1.21.1 could hang the server and trip the watchdog. The 1.21.1 chunk-ticket lookup bound the raw-level ticket method instead of the radius-based region-ticket method, turning a 0- or 1-chunk ticket radius into a 32-33 chunk generation radius around every loaded chunk, and temporary load tickets shared the rtp ticket type with kept-cache tickets. NeoForge 1.21.1 now binds the region-ticket method and uses a separate rtp_load ticket type with a 30-second expiry for temporary loads.

  • Folia safety checks with safetyRadius > 0 could read loaded neighbor chunks off the region thread. When a candidate chunk's center was read from an offline region file while one of its safetyRadius neighbors was already loaded on the server, the neighbor check ran on the async worker instead of the owning region thread. Safety checks now hop to the region thread whenever any chunk in the safety square is loaded.

  • Failed region economy checks left players stuck as "already teleporting", and rtp.free did not bypass balanceFloor. When a region's price or balanceFloor rejected a teleport, the player's incomplete teleport entry stayed active and blocked later /rtp commands with alreadyTeleporting. With toggleTargetPerms enabled, a target player who failed the economy check also did not refund the command sender. Economy and region checks now finish before a teleport session is recorded, rtp.free bypasses balanceFloor, and failed target charges refund the sender.

  • Post-teleport title, subtitle, actionbar, consoleCommands and playerCommands did not run on Fabric or NeoForge, and toggling effectParsing ignored /rtp reload. Post-teleport titles, actionbars and commands now run on Fabric and NeoForge as well as Spigot, Paper and Folia (and are skipped for /rtp test mock players), and effectParsing in advanced/performance.yml updates on /rtp reload without a restart.

  • Visual and sound effects on Folia could run off the player's region thread. Player-targeted effects now check region ownership on Folia and reschedule onto the player's entity scheduler when called from another thread.

  • Bundled action definitions always loaded from the English locale folder. On startup and reload, the action addon read definitions/actions/ using "en" instead of the server's configured language in config.yml.

  • Some translated keys in nested lang/<locale>/advanced/ files did not match their .lang.yml key maps, and /rtp docs messages hardcoded [RTP] instead of [P0]. Nested advanced/ locale files in de, it, pl, zh and cat now match their .lang.yml key-rename maps, and docsNotFound, docsEmpty, docsExportSuccess and docsExportFailed in advanced/messages/commands.yml now use the [P0] prefix placeholder across all locales.

  • Unpacking an @config, @economy or @safety reference in /rtp editor could not be undone with Ctrl+Z. Unpacking a reference now records an undo/redo step, concurrent /rtp editor HTML exports no longer share a single temporary file, and unreachable relay servers log a single warning line without a stack trace when falling back to snapshot-only mode.

  • The /rtp editor biome map on non-Anvil region formats used the .mca reader. Biome extraction for the web editor map now decodes chunks through the registered region-file reader for non-.mca formats instead of calling the Anvil .mca probe directly, and counts unreadable chunks in BIT status.

  • World border startup checks skipped CIRCLE_DEPRECATED_PURE_SPIRAL and SQUARE_DEPRECATED_PURE_SPIRAL regions and string numbers. The world border check now recognizes both spiral shapes and numeric string values in region shape configs.

  • Disconnecting players kept background-refill attribution history and could trigger warnings from open menus. Leaving the server now clears the player's autoTune refill attribution history, and chat or book menus and /rtp admin setup pages that finish rendering after the viewer disconnects skip the render without logging a warning stack trace.

  • Concurrent bad-location flushes could fail with an array bounds error under heavy rejection load. Rebuilding a region's bad-location table while another worker recorded a rejected spot could overrun the snapshot buffer; the snapshot is now bounded to the allocated buffer size.

  • Biome activity sampling could load unloaded player chunks on the main thread. Periodic biome sampling for players standing in or crossing into an unloaded chunk could trigger a synchronous chunk load on Bukkit and Paper; biome sampling now skips unloaded player chunks.

3.3.1 - 2026-10-26

Added

  • Tune background cache refill automatically from server headroom and player demand (autoTune, ADR-087, ADR-123, ADR-124). advanced/performance.yml ships autoTune: true. While players teleport and the server has spare tick time, CPU and memory, regions refill on every tick within asyncAllottedTime, syncAllottedTime and activeChunkCap instead of waiting for period. When tick time, CPU, chunk-load latency or tenured heap usage rises, or when caches are already full, background refill scales down before minTPS, maxMSPT or maxHeapPercent trips, while players waiting for a teleport keep the full configured budgets; constrained refill is shared across regions by distinct active players (ADR-124), and on Folia tick-region shares are probed per cell group and background work prefers tick regions with headroom and fewer players up to a 60 s or 8-deferral aging bound (ADR-123). /rtp info shows effective budgets, per-region refill shares and top consumers, and /rtp test includes the compute-governor check for reduced or floor-held budgets and stale metrics; setting autoTune: false uses the fixed values and refills once per period.

  • Action and Claim addons report setup health through BIT (ADR-121). /rtp test action-setup identifies rejected definitions, command or trigger registration failures, missing batch scheduling and name collisions. On Bukkit-family servers, /rtp test claim-integrations reports disabled, absent, late-enabled and incompatible claim integrations. Each addon publishes a separate code catalog and stable identity lock; first-boot severity overrides for addon codes take effect after addon registration.

  • Refuse steep landing spots (ADR-119). linear and jump verts accept two new optional keys. maxSlope is the largest floor-height step, in blocks, allowed between the landing spot and the ground slopeRadius blocks away (default 2, range 1-8) to the north, south, east and west. Spots on cliff edges or steep hillsides are skipped and the search moves on to the next spot. The check follows the floor the player would stand on, so it also works in caves and the Nether. Regions without maxSlope behave as before and keep their saved region data. Setting or changing either key rebuilds that region's saved data once. Steep worlds with a low maxSlope reject more chunks. Not available on fixed, which places players in mid-air.

  • Keep players off mountainsides and cliff edges (ADR-120). linear and jump verts accept maxHillAngle, the steepest hill in degrees a player may land on. config.yml ships it as "off" under defaults.vert, and the config menu offers "off", 30, 45 and 60; any number from 0 to 89 also works. On a 26.3 test world, 30 refused about 1 in 5 land spots, 45 about 1 in 12 and 60 about 1 in 60. RTP checks the ground 16 blocks away in 8 directions and within 8 blocks of the spot, inside the 3x3 chunks around it, using blocks only, so it works the same with custom generators such as Iris and Terra and on every platform. The check itself loads no chunks: it reads region files during the background search, then rechecks the chunks the server already holds around the spot. Only spots that pass the other checks look at their surroundings, and only at the chunks needed to decide. With the check on, the background search does about 3 times the work per spot and tries more spots, because refused spots are picked again; spots rejected after the server has read their chunk add chunk loads. "off", -1 and a missing key behave as before and keep the region's saved data.

  • Action definitions report findings and support strict registration (ADR-121). Each finding logs its stable code, source file and YAML path, allowed values, and a suggestion when available. advanced/bit.yml ships strictActions: false, which logs structural action codes as warnings and keeps loading compatible; setting it to true prevents registration of an action with any effective ERROR, while other actions continue to load, and per-code overrides take precedence. Unknown ACTION: names are omitted, unknown trigger types are skipped instead of falling back to STEP_IN, and a missing trigger type still defaults to STEP_IN; the checks use the standalone bit-api module.

  • /rtp test reports registered BIT probe results (ADR-121). The SAFE all group includes api-compat, commands, scheduler, events, economy-isolation, disconnect-job, network and safety-verifier, and can be filtered with tier= or subsystem=. /rtp test status shows registered state without rerunning checks, and json=true selects machine-readable output. Chat starts with a component-count summary, then lists only distinct FAIL, WARN and INFO findings; repeated codes are counted, while PASS and SKIP components appear only in the summary. The server log keeps the full table with paths and messages. all is distinct from the Bukkit-only full sweep; existing probe summaries remain unchanged for automation.

  • /rtp test teleport checks the teleport pipeline without a real player (ADR-121). /rtp test teleport [region=<name>] [count=1-16] [json=true] (permission rtp.test.mutating) sends temporary rtp-bit-* test players through real location selection, including real chunk loading, and reports whether the teleport was reached, any left-over teleport state, and timeouts. Test players get no cooldowns, teleport history, usage-limit counts, economy charges, landing-heatmap entries or plugin events, and never appear in online-player lists. Every report says that the final teleport was simulated. The check runs only when named, never as part of all or tier=ibit.

  • Generate a mock teleport landing heatmap (/rtp test teleport-heatmap, ADR-121). Operators with rtp.test.mutating can sample a region with bounded mock teleports and export the landing coordinates and distribution as CSV and PNG files. The probe runs only when named and does not alter the existing landing heatmap.

  • Teleport probes report mock and player results through /rtp test (ADR-121). Stress, queue-starvation, disconnect-midflight, Folia ownership and the pipeline half of async-reply now run as registered BIT components using mock players or UUIDs. Stress and async-reply retain separate player=<name> components for live platform behavior; hologram remains player-only. Component findings are included in the BIT report, and every timeout records BIT_COMPONENT_TIMEOUT while existing [RTP test/<probe>] output remains unchanged.

  • RTP reports startup check health (ADR-121). After startup, RTP runs SAFE action-definition and region-file self-tests off-thread and logs one health summary. A missing optional host Zstandard runtime is informational and leaves the component healthy because RTP can use its safe live-load fallback; a present engine that fails its canary remains degraded.

  • Action runtime health is visible in BIT status (ADR-121). /rtp test status reports missing scoreboard objectives, gates that always or never pass, unresolved placeholders, unknown ACTION: commands, and sessions that remain active beyond their reaper window. advanced/bit.yml adds gateOutcomeSamples, which defaults to 200 evaluations.

  • A bad config no longer breaks a running server on /rtp reload (ADR-121).

  • What is checked. On startup, by /rtp test subsystem=config, and before every /rtp reload, editor Hot-Apply, /rtp config edit, /rtp config import or /rtp admin setup confirm, RTP checks every config file. It reports:
    • YAML that does not parse;
    • values outside the type, allowed values or range in the shipped comments;
    • @config/@economy/@safety references that do not resolve;
    • regions, worlds, schematics and effect groups that point at something missing;
    • impossible settings such as a radius that is not larger than centerRadius or a shrinkTo larger than initialSize;
    • message files with missing keys.
  • How findings are reported. Each finding names its file and key and suggests the closest valid value. The checks read files only and never load chunks.
  • What is rejected. If a reload, Hot-Apply, config command, import or setup confirm finds an error, nothing is applied and the server keeps its current configuration. The sender is told which file and key to fix (new reloadRejected and editorApplyRejected messages, translated in every bundled language).
  • New setting: strictConfig. Problems that earlier releases accepted are logged as warnings for now, so a reload is not rejected. Set strictConfig: true in advanced/bit.yml to treat them as errors. Broken YAML and impossible settings are always errors.

  • Publish condensed metric history across backends in network mode (ADR-040). Setting metrics.networkTimeSeries.publish: true in advanced/network.yml (default false) writes completed metric buckets (tier, default 24h@1m) to the shared SQL table rtp_metric_bucket or Redis sorted sets rtp:metric:<backend_id>:<metric_key> with (sample_count, mean, min, max, p95) and the active network generation. Writes are batched (perPassWriteCap, default 64 rows per pass) and swept per backend after retentionDays (default 7 days). Cross-backend chart snapshots include the (min, max) band alongside mean. When network mode is off and publish: true, RTP logs one warning at startup and stays dormant.

  • Choose whether bare /rtp opens the destination picker (openOnBareRtp). addons/guimenu.yml adds openOnBareRtp: true (also disabled when menuStyle is "none" or "off"). Setting openOnBareRtp: false makes bare /rtp teleport immediately in the player's current world while keeping /rtp gui (rtp.gui) and /rtp menu (rtp.menu) active to open the destination picker.

  • Set the region radius and bare-/rtp menu behavior in the setup wizard (/rtp admin setup, ADR-038). /rtp admin setup adds a region outer radius step (/rtp admin setup radius <distance>, with presets 2.5km, 5km, 10km, 25km, 4096b and 500c, plus a custom distance prompt) and an openGuiOnRtp toggle on the gameplay page (addons/guimenu.yml openOnBareRtp).

Changed

  • BIT codes now have namespace-local identities (ADR-121). The stable identity is (namespace, id, key), so separate code owners with distinct prefixes can use the same number without reserving global ranges. The log table prints namespace:id, JSON includes ns while retaining schema 1 for its first release, and a committed release lock prevents renames, renumbering, reuse or unreviewed default-severity changes; retired codes remain documented. A new startup check, bit-namespaces, reports BIT_NAMESPACE_CONFLICT when two plugins reserve the same code prefix.

  • Runtime-read duration settings accept explicit units. Values such as 30s, 5m, 2h, 1d12h, 40t and 500ms work in safety.yml, advanced/performance.yml, advanced/network.yml and proxy network-proxy.yml; bare numbers retain each setting's existing unit. Invalid backend values use their documented fallback with a warning, while invalid proxy network durations reject the configuration.

  • Both jars share one version number (ADR-117). The separate liteVersion line is retired; full and Lite builds report the same version.

  • For addon developers (ADR-115, ADR-116, ADR-040, ADR-120, ADR-121). The common server bridge and platform-family enum are now available from the standalone server-api artifact in io.github.dailystruggle.server.api (RTPServerAccessor extends ServerAccessor and RTPScheduler extends TaskScheduler), and rtp-api re-exports server-api, menu-api, units-api and tags-api alongside the standalone bit-api, config-bit-api and predict-api modules (ConfigParser, MultiConfigParser, LanguageBootstrap, Factory and FactoryValue also live in yaml-api under their existing packages). Update PlatformFamily imports from io.github.dailystruggle.rtp.api.server and rebuild binaries compiled against the old enum package. Built-in effects now route through ServerAccessors (wrapEffectPlayer, wrapEffectLocation, resolveEffectPlayerAt, dispatchConsoleCommand), HandleRegistry and HandleProvider in io.github.dailystruggle.effectsapi.common.spi are deprecated (@Deprecated(forRemoval = true)) as forwarding shims over ServerAccessors, and the Bukkit effect classes (io.github.dailystruggle.effectsapi.bukkit.* and io.github.dailystruggle.effectsapi.EffectsAPI) have moved from effects-api into :rtp-bukkit:rtp-bukkit-common so effects-api carries no platform code. RTPServerAccessor provides the default Optional<Boolean> hasScoreboardObjective(String) method, RTPScheduler adds isGenerationSaturated(RTPWorld), RTPWorld adds probeChunkSquare for off-thread same-region-file square probes, and rtp-api adds @PublicApi MetricTimeSeriesPublisher and MetricBucketRow in io.github.dailystruggle.rtp.api.metrics.

Fixed

  • Moving during the /rtp warmup now cancels the teleport. Walking farther than cancelDistance during teleportDelay was ignored for /rtp, because the player's starting position was never recorded, so the teleport went ahead anyway.

  • Plain-number teleportCooldown and teleportDelay values were treated as milliseconds instead of seconds. Bare numbers such as teleportCooldown: 300 or teleportDelay: 5 were read as milliseconds after duration-unit parsing landed, and teleportDelay was skipped when all arrival chunks were already loaded. Bare numbers now mean seconds again, and the warmup runs even when no chunks need loading.

  • Per-region cooldown overrides were blocked by a longer global teleportCooldown. Naming a region with /rtp region:<name> now uses that region's cooldown override on its own, and a bare /rtp into a world's default region passes once either the global cooldown or the region's override has elapsed.

  • Walk-in trigger batchInterval waves never fired (ADR-093). The wave timer was registered before the platform scheduler was set on startup, so players waiting in a wave trigger zone were never teleported. The timer now starts when RTP enables and stops on disable.

  • Countdown boss bars stayed on screen after a cancelled teleport. Cancelling a teleport with /rtp cancel or by moving during warmup left the countdown addon's queue or warmup bar running until it reached zero. Both bars are now cleared immediately on cancel.

  • minePlots claim check now detects plots. With rerollMinePlots: true, the check never found a plot, so players could land inside minePlots plots. It looked minePlots up under the wrong plugin name and guessed at its classes. It is now built against minePlots' published API (plugin-api 4.6.2, PlotServiceApi.getPlot from the Bukkit ServicesManager) instead of looking classes up by name, and rejects the spot if minePlots is enabled but that service is missing or the lookup fails. It is tested against the published API, not yet on a live minePlots server, so treat it as best effort.

  • UltimateClaims, PlotSquared, HuskClaims and KingdomsX claim checks fixed. UltimateClaims claims were never found: the check called a lookup UltimateClaims does not have, and could load a chunk off the main thread. On PlotSquared worlds every unclaimed plot was rejected; now owned plots and roads are rejected and unclaimed plots are allowed. The HuskClaims and KingdomsX checks could pick the wrong method depending on the server and then reject everything or nothing. Residence, CrashClaim, HuskTowns, SaberFactions/FactionsUUID and FactionsBridge were checked against their plugins' source and now look methods up by exact signature. These checks are tested against copies of each plugin's API, not on live servers, so treat them as best effort.

  • Claim checks no longer switch themselves off (ADR-118). If a claim plugin is enabled but its API doesn't match what the claim addon expects, every destination is now rejected and one error is logged, instead of the integration turning off and letting players land in claims. Update the claim plugin or the addon, or turn the integration's integrations.yml flag off, to resume teleports.

  • A deleted Rift demo group no longer comes back after a restart. The Rift addon wrote its demo group to the old effects/ folder, and every start moved that copy into definitions/effects/, so deleting definitions/effects/rift.yml while the server was stopped brought it back on the next start, even with the addon removed. The addon now writes definitions/effects/rift.yml directly and deletes an unedited effects/rift.yml left by an earlier version.

  • The Rift effect no longer cancels /rtp or buries the player. The fall into the rift counted as moving and tripped cancelDistance, so every delayed /rtp with RIFT cancelled itself. While the rift is open, only sideways movement now counts, so walking away still cancels. When the rift closes, a player still inside it (teleport cancelled, or the rift's seconds shorter than teleportDelay) is put back on the block they stood on instead of being left inside the restored terrain.

  • Built-in effects that were missing on some platforms are now registered there. TITLE now works on Paper, Spigot and Folia. GLIDE now works on Fabric 26.x and NeoForge. DROP_INVENTORY and DROP_EXP / DROP_EXPERIENCE now work on NeoForge. Before, these tokens were skipped without a message. FIREWORK and NOTE are still Bukkit-family only.

  • GLIDE on Fabric no longer drops the player. Without an elytra the game ended the glide on the next tick, so the player was lifted and then fell, taking fall damage. The glide is now kept going until the player lands, and LANDINGTIMEOUT still forces a landing. Fabric and NeoForge don't yet place players who are still gliding when the server stops.

  • TITLE shows the configured text. Text arguments were replaced by their empty defaults while the effect was built, so TITLE.<title>.<subtitle> showed a blank title on every platform. The same applied to text arguments of addon effects.

  • /rtp config language only tab-completed 5 of the 12 bundled locales. It now suggests all 12 (en, de, es, fr, it, ja, ko, nl, pl, pt, ru, zh).

  • RECTANGLE regions with rotation: 90 mapped locations to the wrong coordinates, and setBiomeGetter overrides on Fabric and NeoForge were ignored. Rotated rectangles now round-trip coordinates and heights, and biome checks on Fabric and NeoForge read the registered setBiomeGetter override first.

  • Background cache fill on NeoForge 1.21.1 could stall player joins. Login-cache promotions and startup ticket re-validation could start unbounded chunk generations at once, and non-hill chunk tickets held a 3x3 radius instead of a single chunk. Generation-causing loads now share a bounded budget, and single-chunk tickets use radius 0 unless maxHillAngle needs the 3x3 square.

3.3.0 - 2026-10-18

Upgrade note. rtp.servers.* now defaults to true instead of op, so in network mode every player can reach open cross-server regions; restrict with negative permissions if you relied on the old default. CIRCLE and SQUARE now use new selection engines that ignore weight; use CIRCLE_DEPRECATED_PURE_SPIRAL or SQUARE_DEPRECATED_PURE_SPIRAL to keep the 3.2.1 behavior. Region shapes now default to mode: REROLL instead of ACCUMULATE; files that set mode keep their value. In config.yml, defaults.shape.uniquePlacements now defaults to "auto" (a radius matching the view distance) instead of 0, and defaults.spatialResolution to "auto" (scaled to the region's size) instead of 3; set 0 and 3 to keep the 3.2.1 values. Both jars now load on Minecraft 1.18 or newer with Java 17 or newer; the Lite jar no longer loads on 1.13 - 1.17. Folia is supported only from 1.21.11; older Folia still loads the jar but is no longer supported. Saved memory and region cache files from 3.2.1 still load, but RTP rewrites them in a new format at the next save or shutdown, and 3.2.1 can't read that format, so back up plugins/RTP/ if you may need to roll back.

Added

  • Runs on Spigot and Paper 1.18 - 1.20.6, and on Java 17 (ADR-113). The full jar now loads on Spigot and Paper 1.18 through 1.20.6, and Fabric 1.20.1 servers can run it on Java 17. These older versions are best-effort and are not covered by automated tests. NeoForge still needs 1.21.1 or newer, and Fabric 1.20.2 - 1.20.6 is not supported. Folia is supported from 1.21.11: it is experimental and only its current builds are maintained, so older Folia builds are not supported and can crash on their own. Bug reports are accepted for Minecraft 1.21.11 through the latest release; the per-version status is in the support matrix.

  • Tag exclusions in safety.yml (ADR-017). Remove entries from a block tag instead of listing every variant by hand, e.g. #minecraft:slabs - OAK_SLAB.

  • Actions. Script multi-step teleports in YAML: what happens before, during and after the teleport, what to do on failure or timeout, and conditions that must pass first (permission, balance, cooldown, world, biome, time, server load and more). Destinations can be anchored to a player, a claim, a faction or a world center, and teams can be placed together. Walk-in triggers start an action when a player enters a zone. Commands: /rtp action (rtp.action; /rtp trigger and /rtp run are other names for it), /rtp action cancel (rtp.action.cancel) and /rtp back (rtp.back). The bundled action addon ships ready-made modes such as arena, KOTH, scatter and teams.

  • Web config editor (/rtp editor). Edit RTP's configs in a browser and apply the changes back to the server. Permission: rtp.editor. The region map shows the land of every loaded world, including the nether and the end, and a region's world can be picked from the worlds the server detected. Passwords, tokens and other secrets are redacted before anything leaves the server and are never overwritten by the editor. Only config files inside the plugin folder can be written, and a browser must be trusted before it can apply changes (revoke with /rtp editor untrust; optional expiry with editor.trust.maxAgeDays in advanced/network.yml).

  • Import from other RTP plugins (/rtp config import, ADR-066). Reads another random-teleport plugin's config folder, such as BetterRTP, JustRTP or EzRTP, by recognizing common config layouts, and moves over worlds, radius, shape, cooldowns, prices, database, effects and JustRTP zones. Permission: rtp.config. The old plugin doesn't need to be installed. Existing files are only replaced with overwrite=true, and are backed up first. /rtp config import permissions prints LuckPerms commands that map BetterRTP, JustRTP and EzRTP permission nodes to RTP's.

  • Setup wizard (/rtp admin setup). A guided first-time setup in chat or the console: world, gameplay, performance, preview, confirm. Your config is backed up before anything is written. Permission: rtp.admin.setup.

  • Teleport near your own claim or faction. Actions can pick destinations around the player's land, with Towny, GriefPrevention and SaberFactions/FactionsUUID supported through the bundled claim addon. The search center stays put through small land changes, and terrain already known to be bad is reused so new searches start fast.

  • Selection heatmap and pipeline views (/rtp visualization heatmap, /rtp visualization pipeline). See on the in-game map where destinations land and how the search moves through a region. Permission: rtp.menu.admin.

  • More claim plugins. The bundled claim addon also keeps players out of HuskTowns, PlotSquared, UltimateClaims and MinePlots land.

  • Minecraft 26.3 on Fabric. The Fabric jar also runs on 26.3 servers.

  • Holograms. Status and pre-teleport text can be shown as holograms, using built-in text displays on 1.19.4+ or DecentHolograms / HolographicDisplays.

  • New engines for CIRCLE and SQUARE (ADR-085, ADR-088). Picks spread evenly by area and never repeat a chunk within a pass. In mode: REROLL players are kept several chunks apart without using up the region, so expand: false regions never run out; very narrow strips of land on internal cell borders may be skipped. Bad-land memory is smaller and faster, and its saved files are up to a third smaller. weight no longer applies; the old shapes remain as *_DEPRECATED_PURE_SPIRAL.

  • Commands as teleport effects, and a death stage (effects-api-ADR-007). Run console or player commands at any teleport stage, with player and location placeholders. The new death stage runs effects when a player dies.

  • Claim and spacing rejections expire (ADR-079). Land rejected for a reason that can change, such as a claim or another player nearby, is retried after the time set in advanced/ttl.yml instead of being avoided forever. Bad terrain is still remembered permanently.

  • Units in configs and commands. Write radius: 5km, teleportCooldown: 2h30m or cacheCap: 256mb. Distance, time and size units are supported; plain numbers keep their old meaning.

  • World border check. RTP warns when a region reaches past the world border and keeps destinations inside it.

  • API on Maven Central. rtp-api, rtp-core and the API libraries they depend on, such as commands-api and effects-api, are published to Maven Central. Platform jars are not.

  • For addon developers. New rtp-api surfaces for actions, claim boundaries (ClaimBoundaryProvider), web editor extensions (EditorExtensionRegistry, ADR-107; tabs are built from the editor's own widgets, so no addon code runs in the browser, and no bundled addon uses them yet), and extra region-file formats (RegionFormatRegistry, ADR-077; RTP itself reads only Anvil .mca and loads other formats such as .linear asynchronously).

Changed

  • RTP is now MIT-licensed in full (ADR-108). The PolyForm Noncommercial terms on non-core source (ADR-061) are withdrawn. Free and Pro jars are both MIT; Pro is a support tier and grants no extra licence. Earlier releases keep the licence they shipped with.

  • Location queues renamed to hot, cold and backlog (ADR-078). The L1/L2/L3 names in /rtp info and the docs now say what each queue holds. Queues always release the chunks of locations they drop.

  • Background search loads far fewer chunks (ADR-110). Filling the location queues first checks chunks that are already loaded or saved on disk. Only locations held ready for teleport get their surrounding view-distance area preloaded. Other spots load just the landing chunk and its safety neighbours, so the cache still fills on fresh, unexplored worlds. Those chunks are checked as they load and RTP doesn't keep them loaded. Fill pauses while the server is short on memory.

  • The backlog queue never loads chunks and feeds the cold queue (ADR-028). Backlog picks the region-file pre-check accepts move into the cold queue with no chunk load. Picks it cannot read from disk, such as ungenerated land, are checked one at a time by the background search instead of being passed on unchecked. Backlog picks fill within each pulse's time budget (asyncAllottedTime, keeping 20% spare for other work). The backlog count in /rtp info shows only locations the region-file pre-check accepted; rejected picks are dropped straight away.

  • Queued locations are fully checked before a player gets one (S-001, S-003). When a cold location is promoted to the ready queue, RTP now checks the world border, biome filter, safety radius and claim plugins on the loaded chunk, after finding the landing height. Locations from the backlog or the database used to skip these checks, so a player could land in a claim or a filtered biome.

  • Region-file pre-check tunes itself (ADR-109). RTP measures, per region, whether reading candidates straight from region files saves time and turns the pre-check on or off accordingly. Nothing to configure.

  • Faster region-file access (ADR-016). Checks against the same region file are batched so each file is opened once instead of once per chunk, read buffers are reused, and save detection no longer hits the file system on every lookup.

  • Paper picks sync or async teleport per teleport (ADR-005). Teleports to an already-loaded chunk happen immediately; all others load the chunk off the main thread first. Set teleportPath: ASYNC in advanced/performance.yml to always use async.

  • Less main-thread work per teleport on Paper, Spigot and Folia. Block-name lookups are cached and the arrival-schematic check no longer touches the disk on every teleport.

  • Tidier shipped config files. Comments are clearly attached to their settings and stay attached when RTP rewrites a file (ADR-042), and long comments that cluttered menu tooltips are shortened.

  • REROLL is the default selection mode. CIRCLE, SQUARE, ELLIPSE and RECTANGLE, and the shipped config.yml in every language, now use mode: REROLL: no spot repeats until the shuffle has cycled and back-to-back spacing stays exact, at the cost of one in-memory check per known-bad chunk. ACCUMULATE stays available for regions that need every draw to be a guaranteed O(1). Regions that set mode keep their value.

  • All memory shapes share one selection routine. Shapes had drifted apart in how they handle bad land, mode and uniqueplacements (see Fixed); they now behave consistently.

  • ELLIPSE turns off expand: true with a one-time warning, as POLYGON already did. Expanding pushed picks outside the ellipse, where they were rejected.

  • bStats on every platform, without a bundled bStats library. Fabric and NeoForge now report too. RTP uses its own small, dependency-free client (bstats-api-ADR-001), keeping the same data, opt-out and server ID on Paper, Spigot and Folia.

  • RTP leaves more of each tick to the server and other plugins. syncAllottedTime now defaults to 5 ms and asyncAllottedTime to 25 ms, and both are capped at 25 ms. Queued commands, scripted actions and promotion checks for ready-queue locations now count against syncAllottedTime, and RTP starts at most 8 chunk loads per region per refill. On Fabric and NeoForge, RTP's end-of-tick work stops at syncAllottedTime and background work uses at most half the CPU cores. period now means ticks between refills of the same region.

  • minTPS now pauses background cache filling, and the new maxMSPT setting (default 45 ms) pauses it when ticks run long even though TPS still reads 20. Players already waiting are still served. On Folia the server-wide pause uses the mean TPS across regions, and a slow region is handled on its own: RTP runs one background task per tick there and fills from other regions instead.

  • Folia divides RTP's work across region threads instead of stacking it on one. Under heavy /rtp load one region could fall to about 1.4 TPS while the mean stayed near 19 (ADR-112).

  • Location checks, retries, claim checks and teleport setup that followed a chunk load now continue on async workers instead of the region thread that loaded the chunk.
  • RTP's work for each region runs in order, within syncAllottedTime per region thread; anything left waits behind other regions until that region's next tick.
  • Regions that are slow or backed up get one RTP task per tick, and the ready queue fills from other regions meanwhile.
  • The limit on concurrent region tasks applies to every kind of region task, and work waiting for a slot runs in order instead of polling.
  • Folia task queues now always run at least one task per pulse and stop inline work once their time budget is spent. Cold-cache refill per region turn is no longer limited to two tasks.

  • For addon developers. rtp-api, rtp-core and the shared API modules they pull in (commands-api, effects-api, maps-api, metrics-api, anvil-api, yaml-api, bstats-api) are compiled to Java 17 bytecode (ADR-113), so addons that build against them can target Java 17. The bundled addons are Java 17 too.

Deprecated

Removed

  • Party and tether addons. LeafRTPPartyAddon and LeafRTPTetherAddon are no longer built. For group teleports, use the action addon's teams and scatter modes.

  • For addon developers. The Bukkit-only classes in commands-api (BukkitCommand, BukkitCommandRegistrar, BukkitParameter, StringCommandDispatcher, BukkitTreeCommand and the LocalParameters package) and its plugin.yml are removed; use the platform-neutral commandsapi.common and commandsapi.brigadier packages. The Bukkit command classes and plugin.yml in effects-api are removed too. The Fabric effect classes in io.github.dailystruggle.effectsapi.fabric moved out of effects-api to io.github.dailystruggle.rtp.fabric.effects in the Fabric adapter, so effects-api no longer needs a Minecraft or Fabric classpath.

Fixed

  • RTP could freeze Fabric 1.20.1 and 1.21.1 servers and run them out of memory. Each chunk load added a chunk ticket that kept a large area around the candidate loaded and was never released, so the server kept generating chunks, partly on the main thread. Loaded chunks were also read as missing, so no locations were found there. Tickets now cover only the area RTP needs and are released after use, and chunks load off the main thread.

  • On Fabric 1.21.5 through 1.21.11, RTP read every chunk it loaded as missing and could release a cached location's chunk early. Chunk results are now read correctly, and the temporary load ticket no longer removes the ticket that keeps a cached location loaded. Chunk loads now always use the non-blocking path, so they can't stall the main thread.

  • Arriving players could trigger a main-thread chunk load. On servers that unload chunks immediately, the landing chunk could unload just before the player arrived. It now stays loaded briefly after a teleport.

  • Background safety checks read whole region files to inspect one chunk. They now read only that chunk, cutting CPU and memory churn on pregenerated worlds.

  • Teleports could stall under heavy load because config reads contended on a shared lock (ADR-094). Reads are now lock-free and reloads switch over in one step.

  • uniquePlacements could use up a region with expand: false within seconds of startup. It now applies only when expand: true.

  • Reserving chunks around a destination could load them on the main thread on Bukkit, Spigot and Paper. They are now loaded in the background first.

  • Claim protection switched itself off after a single error, so players could land in protected land until a restart. An error now rejects only that one location, and the integration stays active. WorldGuard regions also block landings when RTP's custom flag couldn't be registered.

  • Cross-server /rtp requests could vanish with multiple proxies sharing a Redis queue, or after a Redis hiccup. Requests are now handed to the proxy that holds the player.

  • Some region-file chunks always fell back to a full chunk load. The last chunk of a file that the server hadn't closed yet was treated as unreadable.

  • MySQL and PostgreSQL storage stopped saving after a few minutes because database connections were never returned to the pool.

  • Worlds using region-file-compression=lz4 never got the region-file safety check.

  • /rtp scan rejected generated land on Minecraft 26.3 and never finished half-generated chunks. RTP now reads 26.3's block format from region files. Chunks the server saved mid-generation are loaded so the server can finish them, instead of being marked bad.

  • lz4-java is no longer bundled. LZ4 region chunks are decoded by RTP's own bounds-checked code, which closes CVE-2025-12183 and CVE-2026-59949 and makes the jar smaller.

  • Corrupt or crafted region chunks could crash the safety check or force huge memory use. Such chunks are now loaded normally instead.

  • The scan land percentage was wrong during scans, and the scan boss bar showed progress in its place. Progress is now [scan_progress].

  • MSPT on Fabric and NeoForge was stuck at 50 ms or higher. It measured the time between ticks, which includes the server's idle sleep, instead of the time spent in a tick. This also made RTP throttle itself as if the server were overloaded. Expect much lower readings in /rtp info.

  • Shape mode and uniqueplacements inconsistencies. mode values are case-insensitive, NEAREST mode no longer returns known-bad locations or ignores uniqueplacements on CIRCLE and ELLIPSE, SQUARE_NORMAL reads uniqueplacements as a radius, and regions using uniqueplacements no longer slow down as RTP learns more bad land.

  • The JUMP vertical adjustor discarded whole chunks after a miss in a single column.

  • Players who left stayed in memory through their teleport history and boss bars. RTP now keeps only their ID and the data cooldowns need.

  • Fabric on Minecraft 26.x left live chunk loads out of /rtp info, skipped the top block row, and held chunks the server had unloaded. Live loads are now counted, the height limit includes the top block, and RTP's chunk cache is bounded instead of keeping every chunk it loaded.

  • Repeated hex colors showed a stray & on servers without Adventure.

  • syncAllottedTime and asyncAllottedTime above 25 were silently capped, and the high-performance and arena presets wrote 50. The cap is now documented, and the presets use values within it.

  • period refilled each region one tick early (every 19 ticks at period: 20).

  • Background area scans could stall a tick thread while waiting for claim plugins to answer.

  • Fabric and NeoForge could start an unlimited number of background threads, and a slow repeating task could run several copies at once.

  • On Folia, delayed tasks ran immediately, cancelled tasks still ran, and one failing task skipped the rest of that tick's queue. Chunk tickets were also changed on the wrong thread. With spark installed, RTP also lost its own TPS readings.

  • /rtp scan progress lines showed a speed and ETA that jumped wildly between updates (for example 150 cps, then 3,000 cps). They now show the average since the previous progress line.

  • /rtp scan stalled for seconds at a time on large pregenerated worlds. RTP re-checked the region file format by listing the whole region folder every 10 seconds; it now detects the format once.

  • /rtp scan on circle regions checked chunks outside the circle, and generated them on fresh worlds. These are the corners of the square area the scan walks. It now skips them without recording them, so they no longer count toward land % or toward the learned bad area that expand uses.

  • On Paper and Folia 26.1 or newer, /rtp scan and the background search did not recognize pregenerated land and loaded every chunk through the server, which put heavy load on the scheduler. RTP looked for region files in the old folder layout; it now also reads the new world/dimensions/<namespace>/<name>/region/ layout.

  • The free jar declares the same permissions as the Pro jar. Its plugin.yml lacked rtp.version, rtp.biome, rtp.menu.admin, rtp.personalqueue and the rtp.onevent.* nodes, so /rtp version was op-only and no auto-RTP event permission was declared.

Security

Network mode upgrade note. Upgrade every backend and proxy together: network messages and shared-store records now use a new signed format that older builds can't read. Tokens, queue entries and Redis waitlist entries in the old format are rejected, not migrated, so players waiting in a Redis waitlist from an older build need to run the command again. Network mode now requires a Base64 RTP_NET_SECRET of at least 32 bytes; plugin-message, proxy-cache and auto can instead run unsigned with network.allowUnsigned: true in advanced/network.yml.

  • More network traffic and shared records are signed. Proxy-cache replies, request queues and Redis waitlists are now signed with the network secret too, as Redis heartbeats and reservation tokens already were, all in a new record format, so a modded client or anyone with store access can't inject fake servers, regions or requests. Tampered entries are dropped with a warning.

  • One cross-server request at a time per player. A proxy ignores a new request from a player while their previous one is still being handled.

  • Proxy-direct link hardening. All requests are signed, the listener binds to 127.0.0.1 by default, and new settings add an IP allowlist (allowedClients) and TLS with optional client certificates. Connection counts are capped.

  • Redis connection options. TLS, ACL usernames (rediss://user@host) and passwords from environment variables (passwordEnv). A password left in YAML logs a warning.

  • Hardened Redis replies. Oversized or deeply nested Redis replies are rejected.

  • RTPAPI.teleport now checks destination permissions, so menus and addons can't send players to worlds, biomes, regions or servers they lack permission for. Returns NO_PERMISSION; addons that relied on bypassing this must grant the permission themselves.

  • reg: command patterns are capped at 256 characters, so a crafted pattern from the console or API can't stall the server.


3.2.1 - 2026-08-15

Added

  • In-game config editor now shows a picker for fixed-value settings. Settings that only accept a set of valid values (such as database.type, or the region shape/vert types) used to open a blank text box where a typo silently reverted the value to its default. The editor now shows a list of the valid options with the current one marked; free-text keys are unchanged.

  • Teleport view-distance clamp for smoother arrivals. RTP can now briefly reduce a player's view distance just before a teleport and then raise it back one step at a time, spreading out the chunk-loading work so weaker servers don't stutter when a player arrives. Configurable via the new viewDistanceRestoreInterval key in performance.yml (default 200 ticks / 10s; set 0 to disable). Supported on Bukkit/Paper/Folia; other platforms ignore it.

Changed

  • config.yml is now purely teleport behavior. The database settings moved to a new database.yml, and the redundant network.redis block was removed (use the Redis transport settings in network.yml instead). Values you customized in the old locations are not migrated automatically - re-set the database in database.yml and Redis in network.yml. The config.yml version was bumped to 3.1.

  • The plugins/RTP/ folder was reorganized into a cleaner, tiered layout, and messages.yml split into modular category files. The everyday files (config.yml, economy.yml, language.yml, safety.yml) stay at the top level. The definitions you author (regions, worlds, effects, plus the shared shape/vert catalogs) now live under a single definitions/ folder, and the rarely-edited prefab schematics moved under advanced/. The legacy flat messages.yml was removed in favor of modular category messages under advanced/messages/ (commands.yml, network.yml, placeholders.yml, player.yml, system.yml) with co-located dotfile rename maps across all 13 supported locales, ensuring cleaner structure and faster translation audits. On upgrade RTP relocates your files automatically and never overwrites a file already present at the new location. The keys are unchanged - only their location moved - so no re-tuning is required.

  • Biome-weighting settings moved from advanced/performance.yml to advanced/biomes.yml, so every biome-selection option (whitelist/blacklist plus weighting) lives in one file. Behavior is unchanged. A value you customized in performance.yml is not migrated automatically - re-set it in advanced/biomes.yml.

  • Bundled add-on config files moved into an addons/ subfolder. The Countdown (countdown.yml), GUI menu (guimenu.yml), and claim-integration (integrations.yml) files now live under plugins/RTP/addons/ instead of the root, so the root holds only the core files you edit day to day. An older install's root-level copies are relocated automatically, keeping your changes. The top of config.yml now lists every shipped config file and what it is for.

  • Config files now carry a proper file-level header comment. A leading comment block separated from the first setting by a blank line is now treated as a document header for the file, instead of being folded into the first setting's own comment. This keeps each setting's comment clean for use as menu tooltips. Every shipped config file now uses this layout.

  • RTP-lite now ships the same config.yml, advanced/* tuning files, and operator docs as the full edition, for exact parity. Lite still bundles no database/Redis drivers, so the database:/network: blocks in the shipped config are simply inert.

Fixed

  • Fixed several NeoForge and Fabric chunk-loading problems on newer Minecraft versions. On NeoForge 1.21.x, 26.1, and Fabric on the 26.x runtimes, a /rtp chunk request could freeze the server tick (risking a watchdog crash), fail to generate chunks (spamming INSTANT BYPASS in the console and leaving the teleport cache empty), or fail every attempt outright. These paths now load chunks off the tick thread with a proper temporary ticket, so chunks generate correctly, the console spam stops, and the cache fills as expected.

  • Color codes in config comments now show as literal text in the /rtp config menu hover, instead of being turned into actual colors and swallowed. Comments often document color codes as examples (e.g. "avoid yellow (&e/&6)"), and those now display exactly as written.

  • NeoForge on MC 26.2 no longer crashes when a colored /rtp message is sent (for example, clicking a destination in the GUI). The crash came from relying on a Minecraft method that MC 26.2 removed; color detection no longer depends on it.

  • Teleports triggered through a GUI/menu addon (including the bundled LeafRTPGuiAddon) now apply the economy charge instead of teleporting for free. The /rtp command already charged the teleport price plus any per-region price and refused players who couldn't afford it, but clicking a destination in a menu skipped payment entirely. The teleport price, per-region prices, and the rtp.free bypass now apply on the menu/API path too, and a failed teleport is refunded.

  • Fixed a stray x character appearing before the [RTP] prefix on NeoForge/Fabric when a gradient wraps a nested rainbow (as in the default teleportMessage).

  • Fixed the last character of a gradient message rendering in the start color instead of the end color on NeoForge/Fabric (for example, the trailing s of 38ms in the default teleportMessage).

  • Teleports triggered through a GUI/menu addon are now instant when a location is already cached, matching the /rtp command, instead of always waiting for the next background pulse.


3.2.0 - 2026-06-21

Upgrade note (default behavior change). This release bundles and self-extracts the LeafRTPGuiAddon on first run, and that addon binds the bare /rtp (no arguments) root action (ADR-056). On servers that have a GUI renderer available, a player typing bare /rtp now opens the destination-picker menu instead of teleporting immediately; the classic instant teleport is still reachable via the menu and as a fallback when no renderer is installed or the player is offline. To restore the old behavior, delete the extracted addons/LeafRTPGuiAddon.jar (the addons/ folder then exists, so it is never re-extracted) or unbind the root action. The minor version bump (3.1.x -> 3.2.0) reflects this operator-visible default change to the headline command; the public rtp-api/SPI surface is unchanged.

Added

  • The bundled LeafRTPCountdownAddon now shows its delay and queue countdowns as an on-screen boss-bar instead of chat spam, via a new per-player progress-bar API. RTPPlayer gains two default methods, showProgressBar(id, title, progress) and clearProgressBar(id), that render a personal, single-player boss-bar (distinct from the existing server-wide, permission-scoped RTPServerAccessor.updateProgressBars surface). The Bukkit adapter (BukkitRTPPlayer) implements them over Bukkit BossBars keyed per player and bar id; other platforms inherit a graceful no-op default. The countdown addon drives both the "Teleporting in N..." delay countdown and the "you are #N in the queue" / "you're up!" queue countdown through this API, replacing one bar in place each second rather than flooding chat.

  • Addons can now react when an admin applies a config prefab. A new public rtp-api event surface (RTPAPI.onPrefabApplied(Consumer<PrefabAppliedEvent>), returning an AutoCloseable for unregistration) fires a fire-and-forget, post-apply notification after /rtp admin prefab ... confirm writes the affected config files and reloads. The event carries the prefab id, the applying caller's UUID, the written file ids, a per-file list of PrefabChange (keyPath / oldValue / newValue), and whether the reload succeeded. The dispatcher (PrefabEventDispatcher) mirrors the existing player-lifecycle hook pattern: a CopyOnWriteArrayList of subscribers with per-subscriber exception isolation so one faulty addon cannot break delivery to the others. It is created eagerly, so an addon may subscribe before core finishes loading. Covered by two new PrefabCommandTest cases.

  • Loaded chunks now opportunistically register their biome into every in-range region's spatial memory, and this is on by default. performance.yml#checkOnChunkLoads (now defaulting to true, was false) gates a new on-load harvest: whenever the server loads a chunk for any reason, the chunk's center-column biome is recorded into the MemoryShape of each configured region whose range contains that column, feeding biome recall / biome-weighted selection without any extra chunk I/O. A new always-registered OnChunkLoad listener (Bukkit/Paper/Folia) forwards loaded chunks to SelectionAPI.observeChunkLoad, which reads only already-resident chunk data (S-005 safe) and gates O(1) on the config flag, so the cost when disabled is a single boolean check. Positions inside a region's center-radius hole are skipped (no valid location there). Covered by SelectionAPIObserveChunkLoadTest (3 cases). The new default value is mirrored across every shipped locale.

  • The GUI destination-picker addon now ships inside the RTP jar and demos itself out of the box, and gains a proper /rtp gui command. The LeafRTPGuiAddon multi-loader jar is bundled inside both the Pro and lite RTP jars (under bundled-addons/) and self-extracted into <pluginDir>/addons/ on first run only - when the addons/ folder does not yet exist (AddonRegistry.extractBundledAddons) - so a casual admin gets the flashy chest menu the moment the jar is dropped in, with no second download. Turning it off is just deleting the extracted jar (the folder then exists, so it is never re-extracted) or editing the addon's config. A new /rtp gui subcommand (permission rtp.gui) lives in rtp-core and opens whatever menu an addon bound to the bare /rtp root action (ADR-056), registered on the Bukkit, Fabric, and NeoForge command trees so it works on every platform and however the addon was loaded - replacing the old Bukkit-plugin.yml /rtpgui command, which never appeared when the addon was loaded from the addons/ folder (its JavaPlugin entry point does not run there). The Bukkit chest renderer is now also published via a MenuRenderer META-INF/services descriptor so it registers on the ServiceLoader load path (addons-folder / bundled), where the entry point is skipped. Covered by AddonRegistryTest (2 new cases).

  • The lockAfterUses usage cap now survives a restart, reaching parity with the already-persisted cooldown (ADR-068). The BetterRTP LockAfter rolling-window counter previously lived only in memory and was lost on every reload/restart, so a player at their cap got a fresh allowance whenever the server bounced. A new TeleportLimitStore seam (rtp-core) now fronts the usage-cap guards (/rtp command and the addon-facing RTPAPI.teleport) and the success counter; its LocalTeleportLimitStore write-through-persists each player's {count, start} window to the configured database (the file-backed YamlFileDatabase in the lite assembly, so no driver dependency) and lazily reloads it on first use, hydrating the window on restart. The cooldown anchor is unchanged (it already persists). This is the local-durability axis of ADR-068; the cross-server (proxy/transport) axes are tracked as follow-up work. Covered by TeleportLimitStoreTest (4 cases).

  • The RTP-lite assembly variant now ships the full base safety.yml instead of a trimmed lite-specific copy (ADR-024 2026-06-20 amendment). The lite-specific safety.yml overlay is removed, so lite inherits the base config verbatim - including both the vanilla block-tag grammar (#minecraft:<tag>) and state predicates from ADR-017, which are now sufficiently stable for lite. No driver change was needed (the SafetyTokenParser / SafetyCompilationCache / SafetyTokenExpander already ship in the lite jar); only the rtp-tags module (tags/, tagsRefresh.yml) remains a full-edition feature.

Changed

  • The LINEAR vertical adjustor now defaults to middle-out search (direction=2) in every world, not just the nether/end. World generation changed such that a center-out vertical scan is the better general default, so the global LINEAR default direction moved from 0 (bottom-up) to 2 (middle-out) - the same setting already seeded for _nether/_the_end regions. The dimension-specific direction override is removed from NetherEndConfigAmender (its nether maxY<=128 clamp and requireSkyLight=false seeding are unchanged), since middle-out is now the baseline. Existing region configs that set direction explicitly are unaffected.

  • The shipped default overworld region now uses the LINEAR vertical adjustor with middle-out search (direction: 2) and requires sky light (vert.requireSkyLight: true) so /rtp lands players on open-sky surfaces. regions/default.yml switches vert.name from JUMP (which has no scan-direction concept) to LINEAR with direction: 2, matching the middle-out search already used for nether/end, and flips requireSkyLight from false to true. Nether/end regions created from this default still seed requireSkyLight: false automatically via NetherEndConfigAmender (those dimensions have no sky light), so cross-dimension behavior is unchanged. Existing region configs that set these explicitly are unaffected.

  • Claim-plugin integrations moved out of rtp-plugin into the new bundled LeafRTPClaimAddon (ADR-069, superseding ADR-019). The 12 claim/protection checkers (WorldGuard, GriefDefender, GriefPrevention, Towny Advanced, SaberFactions, FactionsBridge, Lands, RedProtect, Residence, CrashClaim, HuskClaims, KingdomsX), the IntegrationsKeys enum, and integrations.yml left the core plugin for a single Bukkit-only addon module that registers its verifiers through the public hook facade (ADR-026) exactly as before (REQ-RTP-S-003 unchanged) and self-gates on PlatformFamily.BUKKIT. The addon jar is bundled inside both the Pro and lite RTP jars (under bundled-addons/) and self-extracted into <pluginDir>/addons/ on first run, so claim-aware teleport still works out of the box with no extra download. The claim compileOnly dependencies and their dedicated soft-dep Maven repositories are removed from rtp-plugin/build.gradle. Behaviour change for operators: the per-locale integrations.yml translations that previously shipped in the core plugin are dropped (the addon ships an English integrations.yml); re-localizing the addon config is tracked follow-up work.

Fixed

  • requireSkyLight: true no longer lands players inside caves. The live full-load vertical-adjustor path (LinearAdjustor / JumpAdjustor) gated sky access on the chunk's stored sky-light nibble (getSkyLight(y+1) > 7), which is unreliable on freshly-generated or unticked chunks - the server frequently reports a stale full 15 before relighting, so a roofed cave column passed the gate. Both adjustors now derive the gate from block data instead (the same computeColumnSkyFloor approach the anvil probe path already used): a candidate is accepted only when its head cell is strictly above the highest non-air block in that column, so any overhang, cave ceiling, or structure roof rejects it deterministically regardless of stored lighting. Covered by a new LinearAdjustorTest regression case (roofed cave with a stale full sky-light is rejected).

  • The bare /rtp GUI (bound via the ADR-056 root-action hook, e.g. LeafRTPGuiAddon) now opens on Fabric and NeoForge instead of silently running a classic teleport. The root-action consult lived only in the Bukkit String[]-args onCommand path; Fabric (RTPCmdFabricRoot.onCommand) and NeoForge dispatch a bare /rtp straight through RTPCmd.compute(...), which had no root-action check, so a bound GUI never opened on those platforms. The hook is now also evaluated at the head of compute(...) for a bare invocation (no args), mirroring the Bukkit path and releasing the processingPlayers lock when the action handles the command; the Bukkit String[] path still short-circuits before compute(...) when it handles the command, so the action never double-fires. Covered by two new ReqApiF006RootActionTest cases exercising the compute() entry point.

  • Fabric on the deobfuscated MC 26.x runtime no longer crashes with NoClassDefFoundError: net/minecraft/class_3222 the moment a /rtp effect (sound / particle / potion) fires. The common effects resolve the player through HandleRegistry.wrapPlayer, which on Fabric routed to the shared effectsapi.fabric.FabricHandles. That provider lives in the Loom intermediary-remapped :effects-api module, so its bytecode names intermediary aliases (net.minecraft.server.level.ServerPlayer -> class_3222) that exist on a 1.20/1.21 Fabric runtime but not on the deobf 26.x runtime, crashing the server tick thread. The deobf carrier now ships its own Mojmap-native effectsapi.fabric_unobf.FabricHandlesUnobf (compiled with no mappings step, so it names Mojang types directly and absorbs 26.x API drift: (ServerLevel) player.level(), record-shape GameProfile#name() with fallback, the 2-boolean sendParticles overload, reflective/packet teleport), and FabricEffectsInitializer.registerAll() registers it instead of the intermediary FabricHandles. The Bukkit/Paper/Folia and 1.20/1.21 Fabric paths are unchanged.

  • Rebuilt jars now actually pick up changes to the Fabric/NeoForge Mojmap "unobf" carriers (e.g. the FabricHandlesUnobf fix above) instead of silently re-shipping stale carrier bytecode. The unobf carriers are appended into the Loom-remapped jar by the remapJar / remapLiteJar doLast merge step, but those tasks only declared a dependsOn on the carrier jars - the carriers are NOT part of the task's inputFile (which is shadowJar/shadowLiteJar, where the bundled :effects-api / rtp-fabric-common are the intermediary-remapped variants). So a carrier-only source change left the shadow jar's bytes identical, remapJar stayed UP-TO-DATE, its doLast never re-ran, and the shipped jar kept the previously-merged carrier classes. The carrier configurations are now declared as task inputs.files(...), so any carrier change invalidates the remap+merge and the corrected bytecode lands in the jar.

  • Fabric (and NeoForge) effects wiring no longer fails to link with NoClassDefFoundError: org/bukkit/entity/Player. The platform-neutral effectsapi.common.effects.PotionEffect carried a Bukkit/Folia entity-thread dispatch seam in a static lambda whose functional-interface (EntityDispatcher) descriptor named org.bukkit.entity.Player / org.bukkit.plugin.Plugin. Resolving that descriptor forced eager loading of org.bukkit.entity.Player the instant the class was instantiated, so FabricEffectsInitializer.registerAll() (new PotionEffect(...)) threw on Fabric/NeoForge where Bukkit is absent - which also masked the real effects setup and let the obf-carrier fallback surface its own class_7923 link failure. The seam (EntityDispatcher, entityDispatcher, applyOnEntityThread) was moved verbatim to the new Bukkit-only effectsapi.bukkit.BukkitPotionDispatch; the common effect now links on every platform and applies potions through the platform-neutral PlayerHandle#applyPotionEffect. Covered by the relocated FoliaDispatchTest and EffectsApiCommonNoPlatformImportsTest.

  • NeoForge 26.1 server no longer crashes with a 60s ServerWatchdog timeout when /rtp loads a chunk. V26_1_R1NeoForgeVersionAdapter#requestFullChunkAsync reflectively invoked vanilla's public ServerChunkCache#getChunkFuture(..., create=true) on the server tick thread (the live-load path dispatches it via MinecraftServer#execute). On the main thread that public entry point parks the tick thread on mainThreadProcessor.managedBlock(...) until generation finishes - a synchronous main-thread chunk load (S-005) that tripped the watchdog and crashed the server. The reflective resolver now prefers vanilla's non-blocking inner getChunkFutureMainThread (same signature), which returns the pending future without blocking while the chunk system settles it off-thread; create=true still self-issues the generation ticket so the holder reaches FULL status.

  • NeoForge 26.1 no longer floods the console with [ScanTask] INSTANT BYPASS: Chunk manager returned a null chunk and starves the location cache. V26_1_R1NeoForgeVersionAdapter#requestFullChunkAsync invoked vanilla's getChunkFuture(..., create=true) without first applying a load-ticket, so on this runtime the chunk holder never reached FULL status and the future resolved with no ChunkAccess - every full-load scan of an ungenerated chunk bypassed instead of generating, spamming the warning and leaving the kept cache underfilled. The adapter now applies a dedicated, non-persistent (S-002), self-expiring temporary load-ticket around the generation request (added on the tick thread, released on completion), mirroring the 1.21.1 carrier which already did this, so the chunk generates and the bypass flood stops.

  • Fabric on the deobfuscated MC 26.x runtime now generates chunks for /rtp instead of flooding [ScanTask] INSTANT BYPASS: Chunk manager returned a null chunk and starving the cache. The rtp-fabric-v26_1_R1 / rtp-fabric-v26_2_R1 carriers never overrode requestFullChunkAsync, so the unobf chunk path (FabricRTPWorldUnobf.loadLiveChunk) fell through to the throwing getChunkFull stub default and no chunk ever generated. Both carriers now implement requestFullChunkAsync the same way as the NeoForge 26.1 carrier (the same deobf MC 26.x runtime): they apply a dedicated, non-persistent (S-002), self-expiring temporary load-ticket via the typed ServerChunkCache#addTicketWithRadius / #removeTicketWithRadius pair, then invoke the public getChunkFuture(..., create=true) off the server tick thread so vanilla takes its non-blocking supplyAsync(mainThreadProcessor) branch and the normal tick pumps generation to completion - the chunk reaches FULL status, the bypass flood stops, and the kept cache fills.

  • Fabric on the deobfuscated MC 26.x runtime now actually generates chunks for /rtp (every attempt was failing with nullChunk/asyncLoadNull). The runtime world is not the common FabricRTPWorld / FabricRTPWorldUnobf but the per-version V26_1_R1FabricRTPWorld / V26_2_R1FabricRTPWorld (constructed via FabricVersionAdapter#createWorld), which carry their own getChunkAt. That path invoked the public getChunkFuture(..., create=true) on the server tick thread with no load-ticket, so on the deobf MC 26.x chunk system the future resolved with no ChunkAccess and every attempt was attributed nullChunk/asyncLoadNull. Both per-version worlds now mirror the NeoForge 26.1 fix: a dedicated, non-persistent (S-002), self-expiring temporary load-ticket is applied on the tick thread, the public getChunkFuture is invoked off the tick thread (where vanilla takes its non-blocking supplyAsync(mainThreadProcessor) branch), and the method resolver prefers the public getChunkFuture over the inner getChunkFutureMainThread so the off-thread self-pump branch is taken. The temporary ticket is released once the generation future settles.

  • NeoForge 26.1 no longer spams NoSuchMethodError every tick while rendering a /rtp scan progress bar. NeoForgeProgressBars (in the version-agnostic rtp-neoforge-common, typechecked against the MC 1.21.x mappings) hard-linked the ServerBossEvent(Component, BossBarColor, BossBarOverlay) constructor, whose signature drifted on MC 26.1, so every progress-bar update threw NoSuchMethodError from the scheduler tick. The construction site now resolves a matching public ServerBossEvent constructor by reflection once (cached), accepting any shape that exposes a Component, BossBarColor and BossBarOverlay parameter and filling any extra parameters with sensible defaults (a fresh UUID per bar, 0f, false, or null); if no usable constructor exists the bar is skipped rather than crashing the tick.

  • Fabric on the deobfuscated MC 26.x runtime now reports its server version and its block list instead of throwing NoSuchMethodError: MinecraftServer.method_3827 and NoClassDefFoundError: net/minecraft/class_7923. FabricServerAccessor lives in the Loom intermediary-remapped common module, so its direct MinecraftServer#getServerVersion() call and its BuiltInRegistries.BLOCK walk in materials() compiled to intermediary aliases that do not exist on the deobf 26.x runtime - the version probe threw and materials() threw, disabling block-name validation. getServerVersion() now reads the mapping-neutral FabricLoader minecraft mod-container version (falling back to a reflective Mojang-then-intermediary method probe), and materials() pre-probes which registries class actually resolves, keeping the typed walk for 1.20/1.21 runtimes and taking a reflection-only, cached registry walk on deobf 26.x - the same strategy blockTagSnapshot() already used. The Bukkit/Paper/Folia and 1.20/1.21 Fabric paths are unchanged.

  • Fabric on MC 26.x now reports integer server version 26 instead of 1, so version-gated addons load. FabricServerAccessor.getServerIntVersion() always parsed the second dot-separated component, which is right for the legacy 1.<minor>.<patch> scheme but yields 1 for 26.1.2 - violating the documented contract (21 for 1.21.x, 26 for 26.x) and making isCompatible / isServerVersionAtLeast fail closed for every addon that declares a version floor. The parse now takes the major when it is not 1, otherwise the minor, and tolerates pre-release suffixes such as 26.2-rc-2.

  • Heap pressure now actively reclaims memory instead of only pausing cache fill, so a small-heap server no longer stays parked above maxHeapPercent with the "pausing background cache generation" warning repeating forever. The HeapPressureMonitor gate paused cold->hot promotion under pressure, which stopped the retained set from growing but never shrank it - each kept location pins a chunk via its ChunkReservation, so heap usage stayed pinned at the threshold indefinitely. Region.execute now runs an active shed step while under pressure: it drains a bounded number of kept locations per pulse (shedHotCacheUnderPressure), closes each chunk reservation so the JVM can reclaim the chunk, and returns the bare coordinates to the ticketless cold buffer (unkeptLocations) via the new LockFreeLocationBuffer.offerSilently - both buffers key the same DB row, so the move issues zero writes. A small reserve of hot locations is left intact so waiting players keep being served while the heap recovers. Covered by a new LockFreeLocationBufferTest case.

  • The multi-world prefab now also repoints each world's worlds/<world>.yml at its synthesised region, so the per-world regions are actually used. Applying the multi-world prefab synthesised one regions/<world>.yml per loaded world (cloning regions/default.yml with world: "<world>") but left every worlds/<world>.yml still pointing its region field at the shared default region, so the new per-world regions were inert. PrefabApplier.apply(..., worldNames) now emits a sparse worlds/<world>.yml overlay setting region: "<world>" for each synthesised world (the default-mapped overworld, which keeps the default region, is left untouched), and PrefabApplyCmd seeds each world's authoritative current region from the in-memory RTP.configs world parser (every loaded world has one by definition, even when no worlds/<world>.yml file exists on disk) so the diff reports the true delta (e.g. default to <world>). The merge is idempotent (a world already pointing at its own region yields no diff) and preserves any other keys in the world file. Covered by a new MultiWorldExpanderTest case.

  • The multi-world prefab now repairs the cloned vertical adjustor for nether/end worlds, so /rtp into a synthesised _nether region no longer fails every attempt with vert/no-stand-y. The prefab clones the overworld regions/default template (sky-light-required LINEAR vert reaching the build limit) verbatim into each world; in the nether (solid bedrock ceiling, no sky light) and the end (no sky light) that vert rejects every candidate column, so the teleport burned all 32 attempts and timed out. The repair now runs through the canonical NetherEndConfigAmender (the same helper /rtp config region uses) at apply time, reading the live regions/default vert as the template and the destination world's real height bounds: it drops requireSkyLight for both *_nether and *_the_end and clamps maxY below the nether ceiling. MultiWorldExpander stays a pure transform and accepts the repair as an injected RegionOverlayAmender, so the dimension rules have a single definition and the apply preview diff already reflects the repaired vert (overworld and unrecognised worlds are untouched). Covered by new MultiWorldExpanderTest and PrefabCommandTest cases.

  • Prefab config writes now go through the live config system (rtp.configs) instead of bespoke disk IO, and ConfigParser.save() gained automatic .bak rotation. Backup write/rotate/restore/prune logic was extracted into a shared ConfigBackups helper; ConfigParser.save() now snapshots the current file as a rotating <name>.bak.<ts> sibling before overwriting (retention via the new ConfigParser.bakRetention, best-effort so a backup failure never blocks the save). PrefabConfirmCmd writes each file through the matching live ConfigParser (set on the cached config + save()), creating brand-new per-world region files via the same region-creation path the config command uses (MultiConfigParser.addParser, which clones regions/default.yml with its comments). The previous bespoke PrefabDiskIO.writeWithBackup path (and its comment-template seeding overload) is retained only as a fallback when the live config system is unavailable. This also fixes the prior loss of regions/default.yml comments in synthesised per-world region files. Covered by the existing PrefabDiskIOTest/PrefabCommandTest suites plus the configuration tests.

  • Fabric on a late 1.21.x runtime (e.g. 1.21.11) no longer crashes the server tick with NoSuchMethodError on ServerLevel.sendParticles the moment a /rtp particle effect fires. The intermediary-remapped obf carrier effectsapi.fabric.FabricHandles.PlayerWrapper.spawnParticle hard-linked the single-boolean sendParticles(ServerPlayer, ParticleOptions, boolean, double, double, double, int, double, double, double, double) overload, which exists on 1.20.x/early 1.21.x but was replaced on later 1.21.x by a two-boolean (longDistance, overrideLimiter) overload, so the older descriptor failed to link at runtime and crashed the tick thread. The carrier now tries the single-boolean overload first and, on NoSuchMethodError, falls back to the two-boolean overload located reflectively by its parameter shape (a name lookup is unreliable because Loom remaps the Mojmap name to its intermediary alias). The deobf MC 26.x carrier (FabricHandlesUnobf) already used the two-boolean overload and is unchanged.


3.1.3 - 2026-06-18

Added

  • MiniMessage markup is now supported anywhere color codes are, including gradients on pure Spigot. Bukkit-family messages sent through SendMessage (including hover/click menu fragments) now accept MiniMessage <tag> markup - named colors, <#rrggbb> hex, gradients, decorations, <hover:...> / <click:...> - on top of the existing & and #rrggbb codes. On Paper/Folia (and forks that bundle Adventure) the full MiniMessage path renders all tags. On pure Spigot (no Adventure on the classpath), <gradient:...>, <rainbow>, and <transition:...> tags are now expanded to per-character legacy section x hex codes by the new GradientExpander pre-pass, so gradient text renders correctly with no new dependencies shaded in; other MiniMessage tags (hover, click, decorations) are left as-is and stripped by the legacy pipeline. Any render failure falls back transparently so nothing breaks. Isolated in MiniMessageRenderer (Paper/Folia) and GradientExpander (Spigot fallback), probed at runtime by SendMessage.

  • bStats charts for RTP's per-teleport cost to the server (rtp_sync_cost_per_rtp / rtp_async_cost_per_rtp). Two new fleet charts report the wall-clock time RTP itself costs the host per teleport served, split into the main-thread/region ("sync") and asynchronous ("async") families - unlike server MSPT, every nanosecond counted is RTP's own work. Each is a DrilldownPie of cost components (outer slice) with a bucketised ms-per-RTP inner slice: scheduler (RTP's scheduler cost, on both charts) plus chunk_generated / chunk_ungenerated (loading already-generated vs ungenerated chunks), folded into whichever chart matches how this backend loads chunks. So the components sum to the per-RTP cost an operator should expect, and the split shows that RTP-ing into ungenerated terrain (generation) is the expensive part - removable by pre-generating the world. Values are always bucketised (<0.1 ... 50+ ms; unknown until sampled), never raw timings or counts, so no server can be fingerprinted; the profiling decorator just adds one System.nanoTime() pair per task. Covered by ProfilingRTPSchedulerTest (3) and BStatsChartIdsAntiFingerprintingTest.

  • bStats chart for the chunk-load floor, split generated vs ungenerated (chunk_load_floor_ms). A new fleet chart reports the smallest single-chunk load time RTP has observed on a server - the running minimum (the sample least polluted by queue contention), taken as the practical floor since RTP cannot see the instant the platform actually begins a load. It is driven by a new ChunkLoadProfile fed only from the genuine live-load paths (BukkitRTPWorld.loadChunkFuture, FoliaRTPWorld.loadLiveChunk), which classify each load as generated vs ungenerated before it runs (the anvil-prefilter short-circuit and already-resident chunks are excluded so they cannot peg the floor at ~0). The DrilldownPie outer slice encodes how the backend loads (sync/async) and whether the chunk was already generated (e.g. async/generated, async/ungenerated); the inner slice is the bucketised floor (<0.1 ... 50+ ms; unknown until recorded). Both levels are categorical, so no raw timing is emitted. Covered by ChunkLoadProfileTest (5) and BStatsChartIdsAntiFingerprintingTest.

  • SaberFactions and FactionsBridge claim integrations added. Two new bundled claim verifiers (ADR-019) reroll teleports that land inside faction land: SaberFactionsChecker (the maintained FactionsUUID fork) and FactionsBridgeChecker (the FactionsBridge layer that fronts many forks - FactionsUUID, SaberFactions, FactionsX, KingdomsX, ...). Both resolve their API reflectively, so they add no compile-only dependency and no-op when the plugin is absent. New rerollSaberFactions / rerollFactionsBridge toggles (default false, mirrored across every locale), the FactionsBridge soft-depend (full and lite), and a metrics chart entry.

  • Residence, CrashClaim, HuskClaims, and KingdomsX claim integrations added. Four more bundled claim verifiers (ADR-019) reroll teleports that land inside a protected claim: ResidenceChecker, CrashClaimChecker, HuskClaimsChecker, and KingdomsXChecker. All four resolve their API reflectively, so they add no compile-only dependency and no-op when the plugin is absent; a coordinate is rejected only when a claim actually covers it. New rerollResidence / rerollCrashClaim / rerollHuskClaims / rerollKingdomsX toggles (default false, mirrored across every locale), the matching plugin.yml soft-depends (full and lite), and metrics chart entries.

  • Addon-facing teleport API gained cross-server targets, a queued outcome, and richer destination status. The public rtp-api teleport surface (RTPAPI.teleport(UUID, RtpTarget)) was extended for network mode and picker menus, with no change to existing callers:

  • RtpTarget gains Kind.NETWORK + a network(serverId, regionName) factory and serverId(), so an addon can target a region on a specific peer backend (routed across the cross-server wait queue, same path as /rtp region=<server>:<region>).
  • RTPResult gains a QUEUED reason (queued(message) / isQueued()) for the accepted-but-transferred outcome (its location() is null - the destination resolves on the remote backend), plus failure reasons ALREADY_TELEPORTING, COOLDOWN, LOCKED, RELOADING mirroring the /rtp command guards.
  • RtpTargetStatus gains optional, nullable display hints iconBlock(), environment(), label() so a picker can decorate a destination whose block/environment/display name cannot be resolved locally. A local region's label() comes from a new regions.yml#displayName key.

The upshot: an addon can deliver a whole network-mode catalog to players. RTPAPI.getAllowedTargets(UUID) surfaces the player's permission-gated cross-server (Kind.NETWORK) destinations alongside local regions, and RTPAPI.getTargetStatus(...) returns the display hints carried over the network for them - so an addon can list and decorate targets living on other servers without resolving anything locally. The bundled LeafRTPGuiAddon picker is the worked example: it builds its menu purely from getAllowedTargets / getTargetStatus and submits via teleport(...) (getting QUEUED for a cross-server hand-off), presenting local and network destinations identically.

  • /rtp menu now has a world picker row (ADR-065). FrontPageBuilder adds a world row beside the region and biome rows (shown only when the player has the world permission and there are worlds to pick), opening the world picker and tinted like the biome rows. Labeled by a new configurable menuFrontPageRowWorld message key (mirrored across every shipped locale).

  • Addon jars can now be dropped into an optional plugins/RTP/addons/ folder (ADR-057). Since addons are no longer Bukkit plugins (they carry no plugin.yml, only a META-INF/services RTPAddon descriptor), placing one in plugins/ made the server's plugin loader abort startup with Directory '...jar' does not contain a paper-plugin.yml or plugin.yml!. RTP now also scans <pluginDir>/addons/ at startup via the new AddonRegistry.discoverFromDirectory(...): each *.jar is loaded in a child URLClassLoader (parent = RTP's own classloader, so rtp-api/rtp-core types resolve to the running classes) and discovered through ServiceLoader. The folder is optional - a missing or empty one is a silent no-op - and the existing classpath/register(...) paths are unchanged. Covered by AddonRegistryTest (2 new cases).

  • MiniMessage markup in console log lines now renders instead of printing raw tags. SendMessage.log(...) resolved only legacy &/hex codes and then emitted to the console via TextComponent.fromLegacyText, which left MiniMessage <tag> markup untouched - so the default <rainbow>[RTP]</rainbow> prefix (messages.yml P0) printed literally as <rainbow>[RTP]</rainbow> on Paper/Folia 26.2 startup lines (e.g. Successfully loaded N locations). Both log overloads now route the modern console-sender path through a new toConsoleComponents(...) helper that renders the line through MiniMessageRenderer when Adventure is present and the line carries <tag> markup, falling back to TextComponent.fromLegacyText when Adventure is absent or rendering fails; existing legacy &/section-sign color codes still render as before.

  • Action-bar messages now honor MiniMessage <tag> markup. SendMessage.actionbar(...) translated only legacy &/hex codes and emitted via TextComponent.fromLegacyText, so MiniMessage tags (e.g. <rainbow>, <#rrggbb>, gradients) printed literally in the action bar while the chat (sendMessage), title (toLegacyText), announce, and console-log sinks already rendered them. The action-bar path now routes through the shared MiniMessage-aware toComponents(...) renderer, so every player-facing and console message sink honors MiniMessage consistently; existing legacy &/hex configs keep rendering via the legacy fallback inside toComponents.

  • Fabric and NeoForge now honor MiniMessage color/format markup instead of printing raw tags. Those platforms render text through their own FabricLegacyText / NeoForgeLegacyText (and the console *AnsiText) parsers, which understood only legacy &/#rrggbb codes - so a MiniMessage-authored config value (e.g. the default <rainbow>[RTP]</rainbow> prefix, <green>, <#5e4fa2>, <bold>, gradients) printed its literal <tag> markup in chat, titles, action bars, and the console. A new platform-neutral MiniMessageColorExpander (rtp-core) converts MiniMessage color/format tags (named + hex colors, bold/italic/underlined/strikethrough/obfuscated/reset, and gradient/rainbow/transition via the existing GradientExpander) into legacy codes, and is now invoked at the head of every Fabric/NeoForge legacy normaliser. Hover/click and other interactive tags are out of scope (Adventure is not present on these platforms): they are dropped rather than printed. Covered by MiniMessageColorExpanderTest (9 cases).

Fixed

  • Gradients and other MiniMessage tags no longer break when mixed with legacy/hex color codes. MiniMessageRenderer.legacyToMiniMessage rewrote legacy &/section-sign and #rrggbb codes across the whole resolved string before the single MiniMessage.deserialize pass, so the direct-hex rule (optional &/section-sign prefix) also matched the bare #rrggbb color stops inside a MiniMessage tag's arguments - e.g. <gradient:#ff0000:#00ff00> became <gradient:<#ff0000>:<#00ff00>>, a malformed tag that MiniMessage could not parse, so the component silently fell back to the legacy path and rendered wrong. The legacy-to-MiniMessage translation is now tag-aware: the string is segmented on MiniMessage <tag> spans and the three legacy-code passes run only on the plain-text gaps between tags, leaving tag names and arguments verbatim. Placeholder-introduced markup is unaffected (placeholders resolve before this step). Inline color inside a tag argument (e.g. a hover body) is authored with MiniMessage syntax (<hover:show_text:'<red>tip'>). Covered by MiniMessageRendererLegacyTest (6 cases).

  • WorldGuard claim protection is now actually enforced (the can-rtp-select-here flag logic was inverted). WorldGuardChecker.isInClaim read the can-rtp-select-here flag directly, but it defaults to false, so ordinary protected regions tested as "not a claim" and RTP happily landed players inside them (REQ-RTP-S-003 effectively unenforced) - only the rare area where an admin set the flag to ALLOW got rerolled, exactly backwards. Now: wilderness -> accept, inside any region -> reject (rerolled), and can-rtp-select-here = ALLOW -> accept (explicit opt-in).

  • A throwing synchronous claim/region verifier now fails safe (rejects the location) instead of being silently accepted (REQ-RTP-S-004). GlobalRegionVerifiers.checkGlobalRegionVerifiers logged a throwing synchronous verifier at WARNING and then continued, so a verifier blowing up (e.g. a third-party claim plugin's API breaking) was treated as a pass and the location accepted - contradicting both the EXTERNAL_HOOKS.md contract and the async path, which already failed safe. The sync path now rejects on a throwable too. The bundled claim *Checkers hid this (they catch internally and return false); the gap only hit third-party synchronous verifiers. Covered by ReqRtpS004VerifierFailSafeTest.

  • /rtp region:<r> world:<w> now duplicates region <r> and adjusts it for world <w> (the world sub-parameter was previously a no-op) (ADR-065). RTPCmd builds a "world-override" region (region <r>'s settings with world set to <w> and shape re-resolved for it), names it <baseRegion>_<world> (e.g. default_nether), and caches it in the existing SelectionAPI.tempRegions map - reusing the temp-region reload/flush lifecycle with no new bookkeeping. Top-level /rtp world:<w> is intentionally NOT overridden: it resolves its region from world <w>'s own configuration (WorldKeys.region) and honors that redirect, so a world configured to use region default teleports to region default as configured. The override is gated by RTPCmd.shouldApplyWorldOverride(...) (applies only when both region and world are present). No new permissions: the existing rtp.world/rtp.params + rtp.worlds.<name> gates still apply and the override only runs for a value that already passed the relevance check, so it cannot widen access. Covered by RTPCmdWorldOverrideGateTest and ReqRtpAdr065WorldRegionTeleportTrapTest.

  • /rtp region:<r> world:<w> into a nether/end world now seeds a dimension-appropriate vertical adjustor instead of inheriting the overworld vert (ADR-065). The world-override region synthesized by SelectionAPI.worldRegion (e.g. default_world_nether) copied the base region's vert verbatim, so a teleport into _nether/_the_end used the overworld's sky-light-required upward search rather than the dimension-tuned vert every other region-creation path applies via NetherEndConfigAmender when the vert is unspecified. worldRegion now seeds a LINEAR, downward (direction=2), no-sky-light vert clamped to the dimension (nether capped at y=128) for _nether/_the_end target worlds, leaving overworld-style worlds unchanged. Covered by SelectionAPIWorldRegionTest.

  • Background cache fill now backs off under heap pressure, so a small-heap server no longer slowly GC-thrashes into a hang. Previously the location caches refilled on every async pulse with no ceiling, and each kept location pins a chunk ticket; on a small heap the retained set grew until the JVM spent all its time in GC and the server appeared frozen (unresponsive, no console error). The new HeapPressureMonitor (rtp-core) pauses background generation while heap use is over a threshold, but keeps serving already-cached locations to waiting players. Threshold: performance.yml#maxHeapPercent (percent of max heap, default 85; <=0 or >=100 disables it). Heap sampling is cached briefly, so the per-pulse check is effectively free.

  • The /rtp menu region and world pickers are now a clean, map-colored destination list (ADR-065). Previously both pickers deferred entirely to the generic command-parameter reflector (CommandTreeMenuBuilder.buildParamPicker), which appended a free-form "type a custom value..." anvil/chat row and left region rows an undifferentiated dark green. Because region and world are closed, enumerable destination sets, that fallback row only invited invalid input and cluttered the page, so it is now omitted for those two pickers (every other parameter keeps it). Region rows are also tinted by the aggregate of the colors that would appear on that region's map (the observation-count-weighted average of its observed biomes, parchment-clamped) via the new MenuColor.regionColorPrefix / BiomeMenuSource.biomeWeightsForRegion, matching how world rows are already colored. Covered by PickerCleanListTest (2).

Changed

  • MC 26.2 Fabric adapter re-pinned from the pre-release to the 26.2 final release (rtp-fabric-ADR-014). The rtp-fabric-v26_2_R1 carrier now pins minecraftVersion = 26.2 (was the 26.2-rc-2 release candidate; loader 0.19.2 and fabric-api 0.150.2+26.2 unchanged), and the carrier builds cleanly against the final game artifacts. RTPFabricMod#adapterFqnFor already dispatches the 26.2 line via startsWith("26.2"), so no dispatch change was needed. NeoForge has no 26.2 carrier yet (its startsWith("26.") matcher would load the 26.1 adapter on a 26.2 server); a dedicated rtp-neoforge-v26_2_R1 carrier is a tracked follow-up.

  • Bundled claim-plugin compile-only dependencies refreshed to current releases. The soft-depend artifacts compiled against by the bundled claim integrations (ADR-019) were bumped: WorldGuard 7.0.9 -> 7.0.12 (1.21.x support), Towny 0.97.5.0 -> 0.102.0.13, and Lands 6.22.0 -> 7.19.1 (the LandsAPI repository moved, so the coordinate also changes from com.github.angeschossen:LandsAPI to com.github.IncrediblePlugins:LandsAPI). These are compile-only API bumps with no runtime behaviour change; LandsChecker compiles against the 7.x API using the still-present (now deprecated) LandsIntegration constructor and isClaimed chunk overload. GriefPrevention stays on the maintained legacy 16.x line (the 17.x/18.x rewrite carries breaking API changes the bundled checker does not target), and GriefDefender, WorldEdit, RedProtect, and the PvP/combat-tag artifacts are intentionally left pinned (snapshot APIs or the documented Java-21 bytecode constraint).

Removed

  • Legacy Factions (MassiveCraft 1.6.9.x) claim integration dropped. The bundled FactionsChecker (ADR-019) is removed: it compiled against the unmaintained MC 1.7-1.8-era com.massivecraft:Factions:1.6.9.5-U0.6.9 (no 1.21 release) and its claim test was inverted (rejected wilderness, accepted faction land). Modern Factions coverage is already provided by the new SaberFactionsChecker / FactionsBridgeChecker. FactionsChecker, the rerollFactions toggle, and the compile-only dependency are gone; the Factions plugin.yml soft-depend and metrics chart stay (SaberFactions registers under the same plugin name).

  • HuskTowns claim integration dropped. The bundled HuskTowns verifier (ADR-019) is removed: it compiled against the unmaintained pre-2.x me.william278.husktowns API (current HuskTowns is the rewritten net.william278 line). HuskTownsChecker, the rerollHuskTowns toggle, the plugin.yml soft-depend, the compile-only dependency, and the metrics chart are all gone. Operators still running HuskTowns can register an equivalent check via the public RTPAPI.hooks().verifiers() API.

3.1.2-Lite - 2026-06-13

Added

  • Cross-server /rtp on the DB-free proxy-direct tier, as a drop-in alternative to Redis/SQL for data management (rtp-proxy-ADR-019, refining rtp-proxy-ADR-018). Building on the proxy-direct region discovery (rtp-proxy-ADR-017), a cross-server /rtp <server>:<region> issued on a lobby now moves the player and runs /rtp on the destination backend with no Redis/SQL. proxy-direct is simply "another data-management transport like redis/sql": the proxy's own in-memory NetworkTransport + NetworkRequestQueue are the shared store, and a backend reaches them over the existing player-independent proxy-direct socket via a thin RPC. The wire carries one opcode per backend-invoked SPI method (OP_HEARTBEAT, OP_FLUSH_PENDING, OP_POLL_STATUS, OP_CANCEL, OP_FIND_RESERVATION, OP_REDEEM, OP_LIST_ACTIVE), HMAC-signed when RTP_NET_SECRET is set; proxy-local methods (claim/dequeueReady/reaper) never leave the proxy. As a result enrolment flows through the standard NetworkEnrolmentBuffer -> NetworkRequestQueue.flushPending, the proxy's existing TransportRequestTriggerSource + dispatcher relocate the player via createConnectionRequest, and arrival redeem runs through the standard JoinTriggerSource (findReservation/redeem) - the same code the Redis/SQL tiers use, with no behavioural branch outside the binding factory. ProxyDirectNetworkBinding is now a full RPC NetworkTransport, plus a new ProxyDirectNetworkRequestQueue (rtp-core); the proxy ProxyDirectListener dispatches each RPC onto the proxy's store. Reservation tokens are retained this pass (slimming them is a future cleanup). Covered by ProxyDirectNetworkBindingTest (5) and ProxyDirectListenerTest (2).

  • Per-server /rtp permission gate for networked backends. A qualified cross-server target /rtp <server>:<region> is now gated by rtp.servers.<server> (the destination backend) in addition to the existing rtp.regions.<region> (the region), mirroring the local rtp.regions.x model so operators can allow/deny teleport per backend. Enforced in the RegionParameter validator, which also filters tab-completion, so a forged argument cannot bypass the suggestion filter. rtp.servers.* defaults to op (and is a child of rtp.*) in both the full and lite plugin.yml.

  • proxy-direct network transport: player-independent cross-server region discovery on the DB-free edition (rtp-proxy-ADR-017). A new transport.type: proxy-direct lets a backend open its OWN outbound TCP connection to the proxy companion (configured transport.proxies: [host:port, ...], the same mirrorable list on every backend) and publish its real region list at startup with NO player online, so cross-server /rtp region=<server>:<region> tab-completion converges with zero players on any backend and no per-server operator config - which plugin messaging cannot do (it is gated on a player connection, so a player-empty backend has no proxy connection). The Velocity proxy opens a matching TCP listener (transport.direct.enabled: true, default port 25599) that ingests backend pushes into and serves the merged availability snapshot from the same store the rtp:net plugin-message companion uses; frames are HMAC-SHA-256 signed when network.secretEnv (RTP_NET_SECRET) is set (rtp-proxy-ADR-010), unsigned otherwise. No Redis/SQL required. The backend dial is driven by the existing heartbeat tick (RTP.scheduler, no raw backend thread); the tier is non-durable (region discovery only - durable cross-server reservations still need the SQL/Redis tier). The proxy availability store no longer fabricates an assumed-default region row for a server that has not actually reported. Covered by ProxyDirectNetworkBindingTest (4), ProxyDirectListenerTest (1), and VelocityProxyAvailabilityCacheTest.

  • /rtp info biomes biome-occupancy leaderboard. A new /rtp info subcommand reporting which biomes online players actually spend their time in, ranked by share - useful for world designers gauging where players congregate (distinct from teleport landings, which mirror biome surface area). A new in-memory BiomeActivityTracker (RTP.biomeActivity, rtp-core) accumulates per-biome occupancy; the platform sampler periodically enumerates online players and BiomeActivityTracker.sample(...) dispatches each per-player biome read to that player's owning thread via RTP.scheduler.runTaskForPlayer (Folia-correct: the read lands on the entity's region thread), reporting back through independent per-player futures so one stalled region never blocks the sweep. Wired on the Bukkit/Paper/Folia plugin (~30s sampler pulse); counts are in-memory only and reset on restart/reload, so behaviour is identical in the full and lite editions. Gated by the existing rtp.info permission. New infoBiomeActivityHeader / infoBiomeActivityRow / infoBiomeActivityEmpty message keys mirrored across every shipped locale. Covered by BiomeActivityTrackerTest (3). Fabric/NeoForge samplers are a tracked follow-up.

  • spark profiler is now an optional source for /rtp info TPS/MSPT metrics (metrics-api-ADR-001; ADR-026 soft-hook). When the spark plugin is installed on a Bukkit/Paper/Spigot/Folia backend, RTP now merges spark's richer per-window TPS (1m/5m/15m) and mean MSPT over the native binding, instead of reading only the coarse Server#getTPS() / Server#getAverageTickTime(). spark is a pure soft-dependency reached entirely by reflection (no compile dependency on me.lucko:spark-api); softdepend: [spark] in plugin.yml only constrains load order so the spark API is ready when queried. New SparkMetricsBinding (per-field merge over a native delegate - player count / soft cap / chunk backlog / db latency / Folia regions still come from the native binding) and ReflectiveSparkStats (self-disables permanently on a ClassNotFoundException / NoClassDefFoundError such as a trimmed lite jar, and returns the native value per-getter on a transient pre-init / not-yet-sampled state so the merge self-heals once spark warms up), wired by MetricsBindingDispatcher#wrapWithSparkIfPresent on the Paper, Spigot, and Folia paths. On Folia, spark wraps FoliaMetricsBinding so its real per-tick MSPT is surfaced (Folia's native per-region sampler can only derive MSPT from the inter-tick interval, ~50 ms on a healthy server, so the visualizer / /rtp info previously showed a flat, incorrect MSPT) while the per-region foliaRegions() samples still come from the native binding. Documented in EXTERNAL_HOOKS.md. Covered by SparkMetricsBindingTest (5) and MetricsBindingDispatcherTest.

  • performance.yml#biomeWeights ships the full vanilla biome set pre-listed at the no-op weight 1.0 (ADR-062). The map previously shipped a single plains: 1.0 example; it now enumerates every vanilla overworld/nether/end biome (grouped by dimension) at 1.0, so the knob doubles as an easy-to-edit reference - change a number to bias a biome, set 0.0 to suppress it, or append a modded biome id, without having to know each biome's exact name first. Behaviour is unchanged: an all-1.0 map is identical to the prior default (unlisted biomes already defaulted to weight 1.0), and weighting only takes effect under biomeWeighted: true. When a future Minecraft version adds a biome, append it here to keep the list current. Mirrored across every shipped locale and the rtp-lite assembly.

  • Registry-aware gray-space steering for biome weighting (ADR-062 Phase 3) (ADR-062). The biomeWeighted / biomeWeights draw no longer treats a requested biome that has not yet been scanned as an implicit weight 0, and a rare biome with a single recorded run no longer funnels every weighted teleport onto one coordinate. The weighted recall draw now consults the world's biome registry (RTPServerAccessor.getBiomes(world), resolved once per /rtp in PregenState): a requested biome the world can produce but that recall memory has not recorded stays reachable as "gray space" via bounded-spiral exploration (its biome confirmed by the existing downstream pipeline verification), and only a biome absent from the registry is a true 0. Each recorded biome also defers a run-count-proportional share of its weight to exploration (PregenTask.grayFraction: unrecorded -> fully gray, a single recorded run -> mostly gray, >= GRAY_SPACE_MIN_RUNS distinct runs -> fully recall-steered), and the draw explores with probability equal to the gray-space share of total weight (PregenTask.graySpaceProbability), so a higher configured weight on a thinly-recorded biome defers more to exploration and can never amplify single-run clustering. Forced recall (biomeRecallForced) opts out. Stays bounded and S-005-safe (no synchronous chunk load to discover a biome). A new cost-tiered biome-sampling SPI is scaffolded for a future cheap pre-filter (BiomeSampleCapability enum + default RTPServerAccessor.biomeSampleCapability / sampleBiome methods, currently GENERATE_REQUIRED / null on every platform); the per-version noise-sample fast path remains D-005-gated follow-up work. Covered by BiomeWeightedDrawTest (8 cases).

  • Biome-probability weighting for biome-filtered selection (ADR-062). New performance.yml knob biomeWeighted (default false, requires biomeRecall). When enabled, a biome-filtered /rtp (or background pre-fill) that requests several biomes steers toward each requested biome with equal probability instead of in proportion to how many recorded location runs it occupies, so a rare biome (mushroom fields, cherry grove) is no longer drowned out by a common biome's many runs. The draw operates over the existing Anvil-sourced per-region biome occupancy map (MemoryShape getBiomeKeys/getBiomePrefixSums): a new PregenTask.drawWeightedBiome(...) picks the target biome uniformly among those present in spatial memory, then a run within it weighted by run width (keeping placement spatially uniform inside the chosen biome), then a uniform offset. It stays bounded (a finite weighted pick over a pre-mapped set, no reroll loop, no chunk I/O) and falls back to the legacy uniform-over-runs draw when disabled and to the plain bounded spiral when no occupancy data exists yet. Accuracy footing is the existing Anvil read, so steering stays correct on worlds pregenerated elsewhere or migrated across a Minecraft version (where a noise-map getBiome lookup would land in the wrong biome). A companion biomeWeights map knob lets operators set explicit, non-equal per-biome weights: when biomeWeighted is on and the map is non-empty, the target biome is picked in proportion to the configured weights instead of equally (biomes absent from the map use weight 1.0, 0.0 suppresses a biome, and an all-zero/empty set falls back to the equal-probability pick); the shipped plains: 1.0 entry is a no-op example, and the equal-probability draw is just the all-equal degenerate case. Weights are parsed once per /rtp invocation (PregenState), keeping the hot draw allocation-light. Mirrored across every shipped locale's performance.yml. Covered by BiomeWeightedDrawTest (6 cases).

  • /rtp version (alias /rtp about) descriptive subcommand. A new lightweight subcommand that reports the running RTP plugin version, the platform brand, and the host server version. Unlike /rtp info, it captures no live MetricsSnapshot and reads no runtime counters, so it is a purely descriptive identity readout rather than realtime telemetry. Registered on the Bukkit/Paper/Folia, Fabric, and NeoForge command roots (the alias about resolves to the same command). Gated by a new rtp.version permission (default true, also a child of rtp.*). Covered by VersionCmdTest.

  • Basic Folia support in the free build (ADR-024 2026-06-10 amendment). The free (lite) build now runs on Folia instead of failing to enable: the lite plugin.yml sets folia-supported: true, and a new correctness-first FoliaAwareScheduler (in the lite-bundled rtp-paper-common) routes work through paper-api's regionized scheduler statics (getGlobalRegionScheduler / getRegionScheduler / getAsyncScheduler) and the per-entity scheduler, while BukkitRTPPlayer.setLocation performs the teleport via Entity#teleportAsync (reflectively, since a cross-region sync teleport() throws on Folia; failures are logged per REQ-RTP-S-004). BukkitServerProvider.resolveServerModel prefers the tuned folia_v* adapter when present (Pro) and falls back to the Paper accessor + FoliaAwareScheduler otherwise (lite). The tuned, throughput-optimized rtp-folia adapter remains a (Pro) early-access feature and is still excluded from the lite jar, so no PolyForm-licensed source enters the MIT lite binary (ADR-061).

Fixed

  • /rtp visualization/map charts no longer crash on the free (lite) build running on Folia. Map chart delivery dropped the chart's FILLED_MAP item via World#dropItem on the thread that ran MapDispatch, which on Folia is the global region thread - it does not own the player's region, so Folia threw NullPointerException: ... ServerLevel.getCurrentWorldData() is null and the chart was never delivered. The region-thread hop is now performed once at the call site: MapDispatch.paint dispatches binding.deliverTo(...) through RTP.scheduler.runTask(viewerLocation, ...) (resolved via RTP.serverAccessor.getPlayer(viewer).getLocation()), so on Folia the drop lands on the region thread owning the viewer's chunk and on Paper/Spigot it runs inline on the main thread as before. The platform map bindings (BukkitMapBinding, FoliaMapBinding) no longer reimplement an EntityScheduler hop - deliverTo simply drops on the (now correct) calling thread, and the S-004 failure-to-mapUnavailable path is evaluated inside the scheduled runnable. Covered by MapDispatchTest, BukkitMapBindingTest, and FoliaMapBindingTest.

  • Metrics now install on the free (lite) build running on Folia, so bStats / /rtp info report sampled data instead of UNSAMPLED. On a Folia server the lite jar's MetricsBindingDispatcher.install() tried to load the Pro-only FoliaMetricsBinding (the whole rtp/folia/** adapter is excluded from the MIT lite jar, ADR-061), caught the ClassNotFoundException, and aborted the metrics install with a startup WARNING + stack trace - leaving the binding at NOOP. The dispatcher now resolves each platform binding through a tryInstallBinding(...) helper that returns gracefully (logging at FINE, no stack trace) when a binding class is absent, falling through Folia -> Paper (Bukkit#getTPS works on Folia) -> the raw Bukkit sampler. Lite-on-Folia therefore installs PaperMetricsBinding and metrics work out of the box. Covered by MetricsBindingDispatcherTest.

  • (Pro) Folia TPS/MSPT metrics no longer go UNSAMPLED on an idle server. FoliaMetricsBinding's scalar TPS/MSPT clock was fed only by FoliaRegionProcessor, which runs only while a region has queued /rtp tasks; with no teleport traffic no samples were recorded and the 60s idle-eviction left /rtp info and bStats reporting UNSAMPLED. The binding now also drives a steady, traffic-independent heartbeat sampler scheduled once per server tick on the Folia global region scheduler (RTP.scheduler.runTaskTimer), folded into the scalar aggregation (but not into the per-region foliaRegions() list), and self-terminating on hot-reload/uninstall. Per-region attribution from FoliaRegionProcessor is unchanged. Covered by a new FoliaMetricsBindingTest case.

  • Relative coordinate tokens (/rtp centerx=~ centerz=~) now resolve to the player's position instead of a garbage center. The Bukkit CoordinateParameter advertises the vanilla /spreadplayers-style ~ / -~ tokens in tab-completion, but the per-call shape-override path in RTPCmd.compute parsed override values with Long.parseLong -> Double.parseDouble -> Boolean.valueOf; a ~ value fell through to Boolean.valueOf("~") == false, so centerx/centerz silently became the boolean false (an effective 0 center) rather than the caller's coordinate. A new RTPCmd.resolveRelativeCoordinate(token, base) helper now resolves ~, ~<n> (e.g. ~-50), -~, and -~<n> against the teleporting player's current X/Z before the generic coercion, with absolute (tilde-free) tokens unchanged and a malformed offset falling back to the player's coordinate. Covered by RelativeCoordinateResolutionTest (6 cases).

  • Fabric and NeoForge no longer suggest /rtp subcommands and parameters the caller lacks permission for (commands-api-ADR-001; REQ-API-F-007). The Brigadier bridge's greedy args-slot suggestion provider (BrigadierCommandAdapter.argsSuggestionsFor) emitted every subcommand name and every paramName= key regardless of the caller's permissions, so on the Brigadier-dispatched platforms (Fabric, NeoForge) tab-completion advertised commands the player could not run - diverging from the Bukkit TreeCommand.onTabComplete contract, which filters by permission. The provider now gates both subcommand-literal and paramName= suggestions through BrigadierBridgeContext.permissionCheck() (empty/null permission stays open; a throwing predicate denies and logs, mirroring applyRequires). Sub-command literal nodes were already requirement-gated via requires(...) and filtered out of the client command-tree packet; this closes the dynamic-suggestion leak. Covered by BrigadierSuggestionPermissionTest (4 cases).

Changed

  • Released jars trimmed of dead weight. Both shadowJar (Pro) and shadowLiteJar (lite) now exclude the compile-only IntelliJ annotation classes (org/jetbrains/annotations/**, org/intellij/lang/annotations/**, CLASS retention, no runtime use) and the orphan maven metadata (META-INF/maven/**, pom/properties never read at runtime) that leaked in transitively from shaded dependencies. The Pro jar additionally stops bundling the contributor-facing docs/architecture/** tree (per-attempt pipeline internals, chunk-ticket lifecycle, network model, etc.) - it remains available in the public repository - while the operator-facing docs/admin/** set (Quick Start, Configuration, Commands, Hazards, Runbook, proxies) is unchanged. No code, dependency, or public-API change: shadowJar's minimize() was deliberately not adopted because the heavy shaded libs are reflectively driven (Jedis pub/sub, lz4 variant selection) or relocated into our own namespace and the RTP modules expose an addon-facing API plus descriptor-loaded platform entry points that static reachability analysis cannot see.

  • /rtp info trimmed to stay compact before any metrics are sampled. The live-health block previously printed a wall of n/a rows (TPS, server MSPT, average pipeline latency, the P50..P99 percentile line, and database latency) on servers where no live MetricsBinding had sampled yet. InfoCmd now suppresses each of those rows until its underlying value exists: the TPS and MSPT rows render only once a live sample is recorded, the average-latency and percentile rows render only once at least one teleport pipeline has completed, and the database-latency row renders only once a query has run. The always-available rows (JVM heap, queue depth, pending teleports, generation outcomes) are unchanged. Backed by four new read-only predicates on PlaceholderProvider (hasLiveTps, hasLiveMspt, pipelineSampleCount, hasDatabaseLatency) that read the snapshot sentinels (NaN TPS/MSPT, negative database latency, zero pipeline samples). The admin-only DRM footer was condensed from up to six separate lines into a single DRM: <source> id=<id> nonce=<nonce> line (BuiltByBit builds append bbb=<resourceId>@<timestamp>); the DRM strings stay hardcoded in core rather than moving into the player-editable messages.yml. Covered by InfoCmdTest.

  • Per-batch [TRACE] ScanTask diag line demoted from INFO to FINE. The scan diagnostic split (probeNull / adjustNull / cacheHitLoad / genscan*) had been logged at INFO, printing a line every few seconds to the default console for the full duration of a world scan. It now logs at FINE, so it stays available when an operator raises the log level to debug a scan but no longer spams a normally-configured server. No behaviour change beyond log verbosity.

3.1.2 - 2026-06-10

Added

  • NeoForge menu, written-book modal, maps, metrics, and backend-sampler parity (MULTI_PLATFORM_PLAN.md Phase 4 N2.6; ports of rtp-fabric-ADR-012/-015 and ADR-049). /rtp menu, /rtp config, the admin panel, and the pickers now open on NeoForge: RTPCmdNeoForgeRoot wires MenuWiringSupport.attachTo with a new NeoForgeBookMenuRenderer (translates the MenuModel into a fully-formatted NeoForgeBookSpec and dispatches an interactive written-book modal through a new NeoForgeVersionAdapter.openBookMenu SPI, implemented on the v1_21_R1 carrier via a typed WrittenBookContent + transient-slot ClientboundContainerSetSlotPacket -> ClientboundOpenBookPacket -> slot-revert, falling back to ChatMenuRenderer otherwise) and a NeoForgeChatPromptCallback (TTL-bounded chat-prompt substitute for the Paper anvil GUI, backed by the typed, cancelable NeoForge ServerChatEvent - no reflective proxy, unlike Fabric). Map charts render to a real vanilla filled-map via new NM-free NeoForgeMapBinding + NeoForgeMapCanvas (installed in RTPNeoForgeMod only when the active carrier opts in via supportsMapCharts(); per-viewer state released on disconnect, REQ-RTP-MAP-003). A NeoForgeMetricsBinding (single-region EMA TPS/MSPT sampler) is installed via RTP.metrics.setBinding and ticked from onServerTick, and a NeoForgeBackendStateSampler is installed onto RTP.backendStateSamplerFactory so a network-mode boot can sample live host state. New player capability markers NeoForgeBookOpener / NeoForgeMapSink keep the raw ServerPlayer private to NeoForgeRTPPlayer. Still an opt-in build island (-PincludeNeoforge); the S-00x regression guards (N2.7) and the live network-mode boot / runtime /rtp round-trip remain Phase N2/N3 follow-ups.

  • NeoForge permission resolution (LuckPerms + plugin.yml defaults + ops.json) (rtp-neoforge-ADR-001; MULTI_PLATFORM_PLAN.md Phase 4 Step NF). NeoForgeRTPPlayer#hasPermission now resolves through a three-tier chain ported from Fabric (rtp-fabric-ADR-011): LuckPerms first (when installed), then the plugin.yml default table, then the on-disk ops.json op-level scan - so baseline player nodes (rtp.see, rtp.use) work for non-ops on a vanilla-permissions NeoForge install, rtp.onevent.* stays denied to everyone by default, and explicit LuckPerms grants/denials win. New NeoForgeDefaultPermissions (default table), NeoForgeOnEventPermissions (closed-namespace constants), NeoForgeEffectivePermissionsResolver (the effective-set computation feeding the menu surface, plus a console op-equivalent variant), and LuckPermsNeoForgeEnumerator (a reflective LuckPerms facade - node enumeration plus a cached-data, wildcard-aware tri-state check - with no compile-time dependency on net.luckperms:api, so the chain degrades gracefully when LuckPerms is absent). #getEffectivePermissions (player and console sender) is wired to the resolver. LuckPerms soft-depend recorded in EXTERNAL_HOOKS.md (ADR-026). Still an opt-in build island (-PincludeNeoforge); the runtime /rtp round-trip remains a Phase N2 follow-up.

  • NeoForge /rtp command tree wired (commands-api-ADR-001; MULTI_PLATFORM_PLAN.md Phase 4 Step NG). The NeoForge RegisterCommandsEvent trampoline now registers the full /rtp Brigadier tree via the shared commands-api BrigadierCommandAdapter, replacing the Phase N1 scaffold that logged "not yet wired". New RTPCmdNeoForgeRoot (port of RTPCmdFabricRoot: region + nested world/price/worldborderoverride/shape/vert, plus biome/player/world/toggletargetperms parameters and reload/config/scan/info/clearcache subcommands) and a typed NeoForgeBrigadierSourceBridge (resolves a CommandSourceStack to a player UUID and routes permission checks through RTP.serverAccessor.getSender(uuid).hasPermission(...)). Because NeoForge is Mojmap-at-runtime, no reflective Proxy/intermediary dance is needed (unlike the Fabric registrar): the dispatcher and command source are referenced directly. The /rtp menu surface, the full permission chain, and the runtime /rtp round-trip remain Phase N2 follow-ups; still an opt-in build island (-PincludeNeoforge).

  • NeoForge platform adapter skeleton (ADR-033; rtp-neoforge-ADR-001; MULTI_PLATFORM_PLAN.md Phase 4/N1). First code for NeoForge as an in-scope fifth platform family, a sibling of rtp-fabric under platforms/rtp-neoforge/: a ModDevGradle build (rtp-neoforge-common + the rtp-neoforge-v1_21_R1 carrier), META-INF/neoforge.mods.toml, the @Mod entry point RTPNeoForgeMod (server lifecycle + per-tick scheduler drain + RegisterCommandsEvent trampoline on NeoForge.EVENT_BUS), a complete server-thread NeoForgeScheduler (RTPScheduler port of FabricScheduler; NeoForge is single-main-thread, no Folia regions), and NeoForgeCommandRegistrar / version-adapter scaffolds. The platform-neutral modules (rtp-core, rtp-api, anvil-api, commands-api) are reused unchanged. The NeoForge modules are an opt-in build island (included only via -PincludeNeoforge) so the default build is unaffected; the RTPServerAccessor implementation, command wiring, the S-005 async chunk path, and the /rtp round-trip remain Phase N2 follow-ups (not yet runtime-functional).

  • (Pro) Second NeoForge carrier rtp-neoforge-v26_1_R1 for the Minecraft 26.x line (ADR-033; MULTI_PLATFORM_PLAN.md Phase 4/N1). Extends NeoForge support past the original 1.21.1-only carrier toward Mojang's 2026 26.x line (the next stable modding target replacing 1.21.1). New per-MC carrier pinned to MC 26.1.2 / NeoForge 26.1.2.71 (ModDevGradle 2.0.141). The 26.x line is fully deobfuscated (Mojmap with native parameter names, Parchment removed) and runs on Java 25, so V26_1_R1NeoForgeVersionAdapter is a faithful clone of the 1.21.1 carrier and the module pins a Java 25 toolchain; it is gated under -PexcludeJdk25 (alongside the JDK-25 Fabric carriers), so a JDK-21-only build still produces a 1.21.x-capable NeoForge jar without it. RTPNeoForgeMod#installVersionAdapter routes a 26.* runtime to the new carrier; rtp-plugin merges its Java 25 bytecode into the unified LeafRTP-Pro jar (findProject-guarded). Compiled and linked against the real NeoForge 26.1.2 userdev artifacts (26.1.2.71, JDK 25); the adapter loads cleanly at runtime (Active version adapter: 26.1.2 boot line), so the Mojmap API surface is verified. A live /rtp teleport stall on 26.1.2 (L1 kept-cache stuck at 0, no chunk tickets, and the first teleport never completing) was traced to requestFullChunkAsync adding its own transient load-ticket and then removing it inside a whenComplete that ran off the server thread, wedging the 26.x chunk holder so its FULL-status future never resolved (getOrLoadChunk ... TimeoutException); the carrier now relies on getChunkFuture(..., create=true) self-issuing the transient ticket, matching the proven Fabric 26.1 path (rtp-fabric-ADR-008). Re-pin versions when 26.1/26.2 bumps. The 1.21.x line is unchanged - the existing v1_21_R1 carrier already serves the whole 1.21 line via startsWith("1.21").

  • Region-specific schematic paste now works on Fabric, with a single shared schematic translator across every platform (ADR-058). A schematics/<region>.schem file on a Fabric backend now pastes at the arrival location instead of logging the "no schematic paster is installed (NoOpSchematicPaster)" S-004 fallback on every teleport. The decode/plan and paste orchestration now live once in the platform-neutral WorldBlockSchematicPaster (rtp-api), driven by two RTPWorld primitives (default no-op): setBlocks(List<BlockDelta>) (block-state writes) and restoreBlockEntities(List<PlacedBlockEntity>) (container-inventory restore). The shared Sponge .schem decoder and placement planner produce the block list, and each adapter supplies only the native writes. The deobf MC 26.1/26.2 Fabric world wrappers (V26_1_R1FabricRTPWorld, V26_2_R1FabricRTPWorld) implement setBlocks via the vanilla BlockStateParser + ServerLevel.setBlock on the server thread (S-005-clean, per-block skip auditing per S-004). Bukkit/Paper/Folia were collapsed onto the same single translator: the former BukkitSchematicPaster is removed and its native block-write + container-restore logic moved into a shared BukkitBlockWriter backing BukkitRTPWorld/FoliaRTPWorld's setBlocks/restoreBlockEntities, so no platform carries a bespoke SchematicPaster. Container/block-entity contents restore on Bukkit/Paper/Folia; Fabric stays block-states-only this pass (its restoreBlockEntities is the default no-op). Covered by WorldBlockSchematicPasterTest (2) and BukkitBlockWriterChestTest.

  • Live-updating region biome map during a world scan. The admin region-biomes chart now re-renders ~1 Hz from the region's saved biome data (joining the MSPT sparkline and bad-locations map on the live-refresh path), so an admin can watch the biome map fill in as the scan records biomes without re-issuing the command. ChartSpec.Kind.REGION_BIOMES was added to MapDispatch.LIVE_REFRESH_KINDS; RegionBiomesResolver is pure and re-runnable per tick (no chunk I/O, S-005-clean - it reads only the in-memory persisted biome cache via MemoryShape.biomeAt). Covered by a new MapDispatchTest.regionBiomes_bindsLive case.

  • Biomes row in the admin Visualizations menu. The /rtp admin Visualizations chart-kind picker now lists a "Biomes" row alongside "Bad locations" and "Pipeline health"; clicking it opens the per-region picker and paints the REGION_BIOMES chart. The typed /rtp visualization biomes [region=<name>] leaf and VisualizationDispatch.paintBiomes were already wired - only the menu surface entry (VisualizationsSubmenuBuilder.KIND_ROWS) was previously withheld.

  • Map chart rendering on Fabric (rtp-fabric-ADR-015; MULTI_PLATFORM_PLAN.md Step K). /rtp visualization charts (bad-locations heatmap, region-shape, live sparkline) now render to a real vanilla filled-map on Fabric instead of bottoming out on NoopMapBinding (... no concrete MapBinding installed). The Fabric map binding ships in both the full and the rtp-lite assemblies (REQ-RTP-MAP-004). New platform-neutral FabricMapBinding + FabricMapCanvas (rtp-fabric-common, no net.minecraft.* binding) paint the maps-api logical palette into a 128x128 ARGB buffer and hand it to three new NM-free FabricVersionAdapter seams (renderMapChart / releaseMapChart / supportsMapCharts). Implemented on the MC 26.2 carrier (V26_2_R1FabricVersionAdapter): allocates a MapItemSavedData/MapId per chart, matches each pixel to the nearest vanilla MapColor, pushes a full-canvas ClientboundMapItemDataPacket, and delivers a FILLED_MAP item; live charts refresh at ~1 Hz. Installed in RTPFabricMod only when the active carrier supports it (other MC lines stay on NoopMapBinding with the localized mapBindingMissing message); per-viewer state released on disconnect (REQ-RTP-MAP-003).

  • Written-book menu on the deobf MC 26.x Fabric carriers (rtp-fabric-ADR-012 section 4; book-menu parity for 26.x). Completes the Fabric book-menu un-defer started for 1.21+: V26_1_R1FabricVersionAdapter and V26_2_R1FabricVersionAdapter now implement openBookMenu(Object, FabricBookSpec) with a typed, Mojang-named port of the 1.21.11 carrier (build a WRITTEN_BOOK ItemStack with a WrittenBookContent data component, send a transient hotbar-slot ClientboundContainerSetSlotPacket -> ClientboundOpenBookPacket(MAIN_HAND) -> slot revert, never mutating the server-side inventory). Per-fragment hover/click is built via the version-local V26_*FabricLegacyText.parseInteractive(...) (reflective HoverEvent/ClickEvent record-carrier probing). On the deobf MC line compile mappings equal runtime mappings, so the typed binding links (one 26.x ctor difference handled: WrittenBookContent's title is Filterable<String>, not Filterable<Component>). /rtp menu, /rtp config, the admin panel, and the pickers now open the interactive book modal on 26.x as well, instead of the chat fallback; the renderer still degrades to ChatMenuRenderer on 1.20.x and on any book-dispatch failure.

  • Written-book menu renderer on Fabric (rtp-fabric-ADR-012 section 4 un-defer; MULTI_PLATFORM_PLAN.md Step I Session 3). /rtp menu, /rtp config, the admin panel, and the param/shape/vert pickers now open an interactive written-book modal on 1.21+ Fabric servers, matching the Paper book UX, instead of scrolling past in chat. New platform-neutral FabricBookMenuRenderer (rtp-fabric-common, no net.minecraft.* binding) translates the MenuModel into a fully-formatted FabricBookSpec (placeholders + colour codes via RTPServerAccessor.format; click commands via the shared MenuActionToCommand) and dispatches through a new FabricVersionAdapter.openBookMenu(Object, FabricBookSpec) SPI. The per-carrier overrides (v1_21_R1, v1_21_R5, v1_21_R11) build a WRITTEN_BOOK ItemStack with a WrittenBookContent data component (fragments built by FabricLegacyText.parseInteractive(..., ClickKind.RUN)), send a transient ClientboundContainerSetSlotPacket for the held hotbar slot, send ClientboundOpenBookPacket(MAIN_HAND), then revert the slot, so the server-side inventory is never mutated. The renderer transparently falls back to the existing ChatMenuRenderer on 1.20.x and the deobf 1.26.x carrier (where openBookMenu keeps its default false), when the viewer is offline, or when the book dispatch throws. Wired in RTPCmdFabricRoot in place of the bare ChatMenuRenderer. Covered by FabricBookMenuRendererTest (6 cases). v26_1_R1 book support remains a tracked follow-up.

  • Early/experimental MC 26.2 Fabric adapter (rtp-fabric-ADR-014). New rtp-fabric-v26_2_R1 submodule, cloned from v26_1_R1 (deobfuscated MC line, Loom 1.15 unobf, JDK-25 toolchain), pinned to the 26.2-rc-2 release candidate (loader 0.19.2, fabric-api 0.150.2+26.2). RTPFabricMod#adapterFqnFor dispatches the 26.2 line (startsWith("26.2"), which matches both the pre-release / release-candidate friendly string and eventual 26.2.x finals) to V26_2_R1FabricVersionAdapter; the adapter bytecode is merged into both the full and rtp-lite jars post-remap via a dedicated fabric262Bytecode configuration. JDK-25-gated (!excludeJdk25); the pinned versions and dispatch matcher are to be re-verified when 26.2 ships final.

Fixed

  • NeoForge 26.1 L1 kept-cache stayed empty and /rtp never landed (chunk caches were weak references; wrong chunk-future method resolved; blocking on the tick thread). On the NeoForge 26.1.2 carrier the cold-to-hot (L2-to-L1) promotion in Region.execute loads each candidate chunk, then reads it back via NeoForgeRTPWorld.getCachedChunk to re-run the vertical adjustor before pinning it with a keep-ticket. NeoForgeRTPWorld.chunkCache / rtpChunkCache were WeakReference maps, and a freshly loaded chunk is only held by vanilla's transient create=true generation ticket (released as soon as the FULL-status future resolves) until that keep-ticket is applied (only after a successful verify). Under the deficit-dispatch burst of generating many candidate chunks at once, the just-loaded wrapper was reclaimed in that gap, so getCachedChunk returned null for every promotion (proven by the [RTP][PROMOTE_DIAG] ... getCachedChunk returned null diagnostic): the L1 kept cache never filled, no keep-tickets were issued, and /rtp never found a safe spot. Fix: chunkCache / rtpChunkCache are now strong references (evicted explicitly in forgetChunkAt / forgetChunks), mirroring the proven Fabric 26.1 carrier (V26_1_R1FabricRTPWorld#chunkCache), so a loaded chunk survives the verify hop. loadLiveChunk also now logs at INFO (REQ-RTP-S-004) when the version adapter resolves a null ChunkAccess, so a genuine unwrap miss is distinguishable from a cache eviction. A second defect surfaced after the strong-reference fix: the version adapter's reflective chunk-future resolver picked the wrong method. The 4-arg (int,int,ChunkStatus,boolean)->CompletableFuture signature is not unique on ServerChunkCache (the public getChunkFuture plus the private getChunkFutureMainThread), and the public getChunkFuture(...), called on the server thread, internally mainThreadProcessor.managedBlock(...)-s, i.e. re-drives the main-thread task queue; because NeoForgeRTPWorld.loadLiveChunk already invokes the adapter from inside a MinecraftServer#execute task on the tick thread, that re-entrant drain ran a task queue from inside one of its own tasks and, on the Forge-patched 26.1 chunk system, resolved IMMEDIATELY to ChunkResult.Fail("Unloaded chunk") (proven by the [RTP][NeoForge 26.1] ... chunkResultError=Unloaded chunk diagnostic). A blocking ServerChunkCache#getChunk(...) fallback added inside that same callback made it worse - the exact self-driving-task deadlock documented in rtp-fabric-ADR-008, wedging the tick thread (the per-chunk promotion diagnostics vanished from the log while the deficit-dispatch worker spam continued). Fix: resolveGetChunkFutureMethod now prefers the private non-blocking primitive getChunkFutureMainThread (then getChunkFuture, then a structural scan) - called on the server thread it adds the create=true UNKNOWN generation ticket and returns the holder's PENDING scheduled future without re-draining the tick thread, exactly mirroring the green Fabric 26.1 carrier - and the deadlocking blocking fallback was removed (the callback now just unwraps the future and emits the S-004 diagnostic on a genuine miss). The persistent kept-cache ticket is still applied separately on the server thread via applyTicket(...), so S-002 is unaffected. A fourth cause was then found: NeoForgeRTPWorld.loadLiveChunk bounded the dispatch with a 1.5s bridge.orTimeout, so whenever the tick thread fell momentarily behind (the server logged "Running 2535ms behind" during first-chunk worldgen) the server.execute runnable could not start within 1.5s and the load failed with a spurious TimeoutException (attributed by PregenTask), so L1 still never promoted and /rtp never landed; the 1.5s pre-dispatch timeout was removed, leaving only the existing 30s generation deadline (matching the Fabric carrier, which has no short pre-dispatch deadline). Still an opt-in build island; runtime /rtp round-trip re-test pending on a JDK-25 host. A fifth cause was found on 26.1.2: getChunkFutureMainThread does not exist on this runtime (only getChunkFuture matches the 4-arg signature), so the resolver always fell back to getChunkFuture, which on 26.1.2 resolves immediately to ChunkResult.error("Unloaded chunk") without a prior load-ticket - the chunk holder never reached FULL status. Fix: resolveGetChunkFutureMethod now prefers getChunkFuture directly (removing the dead getChunkFutureMainThread first-preference), and requestFullChunkAsync now applies a temporary addTicketWithRadius call before invoking getChunkFuture(create=true) and removes it in a whenComplete handler, so the chunk holder is promoted to FULL status before the future resolves - mirroring the v1_21_R1 carrier's proven ticket pattern.

  • Written-book menu now actually opens on the deobf MC 26.x Fabric carriers (rtp-fabric-ADR-012 section 4). After V26_1_R1/V26_2_R1FabricVersionAdapter gained openBookMenu, /rtp menu//rtp config/the admin panel still fell back to the chat renderer on 26.x because FabricBookMenuRenderer recognised only the common FabricRTPPlayer (instanceof) when resolving the target player. On the deobf 26.x runtime the online player is a per-version sink (V26_1_R1FabricRTPPlayer / V26_2_R1FabricRTPPlayer) that implements RTPPlayer directly and does not extend the common FabricRTPPlayer, so the renderer silently degraded to chat - the book never opened. New FabricBookOpener capability interface (rtp-fabric-common): each Fabric player exposes a single openBookMenu(FabricBookSpec) method (delegating to the active FabricVersionAdapter with its own ServerPlayer, which stays private to the player) and the renderer now just calls opener.openBookMenu(spec) instead of extracting and passing a raw ServerPlayer. Implemented on the common FabricRTPPlayer (1.20.x / 1.21.x) and both 26.x players, so the book opens on 26.x. 1.20.x is unaffected (its carrier keeps the openBookMenu SPI default false and the renderer falls back to chat).

  • /rtp admin, /rtp config, and the chat menu now render clickable text on the deobf MC 26.x Fabric carriers. On 26.x the written-book modal is not yet wired (the carrier keeps openBookMenu's default false), so the menu falls back to the chat renderer - but FabricServerAccessor's rich-text path could only attach hover/click to the common FabricRTPPlayer; for the per-version 26.x sink (V26_1_R1FabricRTPPlayer / V26_2_R1FabricRTPPlayer) it degraded to a plain, dead-text message, so every menu//rtp info line arrived unclickable. New FabricInteractiveMessageSink capability interface (rtp-fabric-common): a per-version player that implements it builds the hover/click Component on its own deobf-linkable runtime, and FabricServerAccessor.sendInteractiveMessage / sendMessageAndSuggest route through it instead of the plain fallback. Both 26.x carriers implement it via a new parseInteractive(...) (plus reflective, mapping-agnostic HoverEvent/ClickEvent builders) added to their version-local legacy-text parsers. 1.20.x/1.21.x are unaffected (they use the common FabricRTPPlayer path, and 1.21+ opens the book).

  • Fabric rtp scan no longer abandons chunks that need generating. FabricRTPWorld#getOrLoadChunk (both the obf and unobf carriers) bounded each live chunk load with an adapter-owned LIVE_LOAD_DEADLINE_MS of 4 s. Vanilla cold-start generation on a never-before-explored coordinate routinely takes 5-10 s under early-server scan/pre-fill load, so the deadline fired and rejected the in-progress generation as a nullChunk before vanilla finished - even though ScanTask's full-load path already waits 30 s. The per-chunk deadline is now 30 s, matching the scan wait so generation runs to completion while still bounding a genuinely stuck coordinate; the bridge-dispatch (server-shutdown drop) watchdog is unchanged.

  • /rtp scan cancel (and pause) no longer freeze the server or spam timeout exceptions. ScanTask.setCancelled(true) and pause() drained outstanding chunk-load futures with an unbounded inFlightGate.acquire(MAX_PENDING_CHUNKS) on the calling (command / main) thread. If a candidate chunk was mid-generation, the drain blocked until each in-flight load finished or hit the per-future 30 s orTimeout, stalling the server for up to many seconds, and every elapsed timeout still logged a Chunk generation exception WARNING during the cancel - flooding the console. The drain is now bounded (tryAcquire with a 5 s ceiling) and first actively cancels every tracked in-flight chunk future, so cancellation returns promptly without waiting out the timeouts (the cancelled / paused flag already guards late callbacks from mutating saved state). The full-load completion handler now suppresses the timeout / null-chunk WARNING once the task is cancelled or paused, eliminating the log spam.

Removed

  • Dead Mojmap-decoupling wrappers and their SPI methods on the Fabric version adapter (rtp-fabric-ADR-007). Four FabricVersionAdapter methods had no live callers anywhere in the tree - blockKey, biomeKeyAt, hasChunk, and airState - so they were deleted from the interface and from every per-version adapter implementation (v1_20_R1, v1_21_R1, v1_21_R5, v1_21_R11, v26_1_R1, v26_2_R1) plus the test stub. With those gone, the RTPBlockHandle, RTPBlockStateHandle, and RTPRegistryKey wrapper records became unused and were removed. The still-live chunk-load / ticket seam is unchanged: RTPLevelHandle (parameter of requestFullChunkAsync / getChunkFull / applyTicket / releaseTicket) and RTPChunkHandle (their return) remain. No behaviour change.

  • bStats pipeline_latency_buckets chart. The chart bucketised avgPipelineMs, the mean of every TeleportPipelineTask completion. Because the histogram sample window starts at task construction (ADR-032), it includes at-rate queue-wait / configured-delay time for queued teleports (only the slow-teleport audit is gated to immediate/unqueued teleports per ADR-053). Bucketising that mean misrepresents pipeline latency across the bStats fleet, so the chart was dropped (registration in RTPCostMetricsCharts, BStatsChartIds.PIPELINE_LATENCY_BUCKETS, and the pipelineLatencyBucket helper removed). The honest per-teleport latency signal remains operator-local via /rtp info (mean + P50..P99 percentiles, plus the immediate/unqueued-gated slow-teleport audit).

Changed

  • (Pro) NeoForge now ships inside the unified LeafRTP-Pro jar, loadable on a NeoForge server (ADR-033). The released LeafRTP-Pro-<version>.jar now co-ships META-INF/neoforge.mods.toml and the NeoForge platform bytecode alongside plugin.yml (Bukkit/Paper/Folia), fabric.mod.json (Fabric), and velocity-plugin.json (Velocity), so one artifact drops straight into a NeoForge mods/ folder instead of being rejected as is a Fabric mod and cannot be loaded. rtp-plugin merges the rtp-neoforge-common + rtp-neoforge-v1_21_R1 carriers into the jar after Loom's remapJar (Mojmap names preserved, mirroring the deobf MC 26.x v26/unobf merge), applying the same commandsapi/effectsapi package relocation Shadow performs on the rest of the jar; on a non-NeoForge runtime the @Mod entry point (RTPNeoForgeMod) and its net.neoforged.*/NM references are simply never classloaded. The NeoForge modules build BY DEFAULT (settings.gradle); network-constrained hosts drop them with the new -PexcludeNeoforge (or EXCLUDE_NEOFORGE) flag (replacing the former opt-in -PincludeNeoforge), in which case the unified jar carries no neoforge.mods.toml.

  • Fabric anvil pre-filter helpers lifted into rtp-core so they can be referenced generically. The platform-neutral palette reconciler and the ColumnProbe -> ChunkColumnProbe adapter the Fabric carriers used were duplicated in both rtp-fabric-common and rtp-fabric-common-unobf even though neither touches net.minecraft.* (they depend only on rtp-anvil and rtp-api). They now live once in rtp-core as io.github.dailystruggle.rtp.common.anvil.PaletteNormalizer and AnvilColumnProbeAdapter (with rtp-core gaining an anvil-api dependency; the reverse edge stays forbidden), and all Fabric world/chunk callers (obf, unobf, and the MC 26.1/26.2 carriers) reference the shared copies. No behaviour change; the reconciler regression guard moved with the class (PaletteNormalizerTest).

  • Network-mode backend plumbing lifted from rtp-plugin into rtp-core so it is platform-neutral (ADR-049; MULTI_PLATFORM_PLAN.md Step J). All thirteen network classes (NetworkModeBootstrap, NetworkRouter, NetworkStatusCache, NetworkEnrolmentBuffer, PeerRegionRegistry, LobbyDispatchRetryQueue, NetworkRegionCollisionWarner, RoutingDecision, BukkitNetworkCommandHook, NetworkWaitlistNotifier, plus the three formerly Bukkit-coupled listeners) moved from io.github.dailystruggle.rtp.bukkit.network to io.github.dailystruggle.rtp.common.network, so future network-mode work lands once and ships on every backend platform (Bukkit/Paper/Folia/Fabric) instead of being Bukkit-only. The three event-coupled classes (JoinTriggerSource, NetworkWaitlistQuitListener, NetworkWaitlistGuard) were rewritten off the Bukkit Listener/PlayerJoinEvent/PlayerQuitEvent/CommandSender surface onto the platform-neutral PlayerLifecycleHook SPI plus RTPPlayer.performCommand and Predicate<RTPCommandSender>; the backend heartbeat sampler is now obtained through a settable RTP.backendStateSamplerFactory (Bukkit installs BukkitBackendStateSampler in AbstractServerAccessor.start) rather than a direct new BukkitBackendStateSampler(...). No behaviour change on the user-confirmed-working Paper path; the network test suite (141) moved with the code to rtp-core and stays green, and LobbyModeTest (18) still passes from rtp-plugin. This is the rtp-core groundwork enabling Fabric network-mode parity; the Fabric-side sampler/command-hook/entrypoint wiring is a follow-up.

  • Fabric network-mode backend wiring landed (ADR-049 phase 2) (ADR-049; rtp-fabric-ADR-013). A Fabric server can now act as a network-mode backend or lobby: a Velocity-routed player arriving on a Fabric backend redeems its reservation token on join exactly as on Paper. RTPFabricMod now installs RTP.backendStateSamplerFactory (a new FabricBackendStateSampler in rtp-fabric-common that reads TPS/MSPT/player-count from the Fabric metrics binding and loaded worlds via RTPServerAccessor.getRTPWorlds()), reads routing.lobbyMode early, boots the platform-neutral NetworkModeBootstrap after the database comes up at SERVER_STARTED, registers the join-redeem and waitlist-quit listeners onto the FabricPlayerLifecycleHook, and tears the bootstrap down at SERVER_STOPPING. Cross-server /rtp routing works automatically because the shared RTPCmd.compute consults RTP.networkCommandHook, which the bootstrap installs. Covered by FabricPlayerLifecycleHookTest (5). The Fabric waitlist command-guard (blocking a fresh /rtp while a player is already enrolled) has no Brigadier sender-check insertion point yet and remains a follow-up; the reservation-token redeem path is unaffected by its absence.

  • Vault economy is supported by the RTP-lite assembly variant (ADR-024, 2026-06-01 economy amendment). The earlier scoping that treated Vault/economy as Pro-only was never an intentional monetization boundary - lite now wires the Vault hook from RTPBukkitLitePlugin.onEnable (binding VaultChecker through the RTPHooks economy facade when Vault is present, identically to the full bootstrap), ships economy.yml in the lite jar, declares Vault in its plugin.yml softdepend, and drops the liteJarStructureCheck ban on economy.yml. Optional per-/rtp charging (price, priceOther, params/biome surcharges, balance floor, refund-on-cancel) now works out of the box on the free build; the hook stays dormant at zero runtime cost when Vault is not installed.

  • Open-core dual licensing (ADR-061). The project is now dual-licensed: rtp-api, rtp-core, and the RTP (lite) binary are MIT-licensed (new root LICENSE-MIT, mirrored as module-local rtp-api/LICENSE and rtp-core/LICENSE) and may be used, modified, and redistributed including commercially; all other source (the Pro-only features and the Pro assembly) remains under the PolyForm Noncommercial 1.0.0 root LICENSE, which gained a preamble describing the split. The lite jar now bundles the MIT text as its in-jar LICENSE instead of the PolyForm text, and the liteJarStructureCheck Gradle audit asserts the lite jar ships the MIT license (and not the PolyForm one).

Fixed (network mode)

  • Cross-server /rtp region=<server>:<region> now lands in the requested region on the destination backend (REQ-RTP-NET-015 / REQ-RTP-S-004). A /rtp region=world1:nether issued from another server routed to world1 correctly (the serverHint was honoured) but always arrived in the default/overworld region: the requested regionKey was parsed and reached the proxy dispatcher in RtpRequest, then dropped at three points - the dispatcher's transport.claim(...) carried no region, ReservationToken had no region field, and the destination backend's JoinTriggerSource dispatched a bare rtp. The region constraint is now threaded end-to-end: NetworkTransport.claim gains a region-aware overload (legacy 3-arg preserved), ReservationToken carries an optional regionKey(), all three transport bindings persist and read it back (in-memory token field, a new nullable region_key column on rtp_network_tokens for SQL with an idempotent ALTER migration, and a regionKey HSET field for Redis via claim.lua ARGV[8]), the dispatcher passes request.regionKey() to the claim, and JoinTriggerSource re-attaches it as rtp region=<regionKey> on arrival (regionless arrivals still dispatch a bare rtp). Covered by new region-propagation regression tests on the in-memory and SQL (H2) bindings.

  • Cross-server /rtp arrivals now teleport on a Fabric backend (no more NoSuchMethodError on join) (ADR-049). When a Velocity-routed player joined a Fabric backend, JoinTriggerSource redeemed the reservation token and dispatched /rtp via FabricRTPPlayer.performCommand, which called ServerPlayer#createCommandSourceStack(). That method's intermediary (method_5671) is absent on the MC 1.21.11 runtime, so the dispatch threw NoSuchMethodError and the player connected but was never teleported (same Yarn/intermediary drift family already worked around for getServer / teleportTo / the field_13995 server field in this file). A first fix added a hand-built CommandSourceStack fallback, but that path called Entity#position() (intermediary method_19538), which also drifts on 1.21.11, so it threw NoSuchMethodError in turn and /rtp still was not dispatched. Fix: buildCommandSource(...) now inserts a drift-immune intermediate attempt - MinecraftServer#createCommandSourceStack() re-anchored on the player via CommandSourceStack#withEntity(player), which makes Minecraft perform the position / name lookups internally (no cross-module intermediary call from us) - and the hand-built last resort now sources position / rotation / display name through individually guarded safePosition / safeRotation / safeDisplayName helpers that default to neutral values (the source position is irrelevant to a self-targeting /rtp); if every path fails it logs at WARNING (REQ-RTP-S-004) instead of throwing.

  • Network mode now boots on Folia backends, and cross-server /rtp arrivals teleport there (ADR-049). After the network plumbing was lifted into rtp-core, the backend heartbeat sampler is obtained through RTP.backendStateSamplerFactory, which the Bukkit accessor installs in AbstractServerAccessor.start(Object). Folia uses a separate AbstractFoliaServerAccessor (it does not extend the Bukkit accessor), and its start(Object) neither installed the factory nor registered a PlayerLifecycleHook. A Folia backend therefore aborted its network boot with no BackendStateSampler factory installed by the platform adapter, and because getPlayerLifecycleHook() fell back to the no-op default, a Velocity-routed player arriving on a Folia backend never had its join observed and never redeemed its reservation token (the player connected but was not teleported). Fix: AbstractFoliaServerAccessor.start(Object) now registers a BukkitPlayerLifecycleHook (Folia is a Bukkit-API platform; the hook is reachable via rtp-folia-common -> rtp-paper-common -> rtp-bukkit-common), overrides getPlayerLifecycleHook() to return it, and installs RTP.backendStateSamplerFactory with BukkitBackendStateSampler (which uses only Folia-safe Bukkit.getWorlds() + RTP internals), mirroring the Bukkit accessor.

3.1.0 - 2026-05-31

Added

  • German (de) locale shipped across all config/message files; full locale parity maintained.
  • Region-specific schematic paste platforms (ADR-058) with new PasteOptions API and RegionVerifierRegistry footprint claim checks (S-003). New prefabs updated to use it (skyblock, oneblock, high-performance, multi-world).
  • Pluggable bare-/rtp root action (ADR-056, REQ-API-F-006). New RootActionRegistry SPI (RTPAPI.hooks().rootAction()) lets an addon take over a bare /rtp (e.g. open a GUI menu) instead of teleporting; subcommands are never routed through it. Shipped with an example menu addon.
  • Platform-agnostic addon SPI (ADR-057). New RTPAddon lifecycle interface + AddonRegistry (RTP.addons, ServiceLoader-based) so an addon jar runs unchanged on Bukkit/Paper/Folia, Fabric, and proxy JVMs. RTP_ExampleAddon ported with zero org.bukkit.* imports.
  • Optional PvP / combat-tag gate (ADR-055). Off by default (safety.yml#pvpCheckEnabled=false). When enabled, /rtp is refused for a player currently in combat, using either a bound PvPCombatStateRegistry provider (combat-tag plugins such as PvPManager / SimpleCombatLog / CombatLogX) or RTP's built-in native damage tracker. The native tracker is now fed on every supported platform: Bukkit/Paper/Folia via an EntityDamageByEntityEvent listener and Fabric via ServerLivingEntityEvents.AFTER_DAMAGE (both resolve the projectile shooter / primed-TNT igniter as the aggressor and stamp victim/aggressor per pvpTagVictim / pvpTagAggressor). The gate is consulted at the /rtp pre-dispatch surface before the player is enrolled, fails open (a broken external provider never blocks a teleport), audits every refusal at WARNING (REQ-RTP-S-004), and uses the new configurable messages.yml#pvpInCombat string (REQ-RTP-F-013). Six safety.yml knobs: pvpCheckEnabled, pvpCombatTagSeconds, pvpOnCombat, pvpSource, pvpTagVictim, pvpTagAggressor.
  • Bundled combat-tag plugin integrations for the PvP gate (ADR-055). New reflection-based soft-depend adapters for PvPManager, CombatLogX, and Simple Combat Log (rtp-plugin/.../softdepends/pvp/); PvPIntegrations.setup binds the first enabled plugin (priority PvPManager, then CombatLogX, then Simple Combat Log) to PvPCombatStateRegistry via RTPAPI.hooks().pvpCombatState(), gated on isPluginEnabled(...) like the claim integrations. When none is installed (or pvpSource: NATIVE), the native combat tracker answers; a reflective/API-version failure disables the adapter for the session and treats the player as not-in-combat (REQ-RTP-S-004). Wired in both the full and rtp-lite bootstraps. Covered by PvPCombatAdapterTest.
  • uniquePlacements is now an integer chunk radius (was boolean; defaults to 0 = off). N >= 1 clears a (2N-1)x(2N-1) chunk square around each used spot so placements spread out; legacy true/false still coerce to 1/0. Retired spots tagged with a dedicated uniquePlacement fail cause.
  • Config getters tolerate boolean<->int cross-typing, so a legacy true/false on a now-numeric knob (or 0/1 on a boolean knob) resolves instead of throwing.
  • Optional emergency-platform block-restoration timeout (ADR-060). New safety.yml knob platformRestoreSeconds (-1 = disabled default; 0 = restore on first loaded pulse; > 0 = after that many seconds). Restores are chunk-load-aware (never force-loads, S-005), Folia-safe, and persisted across restarts.
  • /rtp info now surfaces generation outcomes (REQ-RTP-OBS-007, ADR-052): success/failure rate and a per-cause rejection breakdown, via six new placeholders and three messages.yml lines.
  • Live-updating bad-locations map during a world scan: the admin "Region shape" chart now re-renders ~1 Hz from the in-memory bad-keys cache so scan progress is visible without re-issuing the command.
  • New bStats charts: language_selection, MSPT-p99 by platform/game-version/plugin-version, and aggregate generation-outcome (success rate + top failure cause). All privacy-safe (bucketised / whitelisted categories).
  • /rtp clear admin command tree (permission rtp.admin). Groups the clear actions under one verb for cleaner tab-completion: /rtp clear cache clears the L1 (kept), L2 (unkept), and L3 (backlog) location caches for every region across the board in one shot, releasing any held chunk reservations and dropping the associated persisted rows (the scan/queue machinery refills the caches afterwards; backed by a new RegionQueueManager.clearCaches()), alongside cooldown, queue, limit, and invuln.
  • rtp.admin permission node declared in plugin.yml (both full and lite), gating /rtp clear and grouping the existing admin tooling permissions (rtp.reload, rtp.config, rtp.scan, rtp.info) as children so a single grant covers all admin commands.
  • (Pro) Numeric range predicates in the safety-list grammar (ADR-017 amendment). safety.yml::unsafeBlocks / airBlocks now accept block-state comparisons (LAVA[level<=3], FIRE[age>=10], *[level>=8]); multiple bounds AND together. rtp-lite ignores tag/predicate tokens.

Changed

  • Region biome visualization now sources its pixels from saved region biome data only. RegionBiomesResolver no longer reads on-disk .mca palettes via RTPWorld.readBiomesInRegionFile; it classifies each in-disk pixel through the new MemoryShape.biomeAt(int, int) / biomeAt(long), a floor-search over the persisted biomeKeysCache / biomePrefixSumsCache accumulated by the scan pipeline (no chunk I/O, S-005-clean). Pixels with no recorded biome render as unsampled (BLACK), so the chart reflects what the scan has actually saved for the region.

3.0.0 - 2026-05-29

Changed

  • RTPWorld.isChunkGenerated on Bukkit / Paper / Folia now routes through the same AnvilRegionOccupancyCache bitmap path Fabric uses, and ScanTask's PRESCAN precheck runs unconditionally on every platform. BukkitRTPWorld.isChunkGenerated and FoliaRTPWorld.isChunkGenerated previously delegated to org.bukkit.World#isChunkGenerated, a synchronous chunk-system / region-file index walk on the calling thread. When ScanTask invoked it per-candidate inside the in-flight gate, it collapsed peakInFlight from cap=50 to ~2-3 and held PRESCAN cps at ~19 on a 193k-chunk world (the [TRACE] ScanTask diag regression). The previously-shipped Fabric-only isFabricPlatform() gate that fenced off the precheck on Bukkit-family platforms is removed; both BukkitRTPWorld.isChunkGenerated and FoliaRTPWorld.isChunkGenerated now try World#isChunkLoaded first (cheap, off-region safe), then AnvilPrefilter.regionFileFor + AnvilRegionOccupancyCache.isOccupied against the r.X.Z.mca file, with the true-on-error conservative default preserved for the ADR-016 section 13.3 palette-drift contract. The 1024-bit per-region-file occupancy bitmap built on first touch amortises across all ~1024 sibling-chunk queries in that 32x32 tile, so PRESCAN's spiral sweep first-touches each region file once and then runs in O(1) per chunk for the next ~1023 candidates. ScanTask.IS_FABRIC_CACHE + isFabricPlatform() deleted.

Added

  • Always-on generation outcome metrics and cause-tagged bad-location persistence (ADR-052). New process-global RtpOutcomeStats accumulator (rtp-core metrics package) records every location-generation success and per-FailTypes failure, fed from the single always-on PregenTask.recordOutcome(...) chokepoint independent of the verbose flag, so success/failure rates and a per-cause rejection breakdown (including claim/protection rejections via safetyExternal) accumulate from real traffic with no verbose logging and no traffic simulation. The verbose failMap console dump and S-004 attribution are unchanged. MemoryShape now tags each persisted bad-location run with one rejection cause: a badCauseCache byte array aligned to badKeysCache, cause-aware addBadLocation(long, FailTypes) / addBadChunk(long, FailTypes) overloads, first-cause-wins through the RLE rebuild, a versioned .bin format (magic + version header, one cause byte per run, legacy files load as misc with no migration), and a cause field in the debug JSON export. The four chunk-attributable PregenTask.addBadChunk sites are tagged (vert / biome / safety / safetyExternal); all other callers default to misc. Covered by RtpOutcomeStatsAndCauseTaggingTest (5 cases); ReqRtpS004NullChunkAttributionTest and MemoryShape suites (89) confirm no regression.

3.0.0-beta.4 - 2026-05-25

Changed

  • Concrete menu commands supersede token registries (ADR-050, Accepted 2026-05-24; partially supersedes ADR-035 section 3 / section Security and ADR-047's ChartSpecTokens). Book click events now carry self-documenting /rtp menu ... and /rtp visualization ... commands instead of opaque /rtp menu token=<uuid> redeems. Operators can read every click as a literal admin command; permission gating on each dispatch* helper is the sole security boundary. Renderer rewrite (BookMenuRenderer.toClickEvent) emits 22 concrete commands, one per MenuAction variant. New concrete leaves under /rtp menu: open, admin, front, visualizations, picker, page, config, info, anvil, stage, unstage, apply, discard, multi; sibling /rtp visualization for maps. MenuAction.OpenMap(UUID chartSpecToken) reshaped to OpenMap(ChartSpec.Kind kind, String regionName). MenuTokenRegistry (rtp-api), LocalMenuTokenRegistry, and ChartSpecTokens (rtp-core) deleted; the MenuTokenRegistry ctor parameter dropped from 9 classes (MenuRedeemSubcommand, BookMenuRenderer, FrontPageBuilder, AdminPanelBuilder, CommandTreeMenuBuilder, InfoBookBuilder, PrefabConfirmationMenuBuilder, VisualizationsSubmenuBuilder, MultiConfigMenuBuilder); RTPCmdBukkit reflective wiring switched to no-arg ctor lookup. messages.yml::menuExpired retired (no token lifetime to expire); menuInvalid documentation refreshed to reflect the new "malformed concrete command or denied permission" semantics; locale TSV pipeline propagated the removal across all 12 shipped locales. New test suite ReqRtpMenuConcreteCommandsTest (36 cases) exercises every concrete leaf's registration, routing, and permission gate; BookMenuRendererTest (34) rewritten to assert literal command strings per variant. Six token-mechanic tests deleted (MenuMultiConfigDispatchTest, MenuNavigationStageATest, MenuParamPickerStageA2Test, ConfigSearchDispatchTest, MenuConfigSubtreeDispatchTest, ChartSpecTokensTest).

Added

  • Admin-panel curated prefabs subsystem. New /rtp admin shim opens the curated admin panel (OpenAdminPanel, gated on rtp.menu.admin) with a Setup section listing five bundled prefabs (survival-default, low-performance, high-performance, folia-tuned, multi-world) under rtp.admin.prefab. Each row opens a confirmation page (PrefabConfirmationMenuBuilder) backed by a ~60s caller-bound single-use nonce; Confirm writes via PrefabDiskIO.writeWithBackup with .bak.<epochMillis> retention (prefab.bakRetention knob, default 3) plus best-effort reload. Matching chat surface /rtp admin prefab {list,apply,confirm,rollback}; pure-function core under rtp-core/.../commands/prefab/. 15 MessagesKeys constants for the Setup section propagated through the locale TSV pipeline. Covered by 7 test classes; new admin-facing docs/admin/PREFABS.md.
  • Network mode shared cross-server waitlist (rtp-proxy-ADR-015, REQ-RTP-NET-015). Mirrors the per-backend playerQueue UX across proxies in five slices: (1) NetworkWaitlist SPI + InMemoryNetworkWaitlist reference impl (LinkedHashMap-backed, maxSize default 1024); (2) NetworkWaitlistDrainer + DefaultRtpDispatcher rewiring + new WAITLISTED QueueState + WaitlistLeaderLease SPI; (3a) Redis-backed RedisLeaderLease (NX/XX PX, compare-and-DEL) for cross-proxy single-leader election; (3b) RedisNetworkWaitlist with 7 atomic Lua scripts (enrol, drain-batch, position, remove, reap, refresh-ttl, etc.); (4) lobby-side UX wiring (notify, command-lock, quit-removal); (5) MessagesKeys parity: new alreadyQueued key + [position] placeholder propagated through every shipped locale. Covered by InMemoryNetworkWaitlistTest (15), DefaultRtpDispatcherWaitlistTest (4), opt-in RedisLeaderLeaseIT (8), RedisNetworkWaitlistIT, and LocaleParityTest.
  • Lobby load balancing v1 (most-kept) documented. A backend booted with network.yml::routing.lobbyMode: true advertises acceptingRequests=false and regionsAvailable=Set.of(); bare /rtp on it is intercepted by BukkitNetworkCommand and routed to the peer with the most kept locations. Code shipped earlier as Slices I+J during the cross-server /rtp stabilisation; this entry documents the design, sequencing, and coverage (LobbyModeTest 12, LobbyModeEarlyReadTest 3).
  • Fabric menu surface lit up via chat renderer (rtp-fabric-ADR-012 Accepted 2026-05-24; MULTI_PLATFORM_PLAN.md Step I Session 2). New RTPServerAccessor.sendMessageWithRunCommand(...) SPI dispatches a click as RUN_COMMAND (versus the sibling sendMessage(...) which uses SUGGEST_COMMAND); overrides on Bukkit (AbstractServerAccessor), Folia (AbstractFoliaServerAccessor), and Fabric (FabricServerAccessor, threaded through FabricLegacyText.parseInteractive(..., ClickKind) with CLICK_CTOR_RUN probed for 1.21.5+ record-shaped ClickEvent$RunCommand). New platform-neutral ChatMenuRenderer in rtp-core walks MenuModel and emits one chat message per clickable fragment (decorative-only lines coalesce); shares the MenuAction -> /rtp menu ... translation table with BookMenuRenderer via the new MenuActionToCommand helper -- single source of truth post-ADR-050. RTPCmdFabricRoot:218-249 mirrors RTPCmdBukkit:215-230 and wires ChatMenuRenderer + FabricChatPromptCallback (TTL-bounded chat-prompt substitute for PromptAnvilInput per ADR-012 section 3, drained via ServerMessageEvents.ALLOW_CHAT_MESSAGE with the reaper scheduled through RTP.scheduler.runTaskTimerAsynchronously per AGENTS.md Scheduler Usage) into MenuWiringSupport.attachTo; permission probe routes through ADR-048 Phase B's RTPServerAccessor.menuPermissionProbe(uuid). Covered by ChatMenuRendererTest (12 cases including MenuActionToCommand regression guards) plus existing BookMenuRendererTest (33/33 confirms the helper extract is regression-free).
  • Declarative chart composition bridge (ADR-047, REQ-RTP-MAP-006). Renderer-neutral chart-spec + resolver SPI plumbed end-to-end across multiple stages: governance row in TRACEABILITY.md/REQUIREMENTS.md section 1.7; BukkitMapBinding first concrete MapBinding under maps-api/.../mapsapi/bukkit/ (allocate/renderEphemeral); MapBindingLifecycle SPI mirroring commands-api/effects-api registration patterns with viewer-indexed chartIdsByViewer and MapDispatchTest (10); FoliaMapBinding thin override (Bukkit paths inherited; quit/disable hooks delegated); ChartSpecTokens (60s TTL, single-use, player-bound, atomic-remove consume, sweep seam) with 21-case test; Stage-2 menu wiring (MenuAction.OpenMap sealed permit, /rtp info row, BookMenuRenderer arm, redeem through MenuRedeemSubcommand). New baseline messages.yml::menuInfoBadPointsLabel propagated via TSV pipeline.
  • ADR-049 authored (Proposed 2026-05-23); supersedes rtp-fabric-ADR-013. Documentation-only this cycle: re-audit of rtp-plugin/.../bukkit/network/ showed nine of the thirteen classes (including the 1108-line NetworkModeBootstrap) have zero org.bukkit.* imports and the four that do touch the Bukkit API touch it only for player join/quit subscription + Bukkit.getPlayer(uuid) lookup. ADR-049 adopts a lift-to-rtp-core path with a single new SPI primitive (PlayerLifecycleHook) on RTPServerAccessor rather than the parallel-reimplementation path proposed in rtp-fabric-ADR-013 (which was flipped to Superseded). MULTI_PLATFORM_PLAN.md Step J rewritten to reflect the new sub-item list. Implementation is a follow-up change.

Changed

  • commands-api parameter delimiter de-canonicalized; effects-api namespaced-id coercion collapsed to a single path. Follow-up to the : -> = command syntax migration. CommandsAPI.parameterDelimiter / multiParameterDelimiter are now public static final char (binary-compat for getstatic); ~20 internal TreeCommand sites use "=" / "," literals or char overloads; splitOnParamDelimiter remains the named primitive. REQ-API-F-005 re-worded to absolute state. On effects-api, BukkitValueCoercer.resolveViaRegistry/resolveSound lose the raw.contains(":") bifurcation in favour of a single NamespacedKey.fromString path with bare-token front-loader (preserves ENTITY_PLAYER_HURT underscore-to-dot). Legacy legacyColorFromDelimitedString removed. Existing :commands-api:test (31) and :effects-api:test (55) green.

Fixed

  • NetworkWaitlistGuard no longer gates non-teleport /rtp subcommands. The waitlist sender-check (added to RTPCmdBukkit via addSenderCheck(...) at boot) was running on every invocation of /rtp*, including pure subcommand dispatches like /rtp admin, /rtp menu token=..., /rtp info, /rtp reload, /rtp scan ... -- none of which teleport the player. The intent of the guard is to block a new teleport while the player is already enrolled in the cross-server waitlist (REQ-RTP-NET-015); blocking the admin panel or a menu-token redeem on the same condition is wrong and was also producing noisy [NETWORK][trace] NetworkWaitlistGuard.test: ... lines on every menu click. Fix: the raw-args RTPCmdBukkit.onCommand(sender, command, label, args) entry now inspects args[0] against the live getCommandLookup() and skips the sender-check loop when the invocation is a subcommand dispatch. Mirrors the existing early-return at the parametric onCommand(..., CommandsAPICommand nextCommand, ...) entry, which already bails when nextCommand != null before running sender checks. The bare-/rtp teleport path is unaffected.

  • /rtp argument-rejection messages now substitute the offending argument, and use the canonical key=value syntax (REQ-RTP-S-004, REQ-RTP-F-013). Four sites in RTPCmd.compute (unknown player, unknown world, unresolvable region, region with null world) and two in ScanResetCmd / ScanStartCmd were calling langParser.getConfigValue(MessagesKeys.badArg, "player:" + name) -- the second argument is the parser's default-when-key-missing, not a placeholder substitution. With the default messages.yml::badArg template "&c[P0] invalid command argument [arg]" present in the configuration, the player saw the literal [arg] token in the rejection message and never learned which argument was wrong. Fix: each site now fetches with the standard default "[P0] bad parameter - [arg]" (matching BaseRTPCmd.msgBadParameter and BukkitBaseRTPCmd.msgBadParameter) and explicitly calls msg.replace("[arg]", ...) to substitute the offending argument. Additionally, all six call sites and the two MenuRedeemSubcommand RunRtpCommand arms that synthesise /rtp info <scope:name> argv now use the canonical key=value syntax (player=<name> / world=<name> / region=<name>) rather than the legacy key:value form, matching the post-beta.3 commands-api delimiter migration (see Changed above) so the same string that the player sees in the rejection is also the string they would type to retry.

  • Network mode: /rtp region=<self>:<region> no longer gets stuck on the originating backend (REQ-RTP-S-004 / REQ-RTP-NET-015). When a player typed an explicit region=<server>:<region> whose <server> was the local backend's own serverId, NetworkRouter.route(...) honoured the hint as a hard-pin and funnelled the request through the cross-server gates - it would either bounce the player off-and-back to themselves or REJECT with REGION_UNAVAILABLE (depending on what regions the local heartbeat advertised at that instant), instead of just serving the request locally. Fix: at the top of route(...), after normalising the hint, drop it when hint.equals(localServerId). The redundant <self>: prefix now coalesces to the equivalent region=<region> shape and takes the normal local path under both LOCAL and AUTO modes. Foreign pins are unaffected (the user's primary use case for the hint). Covered by three new NetworkRouterTest cases (self_pin_coalesces_to_local_under_mode_LOCAL, self_pin_coalesces_to_local_under_mode_AUTO, foreign_pin_still_routes_cross_server).

  • Network mode: cross-server /rtp arrivals now teleport on Folia (REQ-RTP-S-004 / REQ-RTP-NET-015, Folia threading). After the prior pin/release fixes finally got the destination backend's JoinTriggerSource.handleRedeem to fire, the redeem succeeded and dispatchRtp invoked RTP.scheduler.runTaskLater(hop, 1L) to hop onto the main thread for Bukkit.dispatchCommand(player, "rtp"). On Folia, the bare runTaskLater overload lands on the Global Region Scheduler thread, but CraftServer.dispatchCommand runs TickThread.ensureTickThread against the player's owning region and throws IllegalStateException: Thread failed main thread check: Dispatching command async -- so the /rtp was thrown away and the player arrived without a teleport. Fix: (a) renamed RTPScheduler.scheduleTeleport(RTPPlayer, RTPRunnable, long) to runTaskForPlayer -- the name was a historical artifact; the method is a generic "run this on a thread that owns the player after N ticks" primitive used by TeleportPipelineTask, BukkitEffectsHandler, AnvilInputSession and (now) JoinTriggerSource; (b) JoinTriggerSource.dispatchRtp resolves the arriving RTPPlayer and routes the dispatch through RTP.scheduler.runTaskForPlayer(...), which on Folia hops to the player's entity scheduler (the only thread on which Bukkit.dispatchCommand passes the tick-thread check) and on Bukkit / Paper / Spigot / Fabric falls through to the existing main-thread path. The legacy runTaskLater fallback is preserved for the player-not-resolvable race. Bukkit/Paper/Spigot/Fabric unaffected behaviourally (single-tick-thread platforms).

  • Network mode: cross-server /rtp arrivals now teleport for pinned routes too (REQ-RTP-S-004 / REQ-RTP-NET-015). The Velocity proxy adapter's onServerPreConnect handler was eagerly calling transport.release(token.tokenId(), ReleaseReason.CONSUMED) immediately after rewriting the connect target. release.lua transitions the row to CONSUMED AND DELs the rtp:net:tokactive:<playerId> active-index key, so by the time the player joined the destination backend ~1-2s later, JoinTriggerSource.handleLookup called findReservation and got an empty result ("no reservation found"); the redeem path that pins the coord, evicts the local waitlist guard, and dispatches the local /rtp therefore never ran. Symptom (after the prior pin and evict-on-redeem fixes had landed): the player would correctly route to the named backend but arrive without any teleport happening. Fix: removed the eager release(CONSUMED) from RtpVelocityPlugin.onServerPreConnect. The proxy now only uses the reservation to rewrite the connect target; the token remains CLAIMED so the destination backend's JoinTriggerSource can redeem(...) on join (which transitions CLAIMED -> CONSUMED and clears the active index in redeem.lua atomically with pinning the coord and dispatching /rtp). The unknown-target-server release(BACKEND_REJECTED) path is preserved unchanged. The 30s reservation TTL plus the existing ReservationTokenReaper handle the edge case where the player disconnects mid-transfer and never reaches the backend.

  • Network mode: explicit /rtp region=<server>:<region> is no longer silently load-balanced (REQ-RTP-S-004 / REQ-RTP-NET-015). The proxy SPI RtpRequest had no serverHint field at all, so the upstream router's hard-pin (whether typed by the player or synthesised by lobby pickMostKept) was smuggled by TransportRequestTriggerSource into the unrelated originServerId slot, which the BackendSelector never reads. Every cross-server /rtp - pinned or not - therefore went through the load balancer, and an operator who routed a player to a specific backend had no way to make the proxy honour it. Fix: (a) RtpRequest gains a dedicated serverHint field with a 6-arg back-compat constructor that preserves every existing caller; (b) TransportRequestTriggerSource.dispatchEnvelope routes env.serverHint() into the new slot and leaves originServerId empty (the trigger source is not the request's origin); (c) DefaultRtpDispatcher.claimAfterSelect now branches on request.serverHint() first: present => selector.choose(request, snapshot, Optional.of(hint)) and hard-fail with NO_BACKEND (rather than silently load-balancing) when the pinned backend is not eligible, bypassing the region-aware fallback entirely; (d) waitlist round-trip preserves the hint - DefaultRtpDispatcher.parkOnWaitlist writes request.serverHint() into the WaitEnvelope and NetworkWaitlistDrainer.redispatch reads it back. Covered by two new cases in DefaultRtpDispatcherTest (serverHint_is_honoured_and_passed_to_selector_filter, serverHint_pin_unreachable_hard_fails_NO_BACKEND).

  • Network mode: cross-server arrivals now actually teleport (REQ-RTP-S-004 / REQ-RTP-NET-015). After JoinTriggerSource successfully redeemed a cross-server ReservationToken, the destination backend re-dispatched /rtp for the arriving player; that /rtp was then short-circuited by NetworkWaitlistGuard because the lobby-seeded NetworkStatusCache row was still non-terminal (QUEUED / RESERVED / TRANSFERRING) and would not be reconciled until the next supplier poll. Net symptom: player hops servers, sees no teleport, no warning logged. Fix: JoinTriggerSource.onRedeemed now evicts the arriving player's row from NetworkStatusCache via the new NetworkStatusCache.evictLocal(UUID) before dispatching /rtp, so the waitlist guard sees the player as no longer non-terminal and the local pipeline polls the pinned redeemed coord. The eviction is a local-state correction only; the proxy remains the source of truth for the authoritative terminal transition, which pollOnce will observe on its own schedule. Wired via a new JoinTriggerSource(transport, serverId, statusCache) constructor overload plus a late-bind setStatusCache(...) setter so the trigger source can be constructed before the status cache in the bootstrap sequence. Covered by two new cases in NetworkStatusCacheTest (evictLocal_removes_row_without_firing_terminal_listener, evictLocal_also_clears_sticky_seed). Note: an immediate side effect of the load-balancing fix above is that pinned cross-server /rtp finally lands the player on the named backend, which is the one whose JoinTriggerSource will see the matching ReservationToken - so the prior beta.4 evict-on-redeem fix is now actually exercised on the destination backend in the pinned scenario.
  • Permission-granted on-event teleports and effects now fire on Fabric (rtp-fabric-ADR-011). RTPCommandSender#getEffectivePermissions() previously returned Collections.emptySet() in all three Fabric player variants and the console sender because fabric-permissions-api is a check-only SPI; on-event grants and effect dispatch consequently fell through to config.yml defaults on Fabric. New enumerator threads node-set discovery through LP-Fabric when present (with op closed-namespace fallback) so rtp.onevent.* and effect tokens resolve identically to Bukkit. Covered by FabricEffectivePermissionsTest (22).
  • YAML database race in YamlFileDatabase.setValue(String, Map). Override no longer delegates to super.setValue (which enqueues async via getTable().thenAccept and races the re-nested enqueue, flattening top-level YAML keys); the localTables snapshot is now updated inline with the re-nested shape. Flake in YamlFileDatabaseTest.setValue_flatRow_isNestedUnderPrimaryKey resolved; :rtp-core:test 2460/2460 PASSED.
  • Lobby no-arg /rtp now spreads across ready peers instead of always picking the lex-smallest backend. Three interacting defects on the no-arg lobby dispatch: (a) BukkitBackendStateSampler.sample() was using the 13-arg BackendHeartbeat ctor that defaults keptCount=0 and regionKeptCounts=Map.of(), so every peer scored 0 and the deterministic lex tie-breaker won; (b) peers not accepting requests were not excluded from pickMostKept; (c) local recordDispatch decrement was not applied. Covered by new pickMostKept_* regressions and 18/18 in LobbyModeTest.
  • safety.yml::unsafeBlocks and probed block names accept either bare or minecraft:-namespaced form, with modded namespaces preserved verbatim. Direct analog of the biome fix below for future-proofing against an eventual Keyed-registry Material release (S-001 territory: missing block matches would drop the unsafe-block guard). New MaterialNames#matches(Set<String>, String) helper, sibling of BiomeNames; PregenTask and ScanTask probe-block checks route through it. Covered by MaterialNamesTest (22).
  • Biome arguments and safety.yml::biomes accept either bare or minecraft:-namespaced form across Bukkit-family platforms. Follow-up to the : -> = command syntax migration. New BiomeNames#matches helper treats the uppercase vanilla MINECRAFT: prefix as optional while preserving modded namespaces (IRIS:, TERRALITH:); RTPCmd no longer strips namespaces on input. All four ScanTask and both PregenTask biome-filter sites route through the helper. Covered by BiomeNamesTest (22); ScanTaskProcessingTest and ParameterParsingTest confirm no regression.

Security

  • HMAC envelope on the Redis transport wire (rtp-proxy-ADR-010 Phase 2e-Redis A3). Every published BackendHeartbeat / ProxyHeartbeat row carries an hmac=<hex> field signed via HmacVerifier over the canonical line-oriented payload; verification on read drops tampered or legacy-NULL rows with REQ-RTP-S-004 WARNING. NetworkBindings.open constructs HmacVerifier.loadFromEnv and degrades to InMemory on loader failure. rtp test network all audits the integration end-to-end.
  • HMAC envelope parity on the SQL transport (rtp-proxy-ADR-010). SqlNetworkStateBinding signs every published heartbeat + ReservationToken row over the same canonical field-order strings as Redis, verifies on every read site with constant-time compare, and drops tampered/legacy-NULL hmac rows. SqlNetworkStateSchema adds an idempotent ALTER TABLE ... ADD COLUMN IF NOT EXISTS hmac VARCHAR(128) migration that tolerates the MySQL/MariaDB dialect quirk (portable form first, bare ADD COLUMN retry, SQLSTATE 42S21/42xxx swallowed). Pre-A3 SQL deployments self-heal on the next heartbeat tick; verifier-null ctor preserved for back-compat.

3.0.0-beta.3 - 2026-05-20

Changed

  • User-facing color palette pulled away from yellow/gold/light tones, with occasional custom hex accents. Menu titles (menuRootTitle, menuAdminPanelTitle, configSelectorTitle, configFileTitle, configTypePickerTitle, configSubParamPageTitle) lose &6&l (bold gold) and adopt #5FB3B3&l (muted teal) for general titles or #9D7CD8&l (lavender) for the admin panel; the admin-panel front-page entry row's &6 arrow becomes #9D7CD8; admin-panel row arrows shift from cyan &b to muted teal #5FB3B3 (destructive Reload / Full diagnostics rows keep &c); config selector and per-key rows lose &e[key] / &f[value] for #7E9CC8[key] / #B084DC[value] (muted blue / muted purple). System status messages (alreadyTeleporting, teleportDeniedReloading, chunkLoading, teleportCancel, unsafe, cooldownMessage, notEnoughMoney, invalidWorld, noPerms, locationSaved, locationLoaded, scanReset, scanCancel) drop yellow &e for neutral &7; delayMessage adopts #9D7CD8 lavender and teleportMessage adopts #5FB3B3 teal for occasional accent. /rtp info value placeholders switch from bright white &f to muted blue #7E9CC8. PLAYER_COOLDOWN PAPI status moves from &e to #9D7CD8. Propagated through every shipped locale via the TSV pipeline (new scripts/recolor-locales.ps1 plus locale-files-from-csv.ps1). Verified by LocaleParityTest (154/154) and full gradlew build.

  • Ellipse shape parameterised over a dedicated EllipseMemoryShapeParams enum, with elliptical inner exclusion and Rectangle-style rotation (amends ADR-034). The second semi-axis radius2 previously lived on the shared GenericMemoryShapeParams enum, which forced every single-radius shape (Circle, Square, and their _Normal variants) to carry a meaningless radius2 default solely to satisfy Shape's "every enum constant present" constructor invariant. radius2 is now hosted on the new EllipseMemoryShapeParams enum alongside the other ellipse knobs (mode, radius, centerRadius, centerRadius2, rotation, centerX, centerZ, weight, uniquePlacements, expand), and Ellipse extends MemoryShape<EllipseMemoryShapeParams> directly rather than Circle. Ellipse additionally gains two new knobs: centerRadius2 (the second axis of an elliptical — rather than circular — inner exclusion) and rotation (degrees, mirroring RectangleParams.rotation, applied around (centerX, centerZ)). The spiral 1D mapping (getRange, rand, xzToLocation, locationToXZ, neighbourRingOffset) continues to use the wider of each radius pair as the bounding circle; contains enforces the true rotated elliptical inner / outer shells. Internal refactor — rtp-api is unaffected.

  • rtp.personalqueue permission semantics decomposed (ADR-043). Retires the bundled RegionQueueManager.queue(UUID) / Region.queue(UUID) method and replaces it with three named entry points: openPersonalQueue(UUID) (per-uuid coordinate bucket opt-in, schedules a single pregen fill), closePersonalQueue(UUID) (returns banked coordinates to L2 unkeptLocations), and requestTeleport(UUID) (enrolls the player on the teleport waitlist). Join / respawn / world-change listeners now open the bucket without enqueuing a teleport -- fixes the "ops appear in the queue after every join" symptom. Quit closes the bucket so coordinates are not stranded across sessions. Breaking for addons that called Region.queue(UUID) or RegionQueueManager.queue(UUID): pick openPersonalQueue (bucket opt-in) or requestTeleport (waitlist enrol) per the new semantics. Covered by ReqRtpAdr043PersonalQueueSeparationTest (6 cases).

Added

  • MemoryShape.chunkToLocations(int cx, int cz) and MemoryShape.addBadChunk(long location) -- new bounded inverse of xzToLocation at chunk granularity, plus a sibling of addBadLocation that marks every 1D index decoding to the same chunk. The Archimedean-spiral parameterisation in chunk units (ADR-001) guarantees <= 2 preimages per chunk, so chunkToLocations is O(1) (angular walk plus a shape-specific radial probe via a new neighbourRingOffset hook on Circle / Square). addBadChunk is intended for chunk-attributable rejections (biome, claim, border, anvil-prefilter, ocean), is idempotent, falls back to addBadLocation on outside-shape slop, and returns the count newly marked (0-2). All production rejection call sites in ScanTask, PregenTask, Polygon, ChunkyRTPShape, and the uniqueplacements-knob rand() paths of Circle / Square / Rectangle / Circle_Normal / Square_Normal are migrated to addBadChunk; within a chunk the per-column selection order is deterministic, so re-rolling the same chunk would re-pick the same column and reject identically. The only surviving addBadLocation calls in production are the internal fallbacks inside addBadChunk itself and the public API method body. Covered by MemoryShapeChunkToLocationsTest (10 cases).
  • backlogRefillThreshold performance knob -- new double-valued setting in performance.yml (range [0.0, 1.0], default 0.5) that adds hysteresis to the L3 backlog cache (ADR-028) refill loop. Previously every Region.execute() pulse re-topped backlogLocations to capacity, scattering shape picks across many .mca files and weakening the cross-region amortization of the world-shared anvil bin index. With the knob, the refill latch deactivates at capacity and re-arms only when size falls below floor(threshold * capacity), concentrating shape picks (and their anvil verifications) into bursts that share .mca files for better CPU and memory locality. Edge cases: 0.0 is opt-out (never re-arms), 1.0 reproduces the prior always-refill behaviour; out-of-range clamped, parser failures fall back to default. Covered by BacklogRefillThresholdTest (7 cases).
  • In-house YAML substrate (io.github.dailystruggle.rtp.common.configuration.yaml) now replaces simpleyaml across rtp-core (ADR-025, 2026-05-15 revision; ADR-042). Hand-rolled, zero-dependency reader / writer / AST (RtpYamlConfig, RtpYamlSection, RtpYamlMapping, RtpYamlSequence, RtpYamlScalar, RtpYamlReader, RtpYamlWriter) with block-comment preservation, atomic-rename save(), and a simpleyaml-shaped parity surface (typed getters getString/getInt/getLong/getDouble/getBoolean/getList/getStringList, predicates isSet/isConfigurationSection/isString/isInt/isBoolean/isList, getValues(boolean deep) / getMapValues(boolean), getName/getCurrentPath, getComment/setComment, remove(String), createSection(String[, Map]), loadWithComments/saveWithComments, loadConfiguration(InputStream, boolean), createOrLoad(), exists/getFilePath/createNewFile[(boolean)]/copyTo(String|File), plus RtpYamlOptions exposing copyDefaults(boolean) and indent(int) and a RtpYamlConfig.addDefault(String, Object) set-if-absent helper). All rtp-core production and test call sites — ConfigParser, MultiConfigParser, LanguageBootstrap, YamlFileDatabase, FactoryValue, RTP, RegionConfigLoader, SubConfigCmd, LanguageCmd, ListCmd / ListAddParameter / ListRemoveParameter, and the six corresponding test files — now use the substrate directly; the me.carleslc.Simple-YAML Gradle dependency and rtp-plugin shadow-relocate rules will be dropped in the next beta cycle once rtp-core ships green end-to-end across all platforms. Covered by RtpYamlSimpleYamlParityTest (21 cases) on top of the substrate's read/write/comment suites (211 + 177 + 177 cases), with the full rtp-core test pass continuing to validate every migrated call site.
  • Menu framework foundations in rtp-api (ADR-035 amended 2026-05-15; ADR-044). New io.github.dailystruggle.rtp.api.menu package introduces the platform-neutral menu surface that the upcoming /rtp menu consumer (with /rtp config as the first concrete browser) and downstream renderers will build against: immutable MenuModel / MenuPage / MenuLine / MenuFragment records, a sealed MenuAction (RunRtpCommand with defensive-copy args, ChangePage, SuggestInput, OpenExternalUrl), the MenuRenderer interface, the MenuTokenRegistry single-use / TTL / per-player-bounded contract, and the ADR-044 reflector seams MenuConsumerProfile (with a trivial defaultProfile() factory) + YamlCommentLookup (with an EMPTY constant for non-YAML-backed consumers). No platform imports, no Adventure, no rtp-core dependency — addons can build menus against this surface today. Concrete LocalMenuTokenRegistry, MenuRedeemSubcommand, CommandTreeMenuBuilder, and the Paper/Folia BookMenuRenderer ship in subsequent commits within the same beta.3 cycle. Covered by MenuModelSurfaceTest (12 cases). The matching tp-core concretes for the menu framework — LocalMenuTokenRegistry, MenuRedeemSubcommand, CommandTreeMenuBuilder, and ConfigMenuConsumerProfile — now ship alongside the API surface, gated by five new MessagesKeys entries (menuInvalid, menuExpired, menuUnknownPlayer, menuHoverFallbackType, menuHoverFallbackBounds) so user-facing rejection strings and hover fallbacks remain configurable per REQ-RTP-F-013. The redeem subcommand atomic-consumes tokens (owner-keyed CAS), rejects foreign UUIDs, and dispatches RunRtpCommand actions through the live /rtp tree; the reflector hides permission-denied nodes (scope answer A) and emits Run-for-subcommand / Suggest-for-parameter fragments with a YAML-comment → typed-fallback → null hover chain. messages.yml/TRACEABILITY.md wiring and the actual /rtp menu command registration land in Stage 3 of the same beta.3 cycle. Covered by MenuStageTwoTest (12 cases).
  • Curated front page for /rtp menu (Stage B). When a player runs /rtp menu with no arguments, the root page is now a hand-picked landing screen rather than the flat alphabetised reflection of the /rtp command tree. The new FrontPageBuilder (in rtp-core) emits two permission-gated row catalogues: a player view (Teleport / Region picker / Biome picker / Help, picker rows appearing only when the corresponding root parameter is registered and has at least one suggestable value) and an admin view gated by rtp.menu.admin that collapses to a single Admin panel entry row leading into a dedicated curated admin-panel page (PROPOSAL-admin-panel.md v2; see below). Descending into any subcommand falls through to the existing CommandTreeMenuBuilder reflector. Configurable MessagesKeys entries (menuFrontPageSection*, menuFrontPageRow*, menuFrontPageHover*) keep every label and hover under operator control per REQ-RTP-F-013. Covered by FrontPageBuilderTest (7 cases).
  • Curated admin panel for /rtp menu (PROPOSAL-admin-panel.md v2). The single Admin panel entry row on the front page (admin viewers only, gated by rtp.menu.admin) opens a dedicated curated MenuModel built by the new AdminPanelBuilder (rtp-core). The panel organises operator tooling into four self-hiding sections: Configuration (Config editor -> OpenConfigSelector, gated on rtp.config.view), Diagnostics (Server info, Full diagnostics, Memory tracker snapshot when /rtp test memory is registered, Scan control gated on rtp.scan), Lifecycle (Reload gated on rtp.reload, with a warning hover), and Browse (Browse all commands -> reflected-tree fallback). A Back row at the bottom emits the new MenuAction.OpenFrontPage token to return to the curated front page. Section dividers auto-suppress when their entire body is hidden, so a partial-admin viewer never sees an orphan header. Two new no-payload sealed MenuAction variants (OpenAdminPanel, OpenFrontPage) extend the menu surface to 13 permitted types; both round-trip through /rtp menu token:<t> per ADR-035. New MenuRedeemSubcommand.MenuCuratedPageBuilder SAM hosts the two dispatch arms (dispatchOpenAdminPanel gated on rtp.menu.admin, dispatchOpenFrontPage ungated). Seventeen new MessagesKeys entries (menuFrontPageRowAdmin + hover, menuAdminPanelTitle / menuAdminPanelHint, four section dividers, ten row+hover pairs, one back row); eight prior front-page-inline keys (menuFrontPageRow{Info,Config,Scan,Diagnostics,Reload}, menuFrontPageHover{Diagnostics,Reload}, menuFrontPageSectionAdmin) are retired since their content moved to the panel. Covered by AdminPanelBuilderTest (12 cases) and two new BookMenuRendererTest round-trips.
  • maps-api documentation surface (ADR-046, maps-api-ADR-001, 2026-05-16). Authored the documentation layer of the runtime-cartography subsystem ahead of any code landing: five new functional requirements REQ-RTP-MAP-001..005 in REQUIREMENTS.md section 1.7 (require-by-contract MapBinding extending REQ-RTP-S-006; non-blocking ChartRenderer extending REQ-RTP-F-008 / REQ-RTP-S-005; MemoryTracker lifecycle release on cancel / disconnect / disable; Lite-only NoopMapBinding; in-house Mermaid subset with no external runtime, scripting engine, or third-party graph-layout dependency), matching rows in TRACEABILITY.md, and the in-module bootstrap ADR maps-api-ADR-001 locking package layout (mapsapi root + model / render / render.mermaid / noop / bukkit / fabric subpackages, with bukkit the only subpackage allowed to import org.bukkit.*), the logical-palette-now, concrete-table-Stage-2 palette policy (32-symbol PaletteIndex contract, vanilla map-palette bytes carried per-binding), and the assembly-level Lite trim posture (shadow-jar exclusions in rtp-plugin, audited by an extended liteJarStructureCheck clause in Stage 2). Stage-1 SPI skeleton now also landed (2026-05-16, same beta.3 cycle): new maps-api Gradle module (settings.gradle, maps-api/build.gradle java-library + ArchUnit) with the platform-neutral SPI surface — MapCanvas (128x128, logical-palette bytes), MapHandle / MapAllocationRequest (record + Locking enum) / Cancellation, MapBinding (allocate / renderEphemeral / bindLive), sealed ChartModel (Heatmap2D / CategoryDistribution / TimeSeries / RegionCoverage / MermaidChart, all defensively copied), ChartRenderer and the first concrete HeatmapRenderer, the NoopMapBinding (REQ-RTP-MAP-001 / REQ-RTP-MAP-004 default — every entry-point throws IllegalStateException with the documented prefix), four package-info.java cross-references — plus the InMemoryMapBinding test double and four traceable tests: ReqRtpMap001RequireByContractTest, ReqRtpMap002NoChunkIoTest (ArchUnit + manual blocking-future-call scan over mapsapi.render), HeatmapRendererTest, MapsApiSurfaceTest. 25/25 maps-api tests green; .\gradlew build green across every module.

Fixed

  • Occasional mid-air placement at an invalid Y from L3 backlog entries (S-001 regression closed). The L3 backlog refill path (ADR-028) stamps a placeholder Y on each unverified entry before any ground check has run, and the L2→L1 promotion verification in Region previously trusted that Y and only re-tested the single feet-block via RTPChunk.isSafe(localX, y, localZ, ...). When the placeholder happened to land in air (the prior implementation used the vert window's midpoint), the single-block check returned safe and the player was teleported mid-air. The promotion verifier now re-runs the region's VerticalAdjustor.adjust(chunk) against the loaded chunk and uses its returned RTPCoords as the player-facing coordinate — the same ground+headroom sweep the live-spiral path already enforces — so no separate ground predicate has to be kept in sync. Verification still fails closed: any exception or null result drops the entry and purges the DB row. The placeholder Y used during L3 enqueue (where the value never reaches a player and only feeds biome/border probes in PregenTask / ScanTask) is also changed from the vert-window midpoint to the adjustor floor clamped to [world.minHeight, world.maxHeight - 1], so even if a future consumer accidentally trusts it the value is at least inside the searchable window. Regression guarded by RegionPipelineTest.

  • effects-api Folia dispatch hardening for PotionEffect and FireworkEffect (closes the "firework never spawns / IllegalStateException: Asynchronous effect add" symptom on Folia). Both effects now resolve the Plugin caller through EffectsAPI.getInstance() with a graceful S-006 fallback: if init(Plugin) hasn't run, caller degrades to null and the dispatcher seam (PotionEffect.entityDispatcher / FireworkEffect.regionDispatcher) is still consulted so the Folia EntityScheduler / RegionScheduler path is taken when available. Removed an effects-api-layer call to Bukkit.getPluginManager().getPlugin("RTP") that named the host plugin and violated the platform-agnostic boundary of the module; the legacy primary-thread fallback already handles the null-caller case via safeRun(apply). PotionEffect.applyOnEntityThread additionally swallows addPotionEffect failures (IllegalStateException: Asynchronous effect add, invalid effect data) via safeRun so a misrouted effect never propagates back through the teleport caller. Regression guarded by FoliaDispatchTest (4 cases).

  • Locale TSV pipeline corruption in messages.yml::placeholders[0] (closes a recurring pipeline-roundtrip bug). Six locales (es, ja, ko, pt, ru, zh) had accumulated multi-megabyte runs of stacked backslashes plus trailing YAML residue (" #P0) in the placeholders list-head value as the result of repeated locale-files-to-csv / locale-files-from-csv passes mis-handling a value that contained both YAML special characters and an inline comment. Affected locale TSVs were repaired in place to the baseline value [RTP] and the regenerated lang/<loc>/messages.yml files now match the rest of the locale set. The repair was applied in-place to the affected TSVs and YAMLs; no source-tree artifacts remain.

  • Three universally-untranslated config.yml comment blocks translated into all shipped locales (database.port, network.redis.enabled, network.redis.port). These keys were added to baseline in a recent reconcile pass and seeded into every locale TSV from English; no locale maintainer had yet translated them, so every non-English server displayed English Redis/database documentation. Translations now ship for de, fr, es, it, nl, pt, ja, ko, zh, ru, pl (new), and cat (Internet Cat dialect: see Domain Analogies & Aliases in .junie/AGENTS.md clarifying that lang/cat/ is the cat-themed locale, not Catalan; Catalan would be ISO ca).

  • Four new locale trees shipped since beta.2: Italian (it), Polish (pl), Portuguese (pt), and Russian (ru). New lang/<loc>/ trees per TRANSLATION_GUIDE.md section 8 (first-pass / known-stale locales seeded from English baseline under translated keys, ready for native-speaker fill-in). The three new Redis/database comments above are translated into each; broader recurring English-comment translations across all 12 locales are described in the bullet below. All four pass LocaleParityTest. Locale set is now 12: cat, de, es, fr, it, ja, ko, nl, pl, pt, ru, zh.

  • Recurring high-multiplier English comment leaks translated across every shipped locale. A scan of preceding_comment cells in scripts/out/locale-<loc>.tsv identified 27 baseline (file, key) signatures whose comment block was still untranslated in 10-12 locales each (i.e. nearly every shipped locale missed the same row), affecting in-game runtime config descriptions and /rtp info message documentation. Translated comments now ship for all affected locales (cat, de, es, fr, it, ja, ko, nl, pl, pt, ru, zh) for the following signatures: config.yml (database.password, database.name, database.username, playerCommands, menu); messages.yml (badArg, consoleCmdNotAllowed, cooldownMessage, invalidWorld, newWorld, reloading, unsafe, notEnoughMoney, noLocationsQueued, noPerms, queueUpdate, teleportDeniedReloading, infoDatabaseLatencyMs, infoHealthPipelineHeader, infoMSPTLive, infoTps, menuFrontPageHoverDiagnostics, menuFrontPageHoverReload, menuUnknownPlayer); integrations.yml::rerollFactions; metrics.yml (foliaAggregationMspt, foliaAggregationTickBudget, foliaAggregationTps, foliaIncludeRegions); performance.yml (loginCacheEnabled, loginCacheCap). Doc-tag lines (@type:, @range:, @default:, @unit:, @options:, @source:) are preserved verbatim per the in-game runtime-config description contract; only the prose lines that precede them were translated. network.redis.password (which shares base_key with database.password) was correctly preserved by disambiguating via canonical baseline parent path. ~351 TSV rows patched, regenerated YAMLs verified via LocaleParityTest and full gradlew build.

  • New auditing tooling. Added scripts/scan-locale-comment-leaks.ps1 (per-locale English-leak scanner with @type:/@range:/etc. doc-tag stripping per the in-game runtime-config description contract) and scripts/list-common-comment-leaks.ps1 (cross-locale "translate once, apply everywhere" identifier sorted by locale-multiplier). Both honor the rule "ignore the values after @ symbols, but keep the prose": doc-tag lines are stripped before judging residual prose for English connector words, so a comment like # Database / schema name. Used by mysql/postgresql only.\n# @type: string is scanned only on the first line (the in-game description) and not falsely cleared by the @type: tail.

  • REQ- and ADR- references scrubbed from all shipped config-file comments.** Comments in rtp-plugin/src/main/resources/*.yml (baseline) and every lang/<loc>/*.yml previously referenced internal traceability identifiers (e.g. See ADR-015., (ADR-035 / ADR-044), REQ-RTP-F-013: ..., commands-api-ADR-001, effects-api-ADR-005, effects-api-ADR-001) intended as developer-side cross-links to docs/adr/ and docs/dev/REQUIREMENTS.md. These identifiers are noise to operators reading the shipped YAML and have been removed from baseline files (config.yml, language.yml, messages.yml, performance.yml, plugin.yml, safety.yml, regions/default.yml, effects/default.yml) and propagated through the locale TSV pipeline so every lang/<loc>/ mirror is also stripped. Cross-references remain intact in docs/, ADRs, and code-side Javadoc / commit messages.

  • Missing baseline doc-tag lines (@type:, @range:, @default:, @unit:, @options:, @source:) restored on translated comment blocks across every shipped locale, and the previously-English # Note: #minecraft:tall_flowers is an item-only tag in vanilla block in safety.yml translated. When prior locale-maintainers translated only the prose lines of a comment, they sometimes dropped the trailing doc-tag line that the in-game runtime-config description contract relies on; the canonical baseline doc-tag string is language-agnostic and copyable verbatim, so the locale TSV pass now appends any baseline doc-tag line that is missing from the locale's preceding_comment. Doc-tag values after the @ are preserved unchanged; the prose lines that precede them were translated for the tall_flowers block (11 locales patched; Italian already had the translation). 30-36 doc-tag-only patches per locale; regenerated YAMLs verified via LocaleParityTest and full gradlew build.

  • Chinese (zh) locale: 49 untranslated key names in messages.lang.yml translated. New info* health/metrics block keys (infoQueueDepth, infoPendingTeleports, infoAvgPipelineMs, infoHeap, infoHealthPipelineHeader, infoTps, infoMSPTLive, infoSoftCap, infoDatabaseLatencyMs, the six infoThreshold*Green/Yellow rows, infoThresholdNetworkAgeYellow, infoFoliaRegionsHeader, infoFoliaRegion) plus the entire menu* block (27 keys: menuInvalid / menuExpired / menuUnknownPlayer / hover/back/execute/pick/type/constructed/root/page-prev/next / front-page section + row + hover entries) and three stragglers (busy, invalidCommand, version) were shipping as English identity placeholders. Translated to descriptive Chinese names matching the existing 信息_* / 菜单_* naming pattern.

- Inline/trailing comments baked into quoted YAML scalar values cleaned up across 6 locales (es, ja, ko, pt, ru, zh). A prior pipeline pass had collapsed leading-position comment blocks into the value column for rows like pregeneratedPreference: "0.0 # Probability ..." and evento_cambioMundo: "true # Cuando el jugador cambia de mundo" (~44 rows in performance.yml and logging.yml). Fix: trailing # ... text stripped from the value; locale-translated inline text promoted to the row's preceding_comment column (so it renders as a leading description above the key, matching baseline shape and feeding the in-game runtime-config description contract); rows whose inline text was still English (performance.yml: pregeneratedPreference, backlogRefillThreshold) had preceding_comment restored from baseline verbatim. Regenerated YAML tree verified via LocaleParityTest + full gradlew build.

3.0.0-beta.2 - 2026-05-12

Added

  • L3 backlog cache (ADR-028) is now implemented (ADR-028, Accepted 2026-05-07). New optional RegionQueueManager.backlogLocations (BacklogLocationBuffer) sits upstream of L2 unkeptLocations: spiral picks land as unverified entries (no chunk I/O, no DB row), each Region.execute() pulse anvil-verifies one .mca bin (32×32 chunks; cross-RTP-region amortized via a world-shared weak-ref bin index), and head-contiguous VALIDATED entries promote into L2. Head-blocking on UNVERIFIED preserves spiral order; INVALIDATED heads drop without stalling. New per-region backlogCacheCap knob in regions/<region>.yml (default 1000 on the main jar; lite omits the key so the in-code fallback resolves to 0 ⇒ L3 disabled). Not persisted to the DB by design — restart re-selects fresh entries. Covered by BacklogLocationBufferTest and WorldBacklogBinIndexTest (21 cases).
  • Initial Fabric (rtp-fabric) platform support for Minecraft 1.21.x. Beta.1 shipped a non-functional Fabric source tree marked out of scope; beta.2 turns it into a working adapter with /rtp teleporting end-to-end: async chunk path (no synchronous main-thread loads), Brigadier command tree (RTPCmdFabricRoot) with parameter and subcommand parity matching Bukkit (5 parameters, 5 of 6 subcommands), tab-complete at the /rtp root, anvil pre-filter parity, multi-version support (1.20.x / 1.21.x including 1.21.11), and permissions via fabric-permissions-api with an ops.json fallback. Covered by rtp-fabric-ADR-001 through rtp-fabric-ADR-007. Known Fabric limitations (see Known Issues below): permission-based effects do not fire, and SQL database backends are not wired (SQLite fallback only; MySQL/PostgreSQL/H2 are unplanned on Fabric). Deferred to a later release: TestCmd lift, event-bus wiring, online-player tab-complete.
  • GlideEffect in effects-api (effects-api-ADR-001) — folds addons/RTP_Glide into effects-api as a first-class effect with a shutdown-time safe-landing fallback and a new PlayerLandEvent.Reason.
  • FixedAdjustor vertical adjustor (vert: FIXED). Third engine alongside LINEAR / JUMP; places the player at a single configured Y in mid-air for skyblock-style worlds (requires the platform tool). Covered by FixedAdjustorTest.
  • pregeneratedPreference performance knob — new double-valued setting in performance.yml (range [0.0, 1.0], default 0.0) that probabilistically rejects candidate chunks whose column has not yet been generated on disk, biasing the location selector toward pregenerated terrain while still allowing fallback to ungenerated land. The same weighted gate is applied at the two coordinate-generation sites that feed the caches: the L1 live spiral inside PregenTask.runAttempt() (upstream of the anvil pre-filter), and the L3 backlog refill inside Region.processBacklog() Step 1 (right after Shape.select(), before the unverified entry is enqueued). The check is rejection sampling -- a rejected pick simply advances to the next shape draw, so no validation effort is wasted on locations that the operator's pregeneratedPreference would later drop. Both paths share Region.pregenPrefRejects() and use the existing non-blocking RTPWorld.isChunkGenerated probe (S-005 safe -- no chunk loads triggered). Dropped candidates on the L1 spiral path are attributed to the new LocationGenerator.FailTypes.ungenerated bucket for /rtp info and rtp test full auditing; L3 refill rejections are silent (the candidate never entered any cache). Default 0.0 preserves prior behavior; 1.0 strictly avoids ungenerated chunks. The L3 refill loop additionally caps consecutive rejections per pulse at max(16, backlogCapacity), so a high-weight setting on a sparsely-pregenerated world cannot turn rejection sampling into an unbounded spin -- once the cap trips, the refill yields the remainder of the pulse to the deficit loop and other consumers and retries on the next pulse. The L1 spiral path is bounded by the existing maxAttempts ceiling (each rejected pick consumes one attempt). Covered by PregeneratedPreferenceTest (8 cases including a bounded-refill regression guard).
  • Declarative effect-group configuration via effects/<group>.yml (effects-api-ADR-005). Each file under <pluginDir>/effects/ declares a named group with fields when: (pipeline stage), optional permission: / players: / inherit:, and a required effects: token list (same grammar as rtp.effect.<stage>.* permission suffixes). Loaded via the existing MultiConfigParser<EffectsGroupKeys> plumbing — no bespoke loader class — so per-locale effects.lang.yml field-key remap and /rtp reload hot-swap come for free. The plugin now registers an effects/ parser in Configs.reloadConfigs(); BukkitEffectsHandler and FabricEffectsHandler re-resolve groups per teleport via a new EffectsResolver.resolveUnioned(...) helper that unions permission-derived nodes with config-driven tokens before feeding EffectFactory.buildEffects(prefix, ...). Fabric admins now have a usable effect-configuration surface without fabric-permissions-api; Bukkit admins gain a permission-less complement to the existing rtp.effect.* permission tree.
  • /rtp info health block + bStats RTP cost-metric charts (METRICS_PLAN.md, Phase M1+M2 vertical slice). /rtp info now appends four operator-facing live-state lines sourced from a single RTP.metrics.snapshot() call: players waiting in region queues ([queueDepth]), in-flight teleport pipelines ([pendingTeleports]), rolling-mean pipeline latency ([avgPipelineMs], ms), and JVM heap usage ([heapUsedMb] / [heapMaxMb]). Seven new placeholder tokens — queueDepth, pendingTeleports, avgPipelineMs, heapUsedMb, heapMaxMb, memoryEntries, chunkLoadBacklog — are usable in any messages.yml line and via PlaceholderAPI. The bStats integration (full id 30865, lite id 12277) registers eleven new charts via RTPCostMetricsCharts: configuration adoption (platform, assembly_variant, database_backend), region_count (single-line), cache_pool_health (multi-line, L1 / L2 % fill), and bucketised cost histograms (tps_buckets, mspt_buckets, pipeline_latency_buckets, memory_tracker_pressure, chunk_load_backlog_pressure, queue_depth_pressure). All bucketing is privacy-safe (no raw scalars, no server / region / world identifiers); chart lambdas read pre-computed snapshot fields and never call platform APIs inline. Per-platform MetricsBinding for TPS (Folia, Fabric, Spigot fallback) and the runtime-health charts that depend on it (e.g. s005_violations_recent) remain deferred to a follow-up — TPS lambdas use a reflective Bukkit.getServer().getTPS() lookup as an interim probe and report unknown when unavailable.
  • bStats pipeline_latency_buckets chart implements ADR-032 (ADR-032, Proposed 2026-05-05). A 256-sample wait-free ring-buffer histogram of teleport-pipeline latency feeds the pipeline_latency_buckets AdvancedPie chart described above; the ring is never reset and ages out via overwrite. Privacy-safe (bucketised only).

Changed

  • effects-api platform-split for Fabric readiness (effects-api-ADR-003; effects-api-ADR-004 amends ADR-002). Effect and EffectFactory moved to effectsapi.common and decoupled from org.bukkit.* (now implements Runnable, Cloneable); Bukkit-side concretes, listeners, commands, and events relocated under effectsapi.bukkit.*; token coercion routed through a per-platform ValueCoercer SPI; Bukkit registration and scheduling extracted to BukkitEffectsInitializer. Addon migration: import prefix changes from io.github.dailystruggle.effectsapi.{LocalEffects,BukkitListeners,commands,events}.* to io.github.dailystruggle.effectsapi.bukkit.*; subclasses that called inherited BukkitRunnable methods (runTaskTimer, cancel, isCancelled, etc.) directly will no longer compile; subclasses that only override run() are unaffected.
  • Bundled docs/ tree inside release jars trimmed to admin- and addon-author-facing material. rtp-plugin's copyDocs no longer ships internal dev docs.
  • MULTI_SERVER_PLAN.md updated to treat multi-proxy deployments as first-class (docs only; D-005 gated, no code changes). Adds a Multi-Proxy Deployment section covering HA / failover, geo-distributed proxies, capacity scaling, and blue/green proxy upgrades; introduces a per-proxy proxyId field in the network.yml straw-man (analogous to per-backend serverId); locks in design rules for proxies (no proxy-to-proxy chatter, no singleton assumption, idempotent operations, advisory-only local state, per-proxy heartbeat row); documents hot-spot avoidance under multiple proxies and reservation-token / network-wait-queue behaviour under proxy races and proxy death; adds REQ-RTP-NET-009 / REQ-RTP-NET-010 stubs; bumps the Phase 2 acceptance baseline to 2× Velocity (behind L4) + 2× Paper.
  • MULTI_SERVER_PLAN.md documents DragonflyDB (and other RESP-compatible servers) as supported Redis-transport drop-ins (docs only; D-005 gated, no code changes). The redis transport type covers Redis, DragonflyDB, and KeyDB through the same RedisNetworkStateBinding — only the connection URL differs, no transport.flavour knob, no per-flavour code branches. Redis remains the reference implementation; Phase 2 acceptance gains a parallel container exercising the cross-server /rtp round-trip against DragonflyDB on the unmodified binding, with any observed RESP divergence (Lua/EVAL, Streams consumer groups, persistence semantics) recorded in LESSONS_LEARNED.md rather than branched on. The post-implementation Postgres-vs-Redis comparative benchmark grows a third row for Dragonfly to give operators evidence-based guidance on when its multi-threaded single-node design is worth choosing.
  • Fabric is supported by the RTP-lite assembly variant (ADR-024, 2026-05-07 amendment). The lite jar now ships RTPFabricMod, the rtp-fabric-common classes, and fabric.mod.json, so Fabric Loader can discover RTP from the unclassified RTP-<version>.jar instead of requiring RTP-Pro. JDBC drivers (H2 / SQLite / MySQL / PostgreSQL) remain stripped from lite, so Fabric+lite operators land on FabricDatabaseHandler.setupDatabase's flat-file YAML fallback (a loud warning is logged); operators who want a SQL backend on Fabric must run the Pro jar. Folia remains full-only.
  • Claim-plugin integrations are supported by the RTP-lite assembly variant (ADR-024, 2026-05-11 amendment). Lite now invokes ClaimIntegrations.setup from RTPBukkitLitePlugin.onEnable (deferred tick+1) and declares softdepend: [ GriefDefender, GriefPrevention, Towny, HuskTowns, Factions, Lands, RedProtect, WorldGuard ] in its plugin.yml; integrations.yml is bundled in the lite jar so ClaimIntegrations#buildParser can load its defaults from the classpath. Pro stays the superset target for large-scale deployments (proxy networks, Folia, SQL/Redis persistence); claim-protection support is a baseline operator expectation on the small Spigot/Paper servers lite primarily serves, so withholding it pushed those operators to Pro for an integration that has zero runtime cost when no claim plugin is installed. Vault/economy and PlaceholderAPI remain Pro-only.
  • Multilingual support (language options) is supported by the RTP-lite assembly variant (ADR-024, 2026-05-11(b) amendment supersedes the original ADR-020 drop). Lite now ships lang/** and language.yml, and the full (un-trimmed) messages.yml from rtp-plugin/src/main/resources. No explicit bootstrap call is required: LanguageBootstrap.resolve(pluginDirectory) is invoked unconditionally from Configs#reloadConfigs(), and LanguageCmd (the /rtp lang subcommand) lives in rtp-core and is registered via the shared command tree, so it is available on lite identically to Pro. Lite-irrelevant messages.yml keys (e.g. notEnoughMoney, PAPI status, SQL-persistence messages) are unreachable at runtime because the underlying subsystems are not wired; their presence in the file is harmless and matches the "lite contains the featureset, simply not configured by default" stance. The liteJarStructureCheck audit no longer forbids lang/** or language.yml. Pro stays the superset target for large-scale deployments; locale parity is a baseline operator expectation that previously pushed multilingual servers to Pro for a feature with zero runtime cost on single-locale installs.
  • Fabric obf/unobf carrier split (rtp-fabric-ADR-009, effects-api-ADR-006). Two new Loom-built carrier modules — rtp-fabric/rtp-fabric-common-unobf/ and effects-api/effects-api-fabric-unobf/ — host Mojmap-unobfuscated mirrors of the NM-typed surfaces (FabricRTPWorld, FabricRTPChunk, FabricRTPPlayer, FabricEffectRuntime, the four LocalEffects, FabricValueCoercer, FabricRegistryCompat, FabricLegacyText, FabricPaletteNormalizer, FabricAnvilColumnProbeAdapter) so the deobfuscated MC 26.x runtime family links cleanly without intermediary class_NNNN aliases. Intermediary-bearing 1.20.x / 1.21.x runtimes continue to use the original obf-carrier modules unchanged; runtime selection is dispatched via the new FabricVersionAdapter#installEffectsWiring(Object) SPI (default false, overridden only by V26_1_R1FabricVersionAdapter to install the unobf path). Non-API: rtp-fabric-common[-unobf] and effectsapi.fabric* are internal carriers, so addon authors require no migration. Carrier-disjointness is regression-guarded by EffectsApiFabricCarriersDisjointTest and RtpFabricCarriersDisjointTest.
  • Translations expanded. New locale trees added since beta.1: Japanese (ja), Korean (ko), Simplified Chinese (zh), and a cat dialect (cat); existing locales (de, es, fr, nl) gained additional *.lang.yml overlays. Per the Known Issues note below, localized overlays still cover only the static config files (config.yml, safety.yml, performance.yml, messages.yml, effects.yml) — not the dynamic worlds/, regions/, effects/ directories.

Fixed

  • safety.yml and biome-filter edits now invalidate the persisted shape cache (closes the [3.0.0-beta.1] Known Issues entry; was a tracked follow-up in docs/dev/POTENTIAL_BUGS.md). RegionCacheKey.canonicalize(...) now folds a deterministic snapshot of the validity-affecting subset of safety.yml — safetyRadius, platformRadius / platformAirHeight / platformDepth / platformMaterial, airBlocks, unsafeBlocks, anvilPrefilterEnabled, biomeWhitelist, biomes — into the shape-cache hash inputs, with list values lower-cased and sorted so re-orderings do not invalidate cached MemoryShape data. Cosmetic and runtime-only keys (invulnerabilityTime, staleChunkRetryLimit, version) are explicitly excluded. RegionCacheKey.SCHEMA_VERSION is bumped from 1 to 2, so every existing <region>_<seed>_<12hex>.bin / .scan file and every rtp_cached_locations row from a beta.1 install is naturally orphaned on first launch and re-scanned under the corrected predicate. An allowlist regression guard fails CI if a future SafetyKeys constant is left unclassified. Covered by RegionCacheKeyTest (10 cases).
  • Effect permission tokens with skipped earlier inputs no longer wreck the rest of the chain (effects-api-ADR-002). Effect.setData(String...) now walks a per-effect KEY_ORDER with a non-rewinding cursor, assigning each token to the first remaining key whose default type accepts it. Removes a printStackTrace path. Covered by EffectsApiAdaptiveReadingOrderTest.
  • Per-permission effects did not fire under RTP-lite. Lite bootstrap now schedules BukkitEffectsHandler.setupEffects at tick+1 and re-introduces effectParsing: true in the lite performance.yml.
  • Fabric platform bring-up — intermediary mapping parity across hot-path entry points (rtp-fabric-ADR-009 SPI extension; consolidates work that brought the Fabric adapter from non-functional in beta.1 to a working /rtp end-to-end). Several call sites in rtp-fabric-common previously dispatched through reflection on mojmap names (getPlayer, getUUID, getCommands, createCommandSourceStack) and silently failed on intermediary 1.20.x / 1.21.x runtimes where those methods are obfuscated to method_xxxxx. Replaced each with a typed FabricVersionAdapter SPI method (extractPlayerFromConnection, getPlayerUUID, resolveSenderUuid, dispatchConsoleCommand, installEffectsWiring) dispatched via FabricVersionAdapterRegistry.peek(); per-version adapters (v1_20_R1, v1_21_R1, v1_21_R5, v1_21_R11, v26_1_R1) implement each override with direct typed calls so Loom remaps descriptors to the runtime's mapping at compile time. Covers join/disconnect player tracking (FabricEventBridge), FabricServerAccessor.{register,unregister}PlayerObject, /rtp sender resolution in FabricBrigadierSourceBridge, and post-teleport consoleCommands dispatch. Zero reflection on the relevant hot paths. Regression guarded by FabricEventBridgeAdapterDispatchTest.

  • Default permissions on Fabric now mirror plugin.yml when no permissions mod is installed. FabricRTPPlayer.hasPermission (and the unobf / 26.1 mirrors) previously fell through to the ops.json op-check whenever no fabric-permissions-api implementer (LuckPerms-Fabric, Cyan, Ledger, ...) was registered. Baseline player nodes such as rtp.see and rtp.use (declared default: true in plugin.yml) were therefore silently denied to non-ops, breaking /rtp on a vanilla-permissions Fabric install; conversely, rtp.onevent.* (declared default: false) would have been granted to ops if anything queried them, contradicting the descriptor. Added a shared FabricDefaultPermissions table (mirrored as FabricDefaultPermissionsUnobf on the unobf classpath) that resolves each node to TRUE / FALSE / OP straight from plugin.yml defaults. Resolution order is now perms-api -> default table -> ops.json: TRUE grants to everyone, FALSE denies even ops, OP falls through to the existing ops.json scan, and unknown nodes (addon-defined, wildcard-expanded rtp.worlds.<world> / rtp.regions.<region>, etc.) default to OP to match their parent wildcard's convention.

Known Issues

Fabric-only:

  • Permission-based effects on Fabric require a fabric-permissions-api implementation. All nine pipeline-stage hooks (rtp.effect.presetup / postsetup / preload / postload / preteleport / postteleport / cancel / queuepush / queuepop) are wired on Fabric identically to Bukkit (FabricEffectsHandler.setupEffects), but rtp.effect.<stage>.<token> permission tokens are only consulted when a permissions-api implementer (LuckPerms-Fabric, Cyan, Ledger, ...) is installed. On a vanilla-permissions Fabric server the union falls back to effects/<group>.yml (effects-api-ADR-005) only — which is the recommended configuration surface on Fabric regardless.
  • SQL database backends are not available on Fabric. Only the SQLite fallback is wired. MySQL, PostgreSQL, H2, Redis, and YAML accessors are unplanned for Fabric. Bukkit-family platforms are unaffected.
  • Block-tag registry occasionally logs Block-tag registry yielded no usable tags during Fabric startup. Tag resolution races mod / datapack registry population on some load orders; RTP retries resolution after server startup completes, so the warning is informational and tag-driven safety predicates remain in effect once startup finishes. Bukkit-family platforms are unaffected.
  • Performance considerations on Minecraft 1.20.1 (Fabric). On 1.20.1 specifically, holding chunk tickets at the level used by other platforms causes vanilla's tick pipeline to retain CompletableFuture dependent graphs proportional to held tickets, producing significant heap growth over time on otherwise idle servers. RTP's 1.20.1 adapter mitigates this by holding kept-cache tickets at BORDER level (loaded but not entity-ticking), which preserves teleport correctness but means kept-cache chunks do not tick mobs, redstone, or weather while reserved. 1.21.x is unaffected. Operators on 1.20.1 should expect somewhat higher baseline memory use than on 1.21.x even after the mitigation, and may want to keep cacheCap / keptCache modest until they upgrade.

All platforms:

  • Translations do not apply to dynamic config directories (worlds/, regions/, effects/). Localized lang/<locale>/*.lang.yml overlays cover the static config files (e.g. config.yml, safety.yml, performance.yml) but per-world, per-region, and per-effect files generated under those directories remain in the default language regardless of the configured locale. Affects Bukkit-family platforms (Spigot, Paper, Folia) and Fabric.

3.0.0-beta.1 - 2026-05-03

?? Major release - breaking rtp-api changes. See MIGRATION.md for upgrade instructions.

Beta Scope

This is a beta release. The following surface is considered in scope and supported:

  • Platforms: Spigot, Paper, Folia (Minecraft 1.20.x / 1.21.x / 26.1, Java 21+).
  • Persistence: H2 (default) and SQLite. MySQL, PostgreSQL, Redis, and YAML fallback ship but are experimental - production use not recommended.
  • Public API: the rtp-api types listed under Added. Internals (rtp-core, platform adapters) may still change between betas.
  • Claim integrations (folded into the plugin per ADR-019): Factions, GriefDefender, GriefPrevention, HuskTowns, Lands, RedProtect, TownyAdvanced, WorldGuard.
  • Anvil pre-filter on Spigot (ADR-016).
  • Brigadier bridge for Paper/Folia (commands-api-ADR-001).

Out of scope for this beta (do not file as bugs):

  • Fabric (rtp-fabric) - present in the source tree but not functional. /rtp does not yet teleport on Fabric (scheduled-task processors not wired; permissions, teleport-cancel callback, and full Brigadier command tree pending). Tracking: docs/dev/MULTI_PLATFORM_PLAN.md. Do not deploy on Fabric.
  • Native Forge / NeoForge adapter - not planned, and lower priority than multi-server / proxy support. Forge-based servers are supported via Bukkit-compatibility layers such as Arclight or Mohist (run RTP as the Spigot/Paper build on those launchers). A dedicated Forge/NeoForge adapter remains deferred (ADR-022, MULTI_PLATFORM_PLAN Phase 4) and may not materialize if compatibility layers continue to cover the use case.
  • Multi-server / proxy mode (Velocity, BungeeCord cross-server queues, reservation tokens) - design only. See docs/dev/MULTI_SERVER_PLAN.md.
  • Legacy Minecraft (< 1.20) and legacy Java (< 21) - see ADR-021.
  • RTPEconomy API - present but marked experimental; signature may change before 3.0.0 final.
  • /rtp config command - present but experimental; subcommand surface, argument grammar, and write-back semantics may change before 3.0.0 final. Prefer editing config files directly for production use.
  • Lite assembly variant (ADR-024) - produced from this build but not yet published on a fixed cadence. From 3.0.0 final onward, the Lite jar will be published as RTP (the free tier) a few hours-to-days after the corresponding RTP-Pro (full / paid tier) jar of the same version.

Known Issues

User-visible issues that exist in this beta and are not considered release-blockers. File a new bug only if your symptom differs from the descriptions below.

  • Fabric adapter is non-functional. See Out of scope above. Bukkit-family platforms are unaffected.
  • MySQL / PostgreSQL / Redis / YAML accessors are experimental. Schema and migration semantics may change before 3.0.0 final. Stick with H2 or SQLite for production.
  • safety.yml and biome-filter edits do not invalidate the persisted shape cache (POTENTIAL_BUGS.md, 2026-04-30 entry). Geometry and vertical-adjustor edits are caught (ADR-022); changes to unsafeBlocks, platform, requireSkyLight, ADR-017 tag/state predicates, or per-region biome whitelists/blacklists may leave stale "bad sector" flags in <region>_<seed>_<hash>.bin. Workaround: /rtp scan reset <region> after changing safety predicates.
  • Tag-grammar tokens in safety.yml (e.g. #minecraft:flowers) are accepted but inert until the config-reader tag-expansion slice lands (SAFETY_TAGS_AND_STATES_PLAN.md Slice 3). Use explicit material names for now.
  • Two ADR files share the number ADR-022 (POTENTIAL_BUGS.md, 2026-05-01). Documentation only; no runtime effect. Cross-references in this changelog disambiguate by filename.
  • Pre-release cache invalidation: legacy 2.x .bin files and existing rtp_cached_locations rows from any pre-3.0.0-beta.1 build are abandoned by ADR-022's hash-keyed naming scheme. Expect a one-time re-scan on first launch.
  • Emergency landing platform default changed. safety.yml now ships platformRadius: -1 (disabled). Set platformRadius: 0 or higher to restore legacy 2.x behaviour.

For a live backlog of incidental bugs spotted during development (not necessarily user-visible), see docs/dev/POTENTIAL_BUGS.md.

Planned for 3.0.0 final and beyond

Roadmap visibility for users and addon authors. Order is intent, not commitment.

  • Fabric platform to first-class (rtp-fabric) - targeted for 3.0.0 final. Active frontier - see MULTI_PLATFORM_PLAN.md. Remaining: scheduled-task processor parity (Step E3), permissions via fabric-permissions-api (Step F), full Brigadier command tree (Step G2), stabilization smoke test (Step H).
  • Fold safety.yml validity fields and biome filters into the region cache hash (POTENTIAL_BUGS.md follow-up to ADR-022).
  • Multi-server / proxy mode (Velocity, BungeeCord) - phased rollout per MULTI_SERVER_PLAN.md. D-005 gated; admin docs stub at docs/admin/proxies/INDEX.md.
  • Runtime metrics (TPS / MSPT / heap / queue depth / pipeline samples) - METRICS_PLAN.md.
  • External hook API surface (ADR-026, EXTERNAL_HOOKS.md) - formal registry for third-party reflection / soft-depend integrations.
  • Lite assembly variant (ADR-024) - trimmed jar for resource-constrained servers, published as RTP (the free tier) a few hours-to-days after the corresponding RTP-Pro (full / paid tier) jar of the same version. The Pro jar ships first; the free Lite jar (RTP) follows once the trimmed assembly is verified against the same release tag.
  • Promote MySQL / PostgreSQL / Redis / YAML accessors out of experimental.
  • Stabilize RTPEconomy API.
  • Stabilize /rtp config command - finalize subcommand surface, argument grammar, and write-back semantics, then drop the experimental label.
  • Forge / NeoForge - lower priority than multi-server / proxy support. No native adapter planned for the foreseeable future; Forge-based servers should use a Bukkit-compatibility launcher (Arclight, Mohist, or equivalent) and run the Spigot/Paper build. A dedicated adapter is only re-evaluated if those compatibility layers stop covering the platform (rtp-fabric-ADR-002).

Highlights

  1. Versioned platform submodules - compile-time NMS separation via a common module plus per-version submodules for Spigot, Paper, and Folia (ADR-010).
  2. Stable public rtp-api - broadened addon surface; no more reflection into internals (ADR-011).
  3. Multi-backend persistence - flat-file sector cache replaced by SQL-backed storage (H2 default, SQLite, MySQL, PostgreSQL) with Redis caching and YAML fallback (ADR-002). H2 and SQLite are production-ready; MySQL/PostgreSQL/Redis/YAML remain experimental.
  4. Per-platform scheduling pipelines - Folia uses regional-thread scheduling; Paper uses native async chunk loading (PaperLib removed); Spigot uses the Bukkit scheduler (ADR-004 - 006).
  5. Lock-free location buffer & state-based tasks - LockFreeLocationBuffer decouples pre-generation from teleport dispatch; explicit task states enable pause/resume/cancel and concurrent region fills.
  6. ChunkReservation lifecycle - AutoCloseable abstraction eliminates the 2.x ticket leak (ADR-012).
  7. Multi-platform expansion - rtp-fabric adapter (in progress) and commands-api / effects-api consolidated as sub-modules.
  8. Anvil read-only pre-filter - off-tick safety probing of unloaded chunks on pure Spigot (ADR-016).

Rationale for each decision lives in docs/adr/.

Added

Public API (rtp-api) - new types include RTPAPI, ILocationGenerator, GenerationContext / GenerationResult, RTPScheduler / TrackedRTPTask, RTPServerAccessor, RTPEconomy (experimental), RTPCommandSender / RTPPlayer, RTPWorld / RTPChunk / ChunkSet, RTPCoords (record) / MutableRTPCoords, RTPLocation, MessagesKeys, RTPRunnable, PerformanceTracker, and ChunkReservation. Precondition / postcondition / thread-safety Javadoc added to RTPAPI, ILocationGenerator, and ChunkReservation.

Platform adapters - restructured into versioned submodules with a shared common module (ADR-010): - rtp-folia, rtp-paper, rtp-bukkit each ship -common, -v1_20_R1, -v1_21_R1, -v26_1_R1. - New rtp-fabric adapter (work in progress; see docs/dev/MULTI_PLATFORM_PLAN.md).

Persistence - AbstractSQLDatabaseAccessor foundation with concrete H2, SQLite, MySQL, PostgreSQL accessors, plus RedisManager and YamlFileDatabase fallback.

Performance & scheduling - LockFreeLocationBuffer, state-based scan/teleport tasks, per-region Folia rate limiting, per-platform pipelines, and PerformanceTracker instrumentation. Region-cache async callbacks and chunk-load wall-clock time are now attributed to pluginMSPT. RTPCoords is a record to reduce hot-path allocation.

Commands - /rtp scan reset [region] clears a region's MemoryShape bad-sector data without restarting a scan. New operator diagnostic /rtp test chunk-probe-perf [samples=<n>] A/B-times RTPWorld.probeChunkColumn against RTPWorld.getChunkAtAsync over a random sample of pregenerated chunks discovered by scanning the world's region/ folder; reports pool size, totals, per-sample averages, the full/probe ratio, and the probe-null rate (BIOME_LOOKUP_PERF_PLAN phase 0). Now also times full-anvil AnvilReader.readChunk for pairwise comparison.

Brigadier bridge in commands-api (commands-api-ADR-001, REQ-API-ARCH-005). BrigadierCommandAdapter and BrigadierBridgeContext<S> (under commands-api/.../brigadier/) walk a commands-api TreeCommand and emit a Brigadier LiteralArgumentBuilder with literal sub-command nodes, typed argument nodes for IntegerParameter / FloatParameter / BooleanParameter, string-with-suggestions for EnumParameter / CoordinateParameter / unknowns, and requires(...)-gated permissions. Brigadier is compileOnly on commands-api, so Bukkit-family runtimes never load the adapter. New RTPCmdFabric.register(...) shim in rtp-fabric-common exposes a one-call hookup for the eventual Fabric CommandRegistrationCallback. Purely additive - BukkitTreeCommand remains the production dispatch path on Bukkit-family platforms. Covered by ReqApiArch005BrigadierBridgeTest (3 tests). The Fabric CommandRegistrationCallback wiring itself stays deferred to Phase 3 / 4 per MULTI_PLATFORM_PLAN.md.

Documentation & governance - docs/dev/REQUIREMENTS.md with full REQ-ID coverage, including new REQ-RTP-S-001..S-006 prohibitions cross-linked to docs/admin/HAZARDS.md. - docs/dev/TRACEABILITY.md (69 REQ-IDs; addon requirements pending audit), docs/dev/GLOSSARY.md, docs/dev/STAKEHOLDERS.md, docs/dev/CONCEPTS.md, docs/dev/DESIGN.md, docs/dev/COVERAGE_PLAN.md, docs/dev/MULTI_PLATFORM_PLAN.md. - docs/adr/ - ADR-001 through ADR-013 and index (README.md); commands-api-ADR-001 (Brigadier bridge), ADR-015 (stale-chunk guard), ADR-016 (Anvil pre-filter) added later in the beta cycle. - docs/admin/ - MIGRATION.md, QUICK_START.md, COMMANDS.md, CONFIGURATION.md, FAQ.md, HAZARDS.md (H-001..H-010), FAILURE_MODES.md (FM-001..FM-009), RUNBOOK.md (7 incident scenarios). - Audience landing pages: docs/FOR_ADDON_DEVELOPERS.md, docs/FOR_CONTRIBUTORS.md, docs/FOR_SERVER_ADMINS.md. - Root-level CONTRIBUTING.md, SECURITY.md, CHANGELOG.md, and addons/REQUIREMENTS.md. - Module dependency diagram and ADR index link in docs/dev/ARCHITECTURE.md.

CI / tooling - Gradle workflow (gradle.yml) replaces Maven (maven.yml) on Java 21 with Spotless, JUnit publishing, and Jacoco upload; check_traceability.sh gate in Jenkins and GitHub Actions; .github/dependabot.yml, .github/PULL_REQUEST_TEMPLATE.md, and .github/ISSUE_TEMPLATE/config.yml.

Changed

  • Claim-plugin integrations folded into rtp-plugin (ADR-019). The RTP_ClaimPluginIntegrations addon is removed; the eight checkers (Factions, GriefDefender, GriefPrevention, HuskTowns, Lands, RedProtect, TownyAdvanced, WorldGuard) now register at plugin startup in ClaimIntegrations. integrations.yml ships with the plugin jar; behaviour for REQ-RTP-S-003 is unchanged (verifiers still live behind GlobalRegionVerifiers). A new addons/RTP_ExampleAddon replaces the claim addon as the canonical "how to write an addon" template.
  • /rtp fill -> /rtp scan (permission rtp.fill -> rtp.scan) for clarity.
  • CachedLocation is now an immutable Java record (breaking for addons that mutated fields directly).
  • rtp-paper: PaperLib dropped in favour of native Paper async chunk loading.
  • Platform version targets upgraded to 26.1 (Spigot, Paper, Folia); Java target raised to Java 21.
  • Active task tracking moved to MemoryTracker with WeakReference deallocation; write-through caching consolidated.
  • Independent region queues now fill concurrently without a shared global-queue lock.
  • sendMessage call-site tracking now uses stack trace source for diagnostics.
  • Allocation reduced on hot paths (records, primitives, vectors removed); MemoryShape pending-write storage switched from maps to sets.
  • Region decomposed for cohesion.
  • ScanTask diagnostics (BIOME_LOOKUP_PERF_PLAN.md PR-16). Extended the [DEBUG_LOG] ScanTask concurrency ... line with avgColdMissMs (average Files.readAllBytes wall time per cache miss) and gcDeltaMs (cumulative GC time since previous log window) so operators can discriminate between OS page-cache pressure, GC churn, and driver-loop bottlenecks when scan throughput degrades with scan progress. Diagnostic-only, no behavior change.
  • ScanTask per-bin drain removed + stage-2 instrumentation (BIOME_LOOKUP_PERF_PLAN.md PR-17). PR-16 runtime data ruled out I/O and GC as causes of cps degradation (both metrics stayed flat while peakInFlight dropped 50 ? ~25 over three minutes), pointing at driver-side pipeline bubbles. Removed the inFlightGate.acquire(MAX_PENDING_CHUNKS) drain between region-file bins in ScanTask.run: PR-15 coalescing already makes cross-bin cache interference cheap, so the barrier was costing saturation without earning correctness. Added fullLoads=N fullLoadAvgMs=X.XX to the gauge log (AtomicLong counters wrapped around runFullLoadPath's result future) so operators can confirm whether stage-2 cost (loaded-chunk safety scan) grows with scan progress; if fullLoadAvgMs climbs while avgColdMissMs stays flat, the next optimization target is the full-load path, not the probe.
  • Biome-lookup performance plan (BIOME_LOOKUP_PERF_PLAN.md PR-1 through PR-12). A sequence of commits retired Region.maxBiomeChecksPerGen + PregenState.maxBiomeChecks in favor of a single maxAttempts knob; added probe-first fast paths in PregenTask and ScanTask backed by RTPWorld.probeChunkColumn (overridden on Bukkit / Paper / Folia to read the chunk's center column directly from the persisted r.X.Z.mca via AnvilReader.readColumnProbe); wrapped the result through AnvilColumnProbeAdapter (applies PaletteNormalizer::reconcile); gated on SafetyKeys.anvilPrefilterEnabled + isChunkLoaded. New LocationGenerator.FailTypes.prefilterBiome / prefilterBlock / prefilterRange buckets attribute the rejections. VerticalAdjustor gained requiresSkyLight(). ScanTask reframes the probe as a load-replacement: on cache-miss the probe is authoritative (skip getOrLoadChunk); on cache-hit the safety radius upgrades to max(configured, 2) for free. Blocking I/O moved to a dedicated AnvilIoPool (max(8, 2 * CPU) daemon threads) to avoid ForkJoinPool.commonPool starvation. Added AnvilRegionByteCache (LRU of raw .mca bytes, mtime-invalidated) to eliminate redundant per-chunk Files.readAllBytes of the same ~4 MB region file; PR-11 added hit/miss/stale diagnostics surfaced in ScanTask's existing [DEBUG_LOG] ScanTask concurrency ... line; PR-12 raised cache capacity from 4 to 16 (~64 MB steady-state) after PR-11 measurement showed the 4-entry LRU thrashing at ~0.31 hit rate because the scan frontier spans 6-10 distinct region files simultaneously. Measured full/probe ratio is 16.46x on Bukkit and 20.70x on Folia via /rtp test chunk-probe-perf.

  • Region shape cache key now folds shape and vertical-adjustor config (ADR-022). Persisted MemoryShape data and ScanTask progress files were keyed only by <regionName>_<worldSeed>, so edits to centerX/centerZ, minRadius/maxRadius, spatialResolution, the shape class, or the vertical adjustor silently reused stale per-cell "bad" flags whose spiral mapping no longer matched the configured region. Filenames are now <regionName>_<seed>_<12hex>.bin / .scan, where the 12-hex suffix is a stable SHA-256 of (SCHEMA_VERSION, seed, shape FQCN + sorted shape data, vert FQCN + sorted vert data). The same hash, truncated to 64 bits, is written into the existing rtp_cached_locations.seed BIGINT column, so cached RTPLocation rows are invalidated under the same predicate without a database schema migration. Region.setSettings(...) deletes orphaned .bin / .scan files when the hash changes; ScanTask.delete(regionName) now sweeps every <regionName>_*.scan file. Region cache hydration moved off the calling thread onto RTP.scheduler.runTaskAsynchronously so DB I/O can no longer stall plugin init. Pre-release: legacy .bin files and existing rows are abandoned (no migration). safety.yml validity fields and biome filters are not yet folded into the hash; tracked as a follow-up entry in docs/dev/POTENTIAL_BUGS.md.

Fixed

  • ScanTask probe-first fast path rejected passable non-air blocks (BIOME_LOOKUP_PERF_PLAN.md follow-up). After the isAirAt reconciliation fix unblocked the anvil fast path, live scans still showed a residual adjustNull tail (~1300-1600 per gauge tick) whenever the center-column body/head cells held configured-passable blocks like tall grass, flowers, or snow layer. JumpAdjustor.acceptProbeY required strict vanilla-air (isAirAt) for Y and Y+1, so any chunk whose candidate Y had grass above stone was routed back through the full-load path. safety.yml's airBlocks list documents exactly those passable materials but was wired only into the config enum - no code consumed it. Fix: JumpAdjustor now caches SafetyKeys.airBlocks next to unsafeBlocks (shared 5-second refresh in refreshSafetySets) and acceptProbeY accepts body/head as passable when vanilla air OR present in airBlocks, with unsafeBlocks taking precedence on conflicts. Tag-grammar tokens like #minecraft:flowers are stored verbatim and remain inert until the config reader's tag expansion slice lands (tracked in docs/dev/SAFETY_TAGS_AND_STATES_PLAN.md Slice 3). Regression guarded by JumpAdjustorProbeTest.airBlocksFromConfig_acceptsTallGrassHeadSpace.
  • ScanTask probe-first fast path silently vetoed by case-sensitive isAirAt (BIOME_LOOKUP_PERF_PLAN.md follow-up). AnvilColumnProbeAdapter.blockAt reconciles every palette identifier through PaletteNormalizer::reconcile, which converts "minecraft:air" to Material.AIR.name() = "AIR" so that downstream unsafeBlocks.contains(...) checks (populated as Material#name() upper-case tokens like LAVA) match symmetrically. The default ChunkColumnProbe.isAirAt then compared the path segment against lowercase "air" / "cave_air" / "void_air" and returned false for every air block, making JumpAdjustor.acceptProbeY and LinearAdjustor.acceptY find no acceptable Y on any center column. Live runs showed adjustNull == activeChecks every gauge tick with fullLoads == activeChecks, negating the anvil pre-filter entirely and leaving scan throughput at the PR-17 baseline. Fix: override isAirAt in AnvilColumnProbeAdapter to recognize the reconciled AIR / CAVE_AIR / VOID_AIR forms in addition to the raw minecraft:* path segments. Regression guarded by AnvilColumnProbeAdapterIsAirAtTest.
  • Emergency landing platform spam on kept-queue / DB-rehydrated teleports (Folia in particular). TeleportPipelineTask.runTeleport previously gated RTPWorld.platform(...) on reservation == null, which was always true for those paths. Gate is now a read-only safety check against the already-loaded landing chunk (RTPWorld.getCachedChunk(...) + SafetyKeys.unsafeBlocks); no chunk loads are triggered (REQ-RTP-S-005 preserved). Region.execute synthesizes a ChunkReservation for kept-queue pairs so REQ-RTP-S-002 stays intact. Default safety.yml now ships platformRadius: -1 (disabled); set platformRadius: 0 or higher to restore legacy behaviour.
  • Chunk leak in region queue replenishment and in early ChunkReservation integration.
  • Memory leak in active task tracking.
  • Immediate-teleport timing regression and duplicate task execution on queue drain.
  • MemoryShape caching inconsistencies and region-boundary locational edge cases.
  • Erroneous 2D coordinate check that rejected valid surface locations.
  • On-event teleports granted to operators by default (Paper + LuckPerms). ParsePermissions.hasPerm called sender.hasPermission(...) directly for each candidate child node. On Paper with LuckPerms (and any permission manager that defers to op state for unset nodes), hasPermission short-circuits to true for ops regardless of the registered default: false we declared in plugin.yml. The result was that every registered on-event handler (firstjoin, join, respawn, changeworld, move, teleport) auto-fired for any op the moment they triggered the event, even when the admin had explicitly not granted the corresponding rtp.onevent.* node. Fix: rewrote ParsePermissions.hasPerm to iterate the sender's effective permissions (sender.getEffectivePermissions(), which only contains explicitly granted nodes) and match each candidate child against that set - the same pattern already used by ParsePermissions.getInt for numeric permission tiers. This bypasses the permission manager's op-default short-circuit entirely, restoring the documented opt-in default: false behaviour. The earlier removal of the permissionPrefix + "*" wildcard fast-path is retained on general principles but was not load-bearing on its own.
  • Lifetime Chunks Loaded (/rtp info) double-counted every live chunk load. RTPWorld.getOrLoadChunk (added in the ADR-016 section 13.1 follow-up) calls getChunkAt (probe entry) and, on UNKNOWN, getChunkAtAsync (live entry) for the same logical attempt. Every adapter incremented RTPWorld.totalChunkLoads from getChunkAt, and on Spigot/Fabric getChunkAtAsync delegated back through getChunkAt, so each cache-miss load was counted twice (~2.09× ratio observed in the field: cached: 110, Lifetime Chunks Loaded: 230). The counter is now incremented exactly once per live load, in the live-load path itself: BukkitRTPWorld#loadChunkFuture, FoliaRTPWorld#loadLiveChunk and FoliaRTPWorld#getChunkAtAsync, and inside the MinecraftServer#submit body of FabricRTPWorld#getChunkAt. Probe-only paths (anvil cache hits) and kept-cache replays no longer contribute. Operators upgrading will see infoTotalLoads drop to roughly half its previous value - this is the corrected reading, not a regression. The leakRate placeholder is unaffected (still divided by lifetimeTicketsIssued). Javadoc on RTPWorld.totalChunkLoads updated to document the new "actual live loads only" semantics.
  • Initial command execution failure on first plugin load.

2.0.18 - 2024-01-01

Last 2.x release. All changes since this tag are captured under [3.0.0-beta.1] above.

Upgrading from 2.0.18? See MIGRATION.md.


[2.0.x] - Historical

Earlier versions introduced the multi-module split (rtp-api / rtp-core / platform adapters), the asynchronous queue system, the Archimedean spiral shape algorithm, and the MemoryShape persistent cache. Per-commit history is available via git log.