15 KiB
JVM Downgrader integration handoff
Current state
The scoped integration is implemented on algent/java, building on baseline 65d0cd0. The three regression fixes
are preserved. build.gradle adds two tasks; StackAnalyserLogic.visitInsn uses the validated Java 21 pattern switch,
while JavaTraitRegistration and ClassInfoLookup use Java 21 pattern variables. The nine Scala sources, Scala 2.11.5
dependency, source layout, and normal Gradle entry points remain in place. Production tasks do not read a frozen jar
or any files under run/jvmdg-trial/.
The subsequent StackAnalyser initializer extraction is recorded in JAVA_MIGRATION_HANDOFF.md. The exact-byte
comparisons and frozen-version reproduction below describe checkpoint 5f0e329; later helper edits need their own
reference comparisons. The current extraction's evidence is in run/migration-stack-initialization-reference/.
Build arrangement
- Normal Java and joint Scala/Java compilation remain on Java 8.
compileScalaexcludes the modern helpers from javac's inputs, while scalac resolves their declarations through-sourcepath. This handles the circular Scala references without asking Java 8 javac to compile the modern method bodies. compileModernJavauses JDK 25 with--release 21, against the fresh Java and Scala output directories.downgradeModernJavaconverts the helpers to Java 8. Only the downgraded directory joins the main class outputs, so tests, Forge, dev/reobfuscated jars, and downstream compilation receive Java 8 bytecode.
The source-path declaration is an explicit Scala-task input. The existing scalaCompileOptions.force = true guard
remains to prevent stale joint-compiled Java annotations after generated Tags.VERSION changes.
The per-file include/exclude pairs are temporary compiler routing. These Java files still live in the Scala source set,
whose joint compiler would otherwise send them to Java 8 javac. Once the retained Scala/Java dependency cycle is gone,
move the modern cohort behind one source-set or directory boundary; once Scala is gone, compile all Java with the
modern toolchain and remove the exclusions, -sourcepath bridge and force guard together.
The bundled DowngradeFiles task initially declares outputs only for inputs that already exist during configuration.
outputs.dirs(outputMap.values()) explicitly declares the directory for clean builds. Raw and downgraded output use
separate directories and normal task dependencies. No stub sources or replacement Scala compiler are needed.
Modern Java policy and eligibility audit
The consumer-migration checkpoint should follow a bounded modernization pass. The supported runtime goal is the preferred Java 25 build (2.9.0 beta 3 also supports Java 17 through 26) plus the extended-support Java 8 build. Source modernization is for clearer, safer implementation code; the downgraded artifact remains Java 8 bytecode, so newer syntax alone is not a performance feature.
Use Java 21 as the source ceiling. JVM Downgrader 1.3.5 can accept Java 22 bytecode, but this build's validated
compileModernJava task uses --release 21, and Java 22 does not add enough here to justify moving the boundary.
Apply these rules:
- Prefer modern syntax in implementation bodies when it removes casts, duplicated branches or error-prone control flow. Do not rewrite working code solely for style.
- Keep public descriptors, generic signatures and Scala-facing declarations Java-8-shaped. In particular, do not put records, sealed declarations or modern JDK types on consumer or retained-Scala boundaries.
- Continue using Java 8 library APIs unless a newer API has a concrete benefit and its JVM Downgrader stub/shading and runtime-provider requirements are deliberately accepted and tested.
- Add source files to the modern task in small independently reviewable batches. Each batch must compare ABI, class inventory, generated ASM output and relevant behavior before accepting compiler-induced bytecode changes.
- Before marking the branch ready for consumer migration, verify all packaged classes are version 52, no unexpected JVM Downgrader API references exist, and run the JVM and Forge suites on Java 8 plus packaged smoke tests on the preferred modern runtime.
Eligibility result
A disposable clean-build experiment excluded all 224 Java files under src/main/scala from joint compilation and
compiled them together through the Java 21 task. All nine retained Scala sources resolved their declarations, all 224
Java sources compiled, JVM Downgrader completed, and packaging/checkstyle completed. This establishes broad technical
eligibility for Java 21 method bodies; it does not establish bytecode or behavior equivalence.
The experiment reached 575 passing tests out of 576. The remaining
MultipartMixinFactoryCharacterizationTest.namesAndFillsThePassThroughTrait check reported a missing standalone T
string constant after the newer javac/JVM Downgrader string-concatenation shape changed. That is exactly why moving all
sources at once is rejected: even source-identical classes can acquire observable bytecode differences that require
individual review. The normal production configuration remains unchanged.
Recommended order:
- Start with package-private helpers called directly by retained Scala.
JavaTraitRegistration.javaandClassInfoLookup.javaare completed follow-ups; pattern variables remove their checked casts without changing the Scala-facing declarations.StackAnalyserLogic.javaremains the original proven example. - Continue only where modern syntax produces a concrete control-flow gain.
ScalaSignatureParser.javais the next useful candidate because its two result-producing switches can become exhaustive switch expressions.ScalaTraitRegistration.javashould not move merely to restyle its erasedSomechecks. - Consider public core implementations such as
RedstoneInteractions$.java,TileMultipart.javaand the registries only after the internal batches. Modern method bodies are technically possible, but their published ABI and frozen behavior make the review cost higher. - Defer registered Java trait inputs under
scalatraits/. Their transformer forbids or rewrites several bytecode shapes, including inner classes, lambdas, string switches and primitive-array allocation; syntax changes need transformer-specific fixtures rather than ordinary compilation success. - Defer the six
src/main/javabootstrap/API sources and the separatesrc/mixin/javasource. They are not currently outputs ofdowngradeModernJava, and the simple API declarations have little modernization value. The mixin source needs an explicit downgraded-output arrangement before using post-Java-8 syntax. - Keep Scala companions,
$classcompatibility helpers and other descriptor-preservation facades conservative unless a specific method body warrants the compiler move. Their binary shape is more valuable than stylistic uniformity.
RenderPartResolver.java was initially shortlisted because it is new and package-private in practice, but an isolated
clean trial proved it cannot move alone: joint-compiled MultipartRenderer$.java calls it before the modern task runs.
Moving that caller pulls in the public renderer and client-proxy chain. Defer this group until source-layout cleanup can
move the dependency closure without turning one syntax improvement into a broad compiler migration.
The completed JavaTraitRegistration batch passes a clean build with all 576 JVM tests and the Java 8 Forge run with
all 289 functional tests. All 450 dev-jar classes remain version 52, the jar has no JVM Downgrader runtime API
references, and all 134 generated ASM dump names and hashes match the pre-change manifest. The helper is absent from
joint output and present only in the raw/downgraded modern directories. Its own class bytes changed as expected under
modern javac/JVM Downgrader, but no source signature or consumer-facing class is changed.
The completed ClassInfoLookup batch has the same clean-build, 576-test, Java 8 Forge, 450-class/version-52 and
134-dump results. Its source signatures and package-private visibility are unchanged. JVM Downgrader records nest
metadata as annotations for this helper's anonymous callbacks, but the packaged classes contain no executable JVM
Downgrader API reference and the Java 8 runtime needs no added dependency.
fastutil audit
GTNHLib 0.11.44 currently contributes it.unimi.dsi:fastutil:8.5.18 to compileClasspath. It does not contribute
fastutil to this project's declared runtimeClasspath, because GTNHLib is compileOnly. Using fastutil from ordinary
FMP code would therefore turn the optional GTNHLib relationship into an undeclared runtime requirement. Do not do that
implicitly; require GTNHLib/fastutil explicitly first if a measured core use justifies it.
The present candidates do not justify that change:
JInventoryTilecould replace its temporaryList<Integer>withIntArrayList, but slot lists are small, the code is a transformer-sensitive registered trait, and the dependency would cost more than the avoided boxing.MultiPartRegistry.nameMapandMicroMaterialRegistry.nameMapcould useObject2IntOpenHashMap, but they are small, lifecycle-built registries. Their missing-key behavior is also deliberately characterized. KeepHashMap.ControlKeyModifer.mapcould use a reference-to-boolean map, but it is publicly exposed as a liveMapand normally contains only the connected players. KeepHashMap.PacketScheduleris the only plausible future candidate for an object-to-long map because it accumulates masks and boxeslongvalues. Its collection is private, so a later implementation change can preserve the existing consumer ABI. Its Scala-map iteration and callback-mutation behavior are intentionally preserved. Defer this completely from the Java conversion project; revisit only as separately profiled optimization work with a dedicated semantic test and an explicit runtime dependency decision.TileCachecould only become primitive-keyed by replacingBlockCoordwith an encoded coordinate. Its live map is published and its recovery semantics are characterized, so that would be an API/behavior redesign rather than a fastutil substitution.
Fastutil remains appropriate for a future GTNHLib-gated implementation with a genuinely large or hot primitive collection, or after FMP deliberately makes it a direct runtime dependency. Its transitive compile availability alone is not sufficient, and fastutil adoption is out of scope for the Java conversion project.
Evidence
The actual production patch passes normal and clean builds with 398 freshly compiled JVM tests, 398 frozen JVM consumer tests, and 237 Java 8 Forge tests, with zero failures/errors/skips. Forge's nested build includes both new tasks. Spotless and checkstyle pass.
All 445 dev-jar classes remain version 52. With matching version metadata, only StackAnalyserLogic.class changes;
all retained Scala classes, ScalaSignature payloads, bridges, models, and other classes are byte-for-byte identical.
The helper itself exactly matches the isolated prototype. All 116 generated ASM dump names and hashes match.
The helper has no JVM Downgrader runtime-stub references, and no runtime dependency was added.
The release jar also contains 445 Java 8 classes, and the sources jar contains the exact modern helper source.
Evidence and runnable checks are under ignored run/jvmdg-trial/:
production-candidate.log,production-clean.log: actual build/Forge verification.final-normal-build.log: ordinary build and toolchain inventory without the frozen-version override.integrated-comparison.json,verify-integration.ps1: bytecode, packaging, dump, and test-count checks.frozen-consumers.gradle: tests using the original compiled JVM consumers.src/,reference/,artifacts/: original prototype, frozen baseline, and experiment jars.artifacts/integrated/,integrated-test-results/,integrated-forge-test-results/: preserved clean-build evidence.production-integration.patch: the production changes captured for review.initial-root-handoff.md: the original handoff before this takeover.
Limits
Prefer modern syntax where it improves readability and the compilation path supports it, as established by
5f0e329b. This can accompany consumer-facing API work without waiting for complete Scala removal. Expand the
scoped path selectively; if parsing, compilation order, ABI or downgrade support blocks a source unit, retain its
working syntax and record the blocker and revisit condition. Do not add fragile workarounds solely for syntax.
The production source tree now contains 231 Java files and nine Scala files / 782 nonblank Scala lines. Of the 224 Java
sources in the Scala source tree, only StackAnalyserLogic, JavaTraitRegistration and ClassInfoLookup bypass joint
compilation. Retained models, trait
metadata, synthetic super accessors, and downstream Scala consumers prevent treating the last nine files as a
mechanical deletion queue. Modern GTNH runtime support does not remove the retained Scala compiler's Java 8
requirement. The main migration plan and working handoff carry the current API/adoption priorities and source counts.
Keep enableModernJavaSyntax = false. The global GTNHGradle setting still moves Scala 2.11.5 onto Java 25; the new
helper stage selects its modern compiler explicitly. This supports modern method bodies with declarations that the
old Scala parser understands. Records, sealed declarations, modern API types at Scala boundaries, and references
from joint-compiled Java into the later modern stage need separate compatibility work before expanding the scope.
Modern APIs that downgrade to runtime stubs also require a deliberate runtime-provider decision.
At checkpoint 5f0e329b, the installed GTNHGradle 2.0.24 build classloader used JVM Downgrader engine/plugin 1.3.5.
The earlier 1.3.6 number identifies the API dependency configured by global mode, not the engine observed in that
build. The integrated helper's exact match with the original prototype confirmed that its transformation was preserved.
Reproduce
Normal commands require no init script or special property:
.\gradlew.bat --offline build
.\gradlew.bat --offline runFunctionalTestServer
For exact frozen-consumer comparison, use the original version string: two frozen tests inlined it. A branch-derived version otherwise fails those two version assertions. Do not change or recompile the frozen tests to conceal this.
$previousTrialVersion = $env:VERSION
try {
$env:VERSION = '1.7.12-git.225+65d0cd0090-dirty'
.\gradlew.bat --stop
.\gradlew.bat --offline -I run/jvmdg-trial/frozen-consumers.gradle clean build jvmdgIntegrationFrozenTest runFunctionalTestServer
.\run\jvmdg-trial\verify-integration.ps1
} finally {
$env:VERSION = $previousTrialVersion
}
sourcepath-probe.gradle and integration.gradle are historical investigation harnesses. The latter duplicates the
adopted task names and must not be loaded alongside the production integration. An init-script-only trial also does
not automatically reach runFunctionalTestServer's nested build; the production patch does.