mirror of
https://github.com/GTNewHorizons/ForgeMultipart.git
synced 2026-11-20 04:09:45 +00:00
docs: consolidate the migration documentation set
This commit is contained in:
1 parent
9f01653923
commit
94633dee92
14 files changed
+866
-1153
No files matched your search
+158
-60
@@ -41,8 +41,8 @@ side-only filtering are complete; multiple Scala-trait inheritance still needs i
|
||||
state/accessor/super bridges and the compiler/signature/analyser model shells.
|
||||
|
||||
Start with [JAVA_MIGRATION_HANDOFF.md](JAVA_MIGRATION_HANDOFF.md) for the exact source/test baseline, workflow and
|
||||
Java-source limitations. Read both the [ABI inventory](JAVA_MIGRATION_ABI_INVENTORY.md) and
|
||||
[consumer audit](JAVA_MIGRATION_CONSUMER_AUDIT.md) before changing compatibility surfaces. Completed-target evidence
|
||||
Java-source limitations. Read both the [ABI inventory](JAVA_MIGRATION_COMPATIBILITY.md) and
|
||||
[consumer audit](JAVA_MIGRATION_COMPATIBILITY.md) before changing compatibility surfaces. Completed-target evidence
|
||||
is in [the history](docs/migration/HISTORY.md); the [divergence ledger](JAVA_MIGRATION_DIVERGENCES.md) records only
|
||||
effective compatibility differences.
|
||||
|
||||
@@ -51,7 +51,7 @@ are in place. Schematica's private registry-map view is restored. The tile equal
|
||||
generated client-render dispatch crash are fixed; the user confirmed placement no longer crashes. Broader
|
||||
[manual client checks](JAVA_MIGRATION_MANUAL_CHECKS.md) and full-pack profiling remain release gates.
|
||||
|
||||
Focused traversal/redstone allocation improvements are recorded in [the profile](JAVA_MIGRATION_PROFILE.md).
|
||||
Focused traversal/redstone allocation improvements are recorded in [the profile](JAVA_MIGRATION.md#phase-4b--measured-performance-pass).
|
||||
GTNHLib/UniMixins remain conditional on concrete need. Removing Scala from FMP remains the final target, gated by
|
||||
released consumer migrations and retirement of FMP's own Scala-dependent implementation.
|
||||
|
||||
@@ -77,8 +77,8 @@ verify that the replacement has migrated the relevant FMP contracts before remov
|
||||
|
||||
GTNHLib/fastutil, UniMixins, a new generator design and further mechanical Scala-shell extraction are conditional
|
||||
work, not mandatory tasks to add without a concrete need. The existing generator is retained. See the detailed
|
||||
phases below, [consumer adoption ledger](JAVA_MIGRATION_CONSUMER_AUDIT.md#java-api-adoption-ledger),
|
||||
[manual checklist](JAVA_MIGRATION_MANUAL_CHECKS.md) and [performance protocol](JAVA_MIGRATION_PROFILE.md#broader-performance-pass-protocol-planned).
|
||||
phases below, [consumer adoption ledger](JAVA_MIGRATION_COMPATIBILITY.md#java-api-adoption-ledger),
|
||||
[manual checklist](JAVA_MIGRATION_MANUAL_CHECKS.md) and [performance protocol](JAVA_MIGRATION.md#phase-4b--measured-performance-pass).
|
||||
|
||||
## Scope and compatibility target
|
||||
|
||||
@@ -121,7 +121,8 @@ experiment. It replaced the instruction-type dispatch in `StackAnalyserLogic.vis
|
||||
switch. A JDK 25 task compiles the helper with `--release 21`; JVM Downgrader supplies Java 8 bytecode to tests,
|
||||
Forge and both packaged jars. Scala 2.11.5 and joint Scala/Java compilation stay on Java 8. The checkpoint passed
|
||||
normal/clean builds, frozen consumers and Forge tests with unchanged retained Scala classes and generated tile
|
||||
dumps. See [JVM_DOWNGRADER_HANDOFF.md](JVM_DOWNGRADER_HANDOFF.md) for the arrangement, evidence and limits.
|
||||
dumps. The arrangement, eligibility rules and limits are below; per-batch verification records are in
|
||||
[the history](docs/migration/HISTORY.md).
|
||||
|
||||
- Prefer clearer pattern matching, switch expressions and local type inference where supported and appropriate;
|
||||
retain explicit types or ordinary control flow when they communicate the intent better.
|
||||
@@ -141,6 +142,69 @@ For a new modern source unit or syntax feature, use the existing characterizatio
|
||||
the clean compilation path, packaged Java 8 output and relevant Forge behavior. This is a readability preference
|
||||
with a compatibility gate, not an obligation to modernize every file immediately.
|
||||
|
||||
#### Build arrangement
|
||||
|
||||
1. Normal Java and joint Scala/Java compilation remain on Java 8. `compileScala` excludes 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.
|
||||
2. `compileModernJava` uses JDK 25 with `--release 21`, against the fresh Java and Scala output directories.
|
||||
3. `downgradeModernJava` converts 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.
|
||||
|
||||
`build.gradle` keeps a single `modernJavaPaths` list that both selects the modern sources and excludes them from
|
||||
`compileScala`; do not reintroduce a second copy. An include without a matching exclude fails loudly at the Java 8
|
||||
joint compile, but an exclude without a matching include means the file is never compiled at all and nothing reports
|
||||
it. The `-sourcepath` declaration is an explicit Scala-task input, `scalaCompileOptions.force = true` prevents stale
|
||||
joint-compiled Java annotations after generated `Tags.VERSION` changes, and `outputs.dirs(outputMap.values())`
|
||||
declares the downgrade output for clean builds.
|
||||
|
||||
This per-file routing is temporary. 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 drop
|
||||
the exclusions, `-sourcepath` bridge and force guard together.
|
||||
|
||||
Use Java 21 as the source ceiling. The downgrader can accept Java 22 bytecode, but the validated task uses
|
||||
`--release 21` and Java 22 does not add enough here to justify moving the boundary.
|
||||
|
||||
#### Eligibility: what may move and what may not
|
||||
|
||||
A disposable experiment compiled all 224 Java files under `src/main/scala` through the Java 21 task. Everything
|
||||
compiled, downgraded and packaged, but one characterization test failed: a missing standalone `T` string constant
|
||||
after the newer javac changed its string-concatenation shape. That is why sources move in small reviewable batches
|
||||
rather than all at once. Even source-identical classes can acquire observable bytecode differences.
|
||||
|
||||
- Prefer package-private helpers called directly by retained Scala. The eight current members of the cohort are the
|
||||
proven shape: pattern variables and switch expressions that remove casts without touching Scala-facing declarations.
|
||||
- Rejected, and should stay rejected without a new reason: `RedstoneInteractions$` pulls its facade and then the
|
||||
transformer-sensitive registered `TRedstoneTile`; `BlockMultipart` immediately pulls its companion, cache, event
|
||||
handler, server proxy and renderer resolver; `RenderPartResolver` cannot move alone because joint-compiled
|
||||
`MultipartRenderer$` calls it before the modern task runs. Small cast cleanups do not justify widening the boundary.
|
||||
- Deferred: registered Java trait inputs under `scalatraits/`, whose transformer forbids or rewrites inner classes,
|
||||
lambdas, string switches and primitive-array allocation, so syntax changes need transformer-specific fixtures; the
|
||||
`src/main/java` bootstrap sources and `src/mixin/java`, which are not outputs of `downgradeModernJava`; and
|
||||
`PostMicroblockTraitLogic`, whose explicit `Microblock` cast is required because the retained Scala declaration does
|
||||
not expose `getShape()` through `PostMicroblock`.
|
||||
- Keep Scala companions, `$class` helpers and descriptor-preservation facades conservative. Their binary shape is
|
||||
worth more than stylistic uniformity. `ScalaTraitRegistration` should not move merely to restyle erased `Some` checks.
|
||||
|
||||
Each batch must compare ABI, class inventory, generated ASM output and relevant behavior. Before declaring the branch
|
||||
ready for consumer migration, verify every packaged class is version 52, that no unexpected downgrader API reference
|
||||
exists, and run the JVM and Forge suites on Java 8 plus packaged smoke tests on the preferred modern runtime.
|
||||
|
||||
#### fastutil
|
||||
|
||||
GTNHLib contributes `it.unimi.dsi:fastutil` to `compileClasspath` only, because GTNHLib is `compileOnly`. Using
|
||||
fastutil from ordinary FMP code would turn an optional relationship into an undeclared runtime requirement. Do not do
|
||||
that implicitly; require GTNHLib/fastutil explicitly first if a measured core use justifies it.
|
||||
|
||||
No current candidate justifies it. `JInventoryTile`'s slot lists are small and it is a transformer-sensitive
|
||||
registered trait; both registries' `nameMap`s are small lifecycle-built maps whose missing-key behavior is
|
||||
deliberately characterized; `ControlKeyModifer.map` is published as a live `Map`; and `TileCache` could only become
|
||||
primitive-keyed by replacing `BlockCoord`, which is an API redesign rather than a substitution. `PacketScheduler` is
|
||||
the one plausible future candidate because its private collection boxes `long` masks, so a later change can preserve
|
||||
the consumer ABI. Revisit it only as separately profiled work with a dedicated semantic test and an explicit runtime
|
||||
dependency decision. Fastutil adoption is out of scope for the Java conversion.
|
||||
|
||||
## Audit findings
|
||||
|
||||
### Codebase size
|
||||
@@ -194,7 +258,7 @@ The source and bytecode audit identified these allocation patterns; the named po
|
||||
The focused Forge/JFR baseline confirmed both risks. With eight parts, `updateEntity` and `operate` allocated about 184
|
||||
bytes per call, while a three-query redstone iteration allocated 80.5 bytes. The completed ports reduce the normal
|
||||
paths to effectively zero measured allocation; these remain focused measurements, not whole-pack TPS. See
|
||||
`JAVA_MIGRATION_PROFILE.md`.
|
||||
`JAVA_MIGRATION.md#phase-4b--measured-performance-pass`.
|
||||
|
||||
### Runtime code generation is architectural, not incidental
|
||||
|
||||
@@ -354,7 +418,7 @@ If a characterization test captures a confirmed bug that the port intentionally
|
||||
- [x] Produce and retain a reference dev jar from `f10595d` or the selected migration base.
|
||||
- [x] Dump the public/protected JVM API and important generated tile class shapes.
|
||||
- [x] Inventory downstream mods that compile against or reflect into ForgeMultipart. See
|
||||
`JAVA_MIGRATION_ABI_INVENTORY.md` and `JAVA_MIGRATION_CONSUMER_AUDIT.md`.
|
||||
`JAVA_MIGRATION_COMPATIBILITY.md`.
|
||||
- [x] Record source-level consumers of part IDs, NBT, packets, registration order, reflection, and lifecycle behavior.
|
||||
- [ ] Freeze representative part IDs, NBT trees, packet bytes, registration order, and lifecycle behavior as tests.
|
||||
- [x] Add a Java-8-compatible JUnit/Jupiter setup to the existing Gradle `test` task.
|
||||
@@ -362,7 +426,7 @@ If a characterization test captures a confirmed bug that the port intentionally
|
||||
- [x] Write the first characterization suite against the untouched Scala implementation.
|
||||
- [x] Create a remaining manual compatibility checklist for rendering, input, and other behavior that cannot be asserted reliably by the automated harness. See `JAVA_MIGRATION_MANUAL_CHECKS.md`.
|
||||
- [x] Capture representative CPU and allocation profiles before optimization work. See
|
||||
`JAVA_MIGRATION_PROFILE.md`.
|
||||
`JAVA_MIGRATION.md#phase-4b--measured-performance-pass`.
|
||||
- [x] Start a divergence log.
|
||||
|
||||
Exit condition: there is a reproducible behavior and ABI baseline, the test layers run in CI or an equivalent repeatable command, and the initial suite passes against the Scala implementation.
|
||||
@@ -394,49 +458,30 @@ Exit condition: new code can use a clean Java API while existing supported binar
|
||||
|
||||
### Phase 3 — Convert low-coupling code
|
||||
|
||||
- [x] Characterize each related leaf group before converting it.
|
||||
- [x] Convert the identified constants, value holders, simple utilities, registries, packet data helpers, and leaf
|
||||
classes.
|
||||
- [x] Replace `JavaConversions` in converted files with explicit Java collections or controlled adapters.
|
||||
- [x] Preserve iteration order and null behavior.
|
||||
- [x] Keep mixed Scala/Java compilation working throughout the phase.
|
||||
|
||||
Status: **complete.** The low-risk queue is empty. All eight load-bearing `$class` helpers are Java with their bridges
|
||||
retained, as are both registries, the central part/tile types, scheduler/helper utilities, `BlockMultipart`, and
|
||||
`MultipartRenderer`. Per-type evidence is retained in `docs/migration/HISTORY.md`; the handoff lists the remaining source units.
|
||||
|
||||
Exit condition: leaf code is Java and no longer generates avoidable Scala closures or collection adapters.
|
||||
retained, as are both registries, the central part/tile types, scheduler/helper utilities, `BlockMultipart` and
|
||||
`MultipartRenderer`. Each leaf group was characterized before conversion, `JavaConversions` was replaced with explicit
|
||||
Java collections or controlled adapters, and iteration order and null behavior were preserved throughout. Per-type
|
||||
evidence is in [the history](docs/migration/HISTORY.md).
|
||||
|
||||
### Immediate compatibility gate — complete
|
||||
|
||||
Do this before another source conversion:
|
||||
|
||||
- [x] Restore Schematica's reflective `MultiPartRegistry$` type-map view with its exact field name and Scala mutable-map
|
||||
shape, backed by the canonical Java registry state; add a regression test that performs Schematica's actual lookup.
|
||||
- [x] Add exact member-level guards for GuideNH's `BlockMicroMaterial.block/meta` mixin fields, Et Futurum's mutable
|
||||
`ButtonPart.metaSideMap/sideMetaMap`, Iguana's `ItemSaw.harvestLevel`, and Galacticraft's name-only
|
||||
`registerMaterial` lookup.
|
||||
- [x] Freeze `TileMultipart` order and lifecycle observations: `parts`/`id` NBT, `partList`/`jPartList`, `partMap`, slot
|
||||
rebinding, add/remove/replace callback order, moving the live tile, and `onMoved`.
|
||||
- [x] Add compact mixed-part NBT and description-packet fixtures. The existing torch/button parts provide the needed
|
||||
distinct IDs, order, slots and payload without adding downstream mods or a test-only part registry.
|
||||
- [x] Freeze one generated Scala trait, one Java trait, and representative pass-through interfaces before changing
|
||||
built-in tile traits or either generator.
|
||||
|
||||
Exit condition: every source-only constraint that can silently fail has an automated structural/behavioral guard,
|
||||
and the already-ported registry again supports Schematica.
|
||||
Status: **complete.** Every source-only constraint that can silently fail now has an automated structural or
|
||||
behavioral guard. Schematica's reflective `MultiPartRegistry$` type-map view is restored with its exact field name and
|
||||
Scala mutable-map shape over canonical Java state. Member-level guards cover GuideNH's `BlockMicroMaterial.block/meta`
|
||||
mixin fields, Et Futurum's mutable `ButtonPart.metaSideMap`/`sideMetaMap`, Iguana's `ItemSaw.harvestLevel` and
|
||||
Galacticraft's name-only `registerMaterial` lookup. `TileMultipart` order and lifecycle observations are frozen, as
|
||||
are compact mixed-part NBT/description-packet fixtures and one generated Scala trait, one Java trait and
|
||||
representative pass-through interfaces.
|
||||
|
||||
### Phase 4 — Convert measured hot paths
|
||||
|
||||
- [x] Characterize result ordering, callback timing, early exits, and edge cases before changing traversal code.
|
||||
- [x] Rewrite `TileMultipart` update/operate traversal without per-call collection allocation.
|
||||
- [x] Rewrite redstone queries without closure allocation or `IntRef` boxing.
|
||||
- [x] Replace non-local returns in recipe scans with ordinary Java control flow.
|
||||
- [x] Replace the remaining non-local return in the generated `TSlottedTile` slot scan.
|
||||
- [x] Keep fastutil out of these paths because profiling did not justify another dependency or data structure.
|
||||
- [x] Re-profile the same scenarios and record both improvements and regressions.
|
||||
Status: **complete for the measured targets.** Traversal, redstone queries, recipe scans and the generated
|
||||
`TSlottedTile` slot scan were characterized, then rewritten without per-call collection allocation, closure
|
||||
allocation, `IntRef` boxing or non-local returns, and re-profiled. Fastutil stayed out of these paths because
|
||||
profiling did not justify another dependency.
|
||||
|
||||
Status: complete for the measured targets. `operate` now preserves its captured-sequence mutation semantics without
|
||||
`operate` now preserves its captured-sequence mutation semantics without
|
||||
collection materialization,
|
||||
and the six-interface `IRedstonePart`/`RedstoneInteractions$` unit is ported with its class list and descriptors intact.
|
||||
The comparison proved its allocation was owned by the generated `TRedstoneTile`, which is now Java and allocation-free
|
||||
@@ -481,7 +526,7 @@ represents an observed consumer path. Use actual client/pack runs to validate us
|
||||
Preserve ordering, snapshots, callback/override behavior, packets, NBT and generated-extension compatibility. Do not
|
||||
remove Scala shells or weaken an API contract just to improve a benchmark.
|
||||
- [ ] Publish absolute and relative before/after results, run variability, unchanged controls and regressions using
|
||||
the [measurement protocol](JAVA_MIGRATION_PROFILE.md#broader-performance-pass-protocol-planned). Validate CPU wins
|
||||
the measurement protocol below. Validate CPU wins
|
||||
against allocation/GC, retained memory, startup and client/server tails rather than trading one cost silently for another.
|
||||
- [ ] Repeat the representative pack scenarios after integrating the changes and relevant consumer migrations.
|
||||
Retain only justified improvements; record below-noise results and rejected candidates without claiming a speedup.
|
||||
@@ -490,24 +535,77 @@ Exit condition: representative scenarios have repeatable before/after evidence,
|
||||
declared criteria without unresolved correctness or material performance regressions, and consumer migration benefits
|
||||
are separately demonstrated where present. There is no preset percentage target or promised whole-pack TPS gain.
|
||||
|
||||
#### Measurement protocol
|
||||
|
||||
A workload manifest must identify the world/seed or reproducible snapshot, pack and mod versions, FMP/consumer
|
||||
commits, hardware, exact JVM/flags/heap, view distance and graphics settings, part/tile/trait counts, and the action
|
||||
sequence or replay command. Restore equivalent world state before each run.
|
||||
|
||||
Use the pack's selected modern Java runtime for primary results; check the supported Java 8 artifact separately for
|
||||
behavior and regressions. Hold runtime and configuration fixed within every A/B comparison. Never attribute a JVM,
|
||||
renderer, pack-version or hardware change to the Java port.
|
||||
|
||||
Measure fresh-process startup and cold first-use/class generation separately from warmed steady-state play. Per
|
||||
variant, start with at least five independent runs, alternate baseline/candidate order, use identical warm-up and
|
||||
measurement windows, and extend runs when results are noisy. Keep profiling overhead matched, and confirm end-to-end
|
||||
timing without profiling when overhead is material. Preserve raw reports under a named ignored evidence directory
|
||||
rather than overwriting the only baseline.
|
||||
|
||||
Report median and variability across runs. Derive p95/p99 tick or frame times from enough samples within each run,
|
||||
not from five aggregate timings. Include absolute units and relative differences: CPU time, ms/tick, ms/frame,
|
||||
allocation bytes per operation or second, GC pause time, peak/retained heap, cold latency and network bytes where
|
||||
relevant. TPS alone can hide an improvement below the 50 ms tick budget. Separate CPU-bound and GPU-bound client
|
||||
scenes, and do not turn a helper microbenchmark ratio into an FPS/TPS claim.
|
||||
|
||||
Use two controlled comparisons: baseline versus optimized FMP with consumer code unchanged, then legacy versus
|
||||
migrated consumer calls on the same FMP artifact. Where compatible, also compare with the Scala reference release on
|
||||
the same runtime and inputs. Compare equivalent results/world state, packet/NBT fixtures and callback behavior, and
|
||||
explicitly exclude scenarios whose behavior cannot be matched.
|
||||
|
||||
Each accepted change records: hypothesis and targeted profile site; scenario/manifest and commands; before/after
|
||||
commits; raw evidence location; absolute/relative measurements with variability; correctness checks; controls,
|
||||
regressions and tradeoffs; and the acceptance decision. Define practical benefit above noise before editing. A
|
||||
below-noise result or a bottleneck outside FMP is a valid finding, not a reason to invent more optimization work.
|
||||
|
||||
#### Running the focused harness
|
||||
|
||||
The local server EULA must already contain `eula=true`. From PowerShell at the repository root:
|
||||
|
||||
```powershell
|
||||
.\gradlew.bat runFunctionalTestServer "-Pforgemultipart.profileFunctionalTests=true"
|
||||
```
|
||||
|
||||
The property is quoted because PowerShell otherwise splits the dotted Gradle property. Normal
|
||||
`runFunctionalTestServer` runs are unchanged. Profile mode overwrites these ignored files:
|
||||
|
||||
- `run/server/forgemultipart-profile.txt` — exact timings and per-thread allocation counts;
|
||||
- `run/server/forgemultipart-baseline.jfr` — JFR CPU, allocation-site and GC events.
|
||||
|
||||
```powershell
|
||||
jfr summary run/server/forgemultipart-baseline.jfr
|
||||
jfr view --width 220 hot-methods run/server/forgemultipart-baseline.jfr
|
||||
jfr view thread-allocation run/server/forgemultipart-baseline.jfr
|
||||
```
|
||||
|
||||
The `startEpochMillis` and `nanos` values in the text file define the exact time window for each phase. Java 8
|
||||
recordings expose TLAB allocation events rather than `ObjectAllocationSample`, so `jfr view allocation-by-site` from a
|
||||
recent JDK is not a valid summary of this recording.
|
||||
|
||||
The fixture uses Zulu OpenJDK 8, eight parts per tile, 1,000,000 warm-up iterations and 50,000,000 measured
|
||||
iterations per phase, covering `updateEntity`, `operate`, `lightValue`, `getTile` and `redstoneQueries`. The checksum
|
||||
consumes all observable work. Allocation bytes come from HotSpot's per-thread allocation counter, not from sampled
|
||||
JFR events; JFR remains the source for CPU samples and allocation-site ranking. Recorded results for the Phase 4
|
||||
focused baseline are in [the history](docs/migration/HISTORY.md).
|
||||
|
||||
### Phase 5 — Convert built-in tile traits through the existing Java path
|
||||
|
||||
- [x] Characterize the direct class shape, generated interface, super dispatch, behavior, and class caching of a
|
||||
no-field pilot.
|
||||
- [x] Port one simple built-in trait as a pilot using `registerJavaTrait`.
|
||||
- [x] Verify generated field accessors, initialization, copying, lifecycle callbacks, super bridges, and class caching
|
||||
on the stateful `TSlottedTile` checkpoint.
|
||||
- [x] Characterize ProjectRed/Extra Utilities redstone calls and port `TRedstoneTile` with an immediate paired profile.
|
||||
- [x] Convert remaining traits in small related groups.
|
||||
- [x] Document or deliberately relax the Java trait restrictions only when a real trait requires it.
|
||||
- [x] Preserve pass-through interface behavior.
|
||||
- [x] Keep the completed OpenComputers `TSlottedTile.v_partMap` mutation/rebinding case green and cover ProjectRed/
|
||||
Extra Utilities behavior before `TRedstoneTile`.
|
||||
- [x] Explicitly cover AE2's `TIInventoryTile.rebuildSlotMap` before the inventory trait.
|
||||
Status: **complete.** Traits were converted in small related groups behind characterization of the generated
|
||||
interface, super dispatch, field accessors, initialization, copying, lifecycle callbacks and class caching, starting
|
||||
from a no-field pilot and the stateful `TSlottedTile` checkpoint. Consumer behavior was covered before the risky
|
||||
ports: OpenComputers' `TSlottedTile.v_partMap` mutation/rebinding, ProjectRed and Extra Utilities redstone calls
|
||||
before `TRedstoneTile`, and AE2's `TIInventoryTile.rebuildSlotMap` before the inventory trait.
|
||||
|
||||
Exit condition: built-in behavior is implemented in Java while the established runtime composition mechanism remains stable.
|
||||
|
||||
Status: complete. All built-in tile traits are Java. The client pair required narrowly extending `registerJavaTrait`
|
||||
All built-in tile traits are Java. The client pair required narrowly extending `registerJavaTrait`
|
||||
for a registered Java trait extending another registered Java trait, explicit Java field accessors, and transient
|
||||
runtime-only fields that must not participate in generated `copyFrom`. The generated runtime interfaces and class
|
||||
cache remain reference-identical; pass-through-interface coverage remains green.
|
||||
|
||||
@@ -1,293 +0,0 @@
|
||||
# Downstream ABI inventory
|
||||
|
||||
For runtime behavior, data formats, lifecycle use, and member-level reflection found in consumer source, see
|
||||
[`JAVA_MIGRATION_CONSUMER_AUDIT.md`](JAVA_MIGRATION_CONSUMER_AUDIT.md).
|
||||
|
||||
Completes the Phase 0 item "Inventory downstream mods that compile against or reflect into ForgeMultipart".
|
||||
|
||||
Method: constant-pool scan of every mod jar in a real pack, not a source search. Bytecode is the only oracle that
|
||||
covers reflection strings, closed-source consumers, and mods whose published source does not match their release jar.
|
||||
GitHub code search was deliberately not used; it indexes default branches only and silently omits results.
|
||||
|
||||
Scanned: GTNH daily `2026-08-14+678`, 240 mod jars (`ForgeMultipart-1.7.12.jar` itself excluded).
|
||||
Reproduce with `tools/AbiScan.java`; frozen baseline in `src/test/fixtures/abi/gtnh-daily-678-consumers.txt`.
|
||||
|
||||
```
|
||||
java tools/AbiScan.java <instance>/.minecraft/mods ForgeMultipart
|
||||
```
|
||||
|
||||
Requires a JDK 17+ single-file source launch. Re-run at every public-API phase and diff against the frozen baseline;
|
||||
any member that disappears from the port but appears in the baseline is a linkage break in a shipping mod.
|
||||
|
||||
## Totals
|
||||
|
||||
| Category | Count |
|
||||
| --- | ---: |
|
||||
| Consumer jars | 27 of 240 |
|
||||
| Types extended or implemented downstream | 35 |
|
||||
| Referenced members with exact descriptors | 255 |
|
||||
| Other referenced types | 76 |
|
||||
| Reflective string constants | 20 |
|
||||
|
||||
## Consumers by weight
|
||||
|
||||
Ranked by number of classes in the jar that touch `codechicken/multipart` or `codechicken/microblock`.
|
||||
|
||||
| Classes | Jar |
|
||||
| ---: | --- |
|
||||
| 141 | ProjRed-4.12.41-GTNH |
|
||||
| 38 | extrautilities-1.2.12 |
|
||||
| 19 | OpenComputers-1.12.55-GTNH |
|
||||
| 18 | ProjectBlue-1.2.10-GTNH |
|
||||
| 7 | appliedenergistics2-rv3-beta-1032-GTNH |
|
||||
| 7 | buildcraft-compat-7.1.22 |
|
||||
| 5 | ForgeRelocationFMP-0.2.0 |
|
||||
| 4 | Galacticraft-3.4.33-GTNH, ThaumicTinkerer-2.12.29, WR-CBE-1.7.12, chisel-2.17.32-GTNH |
|
||||
| 3 | IguanaTweaksTConstruct-2.7.12, WitchingGadgets-1.8.49-GTNH, guidenh-1.3.20 |
|
||||
| 2 | BloodArsenal-1.5.12, Botania-1.13.33-GTNH, Waila-1.19.31, matter-manipulator-0.1.53-GTNH |
|
||||
| 1 | BiomesOPlenty, BloodMagic-1.9.12, Natura-2.8.23, Schematica-1.12.6-GTNH, TConstruct-1.14.97-GTNH, ae2fc-1.5.102-gtnh, endercore-0.5.14, etfuturum-2.6.52-GTNH, gregtech-5.09.54.88 |
|
||||
|
||||
Two distinct consumer shapes:
|
||||
|
||||
- **Java consumers** (extrautilities, AE2, chisel, WitchingGadgets, ThaumicTinkerer, buildcraft-compat, gregtech,
|
||||
matter-manipulator, and the long tail) use the Java-facing API: `MultiPartRegistry.registerParts(IPartFactory, String[])`,
|
||||
`registerConverter`, `BlockMicroMaterial`, `MicroMaterialRegistry.registerMaterial`, `TileMultipart.jPartList()`,
|
||||
`addPart`, `remPart`, `canAddPart`. None of these need Scala.
|
||||
- **Scala consumers** (ProjRed, OpenComputers, ProjectBlue, ForgeRelocationFMP) mix in ForgeMultipart traits and call
|
||||
the generated `$class` static helpers directly. These are the constraint on Scala removal.
|
||||
|
||||
## Answers to the plan's open decisions
|
||||
|
||||
### 1. Which existing downstream binaries must keep working without recompilation?
|
||||
|
||||
The 27 jars above. The compatibility budget is dominated by four: ProjRed, extrautilities, OpenComputers, ProjectBlue.
|
||||
ProjRed alone accounts for 141 of the touching classes and is the only consumer exercising the trait-generation path.
|
||||
|
||||
### 2. Are third-party Scala traits registered through `registerScalaTrait`?
|
||||
|
||||
**Yes.** Not internal-only. `ProjRed-4.12.41-GTNH.jar` calls
|
||||
`codechicken/microblock/MicroblockGenerator$.registerTrait(Ljava/lang/Class;)I` from
|
||||
`mrtjp.projectred.illumination.LightMicroMaterial$`, passing `mrtjp.projectred.illumination.LightMicroblock`.
|
||||
That class ships with a `LightMicroblock$class.class` helper and a `Scala` attribute, so
|
||||
`ASMMixinFactory.registerTrait` takes the `info.isTrait` branch into `registerScalaTrait` and parses its ScalaSignature.
|
||||
|
||||
Consequence: Phase 7 cannot drop `registerScalaTrait` or ScalaSignature decoding without breaking ProjRed's
|
||||
illuminated microblocks. The Java trait path can become the internal default, but the Scala path stays as a
|
||||
supported external extension point.
|
||||
|
||||
### 3. How long should deprecated Scala bridges remain supported?
|
||||
|
||||
Not answerable from this data alone, but the surface to support is now bounded and listed below. Of the 255 referenced
|
||||
members, only 5 carry Scala types in their descriptors.
|
||||
|
||||
### 4. Is complete Scala runtime removal required for the first Java release?
|
||||
|
||||
**No, and it is not achievable for the first release.** Four shipping mods link against Scala trait helpers and
|
||||
companion singletons. Java-maintainable source is the correct first milestone; Scala runtime removal requires either a
|
||||
coordinated rebuild of ProjRed, OpenComputers, ProjectBlue and ForgeRelocationFMP, or an accepted break.
|
||||
|
||||
## Load-bearing Scala surface
|
||||
|
||||
Everything in this section must keep its exact descriptor, or a named consumer fails to link.
|
||||
|
||||
### Trait `$class` helpers (8 classes, 16 static methods)
|
||||
|
||||
| Helper | Methods used | Consumers |
|
||||
| --- | --- | --- |
|
||||
| `TCuboidPart$class` | `$init$`, `drawBreaking`, `getCollisionBoxes`, `getSubParts` | ForgeRelocationFMP, OpenComputers, ProjRed, ProjectBlue |
|
||||
| `TIconHitEffects$class` | `$init$`, `addDestroyEffects`, `addHitEffects` | ForgeRelocationFMP, OpenComputers, ProjRed |
|
||||
| `TNormalOcclusion$class` | `$init$`, `occlusionTest` | ForgeRelocationFMP, OpenComputers, ProjRed |
|
||||
| `JIconHitEffects$class` | `$init$`, `getBreakingIcon` | ForgeRelocationFMP, OpenComputers, ProjRed |
|
||||
| `TFacePart$class` | `$init$`, `solid`, `redstoneConductionMap` | OpenComputers, ProjRed, ProjectBlue |
|
||||
| `TItemMultiPart$class` | `$init$`, `getHitDepth`, `onItemUse` | ProjRed |
|
||||
| `Saw$class` | `$init$`, `getMaxCuttingStrength` | ProjRed |
|
||||
| `TEdgePart$class` | `$init$` | OpenComputers |
|
||||
|
||||
The `JPartialOcclusion$class` bridge already added on this branch follows the right pattern, but note that
|
||||
`JPartialOcclusion$class` itself has **no** downstream caller in the pack — the two consumers that touch
|
||||
`JPartialOcclusion` (ForgeRelocationFMP, WitchingGadgets) only call `getPartialOcclusionBoxes()Ljava/lang/Iterable;`.
|
||||
The eight helpers above are the ones that actually matter.
|
||||
|
||||
### Companion object singletons (17 `MODULE$` fields read downstream)
|
||||
|
||||
`MultiPartRegistry$`, `TileMultipart$`, `MultipartGenerator$`, `NormalOcclusionTest$`, `RedstoneInteractions$`,
|
||||
`MicroMaterialRegistry$`, `MicroblockGenerator$`, `MicroblockRender$`, `BlockMicroMaterial$`, `ItemMicroPart$`,
|
||||
`CornerMicroClass$`, `EdgeMicroClass$`, `FaceMicroClass$`, `HollowMicroClass$`,
|
||||
`handler/MultipartProxy$`, `handler/MultipartSaveLoad$`, `handler/MicroblockProxy$`.
|
||||
|
||||
Each must keep a public static `MODULE$` field of its own type plus the instance methods used on it.
|
||||
|
||||
### Members with Scala types in their descriptors (5 total)
|
||||
|
||||
| Descriptor | Consumers |
|
||||
| --- | --- |
|
||||
| `TileMultipart.partList()Lscala/collection/Seq;` | OpenComputers, ProjRed, AE2, extrautilities, guidenh |
|
||||
| `NormalOcclusionTest$.apply(Lscala/collection/Traversable;Lscala/collection/Traversable;)Z` | ForgeRelocationFMP, OpenComputers |
|
||||
| `MultiPartRegistry$.registerParts(Lcodechicken/multipart/MultiPartRegistry$IPartFactory2;Lscala/collection/Seq;)V` | ProjRed |
|
||||
| `MultiPartRegistry$.registerParts(Lscala/Function2;Lscala/collection/Seq;)V` | ForgeRelocationFMP |
|
||||
| `MicroMaterialRegistry.getIdMap()[Lscala/Tuple2;` | extrautilities |
|
||||
|
||||
This is a much smaller surface than the plan assumed. `TileMultipart.jPartList()Ljava/util/List;` is already the more
|
||||
widely used accessor (ProjectBlue, WitchingGadgets, buildcraft-compat, extrautilities, gregtech, matter-manipulator),
|
||||
so the Java-first collection API mostly exists already and the Scala overloads are a thin retained shell.
|
||||
|
||||
The branch now supplies `NormalOcclusionTest.testBoxes(java.lang.Iterable, java.lang.Iterable)` for the box-list
|
||||
contract. Both old `apply(Traversable, Traversable)` entries remain, with deprecations pointing to the Java entry.
|
||||
The shipping ForgeRelocationFMP/OpenComputers companion calls still require their exact descriptor until adoption;
|
||||
see the [migration guide](docs/api/OCCLUSION.md#box-versus-box-queries) and consumer ledger.
|
||||
|
||||
`MultiPartRegistry.registerPartFactory(IPartFactory2, String...)` now provides the Java registration entry without
|
||||
Scala overload resolution. Both `registerParts(IPartFactory2, Seq)` entries are deprecated; all eight existing
|
||||
registration descriptors remain. ProjectRed's sequence and ForgeRelocationFMP's function companion calls still need
|
||||
their bridges until release/adoption. See the [registration guide](docs/api/PART_REGISTRATION.md).
|
||||
|
||||
`IDWriter`, ported on this branch, has **zero** downstream references. Its four deprecated Scala function accessors
|
||||
are not load-bearing and can be dropped.
|
||||
|
||||
## Reflective consumers
|
||||
|
||||
These fail at runtime, not at link time, so ABI tooling will not catch a break. 20 string constants across:
|
||||
|
||||
- `guidenh-1.3.20` — the broadest reflective consumer: `MultipartGenerator`/`MultipartGenerator$`,
|
||||
`MultipartHelper`/`MultipartHelper$`, `MultipartRenderer`/`MultipartRenderer$`, `TileMultipart`,
|
||||
`TileMultipartClient`, `MicroblockClient`, `Microblock`, `MicroblockClass`, `MicroblockGenerator$`,
|
||||
`BlockMicroMaterial`/`BlockMicroMaterial$`, `MicroMaterialRegistry`/`MicroMaterialRegistry$`, `BlockMultipart`.
|
||||
- `Schematica-1.12.6-GTNH` — `TileMultipart`, `TMultiPart`, `MultiPartRegistry$`, `MultipartGenerator$`, `MicroblockClass`.
|
||||
- `Galacticraft-3.4.33-GTNH` — `TileMultipart`, `MicroMaterialRegistry`, `BlockMicroMaterial`.
|
||||
- `Waila-1.19.31` — `BlockMultipart`.
|
||||
- `AE2`, `ae2fc` — `TileMultipart`.
|
||||
- `etfuturum-2.6.52-GTNH` — `codechicken.multipart.minecraft.ButtonPart`.
|
||||
|
||||
Note that both the class and its `$` companion are named in several cases, so renaming or removing a companion
|
||||
object breaks these even where no bytecode reference exists.
|
||||
|
||||
The branch now offers `MultiPartRegistry.getPartFactory(String): IPartFactory2` to replace Schematica's private
|
||||
registry-map reflection, with a [migration guide](docs/api/FACTORY_LOOKUP.md). Its old companion field retains the
|
||||
exact private Scala mutable-map shape and live backing; the public addition does not authorize removing that field
|
||||
before consumer release/adoption. Generator reflection and preview lifecycle remain separate contracts.
|
||||
|
||||
`ButtonPart.setOrientation(int, ForgeDirection): void` now replaces Et Futurum's four reflective array writes and
|
||||
keeps the two direction maps consistent; [guide](docs/api/BUTTON_ORIENTATIONS.md). The existing public mutable static
|
||||
`metaSideMap` and `sideMetaMap` fields retain their exact names, types and modifiers for old releases. Removing or
|
||||
narrowing them still waits for a migrated Et Futurum release, target-pack adoption and a fresh reflective-source scan.
|
||||
|
||||
`ItemSaw.setHarvestLevel(int): void` now replaces Iguana's private-field write; [guide](docs/api/SAW_STRENGTH.md).
|
||||
The existing private `harvestLevel: int` field remains for old releases and shares storage with the setter. It loses
|
||||
only `ACC_FINAL`, which makes the supported mutation explicit and keeps reflective writes working. Removal still
|
||||
waits for an Iguana release, target-pack adoption and a fresh scan.
|
||||
|
||||
## Consequences for the migration plan
|
||||
|
||||
1. Phase 8 (Scala runtime removal) should be reclassified as deferred, not scheduled. Decision 4 is answered.
|
||||
2. Phase 7 must keep `registerScalaTrait`. Add a functional test that registers a Scala trait through
|
||||
`MicroblockGenerator.registerTrait` to freeze the path ProjRed depends on.
|
||||
3. Bridge effort should be spent on the 8 `$class` helpers, 17 `MODULE$` singletons, and 5 Scala-typed descriptors
|
||||
listed above. Every other converted file can drop its Scala bridge after checking this inventory, as `IDWriter` can.
|
||||
4. Add the reflective names to the manual compatibility checklist; the automated ABI diff cannot see them.
|
||||
|
||||
## guidenh's reflective surface, from source
|
||||
|
||||
The constant-pool scan can see the names guidenh reflects on but not the members it looks up. This section is read
|
||||
from the checked-out source at `6137525`, in
|
||||
`src/main/java/com/hfstudio/guidenh/integration/forgemultipart/ForgeMultipartHelpers.java`. **None of this is visible
|
||||
to the ABI diff**; a break here is silent until a user opens a guide page.
|
||||
|
||||
The dispatch helper is `invokeStaticOrSingletonMethod(class, companion, method, args...)`. It tries a **static** method
|
||||
on the plain class first, and only on `INVOCATION_MISSING` falls back to reading `companion.MODULE$` and invoking the
|
||||
method on it. So for most entries the companion is a fallback. The exceptions below are the ones that matter.
|
||||
|
||||
| Owner | Member reflected on | Reached via |
|
||||
| --- | --- | --- |
|
||||
| `MultipartHelper` | `createTileFromNBT(World, NBTTagCompound)` | static; companion is fallback |
|
||||
| `MultipartRenderer` | `renderWorldBlock(IBlockAccess, int, int, int, Block, int, RenderBlocks)` | static; companion is fallback |
|
||||
| `MultipartGenerator` | `generateCompositeTile(TileEntity, scala.collection.Iterable, boolean)` | **companion only for the Scala descriptor**; new static Java-Iterable entry is additive |
|
||||
| `BlockMicroMaterial` | `register(material)`, plus a constructor of arity 2 `(Block, int)` or 1 `(Block)` | static; companion is fallback |
|
||||
| `MicroMaterialRegistry` | `getMaterial(int)` | static; companion is fallback |
|
||||
| `MicroblockGenerator$` | `create(MicroblockClass, int, boolean)` | GuideNH explicitly selects the companion, matched by exact parameter types; static Java replacement exists |
|
||||
| `TileMultipart` | `partList()`, `partList_$eq(scala.collection.Seq)`, `loadParts(...)`, `notifyTileChange()`, `markRender()` | instance |
|
||||
| `Microblock` | `microClass()`, `material()`, `shape()` | instance |
|
||||
| `TMultiPart` | `getDrops()` | instance |
|
||||
| `BlockMicroMaterial` | `block()`, `meta()` | instance; absent from general `IMicroMaterial` |
|
||||
|
||||
Types used only for `isInstanceOf`: `BlockMultipart`, `TileMultipart`, `TileMultipartClient`, `Microblock`,
|
||||
`MicroblockClient`, `BlockMicroMaterial`.
|
||||
|
||||
### Three constraints this adds
|
||||
|
||||
1. **`MultipartGenerator$.MODULE$` is load-bearing through reflection.** `generateCompositeTile` is `private[multipart]`
|
||||
in Scala, so no static forwarder is emitted on `MultipartGenerator` and guidenh's static attempt always misses. It
|
||||
reaches the method only through the companion. A Phase 6/7 port that keeps the class but drops the companion, or
|
||||
promotes the method to a public static and removes it from the companion, breaks guidenh silently.
|
||||
|
||||
The branch now adds `MultipartGenerator.generateCompositeTile(TileEntity, java.lang.Iterable, boolean)` while
|
||||
retaining the exact companion Scala descriptor/body. GuideNH's old Scala sequence is not assignable to the new
|
||||
Java parameter, so its existing matcher still falls back to the companion. Both old and new reflective contracts
|
||||
are tested; migration requires a Java parts collection. See the [guide](docs/api/COMPOSITE_GENERATION.md).
|
||||
|
||||
2. **`MicroblockGenerator$.create` is matched by exact parameter types**, including `pts[0].getName()` string-compared
|
||||
against `"codechicken.microblock.MicroblockClass"`. That pins `create(MicroblockClass, int, boolean)` on the
|
||||
companion and pins `MicroblockClass`'s fully qualified name. Widening a parameter or renaming the class breaks the
|
||||
lookup even though every call site still links.
|
||||
|
||||
The existing static `MicroblockGenerator.create(MicroblockClass, int, boolean)` now has a
|
||||
[guide and compiling example](docs/api/MICROBLOCK_CREATION.md). Both exact reflective entries are tested; no API
|
||||
shape or production method body changes were needed. GuideNH must change its explicitly selected owner and receiver
|
||||
before it stops using the companion. Release/adoption, shape-setter override checks and client previews remain gates.
|
||||
|
||||
3. **`TileMultipart.partList_$eq(scala.collection.Seq)` is reflectively load-bearing.** The branch now supplies
|
||||
`setPartList(java.util.List)` and `loadPartList(java.util.Collection)`, while retaining the exact legacy setter and
|
||||
loader descriptors and override dispatch. Dropping the old setter in favor of the Java method would still break
|
||||
guidenh invisibly. Exact and assignability-based reflective tests cover both legacy contracts. `resolvePartList` also falls back to a public *field*
|
||||
named `partList`, which never existed — Scala emits the field private — so that path is dead in the reference too.
|
||||
|
||||
`MultipartHelper$` is retained on the strength of the fallback path alone: the static is found first today, so the
|
||||
companion is never reached in practice. That is a weaker justification than the two "companion only" entries above,
|
||||
but the cost of keeping a four-method forwarder is negligible against a silent break.
|
||||
|
||||
GuideNH's private `BlockMicroMaterial.block: Block` and `meta: int` fields remain unchanged for its accessor mixin.
|
||||
Existing public virtual `block()` / `meta()` now have a [typed query guide](docs/api/MATERIAL_ACCESS.md) and regression
|
||||
coverage; no descriptor or method body changed. The mixin reads constructor fields whereas direct calls honor
|
||||
subclass overrides, as the old reflective fallback already did. Remove the consumer's mixin only when adopting the
|
||||
typed query; FMP field removal still waits for released-consumer adoption.
|
||||
|
||||
### Documented internal boundary (2026-09-05)
|
||||
|
||||
The [Phase 9.2 audit](JAVA_MIGRATION_CONSUMER_AUDIT.md#api-boundary-audit) marks 15 zero-observed-caller tile/material
|
||||
hooks and five registry companion bridges as internal in Javadocs. All binary shapes and behavior remain unchanged;
|
||||
this does not authorize removing or narrowing these members. The shipped `TileMultipart.bindPart(TMultiPart): void`
|
||||
and `internalPartChange(TMultiPart): void` calls remain supported and are documented in the API guide, as are existing
|
||||
legacy override contracts. The registry's internal `loadIcons()` dispatcher is distinct from its supported material
|
||||
interface callback. The `+719` rescan retains all 386 member/type/reflection rows across the same 27 consumers.
|
||||
|
||||
### Java illuminated extension example
|
||||
|
||||
`MicroblockGenerator.registerTrait(String)` now documents its existing Java input path and pre-loading constraint.
|
||||
The [three-file example](docs/api/MICROBLOCK_EXTENSIONS.md) uses typed FMP entry points, with no additions or changes
|
||||
to the production API. ProjectRed still ships its external Scala trait; the Java example does not authorize retiring
|
||||
its old class/helper contracts or signature ingestion. Consumer release, pack adoption and internal dependency gates
|
||||
remain in force. The example itself lives only in the functional-test source set.
|
||||
|
||||
### Java block converter guidance
|
||||
|
||||
`IPartConverter`, `registerConverter`, `convertBlock`, `invalidateConvertedTile` and `onConverted` now document their
|
||||
existing ownership and lifecycle behavior; [guide](docs/api/BLOCK_CONVERTERS.md). All static/companion descriptors,
|
||||
production method bodies and ScalaSignature payloads remain unchanged. The compiling example is functional-test
|
||||
content only. Existing converter consumers need no API rename; their factory migration and adoption gates remain.
|
||||
|
||||
### Stable Java tile capability access
|
||||
|
||||
The [guide](docs/api/TILE_TRAIT_ACCESS.md) provides ProjectRed's `TRedstoneTile.openConnections` source migration to
|
||||
existing `IRedstoneTile.openConnections`. Legacy descriptors remain and interface calls still link. The dev jar's raw
|
||||
trait classes are not safe replacements for original compile-time interfaces: executable javac fixtures demonstrate
|
||||
class-call and field-read linkage failures. Additive `TileMultipart.refreshPartSlots(TMultiPart): void`, with the
|
||||
generated `TSlottedTile` override of the same descriptor, replaces OpenComputers' live-array mutation for source
|
||||
rebuilds. Keep the old `TSlottedTile.v_partMap()` accessor until released consumer and target-pack adoption.
|
||||
|
||||
### Custom Java tile-trait authoring
|
||||
|
||||
`MultipartGenerator.registerTrait(String, String)` and its side-specific overload now document their existing Java
|
||||
trait path, registration timing and first-mapping behavior. The [four-type example](docs/api/CUSTOM_TILE_TRAITS.md)
|
||||
separates the part marker, stable consumer capability, transformed input and access helper, and runs through actual
|
||||
server/client composite generation. This adds no production class, method, descriptor or behavior. The example remains
|
||||
functional-test content. No supplied consumer directly registers a custom multipart tile trait; existing pass-through
|
||||
and external Scala-trait contracts remain supported and their release/adoption gates are unchanged.
|
||||
@@ -1,11 +1,269 @@
|
||||
# Source-level downstream consumer audit
|
||||
# Downstream compatibility: ABI inventory and consumer audit
|
||||
|
||||
Status: 2026-09-09. This is the source-level companion to
|
||||
[`JAVA_MIGRATION_ABI_INVENTORY.md`](JAVA_MIGRATION_ABI_INVENTORY.md).
|
||||
Status: 2026-09-09. Read this before changing any compatibility surface. It has two parts, answering two different
|
||||
questions.
|
||||
|
||||
- **Part 1, the ABI inventory**, answers "what must still link?" It is a constant-pool scan of every mod jar in a
|
||||
real pack, not a source search.
|
||||
- **Part 2, the consumer audit**, answers the harder question: "what behavior do real consumers expect after they
|
||||
have linked?" It covers all 27 ForgeMultipart consumers in the supplied GTNH daily `2026-08-25+700` instance, plus
|
||||
UtilitiesInExcess as the planned Extra Utilities replacement.
|
||||
|
||||
Intentional differences from the reference belong in the [divergence ledger](JAVA_MIGRATION_DIVERGENCES.md), and the
|
||||
consumer-facing summary of what breaks on rebuild is in the [release notes](docs/RELEASE_NOTES.md).
|
||||
|
||||
# Part 1 - Downstream ABI inventory
|
||||
|
||||
Completes the Phase 0 item "Inventory downstream mods that compile against or reflect into ForgeMultipart".
|
||||
|
||||
Method: constant-pool scan of every mod jar in a real pack, not a source search. Bytecode is the only oracle that
|
||||
covers reflection strings, closed-source consumers, and mods whose published source does not match their release jar.
|
||||
GitHub code search was deliberately not used; it indexes default branches only and silently omits results.
|
||||
|
||||
Scanned: GTNH daily `2026-08-14+678`, 240 mod jars (`ForgeMultipart-1.7.12.jar` itself excluded).
|
||||
Reproduce with `tools/AbiScan.java`; frozen baseline in `src/test/fixtures/abi/gtnh-daily-678-consumers.txt`.
|
||||
|
||||
```
|
||||
java tools/AbiScan.java <instance>/.minecraft/mods ForgeMultipart
|
||||
```
|
||||
|
||||
Requires a JDK 17+ single-file source launch. Re-run at every public-API phase and diff against the frozen baseline;
|
||||
any member that disappears from the port but appears in the baseline is a linkage break in a shipping mod.
|
||||
|
||||
## Totals
|
||||
|
||||
| Category | Count |
|
||||
| --- | ---: |
|
||||
| Consumer jars | 27 of 240 |
|
||||
| Types extended or implemented downstream | 35 |
|
||||
| Referenced members with exact descriptors | 255 |
|
||||
| Other referenced types | 76 |
|
||||
| Reflective string constants | 20 |
|
||||
|
||||
## Consumers by weight
|
||||
|
||||
Ranked by number of classes in the jar that touch `codechicken/multipart` or `codechicken/microblock`.
|
||||
|
||||
| Classes | Jar |
|
||||
| ---: | --- |
|
||||
| 141 | ProjRed-4.12.41-GTNH |
|
||||
| 38 | extrautilities-1.2.12 |
|
||||
| 19 | OpenComputers-1.12.55-GTNH |
|
||||
| 18 | ProjectBlue-1.2.10-GTNH |
|
||||
| 7 | appliedenergistics2-rv3-beta-1032-GTNH |
|
||||
| 7 | buildcraft-compat-7.1.22 |
|
||||
| 5 | ForgeRelocationFMP-0.2.0 |
|
||||
| 4 | Galacticraft-3.4.33-GTNH, ThaumicTinkerer-2.12.29, WR-CBE-1.7.12, chisel-2.17.32-GTNH |
|
||||
| 3 | IguanaTweaksTConstruct-2.7.12, WitchingGadgets-1.8.49-GTNH, guidenh-1.3.20 |
|
||||
| 2 | BloodArsenal-1.5.12, Botania-1.13.33-GTNH, Waila-1.19.31, matter-manipulator-0.1.53-GTNH |
|
||||
| 1 | BiomesOPlenty, BloodMagic-1.9.12, Natura-2.8.23, Schematica-1.12.6-GTNH, TConstruct-1.14.97-GTNH, ae2fc-1.5.102-gtnh, endercore-0.5.14, etfuturum-2.6.52-GTNH, gregtech-5.09.54.88 |
|
||||
|
||||
Two distinct consumer shapes:
|
||||
|
||||
- **Java consumers** (extrautilities, AE2, chisel, WitchingGadgets, ThaumicTinkerer, buildcraft-compat, gregtech,
|
||||
matter-manipulator, and the long tail) use the Java-facing API: `MultiPartRegistry.registerParts(IPartFactory, String[])`,
|
||||
`registerConverter`, `BlockMicroMaterial`, `MicroMaterialRegistry.registerMaterial`, `TileMultipart.jPartList()`,
|
||||
`addPart`, `remPart`, `canAddPart`. None of these need Scala.
|
||||
- **Scala consumers** (ProjRed, OpenComputers, ProjectBlue, ForgeRelocationFMP) mix in ForgeMultipart traits and call
|
||||
the generated `$class` static helpers directly. These are the constraint on Scala removal.
|
||||
|
||||
## Answers to the plan's open decisions
|
||||
|
||||
### 1. Which existing downstream binaries must keep working without recompilation?
|
||||
|
||||
The 27 jars above. The compatibility budget is dominated by four: ProjRed, extrautilities, OpenComputers, ProjectBlue.
|
||||
ProjRed alone accounts for 141 of the touching classes and is the only consumer exercising the trait-generation path.
|
||||
|
||||
### 2. Are third-party Scala traits registered through `registerScalaTrait`?
|
||||
|
||||
**Yes.** Not internal-only. `ProjRed-4.12.41-GTNH.jar` calls
|
||||
`codechicken/microblock/MicroblockGenerator$.registerTrait(Ljava/lang/Class;)I` from
|
||||
`mrtjp.projectred.illumination.LightMicroMaterial$`, passing `mrtjp.projectred.illumination.LightMicroblock`.
|
||||
That class ships with a `LightMicroblock$class.class` helper and a `Scala` attribute, so
|
||||
`ASMMixinFactory.registerTrait` takes the `info.isTrait` branch into `registerScalaTrait` and parses its ScalaSignature.
|
||||
|
||||
Consequence: Phase 7 cannot drop `registerScalaTrait` or ScalaSignature decoding without breaking ProjRed's
|
||||
illuminated microblocks. The Java trait path can become the internal default, but the Scala path stays as a
|
||||
supported external extension point.
|
||||
|
||||
### 3. How long should deprecated Scala bridges remain supported?
|
||||
|
||||
Not answerable from this data alone, but the surface to support is now bounded and listed below. Of the 255 referenced
|
||||
members, only 5 carry Scala types in their descriptors.
|
||||
|
||||
### 4. Is complete Scala runtime removal required for the first Java release?
|
||||
|
||||
**No, and it is not achievable for the first release.** Four shipping mods link against Scala trait helpers and
|
||||
companion singletons. Java-maintainable source is the correct first milestone; Scala runtime removal requires either a
|
||||
coordinated rebuild of ProjRed, OpenComputers, ProjectBlue and ForgeRelocationFMP, or an accepted break.
|
||||
|
||||
## Load-bearing Scala surface
|
||||
|
||||
Everything in this section must keep its exact descriptor, or a named consumer fails to link.
|
||||
|
||||
### Trait `$class` helpers (8 classes, 16 static methods)
|
||||
|
||||
| Helper | Methods used | Consumers |
|
||||
| --- | --- | --- |
|
||||
| `TCuboidPart$class` | `$init$`, `drawBreaking`, `getCollisionBoxes`, `getSubParts` | ForgeRelocationFMP, OpenComputers, ProjRed, ProjectBlue |
|
||||
| `TIconHitEffects$class` | `$init$`, `addDestroyEffects`, `addHitEffects` | ForgeRelocationFMP, OpenComputers, ProjRed |
|
||||
| `TNormalOcclusion$class` | `$init$`, `occlusionTest` | ForgeRelocationFMP, OpenComputers, ProjRed |
|
||||
| `JIconHitEffects$class` | `$init$`, `getBreakingIcon` | ForgeRelocationFMP, OpenComputers, ProjRed |
|
||||
| `TFacePart$class` | `$init$`, `solid`, `redstoneConductionMap` | OpenComputers, ProjRed, ProjectBlue |
|
||||
| `TItemMultiPart$class` | `$init$`, `getHitDepth`, `onItemUse` | ProjRed |
|
||||
| `Saw$class` | `$init$`, `getMaxCuttingStrength` | ProjRed |
|
||||
| `TEdgePart$class` | `$init$` | OpenComputers |
|
||||
|
||||
The `JPartialOcclusion$class` bridge already added on this branch follows the right pattern, but note that
|
||||
`JPartialOcclusion$class` itself has **no** downstream caller in the pack — the two consumers that touch
|
||||
`JPartialOcclusion` (ForgeRelocationFMP, WitchingGadgets) only call `getPartialOcclusionBoxes()Ljava/lang/Iterable;`.
|
||||
The eight helpers above are the ones that actually matter.
|
||||
|
||||
### Companion object singletons (17 `MODULE$` fields read downstream)
|
||||
|
||||
`MultiPartRegistry$`, `TileMultipart$`, `MultipartGenerator$`, `NormalOcclusionTest$`, `RedstoneInteractions$`,
|
||||
`MicroMaterialRegistry$`, `MicroblockGenerator$`, `MicroblockRender$`, `BlockMicroMaterial$`, `ItemMicroPart$`,
|
||||
`CornerMicroClass$`, `EdgeMicroClass$`, `FaceMicroClass$`, `HollowMicroClass$`,
|
||||
`handler/MultipartProxy$`, `handler/MultipartSaveLoad$`, `handler/MicroblockProxy$`.
|
||||
|
||||
Each must keep a public static `MODULE$` field of its own type plus the instance methods used on it.
|
||||
|
||||
### Members with Scala types in their descriptors (5 total)
|
||||
|
||||
| Descriptor | Consumers |
|
||||
| --- | --- |
|
||||
| `TileMultipart.partList()Lscala/collection/Seq;` | OpenComputers, ProjRed, AE2, extrautilities, guidenh |
|
||||
| `NormalOcclusionTest$.apply(Lscala/collection/Traversable;Lscala/collection/Traversable;)Z` | ForgeRelocationFMP, OpenComputers |
|
||||
| `MultiPartRegistry$.registerParts(Lcodechicken/multipart/MultiPartRegistry$IPartFactory2;Lscala/collection/Seq;)V` | ProjRed |
|
||||
| `MultiPartRegistry$.registerParts(Lscala/Function2;Lscala/collection/Seq;)V` | ForgeRelocationFMP |
|
||||
| `MicroMaterialRegistry.getIdMap()[Lscala/Tuple2;` | extrautilities |
|
||||
|
||||
This is a much smaller surface than the plan assumed. `TileMultipart.jPartList()Ljava/util/List;` is already the more
|
||||
widely used accessor (ProjectBlue, WitchingGadgets, buildcraft-compat, extrautilities, gregtech, matter-manipulator),
|
||||
so the Java-first collection API mostly exists already and the Scala overloads are a thin retained shell.
|
||||
|
||||
The branch now supplies `NormalOcclusionTest.testBoxes(java.lang.Iterable, java.lang.Iterable)` for the box-list
|
||||
contract. Both old `apply(Traversable, Traversable)` entries remain, with deprecations pointing to the Java entry.
|
||||
The shipping ForgeRelocationFMP/OpenComputers companion calls still require their exact descriptor until adoption;
|
||||
see the [migration guide](docs/api/OCCLUSION.md#box-versus-box-queries) and consumer ledger.
|
||||
|
||||
`MultiPartRegistry.registerPartFactory(IPartFactory2, String...)` now provides the Java registration entry without
|
||||
Scala overload resolution. Both `registerParts(IPartFactory2, Seq)` entries are deprecated; all eight existing
|
||||
registration descriptors remain. ProjectRed's sequence and ForgeRelocationFMP's function companion calls still need
|
||||
their bridges until release/adoption. See the [registration guide](docs/api/PART_REGISTRATION.md).
|
||||
|
||||
`IDWriter`, ported on this branch, has **zero** downstream references. Its four deprecated Scala function accessors
|
||||
are not load-bearing and can be dropped.
|
||||
|
||||
## Reflective consumers
|
||||
|
||||
These fail at runtime, not at link time, so ABI tooling will not catch a break. 20 string constants across:
|
||||
|
||||
- `guidenh-1.3.20` — the broadest reflective consumer: `MultipartGenerator`/`MultipartGenerator$`,
|
||||
`MultipartHelper`/`MultipartHelper$`, `MultipartRenderer`/`MultipartRenderer$`, `TileMultipart`,
|
||||
`TileMultipartClient`, `MicroblockClient`, `Microblock`, `MicroblockClass`, `MicroblockGenerator$`,
|
||||
`BlockMicroMaterial`/`BlockMicroMaterial$`, `MicroMaterialRegistry`/`MicroMaterialRegistry$`, `BlockMultipart`.
|
||||
- `Schematica-1.12.6-GTNH` — `TileMultipart`, `TMultiPart`, `MultiPartRegistry$`, `MultipartGenerator$`, `MicroblockClass`.
|
||||
- `Galacticraft-3.4.33-GTNH` — `TileMultipart`, `MicroMaterialRegistry`, `BlockMicroMaterial`.
|
||||
- `Waila-1.19.31` — `BlockMultipart`.
|
||||
- `AE2`, `ae2fc` — `TileMultipart`.
|
||||
- `etfuturum-2.6.52-GTNH` — `codechicken.multipart.minecraft.ButtonPart`.
|
||||
|
||||
Note that both the class and its `$` companion are named in several cases, so renaming or removing a companion
|
||||
object breaks these even where no bytecode reference exists.
|
||||
|
||||
The branch now offers `MultiPartRegistry.getPartFactory(String): IPartFactory2` to replace Schematica's private
|
||||
registry-map reflection, with a [migration guide](docs/api/FACTORY_LOOKUP.md). Its old companion field retains the
|
||||
exact private Scala mutable-map shape and live backing; the public addition does not authorize removing that field
|
||||
before consumer release/adoption. Generator reflection and preview lifecycle remain separate contracts.
|
||||
|
||||
`ButtonPart.setOrientation(int, ForgeDirection): void` now replaces Et Futurum's four reflective array writes and
|
||||
keeps the two direction maps consistent; [guide](docs/api/BUTTON_ORIENTATIONS.md). The existing public mutable static
|
||||
`metaSideMap` and `sideMetaMap` fields retain their exact names, types and modifiers for old releases. Removing or
|
||||
narrowing them still waits for a migrated Et Futurum release, target-pack adoption and a fresh reflective-source scan.
|
||||
|
||||
`ItemSaw.setHarvestLevel(int): void` now replaces Iguana's private-field write; [guide](docs/api/SAW_STRENGTH.md).
|
||||
The existing private `harvestLevel: int` field remains for old releases and shares storage with the setter. It loses
|
||||
only `ACC_FINAL`, which makes the supported mutation explicit and keeps reflective writes working. Removal still
|
||||
waits for an Iguana release, target-pack adoption and a fresh scan.
|
||||
|
||||
## Consequences for the migration plan
|
||||
|
||||
1. Phase 8 (Scala runtime removal) should be reclassified as deferred, not scheduled. Decision 4 is answered.
|
||||
2. Phase 7 must keep `registerScalaTrait`. Add a functional test that registers a Scala trait through
|
||||
`MicroblockGenerator.registerTrait` to freeze the path ProjRed depends on.
|
||||
3. Bridge effort should be spent on the 8 `$class` helpers, 17 `MODULE$` singletons, and 5 Scala-typed descriptors
|
||||
listed above. Every other converted file can drop its Scala bridge after checking this inventory, as `IDWriter` can.
|
||||
4. Add the reflective names to the manual compatibility checklist; the automated ABI diff cannot see them.
|
||||
|
||||
## guidenh's reflective surface, from source
|
||||
|
||||
The constant-pool scan can see the names guidenh reflects on but not the members it looks up. This section is read
|
||||
from the checked-out source at `6137525`, in
|
||||
`src/main/java/com/hfstudio/guidenh/integration/forgemultipart/ForgeMultipartHelpers.java`. **None of this is visible
|
||||
to the ABI diff**; a break here is silent until a user opens a guide page.
|
||||
|
||||
The dispatch helper is `invokeStaticOrSingletonMethod(class, companion, method, args...)`. It tries a **static** method
|
||||
on the plain class first, and only on `INVOCATION_MISSING` falls back to reading `companion.MODULE$` and invoking the
|
||||
method on it. So for most entries the companion is a fallback. The exceptions below are the ones that matter.
|
||||
|
||||
| Owner | Member reflected on | Reached via |
|
||||
| --- | --- | --- |
|
||||
| `MultipartHelper` | `createTileFromNBT(World, NBTTagCompound)` | static; companion is fallback |
|
||||
| `MultipartRenderer` | `renderWorldBlock(IBlockAccess, int, int, int, Block, int, RenderBlocks)` | static; companion is fallback |
|
||||
| `MultipartGenerator` | `generateCompositeTile(TileEntity, scala.collection.Iterable, boolean)` | **companion only for the Scala descriptor**; new static Java-Iterable entry is additive |
|
||||
| `BlockMicroMaterial` | `register(material)`, plus a constructor of arity 2 `(Block, int)` or 1 `(Block)` | static; companion is fallback |
|
||||
| `MicroMaterialRegistry` | `getMaterial(int)` | static; companion is fallback |
|
||||
| `MicroblockGenerator$` | `create(MicroblockClass, int, boolean)` | GuideNH explicitly selects the companion, matched by exact parameter types; static Java replacement exists |
|
||||
| `TileMultipart` | `partList()`, `partList_$eq(scala.collection.Seq)`, `loadParts(...)`, `notifyTileChange()`, `markRender()` | instance |
|
||||
| `Microblock` | `microClass()`, `material()`, `shape()` | instance |
|
||||
| `TMultiPart` | `getDrops()` | instance |
|
||||
| `BlockMicroMaterial` | `block()`, `meta()` | instance; absent from general `IMicroMaterial` |
|
||||
|
||||
Types used only for `isInstanceOf`: `BlockMultipart`, `TileMultipart`, `TileMultipartClient`, `Microblock`,
|
||||
`MicroblockClient`, `BlockMicroMaterial`.
|
||||
|
||||
### Three constraints this adds
|
||||
|
||||
1. **`MultipartGenerator$.MODULE$` is load-bearing through reflection.** `generateCompositeTile` is `private[multipart]`
|
||||
in Scala, so no static forwarder is emitted on `MultipartGenerator` and guidenh's static attempt always misses. It
|
||||
reaches the method only through the companion. A Phase 6/7 port that keeps the class but drops the companion, or
|
||||
promotes the method to a public static and removes it from the companion, breaks guidenh silently.
|
||||
|
||||
The branch now adds `MultipartGenerator.generateCompositeTile(TileEntity, java.lang.Iterable, boolean)` while
|
||||
retaining the exact companion Scala descriptor/body. GuideNH's old Scala sequence is not assignable to the new
|
||||
Java parameter, so its existing matcher still falls back to the companion. Both old and new reflective contracts
|
||||
are tested; migration requires a Java parts collection. See the [guide](docs/api/COMPOSITE_GENERATION.md).
|
||||
|
||||
2. **`MicroblockGenerator$.create` is matched by exact parameter types**, including `pts[0].getName()` string-compared
|
||||
against `"codechicken.microblock.MicroblockClass"`. That pins `create(MicroblockClass, int, boolean)` on the
|
||||
companion and pins `MicroblockClass`'s fully qualified name. Widening a parameter or renaming the class breaks the
|
||||
lookup even though every call site still links.
|
||||
|
||||
The existing static `MicroblockGenerator.create(MicroblockClass, int, boolean)` now has a
|
||||
[guide and compiling example](docs/api/MICROBLOCK_CREATION.md). Both exact reflective entries are tested; no API
|
||||
shape or production method body changes were needed. GuideNH must change its explicitly selected owner and receiver
|
||||
before it stops using the companion. Release/adoption, shape-setter override checks and client previews remain gates.
|
||||
|
||||
3. **`TileMultipart.partList_$eq(scala.collection.Seq)` is reflectively load-bearing.** The branch now supplies
|
||||
`setPartList(java.util.List)` and `loadPartList(java.util.Collection)`, while retaining the exact legacy setter and
|
||||
loader descriptors and override dispatch. Dropping the old setter in favor of the Java method would still break
|
||||
guidenh invisibly. Exact and assignability-based reflective tests cover both legacy contracts. `resolvePartList` also falls back to a public *field*
|
||||
named `partList`, which never existed — Scala emits the field private — so that path is dead in the reference too.
|
||||
|
||||
`MultipartHelper$` is retained on the strength of the fallback path alone: the static is found first today, so the
|
||||
companion is never reached in practice. That is a weaker justification than the two "companion only" entries above,
|
||||
but the cost of keeping a four-method forwarder is negligible against a silent break.
|
||||
|
||||
GuideNH's private `BlockMicroMaterial.block: Block` and `meta: int` fields remain unchanged for its accessor mixin.
|
||||
Existing public virtual `block()` / `meta()` now have a [typed query guide](docs/api/MATERIAL_ACCESS.md) and regression
|
||||
coverage; no descriptor or method body changed. The mixin reads constructor fields whereas direct calls honor
|
||||
subclass overrides, as the old reflective fallback already did. Remove the consumer's mixin only when adopting the
|
||||
typed query; FMP field removal still waits for released-consumer adoption.
|
||||
|
||||
|
||||
# Part 2 - Source-level consumer audit
|
||||
|
||||
The ABI inventory answers "what must still link?" This audit answers the harder question: "what behavior do real
|
||||
consumers expect after they have linked?" It covers all 27 ForgeMultipart consumers in the supplied GTNH daily
|
||||
`2026-08-25+700` instance, plus UtilitiesInExcess as the planned Extra Utilities replacement.
|
||||
|
||||
## Bottom line
|
||||
|
||||
@@ -3,11 +3,12 @@
|
||||
Current intentional differences from the `1.7.12` reference. This is a compatibility ledger, not a port diary.
|
||||
An unchanged implementation needs no entry. Results and port history belong in `JAVA_MIGRATION.md` and
|
||||
`JAVA_MIGRATION_HANDOFF.md`; client gaps in `JAVA_MIGRATION_MANUAL_CHECKS.md`; measurements in
|
||||
`JAVA_MIGRATION_PROFILE.md`. Superseded decisions and the original per-port narrative remain in git history.
|
||||
`JAVA_MIGRATION.md#phase-4b--measured-performance-pass`. Superseded decisions and the original per-port narrative remain in git history.
|
||||
|
||||
“No audited consumer” means the frozen GTNH binary inventory and consumer-source audit, not every possible
|
||||
third-party mod. Removed members can still break unaudited consumers. Check both `JAVA_MIGRATION_ABI_INVENTORY.md`
|
||||
and `JAVA_MIGRATION_CONSUMER_AUDIT.md` before extending this list.
|
||||
third-party mod. Removed members can still break unaudited consumers. Check
|
||||
`JAVA_MIGRATION_COMPATIBILITY.md`, which holds both the binary inventory and the consumer-source
|
||||
audit, before extending this list.
|
||||
|
||||
## Runtime and error behavior
|
||||
|
||||
|
||||
+15
-37
@@ -6,13 +6,12 @@ migration checkout; `codex/tile-compatibility-fixes` was deleted after its fixes
|
||||
|
||||
| Document | Purpose |
|
||||
| --- | --- |
|
||||
| [Plan](JAVA_MIGRATION.md) | Phase gates, API policy and upstream cleanup |
|
||||
| [Java API index](docs/API.md) | Consumer entry points, guides, compiling examples and remaining API gaps |
|
||||
| [ABI inventory](JAVA_MIGRATION_ABI_INVENTORY.md) | Shipping binary names/descriptors and reflective constraints |
|
||||
| [Consumer audit](JAVA_MIGRATION_CONSUMER_AUDIT.md) | Runtime behavior, data/lifecycle contracts and consumer source |
|
||||
| [Plan](JAVA_MIGRATION.md) | Phase gates, API/runtime/modern-Java policy, build arrangement and the performance protocol |
|
||||
| [Compatibility](JAVA_MIGRATION_COMPATIBILITY.md) | Binary ABI inventory plus the source-level consumer audit and adoption ledger |
|
||||
| [Divergences](JAVA_MIGRATION_DIVERGENCES.md) | Intentional effective compatibility differences |
|
||||
| [Manual checks](JAVA_MIGRATION_MANUAL_CHECKS.md) | Client/release checks with concrete item examples |
|
||||
| [Profile](JAVA_MIGRATION_PROFILE.md) | Measured workloads, results and rerun commands |
|
||||
| [Java API index](docs/API.md) | Consumer entry points, guides and compiling examples |
|
||||
| [Release notes](docs/RELEASE_NOTES.md) | What breaks for consumers who rebuild, and the supported replacements |
|
||||
| [History](docs/migration/HISTORY.md) | Dated completed-port findings and reference evidence; read as needed |
|
||||
|
||||
## Current state and next target
|
||||
@@ -20,30 +19,9 @@ migration checkout; `codex/tile-compatibility-fixes` was deleted after its fixes
|
||||
**576 plain-JVM tests and 289 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **230 Java
|
||||
files and 9 Scala files / 747 nonblank Scala lines**. The packaged inventory has 450 classes.
|
||||
|
||||
Review follow-up: restored packet-scheduler callback mutation behavior with the original Scala hash-map traversal,
|
||||
virtual tile accessor dispatch throughout `TMultiPart`, and null-safe equality for scheduled-tick deduplication.
|
||||
Six JVM and two Forge regression cases cover the fixes. Callable signatures remain unchanged; the packet traversal
|
||||
callback adds one anonymous class. See the latest history entries for the individual fixes and validation.
|
||||
|
||||
Accessor review fixes: `TileMultipart`, `Microblock` and `BlockMicroMaterial` now use their virtual state accessors
|
||||
throughout the restored paths. Eleven new regression cases pass against the original Scala jar and the fixed port;
|
||||
all 519 archived consumers pass with their recorded version. The supplied consumer checkouts confirm extension/API
|
||||
use, but no override triggering these three regressions was found. All 443 class/member APIs, 17 ScalaSignature
|
||||
payloads and 116 generated dumps are retained. The agreed next milestone is the documented consumer-facing Java API,
|
||||
followed by consumer release/adoption and final Scala removal; see the plan's API migration design and Phases 8–10.
|
||||
|
||||
Latest API work adds [supported multipart button orientation mapping](docs/api/BUTTON_ORIENTATIONS.md). Et Futurum
|
||||
Requiem `78a5744dfd33` currently reflects `ButtonPart.metaSideMap` and `sideMetaMap`, then writes the missing floor and
|
||||
ceiling pairs. Baseline commit `cd13ad6` freezes the default maps, those exact four writes and placement metadata on all
|
||||
six faces. `ButtonPart.setOrientation(int, ForgeDirection)` performs the same update through one validated public API,
|
||||
keeps both maps one-to-one when replacing a pair and rejects invalid input before mutation. Its compiling example uses
|
||||
two direct common-initialization calls without Scala or reflection.
|
||||
|
||||
All 573 JVM / 289 Forge tests pass; 573 archived JVM and 287 archived Forge callers also pass. All 444 production
|
||||
classes and 17 ScalaSignature payloads remain. The 3,763 old methods are unchanged and one public static method is
|
||||
added; all 134 generated dumps match by name and hash. The mutable arrays retain their exact public static shape for
|
||||
old Et Futurum releases. Consumer patch/release/pack adoption and physical-client validation remain open. Evidence:
|
||||
`run/migration-button-orientation-reference/`.
|
||||
The agreed milestone order is the documented consumer-facing Java API, then consumer release and adoption, then final
|
||||
Scala removal; see the plan's API migration design and Phases 8-10. Per-change fixes, their regression cases and their
|
||||
recorded ABI evidence are in [the history](docs/migration/HISTORY.md); do not restate them here.
|
||||
|
||||
Direct typed calls are the intended end state for supported integrations. Optional dependencies should isolate typed
|
||||
compatibility code behind presence/version checks; reflection snippets in earlier guides are temporary legacy
|
||||
@@ -85,8 +63,8 @@ switch awaits approval and actual target-pack adoption. Retain existing contract
|
||||
A separate [Phase 4b performance pass](JAVA_MIGRATION.md#phase-4b--measured-performance-pass) is planned once the API
|
||||
and representative extension workloads are stable, alongside consumer migration. Use fresh realistic profiles and
|
||||
repeated paired runs; distinguish FMP implementation gains from migrated-consumer gains, covering hot paths plus
|
||||
startup, transitions, rendering, network and memory costs. Follow the [measurement protocol](JAVA_MIGRATION_PROFILE.md#broader-performance-pass-protocol-planned).
|
||||
The historical Phase 4 results do not replace that pass, and no new performance gain has been measured for this update.
|
||||
startup, transitions, rendering, network and memory costs, following the measurement protocol recorded there. The
|
||||
historical Phase 4 results do not replace that pass, and no new performance gain has been measured for this update.
|
||||
|
||||
Pause mechanical extraction of retained Scala shells unless it enables that API, fixes a demonstrated issue or has
|
||||
a measured benefit. `ScalaSignature.ClassSymbolRef.info` remains an optional bounded extraction, not the default next
|
||||
@@ -94,12 +72,12 @@ task. Keep case-class/product/serialization shapes and simple model accessors su
|
||||
The external ProjectRed Scala-trait fixture and ScalaSignature model bridges remain required. Actual client
|
||||
generation, GPU output and full-pack checks remain manual.
|
||||
|
||||
Commit `5f0e329b` established Java 21 method-body syntax in `StackAnalyserLogic` through scoped compilation and
|
||||
Java 8 downgrading, while retaining Scala 2.11.5 on Java 8. Prefer modern syntax where it improves readability and
|
||||
the compilation boundary supports it; it need not wait for Scala removal. Defer a specific change if Scala parsing,
|
||||
compile order, ABI or downgrader/runtime support blocks it, recording the blocker and revisit condition. Keep the
|
||||
global modern-syntax setting disabled while it breaks Scala compilation. See the plan's modern Java readability
|
||||
policy and `JVM_DOWNGRADER_HANDOFF.md` for the original 398-test integration checkpoint and expansion constraints.
|
||||
Prefer modern syntax where it improves readability and the compilation boundary supports it; it need not wait for
|
||||
Scala removal. Defer a specific change if Scala parsing, compile order, ABI or downgrader/runtime support blocks it,
|
||||
recording the blocker and revisit condition. Keep the global modern-syntax setting disabled while it breaks Scala
|
||||
compilation. The build arrangement, eligibility rules and expansion constraints are in the plan's
|
||||
[modern Java readability policy](JAVA_MIGRATION.md#modern-java-readability-policy).
|
||||
|
||||
The initial Java API can operate over retained Scala storage and compatibility shells. Record legacy FMP uses,
|
||||
replacements, consumer releases, target-pack adoption and verification in the consumer audit. Source patches alone
|
||||
do not permit removal. Once the adoption gates pass, replace or retire FMP's remaining internal Scala users before
|
||||
|
||||
@@ -91,7 +91,7 @@ its callback-side input tests nor its retained client-body probe validates actua
|
||||
|
||||
## Not yet covered anywhere
|
||||
|
||||
- [ ] A focused pre-optimization CPU/allocation baseline now exists in `JAVA_MIGRATION_PROFILE.md`. A representative
|
||||
- [ ] A focused pre-optimization CPU/allocation baseline now exists in `JAVA_MIGRATION.md#phase-4b--measured-performance-pass`. A representative
|
||||
full-pack capture and the matching post-optimization comparison still need to be performed.
|
||||
- [ ] Shape-specific microblock NBT and packet payloads. Core `Microblock` shape/material NBT, description bytes and
|
||||
one-byte shape updates are complete, along with compact core tile/part NBT and logical chunk-description fixtures.
|
||||
|
||||
@@ -1,224 +0,0 @@
|
||||
# Java migration — focused performance baseline and results
|
||||
|
||||
This is the reproducible pre-optimization baseline for Phase 4. It runs inside the real deobfuscated Forge dedicated
|
||||
server, using the same generated tiles as the functional suite. It is intentionally focused rather than a claim about
|
||||
whole-pack TPS.
|
||||
|
||||
The broader follow-up is planned in [Phase 4b](JAVA_MIGRATION.md#phase-4b--measured-performance-pass). The historical
|
||||
numbers below remain scoped to their recorded workloads and revisions; no new performance result is claimed by
|
||||
adding this plan.
|
||||
|
||||
## Broader performance pass protocol (planned)
|
||||
|
||||
Begin after the Java API/representative extension workloads are stable, alongside consumer migration and before
|
||||
final Scala removal. A workload manifest must identify the world/seed or reproducible world snapshot, pack and mod
|
||||
versions, FMP/consumer commits, hardware, exact JVM/flags/heap, view distance and graphics settings, part/tile/trait
|
||||
counts, and the action sequence or replay command. Restore equivalent world state before each run.
|
||||
|
||||
Use the pack's selected modern Java runtime for primary results; check the supported Java 8 artifact separately for
|
||||
behavior and regressions. Hold the runtime and configuration fixed within every A/B comparison. Never attribute a
|
||||
JVM, renderer, pack-version or hardware change to the Java port.
|
||||
|
||||
Measure fresh-process startup and cold first-use/class generation separately from warmed steady-state play. For each
|
||||
variant, start with at least five independent runs, alternate baseline/candidate order, use identical warm-up and
|
||||
measurement windows, and extend runs/repetitions when results are noisy. Keep profiling overhead matched; confirm
|
||||
end-to-end timing without profiling when overhead is material. Preserve raw reports and recordings under a named
|
||||
ignored evidence directory rather than overwriting the only baseline.
|
||||
|
||||
Report median and variability across runs. Derive p95/p99 tick or frame times from enough samples within each run,
|
||||
not from five aggregate timings. Include absolute units and relative differences: CPU time, ms/tick, ms/frame,
|
||||
allocation bytes per operation or second, GC pause time, peak/retained heap, cold latency and network bytes where
|
||||
relevant. TPS alone can hide an improvement below the 50 ms tick budget. Separate CPU-bound and GPU-bound client
|
||||
scenes, and do not turn a helper microbenchmark ratio into an FPS/TPS claim.
|
||||
|
||||
Use two controlled comparisons: baseline versus optimized FMP with consumer code unchanged; then legacy versus
|
||||
migrated consumer calls on the same FMP artifact, including adapters and any required snapshots. Where compatible,
|
||||
also compare with the Scala/reference release on the same runtime and inputs. Compare equivalent results/world state,
|
||||
packet/NBT fixtures and callback behavior; explicitly exclude scenarios whose behavior cannot be matched.
|
||||
|
||||
Each accepted change records: hypothesis and targeted profile site; scenario/manifest and commands; before/after
|
||||
commits; raw evidence location; absolute/relative measurements with variability; correctness checks; controls,
|
||||
regressions and tradeoffs; and the acceptance decision. Define practical benefit above noise before editing. A
|
||||
below-noise result or a bottleneck outside FMP is a valid finding, not a reason to invent more optimization work.
|
||||
|
||||
Use the existing harness and local profiling tools first. Extend only the missing representative workloads, and keep
|
||||
small microbenchmarks as attribution/regression aids alongside actual pack/client measurements. Update this document
|
||||
with results when that pass runs; performance is not established by completing the API migration table.
|
||||
|
||||
## Re-run
|
||||
|
||||
The local server EULA must already contain `eula=true`. From PowerShell at the repository root:
|
||||
|
||||
```powershell
|
||||
.\gradlew.bat runFunctionalTestServer "-Pforgemultipart.profileFunctionalTests=true"
|
||||
```
|
||||
|
||||
The property is quoted because PowerShell otherwise splits the dotted Gradle property. Normal
|
||||
`runFunctionalTestServer` runs remain unchanged. Profile mode overwrites these ignored files:
|
||||
|
||||
- `run/server/forgemultipart-profile.txt` — exact timings and per-thread allocation counts;
|
||||
- `run/server/forgemultipart-baseline.jfr` — JFR CPU, allocation-site, and GC events.
|
||||
|
||||
Useful JDK commands after the run:
|
||||
|
||||
```powershell
|
||||
Get-Content run/server/forgemultipart-profile.txt
|
||||
jfr summary run/server/forgemultipart-baseline.jfr
|
||||
jfr view --width 220 hot-methods run/server/forgemultipart-baseline.jfr
|
||||
jfr view thread-allocation run/server/forgemultipart-baseline.jfr
|
||||
```
|
||||
|
||||
Open the `.jfr` in Java Mission Control for flame graphs and allocation-site inspection. The `startEpochMillis` and
|
||||
`nanos` values in the text file define the exact time window for each phase. Java 8 recordings expose TLAB allocation
|
||||
events rather than the newer `ObjectAllocationSample`, so `jfr view allocation-by-site` from a recent JDK is not a
|
||||
valid summary of this recording.
|
||||
|
||||
## Workload
|
||||
|
||||
The fixture uses Zulu OpenJDK 8, eight parts per tile, 1,000,000 warm-up iterations, then 50,000,000 measured
|
||||
iterations per phase:
|
||||
|
||||
- `updateEntity`: one `TileMultipart.updateEntity()` call, dispatching `update()` to eight ticking parts;
|
||||
- `operate`: one `TileMultipart.operate(Function1)` call with one reused function and eight bound parts;
|
||||
- `lightValue`: one `TileMultipart.getLightValue()` call across eight parts;
|
||||
- `getTile`: one `BlockMultipart.getTile()` lookup returning the same non-empty eight-part tile;
|
||||
- `redstoneQueries`: one `strongPowerLevel`, one `getConnectionMask`, and one masked `weakPowerLevel` call on a
|
||||
generated `TRedstoneTile` containing eight `IRedstonePart` implementations.
|
||||
|
||||
The checksum consumes all observable work. Allocation bytes come from HotSpot's per-thread allocation counter, not
|
||||
from sampled JFR events. JFR remains the source for CPU samples and allocation-site ranking.
|
||||
|
||||
## Baseline captured 2026-08-27
|
||||
|
||||
Environment: Zulu 8.96 / OpenJDK `1.8.0_504-b01`, Windows 11, 16 hardware threads, `-Xms1G -Xmx4G`, JFR `profile`
|
||||
settings.
|
||||
|
||||
| Phase | Elapsed | Operations/s | Allocated bytes | Bytes/operation | CPU samples |
|
||||
| --- | ---: | ---: | ---: | ---: | ---: |
|
||||
| `updateEntity` | 2.970 s | 16,835,622 | 9,198,500,864 | 184.0 | 209 |
|
||||
| `operate` | 3.004 s | 16,646,549 | 9,195,084,824 | 183.9 | 205 |
|
||||
| `redstoneQueries` | 3.689 s | 13,553,242 | 4,023,003,032 | 80.5 | 239 |
|
||||
|
||||
Timing is machine- and JIT-sensitive; compare it only with the same workload and environment. Allocation per operation
|
||||
is the more stable regression metric.
|
||||
|
||||
### CPU and allocation-site findings
|
||||
|
||||
- `updateEntity` and `operate` are dominated by `TileMultipart.parts()`, `AbstractCollection.toArray`, Scala list
|
||||
length/iteration, and Java-conversion wrappers. Their nearly identical 184-byte allocation cost shows that the
|
||||
traversal snapshot, not the update callback itself, is the first target.
|
||||
- The current Java `parts()` constructs an `ArrayList` from the published Scala `Seq` on every traversal. The reference
|
||||
Scala `operate` captured the immutable `Seq` and iterated it directly, so this cost is a port artifact rather than a
|
||||
compatibility requirement.
|
||||
- Redstone CPU samples are concentrated in Scala `List.foreach` (118/239), `PartMap.edgeBetween` (46/239), iterator
|
||||
`foreach` (35/239), and the generated strong-power closure (31/239). Allocation events identify
|
||||
`scala.runtime.IntRef`, Scala iterators, and generated closures as the major sites.
|
||||
|
||||
## Decision
|
||||
|
||||
The first Phase 4 implementation targeted `TileMultipart` traversal after focused tests froze its mutation semantics:
|
||||
iteration observes the captured part order, skips a part whose tile was cleared before its turn, and does not visit a
|
||||
part added during the callback. The implementation retains the public Scala `Seq` and `operate(Function1)` ABI.
|
||||
|
||||
## Traversal result captured 2026-08-27
|
||||
|
||||
`operate` now captures `partList` directly. The normal immutable Scala `List` path walks its existing head/tail chain,
|
||||
which creates no iterator, Java wrapper, array, or copied collection. The published setter still accepts any Scala
|
||||
`Seq`; unusual implementations use the reference-style iterator fallback rather than being forced into the fast-path
|
||||
representation.
|
||||
|
||||
The retained post-change report is from the same machine, JVM, arguments, warm-up, and 50,000,000-iteration workload:
|
||||
|
||||
| Phase | Baseline elapsed | Result elapsed | Baseline B/op | Result B/op | Throughput change |
|
||||
| --- | ---: | ---: | ---: | ---: | ---: |
|
||||
| `updateEntity` | 2.970 s | 0.682 s | 184.0 | 0.05 | 4.36x |
|
||||
| `operate` | 3.004 s | 0.700 s | 183.9 | 0.0 | 4.29x |
|
||||
| `redstoneQueries` | 3.689 s | 7.286 s | 80.5 | 80.4 | control only |
|
||||
|
||||
A repeat produced 0.732 s / 0.687 s for `updateEntity` / `operate`, with the same 0.05 / 0.0 B/op. The result therefore
|
||||
removes effectively all measured traversal allocation and raises throughput from roughly 16.7 million to 68–73
|
||||
million calls/s. The post-change JFR hot-method view no longer contains `TileMultipart.parts()`,
|
||||
`AbstractCollection.toArray`, or the Java-conversion wrappers in these paths.
|
||||
|
||||
The unchanged redstone allocation is the useful control. Its timing was consistently slower in both post-change runs,
|
||||
but its code did not change and it now starts several seconds earlier because the preceding phases finish faster; do
|
||||
not attribute that timing difference to this traversal change. Re-baseline the redstone unit immediately before its
|
||||
own implementation comparison.
|
||||
|
||||
## Redstone helper-unit comparison captured 2026-08-28
|
||||
|
||||
Immediately before converting `IRedstonePart.scala`, the same workload measured `redstoneQueries` at 7.603 s,
|
||||
6,575,956 iterations/s, 4,022,151,064 allocated bytes, and 80.4 B/iteration. After its six interfaces and
|
||||
`RedstoneInteractions` were converted together, the retained report measured 3.880 s, 12,884,996 iterations/s,
|
||||
4,023,003,032 allocated bytes, and 80.5 B/iteration. Both runs produced checksum `3315999992`.
|
||||
|
||||
The allocation result is unchanged. The elapsed-time difference is not treated as a port win: earlier unchanged
|
||||
Scala runs ranged from 3.689 to 7.603 s on this machine. More importantly, the post-port JFR has the same dominant
|
||||
sites: Scala `List.foreach`, `Iterator.foreach`, `PartMap.edgeBetween`, and
|
||||
`TRedstoneTile$$anonfun$strongPowerLevel$1`.
|
||||
|
||||
That evidence corrects the earlier plan. `IRedstonePart.scala` owned the public interfaces and routing helpers, but the
|
||||
measured `IntRef`, iterator, and closure allocations are emitted by `scalatraits/TRedstoneTile.scala`. Removing them
|
||||
requires the Phase 5 `registerJavaTrait` path and must not be smuggled into this otherwise descriptor-identical port.
|
||||
|
||||
`MicroRecipe.scala` was the next independent Phase 4 unit and is now Java. Its five recipe forms and precedence are
|
||||
characterized, and ordinary loops replaced its range/closure scans and exception-backed non-local returns. The focused
|
||||
server workload does not craft recipes, so no timing claim is made for that structural removal.
|
||||
|
||||
The generated-trait checkpoints are complete. `TPartialOcclusionTile` proved the no-field path; `TSlottedTile` proved
|
||||
field/accessor generation, initialization, copying, lifecycle behavior, and caching. Its ordinary loops remove four
|
||||
Scala range closures and the exception-backed slot-scan return structurally, but the focused workload has no slotted
|
||||
placement phase, so no numeric performance claim is made for that port.
|
||||
|
||||
## TRedstoneTile result captured 2026-08-28
|
||||
|
||||
The port was measured immediately before and after with the same JVM, eight-part generated tile, warm-up, and
|
||||
50,000,000-iteration workload. Both runs produced checksum `3315999992`.
|
||||
|
||||
| Implementation | Elapsed | Operations/s | Allocated bytes | Bytes/operation |
|
||||
| --- | ---: | ---: | ---: | ---: |
|
||||
| Scala trait | 7.534 s | 6,636,424 | 4,023,855,000 | 80.5 |
|
||||
| Java trait | 6.261 s | 7,986,213 | 0 | 0.0 |
|
||||
|
||||
The Java trait removes all measured allocation from the three-query iteration and improves throughput by 20.3% in
|
||||
this paired run. The checksum and all characterization tests are unchanged. Normal immutable Scala `List` part
|
||||
storage is traversed through its existing head/tail chain; the published `partList` setter still accepts any `Seq`,
|
||||
so non-`List` implementations retain an iterator fallback.
|
||||
|
||||
The existing Java-trait transformer cannot safely rewrite bytecode that directly reads inherited Minecraft fields or
|
||||
calls inherited `TileMultipart` methods. A package-private `TRedstoneTileAccess` shim keeps coordinate, `partList`, and
|
||||
virtual `partMap` access outside the transformed class. This changes no public facade or generated-trait member and
|
||||
required no generator change.
|
||||
|
||||
The two focused steady-state allocation targets identified by this workload are now resolved: `TileMultipart.operate`
|
||||
and generated redstone queries are effectively allocation-free on their normal immutable-list paths. Further
|
||||
optimization should follow a new representative profile rather than extending this synthetic workload speculatively.
|
||||
|
||||
## Multipart read-path baseline captured 2026-08-28
|
||||
|
||||
A consumer-audit sanity check identified two Java-port allocations that the original three-phase workload did not
|
||||
exercise. Focused tests now pin empty/non-empty `BlockMultipart.getTile`, direct ordered `Seq` indexing, and read
|
||||
queries over the mutable `Seq` implementations accepted by the public setter. The two matching profile phases measured:
|
||||
|
||||
| Phase | Elapsed | Operations/s | Allocated bytes | Bytes/operation |
|
||||
| --- | ---: | ---: | ---: | ---: |
|
||||
| `lightValue` | 3.170 s | 15,772,691 | 9,196,067,864 | 183.9 |
|
||||
| `getTile` | 0.271 s | 184,225,439 | 1,200,000,000 | 24.0 |
|
||||
|
||||
`lightValue` pays for `TileMultipart.parts()`'s copied `ArrayList`; `getTile` pays for the Java list wrapper returned by
|
||||
`jPartList()`. Both are absent from the reference Scala implementation, which reads the published `Seq` directly.
|
||||
Mutation paths still require a snapshot before publishing a replacement immutable `Seq`.
|
||||
|
||||
### Read-path result captured 2026-08-28
|
||||
|
||||
The paired run used the same JVM, eight-part tiles, warm-up, iteration count, and checksum:
|
||||
|
||||
| Phase | Baseline elapsed | Result elapsed | Baseline B/op | Result B/op | Throughput change |
|
||||
| --- | ---: | ---: | ---: | ---: | ---: |
|
||||
| `lightValue` | 3.170 s | 0.278 s | 183.9 | 0.0 | 11.42x |
|
||||
| `getTile` | 0.271 s | 0.094 s | 24.0 | 0.0 | 2.89x |
|
||||
|
||||
Internal read paths now traverse or index the published Scala `Seq` directly. The normal immutable-list light query
|
||||
walks the existing head/tail chain; arbitrary `Seq` implementations retain an iterator fallback. The public
|
||||
`jPartList()` bridge remains unchanged for downstream ABI compatibility, and only add/remove paths take mutable
|
||||
snapshots before publishing a replacement immutable `Seq`.
|
||||
@@ -1,243 +0,0 @@
|
||||
# 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` uses pattern and arrow-rule switches,
|
||||
`JavaTraitRegistration` and `ClassInfoLookup` use Java 21 pattern variables, and `ScalaSignatureParser` uses switch
|
||||
expressions. `HollowMicroblockTraitLogic`, `PostMicroblockClientLogic`, and `TMicroOcclusionLogic` use the same scoped
|
||||
path for internal microblock control flow, as does `HollowMicroblockClientLogic` for its slot renderer. The nine Scala
|
||||
sources and Scala 2.11.5 dependency remain in place, as do the source layout and normal Gradle entry points. 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
|
||||
|
||||
1. Normal Java and joint Scala/Java compilation remain on Java 8. `compileScala` excludes 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.
|
||||
2. `compileModernJava` uses JDK 25 with `--release 21`, against the fresh Java and Scala output directories.
|
||||
3. `downgradeModernJava` converts 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:
|
||||
|
||||
1. Start with package-private helpers called directly by retained Scala. `JavaTraitRegistration.java` and
|
||||
`ClassInfoLookup.java` are completed follow-ups; pattern variables remove their checked casts without changing the
|
||||
Scala-facing declarations. `StackAnalyserLogic.java` remains the original proven example.
|
||||
2. Continue only where modern syntax produces a concrete control-flow gain. `ScalaSignatureParser.java`, the remaining
|
||||
opcode switches in `StackAnalyserLogic.java`, and the hollow/post-client/occlusion microblock helper group are
|
||||
complete.
|
||||
`ScalaTraitRegistration.java` should not move merely to restyle its erased `Some` checks.
|
||||
3. The public implementation dependency-closure audit is complete. `RedstoneInteractions$.java` cannot move without its
|
||||
facade and then the transformer-sensitive registered `TRedstoneTile.java` trait. `BlockMultipart.java` immediately
|
||||
pulls its companion, cache, event handler, server proxy, and the renderer resolver. Reject both migrations: their
|
||||
small cast cleanup does not justify widening the modern compiler boundary.
|
||||
4. 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.
|
||||
5. Defer the six `src/main/java` bootstrap/API sources and the separate `src/mixin/java` source. They are not currently
|
||||
outputs of `downgradeModernJava`, and the simple API declarations have little modernization value. The mixin source
|
||||
needs an explicit downgraded-output arrangement before using post-Java-8 syntax.
|
||||
6. Keep Scala companions, `$class` compatibility 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 bounded follow-up after those rejected public closures is `TMicroOcclusionLogic.java`: it is package-private, called
|
||||
directly by retained Scala, and its pattern binding removes a checked cast without changing the Scala-facing trait. No
|
||||
other current helper justifies a wider compiler migration solely for syntax. Resume the retained Scala conversion next;
|
||||
as that removes joint-compilation edges, migrate each newly freed Java closure and then collapse the per-file exclusions.
|
||||
|
||||
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.
|
||||
|
||||
The completed `ScalaSignatureParser` batch also passes the clean compiler boundary, all 576 JVM tests, all 289 Java 8
|
||||
Forge tests and the 134-dump comparison; all 450 packaged classes remain version 52. Its non-private ABI is unchanged
|
||||
and it has no executable JVM Downgrader API reference. Modern string concatenation in the same internal class lowers
|
||||
to six private helper methods; these are compiler implementation details, not consumer entry points.
|
||||
|
||||
The follow-up `StackAnalyserLogic` batch converts constant classification to a pattern switch expression and removes
|
||||
fall-through syntax from its opcode switches. It adds no build exclusion and preserves the same 576 JVM tests, 289
|
||||
Java 8 Forge tests and all 134 generated ASM hashes.
|
||||
|
||||
The `HollowMicroblockTraitLogic` and `PostMicroblockClientLogic` batch passes a clean build, all 576 JVM tests, all 289
|
||||
Java 8 Forge tests and the 134-dump comparison. Their non-private ABI is unchanged, all 450 packaged classes remain
|
||||
version 52, and neither helper has an executable JVM Downgrader API reference. `PostMicroblockTraitLogic` was rejected
|
||||
from the batch: the retained Scala declaration does not expose `getShape()` through `PostMicroblock`, so its explicit
|
||||
`Microblock` cast is required and modern pattern syntax provides no useful replacement.
|
||||
|
||||
The `HollowMicroblockClientLogic` slot-renderer batch has the same clean-build, 576-test, 289-test, version-52 and
|
||||
134-dump results. Its non-private ABI and callback ordering are unchanged, and its packaged classes have no executable
|
||||
JVM Downgrader API reference.
|
||||
|
||||
The `TMicroOcclusionLogic` batch also passes the clean build, all 576 JVM tests, all 289 Java 8 Forge tests, and the
|
||||
134-dump comparison. Its package-private method descriptors are unchanged, all 450 packaged classes remain version 52,
|
||||
and the helper has no executable JVM Downgrader API reference.
|
||||
|
||||
### 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:
|
||||
|
||||
- `JInventoryTile` could replace its temporary `List<Integer>` with `IntArrayList`, but slot lists are small, the code
|
||||
is a transformer-sensitive registered trait, and the dependency would cost more than the avoided boxing.
|
||||
- `MultiPartRegistry.nameMap` and `MicroMaterialRegistry.nameMap` could use `Object2IntOpenHashMap`, but they are small,
|
||||
lifecycle-built registries. Their missing-key behavior is also deliberately characterized. Keep `HashMap`.
|
||||
- `ControlKeyModifer.map` could use a reference-to-boolean map, but it is publicly exposed as a live `Map` and normally
|
||||
contains only the connected players. Keep `HashMap`.
|
||||
- `PacketScheduler` is the only plausible future candidate for an object-to-long map because it accumulates masks and
|
||||
boxes `long` values. 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.
|
||||
- `TileCache` could only become primitive-keyed by replacing `BlockCoord` with 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`, `ClassInfoLookup`,
|
||||
`ScalaSignatureParser`, `HollowMicroblockTraitLogic`, `PostMicroblockClientLogic` and `HollowMicroblockClientLogic`
|
||||
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:
|
||||
|
||||
```powershell
|
||||
.\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.
|
||||
|
||||
```powershell
|
||||
$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.
|
||||
+4
-4
@@ -107,7 +107,7 @@ Three advanced methods remain supported because consumers use them directly:
|
||||
|
||||
No reflection is needed to call any of these methods. `operate` and `getOrConvertTile2` retain their documented legacy
|
||||
contracts and Java replacements; neither receives an internal-only marker. Removing those bridges still requires
|
||||
consumer and internal migration gates. The [consumer audit](../JAVA_MIGRATION_CONSUMER_AUDIT.md#api-boundary-audit)
|
||||
consumer and internal migration gates. The [consumer audit](../JAVA_MIGRATION_COMPATIBILITY.md#api-boundary-audit)
|
||||
records the checked source calls and validation.
|
||||
|
||||
## Compatibility and remaining work
|
||||
@@ -135,7 +135,7 @@ Scala dependency requires those gates and removal of FMP's remaining internal Sc
|
||||
| Need | Document |
|
||||
| --- | --- |
|
||||
| What is complete and what comes next? | [Working handoff](../JAVA_MIGRATION_HANDOFF.md), [migration plan](../JAVA_MIGRATION.md) |
|
||||
| Which consumers need changes, releases and pack adoption? | [Consumer adoption ledger](../JAVA_MIGRATION_CONSUMER_AUDIT.md#java-api-adoption-ledger) |
|
||||
| Which binary names, reflective lookups and runtime contracts must survive? | [ABI inventory](../JAVA_MIGRATION_ABI_INVENTORY.md), [source consumer audit](../JAVA_MIGRATION_CONSUMER_AUDIT.md) |
|
||||
| Which consumers need changes, releases and pack adoption? | [Consumer adoption ledger](../JAVA_MIGRATION_COMPATIBILITY.md#java-api-adoption-ledger) |
|
||||
| Which binary names, reflective lookups and runtime contracts must survive? | [ABI inventory and consumer audit](../JAVA_MIGRATION_COMPATIBILITY.md) |
|
||||
| What has been tested and what still needs a client/pack run? | [Migration history](migration/HISTORY.md), [manual release checks](../JAVA_MIGRATION_MANUAL_CHECKS.md) |
|
||||
| Why is some Scala or older Java syntax retained? | [Modern Java policy](../JAVA_MIGRATION.md#modern-java-readability-policy), [compiler/toolchain handoff](../JVM_DOWNGRADER_HANDOFF.md) |
|
||||
| Why is some Scala or older Java syntax retained? | [Modern Java policy](../JAVA_MIGRATION.md#modern-java-readability-policy), [compiler/toolchain handoff](../JAVA_MIGRATION.md#modern-java-readability-policy) |
|
||||
@@ -62,7 +62,7 @@ Extra Utilities' NEI handlers use both tuple fields; both indexed replacements a
|
||||
|
||||
The static and companion `getIdMap()` methods are deprecated, with their original descriptors and live-array
|
||||
behavior retained. This change does not authorize removal of either method. The
|
||||
[consumer adoption ledger](../../JAVA_MIGRATION_CONSUMER_AUDIT.md#java-api-adoption-ledger) records the migrations and
|
||||
[consumer adoption ledger](../../JAVA_MIGRATION_COMPATIBILITY.md#java-api-adoption-ledger) records the migrations and
|
||||
released pack versions still needed.
|
||||
|
||||
## Validation
|
||||
|
||||
@@ -98,5 +98,5 @@ callback input mutation and partial-failure behavior. Forge tests cover slot-cac
|
||||
plus Java assignment/loading on a generated client tile and explicit render-cache rebuilding. The latter does not run
|
||||
a real client world or GPU rendering; GuideNH/Schematica previews and full-pack adoption remain manual release gates.
|
||||
|
||||
The [consumer ledger](../../JAVA_MIGRATION_CONSUMER_AUDIT.md#java-api-adoption-ledger) records the inspected source
|
||||
The [consumer ledger](../../JAVA_MIGRATION_COMPATIBILITY.md#java-api-adoption-ledger) records the inspected source
|
||||
revisions and pending consumer changes/releases. The supplied reference checkouts are unchanged.
|
||||
@@ -97,7 +97,7 @@ GuideNH also reflects `partList`, `partList_$eq` and `loadParts` while reconstru
|
||||
uses to the Java getter does not migrate its setter/loading contracts. Their [Java replacements](PART_LOADING.md)
|
||||
are implemented; the consumer patch, release and pack adoption remain separate work. No reference checkout was edited.
|
||||
|
||||
The [adoption ledger](../../JAVA_MIGRATION_CONSUMER_AUDIT.md#java-api-adoption-ledger) records inspected revisions and
|
||||
The [adoption ledger](../../JAVA_MIGRATION_COMPATIBILITY.md#java-api-adoption-ledger) records inspected revisions and
|
||||
the remaining release gates. JVM checks cover both getter forms, mutable storage, callback mutation/reentrancy,
|
||||
detached/rebound parts, override dispatch and failures. The Forge test removes and adds real parts during traversal
|
||||
of a generated slotted tile. Client rendering and full-pack adoption remain manual release checks.
|
||||
+415
-277
File diff suppressed because it is too large.
Load diff
Vendored
+2
-2
@@ -8,7 +8,7 @@ rather than regenerated automatically, otherwise an accidental change silently r
|
||||
`gtnh-daily-678-consumers.txt` is the constant-pool scan of every mod jar in GTNH daily `2026-08-14+678`, listing
|
||||
every downstream reference into `codechicken/multipart` and `codechicken/microblock`. Regenerate with
|
||||
`tools/AbiScan.java` and diff against this file at every public-API phase; a member present here but absent from the
|
||||
port is a linkage break in a shipping mod. See `JAVA_MIGRATION_ABI_INVENTORY.md` for the analysis.
|
||||
port is a linkage break in a shipping mod. See `JAVA_MIGRATION_COMPATIBILITY.md` for the analysis.
|
||||
|
||||
## Precompiled binary consumers
|
||||
|
||||
@@ -18,7 +18,7 @@ hide exactly the linkage failure the fixture exists to catch.
|
||||
|
||||
`ReferenceScalaPartialOcclusion` was removed together with the `JPartialOcclusion$class` bridge once the inventory
|
||||
showed no downstream consumer of that helper. The trait helpers that do need this treatment are listed in
|
||||
`JAVA_MIGRATION_ABI_INVENTORY.md`.
|
||||
`JAVA_MIGRATION_COMPATIBILITY.md`.
|
||||
|
||||
### `ReferenceScalaCuboidPart`
|
||||
|
||||
|
||||
Reference in new issue
Block a user