| name | legacy-1.8.9 |
| description | Use when touching the 1.8.9 legacy overlay, -Pse.target=legacy builds, JvmDowngrader, the mega-jar, or the legacy/mega smoke gates. |
Legacy 1.8.9 tree
1.8.9 is a separately-compiled tree of the same modules, not a second
codebase (docs/legacy-1.8.9-codeshare-design.md). The modern floor stays
1.17.1; the shipped StarEnchants-<ver>.jar is a Multi-Release jar carrying both
the modern v61 tree and this downgraded v52 tree, the JVM selecting one at load.
The overlay mechanism (ADR-0044 — seams, not same-FQN twins)
Each forking module keeps its shared, 1.8-safe logic in flat src/ and adds two
trees under se/<module>/overlay/{modern,legacy}/. The active one is added as a
main srcDir by -Pse.target (default modern):
sourceSets["main"].java.srcDir(if (legacy) "overlay/legacy" else "overlay/modern").
The unit of era variation is the seam, not the file — the same-FQN whole-file
swap of ADR-0036 is superseded (except the two bindings twins below):
- Seams (the norm). A version-specific capability is a seam interface in
src/ (Hands, ParticleFx, ItemStateStore, EquipSource, ActorProbe,
DropControl, Projectiles, VanillaStats, AnvilRename, …) with two
era-exclusive impls under era-unique FQNs (ModernHands/LegacyHands,
ModernDispatchSink/LegacyDispatchSink, ModernParticleFx/LegacyParticleFx,
PdcItemStateStore/NbtItemStateStore, …). Parity is a per-era javac fact
(implements), not a convention, and drift can't slip past the merge gate. The
impls are constructor-injected from the composition root — shared consumers
name only the interface, never an era class (the EraTreeGateTest G1-c check
enforces this).
- Shared base + era leaf stays valid where most of a class is era-neutral
(
engine.sink.DispatchSinkBase + ModernDispatchSink/LegacyDispatchSink;
feature.combat.EquipListener shared + the era armour-change feeders). The base
is in src/, so it lands in both class sets automatically.
- Asymmetric seams (one era works, the other stubs) are a shared default plus
one override:
VanillaStats.NONE / AnvilRename.UNSUPPORTED in src/, the real
ModernVanillaStats / ModernAnvilRename in overlay/modern.
- The ONLY same-FQN twins are the two composition-only bindings:
bootstrap.compat.EraBindings (implements the shared EraServices — the whole
era wiring manifest, absorbing the former Wiring/Bridges/Targets/Commands) and
platform.resolve.HandleLookups. Content rule (gated): construction and
one-line delegation only — no if/for/while/switch/try, no mutable fields.
Real per-era logic is extracted to era-exclusive classes (LegacyTargets,
LegacyEnchantResolver, LegacyGearPoll), NOT inlined into a binding.
- Must NOT diverge: everything else in
src/ — Sink, the kinds,
WornState/ItemView, the pure core. A same-FQN class lives in src/ or an
overlay, never both (a seam interface and its Modern*/Legacy* impls have
different names, so this holds).
-Pse.target=legacy → a disjoint buildDir
Legacy compiles redirect buildDir to build-legacy/ (root build.gradle.kts),
so the modern build/ jar is never clobbered and Gradle's incremental compiler
can't mix classes across the overlay swap. The merge (build-mega-jar.sh) reads
the modern jar from build/ and the downgraded legacy jar from build-legacy/
in any order. build-legacy/ is gitignored.
The language wall — JvmDowngrader + JDK 8
The base tree targets Java 8 (class v52) — a 1.8.x server runs only on JDK 8.
scripts/build-legacy-jar.sh compiles at 17 then lowers the assembled jar
61→52 with JvmDowngrader (pinned 1.3.6), shading its stdlib-API + util
runtime helpers under the se_jdg root so the jar is self-contained. Records,
sealed types, and switch-expressions lower cleanly; a JDG version bump is a gated
change requiring a fresh live smoke.
MRJAR soundness — a DERIVED gate (ADR-0044), not a hand allowlist
On a modern JVM the classloader serves META-INF/versions/17/ for any class
present there and the base (v52) copy otherwise. A class that exists in only
one era's tree, but is reachable from the other era's bytecode, would load
with the wrong-era signature → NoSuchMethodError. scripts/tools/MegaJarGate.java
(an ad-hoc-compiled ASM tool inside build-mega-jar.sh, like Jdk8ApiGate) proves
soundness derived from the tree, replacing the old hand
ALLOW_ERA_EXCLUSIVE(_PREFIX) allowlists:
- P1 era-exclusivity is derived from the overlay dirs (a class under exactly
one
overlay/<era>/ is legitimately one-era); a divergent class with no such
source fails.
- P2 a constant-pool walk asserts the modern jar references no legacy-exclusive
FQN and vice-versa (the jar-level restatement of the compile-time fact).
- P3 a legacy-excluded module (
:integrate) is derived from the module set, not
a hard-coded prefix.
- P4/P5 the two bindings twins (
EraBindings, HandleLookups, declared in
build-mega-jar.sh's SE_MEGA_BINDINGS) must be present in both trees, and the
base EraBindings must reference v1_8_R3 while its versions/17 copy must not
(the era-direction check, generalising the old Commands grep).
- P6 the non-class resource trees match by SHA-256.
The fast companion EraTreeGateTest runs in every ./gradlew build (G1-a twin
set = bindings; G1-b bindings composition-only; G1-c no src names an era class;
G1-d EraBindings implements EraServices), so a broken seam fails locally. The
tester is excluded by design: its era-specific suites live in src/ includes
(not overlay dirs), so P1 rejects it exactly as before — run-matrix.sh boots the
modern tester, legacy-smoke.sh the downgraded legacy tester, mega-smoke.sh
boot-smokes the shipped plugin on both eras.
The gates
| Gate | Script | Proves |
|---|
| Legacy compile (1 + 1b) | build-legacy-jar.sh (-Pse.target=legacy) | overlay and shared main link against the real Spigot 1.8.8 + v1_8_R3 jar — a 1.8-absent symbol is a javac error, not a runtime crash |
| JDK-8 API gate (2) | jdk8-api-gate.sh (embedded in build-legacy-jar.sh) | closed-world ASM scan of the downgraded v52 jar against a real JDK 8 baseline — an un-shimmable JDK-9+ java.*/javax.* reference fails here, not at runtime |
| Live legacy smoke (4) | legacy-smoke.sh | the downgraded tester boots on a real craftbukkit-1.8.8 under JDK 8 and the reduced in-server suite fresh-PASSes |
| Mega smoke | mega-smoke.sh | the merged mega-jar ENABLES on both eras (base v52 on 1.8, versions/17 v61 on Paper) with no wrong-era leak |
jdk8-api-gate.sh is the single chokepoint for the language wall, so it gates
every legacy-producing lane (legacy-smoke.sh on PR+push, build-mega-jar.sh on
release). SE_SKIP_JDK8_GATE=1 is a loud, local-only escape hatch.
Known traps
Material.CLOCK-class constants break the 1.8 compile. Flattening renamed
hundreds of Materials; a hard-referenced modern constant is absent on the 1.8
jar. Resolve by name through the resolver, never a compile-time constant.- Empty-hand NPE. 1.8
getItemInHand() on an empty hand can return null
(modern returns AIR); the LegacyActorProbe / LegacyHands impls must guard it.
- One legacy gear poll, not three. 1.8 has no
PlayerArmorChangeEvent /
PlayerItemDamageEvent, so equip-refresh, ITEM_DAMAGE, and heroic-durability are
all driven by the single feature.trigger.LegacyGearPoll (one repeating task, one
5-slot scan). Its fixed per-slot subscriber order is load-bearing — ITEM_DAMAGE
fires before any heroic restore, and the poll records the post-restore durability so
next tick sees no phantom delta. Do not re-split it into per-concern polls.
- Stale-jar selection.
build-legacy/libs can retain an old-version
-legacy.jar a bare find | head -1 would grab by directory order — a false
PASS on old code. The scripts pin the exact current-version filename.
ARCH_PREFIX under set -u. The Apple-Silicon arch -x86_64 prefix array
is often empty on x86/CI; expand it as ${ARCH_PREFIX[@]+"${ARCH_PREFIX[@]}"}
so bash 3.2 doesn't error on an unbound empty array.- Chance rolls must be injectable. JvmDowngrader makes
ThreadLocalRandom.nextDouble(double) unstubbable in the legacy smoke — the roll
must come from an injected supplier (the pipeline already reads act.chanceRoll()),
or every proc throws on the real 1.8 jar.
See paper-cross-version for the modern range, matrix-gate for the full gate,
and docs/legacy-1.8.9-codeshare-design.md for the derivation.
