51 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
Work continues on algent/java. The low-coupling queue, core part/tile types, registries, handlers, factories,
placement/render helpers, both generators and all built-in tile traits are Java. Two files still contain generated
microblock implementations in Scala, alongside the compiler/signature/analyser compatibility shells. The common,
face, corner, edge and post traits retain inheritance/bridge declarations over Java behavior. Composite generation,
Java-trait rewriting and compiler startup also delegate to Java helpers. Abstract Java mixins and Java-path side-only
filtering are complete; multiple Scala-trait inheritance still needs its metadata. The next bounded target is
HollowMicroblock in microblock/HollowMicroblockTraits.scala, followed separately by its client trait. Retain the
post lifecycle/super-dispatch bridges and the ScalaSignature path-dependent model bridges.
Start with JAVA_MIGRATION_HANDOFF.md for the exact source/test baseline, workflow and Java-source limitations. Read both the ABI inventory and consumer audit before changing compatibility surfaces. Completed-target evidence is in the history; the divergence ledger records only effective compatibility differences.
The source-only consumer guards, ordered tile lifecycle/NBT/packet fixtures and generated Scala/Java trait fixtures are in place. Schematica's private registry-map view is restored. The tile equality/callback regressions and the generated client-render dispatch crash are fixed; the user confirmed placement no longer crashes. Broader manual client checks and full-pack profiling remain release gates.
Focused traversal/redstone allocation improvements are recorded in the profile. GTNHLib/UniMixins remain conditional on concrete need. Scala runtime removal is deliberately deferred.
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.
Reference classfile inventory
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 these allocation patterns; the named ports have now resolved them:
- The earlier Java
TileMultipart.updateEntity()traversed throughoperate(Function1), whoseparts()helper materialized anArrayList, backing array, Scala iterator and Java-conversion wrappers per call. - The former Scala
TRedstoneTilequeries created closures andscala.runtime.IntRefboxes; the Java trait now walks the normal immutable list without allocation while preserving an arbitrary-Seqfallback. - Several Scala 2.11 collection, range, and
JavaConversionspaths create closure objects, boxed primitives, iterators, or temporary collections. - The former
TSlottedTile.canAddPartandMicroRecipescans used exception-based non-local returns; both are now ordinary Java loops. - 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.
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.
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 or abstract Java mixin class into the interface/static-helper form used by the generator.
The Java path rejects Java interfaces, inner classes, static initializers, and constructors with arguments. Abstract inputs retain their abstract methods as interface contracts while later mixins provide the implementation. 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. See
JAVA_MIGRATION_PROFILE.md. - 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. 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.
Immediate compatibility gate — complete
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
TileMultipartupdate/operate traversal without per-call collection allocation. - Rewrite redstone queries without closure allocation or
IntRefboxing. - Replace non-local returns in recipe scans with ordinary Java control flow.
- Replace the remaining non-local return in the generated
TSlottedTileslot scan. - Keep fastutil out of these paths because profiling did not justify another dependency or data structure.
- Re-profile the same scenarios and record both improvements and regressions.
Status: complete for the measured targets. 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
on the normal immutable-list path.
MicroRecipe is also Java: all five recipe forms and precedence are characterized, its published Scala façade remains,
and its closure-backed scans and non-local returns are gone. TPartialOcclusionTile completed the simple no-field
Java-trait pilot, and TSlottedTile completed the stateful field/lifecycle checkpoint while removing the remaining
slot-scan closures and exception-backed return. The paired TRedstoneTile run removed 80.5 B per three-query iteration
and improved throughput by 20.3% with an identical checksum.
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 direct class shape, generated interface, super dispatch, behavior, and class caching of a no-field pilot.
- Port one simple built-in trait as a pilot using
registerJavaTrait. - Verify generated field accessors, initialization, copying, lifecycle callbacks, super bridges, and class caching
on the stateful
TSlottedTilecheckpoint. - Characterize ProjectRed/Extra Utilities redstone calls and port
TRedstoneTilewith an immediate paired profile. - 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.
- Keep the completed OpenComputers
TSlottedTile.v_partMapmutation/rebinding case green and cover ProjectRed/ Extra Utilities behavior beforeTRedstoneTile. - Explicitly cover AE2's
TIInventoryTile.rebuildSlotMapbefore 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
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.
Phase 6 — Convert multipart core and microblocks
Status: core code, factories, ordinary helpers and common/face/corner/edge/post microblock trait behavior are Java. Two files still contain generated trait implementations. Extract their behavior while retaining Scala declarations where multiple-trait inheritance still needs signature metadata; abstract Java mixins and side filtering alone do not replace that metadata. The following gates continue to apply to those remaining units; completed per-type evidence is in the history.
- 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.
- Allow abstract Java mixins whose base type is abstract, skipping their abstract members instead of rejecting the
class. Required before any Java mixin over
Microblockis possible. See Phase 10. - Implement
@SideOnlymember stripping on the Java mixin path, matching whatlistSideOnlydoes for Scala signatures. Required before a client-only Java mixin method is safe on a dedicated server. See Phase 10. - 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.
Pre-merge cleanup
- Relocate Java sources from
src/main/scalatosrc/main/javaonce their remaining Scala dependencies no longer require joint compilation; document any compatibility/ASM Java sources that must stay in the joint source set. - Revisit
compileScala.scalaCompileOptions.force = trueafter relocation and keep it only if generated-version or remaining joint-compilation inputs still require it. - Refresh
README.mdfor the Java-first codebase while retaining Scala IDE guidance for any sources that remain. - Move the durable migration documents under
docs/migration/and decide whether the historical running plan is archived or removed before merge. - Complete and record the relevant checks in
JAVA_MIGRATION_MANUAL_CHECKS.mdagainst a representative client and GTNH pack before release.
Exit condition: source layout, contributor guidance and durable migration documentation match the codebase being merged, and all release-required manual checks have recorded results.
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.
Complete Scala removal is not the goal in its own right. scala-library stays in the pack regardless of what FMP
does, because OpenComputers (843 Scala files) and ProjectRed (171) are Scala end to end and are not being ported.
The value of removing Scala from FMP is FMP's own maintainability and hot-path allocation, not a pack-level
dependency win. Phase 10 is what actually retires individual items on this list; each Scala shape removed here needs
a corresponding released consumer version there.
- 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.
Phase 9 — Deprecate the Scala-shaped API and mark the internal boundary
Status: planned. This phase does not redesign the API. A surface audit against all 28 consumer checkouts found the
published API is already largely Java-shaped: TMultiPart is an ordinary abstract Java class with conventional
lifecycle, render, NBT, and packet methods, and IPartFactory2, IPartConverter, IMicroMaterial, PartMap,
RedstoneInteractions, and the occlusion interfaces need no replacement. The remaining problems are a short list of
signatures that still carry Scala types, and a boundary problem that is larger than it looks.
The governing rule is: deprecate only where a replacement already exists or is added in the same change. A deprecation with nowhere to go is noise a consumer cannot act on, and these bridges are being retained deliberately for years. Adding the Java sibling and marking the Scala-shaped entry deprecated is one change, not two.
Apply siblings, deprecations and internal-marker javadoc together when the relevant API is being changed. Most implementations are already Java; remaining work is at the specific boundaries below. Keep unrelated API changes separate from mechanical compiler extraction, and do not add a deprecation without its replacement.
9.1 — Scala-typed signatures
Each row keeps its existing descriptor for binary compatibility and gains a Java-shaped sibling. Two rows already have their sibling and only need the annotation and javadoc.
| Deprecate | Java-shaped replacement | Notes |
|---|---|---|
TileMultipart.partList(): scala.collection.Seq |
jPartList(): java.util.List |
Sibling already exists |
MultiPartRegistry.registerParts(IPartFactory2, scala.collection.Seq) |
registerParts(IPartFactory2, String...) |
Sibling already exists |
MicroMaterialRegistry.getIdMap(): scala.Tuple2[] |
materialCount(): int plus existing materialName(int) and getMaterial(int) |
The array index is the material ID, so no pair or map type is needed |
TileMultipart.operate(scala.Function1<TMultiPart, BoxedUnit>) |
forEachPart(java.util.function.Consumer<TMultiPart>) |
Preserve the existing skip-unbound-part behavior |
TileMultipart.occlusionTest(scala.collection.Seq, TMultiPart) |
occlusionTest(Collection<TMultiPart>, TMultiPart) |
|
TileMultipart.loadParts(scala.collection.Iterable) |
loadParts(Collection<TMultiPart>) |
Schematica and GuideNH reflect the Scala descriptor; see Phase 10 |
TileMultipart.partList_$eq(scala.collection.Seq) |
setPartList(List<TMultiPart>) |
GuideNH reflects the _$eq name; see Phase 10 |
TileMultipart.renderID() / renderID_$eq(int) |
getRenderID() / setRenderID(int) |
|
TileMultipart.getOrConvertTile2(): scala.Tuple2<TileMultipart, Object> |
Small immutable result type with named accessors | No consumer in the audited set calls this |
Explicitly not renamed: TMultiPart.world(), x(), y(), z(), and tile(). These carry Scala accessor naming
but no Scala type, so renaming is cosmetic churn across 27 consumers with no compatibility or performance payoff.
tile() is additionally unsafe to rename toward getTile(), which already exists with a different return type; a
same-name overload there invites a silent wrong-overload bind.
- Add the missing Java-shaped siblings and route each Scala-shaped entry through it in one direction only.
- Mark all nine rows
@Deprecatedwith javadoc naming the replacement. - Confirm every original descriptor still exists in the ABI fixture after the change.
9.2 — Mark the internal boundary
Scala's private[multipart] compiles to public. As a result the published surface currently advertises implementation
hooks as though they were API, and a consumer author cannot distinguish addPart from addPart_do. This is a more
practical API defect than the Scala types above, and the fix is javadoc only: no rename, no descriptor change, no
deprecation, and no new dependency for a marker annotation.
Verified against all 28 consumer checkouts as having zero external callers:
TileMultipart.addPart_impl, addPart_do, remPart_impl, writeAddPart, partAdded, partRemoved, from,
copyFrom, loadFrom, setValid, getOrConvertTile2, operate; MicroMaterialRegistry.setupIDMap,
calcMaxCuttingStrength, loadIcons, writeIDMap, readIDMap.
Two similar-looking members are externally load-bearing and must not be marked internal:
| Member | Consumer | Call site |
|---|---|---|
TileMultipart.bindPart |
OpenComputers | li/cil/oc/integration/fmp/PrintPart.scala:171 |
TileMultipart.internalPartChange |
ProjectRed | mrtjp/projectred/integration/gatepartrs.scala:74 |
- Add an internal-marker javadoc line to each zero-caller member listed above.
- Leave
bindPartandinternalPartChangedocumented as supported API and add them to the consumer audit's cross-cutting map. - Do not add an annotations dependency for this; javadoc is sufficient and changes no descriptor.
Exit condition: every Scala-typed public entry has a documented Java-shaped replacement and a deprecation pointing at it, the implementation-hook members are documented as internal, and the ABI fixture is unchanged.
Phase 10 — Upstream consumer cleanup
Status: planned, unsequenced. This phase does not block any other phase, and parts of it can start immediately, including before the Java port merges. Its purpose is to stop consumer-side hacks from dictating FMP's internal design.
Several consumers reach FMP through private fields, Scala-mangled names, name-only reflection, or third-party Scala traits. Today each one forces FMP to preserve an internal shape it would otherwise be free to change. Because all 27 consumers are GTNewHorizons forks, every one of these is patchable upstream. Extra Utilities is the only exception; it is decompiled-only and is being replaced by UtilitiesInExcess, so it constrains FMP until it is retired from the pack rather than being fixed.
The standard pattern is a three-step ratchet, and only the first step is on FMP's critical path:
- FMP adds a public, supported equivalent. Additive, no ABI break, safe to land at any time.
- The consumer is patched to use it and released.
- FMP drops the private shape in a release allowed to break that ABI. Feeds Phase 8.
Cleanup targets
| Consumer | What FMP is currently forced to preserve | Upstream fix | Can start |
|---|---|---|---|
| ProjectRed | Runtime Scala-signature decoding and external trait registration, reached through MicroblockGenerator.registerTrait(classOf[LightMicroblock]) |
Rewrite the ~60-line LightMicroblock trait as a Java mixin registered through the registerJavaTrait path |
FMP compiler prerequisites complete; consumer rewrite and release remain |
| Schematica | Private Scala-mangled field codechicken$multipart$MultiPartRegistry$$typeMap, cast to scala.collection.mutable.Map |
FMP exposes a supported registry lookup; Schematica uses it instead of the field | After step 1 |
| GuideNH | Companion-only MultipartGenerator$.MODULE$.generateCompositeTile and MicroblockGenerator$.create; partList_$eq(scala.collection.Seq); mixin into private BlockMicroMaterial.block and .meta |
FMP exposes supported static entry points and setPartList(List); GuideNH targets those and public material accessors |
After step 1 and Phase 9.1 |
| Et Futurum Requiem | Mutable static int[] ButtonPart.metaSideMap and sideMetaMap must stay public and mutable |
FMP exposes a supported orientation-override API; Et Futurum uses it | After step 1 |
| IguanaTweaksTConstruct | Private ItemSaw.harvestLevel field name and type |
FMP exposes a supported harvest-level setter; Iguana uses it | After step 1 |
| Galacticraft | Selects the first public method named registerMaterial without checking its signature, so FMP cannot add any overload of that name |
Make the reflection check the parameter types | Immediately; independent of the port |
| UtilitiesInExcess | MicroMaterialRegistry.getIdMap(): scala.Tuple2[] |
Both call sites read only the name, so materialCount() from Phase 9.1 plus the existing materialName(int) covers them; no material object is needed |
After Phase 9.1, before it enters the pack |
| UtilitiesInExcess | Not an FMP constraint, but a shipping hazard: the server factory reads NBT key material while MaterialBasedPart.save writes mat |
Fix on the UtilitiesInExcess side; FMP must not special-case it | Immediately; no FMP change needed |
Galacticraft's reflection signature check needs no FMP change. Its wrong-overload failure is silent because the
reflection sits inside an empty catch (Exception).
ProjectRed's LightMicroblock is the audited external constraint on retiring runtime Scala-signature decoding.
Its Java rewrite removes that external dependency only after the updated consumer is released into the pack;
decoder removal also requires retiring internal Scala trait inputs and resolving retained model bridges.
The rewrite has two Phase 7 prerequisites:
- Abstract Java mixins over an abstract base — complete.
registerJavaTraitnow admitsACC_ABSTRACTclasses, retains declared abstract members on the generated interface, and omits them from the static helper and concrete method metadata until a later mixin supplies an implementation. A no-argument mixin constructor may call an argument-taking base constructor; that direct call is discarded because the generated composite invokes the real base constructor before trait initialization. @SideOnlystripping on the Java path — complete.registerJavaTraitchecks both visible and invisible annotations before collecting fields, signatures or methods. Opposite-side members are omitted; an excluded no-argument constructor produces an empty$init$so generated composites remain valid without executing its body, including when Forge stripped it before registration. Current-side members retain their generated behavior.LightMicroblock.renderDynamiccan therefore remain@SideOnly(Side.CLIENT)when ProjectRed rewrites the trait to Java, even though itsaddTraitsignores theclientargument.
Both compiler prerequisites for the single-parent ProjectRed rewrite are complete. FMP's own microblock traits also use multiple Scala-trait inheritance: their implementation can move to Java helpers, while removing their Scala declarations needs a separate inheritance strategy. Removing external Scala-signature support still waits for a released ProjectRed Java rewrite.
UtilitiesInExcess is the cheapest case in the table because it is not yet in the pack. Anything fixed before it ships never becomes a compatibility obligation at all.
Its NBT key mismatch is real but currently mild, and the detail matters for whoever fixes it. loadPart is always
followed by part.load(tag) on every audited path, including BuildCraftCompat's schematic restore, so the factory's
wrong material is corrected immediately afterwards. The visible symptom is therefore one logged
Missing mapping for part with ID: per part per load, from materialID("") falling through to the missing-material
placeholder, rather than lost material data. Extra Utilities writes mat as well, in PartMicroBlock,
PartConnecting, and PartPipeJacket, so correcting the key also matches the legacy tags reached through
UtilitiesInExcess's extrautils:* aliases; there is no legacy-conversion risk in the fix.
- Land the two Phase 7 Java-mixin prerequisites with generated Java-trait fixtures.
- Land the ProjectRed
LightMicroblockJava rewrite with a fixture proving equivalent generated microblocks on both sides. - Land the Galacticraft reflection signature check.
- Fix the UtilitiesInExcess
mat/materialkey mismatch and itsgetIdMap()use before it enters the pack. - Add the supported public equivalents needed by Schematica, GuideNH, Et Futurum, and Iguana as additive API.
- Patch those four consumers and record the released versions that no longer need the private shapes.
- Only after a consumer's released version is in the pack, move its retained private shape onto the Phase 8 removal list.
Consumer migration remains opportunistic. Nothing here justifies a coordinated lockstep release of the pack's most load-bearing block system; the value is in removing FMP's design constraints, not in reaching zero deprecated call sites.
Exit condition: no consumer-side hack constrains an FMP internal that the port would otherwise be free to change, or each remaining constraint is recorded with the released consumer version required to lift it.
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 uses Java-8-compatible JUnit Jupiter and the existing Forge integration runner; the current counts are in the handoff. Minecraft 1.7.10 has no modern GameTest framework, so initialization-dependent tests use this Forge harness. The dedicated server is headless and does not establish client rendering correctness.
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. Phase 9 fixes the policy for adding deprecations (only alongside a replacement); the removal window is still open and is gated by Phase 10.
- 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
Track remaining work by completed compatibility gates, not the retired pre-audit calendar estimates:
- Extract the remaining compiler algorithms with unchanged characterization and generated output.
- Characterize and port the remaining generated microblock behavior, retaining necessary trait inheritance metadata.
- Resolve or explicitly retain the Scala model bridges; finish the applicable API and pre-merge cleanup gates.
- Complete packaged-pack, client and performance validation with recorded results.
Reflection/member guards, core ordering/data fixtures, the first profiles and built-in tile-trait ports are complete. Scala-runtime removal remains a separate compatibility decision.
Findings log
The dated evidence log is archived in docs/migration/HISTORY.md, including reference revisions, test results, ABI comparisons and resolved regressions. Add future per-target findings there. The working handoff carries the current baseline and next target.