rtp-fabric-ADR-002 — Fabric Platform Is In Scope (Multi-Version Single-JAR Multi-Loader Packaging)¶
Renumber history: originally project-wide ADR-022; renumbered to ADR-031 on 2026-05-05 to resolve a collision with ADR-022 (Region Shape Cache Key); restructured to subproject-scoped rtp-fabric-ADR-002 the same day when subproject ADRs were given per-directory numbering. Pre-rename commits and external docs may still say "ADR-022" or "ADR-031".
Status: Accepted Date: 2026-04-30 Last revised: 2026-05-01 (rewritten — single Fabric module replaced by per-MC-version submodules to mirror the Bukkit-family layout)
Context¶
RTP has historically targeted Bukkit-derived server software only (Spigot, Paper, Folia), as recorded in docs/dev/REQUIREMENTS.md section 0 and REQ-RTP-SYS-002. Fabric work has nonetheless been carried in docs/dev/MULTI_PLATFORM_PLAN.md as an "active frontier".
The first iteration of this ADR (2026-04-30) committed to a single version-agnostic Fabric adapter, rtp-fabric/rtp-fabric-common, pinned to one Minecraft version. A 2026-05-01 deployment to a 26.2 (year-based versioning, see Version Naming below) Fabric server surfaced the structural flaw:
java.lang.NoClassDefFoundError: net/minecraft/class_2561
at io.github.dailystruggle.rtp.fabric.RTPFabricMod.onInitialize
Root cause: the adapter was compiled against MC 1.21.1 Mojang mappings. Fabric Loader's intermediary→runtime remap is per-MC-version: a JAR remapped against the 1.21.1 intermediary table is not loadable on a 26.2 runtime, because the intermediary class name space (class_2561 etc.) is not stable across MC releases. This is structurally identical to the Bukkit-family NMS-version problem — and was already solved there by per-version adapter submodules (rtp-bukkit/rtp-bukkit-v1_20_R1, rtp-paper/rtp-paper-v1_21_R1, rtp-folia/rtp-folia-v26_1_R1, etc.).
Four facts inform the rewritten decision:
- Abstraction sufficiency. The April 2026 gap analysis (recorded in
MULTI_PLATFORM_PLAN.mdWhat Does NOT Need to Change) concluded thatRTPServerAccessor,RTPWorld,RTPPlayer,RTPScheduler, and thertp-coreDatabaseHandlerare sufficient for Fabric. The gap analysis stands; no newrtp-apiinterfaces are required. - Per-MC-version mapping divergence is unavoidable on Fabric. Loom statically remaps Mojang→intermediary at build time, in a single namespace per JAR. There is no Fabric-Loader hook for runtime mapping selection equivalent to Bukkit's reflective NMS access. Therefore each MC version that RTP supports needs its own Loom-built artifact in its own package.
- Bukkit-family precedent is reusable.
RTPBukkitPluginalready selects anRTPServerAccessorimplementation at startup by classpath probe (Class.forName("io.github.dailystruggle.rtp.bukkitplatform.v1_21_R1.…")etc.). The same dispatch pattern is portable to Fabric:RTPFabricModqueriesSharedConstants.getCurrentVersion()(or equivalent), thenClass.forNames the matchingio.github.dailystruggle.rtp.fabric_<ver>.FabricServerAccessor<ver>. Non-matching version classes never resolve, so their MC-mapping references never fail to link. - Distribution constraint unchanged. RTP ships through a single resource page on BuiltByBit, which awards one primary download per version entry. The multi-loader single-JAR mandate from the original ADR is preserved — extended with the multi-version dispatch layer on the Fabric side.
Decision¶
1. Scope¶
Fabric is a first-class, in-scope target platform for RTP, alongside Spigot, Paper, and Folia. Forge, NeoForge, and other non-Fabric mod loaders remain out of scope and are deferred to Phase 4 of the multi-platform plan.
This decision supersedes the relevant clause of docs/dev/REQUIREMENTS.md section 0 Out of Scope (the Non-Bukkit platforms bullet, only insofar as it names Fabric) and broadens REQ-RTP-SYS-002 to include Fabric.
2. Module Layout — Per-MC-Version Submodules¶
The rtp-fabric/ module group shall mirror the Bukkit-family per-version adapter pattern:
rtp-fabric/
rtp-fabric-common/ # version-agnostic abstract surface; no MC symbols beyond stable Fabric-Loader API
rtp-fabric-1_20/ # MC 1.20.x
rtp-fabric-1_21/ # MC 1.21
rtp-fabric-1_21_1/ # MC 1.21.1
rtp-fabric-1_21_2/ # MC 1.21.2
rtp-fabric-1_21_4/ # MC 1.21.4
rtp-fabric-1_21_5/ # MC 1.21.5
rtp-fabric-1_21_8/ # MC 1.21.8
rtp-fabric-1_21_11/ # MC 1.21.11
rtp-fabric-26_1/ # MC 26.1 (year-based; "Mounts of Mayhem" line, succeeds 1.21.11)
rtp-fabric-26_2/ # MC 26.2 (current target as of 2026-05)
Each per-version module:
- Applies
fabric-loomwith the Loom version compatible with that MC line. (Loom version selection is delegated to the build script per module; the project does not pin a single Loom across all modules.) - Pins its own
minecraftVersion,loaderVersion,fabricApiVersion, and usesloom.officialMojangMappings(). - Depends on
rtp-fabric/rtp-fabric-common,rtp-api,rtp-core, andcommands-api. - Owns the version-specific concrete classes:
FabricServerAccessor<ver>,FabricRTPWorld<ver>,FabricRTPPlayer<ver>,FabricEventBridge<ver>,RTPCmdFabric<ver>. Each lives in a distinct top-level packageio.github.dailystruggle.rtp.fabric_<ver>.*so that intermediary class names from different MC versions never collide in the shadow JAR. - Produces its own Loom
remapJaroutput containing intermediary-mapped bytecode for that MC version.
rtp-fabric/rtp-fabric-common retains:
- Abstract base classes (
AbstractFabricServerAccessor,AbstractFabricEventBridge,AbstractFabricRTPWorld,AbstractFabricRTPPlayer) that declare the per-version contract using onlyrtp-apitypes and stable Fabric-Loader API. FabricScheduler— uses onlyMinecraftServer.execute(Runnable)(a long-stable Fabric API surface) and is therefore version-agnostic.FabricDatabaseHandler— uses onlyrtp-coresymbols and stable Fabric API.- Version-detection utilities consumed by the dispatcher.
3. Packaging — Single JAR, Multi-Loader, Multi-Version Dispatch¶
RTP shall ship as a single JAR that loads on both Bukkit-family servers and Fabric servers, and on every supported Fabric MC version.
rtp-pluginremains the multi-loader bootstrap module with two entry-point classes in disjoint packages:io.github.dailystruggle.rtp.bukkit.RTPBukkitPlugin—JavaPlugin, declared inplugin.yml, dispatches per-NMS-version Bukkit-family adapter as today.io.github.dailystruggle.rtp.fabric.RTPFabricMod—ModInitializer, declared infabric.mod.json, dispatches per-MC-version Fabric adapter.RTPFabricModshall reference nonet.minecraft.*symbols. It uses onlynet.fabricmc.*(loader API) andrtp-api/rtp-coretypes. Any concreteComponent,ServerLevel,ServerPlayer, etc. usage lives in the per-version submodules. This is the rule that lets Loom inrtp-plugincompile against any chosen MC version without that choice leaking into runtime selection.- The shadow JAR ingests each per-version module's
remapJaroutput (intermediary bytecode), not its rawcompileJavaoutput. This is the build-discipline change in section 4. - Both
plugin.ymlandfabric.mod.jsonship at the JAR root. Each loader ignores the metadata file it does not recognize.
4. Build Discipline¶
- Loom application.
fabric-loomshall be applied to everyrtp-fabric/rtp-fabric-<ver>submodule, tortp-fabric/rtp-fabric-common-unobf(the deobf-26.x unobfuscated common carrier; seertp-fabric-ADR-009), tortp-plugin, toeffects-api(pereffects-api-ADR-003, to support the in-moduleeffectsapi/fabricsubpackage), and toeffects-api/effects-api-fabric-unobf(the deobf-26.x unobfuscated effects-api carrier; seeeffects-api-ADR-006). It shall not be applied at the root, tortp-core, tortp-api, tocommands-api, or to any Bukkit-family adapter. - Per-version Loom plugin. Each per-version module pins its own Loom plugin version compatible with the MC line it targets. The version-agnostic
rtp-fabric-commondoes not apply Loom — it compiles as a plain Java module againstrtp-api/rtp-coreand the stable Fabric-Loader API surface only. - Shadow ingestion.
rtp-plugin/build.gradle'sshadowJartask shall include theremapJaroutput of each per-version module. Including raw compile output would re-mix Mojang-mapped class files across versions and produce a JAR Loader cannot load. - Mappings.
loom.officialMojangMappings()for every per-version module. Yarn is reserved for re-evaluation if the community requests it. - Dual-runtime end-to-end smoke test. A CI matrix shall load the produced JAR on a Paper test server and on at least one Fabric test server per supported MC line, asserting that
/rtpexecutes end-to-end. The matrix is the only automated guard against per-version remap regression. The gate is anchored at Phase 2 Step H (stabilization).
5. Architectural Invariants Preserved¶
The following hard lines remain unchanged and shall be enforced by existing ArchUnit guards:
rtp-core,rtp-api,commands-api,effects-apishall contain zero platform imports.rtp-bukkit,rtp-paper,rtp-foliashall contain Bukkit-family imports only.rtp-fabric/rtp-fabric-commonshall not importnet.minecraft.*(only stable Fabric-Loader API andrtp-api/rtp-core).rtp-fabric/rtp-fabric-<ver>modules shall contain Fabric imports and MC-mapping imports for that version only; they shall not importorg.bukkit.*and shall not cross-reference each other.- The
RTPBukkitPluginpackage and theRTPFabricModpackage withinrtp-pluginshall not import each other and shall not transitively reach the other platform's classes.RTPFabricModadditionally shall not import anynet.minecraft.*symbol. - The per-version Fabric package roots
io.github.dailystruggle.rtp.fabric_<ver>shall be mutually disjoint.
6. Version Naming¶
The submodule suffix <ver> is the underscored MC version (1_21_5, 26_2, ...). Mojang's year-based versioning (introduced for the 2026 release line — 26.1 succeeds 1.21.11, 26.2 succeeds 26.1; see https://www.minecraft.net/en-us/article/minecraft-new-version-numbering-system) maps directly: 26.2 → 26_2. The dispatcher in RTPFabricMod translates SharedConstants.getCurrentVersion().getName() (e.g. "26.2") to the underscored form ("26_2") and then to the FQN io.github.dailystruggle.rtp.fabric_26_2.FabricServerAccessor26_2.
7. Implementation Order¶
The phased implementation order, acceptance gates, and risk mitigations are recorded in docs/dev/MULTI_PLATFORM_PLAN.md (Phase 0 through Phase 3). The 2026-05-01 restructure introduces an explicit skeleton-first sub-phase: scaffolds for all supported MC versions land before any version is fully implemented, so that :rtp-plugin:remapJar and :rtp-plugin:shadowJar succeed for the union of all version modules from day one. Implementation depth proceeds version-by-version, prioritized by user demand (currently 26_2).
8. Ownership¶
A named maintainer shall own the Fabric adapter end-to-end (build, mappings, CI matrix, S-00x proofs, ongoing maintenance). The matrix grows with each new MC release; ownership is the gating factor on adding a new version to the supported set, not technical effort.
Alternatives Considered¶
| Alternative | Why Rejected |
|---|---|
| Single Fabric module pinned to one MC version (the original 2026-04-30 ADR-022 section 2 design) | Confirmed unworkable: Loom intermediary→runtime mapping is per-MC, and Fabric Loader provides no runtime fallback equivalent to Bukkit's reflective NMS. Resulted in NoClassDefFoundError: net.minecraft.class_2561 on a 26.2 server when the JAR was built against 1.21.1. |
| Ship one Fabric JAR per MC version (10 separate downloads) | Same BuiltByBit / release-surface problem the original ADR section 2 rejected. The per-version submodule structure delivers identical isolation guarantees inside a single JAR via package-disjoint dispatch. |
| Use Yarn or hashed mappings instead of Mojmap to share more bytecode across versions | Hashed mappings are not stable across MC versions either (the underlying obfuscation map changes); Yarn introduces a separate maintenance dependency without removing the per-version remap requirement. |
| Adopt Architectury for cross-loader sharing | Architectury produces N binaries from one source tree, not one binary covering N runtimes. Solves a different problem; reconsider at Phase 4 if Forge/NeoForge re-enter scope. |
Move version dispatch into rtp-fabric-common rather than rtp-plugin/RTPFabricMod |
Common would then have to know every version's FQN, defeating its version-agnostic role. Dispatch belongs at the entry point — same place Bukkit-family does it. |
Consequences¶
- Positive:
- Resolves the runtime
NoClassDefFoundErrorcrash by structurally aligning with how Fabric Loader handles per-MC mappings. - Each Fabric MC version is independently buildable, testable, and deployable. A regression in one version's mapping does not block the others.
- Mirrors the Bukkit-family layout developers already understand.
- Adding a new MC version is a mechanical scaffold step (copy a sibling, change the version pin, implement the abstract methods), not an architectural change.
- Negative / Trade-offs:
- Build complexity grows: 10 Loom configurations, each with its own mappings download. CI cache pressure goes up correspondingly.
- Shadow-jar plumbing must consume Loom
remapJaroutputs rather than raw compile outputs — a non-default Gradle pattern that needs documentation inMULTI_PLATFORM_PLAN.md. - The single-JAR size grows with each supported version. Per the precedent in the original ADR (Bukkit-family version adapters), the inert-bytecode cost is acceptable for the distribution-surface gain.
- Per-version Loom plugin versions can drift; the build script must document the compatibility matrix.
- Guardrails preserved:
- Do not backport Fabric-specific patterns into
rtp-coreorrtp-api. - Do not introduce new
rtp-apiinterfaces speculatively for Fabric. - The two entry-point packages in
rtp-pluginshall remain disjoint;RTPFabricModshall remain free ofnet.minecraft.*imports; per-version Fabric packages shall remain disjoint.
References¶
docs/dev/REQUIREMENTS.md section 0(scope),REQ-RTP-SYS-002,REQ-RTP-NF-003(entry-point isolation, applied per-entry-point under this ADR)docs/dev/MULTI_PLATFORM_PLAN.md— phased plan, abstraction gap summary, acceptance gates, multi-version skeleton-first sub-phase- ADR-005 — PaperLib removal (preserves the "no async-chunk shim" stance Fabric must respect)
- ADR-010 — Versioned platform adapter submodules (this ADR brings Fabric into the same pattern)
- commands-api-ADR-001 (formerly ADR-014) — Brigadier bridge via
commands-api(each per-version Fabric adapter consumes the bridge, does not duplicate it) - ADR-018 —
AGENTS.mdpublic-release structure (compatible with multi-version single-JAR multi-loader) - ADR-021 — Legacy Minecraft and Java support out of scope (untouched by this ADR; Fabric ≠ legacy)
- REQ-RTP-S-005 — No synchronous chunk I/O on the main thread (Step A acceptance gate)
- REQ-RTP-S-006 — No undefined behaviour on early API access (Step B acceptance gate)
- External precedent: Geyser, LuckPerms, ViaVersion, Floodgate — single-JAR multi-loader bootstrap in production. Per-MC-version Bukkit-family adapters in this project (
rtp-bukkit/rtp-bukkit-v*,rtp-paper/rtp-paper-v*,rtp-folia/rtp-folia-v*) — internal precedent for the per-version submodule structure now extended to Fabric. - Mojang version-numbering change (2026): https://www.minecraft.net/en-us/article/minecraft-new-version-numbering-system
- 2026-05-01 deployment crash log demonstrating the single-version structural flaw:
NoClassDefFoundError: net.minecraft.class_2561atRTPFabricMod.onInitialize:52on a26.2Fabric server when JAR was built against1.21.1.