effects-api-ADR-004 — ValueCoercer SPI: Per-Platform Type Binding for the Adaptive Reading Order¶
Status: Accepted (2026-05-07)
Date: 2026-05-06
Amends: effects-api-ADR-002 (does not supersede)
Refines: effects-api-ADR-003 step 3 (de-Bukkit-ifying Effect)
Context¶
effects-api-ADR-003 (Accepted 2026-05-06) split effects-api internally into
effectsapi/common, effectsapi/bukkit, and effectsapi/fabric subpackages.
Step 3 of the implementation checklist landed Effect and EffectFactory in
effectsapi.common, but the body of Effect.java still imports
org.bukkit.{Color, Sound, Particle, PotionEffectType} because
effects-api-ADR-002's adaptive reading order
(Effect#fixData / Effect#str2Obj / Effect#canParse /
Effect#resolveSound / Effect#resolveNamedColor /
Effect#resolveViaRegistry) was authored against those Bukkit types as the
canonical leaf parsers. That kept Phase 1 of ADR-003 small but means
effectsapi.common cannot yet pass a "no org.bukkit.* imports" bytecode
test, and Fabric currently has no ADR-002-compliant path at all.
The user question that triggered this ADR — "can ADR-002 still work as it did with variant behavior on each platform via supplier or similar?" — answers itself once the three responsibilities ADR-002 actually bundles are separated:
- Ordering & cache policy — try declared-type predicates in declared
order, promote the winner per
(effectName, fieldName)key. Pure logic; no platform types. The regression guardEffectsApiAdaptiveReadingOrderTestexercises only this. - Type predicates / parsers —
canParse(type, raw)andparse(type, raw). Today implemented withinstanceof-switches overColor.class,Sound.class,Particle.class, etc. - Registry resolvers —
Registry.SOUNDS.get(NamespacedKey.minecraft(raw))and friends.
(1) is platform-neutral. (2) and (3) are the only platform-bound parts. Therefore ADR-002 can keep working unchanged on each platform if the leaf operations become a per-platform supplier.
Per Rule D-005, this ADR is Proposed until accepted; no code lands until
then.
Decision¶
Introduce a ValueCoercer SPI in effectsapi.common.spi that owns the
per-platform leaf operations of ADR-002's adaptive reading order. Effect
moves from instanceof-on-org.bukkit.* switches to delegating those
checks and parses to a ValueCoercer instance bound at platform-init time
by BukkitEffectsInitializer.registerAll() (Bukkit) and
FabricEffectsInitializer.registerAll() (Fabric).
SPI shape¶
package io.github.dailystruggle.effectsapi.common.spi;
public interface ValueCoercer {
/** Cheapest, side-effect-free check: can the raw token be read as the given logical type? */
boolean canParse(TypeKey type, String raw);
/** Parse the raw token into the platform-native object the concrete effect consumes. */
Object parse(TypeKey type, String raw);
/** Declared reading order for this platform; drives ADR-002's adaptive ladder. */
java.util.List<TypeKey> readingOrder();
}
TypeKey is a closed enum (sealed against drift) in
effectsapi.common.spi:
public enum TypeKey {
SOUND, PARTICLE, COLOR, POTION_EFFECT, MATERIAL, WORLD,
STRING, INT, LONG, DOUBLE, FLOAT, BOOLEAN
}
Binding¶
EffectFactoryexposes a single static setter:EffectFactory.setCoercer(ValueCoercer). Idempotent; second call replaces the first (initializers are themselves idempotent per ADR-003).BukkitEffectsInitializer.registerAll()callsEffectFactory.setCoercer(new BukkitValueCoercer())before the six legacy registrations.FabricEffectsInitializer.registerAll()callsEffectFactory.setCoercer(new FabricValueCoercer())before any Fabric registrations.- If
Effectis asked to coerce before any initializer runs (addon misordering), it throwsIllegalStateExceptionper S-006 — never null, never silent (S-004).
Concrete coercers¶
effectsapi.bukkit.BukkitValueCoercer implements ValueCoercer— wraps the currentEffect#resolveSound/Effect#resolveNamedColor/Effect#resolveViaRegistry/Effect#canParse/Effect#str2Objbodies verbatim, just relocated. No behavioural change on Bukkit.effectsapi.fabric.FabricValueCoercer implements ValueCoercer— usesRegistries.SOUND_EVENT.get(ResourceLocation.tryParse(raw)),BuiltInRegistries.PARTICLE_TYPE,MobEffectslookup, etc. Phase-1 scope:SOUND,PARTICLE,POTION_EFFECT, plus the type-agnostic primitives (STRING/INT/LONG/DOUBLE/FLOAT/BOOLEAN, identical to Bukkit).COLOR,MATERIAL,WORLDmay returnOptional.empty()/falsefromcanParseuntil concrete Fabric effects need them (deferred to Phase 2).
Effect body changes¶
Net delta inside Effect.java:
- Replace each
instanceof Color/Sound/Particle/PotionEffectTypebranch infixData/str2Obj/canParsewith aTypeKeylookup (Map<Class<?>, TypeKey>populated lazily perdefaultsmap; the lookup is the only place ADR-004 touches reflection). - Delete
resolveSound,resolveNamedColor,resolveViaRegistry. The bodies move intoBukkitValueCoercerunchanged. - Remove
org.bukkit.*imports fromEffect.java. - Keep
extends BukkitRunnabledeferred to a future ADR (out of scope here — ADR-003 step 3 is unblocked without it; concrete effects on Bukkit still extendEffectandrunTask(plugin); Fabric concrete effects implementRunnableand are scheduled viaEffectRuntime).
What ADR-002 needs to say (amendment, not supersedence)¶
ADR-002 is amended in two places only:
- section "Type acceptance (
canParse)" — replace the fourorg.bukkit.*FQNs with the equivalentTypeKeyconstants (SOUND,PARTICLE,COLOR,POTION_EFFECT). The semantic descriptions ("non-null lookup", "registry hit", etc.) carry over verbatim. - New one-paragraph section "Platform binding": "On any platform, the concrete
object returned by
ValueCoercer.parseis the type the platform'sEffectsubclasses consume. ADR-002 governs the order and the cache-promotion rule; the binding ofTypeKeyto a runtime object is per-platform and lives in theValueCoercerimplementation selected by the platform initializer (see ADR-004)."
The "Implementation note (post-acceptance)" header at the top of ADR-002 gains one bullet pointing at this ADR.
Cache invariants preserved¶
The (effectName, fieldName) → winningTypeKey cache that
EffectsApiAdaptiveReadingOrderTest pins survives unchanged:
- The cache key remains
(effectName, fieldName). - The cache value's type changes from
Class<?>(Bukkit class literal) toTypeKey(platform-neutral). The test does not inspect the value type — it asserts only that the second parse skips predicates that failed the first. - Determinism per platform is now contractual:
ValueCoercer.canParsemust be a pure function of(type, raw). Documented in the SPI Javadoc.
Alternatives Considered¶
- Supersede ADR-002 with a string-keyed model. Rejected — would force
every concrete effect (
SoundEffect,ParticleEffect,PotionEffect,FireworkEffect,NoteEffect,GlideEffect) to carry its own string-to-object resolver, duplicating the registry lookups ADR-002 deliberately centralised. Also breaks the existing test assetEffectsApiAdaptiveReadingOrderTestand every addon'sdefaultsmap. - Push all coercion into per-platform
Effectsubclasses, keepdefaultstyped per platform. Rejected — duplicates the reading order ladder per platform and makes the regression guard platform-specific. Also reintroduces theorg.bukkit.*imports the ADR-003 split set out to remove. - Keep
Effect/EffectFactoryBukkit-typed undereffectsapi/bukkit/and let Fabric provide a parallelFabricEffectFactory(option (iv) in the ADR-003 step-3 menu). Currently shipped as the interim posture. Works, but doubles the surface area, preventseffectsapi.commonfrom passing a "no platform imports" bytecode test, and leaves Fabric without an ADR-002 path. Acceptable as a bridge; not acceptable as the end state. - Use Java's
ServiceLoaderinstead of an explicit setter. Rejected — initializer order is part of the public API surface (ADR-003 makesBukkitEffectsInitializer.registerAll()the only documented entry point), andServiceLoadermakes that order observably non-explicit on shaded jars.
Consequences¶
Positive¶
effectsapi.commonbecomes free oforg.bukkit.*imports — the bytecode test queued in ADR-003 step 9b can be written and run.- ADR-002's adaptive reading order works on Fabric without a single text change to ADR-002's algorithm description.
- Fabric gains an ADR-002-compliant parser path the day
FabricValueCoercerlands (Phase 1:SOUND/PARTICLE/POTION_EFFECTcover the four planned Fabric concrete effects). - The existing
EffectsApiAdaptiveReadingOrderTestbecomes the cross-platform regression guard for free. EffectFactory.setCoercer(...)is the only new public API; one method, fail-fast on misuse.
Negative / costs¶
- One new SPI surface (
ValueCoercer+TypeKey) addons may consume. Documented, versioned witheffects-api. Effect.javabody shrinks but every concrete effect still has to understand the platform-native object returned byValueCoercer.parse(...). This is unavoidable on any platform-split design;ValueCoercerdoes not pretend to make concrete effects platform-portable, onlyEffect/EffectFactory.- Addon authors who reflectively reached into
Effect#str2Obj/Effect#resolveSound(none known in-tree, none documented inEXTERNAL_HOOKS.md) will break. CHANGELOG entry required.
Neutral¶
- The interim Bukkit-typed
BukkitEffectsInitializer.buildEffects(...)shipped with ADR-003 step 3 stays — it's an addon-facing convenience layer, orthogonal to coercion.
Implementation order (informational; lands in a follow-up checklist)¶
effectsapi/common/spi/TypeKey.java(enum).effectsapi/common/spi/ValueCoercer.java(interface).EffectFactory.setCoercer(...)+IllegalStateException-throwing accessor.effectsapi/bukkit/BukkitValueCoercer.java— relocateEffect#resolveSound/Effect#resolveNamedColor/Effect#resolveViaRegistrybodies verbatim.- Refactor
Effect.java: switchcanParse/fixData/str2ObjtoTypeKeylookup; delete the moved methods; removeorg.bukkit.*imports. BukkitEffectsInitializer.registerAll()— first line:EffectFactory.setCoercer(new BukkitValueCoercer()).- ADR-002 amendment commit (text-only, two edits described above).
effectsapi/fabric/FabricValueCoercer.java(Phase-1 types only).FabricEffectsInitializer.registerAll()— first line:EffectFactory.setCoercer(new FabricValueCoercer()).- Bytecode test:
EffectsApiCommonNoPlatformImportsTest(ADR-003 step 9b — now achievable). - CHANGELOG entry under the current unreleased version.
Verification gates: existing EffectsApiAdaptiveReadingOrderTest green,
new EffectsApiCommonNoPlatformImportsTest green,
.\gradlew :effects-api:build :rtp-plugin:compileJava green.
References¶
effects-api-ADR-002— the contract this ADR amends.effects-api-ADR-003— the platform split this ADR completes.docs/dev/scratch/CHECKLIST-effects-api-platform-split.md— step 3 deferred work this ADR resolves.- AGENTS.md Prohibition Requirements — S-004 (no silent failures), S-006 (fail-fast on early API use).