Skip to content

effects-api-ADR-008 - Effects Through a Neutral Server Accessor, Not Per-Platform Initializers

Status: Accepted (implemented 2026-10-24; amends effects-api-ADR-003 and effects-api-ADR-006) Formerly: ADR-116 Date: 2026-10-18 Linear: RTP-70

Context

Effect classes in effects-api/common/effects/ (TitleEffect, GlideEffect, CommandEffect, DeathEffect, DropInventoryEffect, DropExpEffect) are platform-neutral. Each platform still registers them from its own *EffectsInitializer.registerAll() list of EffectFactory.addEffect(...) calls, and no check compares the lists. They have drifted. Registrations in 3.3.0:

Effect Bukkit / Paper / Folia Fabric (obf carriers) Fabric 26.x (unobf) NeoForge
GLIDE yes yes no no
TITLE no yes yes yes (separate NeoForgeTitleEffect)
DROP_INVENTORY / DROP_EXP yes yes yes no
FIREWORK / NOTE yes no no no

Every platform's handle can run the missing effects: all handles implement setGliding, and Bukkit and both Fabric handles implement sendTitle. The gaps are registration lines that were never copied over. NeoForgeHandles.sendTitle, playNote and spawnFirework have empty bodies that point to "version adapters" no class provides.

Effects reach the platform through their own seam: HandleRegistry / PlayerHandle / ValueCoercer. That seam sits beside RTPServerAccessor and repeats it, so each platform implements two seams. effects-api-ADR-003's single EffectRuntime chokepoint was never built.

Effects used per-platform initializers because effects-api could not depend on the accessor: the accessor once lived in rtp-core, and rtp-core depends on effects-api. The accessor now lives in rtp-api. effects-api is not RTP-specific, though, and api/effects-api/build.gradle dropped its rtp-api dependency on purpose so the module stays standalone. Depending on rtp-api would undo that.

Decision

  1. A neutral platform-seam module. The server accessor contract (RTPServerAccessor and the player, world and location types it needs) moves out of rtp-api into a new module with no io.github.dailystruggle.rtp dependency. rtp-api depends on it and re-exports it, so addon source stays compatible. effects-api depends on this module and on nothing RTP-specific.

Foundation implemented 2026-10-21: ServerAccessor, PlatformFamily and the ServerAccessors holder now live in api/server-api; RTPServerAccessor extends the neutral interface, and the existing RTP registration sites also install the common holder. RTP-specific player, world and location types remain in rtp-api for the later extraction.

Effects routing and unified registration implemented 2026-10-24: api/effects-api now depends on api/server-api (routing default diagnostics and failure logs through ServerAccessors), EffectFactory.registerBuiltInEffects(...) registers the full 11-effect canonical key set (TITLE, GLIDE, COMMAND, DEATH, DROP_INVENTORY, DROP_EXP, SOUND, PARTICLE, POTION, FIREWORK, NOTE plus aliases DROP_EXPERIENCE and KILL) once across Bukkit, Fabric (obf + 26.x unobf), and NeoForge, NeoForgeHandles (and the Fabric handle carriers) implement sendTitle, playNote, and spawnFirework with once-per-primitive unsupported/failure reporting (EffectFactory.reportUnsupportedPrimitive), and EffectRegistrationParityTest + EffectsApiCommonNoPlatformImportsTest guard cross-platform parity and package boundaries.

  1. Platform code implements effect primitives on the accessor. The accessor gains the primitives effects need: title, glide start/stop, sound / particle / potion by string key, note, firework, inventory and experience drop, kill, and command dispatch. Each platform implements them once in its existing accessor. HandleRegistry, PlayerHandle and the effect registration in the per-platform initializers are removed. Registry lookups (Sound, Particle, PotionEffectType, Minecraft registries) stay platform-side behind string keys, which also replaces the ValueCoercer binding.

