docs: consolidate the migration documentation set

This commit is contained in:
Algent committed 2026-09-09 16:39:31 +02:00
1 parent 9f01653923
commit 94633dee92
14 files changed
+866 -1153

No files matched your search

+158 -60
View File
@@ -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.
-293
View File
@@ -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
+4 -3
View File
@@ -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
View File
@@ -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
+1 -1
View File
@@ -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.
-224
View File
@@ -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`.
-243
View File
@@ -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
View File
@@ -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) |
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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.
+1 -1
View File
@@ -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
View File
File diff suppressed because it is too large. Load diff
+2 -2
View File
@@ -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`