66 KiB
Java migration plan and audit findings
Status: living document
Initial audit: 2026-08-14
Audited revision: f10595d (master)
Decision summary
Converting ForgeMultipart to Java is realistic. It should be treated as a staged compatibility migration, not as an automatic source conversion or a ground-up rewrite.
The main difficulty is preserving behavior and compatibility, not translating Scala syntax. In particular, ForgeMultipart dynamically builds TileMultipart subclasses from combinations of part capabilities, and its published bytecode exposes Scala types and Scala compiler artifacts to other mods.
The current direction is:
- Preserve observable behavior unless a divergence is an intentional, documented bug fix or performance fix.
- Add clean Java APIs with equivalent features.
- Keep deprecated compatibility bridges for the old Scala-facing API for at least the initial Java release.
- Use the Hodgepodge/GTNH convention for any new Sponge Mixins: UniMixins plus explicit normal, early, and late registration where the target lifecycle requires it.
- Allow GTNHLib as a dependency. Use fastutil selectively for measured primitive-collection or allocation problems, not as a blanket collection replacement.
- Keep ForgeMultipart's runtime composite-tile generator separate from the Sponge Mixin decision until it is proven replaceable. They solve different problems.
No trustworthy tool will produce a maintainable Java port automatically. A decompiler can help recover control flow or compare generated bytecode, but its output should be used as a reference rather than committed as the implementation.
Current status
The binary and source-level consumer audits are complete. Phase 0 still lacks a pre-optimization profile. The low-coupling Phase 3 queue is complete; before entering measured hot-path work, the immediate milestone is the remaining generated-tile portion of the audit-derived compatibility gate below.
That audit found and this branch has now repaired one existing regression: Schematica 1.12.6 reflects the original private
MultiPartRegistry$ field codechicken$multipart$MultiPartRegistry$$typeMap and casts it to a Scala mutable map. The
companion again exposes that exact private field as a live view of the canonical Java HashMap, and a test performs
Schematica's reflective lookup. The remaining source-only member guards, TileMultipart ordering/move lifecycle, and
compact mixed-part NBT/description packet are also frozen; generated-trait and pass-through fixtures are next.
Phase 1 has not properly started: GTNHLib is present but was added at api scope to satisfy a test compile rather
than because a migration change needed it, and no Forge mod dependency was declared. Revisit that entry only when a
real migration change needs it. Phase 8 is answered and deferred.
The working rules established while converting, which apply to every remaining area:
- Check both consumer audits before changing a compatibility surface.
JAVA_MIGRATION_ABI_INVENTORY.mdis the authority on binary linkage;JAVA_MIGRATION_CONSUMER_AUDIT.mdis the authority on runtime behavior, data formats, reflection, and mixin field access. - Emit a Java
defaultmethod only when no class in an implementor's superclass chain declares the same member. Otherwise leave it abstract and add explicit forwarders, because a superclass method always beats an interface default and the failure is silent. - Audit existing
supercall sites on every trait conversion, not just missing overrides. A class that already overrides a method and ends withsuper.x()can silently lose the trait's contribution while still compiling. - Introducing a trait default can change the declared members of concrete implementors that never carried their own override. Diff those classes too, not just the trait.
Scope and compatibility target
“Behave the same” means preserving the following unless a change is explicitly entered in a divergence log:
- Multipart placement, removal, occlusion, collision, selection, ticking, redstone, rendering, and scheduled-tick behavior.
- Client/server separation and Forge/FML lifecycle timing.
- Part and tile registration order and lookup behavior.
- Part identifiers, NBT keys and structures, saved-world loading, and conversion of existing multipart tiles.
- Packet identifiers, field order, encoding, dispatch timing, and client update behavior.
- Dynamically generated tile interfaces and capabilities expected by parts and integrations.
- Public class names, method descriptors, static entry points, and reflective lookups that supported downstream mods use.
- Behavior in both development and obfuscated production environments.
Allowed divergences are:
- Confirmed bug fixes.
- Removal of avoidable allocation, boxing, exception-based control flow, or other performance problems.
- Better failure messages where success-path behavior is unchanged.
Each divergence should record the old behavior, new behavior, reason, compatibility impact, and how it was manually verified. Unintentional behavior changes are regressions even if the new implementation appears cleaner.
Java runtime policy
The main GTNH release targets modern Java across the Java 17–26 range. A Java 8 artifact must remain available for legacy launchers, with the same functional behavior even if it cannot match the modern runtime's performance.
- Modern Java syntax and APIs may be used when the GTNH build's JVM Downgrader/desugaring path provides a verified Java 8 artifact.
- Do not enable desugaring speculatively. Introduce it with the first source change that needs it, then verify both the modern and downgraded artifacts.
- Java 8 startup, serialization, networking, registration, and gameplay semantics are compatibility requirements. Equal throughput or allocation behavior between Java 8 and modern Java is not required.
- Validate routinely in the Java 8 deobfuscated Forge runner. Validate the packaged release in a representative modern-Java server before release, because the current GTNH deobfuscated
runServer17/runServer21/runServer25tasks do not provide a working dedicated-server path in this checkout. - Avoid modern runtime APIs whose downgrader stubs are unavailable or whose semantics materially differ on Java 8, especially in compatibility-critical and hot code.
Audit findings
Codebase size
At the audited revision:
| Area | Scala files | Approximate Scala lines |
|---|---|---|
| Multipart core | 38 | 4,076 |
| Multipart ASM | 8 | 1,933 |
| Microblocks | 28 | 3,013 |
| Total | 74 | 9,022 |
There are also 19 Java source files with approximately 1,148 lines. The existing README explicitly describes the API as Java-friendly, and the bundled Minecraft multipart implementation already serves as a Java consumer of it.
The current Scala source compiles successfully with Scala 2.11.5. This gives the migration a working reference implementation rather than requiring recovery of a broken codebase.
What Scala currently costs
The compiled mod contains 635 class files and is approximately 1.64 MiB before its Scala runtime dependency. Compiler-generated artifacts include:
- 236
anonfunclosure classes, approximately 448 KiB. - 39 trait helper
$classfiles, approximately 98 KiB. - 121 object/companion-related class files, approximately 415 KiB.
These figures support a maintainability and allocation argument for Java, but not the claim that Scala wraps most methods in try/catch.
A scan of 5,126 Scala methods found 52 methods with exception tables and 53 total entries. The important groups were:
- 33 catch-all/finally handlers, mostly compiler machinery for synchronization and lazy initialization.
- 9
scala.runtime.NonLocalReturnControlhandlers caused byreturnfrom inside closures. - 11 ordinary exception handlers covering
Exception,ClassCastException,IllegalStateException, andIOException.
The 222 methods emitted from the Java sources had no exception-table entries in the same scan.
Exception-table metadata does not impose a meaningful steady-state cost merely by existing. The nine non-local-return sites are different: when the early return is taken, Scala implements it by throwing and catching NonLocalReturnControl. Those sites are worth removing, but they do not justify assuming exception overhead across the whole mod.
More credible performance risks
The source and bytecode audit identified allocation patterns that are more plausible performance targets:
TileMultipart.updateEntity()creates a Scala closure for each ticking multipart tile on each tick, then traverses throughoperate(Function1)and Scala collection machinery.TRedstoneTilepower and connection queries create closures andscala.runtime.IntRefboxes in frequently queried code.- Several Scala 2.11 collection, range, and
JavaConversionspaths create closure objects, boxed primitives, iterators, or temporary collections. TSlottedTile.canAddPartand severalMicroRecipesearches use exception-based non-local returns.- Rendering code in
TileMultipartalready uses cached arrays andwhileloops in important paths. It should be preserved as evidence of deliberate optimization, not mechanically rewritten into streams or higher-level collection pipelines.
These are static findings, not proof of their share of frame or tick time. Capture profiles and allocation data before and after each relevant migration phase.
Runtime code generation is architectural, not incidental
MultipartGenerator selects a tile class from the interfaces required by the parts in a block. ASMMixinFactory caches generated constructors by a trait bit set, so class generation is primarily a registration/first-combination cost rather than a per-tick cost.
ASMMixinCompiler already supports two inputs:
registerScalaTrait, which reads Scala signature data and understands Scala trait output.registerJavaTrait, which transforms a concrete Java mixin class into the interface/static-helper form used by the generator.
The Java path rejects Java interfaces, inner classes, abstract classes, static initializers, and constructors with arguments. Those restrictions must be accounted for when converting built-in tile traits, but the path proves that Java implementations can participate in the current composition system.
MultipartGenerator.registerPassThroughInterface also explicitly supports interfaces that generated tiles must expose. This is part of the compatibility surface and must not be lost in a static subclass rewrite.
The least risky plan is therefore to keep the current composition model during the first Java migration. Port or redesign its ASM implementation only after the rest of the behavior is stable.
Public ABI exposes Scala
Several public descriptors contain Scala runtime types. Examples include:
TileMultipart.partListexposingscala.collection.Seqthrough generated accessors.TileMultipart.operateacceptingscala.Function1.- Occlusion methods accepting Scala
Seqvalues. - Tile conversion helpers returning
scala.Tuple2. MultiPartRegistryoverloads accepting ScalaFunction2orSeq, and returningSeq.- Scala object singletons (
MODULE$), companion/static forwarders, and trait$classhelpers.
Changing these descriptors directly to java.util or java.util.function types can cause NoSuchMethodError, NoClassDefFoundError, or reflective integration failures in already compiled mods. Source compatibility alone is not sufficient.
This means “all source is Java” and “the Scala runtime is gone” are separate milestones. Deprecated bridges may still require Scala library types even after the implementation is Java.
API migration design
Create a Java-first API with the same capabilities, then make legacy entry points delegate into it. Delegation should have one direction: deprecated Scala bridge to canonical Java implementation. Avoid two independently maintained implementations.
Candidate mappings, with final names and mutability contracts to be decided from existing behavior:
| Existing Scala-facing shape | Java-first equivalent |
|---|---|
Seq<TMultiPart> |
List<TMultiPart> or a purpose-specific read-only view |
Function1<TMultiPart, Unit> |
Consumer<TMultiPart> or direct indexed traversal methods |
Function2 factory callbacks |
A named Java functional interface with domain-specific arguments and return type |
Tuple2<TileMultipart, Boolean> |
A small immutable Java result class with named accessors |
| Scala collection overloads in registries | Collection, List, arrays, or Java Iterable, according to actual ordering and mutation semantics |
Bridge rules:
- Preserve old JVM descriptors, not merely old source names.
- Mark source-visible legacy APIs deprecated and point their documentation to the Java replacement.
- Preserve ordering, nullability, mutability, exception, and callback timing semantics.
- Keep legacy singleton/static entry points when downstream bytecode may reference them.
- Do not leak new Scala types into the Java API.
- Do not remove Scala library dependencies until an ABI inventory shows that no retained bridge needs them.
- Use
javapplus an API/ABI comparison tool such as japicmp or Revapi against the reference dev jar at every public-API phase.
Before implementing bridges, inventory real consumers in the target modpack. Some Scala compiler artifacts may be technically public but unused; others may be load-bearing despite looking internal.
Mixin strategy
Follow the pattern currently used by Hodgepodge for fixed class transformations:
- Set the GTNH build convention's
usesMixins = true, which supplies UniMixins integration and declares UniMixins as a required dependency. - Use a normal/pre-init mixin configuration for transformations that do not require special early or optional-mod timing.
- Use an
IEarlyMixinLoaderconfiguration only for targets that must be selected before ordinary mod loading. - Use an
@LateMixin/ILateMixinLoaderconfiguration for optional-mod targets whose presence is known later. - Centralize selection through the GTNHMixins builder pattern, including side, loaded-coremod, loaded-mod, and configuration gates.
- Keep early and late lists minimal. A mixin should not be early or late merely because those mechanisms are available.
- Prefer Sponge Mixins for fixed transformations of known classes. Retain raw ASM only where a mixin cannot express the required behavior safely.
The inspected Hodgepodge reference uses:
HodgepodgeCore implements IFMLLoadingPlugin, IEarlyMixinLoaderand delegates early selection toIMixins.getEarlyMixins(...).HodgepodgeLateMixins, annotated with@LateMixin, implementingILateMixinLoaderand delegating late selection toIMixins.getLateMixins(...).- Separate normal, early, and late JSON configurations.
- Explicit dependencies on GTNHMixins and UniMixins.
Important distinction: Sponge/UniMixins modifies known classes during class loading. ForgeMultipart's current generator creates different tile classes for runtime combinations of part interfaces. The Hodgepodge registration pattern should be used for ordinary patches introduced by this port, but UniMixins is not assumed to replace the composite-tile generator.
GTNHLib and fastutil
GTNHLib is an acceptable dependency for the port. The inspected GTNHLib checkout declares fastutil 8.5.18 as compileOnlyApi and uses its dependency-loader/GTNHExtLib arrangement for external runtime libraries. Hodgepodge consumes GTNHLib as an API dependency and imports fastutil through that environment.
Integration requirements:
- Select the GTNHLib version aligned with the target pack/release train rather than copying Hodgepodge's current version blindly.
- Verify both compile and production runtime resolution in ForgeMultipart's actual build after adding the dependency.
- Add the Forge mod dependency declaration with a compatible version range.
- Use primitive fastutil collections where they remove boxing or object-key allocation in a demonstrated hot path.
- Prefer JDK collections for small, cold, or API-facing collections unless fastutil provides a concrete benefit.
- Do not expose fastutil implementation classes from the stable public API without a strong reason; ordinary Java interfaces keep consumers decoupled.
Candidate areas to measure include redstone query state, coordinate-keyed caches, scheduler structures, registry lookups, and render/tile scratch collections. A primitive map is only useful if the key can be represented without first allocating a wrapper such as BlockCoord.
GTNHLib's ASM utilities may also reduce low-level boilerplate when the runtime generator is eventually ported. Evaluate them against the generator's exact needs instead of changing ASM APIs during the earlier source migration.
Migration phases
Every implementation phase follows the same test-first gate:
- Write characterization tests against the current Scala implementation for the area about to change.
- Run them on the untouched implementation and retain any golden fixtures they produce.
- Commit the tests separately from the port so the baseline is reviewable.
- Replace the implementation while leaving the tests unchanged.
- Require the same tests to pass before moving to the next area.
If a characterization test captures a confirmed bug that the port intentionally fixes, record it in the divergence log and change that expectation in a separate, explicit bug-fix step. This prevents accidental changes from being presented as fixes.
Phase 0 — Freeze and measure the reference behavior
- Produce and retain a reference dev jar from
f10595dor the selected migration base. - Dump the public/protected JVM API and important generated tile class shapes.
- Inventory downstream mods that compile against or reflect into ForgeMultipart. See
JAVA_MIGRATION_ABI_INVENTORY.mdandJAVA_MIGRATION_CONSUMER_AUDIT.md. - 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.
- Add a Java-8-compatible JUnit/Jupiter setup to the existing Gradle
testtask. - Add a separate Forge integration-test source set/runner for behavior that cannot execute in a plain JVM.
- Write the first characterization suite against the untouched Scala implementation.
- 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. - Capture representative CPU and allocation profiles before optimization work.
- 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.
Phase 1 — Add infrastructure only when first needed
- Add GTNHLib with a pack-aligned version when the first Java migration or data-structure change uses it.
- Enable UniMixins when the first fixed class transformation is introduced.
- Copy the Hodgepodge loader/config structure selectively: normal by default, early/late only for demonstrated lifecycle needs.
- Confirm client and dedicated-server startup after each dependency or loader change.
Exit condition: dependencies and loaders are present with no unintended gameplay behavior change.
Phase 2 — Establish the Java-first API and compatibility bridges
- Inventory every public Scala descriptor and compiler-generated entry point used by downstream code.
- Add ABI snapshots and compiled consumer fixtures before changing public descriptors.
- Define Java collection, callback, and result types with documented behavior equivalent to the current API.
- Implement the canonical behavior once in Java.
- Keep deprecated Scala signatures and singleton/static entry points as thin adapters.
- Compare the produced jar with the reference API and verify representative Java and Scala consumers can load.
Status: the two open items are open only because conversion is still in progress, not because the approach is
undecided. Every converted area already implements its behavior once in Java with the Scala entry points delegating
inwards, and every public boundary is diffed against the reference dev jar. The collection and callback decisions are
made per area against the inventory rather than up front: readIDMap moved to java.util.List because nothing links
against it, while getIdMap keeps its scala.Tuple2 array because extrautilities does.
Exit condition: new code can use a clean Java API while existing supported binaries still link through the deprecated surface.
Phase 3 — Convert low-coupling code
- Characterize each related leaf group before converting it.
- Convert the identified constants, value holders, simple utilities, registries, packet data helpers, and leaf classes.
- Replace
JavaConversionsin converted files with explicit Java collections or controlled adapters. - Preserve iteration order and null behavior.
- 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. The exact completed list is maintained in JAVA_MIGRATION_HANDOFF.md.
Exit condition: leaf code is Java and no longer generates avoidable Scala closures or collection adapters.
Immediate compatibility gate — current next milestone
Do this before another source conversion:
- 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. - Add exact member-level guards for GuideNH's
BlockMicroMaterial.block/metamixin fields, Et Futurum's mutableButtonPart.metaSideMap/sideMetaMap, Iguana'sItemSaw.harvestLevel, and Galacticraft's name-onlyregisterMateriallookup. - Freeze
TileMultipartorder and lifecycle observations:parts/idNBT,partList/jPartList,partMap, slot rebinding, add/remove/replace callback order, moving the live tile, andonMoved. - 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.
- 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.
Phase 4 — Convert measured hot paths
- Characterize result ordering, callback timing, early exits, and edge cases before changing traversal code.
- Rewrite
TileMultipart.updateEntity()as allocation-free indexed or array traversal. - Rewrite redstone queries without closure allocation or
IntRefboxing. - Replace non-local returns in slot/recipe scans with ordinary Java control flow.
- Use fastutil only where profiling and data shape justify it.
- Re-profile the same scenarios and record both improvements and regressions.
Status: not started. This phase does not begin until the immediate compatibility gate and an initial profile are
complete. The first sensible implementation unit is the whole IRedstonePart.scala file: its six related traits and
load-bearing RedstoneInteractions$ must be characterized and ported together. Do not optimize TileMultipart
storage merely because the source audit found allocations; its list/order/lifecycle contracts must be frozen first.
Exit condition: identified steady-state Scala allocation sites are removed with compatible results.
Phase 5 — Convert built-in tile traits through the existing Java path
- Characterize the interfaces, fields, lifecycle callbacks, and behavior of the Scala-generated pilot tile.
- Port one simple built-in trait as a pilot using
registerJavaTrait. - Verify generated methods, interfaces, field initialization, lifecycle callbacks, and class caching against the Scala version.
- Convert remaining traits in small related groups.
- Document or deliberately relax the Java trait restrictions only when a real trait requires it.
- Preserve pass-through interface behavior.
- For the pilot, explicitly cover OpenComputers'
TSlottedTile.v_partMaprebinding, AE2'sTIInventoryTile.rebuildSlotMap, and ProjectRed/Extra UtilitiesTRedstoneTilebehavior.
Exit condition: built-in behavior is implemented in Java while the established runtime composition mechanism remains stable.
Phase 6 — Convert multipart core and microblocks
- Add characterization coverage for each subsystem immediately before its conversion.
- Convert the central tile, part, registry, placement, rendering, networking, scheduler, and microblock code in dependency order.
- Treat NBT, packets, registration, client/server separation, and rendering state as compatibility-critical.
- Keep recipe scan order and output semantics stable while replacing exception-based early exits.
- Check source and binary compatibility at each public boundary.
Exit condition: normal runtime implementation is Java; any remaining Scala is isolated to compatibility or ASM support.
Phase 7 — Port the ASM subsystem last
- Freeze structural and behavioral fixtures for generated classes before changing the compiler.
- Translate the existing compiler/generator into readable Java while preserving emitted class shapes and cache keys.
- Evaluate GTNHLib ASM helpers where they reduce boilerplate without altering semantics.
- Keep Scala-trait registration while deprecated bridges or supported external Scala traits require it.
- Run ProjectRed's
LightMicroblockexternal Scala-trait fixture and pass-through-interface fixtures against the ported generator. - Decide separately whether a future generator design can avoid custom bytecode generation. Do not couple that experiment to the source-language port.
Exit condition: the composition subsystem is maintainable Java with behavior and generated ABI verified against the reference.
Phase 8 — Decide on Scala runtime removal
Status: decided and deferred. The inventory showed four shipping mods linking against trait $class helpers and
companion singletons, and ProjRed registering its own Scala trait through MicroblockGenerator.registerTrait. Scala
removal is therefore not achievable for the first Java release, and Java-maintainable source is the milestone instead.
Revisit only in a release allowed to break that ABI.
- Measure actual downstream use of Scala descriptors, Scala traits, object singletons, and
$classhelpers. - Publish and complete a deprecation window if compatibility policy permits removal.
- Remove Scala bridges, Scala signature decoding, and the Scala compiler/runtime dependency only in a release allowed to break that ABI.
- Confirm no Scala types remain in published descriptors or runtime loading paths.
Exit condition: Scala removal is either completed deliberately or explicitly deferred as the cost of binary compatibility.
Risk order
| Risk | Work |
|---|---|
| Low | Leaf utilities, value holders, straightforward packets, isolated Java API facades |
| Medium | Registries, recipes, placement logic, render helpers, schedulers, hot-loop rewrites |
| High | TileMultipart, networking/NBT compatibility, tile trait conversion, external API bridges |
| Very high | Runtime composite generator, Scala trait compatibility, removal of Scala runtime |
The work should move from low to high risk while keeping a buildable mixed-language repository. A one-shot conversion would combine source, ABI, lifecycle, data-format, and bytecode-generation failures and make regressions difficult to localize.
Characterization and compatibility test strategy
Extensive tests are both possible and recommended here. Their purpose is not to prove that the current Scala behavior is ideal; it is to make its observable behavior explicit before translation, so every later difference is intentional.
The repository now has a Java-8-compatible JUnit Jupiter suite and a small Forge integration runner. The current baseline is 130 plain-JVM tests and 25 Forge server tests. Minecraft 1.7.10 does not provide the modern GameTest framework, so game-dependent coverage continues through the existing narrow Forge harness rather than a second test framework.
Layer 1 — Plain JVM characterization tests
Run fast tests through the normal Gradle test task, using real implementation classes and small fakes only at world, network, or rendering boundaries. Good targets include:
- Slot masks, part lookup, occlusion and collision decisions.
- Placement grids, side transforms, microblock shape calculations, and recipe matching.
- Registry ordering, duplicate handling, missing-entry behavior, and callback order.
- Scheduler ordering and cancellation with a deterministic clock or tick source.
- Redstone connection and power matrices for all six sides and relevant masks.
- Packet codec logic that does not require a live channel.
- NBT read/write logic that can use real
NBTTagCompoundvalues without starting Forge.
Finite input spaces such as sides, slot masks, and small recipe grids should be covered exhaustively. Larger combinations should use named regression cases plus deterministic property/fuzz tests with a recorded seed. Avoid tests that merely restate the implementation or assert interactions with a large graph of mocks.
Layer 2 — Golden compatibility fixtures
Store compact fixtures under test resources when behavior has a stable serialized or structural representation:
- Canonicalized NBT trees including names, types, values, missing fields, and legacy data; do not depend on unspecified compound-key iteration order.
- Exact packet bytes for representative updates and malformed/truncated input behavior.
- Part identifiers, registration order, and conversion results.
- Public/protected JVM descriptors and required Scala bridge entry points.
- Generated tile superclass, interfaces, fields, methods, access flags, and cache identity. Compare structure and behavior rather than raw class bytes or constant-pool order.
- Small precompiled Java and Scala consumer fixtures built once against the reference dev jar, then loaded against the migrated jar to catch binary linkage failures that source recompilation would hide.
Golden fixtures must be reviewed rather than regenerated automatically when they fail. Otherwise an accidental change can silently redefine the baseline.
Layer 3 — Real Forge integration tests
Use a dedicated test mod/source set launched in an actual Forge environment for behavior coupled to FML, the classloader, worlds, or networking. The harness should fail the Gradle task or process when an assertion fails. It should cover:
- Client and dedicated-server startup, mod lifecycle order, mixin selection, and side-only class safety.
- Registration and creation of representative dynamic tile combinations.
- Add/remove part sequences, ticking, scheduled ticks, redstone neighbor updates, and chunk unload/reload.
- Save with the reference implementation and load with the migrated implementation.
- Server-to-client part description and incremental update packets.
- Loading representative downstream binaries compiled against the reference API.
Keep this harness narrow: a tiny test mod and deterministic scenarios are preferable to a general automation framework. Run server cases routinely; reserve the slower client cases for changes that touch rendering, client packets, or side-specific initialization.
Layer 4 — Irreducible manual and performance checks
Some behavior remains poorly captured by assertions in a legacy client. Retain focused manual checks for visual correctness, selection boxes, particles, input interaction, resource reload, and third-party rendering compatibility. Screenshot comparisons can help, but GPU and renderer differences make them unsuitable as the only oracle.
Performance fixes require the same CPU/allocation scenario before and after the change. Functional tests can prove equivalent results, but they cannot prove reduced allocations or better tick time.
Coverage rule
Coverage percentage is not the goal. The required evidence for an area is:
- Normal behavior, edge cases, invalid input, ordering, and state transitions are represented.
- Compatibility-sensitive bytes, NBT, identifiers, descriptors, and generated interfaces are frozen where applicable.
- At least one real Forge scenario covers code that depends on lifecycle or world state.
- The tests demonstrably pass against the old Scala area before any Java replacement begins.
- The same tests pass unchanged against the Java implementation, except for separately documented bug fixes.
Decisions
Resolved from the consumer audits:
- All 27 binaries in the target pack must keep working without recompilation; UtilitiesInExcess is an additional forward-compatibility target.
- Third-party Scala trait registration is public in practice: ProjectRed registers
LightMicroblock. - Java-maintainable source is the first-release milestone. Scala runtime removal is deferred because shipping mods link Scala descriptors, trait helpers, companions, and external trait generation.
Still open, and only to be decided when they become necessary:
- How long deprecated Scala bridges remain supported after the initial Java release.
- Which known bugs are intentionally fixed during the port rather than after compatibility is established.
- Which GTNHLib release is the minimum supported version once code actually needs it.
- Whether runtime tile composition merits redesign after the Java port is stable.
Effort tracking
The old pre-audit calendar ranges are retired. They mixed the Java source port, ecosystem validation, performance work, and optional Scala-runtime removal into estimates that are no longer useful. Track the remaining work by completed compatibility gates instead:
- Finish the source-only reflection/member guards; the Schematica registry view is repaired.
- Freeze tile ordering, lifecycle, NBT, packet, and generator behavior with compact representative fixtures.
- Capture the first focused CPU/allocation baseline and port the complete redstone unit.
- Convert a representative generated tile-trait group, then the remaining trait groups.
- Convert the multipart/microblock core while keeping the frozen data and consumer contracts green.
- Update the ASM/runtime generator, then run packaged-pack and manual release validation.
Estimate calendar time again after gates 1 and 2. They expose the real cost of hidden consumer contracts and the generated-trait compatibility work. Scala-runtime removal remains a later project and is not part of this estimate.
Findings log
2026-08-14
- Confirmed that the codebase is feasible to migrate incrementally to Java.
- Confirmed that generalized Scala
try/catchoverhead is not present; only a small set of exception-based non-local returns is relevant. - Identified closure/boxing/collection allocations as stronger performance candidates.
- Confirmed that the existing runtime compiler already has a Java trait path.
- Confirmed that public bytecode exposes Scala types and compiler artifacts, so bridges and Scala runtime removal must be separate decisions.
- Confirmed Hodgepodge's normal/early/late UniMixins plus GTNHMixins registration pattern as the reference for fixed mixins.
- Confirmed that UniMixins is not a drop-in replacement for ForgeMultipart's runtime composite-tile generator.
- Confirmed GTNHLib as a viable route to fastutil, subject to pack-aligned versioning and runtime-resolution verification.
- Adopted characterization tests against the existing Scala implementation as a prerequisite for each converted area, backed by golden ABI/data fixtures and real Forge integration scenarios where plain JVM tests are insufficient.
- Bootstrapped JUnit Jupiter and passed an eight-case
IDWritercharacterization pilot against the untouched Scala implementation, covering byte/short/int thresholds and exact encoded bytes. - The pilot found that negative
IDWriter.setMaxvalues select the byte carrier because Scala 2.11 treats0xffffffffas signed-1; current registry callers supply non-negative collection sizes, so this is recorded as a dormant edge case and possible deliberate divergence rather than changed during characterization. - Added a dedicated
functionalTestsource set andrunFunctionalTestServertask. The task starts a real Java 8 Forge dedicated server, loads a test-only FML mod, runs JUnit afterFMLServerStartedEvent, writes legacy JUnit XML, and shuts the server down. - Passed the first two Forge integration checks against the untouched Scala implementation: complete server lifecycle/world startup with all three ForgeMultipart mod IDs loaded, and generation plus constructor-class caching of a
TSlottedTilecomposite with its 27-slot map. - Hardened the Gradle wrapper to delete stale reports and fail when no fresh report is produced, no tests run, or any failure/error is reported. This is necessary because Forge 1.7.10 can terminate after a test-mod exception with process exit code 0.
- Confirmed the Java 8 server lane on Azul OpenJDK 8u492. The current deobfuscated modern-server tasks are not usable as release evidence: Java 21 needs the legacy Security Manager switch and then
Lwjgl3ifyRelauncherTweakerrejects the server launch; Java 25 rejectsSystem.setSecurityManagerbefore Forge loads. Modern-Java validation therefore remains a packaged-server gate rather than a custom test-runner workaround. - Added eight plain-JVM characterization cases for
NormalOcclusionTestandNormallyOccludedPart: empty sets, separation on every axis, face contact, tolerance-sized overlap, real overlap, containment, identical boxes, multiple-box all-pairs behavior, normal-box delegation, partial-box delegation, and parts without occlusion interfaces. - Confirmed that normal occlusion returns
truewhen parts may coexist, despite the source comment saying “true if the test fails.” Face contact and overlaps no larger than CodeChickenLib's1e-5intersection tolerance are accepted; larger overlaps reject placement. Preserve the behavior and correct the misleading documentation separately when this area is ported. - Added nine plain-JVM characterization cases for
PartialOcclusionTest: its fixed 8³ grid and x-major indexing, part-ID encoding, half-voxel coordinate rounding, required visibility, complete-occlusion exemption, cross-part overlap, same-part box overlap, unfilled entries, and the publicJPartialOcclusionoverload. - Confirmed that every non-exempt part needs at least one exclusively owned voxel. Any second write to an occupied voxel permanently changes it to
-1, including overlap between two boxes supplied by the same part; this can make that part fail the test. Preserve this exact dynamic-tile behavior during translation unless it is changed later as an explicitly documented bug fix. - Completed the first behavior-preserving production conversion by replacing
IDWriter.scalawithIDWriter.java. All eight existing encoding cases, all 25 plain-JVM tests, the clean build, and both Java 8 Forge server checks pass unchanged. - Preserved the four legacy Scala function accessor descriptors as deprecated binary bridges and added direct Java
write(MCDataOutput, int)andread(MCDataInput)methods. Recompiled Scala registry callers use the new primitive methods because Scala property auto-application does not apply to accessors declared in Java. - Removed the six
IDWriter$$anonfun$setMax$*compiler artifacts from the packaged jar. Their disappearance and replacement with Java anonymous helper classes is recorded inJAVA_MIGRATION_DIVERGENCES.md; the supportedIDWriterdescriptors remain link-compatible. - Added a frozen Scala 2.11.5 consumer compiled against the reference dev jar. Its constructor and inherited default method call
JPartialOcclusion$classdirectly, so it detects the linkage failure that freshly recompiled tests would miss. - Replaced
TPartialOcclusion.scalawith Java implementations ofPartialOcclusionTestandJPartialOcclusion. The interface keeps its name and method descriptors, whileallowCompleteOcclusion()is now a Java default method and the deprecated$classhelper remains for old Scala binaries. - Passed all ten partial-occlusion behavior/API cases, the frozen Scala binary consumer, all 27 plain-JVM tests, a clean build, and both Java 8 Forge server checks. The existing marker-interface registration remains unchanged and continues to drive runtime tile generation.
- Completed the downstream ABI inventory by constant-pool scan of 240 mod jars in GTNH daily
2026-08-14+678, recorded inJAVA_MIGRATION_ABI_INVENTORY.mdwith the scanner intools/AbiScan.javaand the frozen baseline insrc/test/fixtures/abi/. GitHub code search was rejected as an oracle because it indexes default branches only and cannot see reflection strings or closed-source consumers. - Found 27 consumer jars referencing 35 inherited types, 255 exact member descriptors, 76 other types, and 20 reflective string constants.
- Answered open decision 2: third-party Scala traits are registered externally. ProjRed passes its own
LightMicroblockScala trait toMicroblockGenerator.registerTrait, soregisterScalaTraitand ScalaSignature decoding must survive Phase 7. - Answered open decision 4: Scala runtime removal is not achievable for the first Java release. ProjRed, OpenComputers, ProjectBlue, and ForgeRelocationFMP link against 16 static methods on 8 trait
$classhelpers plus 17 companionMODULE$singletons. - Found only five referenced descriptors containing Scala types, and
TileMultipart.jPartList()already outweighspartList()in downstream use. The Scala bridge surface is much smaller than the initial audit assumed. - Found zero downstream references to
IDWriter, so its four retained Scala function accessors are not load-bearing and can be dropped. - Removed both speculative bridges the inventory proved dead: the four
IDWriterScala function accessors and the wholeJPartialOcclusion$classhelper, along with theReferenceScalaPartialOcclusionfixture that only existed to verify the helper.JPartialOcclusionitself and both of its method descriptors are unchanged. IDWriternow selects a carrier width instead of storing Scala closures, removing the per-callIntegerboxing andFunction1/Function2allocation that the first port had preserved. The nine encoding cases still pass unchanged.- Established the working rule for the remaining phases: check
JAVA_MIGRATION_ABI_INVENTORY.mdbefore writing a bridge, rather than writing one reflexively for every converted file. - Ported
TCuboidPart,JCuboidPartandTCuboidPart$classto Java, the first conversion of a trait whose$classhelper is genuinely load-bearing. All reference descriptors are preserved, verified by diffingjavap -sagainst the reference dev jar, and a frozen Scala 2.11.5 consumer whose forwarders call all four statics loads and runs against the port. - Found the first structural limit of the migration: Scala trait linearization cannot be reproduced by a Java interface, because a superclass method always beats an interface default on the JVM. Recompiled Scala consumers that mix
TCuboidPartinto aTMultiPartsubclass now silently getTMultiPart's empty implementations. Binary compatibility is unaffected, andCuboidPartCharacterizationTestcarries the regression guard, but this applies to every remaining trait that overridesTMultiPartmembers and should be assumed forTFacePart,TNormalOcclusion,TIconHitEffectsandTItemMultiPartas well. - Recorded the consequence for consumers: Scala code that recompiles must extend
JCuboidPartor declare the overrides itself. This belongs in the release notes for the first Java release, not only in the divergence log. - Found a build-order constraint:
compileJavaruns beforecompileScala, so ported Java that still references Scala types must live undersrc/main/scalafor joint compilation, asminecraft/McBlockPart.javaalready does. Files can move tosrc/main/javaonce their Scala dependencies are ported. - Established the fixture recipe for the remaining load-bearing bridges: build a reference dev jar at the pre-port commit, compile the consumer with Scala 2.11.5 under Java 8 with
-target:jvm-1.8against that jar plus the project compile classpath, then store the class base64-encoded undersrc/test/resources/compat/. - Ported the whole
TNormalOcclusion.scalaunit:NormalOcclusionTest,NormalOcclusionTest$,JNormalOcclusion,TNormalOcclusion,TNormalOcclusion$classandNormallyOccludedPart. The singleton and both trait interfaces are descriptor-identical to the reference; the other three add only private members. - Found that Scala emits trait super accessors as
ACC_SYNTHETIC, whichjavachides completely. An abstract synthetic method cannot be implemented by any Java class or by Scala recompiled against a Java interface, socodechicken$multipart$TNormalOcclusion$$super$occlusionTestis emitted as a non-synthetic default returningtrue. Method resolution ignores the flag, so existing call sites are unaffected. Expect the same treatment wherever a remaining trait callssuper. - Found the dangerous shape of the linearization problem.
HollowMicroblocksimply lacked an override, which is easy to spot.PostMicroblockalready had one ending insuper.occlusionTest(npart), which used to route through the trait and now reachesMicroblockdirectly, silently dropping the box test while still compiling. Existingsupercall sites must be audited on every remaining trait conversion, not just missing overrides. - Recorded a second source-only divergence:
NormalOcclusionTestwas a Scalaobject, soNormalOcclusionTest(a, b)apply sugar no longer compiles and recompiled Scala callers must writeNormalOcclusionTest.apply(a, b). Both static forwarders and theMODULE$singleton keep their descriptors, so binaries are unaffected. - Kept
scala.collection.Traversablein two descriptors, as the ABI inventory predicted. They are drained withJavaConversions.asJavaIterator(boxes.toIterator()), which is the one interop route callable from Java. - Removed two more closure artifacts,
NormalOcclusionTest$$anonfun$apply$1and its nested$$anonfun$apply$2, and corrected the scaladoc that claimed the test "returns true if the test fails". - Ported
TFacePart, the first trait where Java default methods are actually safe.TMultiPartdeclares neithersolidnorredstoneConductionMap, so there is no superclass method for a default to lose to. The interface is descriptor-identical to the reference and no in-repo Scala needed changing. - Adopted the resulting rule for the remaining traits: emit default methods only when no class in an implementor's superclass chain declares the same member, otherwise leave the member abstract and add explicit forwarders as
TCuboidPartandTNormalOcclusionrequired. - Made
TFacePartinheritable from Java as a side effect. Both members were abstract on the reference interface, sominecraft/McSidedMetaParthad to declare them even to accept the defaults. That class stays descriptor-identical, so the change is purely additive. - Ported the whole
TIconHitEffects.scalaunit:IconHitEffects,JIconHitEffects,JIconHitEffects$class,TIconHitEffectsandTIconHitEffects$class. Both interfaces are descriptor-identical to the reference and the other three add only a private constructor. - Confirmed the default-versus-abstract rule discriminates correctly within a single file.
JIconHitEffects.getBreakingIconbecame a default becauseTMultiPartdoes not declare it, whileTIconHitEffects.addHitEffectsandaddDestroyEffectsstayed abstract because it does.MicroblockClientneeded explicit forwarders only for the latter pair. - Removed
IconHitEffects$and itsMODULE$field. No jar in the pack references it, in bytecode or by name, so it is dead under the inventory rule. This is the first public class the migration has dropped rather than a method, and it contrasts withNormalOcclusionTest$, which is referenced and was kept. - Preserved evaluation order inside
addDestroyEffectsrather than hoisting the tile read, because the characterization pins which work happens before a null tile fails. - Established that particle appearance cannot be asserted headless. Icon selection, side order and bounds scaling are covered by tests; the visual result stays on the manual checklist.
- Ported
ItemMultiPart.scalaintoJItemMultiPart,TItemMultiPartandTItemMultiPart$class. The interface is descriptor-identical to the reference,JItemMultiPartgains only additive statics, and the bridge keeps all three public statics for ProjRed. - Generalised the default-versus-abstract rule.
TItemMultiPartextendsItemrather thanTMultiPart, and the same split applied:getHitDepthbecame a default becauseItemdoes not declare it, whileonItemUsestayed abstract becauseItemdoes. What matters is the implementor's actual superclass, notTMultiPartspecifically. - Confirmed that placement logic is testable headless.
onItemUseshort-circuits as soon asnewPartreturns null, before any world, player or stack access, so the depth branch, the neighbour offset and the shared mutatedBlockCoordcan all be asserted with null arguments. - Added the first functional coverage of runtime class generation interacting with a ported type. Microblock classes are built by ASM at run time, so a plain-JVM test cannot show that a generated class resolves a Java interface default; the Forge server suite now generates a
FaceMicroblockand asserts it inheritsredstoneConductionMap, and generates aHollowMicroblockand asserts its own0x10andfalsestill win.
2026-08-15
- Ported the six marker interfaces:
TSlottedPart,IRandomDisplayTick,INeighborTileChange,TRandomUpdateTick,ISidedHollowConnectandIMicroMaterialRender. All six are member- and descriptor-identical to the reference, and the seven implementors and mixin tiles were diffed as well and are unchanged member for member. - Confirmed that five of the six were already pure abstract interfaces in bytecode with no
$classhelper, so their conversion had no bytecode consequence at all. Exactly one class left the jar:TRandomUpdateTick$class. - Applied the default-versus-abstract rule to
TRandomUpdateTick.onWorldJoinand got the failing answer:TMultiPartdeclaresonWorldJoin, so a default would be shadowed by the superclass and the auto-registration would silently never run. It stays abstract, and implementors declare it and callTickScheduler.loadRandomTickthemselves, whichRedstoneTorchPart— the only implementor in this codebase — already did. - Applied the bridge rule to
TRandomUpdateTick$classand got a clean negative: no jar in the pack referencesTRandomUpdateTickin any form, and the frozen baseline contains exactly the eight$classhelpers the inventory lists. No bridge was written, following theIDWriterprecedent. The accepted cost is a recompiled-Scala-consumer break with no shipping consumer. - Found that
IMicroMaterialRenderis implemented for every part solely byTMultiPart's Scala-styleworld/x/y/z/getRenderBoundsaccessors. Renaming any of them to a bean accessor would silently unimplement the interface, so the names are now pinned by a characterization test rather than left to reviewer attention. - Established that for interfaces carrying no implementation, the characterization is the shape: every member abstract and public, no superinterface, and the exact member set. That is enough to catch the two realistic failure modes, a stray default and a renamed accessor.
- Noted that
IRedstonePart.scalais misleadingly named and is not a marker-trait file. It carries six traits plusRedstoneInteractions, whoseMODULE$is load-bearing, and was moved out of the low-risk group. - Noted a documentation gap, not addressed here: this log was last appended for the
TItemMultiPartport. The eight ports between it and this entry —TEdgePart,Saw, both registries,TileMultipart,TMultiPart,TickSchedulerandBlockMultipart— are recorded inJAVA_MIGRATION_DIVERGENCES.mdbut never made it here, so the "Current status" section above should be read with that in mind. - Ported
MultipartHelper,MultipartHelper$andMultipartHelper$IPartTileConverterto Java. All three are public-member- and descriptor-identical to the reference and the full emitted class list is unchanged, so this port neither added nor removed a class. - Kept
MultipartHelper$on the strength of a reflective string constant alone. It is not among the 17MODULE$singletons read from bytecode and no jar links against it, but guidenh names it, and the inventory warns that removing a companion breaks such consumers invisibly. This is the opposite call toIconHitEffects$, which was dropped because nothing referenced it in bytecode or by name, and it establishes that theMODULE$list alone is not sufficient grounds to delete a companion. - Found a reusable characterization technique: a class that cannot class-initialize headless is a probe for control flow.
MultipartSaveLoadreflects intoTileEntity's static maps throughObfMappingand always throws under a plain JVM, socreateTileFromNBTreturning null rather than raising proves the id guard short-circuits before theloadingWorldassignment. AssertLinkageErrorrather than the exact type, because the first attempt raisesExceptionInInitializerErrorand later ones raiseNoClassDefFoundError. - Confirmed that erasure does not weaken
IPartTileConverter.convert. The cast toTcompiles away, but theClassCastExceptiona mismatched tile produces comes from the synthetic bridge on the subclass overridingconvertMulti(T), which is the same mechanism Scala'sasInstanceOf[T]relied on. It is now pinned by a test, because the code reads as though the check was lost. - Added five Forge server tests, doubling that suite, because most of this class cannot run headless. They cover tile construction through the ASM generator, the NBT round trip through the save/load hooks,
registerTileConverterappending to a ScalaMutableListfrom Java, andsendDescPacketagainst a loaded chunk. - Dropped the two commented-out blocks the reference carried, the
PlayerInstance.playersInChunkreflection and the multi-tilesendDescPackets, rather than reproducing dead Scala as dead Java. The reason they existed, a missing forge access transformer, is now in the class javadoc. - Read guidenh's actual source at
6137525rather than inferring from its constant pool, and recorded the exact reflective member list inJAVA_MIGRATION_ABI_INVENTORY.md. The scan could see the 20 names; only the source shows which members are looked up on them, and none of it is visible to the ABI diff. - Found that
MultipartGenerator$.MODULE$is load-bearing through reflection.generateCompositeTileisprivate[multipart], so no static forwarder exists and guidenh's static attempt always misses, leaving the companion as the only route. Phase 6/7 must keep it. - Found that
MicroblockGenerator$.createis matched by exact parameter types, withMicroblockClass's fully qualified name string-compared. Widening a parameter or renaming the class breaks the lookup while every call site still links. - Verified against the already-ported
TileMultipartthatpartList_$eq(scala.collection.Seq),loadParts,notifyTileChangeandmarkRenderall survived.partList_$eqis a Scalavarsetter with no Java-facing equivalent and is reflectively load-bearing, so dropping it for a list mutator would have broken guidenh invisibly. It was kept. - Confirmed the MultipartHelper port satisfies guidenh directly: it resolves
createTileFromNBTas a static on the plain class and only falls back toMultipartHelper$.MODULE$if that misses, so the retained companion is belt-and-braces rather than the primary path. - Ported
TileCacheto Java, the first conversion free to change shape rather than preserve it. It has zero downstream references in bytecode and does not appear in guidenh's reflective names, somap()became ajava.util.Map,add/removebecamevoid, andapplyreturns a nullableFlaggedTileinstead of ascala.Option. No internal caller used any of the discarded return values. - Dropped
TileCache$,TileCache$FlaggedTile$and the whole case-class machinery onFlaggedTile. It is only ever a map value, never compared, hashed, printed or destructured. This is theIconHitEffects$case rather than theMultipartHelper$one: nothing names it in bytecode or by string. - Pinned an unreachable branch before removing it. The reference's
findTileends incase _ => null, butSome(FlaggedTile(t, rem))matches whatever the flag holds, so a tile flagged removed is returned like any other and only the warning is suppressed. The functional test asserts that before the port so the Java version cannot quietly start returning null. - Confirmed the adapter approach works for ports that change collection types. The characterization test named
scala.Optionin exactly one helper, so the port's test diff was two lines and every behavioral assertion carried over untouched. - Ported
PacketScheduler,IScheduledPacketPartandTScheduledPacketPart.IScheduledPacketPartis descriptor-identical,schedulePacketis unchanged, andTScheduledPacketPart.readstays abstract becauseTMultiPartdeclares it. - Found the case the default-versus-abstract rule splits within a single interface.
readcannot be a default becauseTMultiPartdeclares it, butwriteScheduledandreadScheduledcan, becauseTMultiPartdeclares neither. Making the latter two defaults restores what a Scala implementor already got from the trait for free; only Java implementors ever had to write them out. - Added
TScheduledPacketPart.readMaskas a Java 8 interface static, carrying the dispatchTScheduledPacketPart$class.readused to hold. Where a trait's central member cannot become a default, an interface static plus a documented one-line forwarder is the replacement, and it is the pattern to reuse. - Widened
sendScheduledfromprivate[multipart]to public. Its only caller is incodechicken.multipart.handler, and Java has no scope spanning a package and its siblings, so package-private would not compile. Expect this whereverprivate[multipart]crosses into the handler package. - Recorded that the whole subsystem has no implementors at all, in this codebase or in the pack. It is a third-party extension point, which is why every behavioral test had to construct its own part.
- Confirmed the Forge server suite can drive the packet path without players connected.
MultipartSPH.getTileStreamonly needs a non-remote world and a position, so a part bound to a tile withsetWorldObjis enough to exercisegetWriteStream. - Ported
ControlKeyModiferandControlKeyHandler.isControlDown(EntityPlayer)andisClientPressing()keep their descriptors;map()became ajava.util.Map, and the implicit-conversion pairplayerControlValue/ControlKeyValuewas dropped because it only ever existed to give Scalaplayer.isControlDownsugar and the reference already shipped the explicit static "for Java users". - Kept the misspelling in
ControlKeyModifer. It is the published type name; only the file name, which saidControlKeyModifier.scala, was corrected. Renaming the type is an API change with no forcing reason and should be a deliberate decision rather than a side effect of a port. - Converted the first Scala
objectthat extends a class rather than being a plain singleton.ControlKeyHandleris now an ordinaryKeyBindingsubclass with anINSTANCEconstant, which drops the twelve static forwarders Scala generated for inheritedKeyBindingmembers along with the companion. The registration sites passControlKeyHandler.INSTANCE. - Found that a Forge
FakePlayermakes the server half of player-dependent code testable.FakePlayerFactory.getMinecraft(worldServer)yields a player whose world is not remote, which is exactly the branch the server takes, and it needs no connection. - Recorded that the client half remains untestable in both harnesses.
isClientPressingis only ever set from a client tick, so the key binding, the press/release packet and the client branch ofisControlDownare all manual checks. - Removed both package objects rather than porting them. A Scala package object compiles to a class named
package, which is a Java keyword, so no Java source can declare or even name it; the characterization had to reach both throughClass.forName. Each held one member, aloggeralias for its proxy, so the indirection was inlined at its eight call sites instead of being given an invented Java home. - Proved the substitution was an identity before making it. The functional test asserted that each alias returned the very instance its proxy holds, so replacing
loggerwithMultipartProxy.logger/MicroblockProxy.loggercannot change behavior.ConfigContentandMultipartGeneratorare descriptor-identical afterwards. - Noted the first case where the migration's answer is deletion. Zero downstream references plus an impossible target name means there is nothing to preserve, and inventing a
MultipartLoggertype to hold a one-line forwarder would add API rather than remove it. - Emptied the low-risk queue. Everything remaining is the medium group or later, so the next piece of work should be chosen deliberately rather than taken off the top of a list.
- Ported
MultipartRendererin theTickScheduler$shape, with the companion holding the implementation and the plain class holding static forwarders. Forge registers the singleton itself and guidenh resolves the static first, so both halves are load-bearing for different reasons and the emitted class list is unchanged. - Applied the reflective-name rule for the second time, and this is the case it was written for:
MultipartRendererhas no bytecode consumer at all, only guidenh string constants, and both the class and its companion had to survive. - Found a Scala-to-Java trap that is not silent but will recur: uniform access makes
renderer.hasOverrideBlockTextureread the same whether it is a field or a no-arg method. It is a method, and the port did not compile until it grew parentheses. Every remaining renderer conversion will meet this. - Dropped the three static forwarders Scala generated for inherited
TileEntitySpecialRenderermembers, the same category as the twelveKeyBindingforwarders dropped fromControlKeyHandler. - Dropped an unused
ThreadSafeISBRHimport. It annotated nothing and appears nowhere else; if the intent was to mark this ISBRH thread-safe for Angelica then the annotation was never applied in the reference either, which is worth checking independently of the migration. - Recorded that this port adds nothing to the automated suites and everything to the manual checklist. Static and dynamic rendering, the breaking overlay and the render id all need a client.
2026-08-27
- Reproduced Schematica 1.12.6's exact
ReflectionHelperlookup of the privateMultiPartRegistry$.codechicken$multipart$MultiPartRegistry$$typeMapfield. The test failed against the existing Java port withUnableToFindFieldException, matching Schematica's silent integration-disable path. - Restored the exact private field name and
scala.collection.mutable.Mapdescriptor as Scala's live wrapper over the canonical Java registry map. The wrapper adds no copied state or synchronization path. - Proved through the reflected Scala view that Schematica can resolve a factory and that the Java registry immediately sees the same entry. The focused registry suite and all 126 plain-JVM tests pass.
- Added four source-consumer structural guards without adding downstream mods as test dependencies. They pin GuideNH's
two
BlockMicroMaterialmixin targets, Et Futurum's mutable static button-orientation arrays, and Iguana's reflectedItemSaw.harvestLevelfield. - Reproduced Galacticraft's name-only method scan and froze its dangerous assumption: exactly one public
MicroMaterialRegistry.registerMaterialmethod may exist, it must accept(IMicroMaterial, String), andBlockMicroMaterial(Block, int)must remain reflectively constructible. All 130 plain-JVM tests pass. - Accepted the dedicated-server EULA locally in ignored
run/server/eula.txt, enabling the Forge characterization suite without adding a distributable acceptance file to the repository. - Froze tile NBT order with two different built-in parts: the outer tile
id, orderedpartsentries and per-partid/payload values survive reconstruction, andjPartListpluspartMapreproduce the same order and slots. - Froze add/remove callback order, list publication, slot binding and detachment in a live Forge world. The plain-JVM
replacement test also proves that a successful
canReplacePartquery does not mutate order or bindings. - Reproduced MatterManipulator's live-tile relocation shape. Removing the tile first calls
onWorldSeparatefor each part in list order; after reinsertion,onMovedcalls each part'sonMovedand defaultonWorldJoin, again in list order. The original generated tile, part instances, order, slot map and tile references survive. - Froze the complete logical chunk-description payload around the same torch/button pair: packet type, chunk coordinates, tile count, nibble-relative X/Z, full Y, part count, sorted runtime part IDs, part order and both meta bytes. CodeChickenLib's deferred Deflater transport step is deliberately outside this FMP fixture.
- The expanded baseline is 130 plain-JVM tests and 25 Forge server tests, all passing.