Implemented 2026-10-24: ServerAccessor and ServerAccessors expose the neutral effect target resolution and console command dispatch contract (wrapEffectPlayer, wrapEffectLocation, resolveEffectPlayerAt, dispatchConsoleCommand), implemented on AbstractServerAccessor and bound by BukkitHandles, FabricHandles, FabricHandlesUnobf, and NeoForgeHandles. EffectTarget and all eleven built-in effects in io.github.dailystruggle.effectsapi.common.effects.* route directly through ServerAccessors, ValueCoercer.DEFAULT provides a platform-neutral default coercer, and HandleRegistry / HandleProvider are retired (@Deprecated(forRemoval = true)) as stateless forwarding shims over ServerAccessors.

  1. One registration. effects-api registers every built-in effect once (EffectFactory.registerBuiltInEffects). A platform that cannot run a primitive reports that explicitly (logged once per primitive via EffectFactory.reportUnsupportedPrimitive, visible from /effectsapi). An empty method body is not allowed.
  2. effects-api carries no platform code. effectsapi/bukkit (BukkitHandles, Bukkit listeners, /effectsapi Bukkit commands) moves to the Bukkit carrier, and spigot-api leaves effects-api/build.gradle. The Fabric and NeoForge effect classes stay in their carriers as accessor implementations.

Implemented 2026-10-24: io.github.dailystruggle.effectsapi.bukkit.* and io.github.dailystruggle.effectsapi.EffectsAPI (along with the Bukkit-specific effect tests) have been relocated from api/effects-api into platforms/rtp-bukkit/rtp-bukkit-common, org.spigotmc:spigot-api has been removed from api/effects-api/build.gradle, and EffectsApiCommonNoPlatformImportsTest verifies that the entire :effects-api module contains zero org.bukkit.*, net.minecraft.*, or io.github.dailystruggle.rtp.* imports or class references.

  1. Mechanical guards. EffectRegistrationParityTest asserts every platform initializer exposes the full built-in effect set or declares each unsupported primitive. EffectsApiCommonNoPlatformImportsTest asserts :effects-api imports no org.bukkit.*, net.minecraft.* or io.github.dailystruggle.rtp.* type.

Alternatives Considered

Alternative Why Rejected
Keep per-platform initializers; add missing lines Fixes 3.3.0's gaps but not the cause. The next effect drifts the same way. Acceptable only as a 3.3.x patch.
Shared registerCommonEffects() over the existing HandleRegistry seam Ends the registration drift but keeps two platform seams per platform. NeoForge's no-op handles show the second seam is where gaps hide.
effects-api depends on rtp-api directly No cycle, but it makes a general-purpose module RTP-specific and undoes the deliberate decoupling in api/effects-api/build.gradle.
Keep RTPServerAccessor in rtp-api and copy it into effects-api Two copies of one contract drift like the initializers did.

Consequences

  • Positive: One platform seam per platform. An effect added to effects-api works on every platform that implements its primitives, and unsupported primitives fail visibly. effects-api becomes reusable outside RTP without platform jars on its compile classpath.
  • Negative / Trade-offs: New Gradle module and a cross-module move of the accessor contract, with japicmp review of rtp-api. Every platform adapter grows effect primitives, and NeoForge needs real sendTitle, playNote and spawnFirework. effectsapi.bukkit.* and effectsapi.common.spi.HandleRegistry disappear from the effects-api artifact, so out-of-tree addons that use them need migration notes in the CHANGELOG. RTPAPI.serverAccessor and RTP.serverAccessor must be set together on every platform (or merged) before effects read the accessor.

References

  • Linear: RTP-70.
  • platforms/rtp-bukkit/rtp-bukkit-common/src/main/java/io/github/dailystruggle/effectsapi/bukkit/BukkitEffectsInitializer.java (registerAll)
  • api/effects-api/effects-api-fabric-unobf/src/main/java/io/github/dailystruggle/effectsapi/fabric_unobf/FabricEffectsInitializer.java
  • platforms/rtp-fabric/rtp-fabric-common/src/main/java/io/github/dailystruggle/rtp/fabric/effects/FabricEffectsInitializer.java
  • platforms/rtp-neoforge/rtp-neoforge-common/src/main/java/io/github/dailystruggle/rtp/neoforge/effects/local/NeoForgeEffectsInitializer.java
  • api/server-api/src/main/java/io/github/dailystruggle/server/api/ServerAccessor.java
  • rtp-api/src/main/java/io/github/dailystruggle/rtp/api/server/RTPServerAccessor.java
  • effects-api-ADR-003, effects-api-ADR-006, leafrtp-ADR-031, ADR-113
  • Operator-facing platform table: EVENTS_AND_EFFECTS.md