effects-api-ADR-002 — Type-Driven Adaptive Reading Order in effects-api¶
(Renumbered from project-wide ADR-030 on 2026-05-05 when subproject ADRs were given per-directory numbering. Prior commits and historical references may still say "ADR-030".)
Status: Accepted
Date: 2026-05-05
Implemented: 2026-05-05 (Effect.applyByType + per-effect KEY_ORDER constants in all six bundled effects; tests in EffectsApiAdaptiveReadingOrderTest)
Amended by: effects-api-ADR-004 (Accepted, 2026-05-07) — replaces the four org.bukkit.* FQNs in section "Type acceptance (canParse)" with platform-neutral TypeKey constants and adds a "Platform binding" paragraph; the ordering and cache-promotion semantics in this ADR are unchanged. The leaf operations of canParse / parse / reflective fallback are now per-platform, supplied by a ValueCoercer implementation bound at platform-init time (BukkitValueCoercer on Bukkit-family, FabricValueCoercer on Fabric).
Implementation note (post-acceptance)¶
The "record unparsed tokens" requirement is satisfied via an injectable
Consumer<String> warn sink on Effect, mirroring the
commands-api-style "pass in a message function" pattern rather than
wiring effects-api to rtp-core's RTP.log. The host plugin can
swap the sink with Effect.setDefaultWarn(...); the library default
prints to System.err (a strict improvement over the prior
printStackTrace() paths in Effect#str2Obj/Effect#fixData,
consistent with AGENTS.md "Zero printStackTrace()"). This keeps
effects-api independent of any host-plugin logger while still
satisfying S-004 (no silent failures).
Context¶
effects-api parses effect arguments through Effect.setData(String... data).
Each Effect<T> declares an enum T of typed keys (e.g. FireworkTypeNames,
ParticleTypeNames) whose declaration order doubles as the positional
order consumed by setData(String...). This is documented in
effects-api/src/main/java/io/github/dailystruggle/effectsapi/LocalEffects/Readme.md:
Key-order in the table = positional order expected by
setData(String...).
Concrete examples of the rigid positional contract:
FireworkEffect: tokens are read as[TYPE, POWER, FLICKER, TRAIL, COLOR, FADECOLOR].- A hypothetical
GlideEffect(see effects-api-ADR-001 (formerly ADR-029)) is intended to expose[MATERIAL, STARTHEIGHT, WORLD, ...].
The rigid order has a practical failure mode that has surfaced repeatedly in addon configs and in user-supplied permission strings:
- An operator wants only a custom
startHeightand aworldfilter; they omitmaterial. With positional parsing, the first token (intended asstartHeight) is misread asmaterialand rejected; the parser either crashes or silently degrades to defaults for later fields. - Permission-node round-trips (
toPermission()/ parse) compound the problem because users hand-edit those nodes.
What we actually want, and what this ADR specifies, is a type-driven
adaptive reading order: when a token does not match the type of the next
expected key, fall through to the next key whose declared type does accept
it. Concretely, given keys [MATERIAL, STARTHEIGHT, WORLD] and input
["64", "world_nether"], the parser should assign STARTHEIGHT=64 (because
"64" is not a valid Material but is a valid integer) and WORLD=world_nether
(because the remaining token is not an integer but is a loaded world name),
rather than failing on MATERIAL="64".
This is complementary to but separate from effects-api-ADR-001 (formerly ADR-029) (which folds
glide into effects-api). effects-api-ADR-001 (formerly ADR-029) introduces fields whose typical
real-world configurations exhibit exactly this "skipped earlier field"
shape, which made the long-standing parsing brittleness acute enough to
warrant its own decision record.
Per Rule D-005, this ADR documents the plan only; implementation requires explicit approval before code lands.
Decision¶
We will replace the strictly-positional setData(String...) contract with
a type-aware, order-preserving, fall-through parser in effects-api.
Parser contract¶
For an Effect<T> whose enum T declares keys k0, k1, …, kn with
declared types Type(k0), Type(k1), …, Type(kn), given input tokens
t0, t1, …, tm:
- Initialise a cursor
i = 0over keys. - For each input token
t: - Walk forward from
k_iuntil the first keyk_j(j ≥ i) whose declared type acceptst(canParse(Type(k_j), t) == true). - If found, assign
data[k_j] = parse(Type(k_j), t), seti = j + 1, and continue to the next token. - If no remaining key accepts
t, record an entry in a per-effectunparsedTokenslist and continue. Do not advancei. - Keys that are never assigned retain their constructor-set defaults (already the case today).
- Order of acceptance is preserved: the parser never rewinds (a token
cannot fill a key earlier than the previous token's key). This keeps
toPermission()round-trips deterministic and avoids combinatorial ambiguity.
Type acceptance (canParse)¶
canParse(type, token) is implemented per-type and returns true only on
exact, side-effect-free recognition:
Material/ similar enums —Material.matchMaterial(token) != null.Integer/Long—tokenparses withInteger.parseInt/Long.parseLongand (for keys that declare a range) lies within range.Double/Float—tokenparses and is finite.Boolean—tokenmatchestrue|false|yes|no|on|off(case-insensitive), using the existingBooleanparser already used elsewhere ineffects-apifor symmetry.World—Bukkit.getWorld(token) != nullor the token equals*/ a configured world filter sentinel.Color— currentEffect#fixDatacolor parser returns non-null.Particle,Sound, enum constants —Enum.valueOfsucceeds (or the effect's own*Nameslookup table accepts it).String(free-form) — always accepts. Keys typed as free-formStringare therefore "greedy": they will swallow any token that no earlier key accepted up to that point. Effect authors are warned inLocalEffects/Readme.mdthat free-formStringkeys should appear late in the enum order to avoid masking later typed keys.
canParse is pure: no Bukkit world load, no chunk I/O, no scheduler call.
This is required for S-005 compliance — config parsing runs on the main
thread today and must remain synchronous and cheap.
Backwards compatibility¶
- All existing configs that already provided tokens in the declared order continue to parse identically: the fall-through never triggers because the very first key always accepts the very first token.
- All existing configs that previously errored on a skipped earlier field now succeed if the user's intent matches the next type-accepting key. This is a strict superset of previous accepted inputs.
- The pathological case of a token that is genuinely valid for two
consecutive keys (e.g.
"1"valid as bothint POWERandint FLICKER) still resolves left-to-right exactly as today — no semantic change. toPermission()continues to emit tokens in declared key order. Round-tripping a permission node parses bit-identically because every emitted token matches its key's type.
Free-form String keys (caveat)¶
Effects whose keys include a String-typed field followed by typed
fields (e.g. a hypothetical [NAME(String), POWER(int)]) must reorder
the enum so the String key sits at the end, or use a typed wrapper
(e.g. an enum of allowed names). This is a pre-existing latent issue
made explicit by this ADR. LocalEffects/Readme.md will be updated to
state: "String-typed keys greedily accept any unmatched token; place
them last in the enum."
Failure & safety¶
- S-004: tokens that match no remaining key are recorded under
unparsedTokensand logged atWARNINGviaRTP.logonce persetDatacall (collapsed list). Never silently dropped. - S-005: parsing performs no chunk I/O.
Worldrecognition usesBukkit.getWorld(name)which is a map lookup, not a load. - REQ-RTP-F-013: any user-facing diagnostic string (e.g. an
/effectsapiadmin command listing unparsed tokens) is keyed inmessages.yml; nothing hardcoded.
Testing¶
- Unit test
EffectsApiAdaptiveReadingOrderTest: [MATERIAL, STARTHEIGHT, WORLD]with input["64", "world_nether"]yieldsSTARTHEIGHT=64,WORLD=world_nether, defaultMATERIAL.[MATERIAL, STARTHEIGHT, WORLD]with input["STONE", "64", "world_nether"]yields the same as today (no regression).[MATERIAL, STARTHEIGHT, WORLD]with input["world_nether", "64"]yieldsWORLD=world_nether,STARTHEIGHT=64only ifSTARTHEIGHTappears beforeWORLDin the enum and the token order also permits it; otherwise recordsworld_netheras unparsed for theMATERIALslot — i.e. the parser does not rewind.- Token
"banana"produces anunparsedTokensentry plus a singleWARNINGlog line. - Round-trip test
EffectsApiPermissionRoundTripTest: every existing fixture ineffects-apiparses →toPermission()→ re-parses bit-identically. - Per-effect smoke tests for
FireworkEffect,ParticleEffect,PotionEffect,SoundEffect,NoteEffectconfirm no regression. TRACEABILITY.mdrows added once a REQ-* ID is authored for the parser contract (out of scope for this ADR).
Alternatives Considered¶
| Alternative | Why Rejected |
|---|---|
Keep strict positional order; require null / - placeholders |
Already supported partially via Effect#fixData, but operators do not use it; UX remains poor. Forcing placeholders in permission nodes is hostile to hand-editing. |
Switch to a fully named-key parser (material=STONE startHeight=64) |
Larger UX break; permission-node format is positional today and round-tripping breaks for everyone. Could be added later as an additive syntax on top of the fall-through parser. |
| Backtracking parser (try every assignment, pick the most-fields-filled) | Combinatorial blow-up for effects with many keys; non-deterministic round-trips when two parses fill the same number of fields; harder to debug. |
| Fall-through but allow rewind (token may fill an earlier key) | Breaks round-trip determinism: a single token list can produce two valid assignments depending on which key the parser tries first. Rejected. |
| Per-effect bespoke parsers | Duplicates logic; every new effect (including GlideEffect from effects-api-ADR-001 (formerly ADR-029)) re-implements the same fall-through. The contract belongs in Effect / EffectFactory. |
Consequences¶
- Positive:
- Operators can omit optional earlier fields without shifting later fields out of place; the most common config-error class disappears.
- effects-api-ADR-001's
GlideEffect(with[MATERIAL, STARTHEIGHT, WORLD, ...]) becomes pleasant to configure: droppingmaterialno longer breaksstartHeight. - Permission-node round-trips remain deterministic.
- Diagnostic surface improves: unparsed tokens are surfaced in logs instead of vanishing into wrong slots.
- Negative / Trade-offs:
- One-time documentation task:
LocalEffects/Readme.mdmust call out the "free-formStringkeys go last" rule, and theeffects-apiREADME's parsing section needs a paragraph on the new contract. - Subtle semantic change for ill-typed effect enums that placed
Stringkeys early — those will start swallowing tokens. Audit of bundledLocalEffects/*enums is part of the implementation task; none of the current bundled effects appear affected. - Parser cost grows from O(tokens) to O(tokens × remainingKeys) in the worst case. Both are tiny constants; negligible at runtime.
References¶
- Existing parser contract:
effects-api/src/main/java/io/github/dailystruggle/effectsapi/Effect.java(setData(String...)),EffectFactory.java. - Positional-order documentation:
effects-api/src/main/java/io/github/dailystruggle/effectsapi/LocalEffects/Readme.md. - Bundled effects whose enums define the canonical key order:
LocalEffects/FireworkEffect.java,ParticleEffect.java,PotionEffect.java,SoundEffect.java,NoteEffect.java. - Companion ADR motivating the immediate need:
effects-api-ADR-001-glide-effect.md. - Safety rules:
.junie/AGENTS.md→ Prohibition Requirements (S-00x), in particular S-004 (no silent failure) and S-005 (no main-thread chunk I/O). - Architectural placement:
.junie/AGENTS.md→ Architecture Boundaries (effects-api owns this contract; notrtp-core/rtp-api). - Message configurability: REQ-RTP-F-013 in
docs/dev/REQUIREMENTS.md.