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: 16384bcould be shrunk to a 64-chunk ring and warn that they exceeded a 256-chunk world border. TheSQUAREworld-border lookup left the border shape at its 256-chunk (4,096-block) default instead of reading the world'sWorldBordersize, andspatialResolution: autoconvertedradius: 16384bto a plain chunk count (1024) before the unit check ran, causing1024chunks to be re-interpreted as1,024blocks (64chunks). Native world-border shapes on Paper, Folia, Spigot, Fabric, and NeoForge now read the world's actualWorldBordersize and center, and unit checks run beforespatialResolution: autocaches the converted chunk count. -
.lcaregion files could be treated as ungenerated chunks during random teleports, and evicting open.lcaregions on large world borders could stall chunk reads. Chunk-existence checks read the first4 KiBof.lcafiles as a legacy.mcaheader, and opening a clean 1,024-chunk.lcaregion read every chunk header individually and ran unpromoted FIFO cache eviction..lcaexistence checks now read the.lcapointer 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.unqueuedor empty cache queues) could decode candidate chunks twice whenanvilPrefilterEnabledwas 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. FabricCHUNK_LOADcallbacks now run on the next server tick instead of insideServerChunkCachechunk promotion, BukkitTimeSkipEventskip-reason lookups resolve across Paper's relocatedSkipReasonenum without throwingIncompatibleClassChangeError, and Bukkit tab completion checks both subcommand maps when suggestingparameter=valuearguments.
3.3.2 - 2026-10-30¶
Added¶
- Litematica schematics (
.litematic, ADR-058). Regions (schematicindefinitions/regions/*.yml) and actionPASTE_SCHEMATICsteps now accept.litematicfiles inschematics/alongside.schemand.schematic, including multi-region Litematica files, negative region sizes and block entities. Config and action BIT checks accept.litematicpaths as well.
Changed¶
-
Action name collisions with
/rtp,/wildor another action are now BIT errors (ACTADDON_NAME_COLLISION, ADR-121)./rtp test action-setupreportsACTADDON_NAME_COLLISIONas anERRORinstead of aWARNINGwhen an action's name or command alias collides with/rtp,/wildor another action, and names the existing owner in the message. -
/rtp reloadreads and checks config files off the main thread. Full and single-section reloads (such as/rtp reload regionsor/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 withalreadyReloadinginstead of overlapping. -
/rtp config searchexpands 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 searchqueries an online synonym fallback off-thread. -
For addon developers.
RTPPlayeradds defaultsendTitle(title, subtitle, fadeIn, stay, fadeOut)andsendActionbar(message)methods. In-sessiononStartandonBoundaryViolationaction gates now pass the session'sActionContextto registered custom gate validators, andRTPRuntime.setServerAccessorkeepsRTPAPI.serverAccessorin 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
rtpticket type with kept-cache tickets. NeoForge 1.21.1 now binds the region-ticket method and uses a separatertp_loadticket type with a 30-second expiry for temporary loads. -
Folia safety checks with
safetyRadius > 0could read loaded neighbor chunks off the region thread. When a candidate chunk's center was read from an offline region file while one of itssafetyRadiusneighbors 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.freedid not bypassbalanceFloor. When a region'spriceorbalanceFloorrejected a teleport, the player's incomplete teleport entry stayed active and blocked later/rtpcommands withalreadyTeleporting. WithtoggleTargetPermsenabled, 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.freebypassesbalanceFloor, and failed target charges refund the sender. -
Post-teleport
title,subtitle,actionbar,consoleCommandsandplayerCommandsdid not run on Fabric or NeoForge, and togglingeffectParsingignored/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 testmock players), andeffectParsinginadvanced/performance.ymlupdates on/rtp reloadwithout 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 configuredlanguageinconfig.yml. -
Some translated keys in nested
lang/<locale>/advanced/files did not match their.lang.ymlkey maps, and/rtp docsmessages hardcoded[RTP]instead of[P0]. Nestedadvanced/locale files inde,it,pl,zhandcatnow match their.lang.ymlkey-rename maps, anddocsNotFound,docsEmpty,docsExportSuccessanddocsExportFailedinadvanced/messages/commands.ymlnow use the[P0]prefix placeholder across all locales. -
Unpacking an
@config,@economyor@safetyreference in/rtp editorcould not be undone withCtrl+Z. Unpacking a reference now records an undo/redo step, concurrent/rtp editorHTML 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 editorbiome map on non-Anvil region formats used the.mcareader. Biome extraction for the web editor map now decodes chunks through the registered region-file reader for non-.mcaformats instead of calling the Anvil.mcaprobe directly, and counts unreadable chunks in BIT status. -
World border startup checks skipped
CIRCLE_DEPRECATED_PURE_SPIRALandSQUARE_DEPRECATED_PURE_SPIRALregions 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
autoTunerefill attribution history, and chat or book menus and/rtp admin setuppages 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.ymlshipsautoTune: true. While players teleport and the server has spare tick time, CPU and memory, regions refill on every tick withinasyncAllottedTime,syncAllottedTimeandactiveChunkCapinstead of waiting forperiod. When tick time, CPU, chunk-load latency or tenured heap usage rises, or when caches are already full, background refill scales down beforeminTPS,maxMSPTormaxHeapPercenttrips, 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 infoshows effective budgets, per-region refill shares and top consumers, and/rtp testincludes thecompute-governorcheck for reduced or floor-held budgets and stale metrics; settingautoTune: falseuses the fixed values and refills once perperiod. -
Action and Claim addons report setup health through BIT (ADR-121).
/rtp test action-setupidentifies rejected definitions, command or trigger registration failures, missing batch scheduling and name collisions. On Bukkit-family servers,/rtp test claim-integrationsreports 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).
linearandjumpverts accept two new optional keys.maxSlopeis the largest floor-height step, in blocks, allowed between the landing spot and the groundslopeRadiusblocks away (default2, range1-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 withoutmaxSlopebehave as before and keep their saved region data. Setting or changing either key rebuilds that region's saved data once. Steep worlds with a lowmaxSlopereject more chunks. Not available onfixed, which places players in mid-air. -
Keep players off mountainsides and cliff edges (ADR-120).
linearandjumpverts acceptmaxHillAngle, the steepest hill in degrees a player may land on.config.ymlships it as"off"underdefaults.vert, and the config menu offers"off",30,45and60; any number from 0 to 89 also works. On a 26.3 test world,30refused about 1 in 5 land spots,45about 1 in 12 and60about 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",-1and 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.ymlshipsstrictActions: false, which logs structural action codes as warnings and keeps loading compatible; setting it totrueprevents registration of an action with any effectiveERROR, while other actions continue to load, and per-code overrides take precedence. UnknownACTION:names are omitted, unknown trigger types are skipped instead of falling back toSTEP_IN, and a missing trigger type still defaults toSTEP_IN; the checks use the standalonebit-apimodule. -
/rtp testreports registered BIT probe results (ADR-121). The SAFEallgroup includesapi-compat,commands,scheduler,events,economy-isolation,disconnect-job,networkandsafety-verifier, and can be filtered withtier=orsubsystem=./rtp test statusshows registered state without rerunning checks, andjson=trueselects machine-readable output. Chat starts with a component-count summary, then lists only distinctFAIL,WARNandINFOfindings; repeated codes are counted, whilePASSandSKIPcomponents appear only in the summary. The server log keeps the full table with paths and messages.allis distinct from the Bukkit-onlyfullsweep; existing probe summaries remain unchanged for automation. -
/rtp test teleportchecks the teleport pipeline without a real player (ADR-121)./rtp test teleport [region=<name>] [count=1-16] [json=true](permissionrtp.test.mutating) sends temporaryrtp-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 ofallortier=ibit. -
Generate a mock teleport landing heatmap (
/rtp test teleport-heatmap, ADR-121). Operators withrtp.test.mutatingcan 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 separateplayer=<name>components for live platform behavior; hologram remains player-only. Component findings are included in the BIT report, and every timeout recordsBIT_COMPONENT_TIMEOUTwhile 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 statusreports missing scoreboard objectives, gates that always or never pass, unresolved placeholders, unknownACTION:commands, and sessions that remain active beyond their reaper window.advanced/bit.ymladdsgateOutcomeSamples, which defaults to200evaluations. -
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 configedit,/rtp config importor/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/@safetyreferences that do not resolve;- regions, worlds, schematics and effect groups that point at something missing;
- impossible settings such as a
radiusthat is not larger thancenterRadiusor ashrinkTolarger thaninitialSize; - 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
reloadRejectedandeditorApplyRejectedmessages, 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. SetstrictConfig: trueinadvanced/bit.ymlto 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: trueinadvanced/network.yml(defaultfalse) writes completed metric buckets (tier, default24h@1m) to the shared SQL tablertp_metric_bucketor Redis sorted setsrtp:metric:<backend_id>:<metric_key>with(sample_count, mean, min, max, p95)and the active networkgeneration. Writes are batched (perPassWriteCap, default64rows per pass) and swept per backend afterretentionDays(default7days). Cross-backend chart snapshots include the(min, max)band alongsidemean. When network mode is off andpublish: true, RTP logs one warning at startup and stays dormant. -
Choose whether bare
/rtpopens the destination picker (openOnBareRtp).addons/guimenu.ymladdsopenOnBareRtp: true(also disabled whenmenuStyleis"none"or"off"). SettingopenOnBareRtp: falsemakes bare/rtpteleport 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-
/rtpmenu behavior in the setup wizard (/rtp admin setup, ADR-038)./rtp admin setupadds a region outer radius step (/rtp admin setup radius <distance>, with presets2.5km,5km,10km,25km,4096band500c, plus a custom distance prompt) and anopenGuiOnRtptoggle on the gameplay page (addons/guimenu.ymlopenOnBareRtp).
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 printsnamespace:id, JSON includesnswhile 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, reportsBIT_NAMESPACE_CONFLICTwhen two plugins reserve the same code prefix. -
Runtime-read duration settings accept explicit units. Values such as
30s,5m,2h,1d12h,40tand500mswork insafety.yml,advanced/performance.yml,advanced/network.ymland proxynetwork-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
liteVersionline 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-apiartifact inio.github.dailystruggle.server.api(RTPServerAccessorextendsServerAccessorandRTPSchedulerextendsTaskScheduler), andrtp-apire-exportsserver-api,menu-api,units-apiandtags-apialongside the standalonebit-api,config-bit-apiandpredict-apimodules (ConfigParser,MultiConfigParser,LanguageBootstrap,FactoryandFactoryValuealso live inyaml-apiunder their existing packages). UpdatePlatformFamilyimports fromio.github.dailystruggle.rtp.api.serverand rebuild binaries compiled against the old enum package. Built-in effects now route throughServerAccessors(wrapEffectPlayer,wrapEffectLocation,resolveEffectPlayerAt,dispatchConsoleCommand),HandleRegistryandHandleProviderinio.github.dailystruggle.effectsapi.common.spiare deprecated (@Deprecated(forRemoval = true)) as forwarding shims overServerAccessors, and the Bukkit effect classes (io.github.dailystruggle.effectsapi.bukkit.*andio.github.dailystruggle.effectsapi.EffectsAPI) have moved fromeffects-apiinto:rtp-bukkit:rtp-bukkit-commonsoeffects-apicarries no platform code.RTPServerAccessorprovides the defaultOptional<Boolean> hasScoreboardObjective(String)method,RTPScheduleraddsisGenerationSaturated(RTPWorld),RTPWorldaddsprobeChunkSquarefor off-thread same-region-file square probes, andrtp-apiadds@PublicApiMetricTimeSeriesPublisherandMetricBucketRowinio.github.dailystruggle.rtp.api.metrics.
Fixed¶
-
Moving during the
/rtpwarmup now cancels the teleport. Walking farther thancancelDistanceduringteleportDelaywas ignored for/rtp, because the player's starting position was never recorded, so the teleport went ahead anyway. -
Plain-number
teleportCooldownandteleportDelayvalues were treated as milliseconds instead of seconds. Bare numbers such asteleportCooldown: 300orteleportDelay: 5were read as milliseconds after duration-unit parsing landed, andteleportDelaywas 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
cooldownoverrides were blocked by a longer globalteleportCooldown. Naming a region with/rtp region:<name>now uses that region'scooldownoverride on its own, and a bare/rtpinto a world's default region passes once either the global cooldown or the region's override has elapsed. -
Walk-in trigger
batchIntervalwaves 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 cancelor 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-api4.6.2,PlotServiceApi.getPlotfrom 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.ymlflag 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 intodefinitions/effects/, so deletingdefinitions/effects/rift.ymlwhile the server was stopped brought it back on the next start, even with the addon removed. The addon now writesdefinitions/effects/rift.ymldirectly and deletes an uneditedeffects/rift.ymlleft by an earlier version. -
The Rift effect no longer cancels
/rtpor buries the player. The fall into the rift counted as moving and trippedcancelDistance, so every delayed/rtpwithRIFTcancelled 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 thanteleportDelay) 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.
TITLEnow works on Paper, Spigot and Folia.GLIDEnow works on Fabric 26.x and NeoForge.DROP_INVENTORYandDROP_EXP/DROP_EXPERIENCEnow work on NeoForge. Before, these tokens were skipped without a message.FIREWORKandNOTEare still Bukkit-family only. -
GLIDEon 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, andLANDINGTIMEOUTstill forces a landing. Fabric and NeoForge don't yet place players who are still gliding when the server stops. -
TITLEshows the configured text. Text arguments were replaced by their empty defaults while the effect was built, soTITLE.<title>.<subtitle>showed a blank title on every platform. The same applied to text arguments of addon effects. -
/rtp config languageonly 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). -
RECTANGLEregions withrotation: 90mapped locations to the wrong coordinates, andsetBiomeGetteroverrides on Fabric and NeoForge were ignored. Rotated rectangles now round-trip coordinates and heights, and biome checks on Fabric and NeoForge read the registeredsetBiomeGetteroverride 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
maxHillAngleneeds the 3x3 square.
3.3.0 - 2026-10-18¶
Upgrade note.
rtp.servers.*now defaults totrueinstead ofop, so in network mode every player can reach open cross-server regions; restrict with negative permissions if you relied on the old default.CIRCLEandSQUAREnow use new selection engines that ignoreweight; useCIRCLE_DEPRECATED_PURE_SPIRALorSQUARE_DEPRECATED_PURE_SPIRALto keep the 3.2.1 behavior. Region shapes now default tomode: REROLLinstead ofACCUMULATE; files that setmodekeep their value. Inconfig.yml,defaults.shape.uniquePlacementsnow defaults to"auto"(a radius matching the view distance) instead of0, anddefaults.spatialResolutionto"auto"(scaled to the region's size) instead of3; set0and3to 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 upplugins/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 triggerand/rtp runare 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 witheditor.trust.maxAgeDaysinadvanced/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 withoverwrite=true, and are backed up first./rtp config import permissionsprints 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
CIRCLEandSQUARE(ADR-085, ADR-088). Picks spread evenly by area and never repeat a chunk within a pass. Inmode: REROLLplayers are kept several chunks apart without using up the region, soexpand: falseregions 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.weightno longer applies; the old shapes remain as*_DEPRECATED_PURE_SPIRAL. -
Commands as teleport effects, and a
deathstage (effects-api-ADR-007). Run console or player commands at any teleport stage, with player and location placeholders. The newdeathstage 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.ymlinstead of being avoided forever. Bad terrain is still remembered permanently. -
Units in configs and commands. Write
radius: 5km,teleportCooldown: 2h30morcacheCap: 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-coreand the API libraries they depend on, such ascommands-apiandeffects-api, are published to Maven Central. Platform jars are not. -
For addon developers. New
rtp-apisurfaces 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.mcaand loads other formats such as.linearasynchronously).
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/L3names in/rtp infoand 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 infoshows 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: ASYNCinadvanced/performance.ymlto 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.
-
REROLLis the default selection mode.CIRCLE,SQUARE,ELLIPSEandRECTANGLE, and the shippedconfig.ymlin every language, now usemode: 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.ACCUMULATEstays available for regions that need every draw to be a guaranteed O(1). Regions that setmodekeep their value. -
All memory shapes share one selection routine. Shapes had drifted apart in how they handle bad land,
modeanduniqueplacements(see Fixed); they now behave consistently. -
ELLIPSEturns offexpand: truewith a one-time warning, asPOLYGONalready 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.
syncAllottedTimenow defaults to 5 ms andasyncAllottedTimeto 25 ms, and both are capped at 25 ms. Queued commands, scripted actions and promotion checks for ready-queue locations now count againstsyncAllottedTime, and RTP starts at most 8 chunk loads per region per refill. On Fabric and NeoForge, RTP's end-of-tick work stops atsyncAllottedTimeand background work uses at most half the CPU cores.periodnow means ticks between refills of the same region. -
minTPSnow pauses background cache filling, and the newmaxMSPTsetting (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
/rtpload 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
syncAllottedTimeper 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-coreand 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¶
- For addon developers.
PaletteIdentifierNormalizerinrtp-apiis deprecated; use the one inanvil-api.
Removed¶
-
Party and tether addons. LeafRTPPartyAddon and LeafRTPTetherAddon are no longer built. For group teleports, use the action addon's
teamsandscattermodes. -
For addon developers. The Bukkit-only classes in
commands-api(BukkitCommand,BukkitCommandRegistrar,BukkitParameter,StringCommandDispatcher,BukkitTreeCommandand theLocalParameterspackage) and itsplugin.ymlare removed; use the platform-neutralcommandsapi.commonandcommandsapi.brigadierpackages. The Bukkit command classes andplugin.ymlineffects-apiare removed too. The Fabric effect classes inio.github.dailystruggle.effectsapi.fabricmoved out ofeffects-apitoio.github.dailystruggle.rtp.fabric.effectsin the Fabric adapter, soeffects-apino 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.
-
uniquePlacementscould use up a region withexpand: falsewithin seconds of startup. It now applies only whenexpand: 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
/rtprequests 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=lz4never got the region-file safety check. -
/rtp scanrejected 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
modeanduniqueplacementsinconsistencies.modevalues are case-insensitive,NEARESTmode no longer returns known-bad locations or ignoresuniqueplacementsonCIRCLEandELLIPSE,SQUARE_NORMALreadsuniqueplacementsas a radius, and regions usinguniqueplacementsno longer slow down as RTP learns more bad land. -
The
JUMPvertical 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. -
syncAllottedTimeandasyncAllottedTimeabove 25 were silently capped, and thehigh-performanceand arena presets wrote 50. The cap is now documented, and the presets use values within it. -
periodrefilled each region one tick early (every 19 ticks atperiod: 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 scanprogress 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 scanstalled 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 scanon 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 thatexpanduses. -
On Paper and Folia 26.1 or newer,
/rtp scanand 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 newworld/dimensions/<namespace>/<name>/region/layout. -
The free jar declares the same permissions as the Pro jar. Its
plugin.ymllackedrtp.version,rtp.biome,rtp.menu.admin,rtp.personalqueueand thertp.onevent.*nodes, so/rtp versionwas 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_SECRETof at least 32 bytes;plugin-message,proxy-cacheandautocan instead run unsigned withnetwork.allowUnsigned: trueinadvanced/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.1by 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.teleportnow checks destination permissions, so menus and addons can't send players to worlds, biomes, regions or servers they lack permission for. ReturnsNO_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
viewDistanceRestoreIntervalkey inperformance.yml(default 200 ticks / 10s; set0to disable). Supported on Bukkit/Paper/Folia; other platforms ignore it.
Changed¶
-
config.ymlis now purely teleport behavior. The database settings moved to a newdatabase.yml, and the redundantnetwork.redisblock was removed (use the Redis transport settings innetwork.ymlinstead). Values you customized in the old locations are not migrated automatically - re-set the database indatabase.ymland Redis innetwork.yml. Theconfig.ymlversion was bumped to 3.1. -
The
plugins/RTP/folder was reorganized into a cleaner, tiered layout, andmessages.ymlsplit 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 singledefinitions/folder, and the rarely-edited prefab schematics moved underadvanced/. The legacy flatmessages.ymlwas removed in favor of modular category messages underadvanced/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.ymltoadvanced/biomes.yml, so every biome-selection option (whitelist/blacklist plus weighting) lives in one file. Behavior is unchanged. A value you customized inperformance.ymlis not migrated automatically - re-set it inadvanced/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 underplugins/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 ofconfig.ymlnow 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 thedatabase:/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
/rtpchunk request could freeze the server tick (risking a watchdog crash), fail to generate chunks (spammingINSTANT BYPASSin 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 configmenu 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
/rtpmessage 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/rtpcommand 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 thertp.freebypass now apply on the menu/API path too, and a failed teleport is refunded. -
Fixed a stray
xcharacter appearing before the[RTP]prefix on NeoForge/Fabric when a gradient wraps a nested rainbow (as in the defaultteleportMessage). -
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
sof38msin the defaultteleportMessage). -
Teleports triggered through a GUI/menu addon are now instant when a location is already cached, matching the
/rtpcommand, 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
LeafRTPGuiAddonon 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/rtpnow 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 extractedaddons/LeafRTPGuiAddon.jar(theaddons/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 publicrtp-api/SPI surface is unchanged.
Added¶
-
The bundled
LeafRTPCountdownAddonnow shows its delay and queue countdowns as an on-screen boss-bar instead of chat spam, via a new per-player progress-bar API.RTPPlayergains two default methods,showProgressBar(id, title, progress)andclearProgressBar(id), that render a personal, single-player boss-bar (distinct from the existing server-wide, permission-scopedRTPServerAccessor.updateProgressBarssurface). The Bukkit adapter (BukkitRTPPlayer) implements them over BukkitBossBars 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-apievent surface (RTPAPI.onPrefabApplied(Consumer<PrefabAppliedEvent>), returning anAutoCloseablefor unregistration) fires a fire-and-forget, post-apply notification after/rtp admin prefab ... confirmwrites 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 ofPrefabChange(keyPath / oldValue / newValue), and whether the reload succeeded. The dispatcher (PrefabEventDispatcher) mirrors the existing player-lifecycle hook pattern: aCopyOnWriteArrayListof 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 newPrefabCommandTestcases. -
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 totrue, wasfalse) gates a new on-load harvest: whenever the server loads a chunk for any reason, the chunk's center-column biome is recorded into theMemoryShapeof each configured region whose range contains that column, feeding biome recall / biome-weighted selection without any extra chunk I/O. A new always-registeredOnChunkLoadlistener (Bukkit/Paper/Folia) forwards loaded chunks toSelectionAPI.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 bySelectionAPIObserveChunkLoadTest(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 guicommand. TheLeafRTPGuiAddonmulti-loader jar is bundled inside both the Pro and lite RTP jars (underbundled-addons/) and self-extracted into<pluginDir>/addons/on first run only - when theaddons/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 guisubcommand (permissionrtp.gui) lives inrtp-coreand opens whatever menu an addon bound to the bare/rtproot 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/rtpguicommand, which never appeared when the addon was loaded from theaddons/folder (itsJavaPluginentry point does not run there). The Bukkit chest renderer is now also published via aMenuRendererMETA-INF/servicesdescriptor so it registers on theServiceLoaderload path (addons-folder / bundled), where the entry point is skipped. Covered byAddonRegistryTest(2 new cases). -
The
lockAfterUsesusage cap now survives a restart, reaching parity with the already-persisted cooldown (ADR-068). The BetterRTPLockAfterrolling-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 newTeleportLimitStoreseam (rtp-core) now fronts the usage-cap guards (/rtpcommand and the addon-facingRTPAPI.teleport) and the success counter; itsLocalTeleportLimitStorewrite-through-persists each player's{count, start}window to the configured database (the file-backedYamlFileDatabasein 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 byTeleportLimitStoreTest(4 cases). -
The RTP-lite assembly variant now ships the full base
safety.ymlinstead of a trimmed lite-specific copy (ADR-024 2026-06-20 amendment). The lite-specificsafety.ymloverlay 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 (theSafetyTokenParser/SafetyCompilationCache/SafetyTokenExpanderalready ship in the lite jar); only thertp-tagsmodule (tags/,tagsRefresh.yml) remains a full-edition feature.
Changed¶
-
The
LINEARvertical 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 globalLINEARdefaultdirectionmoved from0(bottom-up) to2(middle-out) - the same setting already seeded for_nether/_the_endregions. The dimension-specific direction override is removed fromNetherEndConfigAmender(its nethermaxY<=128clamp andrequireSkyLight=falseseeding are unchanged), since middle-out is now the baseline. Existing region configs that setdirectionexplicitly are unaffected. -
The shipped default overworld region now uses the
LINEARvertical adjustor with middle-out search (direction: 2) and requires sky light (vert.requireSkyLight: true) so/rtplands players on open-sky surfaces.regions/default.ymlswitchesvert.namefromJUMP(which has no scan-direction concept) toLINEARwithdirection: 2, matching the middle-out search already used for nether/end, and flipsrequireSkyLightfromfalsetotrue. Nether/end regions created from this default still seedrequireSkyLight: falseautomatically viaNetherEndConfigAmender(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-plugininto the new bundledLeafRTPClaimAddon(ADR-069, superseding ADR-019). The 12 claim/protection checkers (WorldGuard, GriefDefender, GriefPrevention, Towny Advanced, SaberFactions, FactionsBridge, Lands, RedProtect, Residence, CrashClaim, HuskClaims, KingdomsX), theIntegrationsKeysenum, andintegrations.ymlleft 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 onPlatformFamily.BUKKIT. The addon jar is bundled inside both the Pro and lite RTP jars (underbundled-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 claimcompileOnlydependencies and their dedicated soft-dep Maven repositories are removed fromrtp-plugin/build.gradle. Behaviour change for operators: the per-localeintegrations.ymltranslations that previously shipped in the core plugin are dropped (the addon ships an Englishintegrations.yml); re-localizing the addon config is tracked follow-up work.
Fixed¶
-
requireSkyLight: trueno 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 full15before relighting, so a roofed cave column passed the gate. Both adjustors now derive the gate from block data instead (the samecomputeColumnSkyFloorapproach 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 newLinearAdjustorTestregression case (roofed cave with a stale full sky-light is rejected). -
The bare
/rtpGUI (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 BukkitString[]-argsonCommandpath; Fabric (RTPCmdFabricRoot.onCommand) and NeoForge dispatch a bare/rtpstraight throughRTPCmd.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 ofcompute(...)for a bare invocation (no args), mirroring the Bukkit path and releasing theprocessingPlayerslock when the action handles the command; the BukkitString[]path still short-circuits beforecompute(...)when it handles the command, so the action never double-fires. Covered by two newReqApiF006RootActionTestcases exercising thecompute()entry point. -
Fabric on the deobfuscated MC 26.x runtime no longer crashes with
NoClassDefFoundError: net/minecraft/class_3222the moment a/rtpeffect (sound / particle / potion) fires. The common effects resolve the player throughHandleRegistry.wrapPlayer, which on Fabric routed to the sharedeffectsapi.fabric.FabricHandles. That provider lives in the Loom intermediary-remapped:effects-apimodule, 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-nativeeffectsapi.fabric_unobf.FabricHandlesUnobf(compiled with nomappingsstep, so it names Mojang types directly and absorbs 26.x API drift:(ServerLevel) player.level(), record-shapeGameProfile#name()with fallback, the 2-booleansendParticlesoverload, reflective/packet teleport), andFabricEffectsInitializer.registerAll()registers it instead of the intermediaryFabricHandles. 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
FabricHandlesUnobffix above) instead of silently re-shipping stale carrier bytecode. The unobf carriers are appended into the Loom-remapped jar by theremapJar/remapLiteJardoLastmerge step, but those tasks only declared adependsOnon the carrier jars - the carriers are NOT part of the task'sinputFile(which isshadowJar/shadowLiteJar, where the bundled:effects-api/rtp-fabric-commonare the intermediary-remapped variants). So a carrier-only source change left the shadow jar's bytes identical,remapJarstayedUP-TO-DATE, itsdoLastnever re-ran, and the shipped jar kept the previously-merged carrier classes. The carrier configurations are now declared as taskinputs.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-neutraleffectsapi.common.effects.PotionEffectcarried a Bukkit/Folia entity-thread dispatch seam in a static lambda whose functional-interface (EntityDispatcher) descriptor namedorg.bukkit.entity.Player/org.bukkit.plugin.Plugin. Resolving that descriptor forced eager loading oforg.bukkit.entity.Playerthe instant the class was instantiated, soFabricEffectsInitializer.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 ownclass_7923link failure. The seam (EntityDispatcher,entityDispatcher,applyOnEntityThread) was moved verbatim to the new Bukkit-onlyeffectsapi.bukkit.BukkitPotionDispatch; the common effect now links on every platform and applies potions through the platform-neutralPlayerHandle#applyPotionEffect. Covered by the relocatedFoliaDispatchTestandEffectsApiCommonNoPlatformImportsTest. -
NeoForge 26.1 server no longer crashes with a 60s ServerWatchdog timeout when
/rtploads a chunk.V26_1_R1NeoForgeVersionAdapter#requestFullChunkAsyncreflectively invoked vanilla's publicServerChunkCache#getChunkFuture(..., create=true)on the server tick thread (the live-load path dispatches it viaMinecraftServer#execute). On the main thread that public entry point parks the tick thread onmainThreadProcessor.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 innergetChunkFutureMainThread(same signature), which returns the pending future without blocking while the chunk system settles it off-thread;create=truestill 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 chunkand starves the location cache.V26_1_R1NeoForgeVersionAdapter#requestFullChunkAsyncinvoked vanilla'sgetChunkFuture(..., create=true)without first applying a load-ticket, so on this runtime the chunk holder never reached FULL status and the future resolved with noChunkAccess- 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
/rtpinstead of flooding[ScanTask] INSTANT BYPASS: Chunk manager returned a null chunkand starving the cache. Thertp-fabric-v26_1_R1/rtp-fabric-v26_2_R1carriers never overroderequestFullChunkAsync, so the unobf chunk path (FabricRTPWorldUnobf.loadLiveChunk) fell through to the throwinggetChunkFullstub default and no chunk ever generated. Both carriers now implementrequestFullChunkAsyncthe 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 typedServerChunkCache#addTicketWithRadius/#removeTicketWithRadiuspair, then invoke the publicgetChunkFuture(..., create=true)off the server tick thread so vanilla takes its non-blockingsupplyAsync(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 withnullChunk/asyncLoadNull). The runtime world is not the commonFabricRTPWorld/FabricRTPWorldUnobfbut the per-versionV26_1_R1FabricRTPWorld/V26_2_R1FabricRTPWorld(constructed viaFabricVersionAdapter#createWorld), which carry their owngetChunkAt. That path invoked the publicgetChunkFuture(..., create=true)on the server tick thread with no load-ticket, so on the deobf MC 26.x chunk system the future resolved with noChunkAccessand every attempt was attributednullChunk/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 publicgetChunkFutureis invoked off the tick thread (where vanilla takes its non-blockingsupplyAsync(mainThreadProcessor)branch), and the method resolver prefers the publicgetChunkFutureover the innergetChunkFutureMainThreadso the off-thread self-pump branch is taken. The temporary ticket is released once the generation future settles. -
NeoForge 26.1 no longer spams
NoSuchMethodErrorevery tick while rendering a/rtpscan progress bar.NeoForgeProgressBars(in the version-agnosticrtp-neoforge-common, typechecked against the MC 1.21.x mappings) hard-linked theServerBossEvent(Component, BossBarColor, BossBarOverlay)constructor, whose signature drifted on MC 26.1, so every progress-bar update threwNoSuchMethodErrorfrom the scheduler tick. The construction site now resolves a matching publicServerBossEventconstructor by reflection once (cached), accepting any shape that exposes aComponent,BossBarColorandBossBarOverlayparameter and filling any extra parameters with sensible defaults (a freshUUIDper bar,0f,false, ornull); 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_3827andNoClassDefFoundError: net/minecraft/class_7923.FabricServerAccessorlives in the Loom intermediary-remapped common module, so its directMinecraftServer#getServerVersion()call and itsBuiltInRegistries.BLOCKwalk inmaterials()compiled to intermediary aliases that do not exist on the deobf 26.x runtime - the version probe threw andmaterials()threw, disabling block-name validation.getServerVersion()now reads the mapping-neutral FabricLoaderminecraftmod-container version (falling back to a reflective Mojang-then-intermediary method probe), andmaterials()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 strategyblockTagSnapshot()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
26instead of1, so version-gated addons load.FabricServerAccessor.getServerIntVersion()always parsed the second dot-separated component, which is right for the legacy1.<minor>.<patch>scheme but yields1for26.1.2- violating the documented contract (21 for 1.21.x, 26 for 26.x) and makingisCompatible/isServerVersionAtLeastfail closed for every addon that declares a version floor. The parse now takes the major when it is not1, otherwise the minor, and tolerates pre-release suffixes such as26.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
maxHeapPercentwith the "pausing background cache generation" warning repeating forever. TheHeapPressureMonitorgate paused cold->hot promotion under pressure, which stopped the retained set from growing but never shrank it - each kept location pins a chunk via itsChunkReservation, so heap usage stayed pinned at the threshold indefinitely.Region.executenow 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 newLockFreeLocationBuffer.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 newLockFreeLocationBufferTestcase. -
The multi-world prefab now also repoints each world's
worlds/<world>.ymlat its synthesised region, so the per-world regions are actually used. Applying themulti-worldprefab synthesised oneregions/<world>.ymlper loaded world (cloningregions/default.ymlwithworld: "<world>") but left everyworlds/<world>.ymlstill pointing itsregionfield at the shareddefaultregion, so the new per-world regions were inert.PrefabApplier.apply(..., worldNames)now emits a sparseworlds/<world>.ymloverlay settingregion: "<world>"for each synthesised world (the default-mapped overworld, which keeps thedefaultregion, is left untouched), andPrefabApplyCmdseeds each world's authoritative currentregionfrom the in-memoryRTP.configsworld parser (every loaded world has one by definition, even when noworlds/<world>.ymlfile exists on disk) so the diff reports the true delta (e.g.defaultto<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 newMultiWorldExpanderTestcase. -
The multi-world prefab now repairs the cloned vertical adjustor for nether/end worlds, so
/rtpinto a synthesised_netherregion no longer fails every attempt withvert/no-stand-y. The prefab clones the overworldregions/defaulttemplate (sky-light-requiredLINEARvert 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 canonicalNetherEndConfigAmender(the same helper/rtp config regionuses) at apply time, reading the liveregions/defaultvert as the template and the destination world's real height bounds: it dropsrequireSkyLightfor both*_netherand*_the_endand clampsmaxYbelow the nether ceiling.MultiWorldExpanderstays a pure transform and accepts the repair as an injectedRegionOverlayAmender, 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 newMultiWorldExpanderTestandPrefabCommandTestcases. -
Prefab config writes now go through the live config system (
rtp.configs) instead of bespoke disk IO, andConfigParser.save()gained automatic.bakrotation. Backup write/rotate/restore/prune logic was extracted into a sharedConfigBackupshelper;ConfigParser.save()now snapshots the current file as a rotating<name>.bak.<ts>sibling before overwriting (retention via the newConfigParser.bakRetention, best-effort so a backup failure never blocks the save).PrefabConfirmCmdwrites each file through the matching liveConfigParser(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 clonesregions/default.ymlwith its comments). The previous bespokePrefabDiskIO.writeWithBackuppath (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 ofregions/default.ymlcomments in synthesised per-world region files. Covered by the existingPrefabDiskIOTest/PrefabCommandTestsuites plus theconfigurationtests. -
Fabric on a late 1.21.x runtime (e.g. 1.21.11) no longer crashes the server tick with
NoSuchMethodErroronServerLevel.sendParticlesthe moment a/rtpparticle effect fires. The intermediary-remapped obf carriereffectsapi.fabric.FabricHandles.PlayerWrapper.spawnParticlehard-linked the single-booleansendParticles(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, onNoSuchMethodError, 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#rrggbbcodes. 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 legacysection xhex codes by the newGradientExpanderpre-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 inMiniMessageRenderer(Paper/Folia) andGradientExpander(Spigot fallback), probed at runtime bySendMessage. -
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 aDrilldownPieof cost components (outer slice) with a bucketised ms-per-RTP inner slice:scheduler(RTP's scheduler cost, on both charts) pluschunk_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;unknownuntil sampled), never raw timings or counts, so no server can be fingerprinted; the profiling decorator just adds oneSystem.nanoTime()pair per task. Covered byProfilingRTPSchedulerTest(3) andBStatsChartIdsAntiFingerprintingTest. -
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 newChunkLoadProfilefed 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). TheDrilldownPieouter 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;unknownuntil recorded). Both levels are categorical, so no raw timing is emitted. Covered byChunkLoadProfileTest(5) andBStatsChartIdsAntiFingerprintingTest. -
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) andFactionsBridgeChecker(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. NewrerollSaberFactions/rerollFactionsBridgetoggles (defaultfalse, mirrored across every locale), theFactionsBridgesoft-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, andKingdomsXChecker. 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. NewrerollResidence/rerollCrashClaim/rerollHuskClaims/rerollKingdomsXtoggles (defaultfalse, mirrored across every locale), the matchingplugin.ymlsoft-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-apiteleport surface (RTPAPI.teleport(UUID, RtpTarget)) was extended for network mode and picker menus, with no change to existing callers: RtpTargetgainsKind.NETWORK+ anetwork(serverId, regionName)factory andserverId(), 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>).RTPResultgains aQUEUEDreason (queued(message)/isQueued()) for the accepted-but-transferred outcome (itslocation()isnull- the destination resolves on the remote backend), plus failure reasonsALREADY_TELEPORTING,COOLDOWN,LOCKED,RELOADINGmirroring the/rtpcommand guards.RtpTargetStatusgains optional, nullable display hintsiconBlock(),environment(),label()so a picker can decorate a destination whose block/environment/display name cannot be resolved locally. A local region'slabel()comes from a newregions.yml#displayNamekey.
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.
-
/rtpmenu now has a world picker row (ADR-065).FrontPageBuilderadds aworldrow beside the region and biome rows (shown only when the player has theworldpermission and there are worlds to pick), opening the world picker and tinted like the biome rows. Labeled by a new configurablemenuFrontPageRowWorldmessage 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 noplugin.yml, only aMETA-INF/servicesRTPAddondescriptor), placing one inplugins/made the server's plugin loader abort startup withDirectory '...jar' does not contain a paper-plugin.yml or plugin.yml!. RTP now also scans<pluginDir>/addons/at startup via the newAddonRegistry.discoverFromDirectory(...): each*.jaris loaded in a childURLClassLoader(parent = RTP's own classloader, sortp-api/rtp-coretypes resolve to the running classes) and discovered throughServiceLoader. The folder is optional - a missing or empty one is a silent no-op - and the existing classpath/register(...)paths are unchanged. Covered byAddonRegistryTest(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 viaTextComponent.fromLegacyText, which left MiniMessage<tag>markup untouched - so the default<rainbow>[RTP]</rainbow>prefix (messages.ymlP0) printed literally as<rainbow>[RTP]</rainbow>on Paper/Folia 26.2 startup lines (e.g.Successfully loaded N locations). Bothlogoverloads now route the modern console-sender path through a newtoConsoleComponents(...)helper that renders the line throughMiniMessageRendererwhen Adventure is present and the line carries<tag>markup, falling back toTextComponent.fromLegacyTextwhen 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 viaTextComponent.fromLegacyText, so MiniMessage tags (e.g.<rainbow>,<#rrggbb>, gradients) printed literally in the action bar while the chat (sendMessage), title (toLegacyText),announce, and console-logsinks already rendered them. The action-bar path now routes through the shared MiniMessage-awaretoComponents(...)renderer, so every player-facing and console message sink honors MiniMessage consistently; existing legacy&/hex configs keep rendering via the legacy fallback insidetoComponents. -
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&/#rrggbbcodes - 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-neutralMiniMessageColorExpander(rtp-core) converts MiniMessage color/format tags (named + hex colors,bold/italic/underlined/strikethrough/obfuscated/reset, and gradient/rainbow/transition via the existingGradientExpander) 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 byMiniMessageColorExpanderTest(9 cases).
Fixed¶
-
Gradients and other MiniMessage tags no longer break when mixed with legacy/hex color codes.
MiniMessageRenderer.legacyToMiniMessagerewrote legacy&/section-sign and#rrggbbcodes across the whole resolved string before the singleMiniMessage.deserializepass, so the direct-hex rule (optional&/section-sign prefix) also matched the bare#rrggbbcolor 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 byMiniMessageRendererLegacyTest(6 cases). -
WorldGuard claim protection is now actually enforced (the
can-rtp-select-hereflag logic was inverted).WorldGuardChecker.isInClaimread thecan-rtp-select-hereflag directly, but it defaults tofalse, 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 toALLOWgot rerolled, exactly backwards. Now: wilderness -> accept, inside any region -> reject (rerolled), andcan-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.checkGlobalRegionVerifierslogged 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 theEXTERNAL_HOOKS.mdcontract 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 returnfalse); the gap only hit third-party synchronous verifiers. Covered byReqRtpS004VerifierFailSafeTest. -
/rtp region:<r> world:<w>now duplicates region<r>and adjusts it for world<w>(theworldsub-parameter was previously a no-op) (ADR-065).RTPCmdbuilds a "world-override" region (region<r>'s settings withworldset to<w>andshapere-resolved for it), names it<baseRegion>_<world>(e.g.default_nether), and caches it in the existingSelectionAPI.tempRegionsmap - 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 regiondefaultteleports to regiondefaultas configured. The override is gated byRTPCmd.shouldApplyWorldOverride(...)(applies only when bothregionandworldare present). No new permissions: the existingrtp.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 byRTPCmdWorldOverrideGateTestandReqRtpAdr065WorldRegionTeleportTrapTest. -
/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 bySelectionAPI.worldRegion(e.g.default_world_nether) copied the base region'svertverbatim, so a teleport into_nether/_the_endused the overworld's sky-light-required upward search rather than the dimension-tuned vert every other region-creation path applies viaNetherEndConfigAmenderwhen the vert is unspecified.worldRegionnow seeds aLINEAR, downward (direction=2), no-sky-light vert clamped to the dimension (nether capped at y=128) for_nether/_the_endtarget worlds, leaving overworld-style worlds unchanged. Covered bySelectionAPIWorldRegionTest. -
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
/rtpmenu 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 newMenuColor.regionColorPrefix/BiomeMenuSource.biomeWeightsForRegion, matching how world rows are already colored. Covered byPickerCleanListTest(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_R1carrier now pinsminecraftVersion = 26.2(was the26.2-rc-2release candidate; loader0.19.2and fabric-api0.150.2+26.2unchanged), and the carrier builds cleanly against the final game artifacts.RTPFabricMod#adapterFqnForalready dispatches the26.2line viastartsWith("26.2"), so no dispatch change was needed. NeoForge has no 26.2 carrier yet (itsstartsWith("26.")matcher would load the 26.1 adapter on a 26.2 server); a dedicatedrtp-neoforge-v26_2_R1carrier 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), Towny0.97.5.0->0.102.0.13, and Lands6.22.0->7.19.1(the LandsAPI repository moved, so the coordinate also changes fromcom.github.angeschossen:LandsAPItocom.github.IncrediblePlugins:LandsAPI). These are compile-only API bumps with no runtime behaviour change;LandsCheckercompiles against the 7.x API using the still-present (now deprecated)LandsIntegrationconstructor andisClaimedchunk overload. GriefPrevention stays on the maintained legacy16.xline (the17.x/18.xrewrite 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 bundledFactionsChecker(ADR-019) is removed: it compiled against the unmaintained MC 1.7-1.8-eracom.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 newSaberFactionsChecker/FactionsBridgeChecker.FactionsChecker, thererollFactionstoggle, and the compile-only dependency are gone; theFactionsplugin.ymlsoft-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.husktownsAPI (current HuskTowns is the rewrittennet.william278line).HuskTownsChecker, thererollHuskTownstoggle, theplugin.ymlsoft-depend, the compile-only dependency, and the metrics chart are all gone. Operators still running HuskTowns can register an equivalent check via the publicRTPAPI.hooks().verifiers()API.
3.1.2-Lite - 2026-06-13¶
Added¶
-
Cross-server
/rtpon the DB-freeproxy-directtier, as a drop-in alternative to Redis/SQL for data management (rtp-proxy-ADR-019, refining rtp-proxy-ADR-018). Building on theproxy-directregion discovery (rtp-proxy-ADR-017), a cross-server/rtp <server>:<region>issued on a lobby now moves the player and runs/rtpon the destination backend with no Redis/SQL.proxy-directis simply "another data-management transport likeredis/sql": the proxy's own in-memoryNetworkTransport+NetworkRequestQueueare 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 whenRTP_NET_SECRETis set; proxy-local methods (claim/dequeueReady/reaper) never leave the proxy. As a result enrolment flows through the standardNetworkEnrolmentBuffer->NetworkRequestQueue.flushPending, the proxy's existingTransportRequestTriggerSource+ dispatcher relocate the player viacreateConnectionRequest, and arrival redeem runs through the standardJoinTriggerSource(findReservation/redeem) - the same code the Redis/SQL tiers use, with no behavioural branch outside the binding factory.ProxyDirectNetworkBindingis now a full RPCNetworkTransport, plus a newProxyDirectNetworkRequestQueue(rtp-core); the proxyProxyDirectListenerdispatches each RPC onto the proxy's store. Reservation tokens are retained this pass (slimming them is a future cleanup). Covered byProxyDirectNetworkBindingTest(5) andProxyDirectListenerTest(2). -
Per-server
/rtppermission gate for networked backends. A qualified cross-server target/rtp <server>:<region>is now gated byrtp.servers.<server>(the destination backend) in addition to the existingrtp.regions.<region>(the region), mirroring the localrtp.regions.xmodel so operators can allow/deny teleport per backend. Enforced in theRegionParametervalidator, which also filters tab-completion, so a forged argument cannot bypass the suggestion filter.rtp.servers.*defaults to op (and is a child ofrtp.*) in both the full and liteplugin.yml. -
proxy-directnetwork transport: player-independent cross-server region discovery on the DB-free edition (rtp-proxy-ADR-017). A newtransport.type: proxy-directlets a backend open its OWN outbound TCP connection to the proxy companion (configuredtransport.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 port25599) that ingests backend pushes into and serves the merged availability snapshot from the same store thertp:netplugin-message companion uses; frames are HMAC-SHA-256 signed whennetwork.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-defaultregion row for a server that has not actually reported. Covered byProxyDirectNetworkBindingTest(4),ProxyDirectListenerTest(1), andVelocityProxyAvailabilityCacheTest. -
/rtp info biomesbiome-occupancy leaderboard. A new/rtp infosubcommand 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-memoryBiomeActivityTracker(RTP.biomeActivity,rtp-core) accumulates per-biome occupancy; the platform sampler periodically enumerates online players andBiomeActivityTracker.sample(...)dispatches each per-player biome read to that player's owning thread viaRTP.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 (~30ssampler pulse); counts are in-memory only and reset on restart/reload, so behaviour is identical in the full and lite editions. Gated by the existingrtp.infopermission. NewinfoBiomeActivityHeader/infoBiomeActivityRow/infoBiomeActivityEmptymessage keys mirrored across every shipped locale. Covered byBiomeActivityTrackerTest(3). Fabric/NeoForge samplers are a tracked follow-up. -
spark profiler is now an optional source for
/rtp infoTPS/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 coarseServer#getTPS()/Server#getAverageTickTime(). spark is a pure soft-dependency reached entirely by reflection (no compile dependency onme.lucko:spark-api);softdepend: [spark]inplugin.ymlonly constrains load order so the spark API is ready when queried. NewSparkMetricsBinding(per-field merge over a native delegate - player count / soft cap / chunk backlog / db latency / Folia regions still come from the native binding) andReflectiveSparkStats(self-disables permanently on aClassNotFoundException/NoClassDefFoundErrorsuch 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 byMetricsBindingDispatcher#wrapWithSparkIfPresenton the Paper, Spigot, and Folia paths. On Folia, spark wrapsFoliaMetricsBindingso 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 infopreviously showed a flat, incorrect MSPT) while the per-regionfoliaRegions()samples still come from the native binding. Documented inEXTERNAL_HOOKS.md. Covered bySparkMetricsBindingTest(5) andMetricsBindingDispatcherTest. -
performance.yml#biomeWeightsships the full vanilla biome set pre-listed at the no-op weight1.0(ADR-062). The map previously shipped a singleplains: 1.0example; it now enumerates every vanilla overworld/nether/end biome (grouped by dimension) at1.0, so the knob doubles as an easy-to-edit reference - change a number to bias a biome, set0.0to suppress it, or append a modded biome id, without having to know each biome's exact name first. Behaviour is unchanged: an all-1.0map is identical to the prior default (unlisted biomes already defaulted to weight1.0), and weighting only takes effect underbiomeWeighted: 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/biomeWeightsdraw no longer treats a requested biome that has not yet been scanned as an implicit weight0, 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/rtpinPregenState): 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 true0. 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_RUNSdistinct 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 (BiomeSampleCapabilityenum + defaultRTPServerAccessor.biomeSampleCapability/sampleBiomemethods, currentlyGENERATE_REQUIRED/nullon every platform); the per-version noise-sample fast path remains D-005-gated follow-up work. Covered byBiomeWeightedDrawTest(8 cases). -
Biome-probability weighting for biome-filtered selection (ADR-062). New
performance.ymlknobbiomeWeighted(defaultfalse, requiresbiomeRecall). 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 (MemoryShapegetBiomeKeys/getBiomePrefixSums): a newPregenTask.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-mapgetBiomelookup would land in the wrong biome). A companionbiomeWeightsmap knob lets operators set explicit, non-equal per-biome weights: whenbiomeWeightedis 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 weight1.0,0.0suppresses a biome, and an all-zero/empty set falls back to the equal-probability pick); the shippedplains: 1.0entry is a no-op example, and the equal-probability draw is just the all-equal degenerate case. Weights are parsed once per/rtpinvocation (PregenState), keeping the hot draw allocation-light. Mirrored across every shipped locale'sperformance.yml. Covered byBiomeWeightedDrawTest(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 liveMetricsSnapshotand 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 aliasaboutresolves to the same command). Gated by a newrtp.versionpermission (defaulttrue, also a child ofrtp.*). Covered byVersionCmdTest. -
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.ymlsetsfolia-supported: true, and a new correctness-firstFoliaAwareScheduler(in the lite-bundledrtp-paper-common) routes work through paper-api's regionized scheduler statics (getGlobalRegionScheduler/getRegionScheduler/getAsyncScheduler) and the per-entity scheduler, whileBukkitRTPPlayer.setLocationperforms the teleport viaEntity#teleportAsync(reflectively, since a cross-region syncteleport()throws on Folia; failures are logged per REQ-RTP-S-004).BukkitServerProvider.resolveServerModelprefers the tunedfolia_v*adapter when present (Pro) and falls back to the Paper accessor +FoliaAwareSchedulerotherwise (lite). The tuned, throughput-optimizedrtp-foliaadapter 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'sFILLED_MAPitem viaWorld#dropItemon the thread that ranMapDispatch, which on Folia is the global region thread - it does not own the player's region, so Folia threwNullPointerException: ... ServerLevel.getCurrentWorldData() is nulland the chart was never delivered. The region-thread hop is now performed once at the call site:MapDispatch.paintdispatchesbinding.deliverTo(...)throughRTP.scheduler.runTask(viewerLocation, ...)(resolved viaRTP.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 anEntitySchedulerhop -deliverTosimply drops on the (now correct) calling thread, and the S-004 failure-to-mapUnavailablepath is evaluated inside the scheduled runnable. Covered byMapDispatchTest,BukkitMapBindingTest, andFoliaMapBindingTest. -
Metrics now install on the free (lite) build running on Folia, so bStats /
/rtp inforeport sampled data instead of UNSAMPLED. On a Folia server the lite jar'sMetricsBindingDispatcher.install()tried to load the Pro-onlyFoliaMetricsBinding(the wholertp/folia/**adapter is excluded from the MIT lite jar, ADR-061), caught theClassNotFoundException, and aborted the metrics install with a startup WARNING + stack trace - leaving the binding at NOOP. The dispatcher now resolves each platform binding through atryInstallBinding(...)helper that returns gracefully (logging at FINE, no stack trace) when a binding class is absent, falling through Folia -> Paper (Bukkit#getTPSworks on Folia) -> the raw Bukkit sampler. Lite-on-Folia therefore installsPaperMetricsBindingand metrics work out of the box. Covered byMetricsBindingDispatcherTest. -
(Pro) Folia TPS/MSPT metrics no longer go UNSAMPLED on an idle server.
FoliaMetricsBinding's scalar TPS/MSPT clock was fed only byFoliaRegionProcessor, which runs only while a region has queued/rtptasks; with no teleport traffic no samples were recorded and the 60s idle-eviction left/rtp infoand 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-regionfoliaRegions()list), and self-terminating on hot-reload/uninstall. Per-region attribution fromFoliaRegionProcessoris unchanged. Covered by a newFoliaMetricsBindingTestcase. -
Relative coordinate tokens (
/rtp centerx=~ centerz=~) now resolve to the player's position instead of a garbage center. The BukkitCoordinateParameteradvertises the vanilla/spreadplayers-style~/-~tokens in tab-completion, but the per-call shape-override path inRTPCmd.computeparsed override values withLong.parseLong->Double.parseDouble->Boolean.valueOf; a~value fell through toBoolean.valueOf("~") == false, socenterx/centerzsilently became the booleanfalse(an effective0center) rather than the caller's coordinate. A newRTPCmd.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 byRelativeCoordinateResolutionTest(6 cases). -
Fabric and NeoForge no longer suggest
/rtpsubcommands and parameters the caller lacks permission for (commands-api-ADR-001; REQ-API-F-007). The Brigadier bridge's greedyargs-slot suggestion provider (BrigadierCommandAdapter.argsSuggestionsFor) emitted every subcommand name and everyparamName=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 BukkitTreeCommand.onTabCompletecontract, which filters by permission. The provider now gates both subcommand-literal andparamName=suggestions throughBrigadierBridgeContext.permissionCheck()(empty/null permission stays open; a throwing predicate denies and logs, mirroringapplyRequires). Sub-command literal nodes were already requirement-gated viarequires(...)and filtered out of the client command-tree packet; this closes the dynamic-suggestion leak. Covered byBrigadierSuggestionPermissionTest(4 cases).
Changed¶
-
Released jars trimmed of dead weight. Both
shadowJar(Pro) andshadowLiteJar(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-facingdocs/architecture/**tree (per-attempt pipeline internals, chunk-ticket lifecycle, network model, etc.) - it remains available in the public repository - while the operator-facingdocs/admin/**set (Quick Start, Configuration, Commands, Hazards, Runbook, proxies) is unchanged. No code, dependency, or public-API change:shadowJar'sminimize()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 infotrimmed to stay compact before any metrics are sampled. The live-health block previously printed a wall ofn/arows (TPS, server MSPT, average pipeline latency, the P50..P99 percentile line, and database latency) on servers where no liveMetricsBindinghad sampled yet.InfoCmdnow 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 onPlaceholderProvider(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 singleDRM: <source> id=<id> nonce=<nonce>line (BuiltByBit builds appendbbb=<resourceId>@<timestamp>); the DRM strings stay hardcoded in core rather than moving into the player-editablemessages.yml. Covered byInfoCmdTest. -
Per-batch
[TRACE] ScanTask diagline demoted from INFO to FINE. The scan diagnostic split (probeNull / adjustNull / cacheHitLoad / genscan*) had been logged atINFO, printing a line every few seconds to the default console for the full duration of a world scan. It now logs atFINE, 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:RTPCmdNeoForgeRootwiresMenuWiringSupport.attachTowith a newNeoForgeBookMenuRenderer(translates theMenuModelinto a fully-formattedNeoForgeBookSpecand dispatches an interactive written-book modal through a newNeoForgeVersionAdapter.openBookMenuSPI, implemented on thev1_21_R1carrier via a typedWrittenBookContent+ transient-slotClientboundContainerSetSlotPacket->ClientboundOpenBookPacket-> slot-revert, falling back toChatMenuRendererotherwise) and aNeoForgeChatPromptCallback(TTL-bounded chat-prompt substitute for the Paper anvil GUI, backed by the typed, cancelable NeoForgeServerChatEvent- no reflective proxy, unlike Fabric). Map charts render to a real vanilla filled-map via new NM-freeNeoForgeMapBinding+NeoForgeMapCanvas(installed inRTPNeoForgeModonly when the active carrier opts in viasupportsMapCharts(); per-viewer state released on disconnect, REQ-RTP-MAP-003). ANeoForgeMetricsBinding(single-region EMA TPS/MSPT sampler) is installed viaRTP.metrics.setBindingand ticked fromonServerTick, and aNeoForgeBackendStateSampleris installed ontoRTP.backendStateSamplerFactoryso a network-mode boot can sample live host state. New player capability markersNeoForgeBookOpener/NeoForgeMapSinkkeep the rawServerPlayerprivate toNeoForgeRTPPlayer. Still an opt-in build island (-PincludeNeoforge); the S-00x regression guards (N2.7) and the live network-mode boot / runtime/rtpround-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#hasPermissionnow resolves through a three-tier chain ported from Fabric (rtp-fabric-ADR-011): LuckPerms first (when installed), then theplugin.ymldefault table, then the on-diskops.jsonop-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. NewNeoForgeDefaultPermissions(default table),NeoForgeOnEventPermissions(closed-namespace constants),NeoForgeEffectivePermissionsResolver(the effective-set computation feeding the menu surface, plus a console op-equivalent variant), andLuckPermsNeoForgeEnumerator(a reflective LuckPerms facade - node enumeration plus a cached-data, wildcard-aware tri-state check - with no compile-time dependency onnet.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 inEXTERNAL_HOOKS.md(ADR-026). Still an opt-in build island (-PincludeNeoforge); the runtime/rtpround-trip remains a Phase N2 follow-up. -
NeoForge
/rtpcommand tree wired (commands-api-ADR-001; MULTI_PLATFORM_PLAN.md Phase 4 Step NG). The NeoForgeRegisterCommandsEventtrampoline now registers the full/rtpBrigadier tree via the sharedcommands-apiBrigadierCommandAdapter, replacing the Phase N1 scaffold that logged "not yet wired". NewRTPCmdNeoForgeRoot(port ofRTPCmdFabricRoot:region+ nestedworld/price/worldborderoverride/shape/vert, plusbiome/player/world/toggletargetpermsparameters andreload/config/scan/info/clearcachesubcommands) and a typedNeoForgeBrigadierSourceBridge(resolves aCommandSourceStackto a player UUID and routes permission checks throughRTP.serverAccessor.getSender(uuid).hasPermission(...)). Because NeoForge is Mojmap-at-runtime, no reflectiveProxy/intermediary dance is needed (unlike the Fabric registrar): the dispatcher and command source are referenced directly. The/rtp menusurface, the full permission chain, and the runtime/rtpround-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-fabricunderplatforms/rtp-neoforge/: a ModDevGradle build (rtp-neoforge-common+ thertp-neoforge-v1_21_R1carrier),META-INF/neoforge.mods.toml, the@Modentry pointRTPNeoForgeMod(server lifecycle + per-tick scheduler drain +RegisterCommandsEventtrampoline onNeoForge.EVENT_BUS), a complete server-threadNeoForgeScheduler(RTPSchedulerport ofFabricScheduler; NeoForge is single-main-thread, no Folia regions), andNeoForgeCommandRegistrar/ 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; theRTPServerAccessorimplementation, command wiring, the S-005 async chunk path, and the/rtpround-trip remain Phase N2 follow-ups (not yet runtime-functional). -
(Pro) Second NeoForge carrier
rtp-neoforge-v26_1_R1for 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 202626.xline (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, soV26_1_R1NeoForgeVersionAdapteris 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#installVersionAdapterroutes a26.*runtime to the new carrier;rtp-pluginmerges its Java 25 bytecode into the unifiedLeafRTP-Projar (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.2boot line), so the Mojmap API surface is verified. A live/rtpteleport stall on 26.1.2 (L1 kept-cache stuck at 0, no chunk tickets, and the first teleport never completing) was traced torequestFullChunkAsyncadding its own transient load-ticket and then removing it inside awhenCompletethat ran off the server thread, wedging the 26.x chunk holder so its FULL-status future never resolved (getOrLoadChunk ... TimeoutException); the carrier now relies ongetChunkFuture(..., 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 existingv1_21_R1carrier already serves the whole 1.21 line viastartsWith("1.21"). -
Region-specific schematic paste now works on Fabric, with a single shared schematic translator across every platform (ADR-058). A
schematics/<region>.schemfile 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-neutralWorldBlockSchematicPaster(rtp-api), driven by twoRTPWorldprimitives (default no-op):setBlocks(List<BlockDelta>)(block-state writes) andrestoreBlockEntities(List<PlacedBlockEntity>)(container-inventory restore). The shared Sponge.schemdecoder 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) implementsetBlocksvia the vanillaBlockStateParser+ServerLevel.setBlockon the server thread (S-005-clean, per-block skip auditing per S-004). Bukkit/Paper/Folia were collapsed onto the same single translator: the formerBukkitSchematicPasteris removed and its native block-write + container-restore logic moved into a sharedBukkitBlockWriterbackingBukkitRTPWorld/FoliaRTPWorld'ssetBlocks/restoreBlockEntities, so no platform carries a bespokeSchematicPaster. Container/block-entity contents restore on Bukkit/Paper/Folia; Fabric stays block-states-only this pass (itsrestoreBlockEntitiesis the default no-op). Covered byWorldBlockSchematicPasterTest(2) andBukkitBlockWriterChestTest. -
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_BIOMESwas added toMapDispatch.LIVE_REFRESH_KINDS;RegionBiomesResolveris pure and re-runnable per tick (no chunk I/O, S-005-clean - it reads only the in-memory persisted biome cache viaMemoryShape.biomeAt). Covered by a newMapDispatchTest.regionBiomes_bindsLivecase. -
Biomes row in the admin Visualizations menu. The
/rtp adminVisualizations chart-kind picker now lists a "Biomes" row alongside "Bad locations" and "Pipeline health"; clicking it opens the per-region picker and paints theREGION_BIOMESchart. The typed/rtp visualization biomes [region=<name>]leaf andVisualizationDispatch.paintBiomeswere 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).
/rtpvisualization charts (bad-locations heatmap, region-shape, live sparkline) now render to a real vanilla filled-map on Fabric instead of bottoming out onNoopMapBinding(... no concrete MapBinding installed). The Fabric map binding ships in both the full and the rtp-lite assemblies (REQ-RTP-MAP-004). New platform-neutralFabricMapBinding+FabricMapCanvas(rtp-fabric-common, nonet.minecraft.*binding) paint the maps-api logical palette into a 128x128 ARGB buffer and hand it to three new NM-freeFabricVersionAdapterseams (renderMapChart/releaseMapChart/supportsMapCharts). Implemented on the MC 26.2 carrier (V26_2_R1FabricVersionAdapter): allocates aMapItemSavedData/MapIdper chart, matches each pixel to the nearest vanillaMapColor, pushes a full-canvasClientboundMapItemDataPacket, and delivers aFILLED_MAPitem; live charts refresh at ~1 Hz. Installed inRTPFabricModonly when the active carrier supports it (other MC lines stay onNoopMapBindingwith the localizedmapBindingMissingmessage); 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_R1FabricVersionAdapterandV26_2_R1FabricVersionAdapternow implementopenBookMenu(Object, FabricBookSpec)with a typed, Mojang-named port of the 1.21.11 carrier (build aWRITTEN_BOOKItemStackwith aWrittenBookContentdata component, send a transient hotbar-slotClientboundContainerSetSlotPacket->ClientboundOpenBookPacket(MAIN_HAND)-> slot revert, never mutating the server-side inventory). Per-fragment hover/click is built via the version-localV26_*FabricLegacyText.parseInteractive(...)(reflectiveHoverEvent/ClickEventrecord-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 isFilterable<String>, notFilterable<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 toChatMenuRendereron 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-neutralFabricBookMenuRenderer(rtp-fabric-common, nonet.minecraft.*binding) translates theMenuModelinto a fully-formattedFabricBookSpec(placeholders + colour codes viaRTPServerAccessor.format; click commands via the sharedMenuActionToCommand) and dispatches through a newFabricVersionAdapter.openBookMenu(Object, FabricBookSpec)SPI. The per-carrier overrides (v1_21_R1,v1_21_R5,v1_21_R11) build aWRITTEN_BOOKItemStackwith aWrittenBookContentdata component (fragments built byFabricLegacyText.parseInteractive(..., ClickKind.RUN)), send a transientClientboundContainerSetSlotPacketfor the held hotbar slot, sendClientboundOpenBookPacket(MAIN_HAND), then revert the slot, so the server-side inventory is never mutated. The renderer transparently falls back to the existingChatMenuRendereron 1.20.x and the deobf 1.26.x carrier (whereopenBookMenukeeps its defaultfalse), when the viewer is offline, or when the book dispatch throws. Wired inRTPCmdFabricRootin place of the bareChatMenuRenderer. Covered byFabricBookMenuRendererTest(6 cases).v26_1_R1book support remains a tracked follow-up. - Early/experimental MC 26.2 Fabric adapter (rtp-fabric-ADR-014). New
rtp-fabric-v26_2_R1submodule, cloned fromv26_1_R1(deobfuscated MC line, Loom 1.15 unobf, JDK-25 toolchain), pinned to the26.2-rc-2release candidate (loader0.19.2, fabric-api0.150.2+26.2).RTPFabricMod#adapterFqnFordispatches the26.2line (startsWith("26.2"), which matches both the pre-release / release-candidate friendly string and eventual26.2.xfinals) toV26_2_R1FabricVersionAdapter; the adapter bytecode is merged into both the full and rtp-lite jars post-remap via a dedicatedfabric262Bytecodeconfiguration. 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
/rtpnever 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 inRegion.executeloads each candidate chunk, then reads it back viaNeoForgeRTPWorld.getCachedChunkto re-run the vertical adjustor before pinning it with a keep-ticket.NeoForgeRTPWorld.chunkCache/rtpChunkCachewereWeakReferencemaps, and a freshly loaded chunk is only held by vanilla's transientcreate=truegeneration 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, sogetCachedChunkreturned null for every promotion (proven by the[RTP][PROMOTE_DIAG] ... getCachedChunk returned nulldiagnostic): the L1 kept cache never filled, no keep-tickets were issued, and/rtpnever found a safe spot. Fix:chunkCache/rtpChunkCacheare now strong references (evicted explicitly inforgetChunkAt/forgetChunks), mirroring the proven Fabric 26.1 carrier (V26_1_R1FabricRTPWorld#chunkCache), so a loaded chunk survives the verify hop.loadLiveChunkalso now logs at INFO (REQ-RTP-S-004) when the version adapter resolves a nullChunkAccess, 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)->CompletableFuturesignature is not unique onServerChunkCache(the publicgetChunkFutureplus the privategetChunkFutureMainThread), and the publicgetChunkFuture(...), called on the server thread, internallymainThreadProcessor.managedBlock(...)-s, i.e. re-drives the main-thread task queue; becauseNeoForgeRTPWorld.loadLiveChunkalready invokes the adapter from inside aMinecraftServer#executetask 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 toChunkResult.Fail("Unloaded chunk")(proven by the[RTP][NeoForge 26.1] ... chunkResultError=Unloaded chunkdiagnostic). A blockingServerChunkCache#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:resolveGetChunkFutureMethodnow prefers the private non-blocking primitivegetChunkFutureMainThread(thengetChunkFuture, then a structural scan) - called on the server thread it adds thecreate=trueUNKNOWN 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 viaapplyTicket(...), so S-002 is unaffected. A fourth cause was then found:NeoForgeRTPWorld.loadLiveChunkbounded the dispatch with a 1.5sbridge.orTimeout, so whenever the tick thread fell momentarily behind (the server logged "Running 2535ms behind" during first-chunk worldgen) theserver.executerunnable could not start within 1.5s and the load failed with a spuriousTimeoutException(attributed byPregenTask), so L1 still never promoted and/rtpnever 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/rtpround-trip re-test pending on a JDK-25 host. A fifth cause was found on 26.1.2:getChunkFutureMainThreaddoes not exist on this runtime (onlygetChunkFuturematches the 4-arg signature), so the resolver always fell back togetChunkFuture, which on 26.1.2 resolves immediately toChunkResult.error("Unloaded chunk")without a prior load-ticket - the chunk holder never reached FULL status. Fix:resolveGetChunkFutureMethodnow prefersgetChunkFuturedirectly (removing the deadgetChunkFutureMainThreadfirst-preference), andrequestFullChunkAsyncnow applies a temporaryaddTicketWithRadiuscall before invokinggetChunkFuture(create=true)and removes it in awhenCompletehandler, 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_R1FabricVersionAdaptergainedopenBookMenu,/rtp menu//rtp config/the admin panel still fell back to the chat renderer on 26.x becauseFabricBookMenuRendererrecognised only the commonFabricRTPPlayer(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 implementsRTPPlayerdirectly and does not extend the commonFabricRTPPlayer, so the renderer silently degraded to chat - the book never opened. NewFabricBookOpenercapability interface (rtp-fabric-common): each Fabric player exposes a singleopenBookMenu(FabricBookSpec)method (delegating to the activeFabricVersionAdapterwith its ownServerPlayer, which stays private to the player) and the renderer now just callsopener.openBookMenu(spec)instead of extracting and passing a rawServerPlayer. Implemented on the commonFabricRTPPlayer(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 theopenBookMenuSPI defaultfalseand 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 keepsopenBookMenu's defaultfalse), so the menu falls back to the chat renderer - butFabricServerAccessor's rich-text path could only attach hover/click to the commonFabricRTPPlayer; 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 infoline arrived unclickable. NewFabricInteractiveMessageSinkcapability interface (rtp-fabric-common): a per-version player that implements it builds the hover/clickComponenton its own deobf-linkable runtime, andFabricServerAccessor.sendInteractiveMessage/sendMessageAndSuggestroute through it instead of the plain fallback. Both 26.x carriers implement it via a newparseInteractive(...)(plus reflective, mapping-agnosticHoverEvent/ClickEventbuilders) added to their version-local legacy-text parsers. 1.20.x/1.21.x are unaffected (they use the commonFabricRTPPlayerpath, and 1.21+ opens the book). -
Fabric
rtp scanno longer abandons chunks that need generating.FabricRTPWorld#getOrLoadChunk(both the obf and unobf carriers) bounded each live chunk load with an adapter-ownedLIVE_LOAD_DEADLINE_MSof 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 anullChunkbefore vanilla finished - even thoughScanTask'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)andpause()drained outstanding chunk-load futures with an unboundedinFlightGate.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 sorTimeout, stalling the server for up to many seconds, and every elapsed timeout still logged aChunk generation exceptionWARNING during the cancel - flooding the console. The drain is now bounded (tryAcquirewith 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
FabricVersionAdaptermethods had no live callers anywhere in the tree -blockKey,biomeKeyAt,hasChunk, andairState- 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, theRTPBlockHandle,RTPBlockStateHandle, andRTPRegistryKeywrapper records became unused and were removed. The still-live chunk-load / ticket seam is unchanged:RTPLevelHandle(parameter ofrequestFullChunkAsync/getChunkFull/applyTicket/releaseTicket) andRTPChunkHandle(their return) remain. No behaviour change. -
bStats
pipeline_latency_bucketschart. The chart bucketisedavgPipelineMs, the mean of everyTeleportPipelineTaskcompletion. 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 inRTPCostMetricsCharts,BStatsChartIds.PIPELINE_LATENCY_BUCKETS, and thepipelineLatencyBuckethelper 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-Projar, loadable on a NeoForge server (ADR-033). The releasedLeafRTP-Pro-<version>.jarnow co-shipsMETA-INF/neoforge.mods.tomland the NeoForge platform bytecode alongsideplugin.yml(Bukkit/Paper/Folia),fabric.mod.json(Fabric), andvelocity-plugin.json(Velocity), so one artifact drops straight into a NeoForgemods/folder instead of being rejected asis a Fabric mod and cannot be loaded.rtp-pluginmerges thertp-neoforge-common+rtp-neoforge-v1_21_R1carriers into the jar after Loom'sremapJar(Mojmap names preserved, mirroring the deobf MC 26.xv26/unobf merge), applying the samecommandsapi/effectsapipackage relocation Shadow performs on the rest of the jar; on a non-NeoForge runtime the@Modentry point (RTPNeoForgeMod) and itsnet.neoforged.*/NM references are simply never classloaded. The NeoForge modules build BY DEFAULT (settings.gradle); network-constrained hosts drop them with the new-PexcludeNeoforge(orEXCLUDE_NEOFORGE) flag (replacing the former opt-in-PincludeNeoforge), in which case the unified jar carries noneoforge.mods.toml. -
Fabric anvil pre-filter helpers lifted into
rtp-coreso they can be referenced generically. The platform-neutral palette reconciler and theColumnProbe->ChunkColumnProbeadapter the Fabric carriers used were duplicated in bothrtp-fabric-commonandrtp-fabric-common-unobfeven though neither touchesnet.minecraft.*(they depend only onrtp-anvilandrtp-api). They now live once inrtp-coreasio.github.dailystruggle.rtp.common.anvil.PaletteNormalizerandAnvilColumnProbeAdapter(withrtp-coregaining ananvil-apidependency; 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-pluginintortp-coreso 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 fromio.github.dailystruggle.rtp.bukkit.networktoio.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 BukkitListener/PlayerJoinEvent/PlayerQuitEvent/CommandSendersurface onto the platform-neutralPlayerLifecycleHookSPI plusRTPPlayer.performCommandandPredicate<RTPCommandSender>; the backend heartbeat sampler is now obtained through a settableRTP.backendStateSamplerFactory(Bukkit installsBukkitBackendStateSamplerinAbstractServerAccessor.start) rather than a directnew BukkitBackendStateSampler(...). No behaviour change on the user-confirmed-working Paper path; the network test suite (141) moved with the code tortp-coreand stays green, andLobbyModeTest(18) still passes fromrtp-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.
RTPFabricModnow installsRTP.backendStateSamplerFactory(a newFabricBackendStateSamplerinrtp-fabric-commonthat reads TPS/MSPT/player-count from the Fabric metrics binding and loaded worlds viaRTPServerAccessor.getRTPWorlds()), readsrouting.lobbyModeearly, boots the platform-neutralNetworkModeBootstrapafter the database comes up atSERVER_STARTED, registers the join-redeem and waitlist-quit listeners onto theFabricPlayerLifecycleHook, and tears the bootstrap down atSERVER_STOPPING. Cross-server/rtprouting works automatically because the sharedRTPCmd.computeconsultsRTP.networkCommandHook, which the bootstrap installs. Covered byFabricPlayerLifecycleHookTest(5). The Fabric waitlist command-guard (blocking a fresh/rtpwhile 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(bindingVaultCheckerthrough theRTPHookseconomy facade when Vault is present, identically to the full bootstrap), shipseconomy.ymlin the lite jar, declaresVaultin itsplugin.ymlsoftdepend, and drops theliteJarStructureCheckban oneconomy.yml. Optional per-/rtpcharging (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 rootLICENSE-MIT, mirrored as module-localrtp-api/LICENSEandrtp-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 rootLICENSE, which gained a preamble describing the split. The lite jar now bundles the MIT text as its in-jarLICENSEinstead of the PolyForm text, and theliteJarStructureCheckGradle 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:netherissued from another server routed toworld1correctly (theserverHintwas honoured) but always arrived in the default/overworld region: the requestedregionKeywas parsed and reached the proxy dispatcher inRtpRequest, then dropped at three points - the dispatcher'stransport.claim(...)carried no region,ReservationTokenhad no region field, and the destination backend'sJoinTriggerSourcedispatched a barertp. The region constraint is now threaded end-to-end:NetworkTransport.claimgains a region-aware overload (legacy 3-arg preserved),ReservationTokencarries an optionalregionKey(), all three transport bindings persist and read it back (in-memory token field, a new nullableregion_keycolumn onrtp_network_tokensfor SQL with an idempotent ALTER migration, and aregionKeyHSET field for Redis viaclaim.luaARGV[8]), the dispatcher passesrequest.regionKey()to the claim, andJoinTriggerSourcere-attaches it asrtp region=<regionKey>on arrival (regionless arrivals still dispatch a barertp). Covered by new region-propagation regression tests on the in-memory and SQL (H2) bindings. -
Cross-server
/rtparrivals now teleport on a Fabric backend (no moreNoSuchMethodErroron join) (ADR-049). When a Velocity-routed player joined a Fabric backend,JoinTriggerSourceredeemed the reservation token and dispatched/rtpviaFabricRTPPlayer.performCommand, which calledServerPlayer#createCommandSourceStack(). That method's intermediary (method_5671) is absent on the MC 1.21.11 runtime, so the dispatch threwNoSuchMethodErrorand the player connected but was never teleported (same Yarn/intermediary drift family already worked around forgetServer/teleportTo/ thefield_13995server field in this file). A first fix added a hand-builtCommandSourceStackfallback, but that path calledEntity#position()(intermediarymethod_19538), which also drifts on 1.21.11, so it threwNoSuchMethodErrorin turn and/rtpstill was not dispatched. Fix:buildCommandSource(...)now inserts a drift-immune intermediate attempt -MinecraftServer#createCommandSourceStack()re-anchored on the player viaCommandSourceStack#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 guardedsafePosition/safeRotation/safeDisplayNamehelpers 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
/rtparrivals teleport there (ADR-049). After the network plumbing was lifted intortp-core, the backend heartbeat sampler is obtained throughRTP.backendStateSamplerFactory, which the Bukkit accessor installs inAbstractServerAccessor.start(Object). Folia uses a separateAbstractFoliaServerAccessor(it does not extend the Bukkit accessor), and itsstart(Object)neither installed the factory nor registered aPlayerLifecycleHook. A Folia backend therefore aborted its network boot withno BackendStateSampler factory installed by the platform adapter, and becausegetPlayerLifecycleHook()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 aBukkitPlayerLifecycleHook(Folia is a Bukkit-API platform; the hook is reachable viartp-folia-common->rtp-paper-common->rtp-bukkit-common), overridesgetPlayerLifecycleHook()to return it, and installsRTP.backendStateSamplerFactorywithBukkitBackendStateSampler(which uses only Folia-safeBukkit.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
PasteOptionsAPI andRegionVerifierRegistryfootprint claim checks (S-003). New prefabs updated to use it (skyblock,oneblock,high-performance,multi-world). - Pluggable bare-
/rtproot action (ADR-056, REQ-API-F-006). NewRootActionRegistrySPI (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
RTPAddonlifecycle interface +AddonRegistry(RTP.addons, ServiceLoader-based) so an addon jar runs unchanged on Bukkit/Paper/Folia, Fabric, and proxy JVMs.RTP_ExampleAddonported with zeroorg.bukkit.*imports. - Optional PvP / combat-tag gate (ADR-055). Off by default (
safety.yml#pvpCheckEnabled=false). When enabled,/rtpis refused for a player currently in combat, using either a boundPvPCombatStateRegistryprovider (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 anEntityDamageByEntityEventlistener and Fabric viaServerLivingEntityEvents.AFTER_DAMAGE(both resolve the projectile shooter / primed-TNT igniter as the aggressor and stamp victim/aggressor perpvpTagVictim/pvpTagAggressor). The gate is consulted at the/rtppre-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 configurablemessages.yml#pvpInCombatstring (REQ-RTP-F-013). Sixsafety.ymlknobs: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.setupbinds the first enabled plugin (priority PvPManager, then CombatLogX, then Simple Combat Log) toPvPCombatStateRegistryviaRTPAPI.hooks().pvpCombatState(), gated onisPluginEnabled(...)like the claim integrations. When none is installed (orpvpSource: 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 byPvPCombatAdapterTest. uniquePlacementsis now an integer chunk radius (was boolean; defaults to0= off).N >= 1clears a(2N-1)x(2N-1)chunk square around each used spot so placements spread out; legacytrue/falsestill coerce to1/0. Retired spots tagged with a dedicateduniquePlacementfail cause.- Config getters tolerate boolean<->int cross-typing, so a legacy
true/falseon a now-numeric knob (or0/1on a boolean knob) resolves instead of throwing. - Optional emergency-platform block-restoration timeout (ADR-060). New
safety.ymlknobplatformRestoreSeconds(-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 infonow surfaces generation outcomes (REQ-RTP-OBS-007, ADR-052): success/failure rate and a per-cause rejection breakdown, via six new placeholders and threemessages.ymllines.- 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 clearadmin command tree (permissionrtp.admin). Groups the clear actions under one verb for cleaner tab-completion:/rtp clear cacheclears 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 newRegionQueueManager.clearCaches()), alongsidecooldown,queue,limit, andinvuln.rtp.adminpermission node declared inplugin.yml(both full and lite), gating/rtp clearand 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/airBlocksnow 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.
RegionBiomesResolverno longer reads on-disk.mcapalettes viaRTPWorld.readBiomesInRegionFile; it classifies each in-disk pixel through the newMemoryShape.biomeAt(int, int)/biomeAt(long), a floor-search over the persistedbiomeKeysCache/biomePrefixSumsCacheaccumulated 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.isChunkGeneratedon Bukkit / Paper / Folia now routes through the sameAnvilRegionOccupancyCachebitmap path Fabric uses, andScanTask's PRESCAN precheck runs unconditionally on every platform.BukkitRTPWorld.isChunkGeneratedandFoliaRTPWorld.isChunkGeneratedpreviously delegated toorg.bukkit.World#isChunkGenerated, a synchronous chunk-system / region-file index walk on the calling thread. WhenScanTaskinvoked it per-candidate inside the in-flight gate, it collapsedpeakInFlightfromcap=50to ~2-3 and held PRESCAN cps at ~19 on a 193k-chunk world (the[TRACE] ScanTask diagregression). The previously-shipped Fabric-onlyisFabricPlatform()gate that fenced off the precheck on Bukkit-family platforms is removed; bothBukkitRTPWorld.isChunkGeneratedandFoliaRTPWorld.isChunkGeneratednow tryWorld#isChunkLoadedfirst (cheap, off-region safe), thenAnvilPrefilter.regionFileFor+AnvilRegionOccupancyCache.isOccupiedagainst ther.X.Z.mcafile, with thetrue-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
RtpOutcomeStatsaccumulator (rtp-coremetricspackage) records every location-generation success and per-FailTypesfailure, fed from the single always-onPregenTask.recordOutcome(...)chokepoint independent of theverboseflag, so success/failure rates and a per-cause rejection breakdown (including claim/protection rejections viasafetyExternal) accumulate from real traffic with no verbose logging and no traffic simulation. The verbosefailMapconsole dump and S-004 attribution are unchanged.MemoryShapenow tags each persisted bad-location run with one rejection cause: abadCauseCachebyte array aligned tobadKeysCache, cause-awareaddBadLocation(long, FailTypes)/addBadChunk(long, FailTypes)overloads, first-cause-wins through the RLE rebuild, a versioned.binformat (magic + version header, one cause byte per run, legacy files load asmiscwith no migration), and acausefield in the debug JSON export. The four chunk-attributablePregenTask.addBadChunksites are tagged (vert / biome / safety / safetyExternal); all other callers default tomisc. Covered byRtpOutcomeStatsAndCauseTaggingTest(5 cases);ReqRtpS004NullChunkAttributionTestandMemoryShapesuites (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 eachdispatch*helper is the sole security boundary. Renderer rewrite (BookMenuRenderer.toClickEvent) emits 22 concrete commands, one perMenuActionvariant. New concrete leaves under/rtp menu:open,admin,front,visualizations,picker,page,config,info,anvil,stage,unstage,apply,discard,multi; sibling/rtp visualizationfor maps.MenuAction.OpenMap(UUID chartSpecToken)reshaped toOpenMap(ChartSpec.Kind kind, String regionName).MenuTokenRegistry(rtp-api),LocalMenuTokenRegistry, andChartSpecTokens(rtp-core) deleted; theMenuTokenRegistryctor parameter dropped from 9 classes (MenuRedeemSubcommand,BookMenuRenderer,FrontPageBuilder,AdminPanelBuilder,CommandTreeMenuBuilder,InfoBookBuilder,PrefabConfirmationMenuBuilder,VisualizationsSubmenuBuilder,MultiConfigMenuBuilder);RTPCmdBukkitreflective wiring switched to no-arg ctor lookup.messages.yml::menuExpiredretired (no token lifetime to expire);menuInvaliddocumentation 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 suiteReqRtpMenuConcreteCommandsTest(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 adminshim opens the curated admin panel (OpenAdminPanel, gated onrtp.menu.admin) with a Setup section listing five bundled prefabs (survival-default,low-performance,high-performance,folia-tuned,multi-world) underrtp.admin.prefab. Each row opens a confirmation page (PrefabConfirmationMenuBuilder) backed by a ~60s caller-bound single-use nonce;Confirmwrites viaPrefabDiskIO.writeWithBackupwith.bak.<epochMillis>retention (prefab.bakRetentionknob, default 3) plus best-effort reload. Matching chat surface/rtp admin prefab {list,apply,confirm,rollback}; pure-function core underrtp-core/.../commands/prefab/. 15MessagesKeysconstants for the Setup section propagated through the locale TSV pipeline. Covered by 7 test classes; new admin-facingdocs/admin/PREFABS.md. - Network mode shared cross-server waitlist (rtp-proxy-ADR-015, REQ-RTP-NET-015). Mirrors the per-backend
playerQueueUX across proxies in five slices: (1)NetworkWaitlistSPI +InMemoryNetworkWaitlistreference impl (LinkedHashMap-backed,maxSizedefault 1024); (2)NetworkWaitlistDrainer+DefaultRtpDispatcherrewiring + newWAITLISTEDQueueState+WaitlistLeaderLeaseSPI; (3a) Redis-backedRedisLeaderLease(NX/XX PX, compare-and-DEL) for cross-proxy single-leader election; (3b)RedisNetworkWaitlistwith 7 atomic Lua scripts (enrol, drain-batch, position, remove, reap, refresh-ttl, etc.); (4) lobby-side UX wiring (notify, command-lock, quit-removal); (5)MessagesKeysparity: newalreadyQueuedkey +[position]placeholder propagated through every shipped locale. Covered byInMemoryNetworkWaitlistTest(15),DefaultRtpDispatcherWaitlistTest(4), opt-inRedisLeaderLeaseIT(8),RedisNetworkWaitlistIT, andLocaleParityTest. - Lobby load balancing v1 (most-kept) documented. A backend booted with
network.yml::routing.lobbyMode: trueadvertisesacceptingRequests=falseandregionsAvailable=Set.of(); bare/rtpon it is intercepted byBukkitNetworkCommandand routed to the peer with the most kept locations. Code shipped earlier as Slices I+J during the cross-server/rtpstabilisation; this entry documents the design, sequencing, and coverage (LobbyModeTest12,LobbyModeEarlyReadTest3). - 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 asRUN_COMMAND(versus the siblingsendMessage(...)which usesSUGGEST_COMMAND); overrides on Bukkit (AbstractServerAccessor), Folia (AbstractFoliaServerAccessor), and Fabric (FabricServerAccessor, threaded throughFabricLegacyText.parseInteractive(..., ClickKind)withCLICK_CTOR_RUNprobed for 1.21.5+ record-shapedClickEvent$RunCommand). New platform-neutralChatMenuRendererinrtp-corewalksMenuModeland emits one chat message per clickable fragment (decorative-only lines coalesce); shares theMenuAction -> /rtp menu ...translation table withBookMenuRenderervia the newMenuActionToCommandhelper -- single source of truth post-ADR-050.RTPCmdFabricRoot:218-249mirrorsRTPCmdBukkit:215-230and wiresChatMenuRenderer+FabricChatPromptCallback(TTL-bounded chat-prompt substitute forPromptAnvilInputper ADR-012 section 3, drained viaServerMessageEvents.ALLOW_CHAT_MESSAGEwith the reaper scheduled throughRTP.scheduler.runTaskTimerAsynchronouslyper AGENTS.md Scheduler Usage) intoMenuWiringSupport.attachTo; permission probe routes through ADR-048 Phase B'sRTPServerAccessor.menuPermissionProbe(uuid). Covered byChatMenuRendererTest(12 cases includingMenuActionToCommandregression guards) plus existingBookMenuRendererTest(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;BukkitMapBindingfirst concreteMapBindingundermaps-api/.../mapsapi/bukkit/(allocate/renderEphemeral);MapBindingLifecycleSPI mirroring commands-api/effects-api registration patterns with viewer-indexedchartIdsByViewerandMapDispatchTest(10);FoliaMapBindingthin override (Bukkit paths inherited; quit/disable hooks delegated);ChartSpecTokens(60s TTL, single-use, player-bound, atomic-removeconsume, sweep seam) with 21-case test; Stage-2 menu wiring (MenuAction.OpenMapsealed permit,/rtp inforow,BookMenuRendererarm, redeem throughMenuRedeemSubcommand). New baselinemessages.yml::menuInfoBadPointsLabelpropagated 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-lineNetworkModeBootstrap) have zeroorg.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-corepath with a single new SPI primitive (PlayerLifecycleHook) onRTPServerAccessorrather than the parallel-reimplementation path proposed in rtp-fabric-ADR-013 (which was flipped to Superseded).MULTI_PLATFORM_PLAN.mdStep J rewritten to reflect the new sub-item list. Implementation is a follow-up change.
Changed¶
commands-apiparameter delimiter de-canonicalized;effects-apinamespaced-id coercion collapsed to a single path. Follow-up to the:->=command syntax migration.CommandsAPI.parameterDelimiter/multiParameterDelimiterare nowpublic static final char(binary-compat forgetstatic); ~20 internalTreeCommandsites use"="/","literals orcharoverloads;splitOnParamDelimiterremains the named primitive.REQ-API-F-005re-worded to absolute state. Oneffects-api,BukkitValueCoercer.resolveViaRegistry/resolveSoundlose theraw.contains(":")bifurcation in favour of a singleNamespacedKey.fromStringpath with bare-token front-loader (preservesENTITY_PLAYER_HURTunderscore-to-dot). LegacylegacyColorFromDelimitedStringremoved. Existing:commands-api:test(31) and:effects-api:test(55) green.
Fixed¶
-
NetworkWaitlistGuardno longer gates non-teleport/rtpsubcommands. The waitlist sender-check (added toRTPCmdBukkitviaaddSenderCheck(...)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-argsRTPCmdBukkit.onCommand(sender, command, label, args)entry now inspectsargs[0]against the livegetCommandLookup()and skips the sender-check loop when the invocation is a subcommand dispatch. Mirrors the existing early-return at the parametriconCommand(..., CommandsAPICommand nextCommand, ...)entry, which already bails whennextCommand != nullbefore running sender checks. The bare-/rtpteleport path is unaffected. -
/rtp argument-rejection messages now substitute the offending argument, and use the canonical
key=valuesyntax (REQ-RTP-S-004, REQ-RTP-F-013). Four sites inRTPCmd.compute(unknownplayer, unknownworld, unresolvableregion, region with null world) and two inScanResetCmd/ScanStartCmdwere callinglangParser.getConfigValue(MessagesKeys.badArg, "player:" + name)-- the second argument is the parser's default-when-key-missing, not a placeholder substitution. With the defaultmessages.yml::badArgtemplate"&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]"(matchingBaseRTPCmd.msgBadParameterandBukkitBaseRTPCmd.msgBadParameter) and explicitly callsmsg.replace("[arg]", ...)to substitute the offending argument. Additionally, all six call sites and the twoMenuRedeemSubcommandRunRtpCommandarms that synthesise/rtp info <scope:name>argv now use the canonicalkey=valuesyntax (player=<name>/world=<name>/region=<name>) rather than the legacykey:valueform, 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 explicitregion=<server>:<region>whose<server>was the local backend's ownserverId,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 withREGION_UNAVAILABLE(depending on what regions the local heartbeat advertised at that instant), instead of just serving the request locally. Fix: at the top ofroute(...), after normalising the hint, drop it whenhint.equals(localServerId). The redundant<self>:prefix now coalesces to the equivalentregion=<region>shape and takes the normal local path under bothLOCALandAUTOmodes. Foreign pins are unaffected (the user's primary use case for the hint). Covered by three newNetworkRouterTestcases (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
/rtparrivals 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'sJoinTriggerSource.handleRedeemto fire, the redeem succeeded anddispatchRtpinvokedRTP.scheduler.runTaskLater(hop, 1L)to hop onto the main thread forBukkit.dispatchCommand(player, "rtp"). On Folia, the barerunTaskLateroverload lands on the Global Region Scheduler thread, butCraftServer.dispatchCommandrunsTickThread.ensureTickThreadagainst the player's owning region and throwsIllegalStateException: Thread failed main thread check: Dispatching command async-- so the/rtpwas thrown away and the player arrived without a teleport. Fix: (a) renamedRTPScheduler.scheduleTeleport(RTPPlayer, RTPRunnable, long)torunTaskForPlayer-- 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 byTeleportPipelineTask,BukkitEffectsHandler,AnvilInputSessionand (now)JoinTriggerSource; (b)JoinTriggerSource.dispatchRtpresolves the arrivingRTPPlayerand routes the dispatch throughRTP.scheduler.runTaskForPlayer(...), which on Folia hops to the player's entity scheduler (the only thread on whichBukkit.dispatchCommandpasses the tick-thread check) and on Bukkit / Paper / Spigot / Fabric falls through to the existing main-thread path. The legacyrunTaskLaterfallback is preserved for the player-not-resolvable race. Bukkit/Paper/Spigot/Fabric unaffected behaviourally (single-tick-thread platforms). -
Network mode: cross-server
/rtparrivals now teleport for pinned routes too (REQ-RTP-S-004 / REQ-RTP-NET-015). The Velocity proxy adapter'sonServerPreConnecthandler was eagerly callingtransport.release(token.tokenId(), ReleaseReason.CONSUMED)immediately after rewriting the connect target.release.luatransitions the row toCONSUMEDANDDELs thertp:net:tokactive:<playerId>active-index key, so by the time the player joined the destination backend ~1-2s later,JoinTriggerSource.handleLookupcalledfindReservationand got an empty result ("no reservation found"); the redeem path that pins the coord, evicts the local waitlist guard, and dispatches the local/rtptherefore 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 eagerrelease(CONSUMED)fromRtpVelocityPlugin.onServerPreConnect. The proxy now only uses the reservation to rewrite the connect target; the token remainsCLAIMEDso the destination backend'sJoinTriggerSourcecanredeem(...)on join (which transitionsCLAIMED -> CONSUMEDand clears the active index inredeem.luaatomically with pinning the coord and dispatching/rtp). The unknown-target-serverrelease(BACKEND_REJECTED)path is preserved unchanged. The 30s reservation TTL plus the existingReservationTokenReaperhandle 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 SPIRtpRequesthad noserverHintfield at all, so the upstream router's hard-pin (whether typed by the player or synthesised by lobbypickMostKept) was smuggled byTransportRequestTriggerSourceinto the unrelatedoriginServerIdslot, which theBackendSelectornever 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)RtpRequestgains a dedicatedserverHintfield with a 6-arg back-compat constructor that preserves every existing caller; (b)TransportRequestTriggerSource.dispatchEnveloperoutesenv.serverHint()into the new slot and leavesoriginServerIdempty (the trigger source is not the request's origin); (c)DefaultRtpDispatcher.claimAfterSelectnow branches onrequest.serverHint()first: present=>selector.choose(request, snapshot, Optional.of(hint))and hard-fail withNO_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.parkOnWaitlistwritesrequest.serverHint()into theWaitEnvelopeandNetworkWaitlistDrainer.redispatchreads it back. Covered by two new cases inDefaultRtpDispatcherTest(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
JoinTriggerSourcesuccessfully redeemed a cross-serverReservationToken, the destination backend re-dispatched/rtpfor the arriving player; that/rtpwas then short-circuited byNetworkWaitlistGuardbecause the lobby-seededNetworkStatusCacherow 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.onRedeemednow evicts the arriving player's row fromNetworkStatusCachevia the newNetworkStatusCache.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, whichpollOncewill observe on its own schedule. Wired via a newJoinTriggerSource(transport, serverId, statusCache)constructor overload plus a late-bindsetStatusCache(...)setter so the trigger source can be constructed before the status cache in the bootstrap sequence. Covered by two new cases inNetworkStatusCacheTest(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/rtpfinally lands the player on the named backend, which is the one whoseJoinTriggerSourcewill see the matchingReservationToken- 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 returnedCollections.emptySet()in all three Fabric player variants and the console sender becausefabric-permissions-apiis a check-only SPI; on-event grants and effect dispatch consequently fell through toconfig.ymldefaults on Fabric. New enumerator threads node-set discovery through LP-Fabric when present (with op closed-namespace fallback) sortp.onevent.*and effect tokens resolve identically to Bukkit. Covered byFabricEffectivePermissionsTest(22). - YAML database race in
YamlFileDatabase.setValue(String, Map). Override no longer delegates tosuper.setValue(which enqueues async viagetTable().thenAcceptand races the re-nested enqueue, flattening top-level YAML keys); thelocalTablessnapshot is now updated inline with the re-nested shape. Flake inYamlFileDatabaseTest.setValue_flatRow_isNestedUnderPrimaryKeyresolved;:rtp-core:test2460/2460 PASSED. - Lobby no-arg
/rtpnow 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-argBackendHeartbeatctor that defaultskeptCount=0andregionKeptCounts=Map.of(), so every peer scored 0 and the deterministic lex tie-breaker won; (b) peers not accepting requests were not excluded frompickMostKept; (c) local recordDispatch decrement was not applied. Covered by newpickMostKept_*regressions and 18/18 inLobbyModeTest. safety.yml::unsafeBlocksand probed block names accept either bare orminecraft:-namespaced form, with modded namespaces preserved verbatim. Direct analog of the biome fix below for future-proofing against an eventual Keyed-registryMaterialrelease (S-001 territory: missing block matches would drop the unsafe-block guard). NewMaterialNames#matches(Set<String>, String)helper, sibling ofBiomeNames;PregenTaskandScanTaskprobe-block checks route through it. Covered byMaterialNamesTest(22).- Biome arguments and
safety.yml::biomesaccept either bare orminecraft:-namespaced form across Bukkit-family platforms. Follow-up to the:->=command syntax migration. NewBiomeNames#matcheshelper treats the uppercase vanillaMINECRAFT:prefix as optional while preserving modded namespaces (IRIS:,TERRALITH:);RTPCmdno longer strips namespaces on input. All fourScanTaskand bothPregenTaskbiome-filter sites route through the helper. Covered byBiomeNamesTest(22);ScanTaskProcessingTestandParameterParsingTestconfirm no regression.
Security¶
- HMAC envelope on the Redis transport wire (rtp-proxy-ADR-010 Phase 2e-Redis A3). Every published
BackendHeartbeat/ProxyHeartbeatrow carries anhmac=<hex>field signed viaHmacVerifierover the canonical line-oriented payload; verification on read drops tampered or legacy-NULL rows with REQ-RTP-S-004 WARNING.NetworkBindings.openconstructsHmacVerifier.loadFromEnvand degrades to InMemory on loader failure.rtp test network allaudits the integration end-to-end. - HMAC envelope parity on the SQL transport (rtp-proxy-ADR-010).
SqlNetworkStateBindingsigns every published heartbeat +ReservationTokenrow over the same canonical field-order strings as Redis, verifies on every read site with constant-time compare, and drops tampered/legacy-NULLhmacrows.SqlNetworkStateSchemaadds an idempotentALTER TABLE ... ADD COLUMN IF NOT EXISTS hmac VARCHAR(128)migration that tolerates the MySQL/MariaDB dialect quirk (portable form first, bareADD COLUMNretry, 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&6arrow becomes#9D7CD8; admin-panel row arrows shift from cyan&bto muted teal#5FB3B3(destructiveReload/Full diagnosticsrows 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&efor neutral&7;delayMessageadopts#9D7CD8lavender andteleportMessageadopts#5FB3B3teal for occasional accent./rtp infovalue placeholders switch from bright white&fto muted blue#7E9CC8.PLAYER_COOLDOWNPAPI status moves from&eto#9D7CD8. Propagated through every shipped locale via the TSV pipeline (newscripts/recolor-locales.ps1pluslocale-files-from-csv.ps1). Verified byLocaleParityTest(154/154) and fullgradlew build. -
Ellipseshape parameterised over a dedicatedEllipseMemoryShapeParamsenum, with elliptical inner exclusion and Rectangle-style rotation (amends ADR-034). The second semi-axisradius2previously lived on the sharedGenericMemoryShapeParamsenum, which forced every single-radius shape (Circle,Square, and their_Normalvariants) to carry a meaninglessradius2default solely to satisfyShape's "every enum constant present" constructor invariant.radius2is now hosted on the newEllipseMemoryShapeParamsenum alongside the other ellipse knobs (mode,radius,centerRadius,centerRadius2,rotation,centerX,centerZ,weight,uniquePlacements,expand), andEllipseextendsMemoryShape<EllipseMemoryShapeParams>directly rather thanCircle.Ellipseadditionally gains two new knobs:centerRadius2(the second axis of an elliptical — rather than circular — inner exclusion) androtation(degrees, mirroringRectangleParams.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;containsenforces the true rotated elliptical inner / outer shells. Internal refactor —rtp-apiis unaffected. -
rtp.personalqueuepermission semantics decomposed (ADR-043). Retires the bundledRegionQueueManager.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 L2unkeptLocations), andrequestTeleport(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 calledRegion.queue(UUID)orRegionQueueManager.queue(UUID): pickopenPersonalQueue(bucket opt-in) orrequestTeleport(waitlist enrol) per the new semantics. Covered byReqRtpAdr043PersonalQueueSeparationTest(6 cases).
Added¶
MemoryShape.chunkToLocations(int cx, int cz)andMemoryShape.addBadChunk(long location)-- new bounded inverse ofxzToLocationat chunk granularity, plus a sibling ofaddBadLocationthat marks every 1D index decoding to the same chunk. The Archimedean-spiral parameterisation in chunk units (ADR-001) guarantees <= 2 preimages per chunk, sochunkToLocationsis O(1) (angular walk plus a shape-specific radial probe via a newneighbourRingOffsethook onCircle/Square).addBadChunkis intended for chunk-attributable rejections (biome, claim, border, anvil-prefilter, ocean), is idempotent, falls back toaddBadLocationon outside-shape slop, and returns the count newly marked (0-2). All production rejection call sites inScanTask,PregenTask,Polygon,ChunkyRTPShape, and theuniqueplacements-knobrand()paths ofCircle/Square/Rectangle/Circle_Normal/Square_Normalare migrated toaddBadChunk; 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 survivingaddBadLocationcalls in production are the internal fallbacks insideaddBadChunkitself and the public API method body. Covered byMemoryShapeChunkToLocationsTest(10 cases).backlogRefillThresholdperformance knob -- new double-valued setting inperformance.yml(range[0.0, 1.0], default0.5) that adds hysteresis to the L3 backlog cache (ADR-028) refill loop. Previously everyRegion.execute()pulse re-toppedbacklogLocationsto capacity, scattering shape picks across many.mcafiles and weakening the cross-region amortization of the world-shared anvil bin index. With the knob, the refill latch deactivates atcapacityand re-arms only when size falls belowfloor(threshold * capacity), concentrating shape picks (and their anvil verifications) into bursts that share.mcafiles for better CPU and memory locality. Edge cases:0.0is opt-out (never re-arms),1.0reproduces the prior always-refill behaviour; out-of-range clamped, parser failures fall back to default. Covered byBacklogRefillThresholdTest(7 cases).- In-house YAML substrate (
io.github.dailystruggle.rtp.common.configuration.yaml) now replacessimpleyamlacrossrtp-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-renamesave(), and a simpleyaml-shaped parity surface (typed gettersgetString/getInt/getLong/getDouble/getBoolean/getList/getStringList, predicatesisSet/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), plusRtpYamlOptionsexposingcopyDefaults(boolean)andindent(int)and aRtpYamlConfig.addDefault(String, Object)set-if-absent helper). Allrtp-coreproduction 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; theme.carleslc.Simple-YAMLGradle dependency andrtp-pluginshadow-relocate rules will be dropped in the next beta cycle oncertp-coreships green end-to-end across all platforms. Covered byRtpYamlSimpleYamlParityTest(21 cases) on top of the substrate's read/write/comment suites (211 + 177 + 177 cases), with the fullrtp-coretest pass continuing to validate every migrated call site. - Menu framework foundations in
rtp-api(ADR-035 amended 2026-05-15; ADR-044). Newio.github.dailystruggle.rtp.api.menupackage introduces the platform-neutral menu surface that the upcoming/rtp menuconsumer (with/rtp configas the first concrete browser) and downstream renderers will build against: immutableMenuModel/MenuPage/MenuLine/MenuFragmentrecords, a sealedMenuAction(RunRtpCommandwith defensive-copyargs,ChangePage,SuggestInput,OpenExternalUrl), theMenuRendererinterface, theMenuTokenRegistrysingle-use / TTL / per-player-bounded contract, and the ADR-044 reflector seamsMenuConsumerProfile(with a trivialdefaultProfile()factory) +YamlCommentLookup(with anEMPTYconstant for non-YAML-backed consumers). No platform imports, no Adventure, nortp-coredependency — addons can build menus against this surface today. ConcreteLocalMenuTokenRegistry,MenuRedeemSubcommand,CommandTreeMenuBuilder, and the Paper/FoliaBookMenuRenderership in subsequent commits within the same beta.3 cycle. Covered byMenuModelSurfaceTest(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 menuwith no arguments, the root page is now a hand-picked landing screen rather than the flat alphabetised reflection of the/rtpcommand tree. The newFrontPageBuilder(inrtp-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 byrtp.menu.adminthat collapses to a singleAdmin panelentry row leading into a dedicated curated admin-panel page (PROPOSAL-admin-panel.md v2; see below). Descending into any subcommand falls through to the existingCommandTreeMenuBuilderreflector. ConfigurableMessagesKeysentries (menuFrontPageSection*,menuFrontPageRow*,menuFrontPageHover*) keep every label and hover under operator control per REQ-RTP-F-013. Covered byFrontPageBuilderTest(7 cases). - Curated admin panel for
/rtp menu(PROPOSAL-admin-panel.md v2). The singleAdmin panelentry row on the front page (admin viewers only, gated byrtp.menu.admin) opens a dedicated curatedMenuModelbuilt by the newAdminPanelBuilder(rtp-core). The panel organises operator tooling into four self-hiding sections: Configuration (Config editor->OpenConfigSelector, gated onrtp.config.view), Diagnostics (Server info,Full diagnostics,Memory tracker snapshotwhen/rtp test memoryis registered,Scan controlgated onrtp.scan), Lifecycle (Reloadgated onrtp.reload, with a warning hover), and Browse (Browse all commands-> reflected-tree fallback). ABackrow at the bottom emits the newMenuAction.OpenFrontPagetoken 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 sealedMenuActionvariants (OpenAdminPanel,OpenFrontPage) extend the menu surface to 13 permitted types; both round-trip through/rtp menu token:<t>per ADR-035. NewMenuRedeemSubcommand.MenuCuratedPageBuilderSAM hosts the two dispatch arms (dispatchOpenAdminPanelgated onrtp.menu.admin,dispatchOpenFrontPageungated). Seventeen newMessagesKeysentries (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 byAdminPanelBuilderTest(12 cases) and two newBookMenuRendererTestround-trips. maps-apidocumentation 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 requirementsREQ-RTP-MAP-001..005inREQUIREMENTS.mdsection 1.7 (require-by-contractMapBindingextending REQ-RTP-S-006; non-blockingChartRendererextending REQ-RTP-F-008 / REQ-RTP-S-005;MemoryTrackerlifecycle release on cancel / disconnect / disable; Lite-onlyNoopMapBinding; in-house Mermaid subset with no external runtime, scripting engine, or third-party graph-layout dependency), matching rows inTRACEABILITY.md, and the in-module bootstrap ADRmaps-api-ADR-001locking package layout (mapsapiroot +model/render/render.mermaid/noop/bukkit/fabricsubpackages, withbukkitthe only subpackage allowed to importorg.bukkit.*), the logical-palette-now, concrete-table-Stage-2 palette policy (32-symbolPaletteIndexcontract, vanilla map-palette bytes carried per-binding), and the assembly-level Lite trim posture (shadow-jar exclusions inrtp-plugin, audited by an extendedliteJarStructureCheckclause in Stage 2). Stage-1 SPI skeleton now also landed (2026-05-16, same beta.3 cycle): newmaps-apiGradle module (settings.gradle,maps-api/build.gradlejava-library+ ArchUnit) with the platform-neutral SPI surface —MapCanvas(128x128, logical-palette bytes),MapHandle/MapAllocationRequest(record +Lockingenum) /Cancellation,MapBinding(allocate / renderEphemeral / bindLive), sealedChartModel(Heatmap2D/CategoryDistribution/TimeSeries/RegionCoverage/MermaidChart, all defensively copied),ChartRendererand the first concreteHeatmapRenderer, theNoopMapBinding(REQ-RTP-MAP-001 / REQ-RTP-MAP-004 default — every entry-point throwsIllegalStateExceptionwith the documented prefix), fourpackage-info.javacross-references — plus theInMemoryMapBindingtest double and four traceable tests:ReqRtpMap001RequireByContractTest,ReqRtpMap002NoChunkIoTest(ArchUnit + manual blocking-future-call scan overmapsapi.render),HeatmapRendererTest,MapsApiSurfaceTest. 25/25 maps-api tests green;.\gradlew buildgreen 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
Regionpreviously trusted that Y and only re-tested the single feet-block viaRTPChunk.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'sVerticalAdjustor.adjust(chunk)against the loaded chunk and uses its returnedRTPCoordsas 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 inPregenTask/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 byRegionPipelineTest. -
effects-apiFolia dispatch hardening forPotionEffectandFireworkEffect(closes the "firework never spawns /IllegalStateException: Asynchronous effect add" symptom on Folia). Both effects now resolve thePlugincaller throughEffectsAPI.getInstance()with a graceful S-006 fallback: ifinit(Plugin)hasn't run,callerdegrades tonulland the dispatcher seam (PotionEffect.entityDispatcher/FireworkEffect.regionDispatcher) is still consulted so the FoliaEntityScheduler/RegionSchedulerpath is taken when available. Removed aneffects-api-layer call toBukkit.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 viasafeRun(apply).PotionEffect.applyOnEntityThreadadditionally swallowsaddPotionEffectfailures (IllegalStateException: Asynchronous effect add, invalid effect data) viasafeRunso a misrouted effect never propagates back through the teleport caller. Regression guarded byFoliaDispatchTest(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 theplaceholderslist-head value as the result of repeatedlocale-files-to-csv/locale-files-from-csvpasses 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 regeneratedlang/<loc>/messages.ymlfiles 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.ymlcomment 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 forde,fr,es,it,nl,pt,ja,ko,zh,ru,pl(new), andcat(Internet Cat dialect: see Domain Analogies & Aliases in.junie/AGENTS.mdclarifying thatlang/cat/is the cat-themed locale, not Catalan; Catalan would be ISOca). -
Four new locale trees shipped since beta.2: Italian (
it), Polish (pl), Portuguese (pt), and Russian (ru). Newlang/<loc>/trees perTRANSLATION_GUIDE.mdsection 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 passLocaleParityTest. 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_commentcells inscripts/out/locale-<loc>.tsvidentified 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 infomessage 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 sharesbase_keywithdatabase.password) was correctly preserved by disambiguating via canonical baseline parent path. ~351 TSV rows patched, regenerated YAMLs verified viaLocaleParityTestand fullgradlew 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) andscripts/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: stringis 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 everylang/<loc>/*.ymlpreviously 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 todocs/adr/anddocs/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 everylang/<loc>/mirror is also stripped. Cross-references remain intact indocs/, 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.ymltranslated. 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'spreceding_comment. Doc-tag values after the@are preserved unchanged; the prose lines that precede them were translated for thetall_flowersblock (11 locales patched; Italian already had the translation). 30-36 doc-tag-only patches per locale; regenerated YAMLs verified viaLocaleParityTestand fullgradlew build. -
Chinese (
zh) locale: 49 untranslated key names inmessages.lang.ymltranslated. Newinfo*health/metrics block keys (infoQueueDepth,infoPendingTeleports,infoAvgPipelineMs,infoHeap,infoHealthPipelineHeader,infoTps,infoMSPTLive,infoSoftCap,infoDatabaseLatencyMs, the sixinfoThreshold*Green/Yellowrows,infoThresholdNetworkAgeYellow,infoFoliaRegionsHeader,infoFoliaRegion) plus the entiremenu*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 optionalRegionQueueManager.backlogLocations(BacklogLocationBuffer) sits upstream of L2unkeptLocations: spiral picks land as unverified entries (no chunk I/O, no DB row), eachRegion.execute()pulse anvil-verifies one.mcabin (32×32 chunks; cross-RTP-region amortized via a world-shared weak-ref bin index), and head-contiguousVALIDATEDentries promote into L2. Head-blocking onUNVERIFIEDpreserves spiral order;INVALIDATEDheads drop without stalling. New per-regionbacklogCacheCapknob inregions/<region>.yml(default1000on the main jar; lite omits the key so the in-code fallback resolves to0⇒ L3 disabled). Not persisted to the DB by design — restart re-selects fresh entries. Covered byBacklogLocationBufferTestandWorldBacklogBinIndexTest(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/rtpteleporting 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/rtproot, anvil pre-filter parity, multi-version support (1.20.x / 1.21.x including 1.21.11), and permissions viafabric-permissions-apiwith anops.jsonfallback. Covered byrtp-fabric-ADR-001throughrtp-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:TestCmdlift, event-bus wiring, online-player tab-complete. GlideEffectineffects-api(effects-api-ADR-001) — foldsaddons/RTP_Glideintoeffects-apias a first-class effect with a shutdown-time safe-landing fallback and a newPlayerLandEvent.Reason.FixedAdjustorvertical adjustor (vert: FIXED). Third engine alongsideLINEAR/JUMP; places the player at a single configured Y in mid-air for skyblock-style worlds (requires the platform tool). Covered byFixedAdjustorTest.pregeneratedPreferenceperformance knob — new double-valued setting inperformance.yml(range[0.0, 1.0], default0.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 insidePregenTask.runAttempt()(upstream of the anvil pre-filter), and the L3 backlog refill insideRegion.processBacklog()Step 1 (right afterShape.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'spregeneratedPreferencewould later drop. Both paths shareRegion.pregenPrefRejects()and use the existing non-blockingRTPWorld.isChunkGeneratedprobe (S-005 safe -- no chunk loads triggered). Dropped candidates on the L1 spiral path are attributed to the newLocationGenerator.FailTypes.ungeneratedbucket for/rtp infoandrtp test fullauditing; L3 refill rejections are silent (the candidate never entered any cache). Default0.0preserves prior behavior;1.0strictly avoids ungenerated chunks. The L3 refill loop additionally caps consecutive rejections per pulse atmax(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 existingmaxAttemptsceiling (each rejected pick consumes one attempt). Covered byPregeneratedPreferenceTest(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 fieldswhen:(pipeline stage), optionalpermission:/players:/inherit:, and a requiredeffects:token list (same grammar asrtp.effect.<stage>.*permission suffixes). Loaded via the existingMultiConfigParser<EffectsGroupKeys>plumbing — no bespoke loader class — so per-localeeffects.lang.ymlfield-key remap and/rtp reloadhot-swap come for free. The plugin now registers aneffects/parser inConfigs.reloadConfigs();BukkitEffectsHandlerandFabricEffectsHandlerre-resolve groups per teleport via a newEffectsResolver.resolveUnioned(...)helper that unions permission-derived nodes with config-driven tokens before feedingEffectFactory.buildEffects(prefix, ...). Fabric admins now have a usable effect-configuration surface withoutfabric-permissions-api; Bukkit admins gain a permission-less complement to the existingrtp.effect.*permission tree. /rtp infohealth block + bStats RTP cost-metric charts (METRICS_PLAN.md, Phase M1+M2 vertical slice)./rtp infonow appends four operator-facing live-state lines sourced from a singleRTP.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 anymessages.ymlline and via PlaceholderAPI. The bStats integration (full id 30865, lite id 12277) registers eleven new charts viaRTPCostMetricsCharts: 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-platformMetricsBindingfor 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 reflectiveBukkit.getServer().getTPS()lookup as an interim probe and reportunknownwhen 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_bucketsAdvancedPie chart described above; the ring is never reset and ages out via overwrite. Privacy-safe (bucketised only).
Changed¶
effects-apiplatform-split for Fabric readiness (effects-api-ADR-003; effects-api-ADR-004 amends ADR-002).EffectandEffectFactorymoved toeffectsapi.commonand decoupled fromorg.bukkit.*(nowimplements Runnable, Cloneable); Bukkit-side concretes, listeners, commands, and events relocated undereffectsapi.bukkit.*; token coercion routed through a per-platformValueCoercerSPI; Bukkit registration and scheduling extracted toBukkitEffectsInitializer. Addon migration: import prefix changes fromio.github.dailystruggle.effectsapi.{LocalEffects,BukkitListeners,commands,events}.*toio.github.dailystruggle.effectsapi.bukkit.*; subclasses that called inheritedBukkitRunnablemethods (runTaskTimer,cancel,isCancelled, etc.) directly will no longer compile; subclasses that only overriderun()are unaffected.- Bundled
docs/tree inside release jars trimmed to admin- and addon-author-facing material.rtp-plugin'scopyDocsno longer ships internal dev docs. MULTI_SERVER_PLAN.mdupdated 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-proxyproxyIdfield in thenetwork.ymlstraw-man (analogous to per-backendserverId); 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 to2× Velocity (behind L4) + 2× Paper.MULTI_SERVER_PLAN.mddocuments DragonflyDB (and other RESP-compatible servers) as supported Redis-transport drop-ins (docs only; D-005 gated, no code changes). Theredistransport type covers Redis, DragonflyDB, and KeyDB through the sameRedisNetworkStateBinding— only the connection URL differs, notransport.flavourknob, no per-flavour code branches. Redis remains the reference implementation; Phase 2 acceptance gains a parallel container exercising the cross-server/rtpround-trip against DragonflyDB on the unmodified binding, with any observed RESP divergence (Lua/EVAL, Streams consumer groups, persistence semantics) recorded inLESSONS_LEARNED.mdrather 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, thertp-fabric-commonclasses, andfabric.mod.json, so Fabric Loader can discover RTP from the unclassifiedRTP-<version>.jarinstead of requiringRTP-Pro. JDBC drivers (H2 / SQLite / MySQL / PostgreSQL) remain stripped from lite, so Fabric+lite operators land onFabricDatabaseHandler.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.setupfromRTPBukkitLitePlugin.onEnable(deferred tick+1) and declaressoftdepend: [ GriefDefender, GriefPrevention, Towny, HuskTowns, Factions, Lands, RedProtect, WorldGuard ]in itsplugin.yml;integrations.ymlis bundled in the lite jar soClaimIntegrations#buildParsercan 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/**andlanguage.yml, and the full (un-trimmed)messages.ymlfromrtp-plugin/src/main/resources. No explicit bootstrap call is required:LanguageBootstrap.resolve(pluginDirectory)is invoked unconditionally fromConfigs#reloadConfigs(), andLanguageCmd(the/rtp langsubcommand) lives inrtp-coreand is registered via the shared command tree, so it is available on lite identically to Pro. Lite-irrelevantmessages.ymlkeys (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. TheliteJarStructureCheckaudit no longer forbidslang/**orlanguage.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/andeffects-api/effects-api-fabric-unobf/— host Mojmap-unobfuscated mirrors of the NM-typed surfaces (FabricRTPWorld,FabricRTPChunk,FabricRTPPlayer,FabricEffectRuntime, the fourLocalEffects,FabricValueCoercer,FabricRegistryCompat,FabricLegacyText,FabricPaletteNormalizer,FabricAnvilColumnProbeAdapter) so the deobfuscated MC 26.x runtime family links cleanly without intermediaryclass_NNNNaliases. Intermediary-bearing 1.20.x / 1.21.x runtimes continue to use the original obf-carrier modules unchanged; runtime selection is dispatched via the newFabricVersionAdapter#installEffectsWiring(Object)SPI (defaultfalse, overridden only byV26_1_R1FabricVersionAdapterto install the unobf path). Non-API:rtp-fabric-common[-unobf]andeffectsapi.fabric*are internal carriers, so addon authors require no migration. Carrier-disjointness is regression-guarded byEffectsApiFabricCarriersDisjointTestandRtpFabricCarriersDisjointTest. - 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.ymloverlays. 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 dynamicworlds/,regions/,effects/directories.
Fixed¶
safety.ymland biome-filter edits now invalidate the persisted shape cache (closes the[3.0.0-beta.1]Known Issuesentry; was a tracked follow-up indocs/dev/POTENTIAL_BUGS.md).RegionCacheKey.canonicalize(...)now folds a deterministic snapshot of the validity-affecting subset ofsafety.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 cachedMemoryShapedata. Cosmetic and runtime-only keys (invulnerabilityTime,staleChunkRetryLimit,version) are explicitly excluded.RegionCacheKey.SCHEMA_VERSIONis bumped from1to2, so every existing<region>_<seed>_<12hex>.bin/.scanfile and everyrtp_cached_locationsrow 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 futureSafetyKeysconstant is left unclassified. Covered byRegionCacheKeyTest(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-effectKEY_ORDERwith a non-rewinding cursor, assigning each token to the first remaining key whose default type accepts it. Removes aprintStackTracepath. Covered byEffectsApiAdaptiveReadingOrderTest. - Per-permission effects did not fire under RTP-lite. Lite bootstrap now schedules
BukkitEffectsHandler.setupEffectsat tick+1 and re-introduceseffectParsing: truein the liteperformance.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
/rtpend-to-end). Several call sites inrtp-fabric-commonpreviously 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 tomethod_xxxxx. Replaced each with a typedFabricVersionAdapterSPI method (extractPlayerFromConnection,getPlayerUUID,resolveSenderUuid,dispatchConsoleCommand,installEffectsWiring) dispatched viaFabricVersionAdapterRegistry.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,/rtpsender resolution inFabricBrigadierSourceBridge, and post-teleportconsoleCommandsdispatch. Zero reflection on the relevant hot paths. Regression guarded byFabricEventBridgeAdapterDispatchTest. -
Default permissions on Fabric now mirror
plugin.ymlwhen no permissions mod is installed.FabricRTPPlayer.hasPermission(and the unobf / 26.1 mirrors) previously fell through to theops.jsonop-check whenever nofabric-permissions-apiimplementer (LuckPerms-Fabric, Cyan, Ledger, ...) was registered. Baseline player nodes such asrtp.seeandrtp.use(declareddefault: trueinplugin.yml) were therefore silently denied to non-ops, breaking/rtpon a vanilla-permissions Fabric install; conversely,rtp.onevent.*(declareddefault: false) would have been granted to ops if anything queried them, contradicting the descriptor. Added a sharedFabricDefaultPermissionstable (mirrored asFabricDefaultPermissionsUnobfon the unobf classpath) that resolves each node toTRUE/FALSE/OPstraight fromplugin.ymldefaults. Resolution order is now perms-api -> default table ->ops.json:TRUEgrants to everyone,FALSEdenies even ops,OPfalls through to the existingops.jsonscan, and unknown nodes (addon-defined, wildcard-expandedrtp.worlds.<world>/rtp.regions.<region>, etc.) default toOPto match their parent wildcard's convention.
Known Issues¶
Fabric-only:
- Permission-based effects on Fabric require a
fabric-permissions-apiimplementation. 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), butrtp.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 toeffects/<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 tagsduring 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
CompletableFuturedependent 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 atBORDERlevel (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 keepcacheCap/keptCachemodest until they upgrade.
All platforms:
- Translations do not apply to dynamic config directories (
worlds/,regions/,effects/). Localizedlang/<locale>/*.lang.ymloverlays 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-apichanges. 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-apitypes 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./rtpdoes 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.
RTPEconomyAPI - present but marked experimental; signature may change before3.0.0final./rtp configcommand - present but experimental; subcommand surface, argument grammar, and write-back semantics may change before3.0.0final. 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.0final onward, the Lite jar will be published asRTP(the free tier) a few hours-to-days after the correspondingRTP-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.0final. Stick with H2 or SQLite for production. safety.ymland 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 tounsafeBlocks,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.mdSlice 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
.binfiles and existingrtp_cached_locationsrows from any pre-3.0.0-beta.1build 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.ymlnow shipsplatformRadius: -1(disabled). SetplatformRadius: 0or 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 for3.0.0final. Active frontier - seeMULTI_PLATFORM_PLAN.md. Remaining: scheduled-task processor parity (Step E3), permissions viafabric-permissions-api(Step F), full Brigadier command tree (Step G2), stabilization smoke test (Step H). - Fold
safety.ymlvalidity fields and biome filters into the region cache hash (POTENTIAL_BUGS.mdfollow-up to ADR-022). - Multi-server / proxy mode (Velocity, BungeeCord) - phased rollout per
MULTI_SERVER_PLAN.md. D-005 gated; admin docs stub atdocs/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 correspondingRTP-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
RTPEconomyAPI. - Stabilize
/rtp configcommand - 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¶
- Versioned platform submodules - compile-time NMS separation via a
commonmodule plus per-version submodules for Spigot, Paper, and Folia (ADR-010). - Stable public
rtp-api- broadened addon surface; no more reflection into internals (ADR-011). - 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.
- 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).
- Lock-free location buffer & state-based tasks -
LockFreeLocationBufferdecouples pre-generation from teleport dispatch; explicit task states enable pause/resume/cancel and concurrent region fills. ChunkReservationlifecycle -AutoCloseableabstraction eliminates the 2.x ticket leak (ADR-012).- Multi-platform expansion -
rtp-fabricadapter (in progress) andcommands-api/effects-apiconsolidated as sub-modules. - 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). TheRTP_ClaimPluginIntegrationsaddon is removed; the eight checkers (Factions, GriefDefender, GriefPrevention, HuskTowns, Lands, RedProtect, TownyAdvanced, WorldGuard) now register at plugin startup inClaimIntegrations.integrations.ymlships with the plugin jar; behaviour for REQ-RTP-S-003 is unchanged (verifiers still live behindGlobalRegionVerifiers). A newaddons/RTP_ExampleAddonreplaces the claim addon as the canonical "how to write an addon" template. /rtp fill->/rtp scan(permissionrtp.fill->rtp.scan) for clarity.CachedLocationis 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
MemoryTrackerwithWeakReferencedeallocation; write-through caching consolidated. - Independent region queues now fill concurrently without a shared global-queue lock.
sendMessagecall-site tracking now uses stack trace source for diagnostics.- Allocation reduced on hot paths (records, primitives, vectors removed);
MemoryShapepending-write storage switched from maps to sets. Regiondecomposed for cohesion.- ScanTask diagnostics (BIOME_LOOKUP_PERF_PLAN.md PR-16). Extended the
[DEBUG_LOG] ScanTask concurrency ...line withavgColdMissMs(averageFiles.readAllByteswall time per cache miss) andgcDeltaMs(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
peakInFlightdropped 50 ? ~25 over three minutes), pointing at driver-side pipeline bubbles. Removed theinFlightGate.acquire(MAX_PENDING_CHUNKS)drain between region-file bins inScanTask.run: PR-15 coalescing already makes cross-bin cache interference cheap, so the barrier was costing saturation without earning correctness. AddedfullLoads=N fullLoadAvgMs=X.XXto the gauge log (AtomicLong counters wrapped aroundrunFullLoadPath's result future) so operators can confirm whether stage-2 cost (loaded-chunk safety scan) grows with scan progress; iffullLoadAvgMsclimbs whileavgColdMissMsstays 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.maxBiomeChecksin favor of a singlemaxAttemptsknob; added probe-first fast paths inPregenTaskandScanTaskbacked byRTPWorld.probeChunkColumn(overridden on Bukkit / Paper / Folia to read the chunk's center column directly from the persistedr.X.Z.mcaviaAnvilReader.readColumnProbe); wrapped the result throughAnvilColumnProbeAdapter(appliesPaletteNormalizer::reconcile); gated onSafetyKeys.anvilPrefilterEnabled+isChunkLoaded. NewLocationGenerator.FailTypes.prefilterBiome / prefilterBlock / prefilterRangebuckets attribute the rejections.VerticalAdjustorgainedrequiresSkyLight(). ScanTask reframes the probe as a load-replacement: on cache-miss the probe is authoritative (skipgetOrLoadChunk); on cache-hit the safety radius upgrades tomax(configured, 2)for free. Blocking I/O moved to a dedicatedAnvilIoPool(max(8, 2 * CPU)daemon threads) to avoidForkJoinPool.commonPoolstarvation. AddedAnvilRegionByteCache(LRU of raw.mcabytes, mtime-invalidated) to eliminate redundant per-chunkFiles.readAllBytesof the same ~4 MB region file; PR-11 added hit/miss/stale diagnostics surfaced inScanTask'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. Measuredfull/proberatio 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
MemoryShapedata andScanTaskprogress files were keyed only by<regionName>_<worldSeed>, so edits tocenterX/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 stableSHA-256of(SCHEMA_VERSION, seed, shape FQCN + sorted shape data, vert FQCN + sorted vert data). The same hash, truncated to 64 bits, is written into the existingrtp_cached_locations.seed BIGINTcolumn, so cachedRTPLocationrows are invalidated under the same predicate without a database schema migration.Region.setSettings(...)deletes orphaned.bin/.scanfiles when the hash changes;ScanTask.delete(regionName)now sweeps every<regionName>_*.scanfile. Region cache hydration moved off the calling thread ontoRTP.scheduler.runTaskAsynchronouslyso DB I/O can no longer stall plugin init. Pre-release: legacy.binfiles and existing rows are abandoned (no migration).safety.ymlvalidity fields and biome filters are not yet folded into the hash; tracked as a follow-up entry indocs/dev/POTENTIAL_BUGS.md.
Fixed¶
- ScanTask probe-first fast path rejected passable non-air blocks (BIOME_LOOKUP_PERF_PLAN.md follow-up). After the
isAirAtreconciliation fix unblocked the anvil fast path, live scans still showed a residualadjustNulltail (~1300-1600 per gauge tick) whenever the center-column body/head cells held configured-passable blocks like tall grass, flowers, or snow layer.JumpAdjustor.acceptProbeYrequired 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'sairBlockslist documents exactly those passable materials but was wired only into the config enum - no code consumed it. Fix:JumpAdjustornow cachesSafetyKeys.airBlocksnext tounsafeBlocks(shared 5-second refresh inrefreshSafetySets) andacceptProbeYaccepts body/head as passable when vanilla air OR present inairBlocks, withunsafeBlockstaking precedence on conflicts. Tag-grammar tokens like#minecraft:flowersare stored verbatim and remain inert until the config reader's tag expansion slice lands (tracked indocs/dev/SAFETY_TAGS_AND_STATES_PLAN.mdSlice 3). Regression guarded byJumpAdjustorProbeTest.airBlocksFromConfig_acceptsTallGrassHeadSpace. - ScanTask probe-first fast path silently vetoed by case-sensitive
isAirAt(BIOME_LOOKUP_PERF_PLAN.md follow-up).AnvilColumnProbeAdapter.blockAtreconciles every palette identifier throughPaletteNormalizer::reconcile, which converts"minecraft:air"toMaterial.AIR.name()="AIR"so that downstreamunsafeBlocks.contains(...)checks (populated asMaterial#name()upper-case tokens likeLAVA) match symmetrically. The defaultChunkColumnProbe.isAirAtthen compared the path segment against lowercase"air"/"cave_air"/"void_air"and returned false for every air block, makingJumpAdjustor.acceptProbeYandLinearAdjustor.acceptYfind no acceptable Y on any center column. Live runs showedadjustNull == activeChecksevery gauge tick withfullLoads == activeChecks, negating the anvil pre-filter entirely and leaving scan throughput at the PR-17 baseline. Fix: overrideisAirAtinAnvilColumnProbeAdapterto recognize the reconciledAIR/CAVE_AIR/VOID_AIRforms in addition to the rawminecraft:*path segments. Regression guarded byAnvilColumnProbeAdapterIsAirAtTest. - Emergency landing platform spam on kept-queue / DB-rehydrated teleports (Folia in particular).
TeleportPipelineTask.runTeleportpreviously gatedRTPWorld.platform(...)onreservation == 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.executesynthesizes aChunkReservationfor kept-queue pairs so REQ-RTP-S-002 stays intact. Defaultsafety.ymlnow shipsplatformRadius: -1(disabled); setplatformRadius: 0or higher to restore legacy behaviour. - Chunk leak in region queue replenishment and in early
ChunkReservationintegration. - Memory leak in active task tracking.
- Immediate-teleport timing regression and duplicate task execution on queue drain.
MemoryShapecaching 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.hasPermcalledsender.hasPermission(...)directly for each candidate child node. On Paper with LuckPerms (and any permission manager that defers to op state for unset nodes),hasPermissionshort-circuits totruefor ops regardless of the registereddefault: falsewe declared inplugin.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 correspondingrtp.onevent.*node. Fix: rewroteParsePermissions.hasPermto 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 byParsePermissions.getIntfor numeric permission tiers. This bypasses the permission manager's op-default short-circuit entirely, restoring the documented opt-indefault: falsebehaviour. The earlier removal of thepermissionPrefix + "*"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) callsgetChunkAt(probe entry) and, on UNKNOWN,getChunkAtAsync(live entry) for the same logical attempt. Every adapter incrementedRTPWorld.totalChunkLoadsfromgetChunkAt, and on Spigot/FabricgetChunkAtAsyncdelegated back throughgetChunkAt, 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#loadLiveChunkandFoliaRTPWorld#getChunkAtAsync, and inside theMinecraftServer#submitbody ofFabricRTPWorld#getChunkAt. Probe-only paths (anvil cache hits) and kept-cache replays no longer contribute. Operators upgrading will seeinfoTotalLoadsdrop to roughly half its previous value - this is the corrected reading, not a regression. TheleakRateplaceholder is unaffected (still divided bylifetimeTicketsIssued). Javadoc onRTPWorld.totalChunkLoadsupdated 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.