effects-api-ADR-003 — In-module platform split: effectsapi/common (SPI) + effectsapi/bukkit + effectsapi/fabric¶
- Status: Accepted (2026-05-06; revised after user feedback the same day; amended 2026-10-15 -
effectsapi/fabricmoved to the Fabric platform carrier, see Amendment 2026-10-15) - Supersedes: —
- Superseded by: —
- Amendment proposed: effects-api-ADR-008 (effects through a neutral server accessor; the
EffectRuntimechokepoint below was never built, and per-platform registration lists have drifted - RTP-70) - Related:
.junie/AGENTS.mdArchitecture Boundaries (no platform imports inrtp-api/rtp-core; analogous principle applied toeffectsapi/common).commands-api-ADR-001-brigadier-bridge.md— direct precedent:commands-apikeepscommon/,bukkit/,brigadier/as subpackages of one module withcompileOnlySpigot +compileOnlyBrigadier; we mirror that exact shape here.rtp-fabric-ADR-001-fabric-multiversion-submodule-layout.md(multi-MC layering —effectsapi/fabriconly sees the common Fabric surface, not per-MC packets directly; concrete packet calls live inrtp-fabric-common/RTPFabricMod).rtp-fabric-ADR-007-mojmap-name-decoupling.md(rationale for keepingnet.minecraft.*calls behind a thin SPI).effects-api-ADR-001-glide-effect.md,effects-api-ADR-002-type-driven-reading-order.md(per-effect contracts kept intact).docs/dev/scratch/CHECKLIST-fabric-startup-parity.mdItem 2 (this ADR unblocks it).
Context¶
effects-api today is Bukkit-coupled at the base class: every effect extends org.bukkit.scheduler.BukkitRunnable and the abstract Effect<T> imports org.bukkit.{Color, Location, NamespacedKey, Registry, Sound, entity.Entity}. EffectFactory calls Bukkit.getPluginManager() / Permission / PotionEffectType. Every concrete effect under LocalEffects/* and every listener under BukkitListeners/* is Bukkit-typed.
Net effect on Fabric: classloading EffectFactory.buildEffects(...) triggers NoClassDefFoundError on BukkitRunnable. Fabric cannot adopt any rtp.effect.* permission node, so effectParsing is silently a no-op on Fabric (Item 2 of CHECKLIST-fabric-startup-parity.md).
Call surface is small and fully contained:
rtp-plugin/.../bukkit/effects/BukkitEffectsHandler.java— 10EffectFactory.buildEffects(...)call sites (one per lifecycle hook).effects-api/.../commands/*— Bukkit-side/effectsadmin command tree.- No third-party in-tree consumers (
addons/RTP_Glidedoes not importeffectsapi).
User constraint (revision driver, 2026-05-06)¶
"try not to create more root level directories, we can do this within effects-api like we did with commands-api"
The earlier draft of this ADR proposed three sibling root modules (effects-api, effects-api-bukkit, effects-api-fabric). The revised decision below keeps everything inside the existing effects-api module, exactly mirroring how commands-api hosts common/, bukkit/, and brigadier/ subpackages in one gradle module.
Decision¶
Re-organise effects-api internally into three sibling subpackages, with no new gradle modules:
effects-api/ (existing module — unchanged at the gradle level)
src/main/java/io/github/dailystruggle/effectsapi/
common/ ← NEW — platform-neutral SPI + base types
Effect.java (moved; no longer extends BukkitRunnable)
EffectFactory.java (moved; permission lookup via RTPPlayer)
spi/EffectRuntime.java (NEW — schedule / playSound / particle / potion)
spi/EffectTarget.java (NEW — wraps RTPPlayer + RTPLocation)
configmodel/ (NEW — string-keyed POJOs for sound/particle/note/color)
bukkit/ ← RENAMED from current top-level
BukkitEffectRuntime.java (NEW — implements EffectRuntime via Bukkit)
LocalEffects/{Sound,Particle,Note[, _1_12], Potion, Firework, Glide}Effect.java (moved verbatim, retargeted onto EffectRuntime)
BukkitListeners/{Firework,Glide}SafetyListener.java (moved verbatim)
commands/* (Bukkit /effects admin tree) (moved verbatim)
events/* (Bukkit-typed events) (moved verbatim)
fabric/ ← NEW
FabricEffectRuntime.java (NEW — implements EffectRuntime via ServerLevel + clientbound packets)
FabricSoundEffect.java
FabricParticleEffect.java
FabricTitleEffect.java
FabricPotionEffect.java
// FireworkEffect & GlideEffect deferred — see "Out of scope, Phase 2" below.
Gradle wiring (mirrors commands-api/build.gradle)¶
A single effects-api/build.gradle keeps both platforms as compileOnly so neither leaks into runtime classpaths of the wrong adapter:
plugins {
// Required so the fabric subpackage can resolve net.minecraft.* at compile time.
// Same precedent as :rtp-plugin (Loom + compileOnly Spigot in one module — see
// rtp-plugin/build.gradle Phase-1 comment block).
id 'fabric-loom'
}
ext {
minecraftVersion = '1.21.1' // mirrors rtp-fabric-common; bump in lockstep
loaderVersion = '0.16.5'
fabricApiVersion = '0.115.0+1.21.1'
}
dependencies {
// common/ + bukkit/ subpackages
compileOnly 'org.spigotmc:spigot-api:1.20.1-R0.1-SNAPSHOT'
testImplementation 'org.spigotmc:spigot-api:1.20.1-R0.1-SNAPSHOT'
// fabric/ subpackage — Loom-managed Mojmap MC + Fabric loader/api as compileOnly
minecraft "com.mojang:minecraft:${minecraftVersion}"
mappings loom.officialMojangMappings()
modCompileOnly "net.fabricmc:fabric-loader:${loaderVersion}"
modCompileOnly "net.fabricmc.fabric-api:fabric-api:${fabricApiVersion}"
// Already present
implementation project(':commands-api')
implementation 'org.jetbrains:annotations:24.1.0'
}
rtp-plugin keeps its single implementation project(':effects-api') line — no consumer-side dependency change needed. BukkitEffectsHandler switches imports from io.github.dailystruggle.effectsapi.LocalEffects.* → io.github.dailystruggle.effectsapi.bukkit.LocalEffects.* (mechanical). RTPFabricMod gains a parallel FabricEffectsHandler (or inline branch) calling EffectFactory.buildEffects(...) against the new fabric/ runtime.
EffectRuntime SPI (initial surface, refined during implementation)¶
package io.github.dailystruggle.effectsapi.common.spi;
public interface EffectRuntime {
void schedule(Runnable task, long delayTicks); // replaces Effect#runTask*
void scheduleRepeating(Runnable task, long delayTicks, long periodTicks);
void playSound(EffectTarget target, String soundKey, float volume, float pitch);
void spawnParticle(EffectTarget target, String particleKey, int count,
double dx, double dy, double dz, double speed);
void givePotion(EffectTarget target, String potionKey, int durationTicks, int amplifier);
// Title / actionbar already routed through RTPPlayer (FabricRTPPlayer.sendTitle /
// SendMessage.title on Bukkit), so not duplicated here.
}
Effect<T>#run() keeps its current shape; the only structural change is that subclasses receive an injected EffectRuntime (constructor or EffectFactory#build site) rather than calling Bukkit.* directly. Effect no longer extends BukkitRunnable; the only callers (BukkitEffectsHandler lines 192/306/…) currently do effect.runTask(plugin) and switch to runtime.schedule(effect, 0).
Consequences¶
Positive¶
- No new root-level directories — honours the user's constraint and keeps the project structure aligned with
commands-api's precedent. - Fabric gains a real
rtp.effect.*lifecycle hook surface (unblocksCHECKLIST-fabric-startup-parity.mdItem 2). effectsapi/commonis consumable by addons that don't want a Bukkit dependency — same benefitrtp-apialready provides.- Threading boundary aligns with S-005 (the SPI is the single chokepoint for "what thread does this run on").
- Zero churn for in-tree addons —
RTP_Glidedoesn't touch the API today.
Negative / costs¶
- One-time refactor: 8 effect classes +
EffectFactoryto threadEffectRuntime, plus mechanical package moves underbukkit/. effects-api/build.gradlegains thefabric-loomplugin and Loom config block.rtp-fabric-ADR-002 section 4 Build Discipline(andplatforms/rtp-fabric/REQUIREMENTS.mdREQ-FABRIC-ARCH-003) currently restrict Loom toplatforms/rtp-fabric/**andrtp-plugin; this ADR widens that allow-list to also includeeffects-api(rationale: same single-jar mixed-platform precedent asrtp-plugin). REQ-FABRIC-ARCH-003 and ADR-002 section 4 are amended in lockstep with this ADR's acceptance.effectsapi/bukkitpackage move = ~15 file paths change. All consumers are in-tree; oneBukkitEffectsHandlerimport-block edit covers them.- Public-ish change: any out-of-tree addon that does
effect.runTask(plugin)directly migrates toruntime.schedule(effect, 0)— CHANGELOG-flagged.
Out of scope (Phase 2 follow-ups, separate ADR)¶
FabricFireworkEffect— needsFireworkRocketEntityspawn + safety listener equivalent.FabricGlideEffect— needs elytra-equip + glide-state plumbing; no clean Fabric primitive without a mixin.FabricEffectsAPIMainCommand— admin command port; Bukkit-only is acceptable for Phase 1.
Implementation checklist (will live in docs/dev/scratch/CHECKLIST-effects-api-platform-split.md once approved)¶
- Update
effects-api/build.gradle: applyfabric-loom, add Mojmap MC + Loader/APImodCompileOnly, keep SpigotcompileOnly. Confirm:effects-api:buildstill green before any code moves. - Create
effectsapi/common/spi/{EffectRuntime,EffectTarget}.java. - Move
Effect.javaandEffectFactory.javaintoeffectsapi/common/; de-Bukkit-ify them (dropextends BukkitRunnable, swaporg.bukkit.{Color,Location,NamespacedKey,Registry,Sound,Entity}for neutralStringkeys +RTPLocation; replaceBukkit.getPluginManager()permission lookup withRTPPlayer.getEffectivePermissions()). - Move
LocalEffects/*,BukkitListeners/*,commands/*,events/*intoeffectsapi/bukkit/...(verbatim except the package declaration). AddBukkitEffectRuntime. - Update
rtp-plugin/.../bukkit/effects/BukkitEffectsHandler.java: 10 call sites switch fromeffect.runTask(plugin)toruntime.schedule(effect, 0); import block updated toeffectsapi.bukkit.LocalEffects.*. - Add
effectsapi/fabric/withFabricEffectRuntime+ Phase-1 effects (Sound,Particle,Title,Potion). - Wire
RTPFabricMod.onInitializeto callEffectFactory.buildEffects(...)on each lifecycle hook (the sevenrtp.effect.*perms — same shape asBukkitEffectsHandler). - CHANGELOG entry under the current unreleased version describing the in-module split + addon migration note.
- Tests:
- Existing
effects-api/src/test/...tests stay where they are (they exerciseLocalEffectswhich now live undereffectsapi.bukkit.*— package-line update only). - Add a core test asserting
effectsapi.common.*has noorg.bukkit.*/net.minecraft.*references (bytecode/import scan). - Add a
FabricEffectRuntime#playSoundpacket-shape smoke test (mirrorsFabricLegacyTextInteractiveTeststyle).
- Existing
- Update
.junie/AGENTS.mdDomain Analogies & Aliases if needed (likely not — no new informal terms).
Amendment 2026-10-15 - Minecraft-typed code lives in the platform carriers¶
Driver: ADR-113 lowers the shared closure (effects-api included) to Java 17 bytecode. The fabric/ subpackage forced Loom and the Java 21 MC 1.21.1 jar onto effects-api, and platform code belongs to the platform modules that already own a Minecraft classpath.
Decision:
effects-apikeepscommon/(platform-neutral SPI) andbukkit/(Spigot 1.20.1 is Java 17 bytecode). It no longer appliesfabric-loomand carries nonet.minecraft.*code.- The former
effectsapi.fabric.*classes (FabricEffectRuntime,FabricEffectsInitializer,FabricHandles,FabricRegistryCompat,FabricValueCoercer) move to:rtp-fabric:rtp-fabric-commonasio.github.dailystruggle.rtp.fabric.effects.*. They implement the existingeffectsapi.commonSPI (HandleProvider,ValueCoercer,EffectFactory); no new SPI or module is introduced. - NeoForge stops reusing the Fabric runtime.
rtp-neoforge-commonschedules effects throughNeoForgeHandles.execute(MinecraftServer#execute) and owns its effect key enums (NeoForge{Sound,Particle,Potion,Title}Keys). The formereffectsapi.fabric.LocalEffects.enums.Fabric*Keyshad no Fabric consumer. - The obf/unobf disjointness guard (effects-api-ADR-006) moves with the obf carrier to
rtp-fabric-common(FabricEffectsCarriersDisjointTest). - REQ-FABRIC-ARCH-003 is amended in lockstep:
effects-apileaves the Loom allow-list; the nestedeffects-api-fabric-unobfcarrier stays on it.
Consequences: The effectsapi.fabric package is removed from the effects-api artifact (already excluded from japicmp as non-API). Out-of-tree code that imported it switches to io.github.dailystruggle.rtp.fabric.effects.
Verification gates (must be green before submit)¶
.\gradlew :effects-api:build :rtp-plugin:compileJava→ BUILD SUCCESSFUL..\gradlew :effects-api:test→ all moved Bukkit tests pass.- New core test
EffectsApiCommonNoPlatformImportsTest(or equivalent bytecode assertion) passes foreffectsapi.common.*. - Manual smoke (deferred to admin):
/rtpon Fabric witheffectParsing: trueand a sound configured underrtp.effect.postteleportproduces audible feedback.