rtp-fabric-ADR-012 - Menu renderer parity on Fabric (chat-first, book follow-up)¶
- Status: Accepted (2026-05-24)
- Scope:
rtp-fabric(rtp-fabric-common, the per-version carriers, andrtp-plugin/.../fabric/) - Supersedes: none. Implements the Fabric clause of leafrtp-ADR-021 and the menu-reflector contract of menu-api-ADR-001.
- Related: leafrtp-ADR-021 (Interactive Menus via Written Book - the project-wide menu ADR; pins Fabric's primary renderer to chat in the 2026-05-15 amendment), menu-api-ADR-001 (command-tree menu reflector /
MenuModelcontract), leafrtp-ADR-031 (menuPermissionProbeonRTPServerAccessor; subsumes section 2's per-call-site permission-probe wiring), ADR-050 (deletes the menu token registry; menu clicks now carry literal/rtp menu ...commands), rtp-fabric-ADR-009 (obf/unobf carrier split; does not apply to the chat renderer in the shipped shape, see Amendment), rtp-fabric-ADR-011 (menuPermissionProbeconsumes the resolver from this ADR).
Amendment (2026-05-31, book renderer un-defer)¶
Section 4 below deferred a Fabric written-book renderer. Per the maintainer's 2026-05-24 decision to un-defer it (MULTI_PLATFORM_PLAN Step I Session 3), the book renderer now ships for the 1.21+ obf carriers and section 4 no longer holds for those runtimes. Shipped shape:
- A platform-neutral
io.github.dailystruggle.rtp.fabric.menu.FabricBookMenuRenderer(inrtp-fabric-common, nonet.minecraft.*binding) translates theMenuModelinto a fully-formattedFabricBookSpec(placeholders + colour codes resolved throughRTPServerAccessor.format; click commands via the sharedMenuActionToCommand) and dispatches it through a newFabricVersionAdapter.openBookMenu(Object serverPlayer, FabricBookSpec)SPI (defaultfalse). - The per-carrier overrides (
v1_21_R1,v1_21_R5,v1_21_R11) build aWRITTEN_BOOKItemStackwith aWrittenBookContentdata component (oneComponentper page; fragments built by the existingFabricLegacyText.parseInteractive(..., ClickKind.RUN)), send a transientClientboundContainerSetSlotPacketto the held hotbar slot, sendClientboundOpenBookPacket(MAIN_HAND), then revert the slot. The server-side inventory is never mutated (this is the answer to section 4 blocker #2's "transient book without inventory placement" concern: a client-onlySetSlotround-trip rather than a real inventory write). - 1.20.x (no component
WrittenBookContent) keeps the SPI default and stays onChatMenuRenderer; the renderer also falls back to chat when the viewer is offline or the book dispatch throws (S-004 log-and-degrade). The chat renderer therefore remains the default for headless / accessibility / unsupported-carrier cases, as section 4 promised. - Section 4 blocker #1 (per-version
WrittenBookContentschema split) is handled by the existing per-version carrier pattern; each adapter compiles against its own MC mapping. Blocker #3 (parchment colour contrast) now does apply to the Fabric book renderer exactly as on Paper —.junie/AGENTS.md"Book Menu Color Contrast" — and is satisfied for free because theMenuModelproducers' colour choices are shared with Paper. - New test
FabricBookMenuRendererTest(rtp-fabric-common) covers the pureMenuModel→FabricBookSpecconversion and the chat-fallback dispatch (no live server required).
Update (2026-05-31, 26.x book support): the deobf 26.x carriers (v26_1_R1, v26_2_R1) now also ship openBookMenu. Because the deobf MC line compiles against Mojang names that equal its runtime mappings, the per-carrier override is a typed port of the 1.21.11 implementation (same WrittenBookContent data component + transient ClientboundContainerSetSlotPacket -> ClientboundOpenBookPacket(MAIN_HAND) -> slot revert), with per-fragment hover/click delegated to the version-local V26_*FabricLegacyText.parseInteractive(...) (reflective HoverEvent/ClickEvent record-carrier probing). One 26.x ctor difference was handled: WrittenBookContent's title is Filterable<String> (not Filterable<Component> as on 1.21.x). Only 1.20.x now stays on the chat renderer by default.
Amendment (2026-05-24, on acceptance)¶
The original draft was written before leafrtp-ADR-031 (menu builders behind server accessor) and ADR-050 (stateless concrete-command menus) landed. The shipped implementation therefore differs from sections 1 and 2 below in three editorial ways. The chat-first decision (section 1), the chat-prompt callback substitute (section 3), and the book-renderer deferral (section 4) stand as written.
- No
MenuRendererRegistry; no carrier split for the chat renderer. ADR-050 deleted the token system entirely, so the renderer no longer needs to mint per-fragment tokens. The shipped renderer is a singleio.github.dailystruggle.rtp.common.commands.menu.ChatMenuRendererclass inrtp-corewhose only platform coupling is one newRTPServerAccessor.sendMessageWithRunCommand(...)SPI method. Because that SPI dispatches inrtp-apitypes, the renderer itself has nonet.minecraft.*binding; the carrier split applies only toFabricServerAccessor.sendMessageWithRunCommand(one method, routed through the existingFabricLegacyText.parseInteractive(..., ClickKind)path). TheChatMenuRendererCommon/ChatMenuRendererObf/ChatMenuRendererUnobftriple proposed in section 1 collapses to one class. menuPermissionProbeis supplied byRTPServerAccessor, not constructed inRTPCmdFabricRoot. ADR-048 Phase B addedRTPServerAccessor.menuPermissionProbe(UUID)as a default-method SPI;FabricServerAccessor(lines 1933-2034) overrides it to delegate toFabricEffectivePermissionsResolverper rtp-fabric-ADR-011.RTPCmdFabricRoot's wiring (section 2) is therefore a 5-line block that mirrorsRTPCmdBukkit:215-230and consumes the SPI override; no Fabric-specific permission code is added.- No
LocalMenuTokenRegistryconstruction. ADR-050 removed the registry;MenuPlatformBindings(post-ADR-050) carries only(permissionProbe, MenuRenderer, AnvilInputOpener)andMenuWiringSupport.attachToinstalls all menu leaves with concrete-command click targets.
The shipped artifacts are: rtp-core/.../commands/menu/ChatMenuRenderer.java, rtp-core/.../commands/menu/MenuActionToCommand.java (shared MenuAction -> /rtp menu ... helper, used by both BookMenuRenderer and ChatMenuRenderer), rtp-fabric-common/.../menu/FabricChatPromptCallback.java (chat-prompt substitute per section 3), the sendMessageWithRunCommand SPI addition on RTPServerAccessor + overrides on AbstractServerAccessor (Bukkit), AbstractFoliaServerAccessor (Folia), and FabricServerAccessor (Fabric), and the wiring block in RTPCmdFabricRoot:218-249. Section 4 (book-renderer deferral) is unchanged and remains valid for this phase; the Path B serialization in MULTI_PLATFORM_PLAN.md Step I sequences Session 3 (book renderer for 1.21+ Fabric carriers) after this.
Context¶
The interactive-menu rollout (leafrtp-ADR-021, menu-api-ADR-001) has shipped its platform-agnostic layer in rtp-api (the MenuModel / MenuFragment / MenuAction types and the MenuRendererRegistry SPI) and its concretes in rtp-core (CommandTreeMenuBuilder, LocalMenuTokenRegistry, MenuRedeemSubcommand, FrontPageBuilder, AdminPanelBuilder, and the config-view / param-picker / shape-vert / list-editor builders). Paper has rtp-paper-common/.../menu/BookMenuRenderer.java installed at boot and RTPCmdBukkit wires LocalMenuTokenRegistry + menuPermissionProbe + MenuRedeemSubcommand (lines 213, 239, 246, 259, 303 in the current tree). Paper menus are confirmed working end-to-end as of 2026-05-22 (user-reported, this cycle).
On Fabric none of this is wired. The symptoms today:
/rtp menu(the no-arg curated front page fromFrontPageBuilder/ Stage B),/rtp config <file>(the config-view book pages fromCommandTreeMenuBuilder.buildConfigSelector/buildConfigFile), the param-picker page, the shape/vert two-step picker, the list-editor page, and the staging-cart prompt are all no-ops on Fabric. They build aMenuModeland then have noMenuRendererto dispatch to.RTPCmdFabricRootdoes not construct aLocalMenuTokenRegistry, install amenuPermissionProbe, attachMenuRedeemSubcommand, or register anything againstMenuRendererRegistry. Tokens never get minted, so even therunCommand("/rtp menu:<token>")round-trip is non-functional.AdminPanelBuilderhas no entry point on Fabric (no/rtp adminpanelanalogue).
The 2026-05-15 amendment to ADR-035 explicitly assigns Fabric's primary renderer to a chat (component-tree) renderer and defers a Fabric BookMenuRenderer to a follow-up phase via OpenWrittenBookS2CPacket. That decision was made before Paper menus had been exercised end-to-end and before the Fabric obf/unobf common split (rtp-fabric-ADR-009) was in its current shape. This ADR ratifies the chat-first decision in light of those two things and pins the concrete shape of the implementation (carrier split, action dispatch, permission probe, prompt-anvil substitute).
There is a fourth menu interaction the project-wide ADRs do not specifically address for Fabric: the PromptAnvilInput action used by the param-picker and list-editor to ask the player to "type a value here". On Paper this opens a vanilla anvil GUI with the current value as the input slot's name. Fabric has no equivalent first-class "free-text input" GUI - the closest options are a sign-edit packet (OpenSignEditorS2CPacket, finicky on cross-version), a chat-prompt callback (intercepts the next chat message), or a book input page. The two Bukkit-side anvil dependencies (the AnvilGUI library and the per-version reflection backends) are unsuitable on Fabric for both licensing and binding reasons.
Decision¶
Implement two coordinated changes.
1. Adopt ChatMenuRenderer as the Fabric primary renderer, in the obf/unobf split layout¶
Introduce a ChatMenuRenderer that lives on both sides of the carrier split per rtp-fabric-ADR-009:
- The platform-neutral menu-to-component translation logic (walk
MenuModel.pages(), resolve eachMenuFragmentto a styled run with aClickEvent.runCommand("/rtp menu:<token>")and optionalHoverEvent.showText, glue page navigation onto "[prev] / page N of M / [next]" lines) lives inrtp-fabric-commonunderio.github.dailystruggle.rtp.fabric.menu.ChatMenuRendererCommon. It does not importnet.minecraft.*directly; it emits a small internalComponentSpecvalue type (text + color code + click action + hover text) that the carrier-side renderer consumes. - The obf carrier (
rtp-fabric-common, used by 1.20.x and 1.21.x runtimes) implementsChatMenuRendererObfand bindsComponentSpecto the intermediarynet.minecraft.class_2561/class_2583/class_2558/class_2568types. - The unobf carrier (
rtp-fabric-common-unobf, used by deobf 1.26.x runtimes) implementsChatMenuRendererUnobfand bindsComponentSpecto the deobfnet.minecraft.network.chat.Component/Style/ClickEvent/HoverEventtypes. - Per-version submodules contribute nothing renderer-specific. The carrier split already exists for
FabricEffectsHandler/FabricRTPPlayer; the renderer follows the same pattern and is dispatched throughFabricVersionAdapter. - The renderer is installed at
RTPFabricMod.onInitialize()viaMenuRendererRegistry.register("chat", new ChatMenuRendererCarrier(versionAdapter)). The carrier delegate selects obf-vs-unobf at install time, identically to howFabricEffectsHandleris selected.
Click round-trip uses the existing commands-api Brigadier bridge: a MenuFragment whose action is MenuAction.RunRtpCommand("/rtp <args>") translates to a ClickEvent.runCommand("/rtp menu:<token>") where <token> is minted by LocalMenuTokenRegistry at render time. The token is redeemed by MenuRedeemSubcommand on click, which re-dispatches through the same command tree the player would have typed. No bespoke Fabric click-event handling is added.
2. Wire the menu surface in RTPCmdFabricRoot, mirroring RTPCmdBukkit¶
RTPCmdFabricRoot is modified to:
- Construct a
LocalMenuTokenRegistryinstance (per-server, not per-player) and store it on the root command object. - Install a
menuPermissionProbethat consumes rtp-fabric-ADR-011'sFabricEffectivePermissionsResolverfor visibility filtering (callers see only command tree rows their effective permissions allow). - Attach
MenuRedeemSubcommandto the root tree undermenu, with the token-registry handle bound at construction. - Wire
FrontPageBuilderfor the no-arg/rtpand/rtp menupaths. - Wire
AdminPanelBuilderfor/rtp adminpanel(no existing entry point on Fabric). - Wire
CommandTreeMenuBuilderfor/rtp config <file>, the param-picker, the shape/vert two-step picker, and the list-editor / staging-cart flows. These are reused unchanged fromrtp-core.
The wiring is byte-equivalent in structure to RTPCmdBukkit lines 213, 239, 246, 259, 303; only the renderer registration and the permission probe change shape.
3. Defer PromptAnvilInput to a chat-prompt callback substitute¶
Fabric does not get an anvil-input GUI in this phase. The MenuAction.PromptAnvilInput(label, defaultValue, then) action is translated by ChatMenuRenderer to:
- A line in the rendered chat menu reading
"Type the new value in chat. Default: <defaultValue>. Type cancel to abort."(locale-keyed). - A registration with a new
FabricChatPromptCallbackkeyed by player UUID, with a TTL of 30 seconds, draining the next chat message the player sends. The callback resolves to the samethencontinuation that the Paper anvil GUI hands back. - A reminder line on every page-navigation refresh while the callback is pending, so the player does not lose context if they paginate.
A real OpenSignEditorS2CPacket or OpenWrittenBookS2CPacket input modal is deferred to a follow-up ADR. The chat-prompt substitute is acceptable for the param-picker / list-editor use cases and avoids a binding decision against an inherently flaky packet surface in this cycle.
4. Defer the BookMenuRenderer follow-up¶
A Fabric BookMenuRenderer via OpenWrittenBookS2CPacket remains a tracked follow-up. It is not implemented in this ADR. Three concrete blockers keep it deferred:
WrittenBookContentschema differs materially between 1.20.x (pre-component data) and 1.21.x (component-data); a per-carrier book layer doubles the carrier surface area for a marginal UX win over the chat renderer.Player#openBookhas no 1:1 packet path that opens a book modal without placing an item in the player's inventory. The closest path isOpenWrittenBookS2CPacket, which carries an inventory-slot index; the server-authoritative "transient book" trick used on Paper does not directly translate, and reproducing it requires per-version slot bookkeeping plus a follow-upSetSlotS2CPacketrevert that is fragile across the 1.21 slot rework.- The Book Menu Color Contrast section of
.junie/AGENTS.md(yellow/white wash on parchment) does not apply to the chat renderer (the chat-stream background is configurable / dark by default), so deferring the book renderer is a net UX-quality improvement on Fabric and an operator-config simplification.
When the book renderer ships, this ADR will be amended (not superseded); the chat renderer remains the default for headless / accessibility cases.
Consequences¶
Positive¶
- Closes the Step I gap in MULTI_PLATFORM_PLAN.md with a minimal renderer footprint (no new dependency, no new per-version submodule).
- The chat renderer reuses the existing carrier-split SPI introduced in rtp-fabric-ADR-009; no new architectural shape.
- Permission-filtered visibility on Fabric reuses the resolver from rtp-fabric-ADR-011; no second authorization path.
- The
Bookcolor-contrast constraints in.junie/AGENTS.mdbecome irrelevant on Fabric, freeing the renderer to use the full color palette. - A no-op-on-Fabric framework gains a working renderer without committing to the binding-fragile packet surface required for the book modal.
Negative¶
- The chat renderer is a "menu scrolls with chat" experience by design (per ADR-035), not a modal screen. Long menus paginate but cannot suppress the player's chat stream while open. This is the documented trade-off accepted project-wide in ADR-035.
PromptAnvilInputactions become a "type in chat" callback rather than a modal input. Accessibility is comparable, polish is worse. Tracked for the follow-up book renderer.- Two carrier implementations (obf + unobf) must be kept in sync against
ComponentSpec. The pattern is identical toFabricEffectsHandler/FabricRTPPlayerand the existing tests for those serve as a template.
Limitations¶
- No modal input. Players cannot edit a value in a dedicated input widget on Fabric in this phase. The chat-prompt substitute is the documented workaround.
- No book renderer. A second pass is required for the book modal. Tracked as a Phase 3 follow-up; no ADR slot reserved yet.
- Cross-server menus reuse the live command tree. Per the 2026-05-15 ADR-035 amendment, menu content for cross-server flows is the proxy-routed live tree, not a token-shared menu store. No Fabric-specific change is required for that path.
ChatMenuRenderercannot suppress chat-channel plugins on Fabric. Same constraint as Paper, called out for symmetry; no Fabric chat-channel plugins are catalog-tracked today.
Implementation plan (post-acceptance)¶
The actual implementation is a separate change after this ADR is accepted. Sketch:
- New
rtp-fabric-common/.../menu/ChatMenuRendererCommon.java(platform-neutral translation) andChatMenuRendererObf.java(obf carrier binding). - New
rtp-fabric-common-unobf/.../menu/ChatMenuRendererUnobf.java(deobf carrier binding). - New
rtp-fabric-common/.../menu/FabricChatPromptCallback.java(TTL-bounded per-UUID chat-message callback registry; drained by aServerMessageEvents.CHAT_MESSAGElistener on the unobf carrier, by the intermediary equivalent on the obf carrier). - Modify
RTPFabricMod.onInitialize()to register the chat renderer againstMenuRendererRegistryafter the version adapter selects obf vs unobf. - Modify
RTPCmdFabricRootto constructLocalMenuTokenRegistry, install the permission probe (delegating toFabricEffectivePermissionsResolver), attachMenuRedeemSubcommand, and wireFrontPageBuilder/AdminPanelBuilder/CommandTreeMenuBuilderper the Paper template. - New
FabricChatMenuRendererTestanalogous toBookMenuRendererTest: emits a knownMenuModel, captures the renderedComponentSpectree, asserts shape (page count, click actions resolve to mintable tokens, hover text present, permission-filtered rows omitted when probe returns false). - Renderer integration test parity rows added to TRACEABILITY.md once the test class lands.
- Stale-comment cleanup on
RTPCmdFabricRoot(Step F deferred / always-true predicate notes) folded into the wiring change. - CHANGELOG entry under
[3.0.0-beta.4] - Unreleased.
Alternatives Considered¶
| Alternative | Why rejected |
|---|---|
Implement BookMenuRenderer via OpenWrittenBookS2CPacket first |
Per-version WrittenBookContent schema split + transient-inventory-slot bookkeeping doubles carrier surface area for a renderer that ADR-035 already designates as a follow-up. Chat renderer ships first, book follows. |
Anvil GUI input via AnvilGUI library / per-version reflection |
Library is Bukkit-specific; reflection backends bind against Bukkit NMS types absent on Fabric. Chat-prompt callback is the correct substitute. |
| Sign-edit packet input | OpenSignEditorS2CPacket requires a real sign block in the world or a fake block-update sequence that is fragile across 1.21 block-state rework. Not worth the binding cost in this phase. |
| Inventory-backed menu renderer | Explicitly rejected for the whole project in ADR-035 (InventoryClickEvent desync exploit class, no Fabric analogue, S-005 / MemoryTracker conflicts). |
| Defer the entire menu surface on Fabric until book renderer lands | Leaves /rtp menu, /rtp config, /rtp adminpanel, param-picker, shape/vert picker, list-editor, and staging cart as no-ops indefinitely. Unacceptable for a "first-class platform" classification per rtp-fabric-ADR-002. |
References¶
- ADR-035 - Interactive Menus via Written Book (2026-05-15 amendment pins Fabric to chat renderer first)
- ADR-044 - Command-Tree Menu Reflector
- rtp-fabric-ADR-009 - Obf/unobf common split
- rtp-fabric-ADR-011 - Effective-permission enumeration on Fabric
- MULTI_PLATFORM_PLAN.md Step I
.junie/AGENTS.mdBook Menu Color Contrast