effects-api-ADR-006 — Fabric obf/unobf split: relocate effectsapi/fabric/* to a Mojmap-unobfuscated common layer¶
- Status: Accepted (2026-05-09); section
effects-api/build.gradlechange and section Implementation checklist step 2–4 amended in-place 2026-05-09 to reflect the nested sibling Gradle module mechanism (effects-api/effects-api-fabric-unobf/) instead of a second source set insideeffects-api. See Amendment 2026-05-09 — sibling module, not source set below for rationale. - Supersedes: —
- Superseded by: —
- Related:
effects-api-ADR-003-platform-split-bukkit-fabric.md— established the in-modulecommon/ + bukkit/ + fabric/split. This ADR refines thefabric/half without touchingcommon/orbukkit/.effects-api-ADR-004-value-coercer-spi.md—FabricValueCoerceris one of the leak sites this ADR moves.rtp-fabric-ADR-001-multiversion-submodule-layout.md— multi-MC submodule pattern; this ADR adds an obf/unobf axis orthogonal to the per-MC axis.rtp-fabric-ADR-002-platform-in-scope.md section 4 Build Discipline— the Loom allow-list. This ADR keepseffects-api's existing Loom plugin (granted by ADR-003) but narrows whateffectsapi/fabric/*is responsible for.rtp-fabric-ADR-007-mojmap-name-decoupling.md— rationale for keepingnet.minecraft.*calls behind a thin SPI; this ADR is the concrete consequence on the deobf MC 26.x runtime family.- Companion (mandatory pair):
platforms/rtp-fabric/docs/adr/rtp-fabric-ADR-009-obf-unobf-common-split.md— the corresponding Gradle/module decision inplatforms/rtp-fabric/. Both ADRs must be accepted together. docs/dev/scratch/CHECKLIST-fabric-26-1-2-bringup.mdPhase 5 / Phase 5C — the bring-up work this ADR unblocks..junie/AGENTS.mdArchitecture Boundaries, Pre-Flight Checklist, Propose Before Implementation (Rule D-005).
Context¶
effects-api-ADR-003 introduced an in-module common/ + bukkit/ + fabric/ split and added the fabric-loom plugin to effects-api/build.gradle so the fabric/ subpackage could resolve net.minecraft.* at compile time. The fabric/ subpackage is currently compiled against intermediary mappings (Loom default for the 1.20/1.21 family that rtp-fabric-common targets). Loom rewrites every net.minecraft.* reference in the resulting bytecode to net.minecraft.class_NNNN form so that, at runtime, the Fabric loader's intermediary→named remap can re-link those references against the running MC version's mojmap (or yarn) names.
That contract holds on every MC version whose Fabric loader injects an intermediary→runtime remap step. It does not hold on a deobfuscated runtime (a Fabric server jar that is itself already in mojmap form, e.g. the dev/deobf builds the rtp team is testing for MC 26.1.2). On a deobf runtime, class_NNNN constant-pool entries point at classes that simply do not exist; the JVM throws NoClassDefFoundError at first link.
The rtp-fabric-v26_1_R1 submodule already documents and works around this by configuring Loom 1.15 in unobfuscated mode (rtp-fabric-ADR-007), so its bytecode references mojmap names directly and links cleanly on a deobf 26.x runtime. But effectsapi/fabric/* is compiled by the effects-api module under intermediary Loom and is on the classpath of every Fabric runtime, including deobf 26.x. The 26.1.2 bring-up checklist (Phase 5, item 22) confirms the linkage hazard:
FabricEffectRuntime.bindServer(server)—class_3222(ServerPlayer),class_2596(Packet),class_1291(MobEffect),class_2400(ParticleOptions).FabricValueCoercerregistry walk —class_7923(BuiltInRegistries).FabricEffectsInitializer.registerAll()instantiates the four concrete effect classes; each ofFabricSoundEffect,FabricParticleEffect,FabricTitleEffect,FabricPotionEffectindependently leaks its own NM imports (Holder,BuiltInRegistries,SoundEvent,SoundSource,ServerLevel,ParticleOptions,ParticleType,ClientboundSetTitleTextPacket,ClientboundSetSubtitleTextPacket,ClientboundSetTitlesAnimationPacket, …).
Net effect on deobf MC 26.1.2 today: RTPFabricMod.onInitialize swallows the link error during SERVER_STARTED → FabricEffectsHandler.setupEffects(server) and /rtp continues to work, but every rtp.effect.* lifecycle hook silently no-ops, and the post-teleport title/actionbar splash never reaches the client.
What we considered first, and why it was discarded¶
The Phase 5 checklist's original framing of item 22 was "mirror FabricEffectRuntime + FabricEffectsInitializer typed bodies into rtp-fabric-v26_1_R1/". Investigation under that item established that the leak surface covers the entire effectsapi/fabric/ tree (~12 files, ~1100–1500 LOC), because every concrete effect class is independently NM-typed and FabricEffectsInitializer.registerAll() instantiates them all. A v26-only mirror would duplicate ~95% byte-for-byte against effectsapi/fabric/ and be deleted wholesale once a structural fix landed.
MC 26.2 is expected within ~24 h of this ADR's drafting. Any per-version mirror would have to be re-mirrored for 26.2 (and 26.3, and onward) until a structural fix arrives, paying the duplicate cost N times. The structural fix — split the fabric platform layer of effects-api between obf and unobf consumers — is therefore strictly cheaper from N=2 onward, and the unobf carrier can be reused by the corresponding rtp-fabric module split (rtp-fabric-ADR-009).
Constraint inherited from ADR-003¶
"try not to create more root level directories, we can do this within effects-api like we did with commands-api"
This ADR honours that constraint: the split is internal to the effects-api/ subtree and adds no new root-level Gradle modules. Per the 2026-05-09 amendment below, the unobf carrier lives in a nested sibling Gradle module effects-api/effects-api-fabric-unobf/ — exactly mirroring the platforms/rtp-fabric/rtp-fabric-common-unobf/ precedent established by rtp-fabric-ADR-009. No new top-level root directory is introduced; from the repo-root perspective the only change is one new nested module under the existing effects-api/ directory.
Decision¶
Split effectsapi/fabric/* along the obf/unobf axis by relocating its current contents to a new sibling subpackage compiled under unobfuscated Loom, and replacing the existing intermediary-Loom subpackage with a thin obf-runtime adapter that delegates to it through the existing EffectRuntime SPI from ADR-003.
Target package shape¶
Per the 2026-05-09 amendment, the unobf carrier lives in a nested sibling Gradle module rather than a sibling source set. The package layout is otherwise unchanged from the original decision:
effects-api/ (existing module — KEPT, intermediary-Loom)
build.gradle (UNCHANGED w.r.t. Loom config; only adds a
runtime-only `compileOnly project(':effects-api:effects-api-fabric-unobf')`
edge IF effects-api itself ever needs to name the unobf carrier — it does not at landing.)
src/main/java/io/github/dailystruggle/effectsapi/
common/ ← UNCHANGED — platform-neutral SPI + base types (ADR-003)
bukkit/ ← UNCHANGED (ADR-003)
fabric/ ← THINNED — obf-runtime adapter only
FabricEffectRuntime.java (kept; intermediary-Loom-compiled; the on-classpath
surface for 1.20 / 1.21.x runtimes that DO have an
intermediary→named remap step. Implementation
becomes a thin `EffectRuntime` adapter that calls
the same NM types it does today, but its
constant-pool entries are intermediary class_NNNN
refs that the Fabric loader rewrites at runtime.)
// (initializer + value coercer + concrete effects move to the unobf sibling module below)
effects-api-fabric-unobf/ ← NEW — nested sibling Gradle module, unobfuscated 1.15 Loom
build.gradle (mirrors rtp-fabric-v26_1_R1 / rtp-fabric-common-unobf:
`id 'net.fabricmc.fabric-loom'`, MC 26.1.2, no `mappings`
line, Java 25 toolchain. See section build wiring below.)
src/main/java/io/github/dailystruggle/effectsapi/fabric_unobf/
FabricEffectRuntimeUnobf.java (mirror of fabric/FabricEffectRuntime — same source
body, compiled under unobfuscated Loom so the NM
constant-pool refs survive on deobf 26.x)
FabricEffectsInitializer.java (moved from effects-api/.../fabric/)
FabricValueCoercer.java (moved from effects-api/.../fabric/)
FabricRegistryCompat.java (moved from effects-api/.../fabric/)
LocalEffects/FabricSoundEffect.java (moved from effects-api/.../fabric/)
LocalEffects/FabricParticleEffect.java (moved from effects-api/.../fabric/)
LocalEffects/FabricTitleEffect.java (moved from effects-api/.../fabric/)
LocalEffects/FabricPotionEffect.java (moved from effects-api/.../fabric/)
LocalEffects/enums/FabricSoundKeys.java (moved from effects-api/.../fabric/)
LocalEffects/enums/FabricParticleKeys.java (moved from effects-api/.../fabric/)
LocalEffects/enums/FabricTitleKeys.java (moved from effects-api/.../fabric/)
LocalEffects/enums/FabricPotionKeys.java (moved from effects-api/.../fabric/)
The Java package FQN of the relocated classes (io.github.dailystruggle.effectsapi.fabric_unobf.…) is identical regardless of which Gradle module compiles them — consumers (e.g. rtp-fabric-common-unobf) name the relocated symbols by their package FQN, not by their host module.
The two subpackages share source-level intent (every type in fabric_unobf/ has the same source body its fabric/ predecessor had at the time of relocation) but differ in their bytecode form because they are compiled under different Loom configurations:
| Carrier | Host module | Loom config | Constant-pool form | Loads on |
|---|---|---|---|---|
effectsapi.fabric.* |
effects-api |
intermediary (existing ADR-003 setup) | net/minecraft/class_NNNN |
1.20 / 1.21.x runtimes; fails on deobf 26.x |
effectsapi.fabric_unobf.* |
effects-api/effects-api-fabric-unobf |
unobfuscated 1.15 (mirrors rtp-fabric-v26_1_R1 / rtp-fabric-common-unobf) |
mojmap (net/minecraft/server/level/ServerPlayer, …) |
deobf 26.x runtimes; fails on 1.20 / 1.21.x intermediary runtimes |
Each carrier is on the classpath of every Fabric runtime; correctness comes from only naming the appropriate carrier from runtime-selected dispatch code, never from both at once. Naming a class triggers loading; we must keep the unsafe carrier name out of any code path the runtime actually executes on the wrong side.
Dispatch policy¶
RTPFabricMod already resolves a per-version FabricVersionAdapter by FQN string at server start (per rtp-fabric-ADR-001). The same string-FQN dispatch picks the correct effects carrier at runtime:
RTPFabricMod.onInitialize
└─ resolve FabricVersionAdapter for the running MC version
├─ adapter.installEffectsWiring(server) returns true
│ → adapter chose its own carrier (e.g. V26_1_R1FabricVersionAdapter
│ names FabricEffectRuntimeUnobf via the rtp-fabric-common-unobf
│ module from ADR-009)
│ → fabric/ carrier is never named on this JVM
└─ adapter.installEffectsWiring(server) returns false
→ fall through to FabricEffectsHandler.setupEffects(server),
which names fabric/FabricEffectRuntime (intermediary form)
→ fabric_unobf/ carrier is never named on this JVM
The three SPI methods added in Phase 5 item 21 (installEffectsWiring, dispatchTitle, dispatchActionbar on FabricVersionAdapter) are the single chokepoint. The unobf adapter named on a 1.20/1.21 runtime is only reachable via per-version adapters that themselves don't load on those runtimes (because they're compiled in rtp-fabric-v26_1_R1/v26_2_R1/…, which are absent from the runtime classpath of 1.20/1.21 servers — see rtp-fabric-ADR-009). The obf adapter named on a 26.x deobf runtime is only reachable when the v26 version-adapter returns false from installEffectsWiring, which it never will once ADR-009 lands.
Amendment 2026-05-09 — sibling module, not source set¶
The original draft proposed a fabricUnobf source set inside effects-api/build.gradle. Implementation on 2026-05-09 disproved that approach: fabric-loom owns the project's MC + mappings configuration at the project level (single loom extension, single minecraft "com.mojang:minecraft:…" coordinate, single mappings mode). Two source sets in the same Loom-configured project share that one regime; there is no supported Loom 1.15 facility to compile main/ under intermediary mappings and fabricUnobf/ under unobfuscated mappings within the same Gradle invocation. Attempting it either silently compiles both source sets under intermediary (defeating the entire split) or fails Loom configuration outright.
The structurally correct mechanism is the same precedent rtp-fabric-ADR-009 set in lockstep: a separate Gradle module with its own Loom plugin instance, its own MC pin, and no mappings line. To honour ADR-003's "no new root directories" constraint, the new module is nested under effects-api/ rather than promoted to a top-level repo-root sibling. Same nesting pattern as platforms/rtp-fabric/rtp-fabric-common-unobf/. Net repo-root delta: zero new top-level directories.
effects-api/effects-api-fabric-unobf/build.gradle shape¶
Mirrors platforms/rtp-fabric/rtp-fabric-common-unobf/build.gradle (and therefore platforms/rtp-fabric/rtp-fabric-v26_1_R1/build.gradle) including the Java 25 toolchain pin, for the same reason recorded in rtp-fabric-ADR-009: com.mojang:minecraft:26.1.2 is Java-25 bytecode and Loom reads it at configuration time, so Java 21 fails with UnsupportedClassVersionError before any source compiles.
plugins {
id 'net.fabricmc.fabric-loom'
}
ext {
minecraftVersion = '26.1.2'
loaderVersion = '0.18.4'
fabricApiVersion = '0.143.5+26.1'
permissionsApiVersion = '0.3.1'
}
java {
toolchain {
// Java 25 — required because com.mojang:minecraft:26.1.2 is Java-25
// bytecode and Loom reads it at configuration time.
languageVersion = JavaLanguageVersion.of(25)
}
}
dependencies {
minecraft "com.mojang:minecraft:${minecraftVersion}"
// No `mappings` line — 26.1+ ships deobfuscated.
implementation "net.fabricmc:fabric-loader:${loaderVersion}"
implementation "net.fabricmc.fabric-api:fabric-api:${fabricApiVersion}"
// The unobf carrier names types from effects-api's common/ SPI
// (Effect, EffectFactory, EffectRuntime). compileOnly keeps it off
// this module's runtime classpath; consumers (rtp-fabric-common-unobf)
// bring effects-api in via their own classpath.
compileOnly project(':effects-api')
compileOnly project(':rtp-api')
compileOnly "me.lucko:fabric-permissions-api:${permissionsApiVersion}"
}
The Loom plugin pin, MC version, loader version, and fabric-api version are intentionally identical to rtp-fabric-v26_1_R1 and rtp-fabric-common-unobf. Drift between the three is the same maintenance hazard already called out in rtp-fabric-ADR-009 Negative / costs; the same gradle.properties follow-up will share pins across all three.
settings.gradle change¶
One line added (alphabetically adjacent to the existing :effects-api include):
include ':effects-api:effects-api-fabric-unobf'
effects-api/build.gradle — unchanged¶
effects-api's own Loom configuration is not modified by this ADR. Its existing intermediary-mappings Loom setup (loom.officialMojangMappings(), MC 1.21.1) continues to compile effectsapi/common/, effectsapi/bukkit/, and the thinned effectsapi/fabric/ carrier. No compileOnly project(':effects-api:effects-api-fabric-unobf') edge is added — effects-api does not name the unobf carrier directly; only rtp-fabric-common-unobf does.
What this ADR explicitly does not change¶
effectsapi/common/*— untouched. TheEffectRuntimeSPI surface from ADR-003 is sufficient.effectsapi/bukkit/*— untouched.- The
rtp.effect.*permission lifecycle, the seven hook points, theEffect<T>base class,EffectFactory.buildEffects— untouched. rtp-plugin/.../bukkit/effects/BukkitEffectsHandler— untouched.addons/RTP_Glide— untouched.- The intermediary
fabric/FabricEffectRuntimecarrier is kept, not deleted. Removing it would break the 1.20 / 1.21.x classpath story; we only thin its responsibilities by moving the initializer/coercer/concrete-effect siblings out.
Consequences¶
Positive¶
- Resolves the Phase 5 / item 22 linkage hazard structurally for every deobf 26.x runtime (26.1.2 today, 26.2 tomorrow, 26.3+ onward), once.
- No throwaway code: every line written under
fabric_unobf/survives the next MC bump because nothing in it is version-specific. - Honours ADR-003's "no new root directories" constraint — the split is internal to
effects-api/. - Pairs cleanly with
rtp-fabric-ADR-009'srtp-fabric-common-unobfmodule: the unobf carrier ineffects-api/is consumed by the unobf carrier inplatforms/rtp-fabric/, and per-version v26.x modules thin out to version-specific deltas only. - Aligns with S-005 (no chunk I/O on main thread — preserved; nothing in the effects path touches chunks), S-006 (API-before-core null guards — unchanged; the SPI fall-through path in ADR-003 already throws
IllegalStateExceptionwhen called before core loads), and S-004 (failure surfacing — preserved through the existing dispatcher try-blocks; no silent swallow added).
Negative / costs¶
- One-time relocation: ~12 files move from
effectsapi/fabric/toeffectsapi/fabric_unobf/, plus one new file (FabricEffectRuntimeUnobf— the mojmap-bytecode mirror ofFabricEffectRuntime). The source bodies are identical at relocation time; subsequent edits must be made in lockstep until/unless a future ADR collapses the two carriers behind a shared common ancestor. CHANGELOG-flagged. - One new nested Gradle module (
effects-api/effects-api-fabric-unobf) and the correspondingsettings.gradleinclude. Build-graph leaf-count grows by one. The new module uses the same Java 25 + Loom 1.15 toolchain asrtp-fabric-v26_1_R1andrtp-fabric-common-unobf; contributors without JDK 25 will see this module fail toolchain provisioning (the rest ofeffects-apiremains on Java 21). Loom config drift between this module and the two existing unobf modules is a maintenance hazard; mitigation is the sharedgradle.properties/versions.gradlefollow-up already recorded inrtp-fabric-ADR-009Negative / costs. - The
effects-apijar now contains two carriers for the fabric platform. This is an allowed jar-content change underrtp-fabric-ADR-002 section 4 Build Discipline's existing exception forrtp-pluginand (post-ADR-003)effects-api. No third-party addon's classpath grows by more than the difference between one and two compiled subpackages; addons that didimport io.github.dailystruggle.effectsapi.fabric.*continue to work — the public-ish symbols (concrete effect names) move underfabric_unobf/, but no in-tree addon imports them today (verified for ADR-003) and a CHANGELOG migration note covers out-of-tree consumers. - The dispatch policy relies on the runtime never naming the wrong carrier. A regression test (bytecode/import scan, mirror of the
EffectsApiCommonNoPlatformImportsTestproposed in ADR-003) is required to assert that no class undereffectsapi/common/*oreffectsapi/bukkit/*references either fabric carrier, and that nothing undereffectsapi/fabric/referenceseffectsapi/fabric_unobf/*or vice versa.
Out of scope (separate follow-ups)¶
- Collapsing
fabric/andfabric_unobf/behind a shared common ancestor (e.g. extracting the source bodies to a*.java.intemplate and generating both subpackages from it). Considered, deferred: the duplication is small, low-churn, and the readability cost of source generation outweighs the maintenance savings until/unless a third Loom regime appears. Re-evaluate when MC introduces a fourth mapping family. - Same-shape obf/unobf split for
commands-api/brigadier/*. Out of scope here; record undercommands-api/docs/adr/if/when a deobf 26.x runtime exposes the same hazard there. - Backporting the unobf carrier to provide deobf-runtime support for 1.20 / 1.21.x dev environments. Not a requirement today; the unobf carrier targets the deobf 26.x family only.
Implementation checklist (will live under Phase 5C of docs/dev/scratch/CHECKLIST-fabric-26-1-2-bringup.md once approved)¶
- Land the companion ADR
platforms/rtp-fabric/docs/adr/rtp-fabric-ADR-009-obf-unobf-common-split.mdfirst (or in lockstep). This ADR is meaningless without a consumer —rtp-fabric-common-unobfis the consumer. (Done 2026-05-09.) - Add
':effects-api:effects-api-fabric-unobf'tosettings.gradle. Createeffects-api/effects-api-fabric-unobf/build.gradleper the build.gradle shape section above (unobfuscated 1.15 Loom, Java 25 toolchain, nomappingsline). Confirm.\gradlew :effects-api:effects-api-fabric-unobf:buildis BUILD SUCCESSFUL on an empty source tree. - Relocate
FabricEffectsInitializer,FabricValueCoercer,FabricRegistryCompat, and the fourLocalEffects/Fabric*Effectclasses (plus their four enum siblings) fromeffects-api/src/main/java/.../effectsapi/fabric/toeffects-api/effects-api-fabric-unobf/src/main/java/.../effectsapi/fabric_unobf/. Javapackagedeclaration updated toio.github.dailystruggle.effectsapi.fabric_unobf[.LocalEffects[.enums]]; source body otherwise unchanged at relocation time. - Add
FabricEffectRuntimeUnobfundereffectsapi/fabric_unobf/(in the new nested module) — same source body as the existingFabricEffectRuntime, package declaration changed, compiled under the unobf module so its NM constant-pool refs survive on deobf 26.x. - Keep
effectsapi/fabric/FabricEffectRuntimeas the obf-runtime carrier; thin it to the minimum required forFabricEffectsHandler.setupEffects(server)to keep working on 1.20 / 1.21.x. (Per-effect classes move out; the obf carrier no longer instantiates them. The obf path on 1.20/1.21 will route through the unobf-side initializer + concrete effects via thertp-fabric-common-unobfmodule loaded under intermediary remap — see ADR-009 for the loader-level dispatch detail.) - Add a regression test
EffectsApiFabricCarriersDisjointTest(bytecode/import scan): asserts thateffectsapi/common/*andeffectsapi/bukkit/*reference neither carrier; thateffectsapi/fabric/*does not reference any class undereffectsapi/fabric_unobf/*; and vice versa. - CHANGELOG entry under the current unreleased version describing the obf/unobf split + addon migration note (any addon importing
effectsapi.fabric.{LocalEffects,FabricEffectsInitializer,FabricValueCoercer,FabricRegistryCompat}.*updates the import toeffectsapi.fabric_unobf.…). - Cross-reference
docs/dev/POTENTIAL_BUGS.mdrows forclass_2596/class_7923(already logged) when closing the work. - Update
.junie/AGENTS.mdDomain Analogies & Aliases if a new informal alias emerges (likely "obf carrier" / "unobf carrier" — add only if it appears in chat/issues, per the Self-Updating Protocol). - Update
docs/dev/TRACEABILITY.mdif any moved class is referenced by a REQ-* row (mechanical path update; no requirement-text change).
Verification gates (must be green before submit of the implementation PR)¶
.\gradlew :effects-api:build :rtp-plugin:compileJava→ BUILD SUCCESSFUL..\gradlew :effects-api:test→ existing tests + newEffectsApiFabricCarriersDisjointTestpass..\gradlew :rtp-fabric:rtp-fabric-v26_1_R1:build→ BUILD SUCCESSFUL (depends on ADR-009's module landing first).- Manual smoke (deferred to admin, after ADR-009 ships):
/rtpon a deobf MC 26.1.2 server witheffectParsing: trueand a sound configured underrtp.effect.postteleportproduces audible feedback; the post-teleport title splash reaches the client. - Manual regression:
/rtpon a 1.21.1 (intermediary) runtime continues to fire effects (the obf path is unchanged from the consumer's perspective).