rtp-fabric-ADR-015 - Maps API parity on Fabric (vanilla filled-map path)¶
- Status: Accepted (2026-05-31)
- Scope:
rtp-fabric(rtp-fabric-common, the per-version carriers, andrtp-plugin/.../fabric/RTPFabricMod) - Supersedes: none. Implements the Fabric clause of maps-api-ADR-003 (maps-api module) and ADR-047 (declarative chart composition).
- Related: maps-api-ADR-003, ADR-047, maps-api-ADR-001, rtp-fabric-ADR-007 (Mojmap-name decoupling: the version-volatile call sites cross the seam NM-free), rtp-fabric-ADR-001 (per-version carrier layout). Requirements: REQ-RTP-MAP-001/002/003.
Context¶
maps-api (MapBinding, MapBindingLifecycle, MapHandle, MapCanvas, MapAllocationRequest, the ChartModel hierarchy, and the renderers) is platform-neutral and ships BukkitMapBinding, FoliaMapBinding, and NoopMapBinding. There was no FabricMapBinding and no MapDispatch.setMapBinding(...) call in RTPFabricMod, so every /rtp visualization chart on a Fabric backend bottomed out on the NoopMapBinding sentinel and logged ... skipped: no concrete MapBinding installed (NoopMapBinding active) (the symptom reported on Fabric 26.2-pre2). This ADR records the renderer-path decision required by MULTI_PLATFORM_PLAN Step K sub-item 1.
Decision¶
Ship the vanilla filled-map path (option A): charts render onto a real MapItemSavedData and a FILLED_MAP item referencing it is delivered to the viewer. The chat-rendered ASCII fallback (option B) was rejected by the maintainer as too low-fidelity for heatmap / region-shape charts.
Because every map touch is net.minecraft.* and the names drift across the 1.20 -> 26.x window (and are intermediary-leaked on rtp-fabric-common, deobf on the 26.x carriers), the work is split across the rtp-fabric-ADR-007 NM-free seam:
rtp-fabric-commonhosts the platform-neutral, NM-free pieces:FabricMapCanvas- writes the maps-api logical palette (0..31) into a row-major 128x128 ARGBint[]buffer (mirrors theBukkitMapCanvasramp;setPixelRgbis a full-colour bypass).drawTextis a no-op (no server-side font raster reachable here).FabricMapBinding implements MapBinding, MapBindingLifecycle- owns the per-chart ARGB buffers and the live-refresh loop; resolves the viewer to aFabricRTPPlayerthroughRTP.serverAccessor(no NM in its constant pool, no ad-hocMinecraftServerlookup) and delegates all NM work through that player's map sink.allocatereturns a syntheticMapHandle.mapId(the realMapIdis carrier-owned, keyed bychartId);renderEphemeral/bindLiveonly paint the buffer;deliverTotriggers the player dispatch withdeliverItem=true; the live loop re-renders and re-dispatches at ~1 Hz withdeliverItem=false.onPlayerQuit/onDisablecancel live tasks and release carrier state (REQ-RTP-MAP-003).- The maps path flows player-first. Server/level state is reached through the viewer's
RTPPlayer, not a standaloneMinecraftServer:FabricRTPPlayergainsrenderMapChart(chartKey, int[] argb, locked, deliverItem)(mirroring itsopenBookMenusink) which resolves the active carrier, hops to the server tick thread viaRTP.scheduler, and delegates to the carrier seam with its liveServerPlayerhandle;releaseMapChart(chartKey)forwards cache cleanup. The rawServerPlayernever leavesFabricRTPPlayer. FabricVersionAdaptergains three NM-free default-method seams:renderMapChart(Object serverPlayer, chartKey, int[] argb, locked, deliverItem)(the viewer is supplied as the raw NMServerPlayertheFabricRTPPlayerowns),releaseMapChart(chartKey)(pure cache cleanup, needs no server or player), andsupportsMapCharts()(defaultfalse).- The 26.2_R1 carrier (
V26_2_R1FabricVersionAdapter) implements them: it hops to the server tick thread, allocates/reuses aMapId+MapItemSavedDataperchartKey, matches each opaque ARGB pixel to the nearest vanillaMapColorpacked byte (viaMapColor.byId+getColorFromPackedId-MATERIAL_COLORS/calculateRGBColorare private on this runtime), pushes a full-canvasClientboundMapItemDataPacketbuilt from a 128x128MapPatch(vanilla'ssetColorsDirty/getUpdatePacketare private), and ondeliverItemadds aFILLED_MAPcarrying theMAP_IDdata component to the viewer's inventory (drop-at-feet fallback when full).
RTPFabricMod.onInitialize installs FabricMapBinding via MapDispatch.setMapBinding(...) only when FabricVersionAdapterRegistry.peek().supportsMapCharts() is true, and wires MapDispatch.firePlayerQuit onto FabricPlayerLifecycleHook.onPlayerQuit. Carriers that do not yet implement the seam (1.20.x, 1.21.x, 26.1_R1 at time of writing) return false, so MapDispatch stays on NoopMapBinding and the configurable mapBindingMissing message still surfaces - no half-working binding is installed.
Consequences¶
- Fabric 26.2.x reaches feature parity with Bukkit for
/rtpchart rendering (heatmap, region-shape, sparkline live charts). - The other carriers (1.20.x, 1.21.x, 26.1_R1) are a mechanical follow-up: each overrides the three seam methods against its own mapping. The 26.2 implementation is the reference port.
- S-005 / REQ-RTP-MAP-002: no chunk I/O on any path;
FabricMapBindingonly mutates in-memory buffers and the carrier touches only map/inventory/connection state on the server thread. - No
net.minecraft.*reference leaks intoRTPFabricMod(verified byReqRtpFabricEntrypointNoNetworkProtocolTest) or intoFabricMapBinding/FabricMapCanvas.
Follow-ups¶
- Port
renderMapChart/releaseMapChart/supportsMapChartsto the 1.20.x, 1.21.x, and 26.1_R1 carriers. - Optional: pre-raster chart labels into the ARGB buffer so
drawTextis no longer a no-op on Fabric. - Add a Fabric-flavoured S-005 sibling of
ReqRtpMap002NoChunkIoTestonce a headless map fixture exists.