From 785991f270a2c40b975a2b8a93189b01946c1970 Mon Sep 17 00:00:00 2001 From: Algent Date: Wed, 2 Sep 2026 17:13:53 +0200 Subject: [PATCH] docs: condense migration divergence log --- JAVA_MIGRATION.md | 9 +- JAVA_MIGRATION_DIVERGENCES.md | 3323 ++------------------------------- JAVA_MIGRATION_HANDOFF.md | 8 +- 3 files changed, 202 insertions(+), 3138 deletions(-) diff --git a/JAVA_MIGRATION.md b/JAVA_MIGRATION.md index 8525fb2..e24bd02 100644 --- a/JAVA_MIGRATION.md +++ b/JAVA_MIGRATION.md @@ -768,7 +768,10 @@ generated-trait compatibility work. Scala-runtime removal remains a later projec - Found that `IMicroMaterialRender` is implemented for every part solely by `TMultiPart`'s Scala-style `world`/`x`/`y`/`z`/`getRenderBounds` accessors. 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.scala` is misleadingly named and is not a marker-trait file. It carries six traits plus `RedstoneInteractions`, whose `MODULE$` 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 `TItemMultiPart` port. The eight ports between it and this entry — `TEdgePart`, `Saw`, both registries, `TileMultipart`, `TMultiPart`, `TickScheduler` and `BlockMultipart` — are recorded in `JAVA_MIGRATION_DIVERGENCES.md` but never made it here, so the "Current status" section above should be read with that in mind. +- Historical documentation gap: the ports between `TItemMultiPart` and this entry — `TEdgePart`, `Saw`, both + registries, `TileMultipart`, `TMultiPart`, `TickScheduler` and `BlockMultipart` — did not receive dated findings + here. Use the handoff for their current status and git history for the original validation narrative; the divergence + ledger now records only their effective compatibility differences. - Ported `MultipartHelper`, `MultipartHelper$` and `MultipartHelper$IPartTileConverter` to 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 17 `MODULE$` 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 to `IconHitEffects$`, which was dropped because nothing referenced it in bytecode or by name, and it establishes that the `MODULE$` 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. `MultipartSaveLoad` reflects into `TileEntity`'s static maps through `ObfMapping` and always throws under a plain JVM, so `createTileFromNBT` returning null rather than raising proves the id guard short-circuits before the `loadingWorld` assignment. Assert `LinkageError` rather than the exact type, because the first attempt raises `ExceptionInInitializerError` and later ones raise `NoClassDefFoundError`. @@ -1230,3 +1233,7 @@ generated-trait compatibility work. Scala-runtime removal remains a later projec - A clean build passes all 266 plain-JVM tests and the Java 8 Forge server passes all 116 tests. The two-type ABI and both generator companions' disassembly match the reference. `multipart/asm/ByteCodecs.scala` is next as an isolated codec port, leaving signature parsing and trait compilation for separate targets. +- Condensed `JAVA_MIGRATION_DIVERGENCES.md` from 3,134 to 189 lines, keeping effective runtime, binary and source + differences plus one shared classfile section. Removed repeated preservation claims, validation histories and + superseded intermediate decisions; the original narrative remains in git history. The workflow now records test + results here and updates the divergence ledger only for a genuinely new difference. diff --git a/JAVA_MIGRATION_DIVERGENCES.md b/JAVA_MIGRATION_DIVERGENCES.md index bbe8bc9..551e773 100644 --- a/JAVA_MIGRATION_DIVERGENCES.md +++ b/JAVA_MIGRATION_DIVERGENCES.md @@ -1,3134 +1,189 @@ -# Java migration divergence log - -This log records intentional differences from the `1.7.12` reference implementation. Behavioral changes must be isolated from behavior-preserving conversions and justified here. - -## 2026-08-14 — IDWriter Java pilot - -### Observable behavior - -No known behavior divergence. Byte, unsigned-short, and integer carrier selection and encoding remain identical, including the reference behavior that negative maximum values select the byte carrier. - -### Supported JVM API - -- Preserved `write()`, `write_$eq(Function2)`, `read()`, `read_$eq(Function1)`, `setMax(int)`, and the public constructor with their reference JVM descriptors. -- Marked the four Scala function property methods deprecated. -- Added `write(MCDataOutput, int)` and `read(MCDataInput)` as the Java-native API. Recompiled Scala callers also resolve to these methods. - -### Compiler artifacts - -Accepted divergence: the six public-but-generated `IDWriter$$anonfun$setMax$1` through `$6` classes are removed and replaced by private Java anonymous helper classes. They represented closure implementation details, were not named by source callers, and are not retained as supported API. - -### Validation - -- Existing `IDWriterCharacterizationTest`: 8 tests, 0 failures, 0 errors. -- Complete plain-JVM suite: 25 tests, 0 failures, 0 errors. -- Clean `checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 2 tests, 0 failures, 0 errors. -- `IDWriter` class-file version: 52 (Java 8). - -## 2026-08-14 — Partial occlusion Java port - -### Observable behavior - -No known voxel-test divergence. Grid resolution, coordinate rounding, owner encoding, conflict marking, required visibility, complete-occlusion exemption, and same-part overlap behavior remain unchanged. - -### Supported JVM API - -- Preserved every public `PartialOcclusionTest` constructor, accessor, `fill` overload, and `apply()` descriptor. Its four private fields also retain their reference names and descriptors. -- Preserved the `JPartialOcclusion` name plus both method descriptors. `allowCompleteOcclusion()` changes from a Scala-trait abstract method to a Java default method returning `false`. -- Retained deprecated `JPartialOcclusion$class` with the reference `allowCompleteOcclusion(JPartialOcclusion)` and `$init$(JPartialOcclusion)` static descriptors. This keeps Scala 2.11 implementations compiled against the reference jar linkable. - -### Compiler artifacts - -Accepted divergence: the five generated `PartialOcclusionTest$$anonfun$*` classes are removed. The Java loops produce no replacement helper classes, and these closure implementation details are not retained as supported API. - -### Validation - -- `PartialOcclusionCharacterizationTest`: 10 tests, 0 failures, 0 errors. -- Reference-compiled Scala consumer: 1 test, 0 failures, 0 errors. -- Complete plain-JVM suite: 27 tests, 0 failures, 0 errors. -- Clean `checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 2 tests, 0 failures, 0 errors. -- `PartialOcclusionTest` class-file version: 52 (Java 8). - -## 2026-08-14 — Removal of unused Scala bridges - -The downstream ABI inventory (`JAVA_MIGRATION_ABI_INVENTORY.md`) scanned 240 mod jars and found no consumer of either -bridge below. Both were written speculatively before the inventory existed. - -### Removed API - -- `IDWriter.write()`, `IDWriter.write_$eq(Function2)`, `IDWriter.read()`, and `IDWriter.read_$eq(Function1)`. - No jar in the pack references `IDWriter` at all. Both in-repo callers, `MultiPartRegistry` and - `MicroMaterialRegistry`, already use `write(MCDataOutput, int)` and `read(MCDataInput)`. -- `JPartialOcclusion$class`, including the `allowCompleteOcclusion(JPartialOcclusion)` and `$init$(JPartialOcclusion)` - static descriptors. No jar references the helper. The two consumers that touch `JPartialOcclusion`, - ForgeRelocationFMP and WitchingGadgets, only call `getPartialOcclusionBoxes()Ljava/lang/Iterable;`, and the two - jars that implement the interface, WR-CBE and extrautilities, emit no call to the helper. The interface itself and - both of its method descriptors are unchanged. - -The `ReferenceScalaPartialOcclusion` binary fixture and `JPartialOcclusionBinaryCompatibilityTest` were removed with -the helper they existed to verify. - -### Observable behavior - -`IDWriter` no longer stores Scala closures, so carrier selection and encoding happen without boxing an `Integer` or -allocating a `Function1`/`Function2` per call. Byte, unsigned-short, and integer selection and the encoded bytes are -unchanged, including negative maximums selecting the byte carrier. - -Accepted divergence: calling `write` or `read` before `setMax` now throws `IllegalStateException` instead of -`NullPointerException`. No caller reaches this state; the change only improves the failure message. - -### Validation - -- `IDWriterCharacterizationTest`: 9 tests, 0 failures, 0 errors. -- Complete plain-JVM suite: 27 tests, 0 failures, 0 errors. -- Clean `checkstyleTest build` with Spotless re-enabled: passing. -- Java 8 Forge dedicated-server suite: 2 tests, 0 failures, 0 errors. - -## 2026-08-14 — TCuboidPart Java port - -### Observable behavior - -No known divergence for any part that reaches the cuboid implementation. `getSubParts` still yields one -`IndexedCuboid6` holding a boxed `Integer` 0 and a copy of the bounds, `getCollisionBoxes` still yields the bounds -instance itself, and `drawBreaking` performs the same pipeline setup and `BlockRenderer.renderCuboid` call. - -The concrete `java.lang.Iterable` implementation changes from a Scala `Seq` wrapped by `JavaConversions` to -`Collections.singletonList`. Both are single-element and immutable; only code inspecting the runtime class or -attempting mutation could observe the difference. - -### Accepted divergence: Scala trait linearization is not reproducible - -This is the significant one, and it affects source compatibility rather than binary compatibility. - -A Scala trait that overrides superclass methods wins over that superclass. A Java interface loses to it: on the JVM a -superclass method always beats an interface default. `TCuboidPart` is now a Java interface, so a **recompiled** Scala -class written as `class Foo extends TMultiPart with TCuboidPart` silently inherits `TMultiPart`'s empty `getSubParts` -and `getCollisionBoxes` instead of the cuboid ones. It compiles cleanly and fails at runtime with missing collision and -selection boxes. - -Declaring the interface methods as `default` would not help, because the superclass still wins. They are therefore left -abstract, which also matches the reference bytecode exactly. - -Consequences: - -- Already compiled binaries are unaffected. Their forwarders call `TCuboidPart$class`, which is retained. -- Java consumers are unaffected. They extend `JCuboidPart`, which carries the overrides. -- Scala consumers that recompile must extend `JCuboidPart`, or declare the three overrides themselves and delegate to - `JCuboidPart.subParts`, `JCuboidPart.collisionBoxes` and `JCuboidPart.renderBreaking`. - -`Microblock` was the one in-repo case and now does exactly that. It changed from `extends TCuboidPart` to -`extends TMultiPart with TCuboidPart` plus the three explicit forwarders, because a Java interface can no longer supply -`TMultiPart` as its superclass. - -`CuboidPartCharacterizationTest.cuboidBehaviorWinsOverTheEmptyTMultiPartDefaults` is the regression guard for this. - -### Supported JVM API - -- Preserved every reference descriptor on `TCuboidPart`, `JCuboidPart` and `TCuboidPart$class`, verified by diffing - `javap -s` output against the reference dev jar built at `246daff`. -- Retained `TCuboidPart$class` with all four statics, since ForgeRelocationFMP, OpenComputers, ProjRed and ProjectBlue - call them. Its bodies cannot delegate to the instance methods, because old forwarders call the statics and would - recurse; they delegate to the canonical statics on `JCuboidPart` instead. -- Kept `@SideOnly(Side.CLIENT)` on `TCuboidPart.drawBreaking` and `TCuboidPart$class.drawBreaking`, matching the - reference. As in the reference, `Microblock.drawBreaking` is deliberately not annotated, so on a dedicated server it - survives while its callee is stripped. That hazard is unchanged; the method is never invoked server-side. -- Added `JCuboidPart.subParts`, `JCuboidPart.collisionBoxes` and `JCuboidPart.renderBreaking` as public statics, plus a - private constructor on `TCuboidPart$class`. Both are additive. - -### Build layout - -`compileJava` runs before `compileScala`, so Java sources under `src/main/java` cannot reference types that are still -Scala. All three files live under `src/main/scala/codechicken/multipart/` for joint compilation, matching the existing -`minecraft/McBlockPart.java`. They can move to `src/main/java` once `TMultiPart` is ported. - -### Compiler artifacts - -None removed. The Scala implementation generated no closure classes for this trait. - -### Validation - -- `CuboidPartCharacterizationTest`: 5 tests, 0 failures, 0 errors, unchanged from the Scala baseline. -- `TCuboidPartBinaryCompatibilityTest`: 1 test, 0 failures, 0 errors, loading a Scala 2.11.5 class compiled against the - reference dev jar whose forwarders call all four `$class` statics. -- Complete plain-JVM suite: 33 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 2 tests, 0 failures, 0 errors. The `RenderBlocks` side warning and the `antlr4` - jar parse errors in that log are present on the pre-port baseline as well. - -## 2026-08-14 — TNormalOcclusion Java port - -Covers `NormalOcclusionTest`, `NormalOcclusionTest$`, `JNormalOcclusion`, `TNormalOcclusion`, -`TNormalOcclusion$class` and `NormallyOccludedPart`, which all shared one Scala file. - -### Observable behavior - -No known divergence in the occlusion result. The box test still returns true when every pair of boxes fails to -intersect, still gathers the neighbour's normal boxes followed by its partial boxes in that order, and the bridge still -evaluates the box test before the super chain and short-circuits on failure. - -`Traversable` inputs are drained through `JavaConversions.asJavaIterator(boxes.toIterator())` into an `ArrayList` -before testing, rather than traversed with `forall`. Iteration order is preserved. The result of the test does not -depend on order, since `intersects` is side-effect free. - -### Accepted divergence: super accessor becomes a non-synthetic default - -The reference interface declares `codechicken$multipart$TNormalOcclusion$$super$occlusionTest(TMultiPart)Z` as -`ACC_PUBLIC | ACC_ABSTRACT | ACC_SYNTHETIC`. `javac` hides synthetic members completely, so no Java class, and no -Scala class recompiled against a Java interface, could ever implement it. Left abstract it would make the interface -unimplementable outside the original Scala compiler. - -It is therefore emitted as a non-synthetic `default` returning `true`. `true` is the identity for the `&&` chain the -bridge builds, and matches `TMultiPart.occlusionTest`. Classes compiled against the reference supply their own -override carrying their real super chain, so the default is only reached if the deprecated bridge is used on a class -that never had one. Method resolution ignores `ACC_SYNTHETIC`, so existing `invokeinterface` call sites are unaffected. - -Consequently `NormallyOccludedPart` no longer declares that method itself and inherits the default. An old -`invokevirtual` against it still resolves through the interface default and still returns `true`. - -### Accepted divergence: Scala apply sugar on NormalOcclusionTest - -`NormalOcclusionTest` was a Scala `object`, so Scala callers could write `NormalOcclusionTest(boxes1, boxes2)`. It is -now a Java class with static methods, and that sugar no longer compiles; recompiled Scala callers must write -`NormalOcclusionTest.apply(...)`. The in-repo callers in `EdgeMicroblock` and `HollowMicroblock` were updated. - -Binary compatibility is unaffected: both static forwarders keep their reference descriptors, and `NormalOcclusionTest$` -keeps `MODULE$` plus both instance methods, which is what ForgeRelocationFMP and OpenComputers link against. - -### Accepted divergence: NormallyOccludedPart.getType - -The reference emitted two `getType` methods, `()Ljava/lang/String;` and `()Lscala/runtime/Null$;`, because Scala infers -`Null` for `def getType = null`. Only the `String` form remains. The `Null$` form was a compiler artifact of the -inferred type, and no jar in the pack references it. AE2, the only consumer of this class, uses the `(Cuboid6)V` -constructor and the type itself. - -### Trait linearization, as with TCuboidPart - -Both in-repo mixins needed explicit handling, and the two cases differ: - -- `HollowMicroblock` did not override `occlusionTest` at all and relied on the trait. It now declares - `NormalOcclusionTest.apply(this, npart) && super.occlusionTest(npart)`. -- `PostMicroblock` already overrode `occlusionTest` and ended with `super.occlusionTest(npart)`, which previously - routed through `TNormalOcclusion` because it was the last mixin. That call now reaches `Microblock` directly and - would have skipped the box test entirely, so the same expression was substituted at that call site. - -This second shape is the more dangerous one: the class looks correct, still compiles, and silently drops the box test. -Every remaining trait conversion needs its existing `super` call sites audited, not just its missing overrides. - -### Supported JVM API - -- `NormalOcclusionTest$`, `JNormalOcclusion` and `TNormalOcclusion` are descriptor-identical to the reference. -- `NormalOcclusionTest` and `TNormalOcclusion$class` add only a private constructor, and `NormalOcclusionTest` three - private helpers. Both public `apply` descriptors are unchanged, including - `(Lscala/collection/Traversable;Lscala/collection/Traversable;)Z`. -- Scala's `Traversable` is retained in two descriptors, as the ABI inventory anticipated. - -### Compiler artifacts - -Accepted divergence: `NormalOcclusionTest$$anonfun$apply$1` and `NormalOcclusionTest$$anonfun$apply$1$$anonfun$apply$2` -are removed. The Java loops produce no replacement classes. These were closure implementation details of the nested -`forall` and are not retained as supported API. - -### Documentation fix - -The reference scaladoc said the test "returns true if the test fails", which the earlier characterization showed to be -backwards. The Java doc comments now say the test returns true when the parts may coexist. - -### Validation - -- `NormalOcclusionCharacterizationTest`: 12 tests, 0 failures, 0 errors, unchanged from the Scala baseline. -- `TNormalOcclusionBinaryCompatibilityTest`: 1 test, 0 failures, 0 errors, exercising forwarder, `$class`, singleton - and the accessor callback. -- Complete plain-JVM suite: 38 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 2 tests, 0 failures, 0 errors. - -## 2026-08-14 — TFacePart Java port - -### Observable behavior - -No known divergence. `solid` still returns true for every side, including negative and out-of-range values, and -`redstoneConductionMap` still returns 0. `TFacePart` still extends `TSlottedPart`. - -### The first trait where default methods are safe - -`TMultiPart` declares neither `solid` nor `redstoneConductionMap`, and neither does anything in the microblock -superclass chain. There is therefore no superclass method for an interface default to lose to, and both members are -emitted as real Java `default` methods rather than left abstract. - -This is the check to apply to every remaining trait: a default is safe only when no class in an implementor's -superclass chain declares the same member. `TCuboidPart` and `TNormalOcclusion` both failed that check and had to stay -abstract with explicit forwarders. - -As a result no in-repo Scala needed changing. `FaceMicroblock` and `HollowMicroblock` already override what they care -about, and `FaceMicroblock` picks up the `redstoneConductionMap` default exactly as it previously picked up the trait -implementation. - -### Improvement for Java implementors - -Both members were abstract on the reference interface, so a Java class implementing `TFacePart` had to supply them even -to accept the defaults; `minecraft/McSidedMetaPart` does exactly that. Java implementors can now inherit them. This is -additive: `McSidedMetaPart` is descriptor-identical to the reference, and existing implementors that declare their own -overrides are unaffected. - -### Supported JVM API - -- `TFacePart` is descriptor-identical to the reference, including both members remaining public and non-static on the - interface. Changing them from abstract to default does not affect method resolution for existing implementors, which - all declare their own. -- Retained `TFacePart$class` with all three statics for OpenComputers, ProjRed and ProjectBlue. It adds only a private - constructor. Its bodies hold the defaults directly rather than dispatching through the instance, matching the - reference and avoiding recursion from old forwarders. -- The emitted class-file set for this area is unchanged; the Scala implementation generated no closure classes here. - -### Validation - -- `FacePartCharacterizationTest`: 4 tests, 0 failures, 0 errors, unchanged from the Scala baseline. -- `TFacePartBinaryCompatibilityTest`: 1 test, 0 failures, 0 errors, loading a Scala 2.11.5 consumer whose forwarders - call all three statics. -- Complete plain-JVM suite: 43 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 3 tests, 0 failures, 0 errors. A new case covers what plain-JVM tests cannot: - microblock classes are generated by ASM at runtime, so it checks that a generated `FaceMicroblock` inherits the - `redstoneConductionMap` default and that a generated `HollowMicroblock` still returns its own `0x10` and `false`. - -## 2026-08-14 — TIconHitEffects Java port - -Covers `IconHitEffects`, `JIconHitEffects`, `JIconHitEffects$class`, `TIconHitEffects` and `TIconHitEffects$class`, -which shared one Scala file. - -### Observable behavior - -No known divergence. `getBreakingIcon` still ignores its `subPart` argument and returns `getBrokenIcon(side)`, destroy -effects still request sides 0 through 5 in order, and the `scaleDensity` overload still chooses between the part's own -bounds and `Cuboid6.full`. - -Evaluation order in `addDestroyEffects` is deliberately preserved: icons first, then bounds, then the tile. Hoisting -the tile read to the top of the method would have been tidier but changes which work happens before a null tile fails, -and the characterization pins the reference order. - -### Removed API: IconHitEffects$ - -Accepted divergence: the `IconHitEffects$` companion singleton and its `MODULE$` field are removed. No jar in the pack -references the class, by bytecode or by name; the four consumers of this area use the static forwarders on -`IconHitEffects` (WR-CBE, extrautilities) or the two `$class` bridges (ForgeRelocationFMP, OpenComputers, ProjRed). - -This is the same reasoning applied to the dead `IDWriter` and `JPartialOcclusion` bridges, but it removes a public -class rather than a method, so it is worth calling out separately. Restoring it is a thin delegating class if any -consumer outside the pack turns out to need it. Note the contrast with `NormalOcclusionTest$`, which is referenced by -ForgeRelocationFMP and OpenComputers and was therefore kept. - -### Trait linearization, split decision - -The two interfaces needed opposite treatment, which is the rule from the `TFacePart` port working as intended: - -- `JIconHitEffects.getBreakingIcon` becomes a real `default`. `TMultiPart` does not declare it, so nothing in an - implementor's superclass chain can beat it. Java implementors can now inherit it; `minecraft/McBlockPart` already - declared its own and stays descriptor-identical. -- `TIconHitEffects.addHitEffects` and `addDestroyEffects` stay abstract. `TMultiPart` declares both, so a default would - silently lose to its empty versions. - -`MicroblockClient` was the one in-repo case and now declares both explicitly, delegating to the `IconHitEffects` -statics. - -### Supported JVM API - -- `JIconHitEffects` and `TIconHitEffects` are descriptor-identical to the reference. -- `IconHitEffects`, `JIconHitEffects$class` and `TIconHitEffects$class` add only a private constructor. All three - `IconHitEffects` static overloads keep their reference descriptors, including the three-argument `scaleDensity` form - that extrautilities links against. -- `@SideOnly(Side.CLIENT)` placement matches the reference exactly: two on `JIconHitEffects`, one on - `JIconHitEffects$class`, two on `TIconHitEffects`, two on `TIconHitEffects$class`, and none on `IconHitEffects`. -- `JIconHitEffects` does not extend `TMultiPart` at bytecode level in the reference either, so the statics cast to - `TMultiPart` internally exactly as the reference does. Passing a non-`TMultiPart` still fails with - `ClassCastException`. - -### Compiler artifacts - -Accepted divergence: `IconHitEffects$$anonfun$addDestroyEffects$1` is removed along with `IconHitEffects$`. The Java -loop produces no replacement class. - -### Validation - -- `IconHitEffectsCharacterizationTest`: 5 tests, 0 failures, 0 errors, unchanged from the Scala baseline. -- `TIconHitEffectsBinaryCompatibilityTest`: 1 test, 0 failures, 0 errors, exercising all five statics across both - bridges. -- Complete plain-JVM suite: 49 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 3 tests, 0 failures, 0 errors. -- Particle appearance itself needs a client and stays on the manual checklist. - -## 2026-08-14 — TItemMultiPart Java port - -Covers `JItemMultiPart`, `TItemMultiPart` and `TItemMultiPart$class`, which shared `ItemMultiPart.scala`. - -### Observable behavior - -No known divergence. `getHitDepth` still projects a copy of the hit vector onto the axis for that side and adds 1 on -even sides, leaving the caller's vector untouched. `onItemUse` still tries the clicked block only when the depth is -below 1, then always tries the neighbour on that side, reusing and mutating a single `BlockCoord` across both attempts -and passing the same `Vector3` to every `newPart` call. Placement still short-circuits on a null part before touching -the world, still skips `addPart` on the client, and still decrements the stack only outside creative mode. - -### First trait extending a Minecraft class rather than TMultiPart - -`TItemMultiPart extends Item`, so the linearization check runs against `Item` instead of `TMultiPart`. The outcome is -the same split seen in the `TIconHitEffects` port: - -- `getHitDepth` becomes a real `default`. `Item` does not declare it, so nothing in an implementor's superclass chain - can beat it. -- `onItemUse` stays abstract. `Item` declares it, so a default would silently lose to the vanilla implementation and - placement would stop working. - -This confirms the rule generalises: what matters is the implementor's actual superclass, not `TMultiPart` specifically. - -There were no in-repo implementors beyond `JItemMultiPart` itself, so nothing else needed changing. - -### Supported JVM API - -- `TItemMultiPart` is descriptor-identical to the reference. -- `JItemMultiPart` keeps its constructor, both instance methods and their descriptors; WR-CBE links against the - constructor and the inherited `func_77658_a`. It gains two public statics, `hitDepth` and the `onItemUse` overload - taking the part, plus a private `place`. All additive. -- `TItemMultiPart$class` keeps all three public statics for ProjRed, its only consumer. It adds a private constructor - and drops the reference's private `place$1` helper, which was never visible to consumers. -- `getHitDepth` on the bridge ignores its part argument and calls the static directly, matching the reference, whose - trait body never used `this`. The `onItemUse` path still dispatches `getHitDepth` through the interface, so an - implementor's override is honoured exactly as before. - -### Compiler artifacts - -None removed or added. The emitted class-file set for this area is unchanged; the local `place` function compiled to a -private static method rather than a closure class in both versions. - -### Validation - -- `ItemMultiPartCharacterizationTest`: 7 tests, 0 failures, 0 errors, unchanged from the Scala baseline. -- `TItemMultiPartBinaryCompatibilityTest`: 1 test, 0 failures, 0 errors, driving a reference-compiled Scala consumer - through both attempt positions. -- Complete plain-JVM suite: 57 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 3 tests, 0 failures, 0 errors. -- Real placement into a world needs a client or a server scenario and stays on the functional and manual layers. - -## 2026-08-14 — TEdgePart Java port - -### Observable behavior - -No known divergence. `conductsRedstone` still returns false and `TEdgePart` still extends `TSlottedPart`. - -### Default method, same test as TFacePart - -`TMultiPart` does not declare `conductsRedstone`, and nothing in the microblock superclass chain does either, so the -member is emitted as a real Java `default`. `EdgeMicroblock` never declared its own forwarder even in the reference, -because it is a Scala trait rather than a concrete class, and the generated concrete classes now resolve the interface -default instead of a Scala trait forwarder. The functional microblock generation case added during the `TFacePart` -port already covers that resolution path. - -No in-repo Scala needed changing. - -### Supported JVM API - -- `TEdgePart` is descriptor-identical to the reference. -- `TEdgePart$class` keeps both statics and adds only a private constructor. OpenComputers links against `$init$` only, - but `conductsRedstone` is retained because the bridge class is being kept regardless and dropping one static from a - live bridge would be a gratuitous shape change. -- The emitted class-file set for this area is unchanged; the Scala implementation generated no closure classes here. - -### Validation - -- `EdgePartCharacterizationTest`: 3 tests, 0 failures, 0 errors, unchanged from the Scala baseline. -- `TEdgePartBinaryCompatibilityTest`: 1 test, 0 failures, 0 errors. -- Complete plain-JVM suite: 61 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 3 tests, 0 failures, 0 errors. - -## 2026-08-14 — Saw Java port - -The first port outside `codechicken.multipart`. `Saw` was declared in `ItemSaw.scala`; only the trait is extracted, -and `ItemSaw` itself stays Scala. - -### Observable behavior - -No known divergence. `getMaxCuttingStrength` still asks the saw about a stack of itself, so the stack handed to -`getCuttingStrength` wraps the saw and has size 1, and the result still follows an implementor's -`getCuttingStrength` override. - -### Default method, and a shape change on ItemSaw - -`Item` does not declare `getMaxCuttingStrength`, so it becomes a real Java `default`. - -Consequence worth recording: `ItemSaw` previously carried a Scala trait forwarder for `getMaxCuttingStrength` and now -inherits the default instead, so it no longer declares that method. Three jars reference the `ItemSaw` type -(IguanaTweaksTConstruct, ProjectBlue, endercore) but none reference any of its members, and an `invokevirtual` against -`ItemSaw.getMaxCuttingStrength` would still resolve through the interface default. `harvestLevel` and -`getCuttingStrength` are unchanged. - -This is the first time a port changed the declared members of a class it did not touch. Watch for it whenever a trait -default is introduced on a type with concrete Scala implementors. - -### Unlike the other constant bridges - -`Saw$class.getMaxCuttingStrength` dispatches `getCuttingStrength` back through the interface, so an implementor's -override is honoured even when the bridge is called directly. `TFacePart$class` and `TEdgePart$class` hold constants -and deliberately ignore overrides. Both behaviors are preserved as found and are asserted separately. - -### Supported JVM API - -- `Saw` is descriptor-identical to the reference. -- `Saw$class` keeps both statics for ProjRed and adds only a private constructor. Its body casts to `Item` to build - the stack, exactly as the reference bytecode did. -- The emitted class-file set for this area is unchanged. - -### Validation - -- `SawCharacterizationTest`: 3 tests, 0 failures, 0 errors, unchanged from the Scala baseline. -- `SawBinaryCompatibilityTest`: 1 test, 0 failures, 0 errors, where the fixture reports its strength only if handed a - stack that wraps itself. -- Complete plain-JVM suite: 65 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 3 tests, 0 failures, 0 errors. - -## 2026-08-14 — MicroMaterialRegistry Java port - -The first stateful registry converted, and the widest surface so far: ten jars reference the type and three more reach -it reflectively. Covers `MicroMaterialRegistry`, `MicroMaterialRegistry$` and the two nested interfaces. - -### Observable behavior - -No known divergence. `setupIDMap` still sorts the type map by name into the id array so ids are indexes into it, -`materialID` and `materialName` still round trip, `remapName` still resolves on both `getMaterial(String)` and -`materialID`, `getMissingId` still fails loudly when the placeholder is absent rather than falling back to zero, ids -still round trip through the shared `IDWriter`, and a highlight renderer that claims the highlight still short-circuits -the default renderer. - -`calcMaxCuttingStrength` still throws when no saw is registered. The reference reached that through `max` on an empty -collection; the port throws `UnsupportedOperationException` explicitly to keep the same failure rather than silently -leaving the field at zero. - -### Changed API: readIDMap - -Accepted divergence: `readIDMap` returns `java.util.List` instead of `scala.collection.Seq`. No jar in -the pack references it, and the only caller is the in-repo material registration packet handler, which was updated -from `mkString` to `String.join`. This removes one of the five Scala-typed descriptors the ABI inventory identified. - -`getIdMap()[Lscala/Tuple2;` is deliberately **not** changed, because extrautilities links against it. The registry -therefore still stores `scala.Tuple2` internally rather than converting on every call. - -### Removed API - -- The three mangled accessors Scala emitted as public so its closure classes could reach private state: - `codechicken$microblock$MicroMaterialRegistry$$idMap()`, `$$typeMap()` and `$$nameMap()`. They are compiler - artifacts, not API, and no jar references them. -- `MicroMaterialRegistry$IMicroMaterial$class`, along with its four statics. No jar references it. All ten - implementors reach `IMicroMaterial` through `BlockMicroMaterial`, which is in-repo, so nothing external carries - forwarders to the helper. -- `MissingMicroMaterial.canRenderInPass(int)` and `MissingMicroMaterial.isSolid()` static forwarders, plus the - matching instance methods on `MissingMicroMaterial$`. That object overrides neither, so with the members now being - Java interface defaults Scala emits no forwarder and therefore no static forwarder either. Nothing in the pack - references `MissingMicroMaterial` at all. This is the same class of change as `ItemSaw` in the `Saw` port, and the - characterization caught it by failing to compile. - -### Added API - -`setupIDMap`, `calcMaxCuttingStrength` and `loadIcons` gain static forwarders on `MicroMaterialRegistry`. They were -`private[microblock]` in Scala, which is public on the JVM but produces no static forwarder. Additive. - -### IMicroMaterial defaults - -`loadIcons`, `canRenderInPass` and `isSolid` become real Java defaults. Neither nested interface has a superclass to -lose to, and both in-repo implementors, `BlockMicroMaterial` and `MissingMicroMaterial`, extend nothing else. Java -implementors can now inherit the three instead of restating them; both nested interfaces are descriptor-identical to -the reference. - -### Compiler artifacts - -Accepted divergence: all eleven `MicroMaterialRegistry$$anonfun$*` classes are removed. The Java loops produce no -replacement classes. - -### Validation - -- `MicroMaterialRegistryCharacterizationTest`: 7 tests, 0 failures, 0 errors, passing against both the Scala baseline - and the port. -- `MicroMaterialRegistryBinaryCompatibilityTest`: 1 test, 0 failures, 0 errors, driving a reference-compiled Scala - consumer through `MODULE$` and the raw `scala.Tuple2` array. -- Complete plain-JVM suite: 73 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 3 tests, 0 failures, 0 errors. This exercises the real path, since server - startup calls `setupIDMap`, `calcMaxCuttingStrength` and the default content registration. -- Error paths remain uncovered by tests: they call the microblock logger, which is null until `MicroblockProxy.preInit` - runs, so they cannot execute headless. They are unchanged from the reference. - -## 2026-08-14 — MultiPartRegistry Java port - -Covers `MultiPartRegistry`, `MultiPartRegistry$` and the three nested interfaces. Twelve jars reference the type and -Schematica reaches the singleton reflectively. - -### Observable behavior - -Registry behavior itself has no known divergence. `beforeServerStart` still sorts the type map by name so ids are indexes into it, part ids still -round trip through the shared `IDWriter`, converters are still grouped per block with the first non-null result -winning, registration still refuses to run once the registry is closed and still requires an active mod container, a -duplicate part id still throws, and `writePartID` and `getModContainer` still throw rather than returning null for an -unknown name. - -### Resolved reflective regression, discovered and fixed 2026-08-27 - -The full consumer-source audit found a constraint that the bytecode scan missed. Schematica 1.12.6 obtains the private -field `codechicken$multipart$MultiPartRegistry$$typeMap` from `MultiPartRegistry$` and casts its value to -`scala.collection.mutable.Map`. The Java port moved the canonical map to a private `java.util.HashMap` on -`MultiPartRegistry`, and `MultiPartRegistry$` exposed no compatibility field, so Schematica disabled its FMP -integration during reflective initialization. - -`MultiPartRegistry$` now restores that exact private field and descriptor using Scala's existing live Java-map wrapper; -the Java map remains the single source of truth. `MultiPartRegistryCharacterizationTest` performs Schematica's actual -`ReflectionHelper` lookup, casts the result to `scala.collection.mutable.Map`, and proves mutations reach the Java -registry. No separate registry or synchronization path was added. - -### Preserved Scala-typed descriptors - -Both remain, because ForgeRelocationFMP and ProjRed link against them: - -- `registerParts(Lscala/Function2;Lscala/collection/Seq;)V` -- `registerParts(Lcodechicken/multipart/MultiPartRegistry$IPartFactory2;Lscala/collection/Seq;)V` - -The `Seq` overload drains through `JavaConversions.seqAsJavaList`. The `Function2` overload applies the function with -a boxed `Boolean`, matching what the Scala closure received. - -### Array overloads become Java varargs - -`registerParts(IPartFactory, String[])` and `registerParts(IPartFactory2, String[])` are declared `String...`. The -descriptor is unchanged, verified against the reference dev jar; `ACC_VARARGS` is a compiler flag and does not affect -linkage. This was needed because `MicroblockClass` called the Scala varargs form with a single string, which no longer -resolves against a plain array parameter. It also makes the Java call sites more natural without adding API. - -### Changed and removed API - -- `readIDMap` returns `java.util.List` instead of `scala.collection.Seq`, as with - `MicroMaterialRegistry`. It is `private[multipart]` in Scala, so it has no static forwarder, and no jar references - it. -- The mangled public accessor methods Scala emitted so its closures could reach private state - (`codechicken$multipart$MultiPartRegistry$$typeMap()` and the four others) are gone. No jar links those methods. - This original check did not cover Schematica's reflective access to the separate private backing field described - above. - -### Compiler artifacts - -Accepted divergence: the eight `MultiPartRegistry$$anonfun$*` classes and `MultiPartRegistry$$anon$1` are replaced by -two Java anonymous classes, `MultiPartRegistry$1` and `$2`, which are the two `IPartFactory2` adapters the deprecated -overloads build. - -### Validation - -- `MultiPartRegistryCharacterizationTest`: 5 tests, 0 failures, 0 errors, unchanged from the Scala baseline. -- Complete plain-JVM suite: 78 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 5 tests, 0 failures, 0 errors. This is the layer that matters for this class: - registration needs FML's active mod container, so real startup is the only place both factory overloads actually - run, and the suite resolves a part registered through each. -- Error paths that log remain uncovered headless, as before, because the multipart logger is null until preInit. - -### 2026-08-27 compatibility repair validation - -- The new Schematica reflection case failed first with `UnableToFindFieldException`, then passed with the compatibility - field present. -- `javap -private -s` confirms the field is private/final with descriptor `Lscala/collection/mutable/Map;`. -- `MultiPartRegistryCharacterizationTest`: 6 tests, 0 failures, 0 errors. -- Complete plain-JVM suite: 126 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. - -## 2026-08-14 — TileMultipart Java port - -The central tile. Twelve jars reference it and about twenty-five of its members. `TileMultipartClient` was split into -its own Scala file and deliberately **not** converted: it is registered with the ASM generator through -`registerTrait`, so converting it is Phase 5 `registerJavaTrait` work with different machinery. - -### Observable behavior - -No known divergence. Parts are still appended in order, the list is still replaced rather than mutated so a previously -published `Seq` never changes under a caller, `operate` still skips parts whose tile is null, ticking still starts on -the first ticking part and stops when the last one leaves, `getLightValue` is still max-or-zero while -`getExplosionResistance` is still max-or-throws, occlusion still requires agreement in both directions, and -`canReplacePart` still excludes the outgoing part while rejecting a part already present. - -`handlePacket` case 254 resolves the tile twice, once for the receiver and once for the argument, because the -reference used a by-name local def that re-evaluated `TileCache.findTile` at each use. Argument order is preserved. - -The `assert` calls on part count, client removal and client addition become explicit `AssertionError` throws with the -same messages, since Scala's `assert` is always enabled here and Java's is not. - -### Storage - -`partList` remains a `scala.collection.immutable.List` published through `partList()Lscala/collection/Seq;`, which -five jars link against. Mutations copy to a Java list, mutate, and republish through `JavaConversions`, matching the -reference's allocate-a-new-Seq semantics exactly. The focused Phase 4 baseline later found that the Java port's -`parts()` read helper also materializes an `ArrayList`, backing array, iterator and conversion wrappers on every -traversal. That read-side cost was later removed after focused characterization; see `JAVA_MIGRATION_PROFILE.md`. - -`operate` keeps its `(Lscala/Function1;)V` descriptor and internal callers still go through it, wrapping their action -in an `AbstractFunction1`. That preserves both the virtual dispatch, so any trait overriding `operate` still sees -every call, and the reference's callback-adapter call shape. - -### 2026-08-27 Phase 4 traversal optimization - -The initial Java port implemented every read through `parts()`, which copied the Scala `Seq` into a Java `ArrayList`. -The focused profile measured about 184 allocated bytes for every eight-part `operate` call. `operate` now captures the -published sequence itself and walks the normal immutable Scala `List` through its existing head/tail chain. Other -`Seq` implementations accepted through `partList_$eq` retain an iterator fallback. - -This restores the reference's captured-sequence behavior: a callback-added part is not visited, and an original part -detached before its turn is skipped by the existing null-tile guard. The public member descriptors and virtual call -path are unchanged. The matching profile measured 0 B/call for direct `operate`, 0.05 B/call through `updateEntity`, -and roughly 4.3x higher throughput. Three new plain-JVM tests cover addition, detachment, and the non-list fallback; -the complete 133-test plain-JVM and 28-test Forge server suites pass. - -### Preserved Scala-typed descriptors - -- `partList()Lscala/collection/Seq;` and `partList_$eq(Lscala/collection/Seq;)V` -- `operate(Lscala/Function1;)V` -- `getOrConvertTile2(...)Lscala/Tuple2;` -- `loadParts(Lscala/collection/Iterable;)V` -- `rayTraceAll` still stores a `scala.Tuple2` into `ExtendedMOP.data`, which `EdgeMicroblock` reads back through - `getData[(Int, _)]`. - -### Removed API - -`protected$worldObj(TileMultipart)`, the public accessor Scala emitted so the `dropItems` closure could reach the -protected field. It is a compiler artifact and no jar references it. `TileMultipartClient` lost nothing, including its -generated super accessor for `markRender`, which Scala regenerated correctly against the Java superclass. - -### Recompiled Scala consumers - -The largest source-only divergence so far. Scala reads the Java signatures rather than a ScalaSignature, so: - -- `tile.partList(i)` no longer parses as an index; it must be `tile.partList.apply(i)`. Eleven in-repo call sites - were updated. -- `TileMultipart.renderID = x` must become `renderID_$eq(x)`. -- `getOrConvertTile2` returns `Tuple2[TileMultipart, Object]` rather than `(TileMultipart, Boolean)`, so `_2` needs an - explicit cast. Two in-repo call sites. -- `operate { p => ... }` no longer accepts a lambda, because Scala 2.11 will not adapt `TMultiPart => Unit` to - `Function1[TMultiPart, BoxedUnit]`. The one in-repo caller, `TTileChangeTile`, now builds an `AbstractFunction1`. - -Binary compatibility is unaffected in all four cases. - -### Compiler artifacts - -Accepted divergence: all 31 `TileMultipart$$anonfun$*` classes are removed, replaced by one Java anonymous class for -the `operate` adapter. - -### Validation - -- `TileMultipartCharacterizationTest`: 12 tests, 0 failures, 0 errors, unchanged from the Scala baseline. -- Complete plain-JVM suite: 90 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 5 tests, 0 failures, 0 errors. This is the load-bearing check: the ASM - generator builds composite tiles that extend this class and mix Scala traits into it, and the suite still generates - a `TSlottedTile` composite and two microblock classes. -- Every public member of the reference is still present except `protected$worldObj`, verified by name-level diff, and - `partList`, `operate`, `jPartList`, `getOrConvertTile2`, `multiPartChange`, `rayTraceAll` and `dropItems` were - checked descriptor by descriptor. -- World-dependent paths, NBT round trips through `createFromNBT`, and desc packets are not covered by tests and stay - on the manual checklist. - -## 2026-08-14 — TMultiPart Java port - -The base class every part extends. Five jars extend it and about twenty of its members are referenced. - -### Observable behavior - -No known divergence. The class is almost entirely no-op defaults; the only real implementation is -`collisionRayTrace`, which still offsets each sub part by the tile coordinates, rebuilds them as `IndexedCuboid6` -carrying the original `data`, and delegates to `RayTracer.rayTraceCuboids` with the same block coordinate and block -type. `x`, `y` and `z` still throw `NullPointerException` when the part is unbound, and `world` still returns null -rather than throwing. - -`getSubParts` was traversed through `JavaConversions` purely to get Scala's `map`; `rayTraceCuboids` already took a -`java.util.List`, so the Java loop builds that list directly and the conversion disappears. - -### Supported JVM API - -This is the cleanest result so far. Diffed against a reference dev jar built at `cacc9a3`: - -- Every descriptor is identical, checked across all members rather than a sample. -- No public member lost and none added. -- `@SideOnly(Side.CLIENT)` appears on the same seven members. -- `getTile()` and the no-argument `addDestroyEffects` remain the only deprecated members. `javap` reports a higher - raw count because javac emits both the `Deprecated` attribute and the annotation where Scala emitted one form; the - marked members are identical. -- `tile` keeps its `tile()` and `tile_$eq(TileMultipart)` accessor pair, so Scala callers can still write - `part.tile = t`. - -### Recompiled Scala consumers - -None. No in-repo Scala call site needed changing, which is the first port where that has been true of a type this -widely used. Scala resolves the empty-paren Java accessors the same way it resolved the Scala ones, and assignment to -`tile` still desugars to `tile_$eq`. - -### Compiler artifacts - -Accepted divergence: `TMultiPart$$anonfun$1`, the closure from the `getSubParts.map` in `collisionRayTrace`, is -removed. The Java loop produces no replacement class. - -### Validation - -- Complete plain-JVM suite: 90 tests, 0 failures, 0 errors, including the twelve `TileMultipart` cases that drive - parts through `bind`, `doesTick`, `occlusionTest`, `getLightValue` and `explosionResistance`. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 5 tests, 0 failures, 0 errors, covering real part registration and - instantiation of `mc_torch` and `mcr_face` plus composite tile generation. -- Ray tracing, rendering and particle paths need a client and stay on the manual checklist. - -## 2026-08-14 — TickScheduler Java port - -No jar in the pack references this class, so the ABI constraint was minimal, but the reference shape was preserved -anyway for consistency with the other ports. - -### Observable behavior - -No known divergence. Ticks scheduled while the world is mid-tick are still queued and applied after processing rather -than during it, an existing entry for the same part is still only overridden when going from random to scheduled, -random-update parts still reschedule themselves 800 to 1600 ticks out, chunks are still dropped from the active set -once their list empties, and only non-random entries are still written to chunk NBT. - -`processTicks` filtered a `ListBuffer` with a side-effecting predicate that fires the part callbacks and mutates the -entry. The Java version iterates and rebuilds the list in the same order, so callback order and the reschedule -mutation are unchanged. - -### The singleton carries behavior here - -Unlike the other companion singletons in this migration, `TickScheduler$` is not a pure forwarder. The object extends -`WorldExtensionInstantiator` and `WorldExtensionManager.registerWorldExtension` is handed the instance itself, so the -two instantiator hooks have to live on the singleton. It stays a Java class extending `WorldExtensionInstantiator` -with `MODULE$`, delegating into the statics. - -### Supported JVM API - -- `TickScheduler$` and `TickScheduler$PartTickEntry` are descriptor-identical to the reference, including - `PartTickEntry`'s Scala-style `time()`, `time_$eq`, `random()` and `random_$eq` accessor pairs and both - constructors. -- `TickScheduler` adds only a private constructor. -- `WorldTickScheduler` and `ChunkTickScheduler` were Scala `private class` and are now package-private static nested - classes, keeping their `TickScheduler$WorldTickScheduler` and `TickScheduler$ChunkTickScheduler` binary names. - -### Recompiled Scala consumers - -One call site. `WorldExtensionManager.registerWorldExtension(TickScheduler)` passed the object as a value and must now -pass `TickScheduler$.MODULE$`. - -`TRandomUpdateTick` is a Scala trait extending `TMultiPart`, so at bytecode level it is a bare interface that does not -extend the class. The Java code casts where the reference relied on Scala's view of the type, the same pattern already -recorded for `JIconHitEffects`. - -### Compiler artifacts - -Accepted divergence: the five `$$anonfun$` classes under `WorldTickScheduler.postTick` and `ChunkTickScheduler`'s -`processTicks`, `saveData` and `loadData` are removed. The Java loops produce no replacement classes. - -### Validation - -- Complete plain-JVM suite: 90 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 5 tests, 0 failures, 0 errors. This exercises the port directly rather than - incidentally: the scheduler is registered as a world extension during startup, so `createWorldExtension`, `load`, - and the `preTick`/`postTick` pair all run for every server tick of the suite. -- Scheduled and random tick firing over time, and the chunk NBT round trip, are not asserted by any test and stay on - the manual checklist. - -## 2026-08-14 — BlockMultipart Java port - -The Block face of the API. No jar references any member of it; it appears only as the return type of -`MultipartProxy.block()`, which ProjRed and buildcraft-compat call, and by name in Waila and guidenh reflection. - -### Observable behavior - -No known divergence. Every override still resolves the tile through `getTile`, which continues to return null both -when the tile is not a multipart tile and when its part list is empty, so the null branches and the empty-tile branches -stay merged exactly as before. `isAir` still reports true for a missing tile, `getExplosionResistance` still returns 0 -rather than reaching the throwing max on an empty tile, and the redstone queries still flip the side with `side ^ 1`. - -`reduceMOP` still returns the struck part's index alongside a rebased `ExtendedMOP` carrying that part's own data and -the original distance. - -### Supported JVM API - -- `BlockMultipart$` is descriptor-identical to the reference, including `reduceMOP`'s `scala.Tuple2` return. -- `BlockMultipart` differs by exactly one descriptor, discussed below. `addCollisionBoxesToList` keeps its descriptor; - only its generic signature changes from Scala's `List` to the raw `List` that vanilla's `Block` actually - declares, which is the more faithful override. -- The four static forwarders `getTile`, `getClientTile`, `reduceMOP` and `drawHighlight` are unchanged. - -### Removed API - -`hasTileEntity$default$1()`, the accessor Scala emits for the default argument on `hasTileEntity(meta: Int = 0)`. -Java has no default arguments, so it disappears. It is a compiler artifact of the default parameter, not API, and no -jar references any member of this class. - -### TileMultipartClient is a bare interface here - -`getClientTile` returns `TileMultipartClient`, which is a Scala trait extending `TileMultipart`, so in bytecode it is -an interface carrying none of the class's members. `addHitEffects` casts to `TileMultipart` to reach the part list. -This is the third occurrence of the pattern, after `JIconHitEffects` and `TRandomUpdateTick`. - -### Compiler artifacts - -Accepted divergence: the four `$$anonfun$` classes under `getDrops` and `addCollisionBoxesToList`, including the two -nested inner closures, are removed. The Java loops produce no replacement classes. - -### Validation - -- Complete plain-JVM suite: 90 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 5 tests, 0 failures, 0 errors. The block is registered during startup and is - the block every generated multipart tile is placed against, so registration and `hasTileEntity` run for real. -- Almost everything else in this class needs a player, a ray trace or a renderer. Block breaking, selection boxes, - collision, pick block, activation, particles and light are all on the manual checklist and are the reason that - checklist exists. - -## 2026-08-15 — Marker interface Java port - -Six interfaces that carry no implementation: `TSlottedPart`, `IRandomDisplayTick`, `INeighborTileChange`, -`TRandomUpdateTick`, `ISidedHollowConnect` and `IMicroMaterialRender`. - -### Observable behavior - -No known divergence. Five of the six were already pure abstract interfaces in bytecode with no `$class` helper, so -their conversion is a source-language change with no bytecode consequence at all. The sixth is discussed below. - -### Supported JVM API - -All six are member-identical and descriptor-identical to the reference. Every implementor and mixin was diffed as -well — `Microblock`, `RedstoneTorchPart`, `TorchPart`, `HollowMicroblock`, `TSlottedTile`, `TTileChangeTile` and -`TRandomDisplayTickTile` are unchanged member for member, so no concrete class gained or lost a forwarder. - -`TSlottedPart` and `TRandomUpdateTick` extended `TMultiPart` in Scala source. A trait extending a class is a bare -interface in bytecode, carrying none of the class's members, so the Java interfaces are bare too and match the -reference exactly. This is the same pattern as `JIconHitEffects` and `TileMultipartClient`; the port makes it explicit -in the source rather than changing it. - -`IMicroMaterialRender` keeps the Scala accessor names `world`, `x`, `y` and `z`. `TMultiPart` declares all five -members under exactly these names, which is what implements the interface for every part. Renaming any of them to a -bean accessor would silently unimplement it, so the names are pinned by a characterization test. - -### Removed API - -`TRandomUpdateTick$class`, with its `onWorldJoin` and `$init$` statics. It is the only class removed from the jar by -this port; the full class list is otherwise identical. - -`onWorldJoin` **cannot** become an interface default. `TMultiPart` declares `onWorldJoin`, and a superclass method -always beats an interface default on the JVM, so the default would never run and the failure would be silent. It stays -abstract, and each implementor declares it and calls `TickScheduler.loadRandomTick` itself, which is what -`RedstoneTorchPart` — the only implementor in this codebase — already did. The Scaladoc already carried this warning -for Java implementors; it now applies to Scala implementors too. - -No jar in the pack references `TRandomUpdateTick` in any form, and the frozen baseline contains exactly the eight -`$class` helpers listed in the inventory, which does not include this one. Per the `IDWriter` precedent, no -compatibility bridge was written. The consequence to accept: a Scala class mixing in `TRandomUpdateTick` and relying -on the trait's `onWorldJoin` must now declare it, or it will resolve to `TMultiPart`'s no-op and never register for -random ticks. This is a recompiled-Scala-consumer break with no shipping consumer. - -### Validation - -- Complete plain-JVM suite: 99 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 5 tests, 0 failures, 0 errors. -- Public members, descriptors and the full emitted class list diffed against a reference jar built at `3e68e67`. -- Random tick firing over time still needs a world and stays on the manual checklist, as does torch display-tick - rendering and hollow-cover connection sizing. - -## 2026-08-15 — MultipartHelper Java port - -The NBT and description-packet entry point. Two of its statics are linked against by shipping jars, and guidenh -reflects on both `MultipartHelper` and `MultipartHelper$` by name. - -### Observable behavior - -No known divergence. The id guard still returns null before assigning `MultipartSaveLoad.loadingWorld`, so a tag that -is not a saved multipart still leaves the loading world untouched. `sendDescPacket` still resolves the chunk from the -tile's own coordinates and still sends nothing when `getDescPacket` returns null, which it does when the iterator -yields no `TileMultipart`. - -`createTileFromParts` now builds one `JavaConversions` wrapper and passes it to both `generateCompositeTile` and -`loadParts`, where the Scala applied the implicit conversion separately at each call site. Both wrappers were views -over the same `java.lang.Iterable`, so this is one allocation fewer and the same traversal. - -### Supported JVM API - -- `MultipartHelper` is public-member-identical and descriptor-identical to the reference, including - `createTileFromParts`'s `java.lang.Iterable` parameter, which is easy to misread as Scala's. -- `MultipartHelper$IPartTileConverter` is identical, including the `clazz()` accessor Scala generated for its `val`. -- `MultipartHelper$` keeps `MODULE$`, its private constructor and all four instance forwarders, identical. -- The full emitted class list is unchanged: nothing was added or removed. - -`MultipartHelper$` was kept deliberately. It is not among the 17 `MODULE$` singletons the inventory found read from -bytecode, and no jar links against it, but guidenh names it as a reflective string constant. The inventory warns that -removing a companion breaks those consumers even where no bytecode reference exists, so this one stays. This is the -opposite call to `IconHitEffects$`, which was dropped because nothing referenced it in bytecode *or* by name. - -### Differences that are not API - -- `MultipartHelper` gains a private constructor, as every converted Scala `object` has. -- `MultipartHelper$`'s class initializer loses its `ACC_PUBLIC` flag: Scala emits `public static {}`, `javac` emits - `static {}`. The JVM invokes `` implicitly and it cannot be named by any caller. -- `IPartTileConverter.convertMulti` returns `Collections.emptyList()` or `Collections.singletonList(part)` instead of a - `scala.collection.convert.Wrappers$SeqWrapper` over a Scala `Seq`. The declared type was always `java.lang.Iterable` - and no consumer implements or inspects the concrete type, so this is an implementation detail, and it removes a - wrapper allocation per converted tile. -- The two commented-out blocks the reference carried — the `PlayerInstance.playersInChunk` reflection and the - multi-tile `sendDescPackets` — are not reproduced as dead code. The reason they were removed, a missing forge access - transformer, is recorded in the class javadoc instead. - -### The cast in convert is still checked - -`convert(TileEntity)` calls `convertMulti((T) tile)`, and erasure turns that cast into `(TileEntity)`, which cannot -fail. The `ClassCastException` a mismatched tile produces comes from the synthetic bridge method on the *subclass* -that overrides `convertMulti(T)`, exactly as it did under Scala's `asInstanceOf[T]`. The mechanism is unchanged, and -`convertFailsOnATileTheConverterDoesNotAccept` pins it because it looks like erasure should have swallowed it. - -### Validation - -- Complete plain-JVM suite: 107 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 10 tests, 0 failures, 0 errors, 5 of them new for this port. They cover - everything the plain-JVM suite cannot reach: tile construction through the ASM generator, the NBT round trip through - the save/load hooks, `registerTileConverter` appending to a Scala `MutableList`, and `sendDescPacket` against a - loaded chunk. -- Public members, descriptors and the full emitted class list diffed against a reference jar built at `0fdf9e5`. -- What stays manual: a description packet actually arriving at a watching client. The functional test builds and sends - one with no players connected, so the wire format and the client's handling of it are still unasserted. - -## 2026-08-15 — TileCache Java port - -The client-side tile recovery cache. **Zero downstream references**: no jar links against any member, and guidenh's -reflective name list does not include it. That makes this the first port free to change shape rather than preserve it, -on the `IDWriter` precedent. - -### Observable behavior - -No known divergence. `add` still stores the tile unflagged and `remove` still replaces that entry with a flagged one -rather than dropping it, both keyed by a fresh `BlockCoord` built from the tile's own coordinates. `findTile` still -prefers the world's tile, still warns only when the cached entry is not flagged removed, and still throws -`RuntimeException("DC: Client multipart @" + c + " not found")` when the cache has nothing. - -The reference's trailing `case _ => null` in `findTile` is unreachable — `Some(FlaggedTile(t, rem))` matches whatever -the flag is — so a tile flagged removed is returned just like any other, silently. The Java port makes that explicit -with a comment instead of a dead branch, and `stillReturnsATileThatWasFlaggedRemoved` pins it. - -### Changed API - -All of it is unreferenced, and each change removes a Scala type from a signature no Java caller could use naturally: - -| Member | Reference | Port | -| --- | --- | --- | -| `map()` | `scala.collection.mutable.Map` | `java.util.Map` | -| `add`, `remove` | returned `scala.Option` (the displaced entry) | `void` | -| `apply(BlockCoord)` | `scala.Option` | `FlaggedTile`, null when absent | - -`findTile` and `clear` are unchanged. No internal caller used any of the discarded return values: `TileMultipart` calls -`add`/`remove`/`findTile` and `MultipartEventHandler` calls `clear`. - -### Removed API - -- `TileCache$` and `TileCache$FlaggedTile$`, the two companion singletons. Nothing references either in bytecode or by - name, which is the `IconHitEffects$` case rather than the `MultipartHelper$` one. -- `FlaggedTile`'s case-class machinery: `copy`, `copy$default$1`, `copy$default$2`, `canEqual`, `equals`, `hashCode`, - `toString`, `productPrefix`, `productArity`, `productElement`, `productIterator`, and the `scala.Product` and - `scala.Serializable` interfaces. It is only ever a map *value*, never compared, hashed, printed or destructured, so - none of it was load-bearing. `t()` and `removed()` are kept under their generated names. - -### Validation - -- Complete plain-JVM suite: 114 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 13 tests, 0 failures, 0 errors, 3 of them new. `findTile` needs a world, so all - three branches are covered there rather than headless. -- Class list and members diffed against a reference jar built at `b92d4b7`. Two classes removed, both companions. -- One characterization assertion changed with the port: the test's `entryAt` adapter stopped unwrapping a - `scala.Option`. It was written as the single place the collection types are named precisely so this diff would be two - lines. Every behavioral assertion is unchanged and passed before and after. -- What stays manual: the recovery path itself. It only fires when a client tile is evicted from its chunk before its - update packet arrives, which no test reproduces. - -## 2026-08-15 — PacketScheduler Java port - -`PacketScheduler`, `IScheduledPacketPart` and `TScheduledPacketPart`. **Zero downstream references** and, unusually, -zero implementors in this codebase either: the whole subsystem is a third-party extension point that no shipping mod -in the pack uses. - -### Observable behavior - -No known divergence. `schedulePacket` still refuses a client world with `IllegalArgumentException`, still ORs repeated -masks for the same part, and `sendScheduled` still skips parts whose tile is null, still writes the mask at the part's -own width before calling `writeScheduled`, and still clears the schedule at the end. - -It also still fails rather than writing nothing for a mask width outside 1, 2, 4 and 8. The reference matched with no -fallback and raised `scala.MatchError`; the port throws `IllegalArgumentException`. Both are `RuntimeException`, which -is what the characterization asserts, and there is no consumer to notice the type. The map is still **not** cleared -when that throw happens, because the reference had no `try`/`finally` and the port does not add one. - -### Supported JVM API - -- `IScheduledPacketPart` is member- and descriptor-identical to the reference. -- `PacketScheduler.schedulePacket(TMultiPart, long)` is unchanged. -- `TScheduledPacketPart` keeps `read` **abstract**. `TMultiPart` declares `read`, so a default would be shadowed by the - superclass and a part would silently read a description instead of a mask. - -### Changed API - -`TScheduledPacketPart.writeScheduled` and `readScheduled` became interface defaults with empty bodies. They were -abstract on the reference interface with the empty bodies held in `TScheduledPacketPart$class`, which is to say a Scala -implementor already got them for free and only a Java implementor had to write them out. Making them defaults restores -the trait's source-level semantics for Java implementors rather than changing them. `TMultiPart` declares neither, so -the default-versus-superclass rule permits it. - -Added `TScheduledPacketPart.readMask(TScheduledPacketPart, MCDataInput)`, a Java 8 interface static carrying the mask -dispatch that `TScheduledPacketPart$class.read` used to hold. Because `read` cannot be a default, this is what makes -the interface worth mixing in: implementors write a one-line `read` that delegates to it. The javadoc carries the -snippet. - -`sendScheduled` is public. The reference declared it `private[multipart]`, which reaches `codechicken.multipart.handler` -where the only caller lives; Java has no scope that spans a package and its siblings, so package-private would not -compile and public is the only option. - -### Removed API - -`PacketScheduler$` with its `MODULE$`, and `TScheduledPacketPart$class`. Neither is referenced by any jar in the pack, -in bytecode or by reflective name, so both fall under the `IconHitEffects$` case rather than the `MultipartHelper$` -one. The two `PacketScheduler$$anonfun$` closure classes go with them; the Java loop produces no replacement. - -### Validation - -- Complete plain-JVM suite: 118 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 18 tests, 0 failures, 0 errors, 5 of them new for this port. -- Class list and members diffed against a reference jar built at `3ad25f5`. -- Two characterization adjustments, both anticipated: the functional test's `sendScheduled` helper stopped naming - `PacketScheduler$.MODULE$`, and the structural test stopped asserting that `writeScheduled` and `readScheduled` are - abstract on `TScheduledPacketPart`, asserting the member set instead. Every behavioral assertion is unchanged. -- What stays manual: the client-world guard. `schedulePacket` throws only when `world.isRemote`, which neither harness - can produce — the plain JVM cannot build a `World` and the dedicated server is never remote. - -## 2026-08-15 — ControlKeyModifer and ControlKeyHandler Java port - -The placement-modifier key: a server-side map of which players hold it, and the client key binding that keeps that map -in sync. **Zero downstream references**, and not among guidenh's reflective names. - -The misspelling in `ControlKeyModifer` is the published name and is kept. The file was named `ControlKeyModifier.scala` -while the object inside it was `ControlKeyModifer`; only the file name is corrected. Renaming the type would be an API -change with no forcing reason, so it is left for a deliberate decision rather than smuggled into a port. - -### Observable behavior - -No known divergence. `isControlDown` still branches on whether the player's world is remote, still reports -`isClientPressing` on a client and the recorded map value on a server, and an unrecorded player still reads as not -holding. `ControlKeyHandler.tick` still fires only on a change, still checks the net handler before sending, and still -sets the client flag before writing packet 1. - -The reference's map was `HashMap().withDefaultValue(false)`; the port uses a plain `HashMap` and treats an absent key -as false at the single read site, which is the only place the default was ever observable. - -### Changed and removed API - -| Member | Reference | Port | -| --- | --- | --- | -| `isControlDown(EntityPlayer)` | static | **unchanged**, the documented Java entry point | -| `isClientPressing()` | static | unchanged | -| `isClientPressing_$eq(boolean)` | static | `setClientPressing(boolean)` | -| `map()` | `scala.collection.mutable.Map` | `java.util.Map` | -| `playerControlValue(EntityPlayer)` | static, returned `ControlKeyValue` | removed | - -Removed classes: `ControlKeyModifer$`, `ControlKeyModifer$ControlKeyValue` and `ControlKeyHandler$`. Nothing -references any of them in bytecode or by reflective name. - -`ControlKeyValue` and `playerControlValue` existed only to give Scala `player.isControlDown` sugar through an implicit -conversion. They are meaningless from Java, and the reference already shipped `isControlDown(EntityPlayer)` explicitly -"for Java users". The one in-repo user, `MicroblockPlacement`, now calls that static directly. - -### ControlKeyHandler is now an ordinary class with a singleton - -The reference was a Scala `object` extending `KeyBinding`, so the instance the key registry and the event bus both -needed was `ControlKeyHandler$.MODULE$`, and `ControlKeyHandler` was a class of static forwarders — including -forwarders for twelve inherited `KeyBinding` members. The port makes `ControlKeyHandler` itself the `KeyBinding` -subclass with a single `INSTANCE`, and `MultipartProxy_clientImpl` passes `ControlKeyHandler.INSTANCE`. - -Consequence to note: referencing `ControlKeyHandler` at all now loads `KeyBinding`, where before only the companion -did. Both are reached solely from the client proxy's `postInit`, so nothing changes in practice, and the class carries -`@SideOnly(Side.CLIENT)`. - -### Validation - -- Complete plain-JVM suite: 120 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 21 tests, 0 failures, 0 errors, 3 of them new. `isControlDown` needs a real - player to pick its branch, so they run against a Forge `FakePlayer` on a server world, which takes the server branch. -- Class list and members diffed against a reference jar built from the pre-port `src/main`. -- No characterization assertion changed with the port. -- What stays manual, and it is most of the client half: the key binding appearing in the controls screen, the packet - actually reaching the server on press and release, and `isControlDown` reporting the pressed state on a client world. - No harness has a client, so `isClientPressing` is never exercised. - -## 2026-08-15 — Package objects removed rather than ported - -`codechicken.multipart.package` and `codechicken.microblock.package`. This entry records a **removal**, not a -conversion, because a conversion is impossible. - -### Why they have no Java form - -A Scala package object compiles to a class literally named `package`, plus its `package$` companion. `package` is a -Java keyword, so no Java source can declare or even name those types. The characterization test had to reach both of -them through `Class.forName`, which is the whole argument in one line. - -That left three options: leave two six-line Scala files in the tree forever, invent a Java type to hold the member, or -remove the indirection. Each package object held exactly one member — `def logger = MultipartProxy.logger` and -`def logger = MicroblockProxy.logger` — so the third is the honest one. The alias existed only to let Scala code inside -the package write `logger` unqualified; Java has no such sugar, and the proxies already publish the value. - -### Observable behavior - -None changed. The functional characterization asserted before the removal that each alias returned the *very instance* -its proxy holds, so replacing `logger` with `MultipartProxy.logger` / `MicroblockProxy.logger` at the call sites is an -identity substitution. The eight call sites are `ConfigContent` (7) and `MultipartGenerator` (1); both classes are -descriptor-identical after the change, since only method bodies moved. - -### Removed API - -`codechicken/multipart/package`, `codechicken/multipart/package$`, `codechicken/microblock/package` and -`codechicken/microblock/package$`. Exactly those four classes leave the jar and nothing else changes. No jar in the -pack references any of them, in bytecode or by reflective name — no Java consumer *could* reference them by name, and -no Scala consumer did. - -### Validation - -- Complete plain-JVM suite: 120 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 22 tests, 0 failures, 0 errors. -- Class list diffed against a reference jar built from the pre-removal `src/main`: exactly four classes removed. -- Test churn, both expected for a removal rather than a port: `PackageObjectCharacterizationTest` was deleted with its - subject, and `ProxyLoggerFunctionalTest` lost only its alias-identity assertion. What survives is the assertion worth - keeping — that both proxies publish a non-null logger during preInit, which is what the inlined call sites now read. - -## 2026-08-15 — MultipartRenderer Java port - -The client rendering callbacks. No jar links against any member, but guidenh reflects on **both** `MultipartRenderer` -and `MultipartRenderer$` by name, resolving `renderWorldBlock` as a static first and falling back to the companion's -`MODULE$`. Both classes are therefore kept, in the `TickScheduler$` shape: the companion holds the implementation -because Forge registers that instance itself, and the plain class is static forwarders. - -### Observable behavior - -No known divergence. The render id is still claimed in the singleton's initialiser, which preserves the reference's -timing: a Scala object runs its body on first access, and the first access is the client proxy's `postInit`. -`renderWorldBlock` still returns false for a non-multipart tile, for an empty part list, and after drawing a breaking -overlay; `renderTileEntityAt` still returns early unless the tile has dynamic parts; `getRenderId` still reads -`TileMultipart.renderID`. - -The reference wrote the dynamic-part guard with a non-short-circuiting `|`. The port uses `||`. Both operands are -side-effect-free getters, so this cannot differ. - -The breaking-overlay branch moved into a private helper. The reference nested a pattern match inside an `if`; the hit -data is a `scala.Tuple2` that arrives erased, so the port checks the tuple and then the boxed index before unboxing, -which is what the match compiled to. `BlockMultipart` already reads the same data the same way. - -### Supported JVM API - -The emitted class list is **unchanged** — nothing added, nothing removed. All five rendering callbacks keep their -exact signatures on `MultipartRenderer`, `MODULE$` keeps its type and flags on `MultipartRenderer$`, and both classes -keep class-level `@SideOnly(Side.CLIENT)`, so both are still stripped on a dedicated server. - -`MultipartRenderer$` still extends `TileEntitySpecialRenderer` and implements `ISimpleBlockRenderingHandler`. Forge -rejects the registration outright if either is missing, and the characterization asserts both. - -### Differences that are not API - -- `MultipartRenderer` loses `func_147498_b`, `func_147496_a` and `func_147497_a`, the forwarders Scala generates for - inherited `TileEntitySpecialRenderer` members. Same category as the twelve `KeyBinding` forwarders dropped from - `ControlKeyHandler`: artifacts of the object-forwarder mechanism, not API, and unreferenced. -- `MultipartRenderer$`'s class initialiser loses `ACC_PUBLIC`, as every converted companion has. -- The unused `com.gtnewhorizons.angelica.api.ThreadSafeISBRH` import is dropped. It appears nowhere else in the - codebase and annotated nothing; no behavior depended on it. Worth a second look independently — if the intent was to - mark this ISBRH thread-safe for Angelica, that annotation was never actually applied in the reference either. - -### Scala's uniform access hid a field-versus-method difference - -`renderer.hasOverrideBlockTexture` reads identically in Scala whether it is a field or a no-arg method. It is a method -on `RenderBlocks`, and the port did not compile until it became `hasOverrideBlockTexture()`. This is a compile-time -failure rather than a silent one, but it will recur in every remaining renderer conversion. - -### Validation - -- Complete plain-JVM suite: 125 tests, 0 failures, 0 errors. -- Clean `spotlessApply checkstyleTest build`: passing. -- Java 8 Forge dedicated-server suite: 22 tests, 0 failures, 0 errors. It does not exercise this class and cannot: - the server never loads it. -- Class list and members diffed against a reference jar built from the pre-port `src/main`. -- No characterization assertion changed with the port. -- What stays manual, and it is everything this class actually does: static block rendering, dynamic part rendering, - the breaking overlay on the struck part, inventory rendering, and the render id being claimed exactly once. None of - it can run without a client, so all of it is on the checklist. - -## 2026-08-28 — IRedstonePart and RedstoneInteractions Java port - -The complete source unit: six abstract interfaces plus the routing singleton. ProjectRed, ProjectBlue, WR-CBE, -Extra Utilities, OpenComputers and AE2 consume this surface; ProjectRed also reads `RedstoneInteractions$.MODULE$` -directly, so the companion cannot be collapsed into a static utility class. - -### Observable behavior - -No known divergence. Plain, face, and custom-mask parts retain the same precedence and bit masks. Connector tiles -still win over connector blocks, which still win over vanilla handling. Neighbor lookups retain the same coordinate -offset and opposite-side transform. Full-connect blocks, wire/comparator visual masks, repeater orientation, the -redstone-wire metadata fallback, and `Block.canConnectRedstone` retain their existing branches. Java uses -`Objects.equals` where Scala used null-safe `==`. - -`vanillaSideMap`, `sideVanillaMap`, and `fullVanillaBlocks` remain singleton-owned objects returned by identity from -both published classes. `fullVanillaBlocks` deliberately remains a `scala.collection.immutable.Set` so its -descriptor and existing Scala consumers do not change. - -### Supported JVM API - -The emitted class list is unchanged: the six interface classes, `RedstoneInteractions`, and -`RedstoneInteractions$`. Every public member and descriptor is unchanged. `RedstoneInteractions` remains the static -façade and `RedstoneInteractions$.MODULE$` remains the implementation instance. The Java façade necessarily has a -private constructor where Scala's static-forwarder class emitted none; no consumer references constructors on either -class. - -The six Scala traits contained only abstract members, so they emitted no `$class` helpers and need no compatibility -bridges. Their Scala signatures disappear, but inheritance and JVM method descriptors are identical. - -### Performance boundary - -The fresh Scala baseline measured 80.4 B per generated redstone three-query iteration; the Java result measured -80.5 B. Post-port JFR still attributes the work to Scala `List.foreach`, `Iterator.foreach`, `PartMap.edgeBetween`, and -the generated strong-power closure in `scalatraits/TRedstoneTile.scala`. This port therefore claims no performance -gain. Removing that allocation requires the later `registerJavaTrait` conversion and is explicitly deferred. - -### Validation - -- `RedstoneInteractionsCharacterizationTest`: 6 tests, covering every interface shape and pure routing branch. -- Complete plain-JVM suite: 139 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 31 tests, 0 failures, 0 errors; three tests cover initialized vanilla state, - actual world routing, and a generated redstone tile. -- Clean `spotlessApply checkstyleTest build`: passing. -- Class list and public members diffed against the pre-port build; no characterization assertion changed. - -## 2026-08-28 — MicroRecipe Java port - -The complete recipe singleton moved together. Extra Utilities consumes this area through NEI recipe enumeration, and -the audited binary corpus calls `create`, `findMaterial`, and `getCraftingResult`; the port preserves the larger -published surface as well. - -### Observable behavior - -No known recipe divergence. Hollow construction, gluing, vertical thinning, horizontal splitting, and hollow filling -retain their exact slot shapes and early rejection rules. A ring of eight size-one covers is valid both as a hollow -recipe and as gluing back to a full block; `getCraftingResult` still chooses the hollow result first. Gluing retains -the separate cover/hollow, edge, and corner rules, and splitting keeps the `0 -> 3`, `1 -> 3`, `3 -> 2` map. - -Saw discovery remains row-major. Cutting still accepts either sufficient strength or exactly the registry's maximum -saw strength. Full-size results still copy the material's source stack, while smaller results retain the material name -in an `ItemMicroPart`. `findMaterial` still returns the first exact item, damage, and NBT match. This means the missing -material placeholder's vanilla-stone stack can shadow a later stone entry; the Forge tests deliberately use glass when -they need an unambiguous raw-material round trip. - -Java uses `Objects.equals` where Scala used null-safe `==`. Internal thinning and splitting locate the saw by slot -number to avoid constructing the published tuple for private work; direct `getSaw` calls still return the same boxed -`scala.Tuple3`. - -### Supported JVM API - -`MicroRecipe` retains all 17 public static methods with their exact descriptors. `MicroRecipe$` still implements -`IRecipe`, exposes `MODULE$`, carries the implementation methods, and publishes the same -`scala.collection.immutable.Map` by identity. The Java façade necessarily has a private constructor, -as with the other converted Scala forwarder classes. - -The 12 private `MicroRecipe$$anonfun$...` compiler classes disappear; no consumer references them. The in-repo Scala -proxy now registers `MicroRecipe$.MODULE$` explicitly because deleting the Scala object removes the compiler symbol -that allowed `MicroRecipe` to be used as a value. Existing bytecode remains compatible through the retained companion. - -### Performance boundary - -Ordinary loops remove the range, filter, collection-search, captured-ref, and `NonLocalReturnControl` machinery from -recipe matching. No recipe workload was added to the focused tick/redstone profiler, so this is a structural result, -not a numeric performance claim. The public `getSaw` tuple allocation remains compatibility-required; internal recipe -paths no longer pay for it. - -### Validation - -- `MicroRecipeBinaryCompatibilityTest`: 2 tests covering the complete façade/companion ABI, `MODULE$`, and split map. -- `MicroRecipeFunctionalTest`: 6 Forge tests covering all recipe forms, precedence, class mappings, saw order, - material lookup, NBT sensitivity, metadata, creation, and rejection paths. -- Complete plain-JVM suite: 141 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 37 tests, 0 failures, 0 errors. -- Class list and public members compared with the pre-port build; no characterization assertion changed. - -## 2026-08-28 — TPartialOcclusionTile Java-trait pilot - -This is the first built-in generated tile implementation whose source moved directly to Java. It was already a -concrete Scala class, so the existing registration path treated it as a Java trait and rewrote it at class-load time; -the port changes the compiler input without changing that generator. - -### Observable behavior - -No known divergence. A partial-occlusion candidate is still appended to the existing Scala `Seq` and tested before -the normal superclass pairwise chain. Failure still short-circuits that chain. Non-partial candidates still go directly -to the superclass. `partialOcclusionTest` still fills only `JPartialOcclusion` entries at their original indices and -retains `PartialOcclusionTest`'s exclusive-voxel and complete-occlusion rules. - -Java uses a Scala `Seq` builder for the appended candidate because Scala 2.11's `Seq.:+` builder signature is not -expressible type-safely from javac with its wildcarded `CanBuildFrom`. The resulting call still dispatches through the -public `partialOcclusionTest(Seq)` method, preserving subclass/generated override behavior. - -### Supported JVM and generated APIs - -The direct compiled class still extends `TileMultipart`, has no fields or interfaces, one public no-arg constructor, -and exactly the same two public method descriptors. No anonymous or helper class is emitted. There were no direct -downstream references to this class in the audited mod corpus; consumers reach the behavior through -`JPartialOcclusion` parts and generated tiles. - -At Forge class-load time the same name is still rewritten to a public interface with no fields and exactly three -methods: `occlusionTest`, `partialOcclusionTest`, and the generated -`codechicken$multipart$scalatraits$TPartialOcclusionTile$$super$occlusionTest` accessor. Generated composite instances -still implement it, and equal trait sets still reuse the same generated class. - -The Scala source signature disappears from the untransformed class. No supported consumer used it, no `$class` helper -existed in the input artifact, and the runtime generator continues to create the implementation helper it requires. - -### Scope boundary - -This pilot has no fields or lifecycle callbacks. It therefore does not validate field-to-accessor rewriting, -constructor initialization injection, setter rebinding, copying, or part add/remove lifecycle order. Those are not -assumed safe from this result; `TSlottedTile` is the explicit stateful checkpoint before broader trait conversion. - -### Validation - -- `TPartialOcclusionTileCharacterizationTest`: 4 tests covering exact direct shape, partial/normal precedence, - exclusive visibility, complete-occlusion exemption, and both short-circuit paths. -- Complete plain-JVM suite: 145 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 37 tests, 0 failures, 0 errors. -- Runtime reflection verifies the exact generated interface methods, no fields, override behavior, and class reuse. - -## 2026-08-28 — TSlottedTile Java-trait port - -This is the stateful `registerJavaTrait` checkpoint. OpenComputers casts generated tiles to this type, retrieves the -public `v_partMap()` array, mutates matching entries in place, and calls `bindPart` to rebuild them. The frozen binary -inventory contains that exact getter descriptor and no reference to `TSlottedTile$class`. - -### Observable behavior - -No known runtime divergence. Every generated tile receives its own 27-entry array. `copyFrom` still calls its super -implementation first and then shares the source array by identity only when the source is slotted. `partMap` preserves -normal array indexing. `clearParts` still clears both the superclass part list and every entry in the current array. - -`partRemoved` still calls super first, acts only on `TSlottedPart`, scans exactly 27 slots, and uses Scala-style -null-safe value equality; Java uses `Objects.equals` to preserve the last detail. `canAddPart` still rejects the first -occupied masked slot before delegating to the base tile, while non-slotted and conflict-free parts delegate normally. -`bindPart` still calls super first and fills each of the 27 positive masked slots. OpenComputers' external mutation and -rebind pattern is exercised directly. - -### Generated ABI and raw input divergence - -At Forge runtime `TSlottedTile` remains a public interface with no fields and the exact same 13 abstract methods: six -behavior methods, `v_partMap` getter/setter, and five super accessors. The generated composite still owns a -`TMultiPart[] v_partMap` field, runs the 27-entry initializer for every instance, and reuses its class for equal trait -sets. All 27 shipping consumer jars therefore retain their binary linkage. - -The untransformed artifact necessarily changes shape. Scala emitted an interface, a static `$class` implementation -helper, and four `$$anonfun$` range classes. Java emits one concrete `TileMultipart` subclass with a public array field, -one no-arg constructor, and six overrides; `registerJavaTrait` creates the interface/helper at class-load time. No -shipping consumer references the removed raw helper or closure classes. - -This produces an accepted source-build limitation: code recompiled directly against the raw dev jar sees a class and -public field, so it may emit `invokevirtual` or `getfield`; Forge later rewrites that owner to an interface, for which -those opcodes are invalid. Existing binaries such as OpenComputers use `invokeinterface` and remain valid. A future -downstream-source release needs either a transformed compile stub/API artifact or explicit avoidance of direct -generated-trait calls; runtime binary compatibility does not by itself solve that development artifact problem. - -### Performance boundary - -Ordinary loops remove the four Scala `Range.foreach` closure classes and the `NonLocalReturnControl` used for occupied -slot rejection. The retained focused profiler does not perform slotted placement, so this is a structural removal, not -a numeric performance claim. No new dependency or generator change was needed. - -### Validation - -- `TSlottedTileFunctionalTest`: 6 Forge tests covering copy identity, non-slotted copy, external mutation/rebinding, - bind/remove/clear semantics, value equality, and occupied/free/non-slotted placement. -- `ForgeEnvironmentSmokeTest` verifies the exact 13-method runtime interface, generated field, distinct initialized - arrays, setter rebinding, and class-cache identity. -- Existing live-world lifecycle tests continue to cover add/remove slot caches and relocation of the generated tile. -- Complete plain-JVM suite: 145 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 43 tests, 0 failures, 0 errors. - -## 2026-08-28 — TRedstoneTile Java-trait port - -ProjectRed directly casts a generated tile to `TRedstoneTile` and calls `openConnections(int)`. Extra Utilities casts -the same type and calls the inherited one-argument `weakPowerLevel(int)`. Neither shipping consumer references -`TRedstoneTile$class`; UtilitiesInExcess has no direct reference in its current source. - -### Observable behavior - -No known runtime divergence. Strong power still scans only `IRedstonePart` instances, ignores connection masks, and -returns the greatest positive level from a zero baseline. Face and edge parts retain the same center/rotation -conduction rules. Connection masks are still intersected with the open face/edge mask before being combined, while -weak power calls only connected redstone parts and takes their maximum from zero. - -The one-argument weak-power method still intersects the tile's mask with the adjacent connector's power mask. -`canConnectRedstone` still applies the legacy vanilla-to-multipart side mapping and uses the neighbor's non-power mask. -Normal immutable Scala `List` storage is traversed without allocation; an arbitrary `Seq` supplied through the public -setter retains an iterator fallback. - -### Generated ABI and raw input divergence - -At Forge runtime `TRedstoneTile` remains a public interface extending exactly `IRedstoneTile`, with no fields and the -same eight abstract methods: `strongPowerLevel(int)`, both `weakPowerLevel` overloads, `canConnectRedstone(int)`, -`openConnections(int)`, `getConnectionMask(int)`, `redstoneConductionF(int)`, and `redstoneConductionE(int)`. -Generated composites still implement that interface, and equal trait sets still reuse the same generated class. - -The untransformed artifact changes from the Scala interface, `$class` helper, and four `$$anonfun$` classes to a -concrete Java `TileMultipart` subclass plus package-private `TRedstoneTileAccess`. The shim is required because the -current Java-trait transformer treats direct inherited field reads as trait fields and emits an invalid cast for -inherited virtual calls. It performs coordinate, `partList`, and virtual `partMap` access outside the transformed -class. It adds no public member and does not change the generator. - -As with `TSlottedTile`, this preserves existing consumer binaries but not recompilation directly against the raw dev -jar: Java source presents the mixin input as a class, while Forge rewrites it to an interface at runtime. A transformed -compile stub or downstream source guidance is still required before claiming source-compatible rebuilds. - -### Performance result - -The paired 50,000,000-iteration Forge/JFR run fell from 4,023,855,000 allocated bytes / 80.5 B per three-query -iteration to zero measured bytes / 0.0 B. Elapsed time fell from 7.534 s to 6.261 s, raising throughput from 6,636,424 -to 7,986,213 iterations/s (20.3%). Both runs produced checksum `3315999992`. - -### Validation - -- `TRedstoneTileFunctionalTest`: 3 Forge tests covering the exact eight-method interface and class cache, face/edge - conduction, strong and weak maxima, mask filtering, non-redstone parts, arbitrary `Seq` input, neighbor masks, and - vanilla-side translation. -- Complete plain-JVM suite: 145 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 46 tests, 0 failures, 0 errors. -- Clean formatting, checkstyle, build, generated runtime reflection, and paired profile checksum. - -## 2026-08-28 — multipart read-path cleanup - -### Observable behavior and ABI - -No known runtime divergence. Focused tests pin max-or-zero lighting, torch support, live reads through a mutable `Seq`, -direct ordered indexing, and `BlockMultipart.getTile`'s non-multipart/empty/non-empty filtering. Internal code now reads -the published `Seq` directly. The public `partList`, `partList_$eq`, and `jPartList` descriptors and live-view behavior -are unchanged; add/remove still snapshot before publishing a replacement immutable `Seq`. - -### Performance result - -The paired 50,000,000-iteration Forge/JFR run reduced `getLightValue` from 9,196,067,864 allocated bytes / 183.9 B per -call to zero and raised throughput 11.42x. `BlockMultipart.getTile` fell from 1,200,000,000 bytes / 24.0 B per call to -zero and rose 2.89x. Both runs used the same eight-part tile and produced the same checksum. - -### Validation - -- Complete plain-JVM suite: 147 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 46 tests, 0 failures, 0 errors. -- The public Java list bridge remains for downstream consumers; there are no internal `jPartList()` callers. - -## 2026-08-28 — TTileChangeTile Java-trait port - -The first Java trait carrying both mutable state and inherited-member access. Nothing in the frozen consumer baseline -references `TTileChangeTile` or a `$class` helper for it; the load-bearing surface is `INeighborTileChange`, which is -already Java and byte-for-byte unchanged across the port. ProjRed and Extra Utilities implement that interface on their -parts and never touch the tile trait. - -### Observable behavior - -No known runtime divergence. `bindPart` still calls super first and only ever ors the flag in, so a later part that -does not want weak changes cannot clear it. `copyFrom` still takes the flag from another change tile and leaves it -untouched for a plain source. `clearParts` still resets both the superclass list and the flag. `partRemoved` still -recomputes from the remaining published list rather than from the part it is handed, and still short-circuits on the -first weak part, matching `exists`. - -`onNeighborTileChange` keeps the same coordinate filter: it calls super first, computes the offset from the tile's own -coordinates, and returns unless the offset is axial with an absolute sum of one or two. Two blocks is still reported as -weak. Dispatch still goes through `operate`, so the null-tile guard and any trait overriding `operate` still apply. - -### Generated ABI and raw input divergence - -At Forge runtime `TTileChangeTile` remains a public interface with no fields and the exact same 13 methods: six -behavior methods, the `weakTileChanges` getter and setter, and five super accessors. The generated composite owns a -`boolean weakTileChanges` field, and state stays per tile. `ForgeEnvironmentSmokeTest` freezes that shape. - -The untransformed artifact changes shape, as with every Java-trait port. Scala emitted an interface, a `$class` helper, -an `$$anon$1` for the operate callback, and an `$$anonfun$partRemoved$1` for the `exists` scan. Java emits one concrete -`TileMultipart` subclass, plus the `TTileChangeTileAccess` helper and its callback class. No shipping jar references -any of the removed classes. The recompile-against-the-raw-dev-jar limitation recorded for `TSlottedTile` applies here -unchanged. - -### Two transformer constraints found by this port - -**A Java mixin trait may not carry an inner class.** `registerJavaTrait` rejects a non-empty `InnerClasses` attribute -outright, so the anonymous `AbstractFunction1` for the `operate` callback could not live in the trait. It moved to -`TTileChangeTileAccess` as a named class, which the transformer does not process. Any future Java trait needing a -callback, a lambda or a switch on strings has the same constraint. - -**An access shim must not name a compile-time supertype of the trait.** The first attempt typed the shim parameters as -`TTileChangeTile` and cast to `TileMultipart` inside. Because the untransformed trait extends `TileMultipart`, javac -elided the cast entirely, and once Forge rewrote the trait to an interface the verifier rejected the resulting -`getfield` with "Type TTileChangeTile is not assignable to TileMultipart". `TRedstoneTileAccess` avoids this only by -accident: `IRedstoneTile` is unrelated to `TileMultipart`, so javac was forced to emit a real `checkcast`. The general -fix, used here, is to type the shim parameters as `Object` so the cast is always emitted. - -### Validation - -- `TTileChangeTileFunctionalTest`: 7 Forge tests covering the flag lifecycle across bindPart, copyFrom, clearParts and - partRemoved, plus the coordinate filter and the per-part dispatch filter. -- `ForgeEnvironmentSmokeTest.generatesAndCachesTileChangeTileClass`: interface shape, field type, per-tile state and - generated-class reuse. -- All eight were written and passed against the untouched Scala trait first, and pass unchanged after the port. -- Complete plain-JVM suite: 153 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 54 tests, 0 failures, 0 errors. -- `INeighborTileChange` descriptors identical between the reference and ported dev jars. - -## 2026-08-30 — TFluidHandlerTile Java-trait port - -No frozen binary or audited source consumer names `TFluidHandlerTile` or its `$class` helper. The load-bearing surface -is Forge's `IFluidHandler`, which generated multipart tiles still implement with the same six fluid method -descriptors. - -### Observable behavior - -No known runtime divergence. Every generated tile receives a distinct `LinkedList`; `copyFrom` still shares that list -by identity only for another fluid tile. Fluid parts are appended in binding order, removal deletes the first equal -entry, and clear empties both the superclass part list and the existing tank list. - -`getTankInfo` still visits every handler twice, first to size the result and then to flatten each returned array in -part order. Fill still passes a fresh copy with the decreasing remaining amount to every handler, including handlers -reached after the full quantity has been accepted. `canFill` and `canDrain` still stop at the first matching handler. - -Both drain overloads still simulate every handler first, accept the first positive fluid and only later matching -fluids, and commit only accepted simulations when requested. The first accepted simulated stack remains the returned -object, with its amount replaced by the total. The stack overload still passes decreasing copies and leaves the -caller's stack unchanged. - -### Generated ABI and raw input divergence - -At Forge runtime `TFluidHandlerTile` remains a public interface extending exactly `IFluidHandler`, with no fields and -the same 16 abstract methods: ten behavior methods, the `tankList` getter and setter, and four super accessors. The -generated composite still owns and initializes a `LinkedList tankList` field, permits setter rebinding, and reuses its -class for equal trait sets. - -The untransformed artifact changes from a Scala interface, `$class` helper, and eight `$$anonfun$` classes to one -concrete Java `TileMultipart` subclass plus package-private `TFluidHandlerTileAccess`. No shipping consumer references -the removed classes. The raw-dev-jar source-build limitation recorded for `TSlottedTile` applies unchanged. - -### Transformer constraint - -The Java-trait transformer rewrites every `GETFIELD` instruction as access to trait-owned state without checking the -instruction's owner. The first port therefore failed registration on the public `FluidStack.amount` field with -`key not found: amount`. `TFluidHandlerTileAccess` now owns those reads, writes, and amount-adjusted copies outside the -transformed class. It adds no public surface and requires no generator change. - -### Performance boundary - -Ordinary loops remove the eight Scala closure classes, but no representative workload in the retained profiler uses -multipart fluid distribution. This is a structural removal, not a throughput or allocation claim. - -### Validation - -- `TFluidHandlerTileFunctionalTest`: 7 Forge tests covering list lifecycle and identity, tank-info order, fill - distribution, capability short-circuiting, fluid matching, simulation, commit behavior, and both drain overloads. -- `ForgeEnvironmentSmokeTest.generatesAndCachesFluidHandlerTileClass`: exact 16-method runtime interface, parent - interface, generated field, distinct initialization, setter rebinding, and generated-class reuse. -- All eight tests passed against the untouched Scala trait first and pass unchanged after the port. -- Complete plain-JVM suite: 153 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 62 tests, 0 failures, 0 errors. -- The frozen consumer inventory and audited source consumers contain no `TFluidHandlerTile` reference. - -## 2026-08-30 — TIInventoryTile/JInventoryTile Java-trait port - -AE2 is the load-bearing consumer for this port. `CableBusPart.notifyNeighbors` checks a generated tile with -`instanceof TIInventoryTile` and directly invokes `rebuildSlotMap()`. The registered trait input is separately named -`JInventoryTile`; preserving only one of those types would break either registration or AE2 linkage. - -### Observable behavior - -No known runtime divergence. Each generated tile starts with distinct empty inventory-list and slot-map instances. -Binding appends only `IInventory` parts in order, removal deletes the matching inventory, and clear empties both the -superclass part list and inventory state. Copying from another inventory tile shares its inventory list by identity and -rebuilds a distinct slot map; copying from a plain tile leaves both current references untouched. - -The slot map still flattens every inventory in list order and routes each global slot to its original inventory and -local index. The fixed name, custom-name flag, stack limit, usability and no-op open/close behavior are unchanged. -Sided access still exposes only `ISidedInventory` slots, while its global base advances across every inventory; -insert/extract checks still delegate to sided inventories and return true for ordinary inventories. - -### Generated ABI and raw input divergence - -At Forge runtime `TIInventoryTile` remains a public interface extending exactly `ISidedInventory`, with no fields and -the exact same 28 methods: 20 behavior/inventory methods, four public state accessors, and four super accessors. -`JInventoryTile` remains a public child interface with no fields and the exact same 36 methods, adding four private- -field accessors and four `JInventoryTile` super bridges. The generated composite still owns the two private fields -`codechicken$multipart$scalatraits$JInventoryTile$$invList` and -`codechicken$multipart$scalatraits$JInventoryTile$$slotMap`, with `LinkedList` and `scala.Tuple2[]` descriptors. - -The raw dev artifact now contains a Java interface `TIInventoryTile`, a concrete Java `JInventoryTile` mixin input, -and package-private `JInventoryTileAccess` instead of the Scala interface, `$class` helper and concrete forwarding -class. No frozen consumer references `TIInventoryTile$class` or names `JInventoryTile`; AE2's load-bearing -`TIInventoryTile.rebuildSlotMap()` descriptor is unchanged. As with the other Java-trait ports, consumers compiling -against the untransformed dev jar should use a transformed compile stub when they name the registered mixin type. - -### Transformer constraint - -The Java-trait stack analyzer has no case for JVM opcode `NEWARRAY` (`188`). Creating the primitive result array in -`getAccessibleSlotsFromSide` initially failed trait registration with `scala.MatchError: 188`. The method now collects -the same ordered boxed slots and delegates only the final `int[]` allocation/copy to package-private -`JInventoryTileAccess`. Reference-array allocation remains inside the trait because its `ANEWARRAY` opcode is already -supported. The helper adds no public surface. - -### Validation - -- `TIInventoryTileFunctionalTest`: 7 Forge tests covering list/map lifecycle and identity, flattened routing, the - direct AE2-shaped rebuild call, fixed metadata, sided global offsets, and insert/extract delegation. -- `ForgeEnvironmentSmokeTest.generatesAndCachesInventoryTileClassWithBothPublicTraitInterfaces`: exact 28- and - 36-method runtime interfaces, inheritance, generated private fields, distinct initialization, setter rebinding, and - generated-class reuse. -- All eight tests passed against the untouched Scala implementation first and pass unchanged after the port. -- Complete plain-JVM suite: 153 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 70 tests, 0 failures, 0 errors. -- Raw `javap` descriptors for both public types match the reference, including `scala.Tuple2[]` state accessors. - -## 2026-08-30 — TileMultipartClient/TRandomDisplayTickTile Java-trait port - -GuideNH is the only audited shipping consumer naming `TileMultipartClient`; it loads the class reflectively and uses -it only for `isInstanceOf`. No frozen binary or audited source consumer references either trait's `$class` helper. - -### Observable behavior - -No known runtime divergence. `updateRenderCache` still partitions each part once in source order, using the same -`doesTick || shouldRenderDynamic` short-circuit, then builds static and dynamic arrays in their respective order. Its -bounding box remains the union of all render bounds translated by tile coordinates, or the full block for an empty or -null part list. Static rendering still visits both caches, dynamic rendering still returns immediately when its flag -is false, queries still initialize lazily, and `markRender` still calls super before rebuilding the cache. - -The base display-tick method remains a no-op. `TRandomDisplayTickTile` still visits only `IRandomDisplayTick` parts in -part-list order and passes the same `Random` instance to every callback. - -### Generated ABI and raw input divergence - -At Forge runtime `TileMultipartClient` remains a public field-free interface with no parent interface and the exact -same 16 methods, including six private-cache accessors and the `markRender` super bridge. -`TRandomDisplayTickTile` remains a field-free child interface extending exactly `TileMultipartClient` and declaring -only `randomDisplayTick(Random)`. Generated composites retain the three private prefixed cache fields plus the plain -private `hasDynamicParts` field, and continue to use the same class cache. - -The raw dev artifact replaces the two Scala interfaces, two `$class` helpers, and three closure classes with concrete -Java mixin inputs plus package-private `TileMultipartClientAccess` and `TRandomDisplayTickTileAccess`. As with earlier -Java-trait ports, a consumer compiling directly against the untransformed dev jar must not emit direct class/field -opcodes for these runtime interfaces; use a transformed compile stub for source-compatible downstream rebuilds. - -`TileMultipart` gains additive no-op `renderStatic`, `renderDynamic`, and `randomDisplayTick` hooks. In-repo Java code -invokes generated overrides through that stable superclass because javac otherwise emits `invokevirtual` against the -concrete mixin input that Forge later rewrites to an interface. Existing binary consumers are unaffected. - -### Transformer constraints - -This is the first registered Java mixin extending another registered Java mixin. `registerJavaTrait` now carries the -parent runtime interface into the generated hierarchy and linearization, while parent validation resolves through the -registered mixin to `TileMultipart`. It also recognizes explicit source field accessors so it does not emit duplicate -runtime declarations. - -Render caches must not be copied by `TileMultipart.copyFrom`, matching the Scala trait. They are marked transient on -the Java mixin input, and automatic Java-trait field copying now ignores transient fields. The generated runtime fields -remain ordinary private fields. Trait registration moved before `BlockMultipart` construction so its -`instanceof TileMultipartClient` bytecode cannot preload the raw class before Forge defines the runtime interface. - -### Validation - -- `TileMultipartClientFunctionalTest`: 6 Forge tests covering cache partition/order, short-circuiting, translated and - fallback bounds, lazy initialization, dynamic early return, base no-op behavior, and ordered display-tick dispatch. -- `ForgeEnvironmentSmokeTest.generatesClientAndRandomDisplayTickTraitsWithTheirExactHierarchy`: exact interfaces, - inheritance, methods, generated fields, distinct combinations, and class-cache behavior. -- All seven tests passed against the untouched Scala implementation before the port; all 77 Forge tests pass after it. -- Complete plain-JVM suite: 153 tests, 0 failures, 0 errors. -- Actual block/TESR rendering and particle appearance require a client and remain on the manual checklist. - -## 2026-08-30 — MultipartCompatiblity/MCPCCompatModule Java port - -The intentionally misspelled `MultipartCompatiblity` singleton and its optional MCPC integration companion are now -Java. The in-repo placement gate still reads the same mutable callback, and no frozen binary or audited source consumer -names either singleton or its generated closure classes directly. - -### Observable behavior - -No known runtime divergence. The callback initially allows every placement. `load()` still performs a case-sensitive -`"mcpc"` check against FML's mod name and otherwise leaves the current callback untouched. MCPC loading still looks -for `World.canPlaceMultipart(Block, int, int, int)`, installs the reflective callback only after a successful lookup, -and logs `Failed to integrate MCPC placement hooks` without replacing the previous callback when lookup fails. - -The installed callback passes `MultipartProxy.block()` and the same boxed coordinates to `Method.invoke`, casts the -result to `Boolean`, and returns its primitive value. Java's checked-reflection restriction is bridged with a private -unchecked throw helper so invocation, access and target failures propagate as the same exception objects rather than -being wrapped in a new exception type. - -### ABI and emitted classes - -The public surface is descriptor-identical to the reference: static `load`, `canAddPart` and `canAddPart_$eq` remain on -`MultipartCompatiblity`; the companion retains `MODULE$`, the private `scala.Function4` field and the three matching -instance methods; `MCPCCompatModule` and `MCPCCompatModule$` retain their static and instance `load` methods. - -Accepted divergence: `MultipartCompatiblity$$anonfun$1` and `MCPCCompatModule$$anonfun$load$1` are replaced by the -private Java callback classes `MultipartCompatiblity$$AllowPlacement` and `MCPCCompatModule$$MCPCPlacement`. These are -closure implementation details with no consumer reference. The four public facade/companion class names are retained. - -### Validation - -- `MultipartCompatiblityCharacterizationTest`: 3 plain-JVM tests, unchanged from the Scala baseline. -- `MultipartCompatiblityFunctionalTest`: 2 Forge tests, unchanged from the Scala baseline. -- Complete plain-JVM suite: 156 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 79 tests, 0 failures, 0 errors. -- Raw `javap` comparison confirms identical public names and descriptors for all four public types. -- The successful reflective path requires an MCPC-patched `World` and remains an environment-specific integration - check; the stock development server covers its failure fallback only. - -## 2026-08-30 — MultipartMod Java port - -The ForgeMultipart FML entry point is now an annotated Java facade/companion pair. It deliberately remains a -`modLanguage = "scala"` mod: FML's Scala language adapter loads `MultipartMod$.MODULE$`, which is also the identity -CodeChickenLib uses for the multipart packet channel. - -### Observable behavior - -No known runtime divergence. Pre-initialization still passes the event's configuration directory and logger to the -proxy; initialization still delegates directly; post-initialization still finalizes the registry and proxy only when -multipart registration is required; server startup still rebuilds the part ID map; and server shutdown still clears -the loading-world reference and control-key map. - -The proxy calls use `MultipartProxy$.MODULE$`, matching the original Scala bytecode. This is required on a dedicated -server: the raw `MultipartProxy.postInit()` static forwarder inherits `@SideOnly(CLIENT)` from the client override and -Forge strips it. Calling that facade from common Java compiles but fails at runtime with `NoSuchMethodError`; companion -dispatch survives stripping and resolves to the server superclass method. - -### ABI, annotations and source compatibility - -`MultipartMod` retains the exact five public static event methods. `MultipartMod$` retains `MODULE$` and the matching -five public instance methods. Both classes still carry the same `@Mod` values, and every method still carries -`@Mod.EventHandler`. Public names and descriptors are identical to the reference. - -The in-repo Scala expression `val channel = MultipartMod` becomes `MultipartMod$.MODULE$`. The compiled -`MultipartPH.channel` field and accessor remain typed as `MultipartMod$`, so packet identity and binary compatibility -are unchanged. No frozen external consumer names either mod class. - -Accepted divergence: the Scala signature/marker attributes disappear, and the static Java facade gains only a private -constructor. These do not change the runtime annotation data or callable public surface. The emitted class list remains -exactly `MultipartMod.class` and `MultipartMod$.class`. - -### Validation - -- `MultipartModCharacterizationTest`: 2 plain-JVM tests, unchanged from the Scala baseline. -- `MultipartModFunctionalTest`: 2 Forge tests, unchanged from the Scala baseline. -- Complete plain-JVM suite: 158 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 81 tests, 0 failures, 0 errors. -- The Forge run loads all nine mods, identifies `MultipartMod$.MODULE$` as the ForgeMultipart instance, completes every - startup phase, reaches server-started tests, and shuts down cleanly. -- Raw `javap` comparison confirms identical public names/descriptors for `MultipartMod`, `MultipartMod$` and - `MultipartPH`; reflection confirms identical FML annotations. - -## 2026-08-30 — MultipartEventHandler Java port - -The ForgeMultipart event handler is now an annotated Java facade/companion pair. The server proxy registers -`MultipartEventHandler$.MODULE$` explicitly on both the FML and MinecraftForge event buses, preserving the same target -identity as the Scala object expression. - -### Observable behavior - -No known runtime divergence. Chunk-data loading still runs at `HIGHEST` priority and delegates to -`MultipartSaveLoad.loadTiles`. World unload still removes server packet state, clears the client tile cache for remote -worlds, and otherwise clears the loading-world reference. Watch and unwatch events still update the two-stage chunk -watcher state, and only the END server-tick phase flushes packets and promotes queued watches. - -The highlight handler retains both `@SubscribeEvent` and `@SideOnly(CLIENT)`. Its null, block-hit and multipart-tile -guards remain short-circuiting; a successful `BlockMultipart.drawHighlight` call still cancels the event. This client -rendering path remains on the manual checklist because the automated harness is a dedicated server. - -Server ticking still wraps the configuration manager's live `java.util.List` with Scala's `JavaConverters` buffer -adapter before calling `MultipartSPH.onTickEnd`. This preserves the original `scala.collection.Seq` contract without -copying the player list or adding a new traversal. - -### ABI, annotations and source compatibility - -`MultipartEventHandler` retains the exact six public static methods. `MultipartEventHandler$` retains `MODULE$` and -the matching six public instance methods. Every method still carries `@SubscribeEvent`; only `tileEntityLoad` uses -`HIGHEST`, the other five use `NORMAL`, none receive canceled events, and only `drawBlockHighlight` carries -`@SideOnly(CLIENT)`. - -The in-repo Scala registrations now spell the handler value as `MultipartEventHandler$.MODULE$`. The registered -runtime identity is unchanged, and no frozen binary or audited source consumer names either handler class. - -Accepted divergence: the Scala signature/marker attributes disappear, and the static Java facade gains only a private -constructor. These do not change the runtime annotation data or callable public surface. The emitted class list remains -exactly `MultipartEventHandler.class` and `MultipartEventHandler$.class`. - -### Validation - -- `MultipartEventHandlerCharacterizationTest`: 2 plain-JVM tests, unchanged from the Scala baseline. -- `MultipartEventHandlerFunctionalTest`: 3 Forge tests, unchanged from the Scala baseline. -- Complete plain-JVM suite: 160 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 84 tests, 0 failures, 0 errors. -- The Forge run confirms the companion identity on both event buses and exercises load/unload, watch/unwatch and both - server-tick phases before shutting down cleanly. -- Raw `javap` comparison confirms identical public fields, method names and descriptors for both handler types; - reflection confirms identical event annotations, and both jars emit exactly the same two handler classes. - -## 2026-08-30 — MicroblockMod Java port - -The ForgeMicroblock FML entry point is now an annotated Java facade/companion pair. It deliberately remains a -`modLanguage = "scala"` mod, so FML continues to load `MicroblockMod$.MODULE$` as the mod instance. - -### Observable behavior - -No known runtime divergence. Pre-initialization still initializes the proxy, loads default content and parses the -configuration directory in order. Initialization still registers recipes before loading configured materials. -Post-initialization still builds the material ID map before finalizing the proxy, and server startup still rebuilds -that map. IMC messages still reach `ConfigContent` through Scala's live Java-list buffer adapter. - -The proxy calls use `MicroblockProxy$.MODULE$`, matching the original Scala bytecode. This is required on a dedicated -server because the generated static `init` and `postInit` forwarders inherit `@SideOnly(CLIENT)` and Forge strips them; -virtual companion dispatch safely reaches the server implementation. - -### ABI, annotations and source compatibility - -`MicroblockMod` retains the exact five public static event methods and two static `angelicaCompat` accessors. -`MicroblockMod$` retains `MODULE$`, the matching five instance event methods, two instance accessors and its private -`AngelicaCompat` field. Both classes carry the same `@Mod` values, and exactly the five lifecycle/IMC methods carry -`@Mod.EventHandler`. Public names and descriptors are identical to the reference, and both jars emit exactly -`MicroblockMod.class` and `MicroblockMod$.class`. - -The internal Scala property assignment now spells the preserved binary setter explicitly as -`MicroblockMod.angelicaCompat_$eq(...)`. Scala's assignment rewrite is unavailable when the setter is authored in -Java, but compiled callers already target that same method name and descriptor. Reads remain unchanged. - -Accepted divergence: Scala signature/marker attributes disappear, and the static Java facade gains only a private -constructor. Neither changes runtime annotation data or the callable public surface. - -### Validation - -- `MicroblockModCharacterizationTest`: 2 plain-JVM tests, unchanged from the Scala baseline. -- `MicroblockModFunctionalTest`: 1 Forge test, unchanged from the Scala baseline. -- Complete plain-JVM suite: 162 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 85 tests, 0 failures, 0 errors. -- The Forge run loads all nine mods, identifies `MicroblockMod$.MODULE$` as the ForgeMicroblock instance, completes the - lifecycle, initializes every proxy item and builds a usable material ID map before shutting down cleanly. -- Raw `javap` comparison confirms identical callable public names/descriptors; reflection confirms identical FML - annotations, and the emitted class list is unchanged. - -## 2026-08-30 — MicroblockEventHandler Java port - -The ForgeMicroblock client event handler is now a Java facade/companion pair. The server proxy explicitly registers -`MicroblockEventHandler$.MODULE$`, preserving the Scala object's identity. - -### Observable behavior - -No known runtime divergence. Post-stitch handling still reloads material icons only for texture-map type zero. -Highlight handling retains the same ordered guards for a non-null current stack, the microblock item, a non-null hit -and a block hit. It then pushes the GL matrix, translates to world coordinates, delegates to the item renderer, cancels -only when that renderer succeeds, and pops the matrix in the same sequence. - -Both handlers remain client-only. On a dedicated server Forge strips both methods from both singleton types before -the proxy registers the companion. Registration still reaches the event bus and records the same companion owner, but -there are correctly no server-side subscribers. - -### ABI, annotations and source compatibility - -`MicroblockEventHandler` retains the exact two public static methods. `MicroblockEventHandler$` retains `MODULE$` and -the matching two public instance methods. Every method still carries `@SubscribeEvent` with `NORMAL` priority and -`receiveCanceled = false`, plus `@SideOnly(CLIENT)`; neither class is itself side-only. Public names and descriptors are -identical to the reference, and both jars emit exactly `MicroblockEventHandler.class` and -`MicroblockEventHandler$.class`. - -The in-repo Scala registration now spells the object value as `MicroblockEventHandler$.MODULE$`. Compiled external -callers and event-bus identity are unchanged, and no frozen binary or audited source consumer names either type. - -Accepted divergence: Scala signature/marker attributes disappear, and the static Java facade gains only a private -constructor. Neither changes runtime annotations or the callable public surface. - -### Validation - -- `MicroblockEventHandlerCharacterizationTest`: 2 plain-JVM tests, unchanged from the Scala baseline. -- `MicroblockEventHandlerFunctionalTest`: 1 Forge test, unchanged from the Scala baseline. -- Complete plain-JVM suite: 164 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 86 tests, 0 failures, 0 errors. -- Raw `javap` comparison confirms identical callable public members, reflection confirms identical annotations, and - the emitted class list is unchanged. -- Texture stitching and placement-highlight rendering require a client and remain on the manual checklist. - -## 2026-08-31 — ForgeMicroblock packet-handler Java port - -The shared packet-handler base and both client/server facade-companion pairs are now Java. Scala proxy code registers -`MicroblockCPH$.MODULE$` and `MicroblockSPH$.MODULE$` explicitly, preserving the singleton objects CodeChickenLib -receives. - -### Observable behavior - -No known runtime divergence. The registry channel remains `ForgeMicroblock`. Client packet type 1 still skips the -material-map read in an integrated single-player game, avoiding mutation of the registry shared with the server. A -multiplayer client still reads the complete map and disconnects with translation key `microblock.missing` plus the -ordered, comma-separated missing names. Unknown client packet types still throw `scala.MatchError`. - -The server packet callback remains a no-op. The handshake still sends packet type 1 on `ForgeMicroblock`, followed by -the material count and every registered material name in ID order. - -### ABI and source compatibility - -`MicroblockPH` retains its public constructor and `registryChannel()` accessor. `MicroblockCPH` and `MicroblockSPH` -retain their exact static forwarders. Their companion classes retain `MODULE$`, extend `MicroblockPH`, implement the -same CodeChickenLib packet interfaces in the same order, and expose the same instance methods. No audited shipping -consumer references these types. - -Both jars emit exactly `MicroblockPH.class`, `MicroblockCPH.class`, `MicroblockCPH$.class`, `MicroblockSPH.class` and -`MicroblockSPH$.class`. Accepted classfile-only differences are the removed Scala signature/marker attributes, private -constructors on the static facades, and companion class initializers without Scala's `ACC_PUBLIC` flag. A class -initializer is invoked only by the JVM and cannot be named by caller bytecode. - -Recompiled in-repo Scala now passes `MicroblockCPH$.MODULE$` and `MicroblockSPH$.MODULE$` where the object values were -previously implicit, and calls the Java no-arg channel accessors with parentheses. Compiled external callers still -target the same classes, fields, method names and descriptors. - -### Validation - -- `MicroblockPacketHandlerCharacterizationTest` and `MicroblockPacketHandlerBehaviorTest`: 7 plain-JVM tests, - unchanged from the Scala baseline. -- `MicroblockPacketHandlerFunctionalTest`: 1 Forge handshake test, unchanged from the Scala baseline and compiled into - the functional-test jar. -- Complete plain-JVM suite: 171 tests, 0 failures, 0 errors. -- Raw `javap` comparison confirms identical callable public names/descriptors and interface order for all five types; - the emitted class list is unchanged. -- The deferred Java 8 Forge run now passes all 87 tests after the local EULA was accepted. - -## 2026-08-31 — MultipartSaveLoad Java port - -The chunk-load save/restore singleton is now a Java static facade plus a Java companion singleton. ProjectRed reads -`MultipartSaveLoad$.MODULE$` and calls `loadingWorld()`, so both forms remain rather than collapsing the object into a -single utility class. - -### Observable behavior - -No known runtime divergence. `hookLoader` still reflects Forge's runtime TileEntity name map and registers -`savedMultipart`; `registerTileClass` still updates the reverse map cached during singleton construction. Chunk loading -still records the world, reconstructs saved multipart dummies, uses the first matching converter, removes empty -conversions and leaves unclaimed tiles untouched. Replacements retain the old world, validate and replace the map -entry. - -### ABI and source compatibility - -`MultipartSaveLoad` retains its seven public static methods. `MultipartSaveLoad$` retains `MODULE$`, the seven matching -instance methods, and the exact private `converters`, `loadingWorld` and `classToNameMap` fields. The dummy remains the -public, non-final static member `MultipartSaveLoad.TileNBTContainer`, emitting the literal binary name -`MultipartSaveLoad$TileNBTContainer`. Placing it inside the companion would have incorrectly emitted a double dollar -and was rejected by the characterization test. - -All callable public names and descriptors match the Scala reference. The reference-only -`MultipartSaveLoad$$anonfun$1` closure class disappeared; it was implementation machinery and has no entry in -the downstream ABI inventory. Accepted classfile-only differences are removed Scala attributes, a private constructor -on the facade, extra private Java helpers, and the companion class initializer without Scala's `ACC_PUBLIC` flag. - -The frozen Scala consumer compiled against the reference continues to link and mutate the companion state. As with -other Java-authored Scala-style setters in this migration, newly recompiled Scala source should call -`loadingWorld_$eq` explicitly if property-assignment rewriting does not recognize the Java method. - -### Validation - -- `MultipartSaveLoadCharacterizationTest`: 3 plain-JVM tests, unchanged from the Scala baseline. -- `MultipartSaveLoadFunctionalTest`: 4 Forge tests, unchanged from the Scala baseline, including the frozen Scala - consumer. -- Complete plain-JVM suite: 174 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 91 tests, 0 failures, 0 errors. -- Raw `javap` comparison confirms identical callable public names/descriptors for all three retained types. The sole - class-list removal is the unreferenced compiler closure above. - -## 2026-08-31 — MissingMicroMaterial Java port - -The unresolved-material placeholder is now a Java static facade plus a Java companion singleton implementing -`IMicroMaterial`. `DefaultContent` and `ItemMicroPart` name `MissingMicroMaterial$.MODULE$` explicitly where Scala -previously supplied the object value implicitly. - -### Observable behavior - -No known runtime divergence. The registered key remains `forgemicroblock:missing`; the material remains opaque, -non-luminous, strength 1, cutter strength 0, stone-sounding, explosion resistance 6, and supplies a one-item stone -stack. It still inherits render-pass-zero and solid behavior from the Java `IMicroMaterial` defaults. - -On the client, icon loading still asks the proxy renderer for its safe null icon. Breaking returns that icon and face -rendering still applies its `IconTransformation`, lighting and render pipeline in the same order. On a dedicated -server Forge strips the three client methods from both singleton types and the client-only icon field from the -companion before `DefaultContent` registers it. - -### ABI and source compatibility - -`MissingMicroMaterial` retains its exact 12 public static methods. `MissingMicroMaterial$` retains `MODULE$`, -implements `IMicroMaterial`, and retains the matching 12 public instance methods. Both types keep `@SideOnly(CLIENT)` -on `loadIcons`, `getBreakingIcon` and `renderMicroFace`; neither class is itself side-only. Both jars emit exactly -`MissingMicroMaterial.class` and `MissingMicroMaterial$.class`, and no audited shipping consumer references either -type. - -Accepted classfile-only differences are removed Scala signature/marker attributes, a private constructor on the -facade, removal of the companion's private Scala `icon` getter/setter, and a class initializer without Scala's -`ACC_PUBLIC` flag. None is a callable public member. Recompiled Scala source that passes the singleton as a value must -use `MissingMicroMaterial$.MODULE$`; static calls retain their original names and descriptors. - -### Validation - -- `MissingMicroMaterialCharacterizationTest`: 3 plain-JVM tests, unchanged from the Scala baseline. -- `MissingMicroMaterialFunctionalTest`: 1 Forge test, unchanged from the Scala baseline. -- Complete plain-JVM suite: 177 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 92 tests, 0 failures, 0 errors. -- Raw `javap` comparison confirms identical callable public names/descriptors and the emitted class list is unchanged. -- Missing-texture icon loading and face rendering require a client and remain on the manual checklist. - -## 2026-08-31 — DefaultContent Java port - -The built-in microblock registration singleton is now a Java static facade plus Java companion. `MicroblockMod$` -continues to call `DefaultContent$.MODULE$.load()` during pre-init. - -### Observable behavior - -No known runtime divergence. The same face, hollow, corner and edge classes retain IDs 0 through 3, and the post -class remains registered without a common-class ID. Their five multipart type names and exact singleton factories are -unchanged. - -The material registry still receives the same 103 entries, sorts them by name during post-init, and maps every legacy -unlocalized key to the same registry key. Grass still uses `GrassMicroMaterial`, mycelium still uses -`TopMicroMaterial`, and the missing key still maps to `MissingMicroMaterial$.MODULE$`. The Java implementation calls -the existing `BlockMicroMaterial$` overloads with Scala inclusive ranges, preserving the reference's meta coverage. -In particular, the three-argument overload used for `log2` and `leaves2` still registers only metadata zero despite -receiving ranges through one; this port deliberately does not combine a behavior fix with the language conversion. - -### ABI and source compatibility - -`DefaultContent` retains its sole public static `load()V`; `DefaultContent$` retains `MODULE$` and the matching public -instance method. Both jars emit exactly `DefaultContent.class` and `DefaultContent$.class`. No audited shipping -consumer references either type. - -Accepted classfile-only differences are removed Scala signature/marker attributes, a private constructor on the -facade, and a class initializer without Scala's `ACC_PUBLIC` flag. A class initializer is JVM-only and is not a -callable member. - -### Validation - -- `DefaultContentCharacterizationTest`: 1 plain-JVM test, unchanged from the Scala baseline. -- `DefaultContentFunctionalTest`: 2 Forge tests, unchanged from the Scala baseline. -- Complete plain-JVM suite: 178 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 94 tests, 0 failures, 0 errors. -- Raw `javap` comparison confirms identical callable public names/descriptors and the emitted class list is unchanged. - -## 2026-08-31 — Grass and top micro-material Java port - -The grass-specific material and the top-texture material are now separate Java classes. The Scala-generated -default-argument companion for `TopMicroMaterial` is retained as a small Java singleton because compiled Scala callers -can address it even though no source object existed. - -### Observable behavior - -No known runtime divergence. Grass still renders its ordinary texture without tint on the bottom and sides, tints the -top, and adds the biome-coloured grass overlay only to side faces. The overlay UV still shifts by -`bounds.max.y - 1`, and non-inventory passes still compute light coordinates before either layer. Top materials still -use their ordinary icons on the two horizontal faces and the same height-adjusted UV on all four sides. Both coloured -paths retain lighting and Angelica's block/meta shader override calls. - -The pipeline characterization observes the actual UV and colour operations with an empty vertex range, so it freezes -branch routing without requiring a GL context. Actual grass/mycelium icons, biome tint and rendered pixels still need -the client checklist. - -### ABI and source compatibility - -`GrassMicroMaterial` retains its public no-argument constructor, four public methods, private `sideIconT` field and -non-final `BlockMicroMaterial` subclass shape. Its `sideIconT()` getter remains directly compatible with the audited -UtilitiesInExcess renderer. `TopMicroMaterial` retains its `(Block, int)` constructor, static -`$lessinit$greater$default$2()` method, render override and non-final superclass shape. `TopMicroMaterial$` retains its -public final singleton class, `MODULE$` field and instance default getter. - -Both jars emit exactly `GrassMicroMaterial.class`, `TopMicroMaterial.class` and `TopMicroMaterial$.class`. Accepted -classfile-only differences are removed Scala signature/marker attributes and the companion class initializer without -Scala's `ACC_PUBLIC` flag. A class initializer is JVM-only and is not callable consumer API. The same fields and -methods remain common-side and therefore survive dedicated-server stripping, matching the reference. - -### Validation - -- `GrassMicroMaterialCharacterizationTest`: 5 plain-JVM tests, unchanged from the Scala baseline. -- `GrassMicroMaterialFunctionalTest`: 1 Forge test, unchanged from the Scala baseline. -- Complete plain-JVM suite: 183 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 95 tests, 0 failures, 0 errors. -- A clean build followed by raw `javap` comparison confirms identical callable public names/descriptors and emitted - classes. The clean step is material: Zinc otherwise retained and packaged the deleted Scala class files. - -## 2026-09-01 — MultipartProxy Java port - -The multipart server/client proxy hierarchy is now Java, including the static facade and load-bearing companion -singleton. ProjectRed's direct `MultipartProxy$.MODULE$` block access and BuildCraftCompat/Iguana Tweaks' static -`MultipartProxy.block()`/`config()` calls therefore keep the same owners and descriptors. - -### Observable behavior - -No known runtime divergence. Pre-init still records the logger, opens `multipart.cfg`, registers the same eight -generated-tile traits in the same order, registers and resolves the multipart block, then hooks saved-tile loading. -Post-init still registers the same event-handler singleton on both buses, assigns both server packet handlers, starts -the tick scheduler and chunk-load hook, and loads compatibility hooks in the same order. - -Client post-init still follows common post-init with the multipart block renderer, both client packet channels, and -the control-key event/key-binding registrations. Generated tile classes are still registered for save/load before a -client renderer is bound. The two chunk-index conversions retain their exact bit packing, including signed input. - -On a dedicated server Forge strips `postInit` and `onTileClassBuilt` from `MultipartProxy_clientImpl` and strips their -static facade forwarders. `MultipartProxy$.MODULE$` then resolves both calls to `MultipartProxy_serverImpl`, exactly as -the Scala hierarchy did. The common `MultipartGenerator` callback now spells that companion call explicitly; calling -the stripped facade would fail after the Java port even though its raw dev-jar ABI is correct. - -### ABI, annotations and source compatibility - -All four emitted types remain: `MultipartProxy_serverImpl`, `MultipartProxy_clientImpl`, `MultipartProxy`, and -`MultipartProxy$`. The inheritance and final flags are unchanged. The server implementation retains its exact ten -public methods and three private fields; the client implementation declares only its two overrides; the facade keeps -all twelve public static forwarders; and the companion declares only `MODULE$` plus both instance index conversions. -Every callable public descriptor matches the reference. - -Only the two client overrides and their facade forwarders retain `@SideOnly(CLIENT)`; no class is side-only. The -facade and companion still share mutable block/config/logger state while separately constructed server proxies remain -independent. - -Accepted classfile-only differences are removed Scala signature/marker attributes, a private constructor on the -static facade, and a companion class initializer without Scala's `ACC_PUBLIC` flag. Both jars emit exactly the same -four proxy classes. An unused Scala wildcard import was removed from the packet-handler source. - -### Validation - -- `MultipartProxyCharacterizationTest`: 4 plain-JVM tests, unchanged from the Scala baseline. -- `MultipartProxyFunctionalTest`: 1 Forge test, unchanged from the Scala baseline. -- Complete plain-JVM suite: 187 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 96 tests, 0 failures, 0 errors. -- A clean build followed by raw `javap` comparison confirms identical emitted classes, hierarchy, fields, callable - public names/descriptors and client-only method annotations. -- Client renderer, packet, key-binding and generated-tile renderer registration require a client and remain on the - manual checklist. - -## 2026-09-01 — MicroblockProxy Java port - -The ForgeMicroblock server/client proxy hierarchy is now Java, including its static facade and load-bearing companion -singleton. Iguana Tweaks' direct `MicroblockProxy$.MODULE$` item/saw reads and static `MicroblockProxy.sawDiamond()` / -`createSaw(...)` calls retain their original owners and descriptors. - -### Observable behavior - -No known runtime divergence. Pre-init still registers the microblock item, stone/iron/diamond saws and stone rod in -the same sequence, preserves saw-list order, registers `rodStone` and the event-handler singleton, and reads the same -`useSawIcons` configuration tag. Each saw still uses the named braced config tag, strength, unlocalized name and -texture name. - -Init still adds `MicroRecipe$.MODULE$` and, outside Dreamcraft, the four-stone-rod recipe plus all three ore-dictionary -saw recipes. Forge subsequently sorts the global recipe list, so only recipe identity/content and the proxy's own saw -list have meaningful stable order. Post-init still calculates maximum cutting strength, assigns the registry handshake -handler and conditionally registers Postea transformers. - -Client init still registers the same renderer for all three saws. Client post-init still loads material icons, -registers the microblock-item renderer and packet handler, and conditionally installs `AngelicaCompat`. The -`RenderBlocks` instance remains lazy, synchronized and published through the same volatile bitmap. - -### ABI, annotations and source compatibility - -The four callable types remain `MicroblockProxy_serverImpl`, `MicroblockProxy_clientImpl`, `MicroblockProxy`, and -`MicroblockProxy$`, with unchanged inheritance and final flags. The server implementation retains its exact 21 public -methods and eight private fields. Its source-protected `saws` property remains a Scala `MutableList` with public -JVM accessors, preserving compiled callers. The facade retains its exact 20 static methods, deliberately excluding the -protected saw-list accessors, and the companion still declares only `MODULE$`. - -The client implementation retains its private `renderBlocks` field, volatile `bitmap$0`, private -`renderBlocks$lzycompute()` helper and three public methods. As in the Scala reference, only the renderer field is -`@SideOnly(CLIENT)`; the getter and lazy helper are not. Only `init` and `postInit` are client-only on the client -implementation and facade. Consequently dedicated-server reflection across all client methods still encounters the -stripped `RenderBlocks` type, while direct companion lifecycle dispatch resolves to the inherited server methods. - -Accepted classfile-only differences are removed Scala signature/marker attributes, a private facade constructor, one -private Java recipe-list helper, and removal of the unreferenced -`MicroblockProxy_clientImpl$$anonfun$init$1` iteration closure. The downstream inventory contains no reference to that -private implementation class. - -### Validation - -- `MicroblockProxyCharacterizationTest`: 4 plain-JVM tests, unchanged from the Scala baseline. -- `MicroblockProxyFunctionalTest`: 2 Forge tests, unchanged from the Scala baseline. -- Complete plain-JVM suite: 191 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 98 tests, 0 failures, 0 errors. -- A clean build and raw `javap` comparison confirm identical retained class hierarchy, fields, callable public - names/descriptors and side annotations. The sole class-list removal is the private closure above. -- Item-renderer registration, material icon loading, client packet registration and Angelica integration require a - client and remain on the manual checklist. - -## 2026-09-01 — ForgeMultipart packet-handler Java port - -The shared packet-handler base, both client/server facade-companion pairs and the nested byte stream are now Java. -The multipart proxy continues to register `MultipartCPH$.MODULE$` and `MultipartSPH$.MODULE$`, preserving the exact -singleton objects CodeChickenLib receives. - -### Observable behavior - -No known runtime divergence. The ordinary channel remains `MultipartMod$.MODULE$` and the registry channel remains -`ForgeMultipart`. Registry packet type 1 still replaces the client ID map and disconnects with translation key -`multipart.missing` plus every missing name in server order. Client desynchronization exceptions beginning `DC: ` -still become a plain-text disconnect with that marker removed; other runtime exceptions still escape unchanged. - -Chunk-description packet type 2 still reads chunk coordinates, an unsigned tile count, signed local x/z bytes and -each tile description in sequence. Update packet type 3 still reads absolute coordinates until `Integer.MAX_VALUE` -and part updates until unsigned byte 255. The server callback still maps packet type 1 to the sender's control-key -state, and unknown packet types on either side still throw `scala.MatchError`. - -Server handshakes still send the complete part-ID map on packet type 1. Tile streams remain cached by world and -position, begin with the absolute coordinate, and reject client worlds before publishing state. World unload still -removes only server state. End-of-tick processing still flushes scheduled packets first, sends accumulated updates -only to players watching each chunk, clears every per-world update map, sends descriptions for newly watched chunks, -promotes those watches and finally clears the pending-watch map. Description packets retain their exact logical -framing and deferred CodeChickenLib compression. - -The direct Java loops avoid the closure objects previously created by the Scala comprehensions. No focused profile -claim is made because the current functional profiling fixture does not generate sustained watched-chunk multipart -traffic; a representative full-pack capture remains the authority. - -### ABI and source compatibility - -`MultipartPH` retains its public constructor, `MultipartMod$`-typed `channel` field/accessor and registry-channel -accessor. `MultipartCPH` and `MultipartSPH` retain every static forwarder. Their companions retain `MODULE$`, extend -`MultipartPH`, implement the same CodeChickenLib interfaces in the same order, and expose the same instance methods. -`MultipartSPH$` also retains the exact private prefixed `updateMap`, `chunkWatchers` and `newWatchers` fields and their -public mangled accessors with Scala `Map`/`HashMap` descriptors. - -`MultipartSPH.MCByteStream` remains a public, non-final static member of the facade, so its binary name is still -`MultipartSPH$MCByteStream`. It retains the `(ByteArrayOutputStream)` constructor, private final `bout` field, -`MCDataOutputWrapper` superclass and `getBytes()[B`. No audited shipping consumer references any handler type. - -Both jars retain these six runtime classes. Accepted classfile-only differences are removed Scala signature/marker -attributes, private constructors on the static facades, companion class initializers without Scala's `ACC_PUBLIC` -flag, and removal of the anonymous `MultiMap` plus thirteen `$$anonfun$` classes. The fourteen removed classes are -private compiler artifacts with no downstream reference. - -### Validation - -- `MultipartPacketHandlerCharacterizationTest` and `MultipartPacketHandlerBehaviorTest`: 11 plain-JVM tests, - unchanged from the Scala baseline. -- Existing `MultipartEventHandlerFunctionalTest` and `MultipartHelperFunctionalTest` cases retain unload cleanup, - watcher/tick ordering and exact logical chunk-description framing. -- Clean complete plain-JVM suite: 202 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 98 tests, 0 failures, 0 errors. -- Raw `javap` comparison confirms identical callable public names/descriptors for all six retained classes. The exact - class-list diff contains only the fourteen compiler artifacts described above. -- Real client chunk-description application, update dispatch and rendering remain on the manual checklist. - -## 2026-09-01 — ItemMicroPart Java port - -The microblock item, its static facade/companion pair and its renderer facade/companion pair are now Java. -ProjectRed's direct `ItemMicroPart$.MODULE$` calls and Extra Utilities' static material-ID lookup retain their original -owners and descriptors. - -### Observable behavior - -No known runtime divergence. The item still packs the microblock class above the low size byte, stores the material -name under NBT key `mat`, maps absent tags to null/missing ID and unknown names to `MissingMicroMaterial$.MODULE$`. -Both creation overloads still use the registered proxy item. Display names, the `Unnamed` invalid fallback, creative -class/size/material ordering, block retrace, placement validation, survival consumption and material sound are -unchanged. - -The renderer still accepts every render type/helper, applies the same entity/inventory transforms, builds the same -client part and draws it with normals and the lightmap. `MicroblockRender.renderItem` centralizes the transformed -`MicroblockClient` cast, shape assignment, centering and render call. Its later Java port added a clean-build bytecode -gate proving those client calls remain `invokeinterface` after compilation. - -### ABI and source compatibility - -The retained runtime types are exactly `ItemMicroPart`, `ItemMicroPart$`, `ItemMicroPartRenderer`, and -`ItemMicroPartRenderer$`. Every callable public name and descriptor matches the reference, including both creation -overloads, `MODULE$`, the renderer's Scala `Seq` overload and its `Object[]` interface method. The Java -renderer's array method is ordinary rather than Scala-synthetic, which does not affect linkage or dispatch. - -Accepted classfile-only differences are removed Scala signature/marker attributes, private constructors on static -facades, a private Java renderer helper, and removal of the three unreferenced `getSubItems` closure classes. The -downstream inventory contains no reference to those compiler artifacts. - -### Validation - -- `ItemMicroPartCharacterizationTest`: 5 plain-JVM tests, unchanged from the Scala baseline. -- `ItemMicroPartBinaryCompatibilityTest`: 1 frozen Scala-consumer test, unchanged from the Scala baseline. -- Existing `MicroRecipeFunctionalTest` and `MicroblockProxyFunctionalTest` retain initialized item/material creation, - registration and recipe integration. -- Clean complete plain-JVM suite: 208 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 98 tests, 0 failures, 0 errors. -- A clean jar contains only the four retained types, and raw `javap` comparison confirms identical callable public - names/descriptors. -- Creative listing, localized names, successful placement/consumption/sound and real client rendering remain on the - manual checklist. - -## 2026-09-01 — MicroblockPlacement Java port - -The placement decision engine, its executable result hierarchy, property base and companion singleton are now six -Java types. The item and highlight renderer continue to call `MicroblockPlacement$.MODULE$`, preserving the singleton -entry point exposed by the Scala implementation. - -### Observable behavior - -No known runtime divergence. Custom placement still wins before a rejected grid slot. Expansion still requires an -internal, non-converted tile hit without sneaking or the opposite modifier, then checks part type, material, combined -size, entity collision and replacement compatibility. Successful expansion mutates the original part's shape in -place, notifies its tile and sends the shape update. Internal placement retains the same shallow-hit and control-key -slot selection; external placement retains the same side offset. Addition and expansion each consume one item when -their caller requests consumption. - -The Java implementation uses direct conditionals and standard null-safe equality. No focused performance claim is -made because placement is an interactive path rather than a sustained server loop. - -### ABI and source compatibility - -The retained runtime types are exactly `ExecutablePlacement`, `AdditionPlacement`, `ExpandingPlacement`, -`PlacementProperties`, `MicroblockPlacement`, and `MicroblockPlacement$`. Their hierarchy, constructors, stored-field -names/types/modifiers, `MODULE$`, and every callable public name and descriptor match the Scala reference. No anonymous -or closure classes existed in the reference unit, so the emitted class list is unchanged. - -The remaining Scala highlight renderer now spells the companion call as `MicroblockPlacement$.MODULE$.apply(...)`; -Scala's object-application sugar does not recognize a Java-authored companion. Accepted classfile-only differences are -removed Scala signature/marker attributes, a private companion constructor and the companion class initializer without -Scala's `ACC_PUBLIC` flag. - -### Validation - -- `MicroblockPlacementCharacterizationTest`: 3 plain-JVM tests, unchanged from the Scala baseline. -- `MicroblockPlacementFunctionalTest`: 4 Forge tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 211 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 102 tests, 0 failures, 0 errors. -- Clean reference/port jars contain the same six runtime classes, and raw `javap` comparison confirms identical - callable public names/descriptors. -- Full item-use sound plus client highlight/control-key feedback remain on the manual checklist. - -## 2026-09-01 — PlacementGrids Java port - -The placement-grid trait, its Scala binary helper, configurable face-edge grid, and the face/corner/edge facade and -companion pairs are now nine Java types. ProjectBlue's direct static calls to `FacePlacementGrid.getHitSlot` and -`FacePlacementGrid.render` retain their original owners and descriptors. - -### Observable behavior - -No known runtime divergence. Face and hollow-style grids still use a strict center-size comparison, select the hit -side's opposite slot in the center, choose the larger projected axis outside it and resolve equal projections through -the second axis. Corner grids still treat zero as positive and encode the hit normal plus both projected signs. Edge -grids retain the strict quarter-block center and diagonal tests, second-axis tie behavior and `PartMap.edgeBetween` -mapping. These rules are frozen for all six hit sides, including values immediately below and exactly on boundaries. - -The OpenGL guide path retains the same face transform, line state, vertex sequence and matrix pop. It is interactive -client rendering rather than a sustained loop, so no focused performance claim is made. - -### ABI and source compatibility - -The retained runtime types are exactly `PlacementGrid`, `PlacementGrid$class`, `FaceEdgeGrid`, `FacePlacementGrid`, -`FacePlacementGrid$`, `CornerPlacementGrid`, `CornerPlacementGrid$`, `EdgePlacementGrid`, and `EdgePlacementGrid$`. -Every callable public name and descriptor matches the Scala reference. `FaceEdgeGrid` retains its private final -`double size`, public constructor and four declared methods; all facades and companions retain their exact public -surfaces and `MODULE$` fields. - -`PlacementGrid`'s three concrete trait methods are Java defaults, while `getHitSlot` remains abstract. The deprecated -`PlacementGrid$class` bridge retains the original four static methods for already-compiled Scala forwarders. The -three in-repo Scala object-value references now spell the corresponding `MODULE$` explicitly. - -Accepted classfile-only differences are removed Scala signature/marker attributes, the default-versus-abstract flags -on the three reusable interface methods, four private Java constructors on the helper/static facades, and companion -class initializers without Scala's `ACC_PUBLIC` flag. No runtime class was added or removed. - -### Validation - -- `PlacementGridsCharacterizationTest`: 5 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 216 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 102 tests, 0 failures, 0 errors. -- Clean reference/port jars contain the same nine runtime classes, and raw `javap` comparison confirms identical - callable public names/descriptors. -- Face/corner/edge/hollow guide-line rendering remains on the manual checklist. - -## 2026-09-01 — BlockMicroMaterial Java port - -The block-backed material, its registry companion, the render-helper facade/companion and per-thread state are now -five Java types. - -### Observable behavior - -No known runtime divergence. Material keys and legacy names, metadata suffixes, all six registration overloads, -registry remaps, block/item/name/strength/light/harvest/sound/resistance delegation, colour selection and face-render -pipeline order are unchanged. The historical `createAndRegister(Block, Seq, oldName)` behavior still ignores the -sequence and registers only metadata 0; this port does not repair it. - -Icon loading still reacquires the block from its registry name in case another mod replaced the instance, resolves all -six icons through `RenderBlocks.getIconSafe`, and falls back to its null icon after any exception. The render helper -still stores pass and pipeline builder per thread, applies light only outside inventory rendering, sets the Angelica -block/meta shader override before drawing and resets it afterwards. - -### ABI and reflection compatibility - -The retained runtime types are exactly `ThreadState`, `MaterialRenderHelper`, `MaterialRenderHelper$`, -`BlockMicroMaterial`, and `BlockMicroMaterial$`. Every callable public name and descriptor matches the Scala -reference, including both static facades, both `MODULE$` fields, the Scala `Seq` overloads, default-argument methods, -the public `(Block, int)` constructor and the mangled icon helper. - -`BlockMicroMaterial` remains non-final and keeps exactly four instance fields. In particular, GuideNH's late mixin -targets remain private final fields named `block: Block` and `meta: int`; the private final `blockKey: String` and -private mutable `icont: MultiIconTransformation` retain their names and types too. `@SideOnly(CLIENT)` remains only on -the icon field, `loadIcons` and `getBreakingIcon`, matching the dedicated-server stripped surface. - -A frozen Scala 2.11.5 consumer calls `BlockMicroMaterial$.MODULE$` key/default methods and -`MaterialRenderHelper$.MODULE$` pass accessors, proving both load-bearing companion links after the port. Accepted -classfile-only differences are removed Scala signature/marker attributes, private Java constructors on the static -facade/companions, and companion class initializers without Scala's `ACC_PUBLIC` flag. - -### Compiler artifacts - -Accepted divergence: `BlockMicroMaterial$$anonfun$createAndRegister$1`, -`BlockMicroMaterial$$anonfun$loadIcons$1`, and `MaterialRenderHelper$$anon$1` disappear. Direct Java iteration and -`ThreadLocal.withInitial` need none of these compiler-generated implementation classes, and the downstream inventory -contains no reference to them. - -### Validation - -- `BlockMicroMaterialCharacterizationTest`: 5 plain-JVM tests, unchanged from the Scala baseline. -- `BlockMicroMaterialBinaryCompatibilityTest`: 1 frozen Scala-consumer test, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 222 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 103 tests, 0 failures, 0 errors. -- Clean reference/port jars retain the same five supported types; the three compiler artifacts above disappear, and - raw `javap` comparison confirms identical callable public names/descriptors. -- Client icon reload, material face rendering and Angelica shader overrides remain on the manual checklist. - -## 2026-09-01 — ConfigContent Java port - -The custom micro-material configuration loader is now a Java static facade and `MODULE$` companion. - -### Observable behavior - -No known runtime divergence. A missing `microblocks.cfg` still produces the same five-line default file. Existing -files still accept quoted unlocalized or registry names, add the `minecraft:` namespace only when neither `.` nor `:` -is present, default metadata to zero, expand comma lists and inclusive ascending ranges, leave descending ranges -empty, and replace earlier declarations for the same name. Invalid lines still log twice and do not stop later lines. - -Loading still consumes both the unlocalized-name and registry-name aliases before registration, registers their -metadata in that order, catches registration failures per metadata, and retains unmatched entries so each load can -warn about them. IMC still ignores other keys, requires the exact final `ItemStack` runtime type, checks block -registration before the `[0, 16)` metadata bound, and catches only duplicate-registration failures. - -The public `generateDefault` and `loadLines` methods retain the Scala source surface with no declared checked -exceptions while rethrowing the original `IOException` instance. `parse` alone catches those IO failures and logs -them, matching the reference rather than wrapping them. - -### ABI and reflection compatibility - -The retained runtime types are exactly `ConfigContent` and `ConfigContent$`. Both keep the same six callable public -methods and descriptors, and the companion keeps `MODULE$` plus the private final -`codechicken$microblock$ConfigContent$$nameMap: scala.collection.mutable.Map` field and its public mangled accessor. -The downstream inventory contains no ConfigContent member or reflective references, so no frozen consumer fixture is -needed. Accepted classfile-only differences are removed Scala signature/marker attributes, private Java constructors, -and the companion class initializer without Scala's `ACC_PUBLIC` flag. - -### Compiler artifacts - -Accepted divergence: `ConfigContent$$anonfun$handleIMC$1`, `ConfigContent$$anonfun$handleIMC$2`, -`ConfigContent$$anonfun$load$1`, `ConfigContent$$anonfun$load$1$$anonfun$1`, -`ConfigContent$$anonfun$load$1$$anonfun$apply$1`, `ConfigContent$$anonfun$load$2`, and -`ConfigContent$$anonfun$loadLine$1` disappear. Direct Java loops need none of these private implementation classes, -and the downstream inventory contains no references to them. - -### Validation - -- `ConfigContentCharacterizationTest`: 6 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 228 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 103 tests, 0 failures, 0 errors. -- Clean reference/port jars retain the same two supported types; the seven compiler artifacts above disappear, and - raw `javap` comparison confirms identical callable public names/descriptors. -- File parsing, registration and IMC behavior are automated; this port adds no new client-only manual check. - -## 2026-09-01 — AngelicaCompat Java port - -The optional Angelica shader-material adapter is now Java. - -### Observable behavior - -No known runtime divergence. Both methods still act only when `Tessellator.instance` is a -`CapturingTessellator`, call the matching Iris shader-material hook, and catch only `ClassCastException`. The public -methods deliberately continue to return `Object`: the normal path returns `BoxedUnit.UNIT`, while the caught fallback -returns `Unit$.MODULE$`, exactly as the Scala bytecode did. - -### ABI and reflection compatibility - -`AngelicaCompat` remains a public, non-final class with one public no-argument constructor, no fields or interfaces, -and exactly these two callable methods: - -- `setShaderMaterialOverride(Block, int): Object` -- `resetShaderMaterialOverride(): Object` - -The downstream inventory contains no reference to this class, so no frozen consumer fixture is needed. Accepted -classfile-only differences are the removed Scala signature/marker attributes and the Java source-file marker. - -### Compiler artifacts - -No runtime class is added or removed; both clean jars contain only `AngelicaCompat.class` for this source unit. - -### Validation - -- `AngelicaCompatCharacterizationTest`: 2 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 230 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 103 tests, 0 failures, 0 errors. -- Raw `javap` comparison confirms identical class modifiers, constructor and callable public names/descriptors. -- Live shader-material selection and reset with Angelica remain on the manual checklist. - -## 2026-09-01 — ItemSaw and renderer Java port - -The config-backed saw item, renderer facade and registered renderer singleton are now Java. - -### Observable behavior - -No known runtime divergence. A missing durability value still defaults to `1 << (harvestLevel + 8)`; a positive value -sets maximum damage, while zero or a negative value leaves the item non-damageable. Saws remain non-repairable, -single-stack tools on the tools tab. Damageable saws leave a new one-item container with damage incremented by one; -non-damageable saws return the original stack, and neither leaves the crafting grid. - -The renderer still chooses its model when saw icons are disabled or the item icon is missing, always accepts Forge -render helpers, handles exactly inventory, entity, equipped-first-person and equipped transforms, and ignores other -render types. It loads the same OBJ groups and texture, uses the same render-state/GL order, and selects the blade UV -row from cutting strength. - -### ABI and reflection compatibility - -The retained runtime types are exactly `ItemSaw`, `ItemSawRenderer`, and `ItemSawRenderer$`. Every callable public -name and descriptor matches the Scala reference, including the static facade's Scala `Seq` overload, the -companion's `Object[]` interface bridge, all four model getters and `MODULE$`. - -`ItemSaw` remains non-final, extends `Item`, implements `Saw`, and keeps the private final `harvestLevel: int` field -and public accessor used by Iguana Tweaks. The companion retains its private final `models`, `handle`, `holder`, and -`blade` fields. The downstream inventory has no direct ItemSaw member reference, so no frozen binary fixture is -needed; the known reflective source consumer is covered directly. - -Accepted classfile-only differences are removed Scala signature/marker attributes, a private constructor on the -static facade, the companion class initializer without Scala's `ACC_PUBLIC` flag, and an ordinary Java implementation -of the `Object[]` renderer bridge instead of Scala's synthetic bridge. - -### Compiler artifacts - -No runtime class is added or removed; both clean jars contain the same three ItemSaw/renderer classes. - -### Validation - -- `ItemSawCharacterizationTest`: 4 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 234 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 103 tests, 0 failures, 0 errors, including registered saws and recipes. -- Clean reference/port jars retain the same three types, and raw `javap` comparison confirms identical callable - public names/descriptors and retained field shapes. -- Client model loading, transformations, texture/UV output and GL culling remain on the manual checklist. - -## 2026-09-01 — MicroblockRender Java port - -The static renderer facade and its companion singleton are now Java. - -### Observable behavior - -No known runtime divergence. Item rendering still applies the requested shape before centering the generated client -part on its bounds and rendering pass `-1`. Highlight rendering still draws the placement grid first, asks the -placement engine with the inverse creative flag, returns before touching OpenGL when no placement exists, and uses the -same matrix, blend, depth-mask, atlas, alpha, normals and draw order for a valid placement. - -Cuboid rendering still reuses one `BlockFace` per thread, installs it as the current render-state model, visits sides -0 through 5, and skips every side whose mask bit is set. The Java loop removes the Scala `Range`, filter and two -per-call closure objects from this render-hot path without adding a new cache or abstraction. - -### ABI and reflection compatibility - -The retained runtime types are exactly `MicroblockRender` and `MicroblockRender$`. Both keep the same four callable -public names and descriptors; the facade methods remain static, the companion keeps `MODULE$`, and its `face` field -remains private final with the `ThreadLocal` descriptor. - -The generated `MicroblockClient` boundary is explicitly frozen. A clean compile emits `invokevirtual` for -`Microblock.setShape` and `invokeinterface` for `MicroblockClient.getBounds` and both client `render` calls, matching -the Scala reference. Accepted classfile-only differences are removed Scala signature/marker attributes, a private -constructor on the static facade and the companion class initializer without Scala's `ACC_PUBLIC` flag. - -### Compiler artifacts - -Accepted divergence: `MicroblockRender$$anon$1`, `MicroblockRender$$anonfun$renderCuboid$1`, and -`MicroblockRender$$anonfun$renderCuboid$2` disappear. Java's constructor reference initializes the thread-local face, -and the direct loop needs none of the private Scala implementation classes. The downstream inventory contains no -references to them. - -### Validation - -- `MicroblockRenderCharacterizationTest`: 4 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 238 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 103 tests, 0 failures, 0 errors, including runtime-generated microblock classes. -- Clean reference/port jars retain the same two supported types, and raw `javap` comparison confirms identical - callable public names/descriptors and retained field shape. -- Actual item, material-face, placement-grid and highlight OpenGL output remains on the manual checklist. - -## 2026-09-01 — MicroblockClass Java port - -The abstract microblock factory, common factory base and common-factory registry singleton are now Java. - -### Observable behavior - -No known runtime divergence. Construction still registers the common trait eagerly. The client trait ID remains a -synchronized, one-time lazy value backed by the same volatile bitmap shape, so a dedicated server does not initialize -the client trait. `register(int)` still publishes the multipart factory before assigning and publishing the common -class ID. Packet creation still passes `client = true`; NBT creation still passes `client = false`. - -The common-class registry remains a fixed 256-entry array indexed by the signed high byte of the material ID. A -duplicate registration still throws with the same message and leaves the first entry installed. - -### ABI and reflection compatibility - -The retained runtime types are exactly `MicroblockClass`, `CommonMicroClass`, and `CommonMicroClass$`. Their hierarchy, -constructors, callable public names/descriptors, private fields and `@SideOnly` annotations match the Scala reference. -The compiler-generated covariant `createPart` bridges retain the `TMultiPart` descriptors expected by -`IPartFactory2`. - -This identity is load-bearing: Schematica calls `MicroblockClass.create(boolean, int)` reflectively, while GuideNH -matches `MicroblockGenerator$.create(MicroblockClass, int, boolean)` by exact parameter type. Both descriptors are -unchanged. The `CommonMicroClass` static facade and `CommonMicroClass$.MODULE$` companion also remain available to -downstream Scala and Java consumers. - -Accepted classfile-only differences are removed Scala signature/marker attributes, removal of the private Scala -`classId` accessor methods, and the companion class initializer without Scala's `ACC_PUBLIC` flag. The exact private -`clientTraitId$lzycompute` method, `clientTraitId` field and `bitmap$0` field are deliberately retained. - -### Compiler artifacts - -No runtime class is added or removed; both clean jars contain the same three supported types. - -### Validation - -- `MicroblockClassCharacterizationTest`: 3 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 241 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 103 tests, 0 failures, 0 errors, including all five built-in factories and - runtime-generated microblock classes. -- Clean reference/port jars retain the same three types, and raw `javap` comparison confirms identical callable public - names/descriptors and retained field/annotation shapes. -- The real constructor cannot be initialized under the plain-JVM application class loader; exact generator calls are - therefore frozen at the bytecode boundary and exercised end to end by the Forge suite. - -## 2026-09-01 — Microblock base Java port - -The shared abstract microblock base and its generated default-argument companion are now Java. The three mixin traits -from the same source unit remain Scala in `MicroblockTraits.scala`; translating them would require either changing -their multiple-inheritance shape or widening the mixin generator, neither of which is needed to port the base. - -### Observable behavior - -No known gameplay divergence. Material and shape state, signed-byte shape packing, cuboid routing, type/strength/light/ -transparency/resistance delegation, drop denominations, pick-item preference, description and update bytes, tile -notification order, and `shape`/`material` NBT remain unchanged. - -`getDrops()` now returns a directly populated `ArrayList` instead of the Java view of a Scala `ListBuffer`. Both are -mutable Java `List` implementations with the same ordered contents; no audited consumer depends on the concrete list -class. Direct `4, 2, 1` loops also replace Scala collection traversal and `pickItem`'s non-local-return exception. - -### ABI and reflection compatibility - -`Microblock` remains a public abstract subclass of `TMultiPart` implementing `TCuboidPart`, with exactly one public -`(int)` constructor, the same private mutable `material: int` and `shape: byte` fields, and every callable public name -and descriptor retained. `Microblock$`, `MODULE$`, the constructor-default method and its static forwarder also remain. -GuideNH's reflected `microClass()`, `material()` and `shape()` members and Schematica's `Microblock` type identity are -therefore unchanged. - -`MicroblockClient`, `CommonMicroblock`, `CommonMicroblockClient` and their three `$class` helpers remain Scala and -retain their exact interface hierarchy and public descriptors. The three remaining Scala source assignments in the -corner/edge units now name `shape_$eq(byte)` explicitly because Java classfiles do not carry Scala source-property -metadata; the emitted call and runtime behavior are the same. - -Accepted classfile-only differences are removed Scala signature/marker attributes from `Microblock`, Java's ordinary -companion class-initializer flag, and the traits' updated source-file marker. - -### Compiler artifacts - -`Microblock$$anonfun$getDrops$1` and `Microblock$$anonfun$pickItem$1` disappear. The direct Java loops need neither -private Scala closure; the downstream inventory contains no reference to them. The other eight supported runtime -types are unchanged. - -### Validation - -- `MicroblockCharacterizationTest`: 3 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 244 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 103 tests, 0 failures, 0 errors, including generated face/hollow parts and a - separately compiled external Scala microblock trait. -- Raw `javap` comparison confirms identical callable public names/descriptors for `Microblock`, `Microblock$`, all - three traits and all three `$class` helpers; the retained class inventory is otherwise exact. - -## 2026-09-01 — FaceMicroblock factory Java port - -The face placement and factory facades/companions are now Java. The generated `FaceMicroblock` and -`FaceMicroblockClient` traits remain Scala in `FaceMicroblockTraits.scala`; translating them would widen the generator -work without helping this concrete-state port. - -### Observable behavior - -No known runtime divergence. Placement still selects the opposite face with `slot ^ 1`, expands only when the clicked -side is that opposite face, and uses the same face placement grid. Factory name, item slot, resistance, trait classes -and eager common-trait registration are unchanged. - -The bounds table remains a mutable 256-entry array. The same 42 entries (`size` 1 through 7, `side` 0 through 5) are -populated with the same rotations and cuboids; all other entries remain null. Generated parts still use the table -entry by identity, expose the same face slot and delegate solidity to their material. - -### ABI and reflection compatibility - -All eight retained facade, companion, trait and `$class` types keep their hierarchy and callable public -names/descriptors. The static `FaceMicroClass.aBounds(): Cuboid6[]` method used by WirelessRedstone and existing -ProjectRed binaries is unchanged, as are `FaceMicroClass.getClassId()` and both `MODULE$` singleton fields. - -Recompiled Scala source must write `FaceMicroClass.aBounds()(index)` rather than -`FaceMicroClass.aBounds(index)`, because the Java facade does not carry Scala property metadata. This is source-only; -existing bytecode already performs the unchanged zero-argument getter followed by an array load. The companion's -`baseTrait` generic signature is necessarily `Class` in Java rather than Scala's -`Class`; its raw JVM descriptor remains `()Ljava/lang/Class;`, and the static facade retains the -consumer-facing `Class` signature. - -Accepted classfile-only differences also include the ordinary Java companion class-initializer flag and removed -Scala signature/marker attributes. - -### Compiler artifacts - -`FaceMicroClass$$anonfun$1` and `FaceMicroClass$$anonfun$1$$anonfun$apply$mcVI$sp$1` disappear. Direct nested Java -loops need neither private bounds-initializer closure, and the downstream inventory contains no reference to them. -The eight supported runtime types remain. - -### Validation - -- `FaceMicroblockCharacterizationTest`: 2 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 246 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 104 tests, 0 failures, 0 errors, including all 42 bounds and a runtime-generated - face part. -- Raw `javap` comparison confirms identical callable public names/descriptors for both facades, both companions, both - traits and both `$class` helpers. -- Actual face rendering and highlight geometry remain covered by the existing manual checklist entries. - -## 2026-09-02 — CornerMicroblock factory Java port - -The corner placement and factory facades/companions are now Java. The generated `CornerMicroblock` trait remains -Scala in `CornerMicroblockTraits.scala`, avoiding any generator expansion for a port that only needs concrete state. - -### Observable behavior - -No known runtime divergence. Placement still toggles the corner bit for the clicked axis with -`1 << (side >> 1)`, uses the same corner grid, and inherits the same always-true expand/sneak defaults. Factory name, -item slot, resistance and trait classes remain unchanged. - -The bounds table remains a mutable 256-entry array. The same 56 entries (`size` 1 through 7, `corner` 0 through 7) -are populated with the same centre-relative axis mirrors; all other entries remain null. Generated parts still encode -`slot - 7` in the shape nibble, recover the slot with `getShape + 7`, and return the table entry by identity. - -### ABI and reflection compatibility - -All six retained facade, companion, trait and `$class` types keep their hierarchy and callable public -names/descriptors. ProjectRed's load-bearing `CornerMicroClass$.MODULE$.getClassId()` call is unchanged, as are the -static facade and both singleton fields. The stable `"mcr_cnr"` ID used by BuildCraft and MatterManipulator is also -unchanged. - -Recompiled Scala source must write `CornerMicroClass.aBounds()(index)` rather than -`CornerMicroClass.aBounds(index)`, because the Java facade does not carry Scala property metadata. This is source-only; -existing bytecode still performs the unchanged zero-argument getter followed by an array load. The companion's -`baseTrait` generic signature is necessarily `Class` in Java rather than Scala's -`Class`; its raw JVM descriptor remains `()Ljava/lang/Class;`, and the static facade retains the -consumer-facing `Class` signature. - -Accepted classfile-only differences also include the ordinary Java companion class-initializer flag and removed -Scala signature/marker attributes. - -### Compiler artifacts - -`CornerMicroClass$$anonfun$1` and `CornerMicroClass$$anonfun$1$$anonfun$apply$mcVI$sp$1` disappear. Direct nested Java -loops need neither private bounds-initializer closure, and the downstream inventory contains no reference to them. -The six supported runtime types remain. - -### Validation - -- `CornerMicroblockCharacterizationTest`: 2 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 248 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 105 tests, 0 failures, 0 errors, including all 56 bounds and a runtime-generated - corner part. -- Raw `javap` comparison confirms identical callable public names/descriptors for both facades, both companions, the - trait and its `$class` helper. -- Actual corner rendering and highlight geometry remain covered by the existing manual checklist entries. - -## 2026-09-02 — Edge/Post microblock factory Java port - -The Edge placement/factory and Post factory facades/companions are now Java. `EdgeMicroblock`, `PostMicroblock`, and -the stateful `PostMicroblockClient` remain Scala in `EdgeMicroblockTraits.scala`; their multiple-inheritance and -generated state/super-accessor surfaces need no generator changes for this concrete port. - -### Observable behavior - -No known runtime divergence. Edge opposite selection still preserves negative custom slots and toggles the packed -edge bit for the clicked axis. Custom placement still creates posts only for even sizes, yields to normal edge -placement outside the grid centre, expands only a matching-material post whose combined size is below eight, and -retains the same internal/opposite/external precedence. - -The Edge bounds table remains a mutable 256-entry array with exactly 84 populated entries (`size` 1 through 7 over 12 -edges). The Post table likewise retains exactly 12 entries (even sizes 2, 4, 6 over three axes). Generated edges keep -their `slot - 15` shape encoding. Generated posts keep the Edge item class ID, one-element occlusion list, partial and -normal occlusion behavior, resistance and axis-zero torch support. - -The Post client trait's two mutable render bounds, lifecycle recalculation, face/post shrinking order and transparency/ -size/axis tie-break remain the original Scala implementation. Actual client rendering remains a manual check. - -### ABI and reflection compatibility - -All twelve retained facade, companion, trait and `$class` types keep their hierarchy and callable public -names/descriptors. ProjectRed's load-bearing `EdgeMicroClass$.MODULE$.getClassId()` and UtilitiesInExcess's static -`EdgeMicroClass.getClassId()` calls are unchanged. The stable `"mcr_edge"` ID used by both BuildCraft and -MatterManipulator, and BuildCraft's `"mcr_post"` ID, are unchanged. - -Recompiled Scala source must use `EdgeMicroClass.aBounds()(index)` and `PostMicroClass.aBounds()(index)` because Java -facades do not carry Scala property metadata. Existing bytecode still performs the same zero-argument getter followed -by an array load. Both companion `baseTrait` generic signatures widen to `Class` in Java; their -raw JVM descriptors remain `()Ljava/lang/Class;`, and both static facades retain their consumer-facing trait type. - -Accepted classfile-only differences also include ordinary Java companion class-initializer flags and removed Scala -signature/marker attributes from the six Java types. - -### Compiler artifacts - -The two `EdgeMicroClass$$anonfun$1...` and two `PostMicroClass$$anonfun$2...` bounds-initializer classes disappear. -Direct nested Java loops need none of them, and the downstream inventory contains no references. The stateful -`PostMicroblockClient$$anonfun$recalcBounds$1` class remains and its complete private surface matches the reference. - -### Validation - -- `EdgeMicroblockCharacterizationTest`: 2 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 250 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 108 tests, 0 failures, 0 errors, including both generated families, all 96 - populated bounds, even/odd custom placement and in-place Post expansion. -- Raw `javap` comparison confirms identical callable public names/descriptors for all twelve supported types and an - exact private-surface match for the retained Post client traversal closure. -- Actual Edge/Post rendering and neighbour-driven Post shrink geometry remain on the manual checklist. - -## 2026-09-02 — Hollow microblock factory Java port - -The Hollow placement and factory facades/companions are now Java. `HollowMicroblock` and the stateful -`HollowMicroblockClient` remain Scala in `HollowMicroblockTraits.scala`; their generated multiple-inheritance, -mutable render state and super-accessor surfaces require no generator change for this concrete port. - -### Observable behavior - -No known runtime divergence. Placement still uses the nested `FaceEdgeGrid` at exactly `3 / 8D`, flips face slots -with `slot ^ 1`, and expands only when the selected slot is opposite the clicked side. Factory name, item slot, -resistance and both trait classes remain unchanged. - -The partial-occlusion and central-occlusion tables remain mutable 256-entry arrays with the same 42 populated shapes -(`size` 1 through 7 over six faces). Every partial entry remains a Scala immutable sequence of the same four -transformed rim boxes. Generated Hollow parts retain Face bounds, normal and partial occlusion, complete-occlusion -permission, false face solidity and the `0x10` redstone conduction map. - -With no tile or no compatible centre part, the opening remains eight pixels. An `ISidedHollowConnect` centre part -still supplies the face-specific opening size. All collision, occlusion and raytrace subpart boxes retain their exact -orientation and dimensions for all six faces and supported connector sizes 1 through 11. The client render, -breaking-overlay and highlight implementations remain the original Scala bytecode; actual OpenGL output stays on the -manual checklist. - -### ABI and reflection compatibility - -All nine supported facade, companion, nested-grid, trait and `$class` types keep their hierarchy and callable public -names/descriptors. `HollowPlacement.HollowPlacementGrid$` remains a real public static nested class in the -`InnerClasses` attribute as well as retaining the binary name -`codechicken.microblock.HollowPlacement$HollowPlacementGrid$`. This preserves both Java source and existing binary -linkage. - -ProjectRed's static `HollowMicroClass.getClassId()` call and `HollowMicroblock` type checks remain exact. Extra -Utilities' `HollowMicroblockClient` type checks remain exact. The stable `"mcr_hllw"` ID used by BuildCraft and -MatterManipulator is unchanged. - -The companion's `baseTrait` generic signature necessarily widens to `Class` in Java rather -than Scala's `Class`; its raw descriptor remains `()Ljava/lang/Class;`, while the static facade -retains the consumer-facing trait type. Accepted classfile-only differences also include ordinary Java companion -class-initializer flags and removed Scala signature/marker attributes from the concrete Java types. - -### Compiler artifacts - -`HollowMicroClass$$anonfun$1` and its two nested bounds-table initializer closures disappear. Direct Java loops need -none of them, and the downstream inventory contains no references. Both retained trait helpers and all seven private -trait closures (`getCollisionBoxes`, `getSubParts`, `drawBreaking`, and the four render callbacks) have bytecode- -identical `javap -c -p -s` output after the port. - -### Validation - -- `HollowMicroblockCharacterizationTest`: 2 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 252 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 110 tests, 0 failures, 0 errors, including both 42-entry tables, a generated - Hollow part and every side across connected opening sizes 1 through 11. -- Raw `javap` comparison confirms identical callable public names/descriptors for all nine supported types, the exact - nested-grid relationship, and bytecode-identical retained trait helpers and closures. -- Actual client rendering, breaking overlay and hollow highlight geometry remain on the manual checklist. - -## 2026-09-02 — Micro occlusion Java port - -The concrete `MicroOcclusion` facade and companion are now Java. `JMicroShrinkRender`, `TMicroOcclusion` and the -stateful `TMicroOcclusionClient` remain Scala in `TMicroOcclusion.scala`, preserving their generated-trait, -super-accessor and mutable render-state surfaces without involving the generator. - -### Observable behavior - -No known runtime divergence. Axis shrink remains non-expanding and keeps `-1` as a no-op. Shape priority remains -cover, corner, then edge/post; priority class, size, transparency and slot tie-breaking retain their original order, -including transparency taking precedence over size only for covers. Every valid face/corner/edge `shrinkSide` -mapping is unchanged. - -`shrinkFrom` still either contracts the render bounds or masks a fully covered opaque face. Recalculation still -visits slots 0 through 5 for covers, 0 through 14 for corners, and 0 through 26 for edges/posts. The original Scala -`TMicroOcclusion` material, size, opposite-part and edge/corner decisions are unchanged. - -### ABI and reflection compatibility - -All seven supported facade, companion, trait and `$class` types keep their hierarchy and callable public -names/descriptors. WR-CBE's load-bearing static -`MicroOcclusion.recalcBounds(JMicroShrinkRender, Cuboid6): int` call remains exact, as does the -`JMicroShrinkRender` interface. The downstream inventory contains no references to the private implementation -closure or trait helpers. - -The five retained Scala types and helpers have bytecode-identical `javap -p -c -s` output. Accepted classfile-only -differences in the two Java types are ordinary Java singleton initialization, constructors and removed Scala -signature/marker attributes. - -### Compiler artifacts - -`MicroOcclusion$$anonfun$shrink$1` disappears. Direct Java slot iteration needs no closure, and the downstream -inventory contains no reference to it. - -### Validation - -- `MicroOcclusionCharacterizationTest`: 5 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 257 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 110 tests, 0 failures, 0 errors. -- Raw `javap` comparison confirms identical callable public names/descriptors for all seven supported types and - bytecode-identical retained trait/helper disassembly. -- Actual neighbour-driven shrink and render-bound refresh remain on the manual checklist. - -## 2026-09-02 — Microblock generator Java port - -The `MicroblockGenerator` facade, companion and nested `IGeneratedMaterial` interface are now Java. The companion -still extends the unchanged Scala `ASMMixinFactory` and implements the unchanged Scala `ScratchBitSet`; -all ScalaSignature parsing, Scala-trait registration and generated-class compilation remain in the original ASM -subsystem. - -### Observable behavior - -No known runtime divergence. Each `create` still clears and reuses the current thread's scratch `BitSet`, selects the -microblock class's base trait, adds the client trait only for client construction, then lets an -`IGeneratedMaterial` amend that same set before construction. The material ID remains a boxed `Integer` in the sole -generated constructor argument. - -The public scratch setter remains behaviorally replaceable despite being a compiler-oriented trait member. The -Forge fixture proves an external material receives only the expected initial base bit, adds a registered third-party -Scala trait, and produces a generated microblock with that trait's initialized state and dispatch. - -### ABI and reflection compatibility - -The facade, companion and nested material interface retain the same three binary names, hierarchy and callable -public names/descriptors. `IGeneratedMaterial` remains a real public static member of `MicroblockGenerator`; the -original pure abstract Scala trait emitted no `$class` helper, so none is removed. - -ProjectRed's load-bearing `MicroblockGenerator$.registerTrait(Class): int` call remains exact, and the unchanged -`ASMMixinFactory` still recognizes and compiles its external `LightMicroblock` Scala trait. GuideNH's exact reflective -`MicroblockGenerator$.create(MicroblockClass, int, boolean)` lookup also remains exact. All inherited static -forwarders, including the Scala `Seq`-shaped `construct`, keep their raw descriptors and generic surface. - -Accepted classfile-only differences are the Java facade's private constructor, the ordinary non-public Java class -initializer flag and removed Scala marker attributes. The private scratch `ThreadLocal` loses `ACC_FINAL`: Java -cannot assign a final instance field through the required public Scala-trait setter, and preserving the setter's -observable replacement behavior is more important than an unreferenced private modifier. - -### Compiler artifacts - -None. The clean reference and port jars contain the same three `MicroblockGenerator` classes. - -### Validation - -- `MicroblockGeneratorCharacterizationTest`: 3 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 260 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 111 tests, 0 failures, 0 errors, including material-driven addition, - initialization and dispatch of the external Scala microblock trait. -- Raw `javap` comparison confirms the exact three-class list and identical callable public names/descriptors. -- The existing ProjectRed illuminated-microblock row remains the full-pack/client manual checkpoint. - -## 2026-09-02 — Multipart generator Java port - -The `MultipartGenerator` facade and companion are now Java. `MultipartMixinFactory`, `ASMMixinFactory`, -`ScratchBitSet` and the compiler remain Scala; the factory callback only changes its source spelling to -`MultipartGenerator$.MODULE$.registerTileClass`. - -### Observable behavior - -No known runtime divergence. Trait discovery retains interface/class/superclass traversal order, distinct trait -names, separate client/server caches and the original lack of cache invalidation after late registration. Duplicate -registrations keep the first mapping. A failed trait lookup still leaves its side mapping inserted, and null traits -still exclude that side. Construction clears the same thread-local scratch set and adds the client bit only on the -client path. - -Registered tile classes still receive an independent bit-set snapshot and the proxy's virtual companion callback. -Composite construction reuses only an exact registered trait set; unregistered tile classes retain the original -missing-map-entry failure. Vanilla conversion and live tile upgrades/downgrades preserve packet/callback order, -invalidation, part ordering, rebinding and copying. The removal comparison retains Scala's value equality. - -### ABI and reflection compatibility - -The facade's seven methods and companion's fifteen methods retain their names and descriptors. The five private -Scala mutable-map fields, the public mangled map/cache accessors and the `ScratchBitSet` interface remain. GuideNH -and Schematica still reach `generateCompositeTile(TileEntity, scala.collection.Iterable, boolean)` only through -`MultipartGenerator$.MODULE$`; no new static generation entry point is introduced. Shipping static and companion -pass-through registration calls also remain exact. - -A frozen Scala 2.11.5 consumer compiled against the untouched reference calls both companion generation and default -pass-through registration, then exercises a generated forwarding method under Forge. - -Accepted classfile-only differences are the private Java facade constructor, ordinary Java singleton initialization -and removed Scala marker attributes. As with `MicroblockGenerator`, the private scratch `ThreadLocal` loses -`ACC_FINAL` so the public Scala-trait setter remains replaceable. Unreferenced private map getters are gone. - -### Compiler artifacts - -Six private Scala closure classes disappear: the `traitsForPart` closure and its four hierarchy/mapping helpers, plus -the `setTraits` traversal closure. The downstream inventory contains no references to them. Hierarchy discovery uses -a `LinkedHashSet`; part iteration uses the existing Scala iterator without extra collection adapters. - -### Validation - -- `MultipartGeneratorCharacterizationTest`: 2 plain-JVM tests, unchanged from the Scala baseline. -- `MultipartGeneratorFunctionalTest`: 5 Forge tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 262 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 116 tests, 0 failures, 0 errors. -- Raw `javap` comparison confirms identical callable public names/descriptors and the expected six-closure removal. -- Real client conversion packets/render rebinding and GuideNH/Schematica previews remain manual checkpoints. - -## 2026-09-02 — Scratch bit-set Java port - -`ScratchBitSet` and `ScratchBitSet$class` are now Java. The multipart and microblock generator companions continue -using the same interface, storage accessors and helper calls without any source changes. - -### Observable behavior - -No known runtime divergence. Initialization installs a new ordinary `ThreadLocal` through the public setter; the -first read on each thread lazily allocates a `BitSet`, and subsequent reads reuse it without clearing. Each owner and -thread has independent storage. `freshBitSet` clears and returns the same set via the owner's virtual `getBitSet`, -preserving overrides instead of directly calling the helper's implementation. - -The lazy-allocation path still reads the storage accessor twice. Public setter replacement and repeated `$init$` -calls still replace storage, without eagerly allocating a set or clearing the previous storage's contents. - -### ABI and source compatibility - -The interface retains its four abstract methods, including the exact mangled getter and raw `ThreadLocal` setter. -The abstract helper class retains all three static methods and their descriptors. Neither type acquires fields, -and both generator companions have unchanged `javap -p -c -s` output. Neither downstream audit identifies a direct -consumer of this trait, so no new frozen Scala consumer is needed. - -Accepted classfile differences are removed Scala marker/signature attributes and a private Java helper constructor -(the original helper had no constructor). Recompiled Scala can no longer inherit implementations merely by mixing -in this Java interface: it must implement the methods and initialize storage explicitly, as the existing Java -generator companions do. Previously compiled helper calls retain their binary entry points. - -### Compiler artifacts - -None. The reference and port jars contain the same two `ScratchBitSet` classes. - -### Validation - -- `ScratchBitSetCharacterizationTest`: 4 plain-JVM tests, unchanged from the Scala baseline. -- Clean complete plain-JVM suite: 266 tests, 0 failures, 0 errors. -- Java 8 Forge dedicated-server suite: 116 tests, 0 failures, 0 errors, including both generator families. -- Raw `javap` comparison confirms the same public names, descriptors, modifiers and class list. -- No new manual checkpoint; existing generator/client integration checks remain on the checklist. +# Java migration divergences + +Current intentional differences from the `1.7.12` reference. This is a compatibility ledger, not a port diary. +An unchanged implementation needs no entry. Results and port history belong in `JAVA_MIGRATION.md` and +`JAVA_MIGRATION_HANDOFF.md`; client gaps in `JAVA_MIGRATION_MANUAL_CHECKS.md`; measurements in +`JAVA_MIGRATION_PROFILE.md`. Superseded decisions and the original per-port narrative remain in git history. + +“No audited consumer” means the frozen GTNH binary inventory and consumer-source audit, not every possible +third-party mod. Removed members can still break unaudited consumers. Check both `JAVA_MIGRATION_ABI_INVENTORY.md` +and `JAVA_MIGRATION_CONSUMER_AUDIT.md` before extending this list. + +## Runtime and error behavior + +| Area | Difference and consequence | +| --- | --- | +| `IDWriter` before `setMax` | `read`/`write` throw `IllegalStateException` instead of `NullPointerException`. Uninitialized use is unsupported. | +| `PacketScheduler` invalid `maskWidth` | Throws `IllegalArgumentException` instead of `scala.MatchError`. Valid widths remain 1, 2, 4 and 8. | +| `NormalOcclusionTest.apply(Traversable, Traversable)` | Materializes both inputs into Java lists before testing instead of nested Scala `forall`. Finite, side-effect-free collections give the same result; eager traversal can change side effects, failure timing and termination for unusual inputs. | +| `MultipartRenderer` dynamic-part guard | Uses short-circuit `\|\|` instead of `\|`; the second getter is no longer evaluated when the first operand succeeds. Ordinary getters give the same render decision. | +| `ControlKeyModifer.map()` | The exposed Java map has no Scala default-value wrapper: an absent key returns null from `get`, not false from Scala `apply`. Use `isControlDown` for the unchanged absent-means-false behavior. | + +Concrete collection implementations also change without changing the declared `java.lang.Iterable`/`List` contracts: + +| Return path | Reference → Java | +| --- | --- | +| `JCuboidPart.getSubParts` / `getCollisionBoxes` | Scala `Seq` adapter → immutable `Collections.singletonList` | +| `MultipartHelper.IPartTileConverter.convertMulti` default | Scala `Seq` adapter → `Collections.emptyList` / `singletonList` | +| `Microblock.getDrops` | Java view of Scala `ListBuffer` → mutable `ArrayList` | + +Code depending on concrete collection classes or their exact mutation failure behavior must adapt. + +## Removed or changed binary surface + +These removals were accepted because neither audit identified a consumer of the removed surface. This does not +authorize removing other members of the same type. + +| Area | Removed or changed surface | +| --- | --- | +| `IDWriter` | Removed `write()`, `write_$eq(Function2)`, `read()` and `read_$eq(Function1)`. Use the Java methods listed below. | +| Both registries | `MicroMaterialRegistry.readIDMap` and `MultiPartRegistry$.readIDMap` return `java.util.List` instead of `scala.collection.Seq`; the return descriptor changes. | +| Registry compiler accessors | Removed `MicroMaterialRegistry`'s public mangled `$$idMap()`, `$$typeMap()` and `$$nameMap()` accessors, and the five `codechicken$multipart$MultiPartRegistry$$...()` accessors. Schematica's separate private `MultiPartRegistry$.$$typeMap` **field is retained** as a live Scala-map view; it is not one of the removed methods. | +| `NormallyOccludedPart` | Removed the inferred `getType(): scala.runtime.Null$` overload; the `String` method remains. | +| `MissingMicroMaterial` | Removed static `canRenderInPass(int)` and `isSolid()` forwarders. The companion no longer declares these methods but inherits the interface defaults. | +| `TileMultipart` | Removed compiler accessor `protected$worldObj(TileMultipart)`. | +| `BlockMultipart` | Removed `hasTileEntity$default$1()`; source callers must supply metadata explicitly. | +| `TileCache` | `map()` now returns Java `Map`; `add`/`remove` return `void` instead of Scala `Option`; `apply(BlockCoord)` returns a nullable `FlaggedTile` instead of `Option`. | +| `TileCache.FlaggedTile` | Dropped Scala case-class `copy`, copy-default getters, `canEqual`, value `equals`/`hashCode`/`toString`, product methods, and `scala.Product`/`scala.Serializable`. It now has ordinary object identity semantics; `t()` and `removed()` remain. | +| `ControlKeyModifer` | Replaced `isClientPressing_$eq(boolean)` with `setClientPressing(boolean)`; `map()` returns Java `Map` instead of Scala mutable `Map`; removed `playerControlValue(EntityPlayer)` and its implicit wrapper type. | +| `ControlKeyHandler` | Former static facade is now a `KeyBinding` subclass with `INSTANCE`. `wasPressed`/`tick` are instance methods, and the twelve inherited-KeyBinding static forwarders disappear. Initializing this client-only class now initializes its binding. | +| `MultipartRenderer` | Removed inherited-TESR static forwarders `func_147498_b`, `func_147496_a` and `func_147497_a`. | + +Removed named helpers and companions (besides private compiler artifacts covered below): + +- `JPartialOcclusion$class`, including `allowCompleteOcclusion` and `$init$`. +- `MicroMaterialRegistry$IMicroMaterial$class` and its four statics. +- `TRandomUpdateTick$class`, including `onWorldJoin` and `$init$`. +- `TScheduledPacketPart$class` and `PacketScheduler$`. +- `IconHitEffects$`. +- `TileCache$` and `TileCache$FlaggedTile$`. +- `ControlKeyModifer$`, `ControlKeyModifer$ControlKeyValue` and `ControlKeyHandler$`. +- `codechicken.multipart.package` / `package$` and `codechicken.microblock.package` / `package$`. + Their logger aliases are replaced by the corresponding proxy's `logger()`. + +Generated-tile helpers removed only from the **raw artifact** are listed separately below; Forge recreates them. +Other retained `$class` bridges and `MODULE$` companions are not covered by this removal decision. + +## Additions and default-method changes + +| Area | Additive Java entry points | +| --- | --- | +| `IDWriter` | `write(MCDataOutput, int)` and `read(MCDataInput)` | +| `JCuboidPart` | Static `subParts`, `collisionBoxes` and `renderBreaking` implementations for explicit forwarding | +| `JItemMultiPart` | Static `hitDepth` and `onItemUse(part, ...)` implementations | +| `MicroMaterialRegistry` | Static `setupIDMap`, `calcMaxCuttingStrength` and `loadIcons` forwarders | +| `PacketScheduler` / `TScheduledPacketPart` | Static `sendScheduled()` on the facade and `readMask(part, packet)` on the interface | +| `TileMultipart` | No-op `renderStatic`, `renderDynamic` and `randomDisplayTick` hooks for dispatching generated overrides through a stable superclass | + +Previously abstract JVM interface methods now have Java defaults, allowing inheritance without Scala forwarders: + +| Interface | Default methods | +| --- | --- | +| `JPartialOcclusion` | `allowCompleteOcclusion` | +| `TFacePart` | `solid`, `redstoneConductionMap` | +| `JIconHitEffects` | `getBreakingIcon` | +| `TItemMultiPart` | `getHitDepth` | +| `TEdgePart` | `conductsRedstone` | +| `Saw` | `getMaxCuttingStrength` | +| `MicroMaterialRegistry.IMicroMaterial` | `loadIcons`, `canRenderInPass`, `isSolid` | +| `TScheduledPacketPart` | `writeScheduled`, `readScheduled` | +| `PlacementGrid` | `render`, `drawLines`, `glTransformFace` | + +`ItemSaw` consequently no longer declares `getMaxCuttingStrength`; ordinary calls still resolve to the default, +but declared-member reflection differs. The same distinction applies to the two `MissingMicroMaterial$` methods above. + +The `TNormalOcclusion` super accessor +`codechicken$multipart$TNormalOcclusion$$super$occlusionTest(TMultiPart)` additionally loses `ACC_SYNTHETIC` and +becomes a default returning true, so javac can see and implement it. `NormallyOccludedPart` inherits it rather than +declaring its own. Existing Scala binaries retain their explicit super-chain overrides. + +## Recompiling Scala consumers + +Binary descriptors alone do not preserve Scala source semantics after `ScalaSignature` metadata is removed. + +### Trait composition + +A Java interface cannot supply a Scala trait's class supertype or its linearization. A superclass method wins over +an interface default, so recompiling `extends TMultiPart with TCuboidPart` silently selects the empty superclass +methods. Explicit forwarding is required where the implementation remains abstract: + +| Trait | Source migration | +| --- | --- | +| `TCuboidPart` | Extend `JCuboidPart`, or forward subparts, collision boxes and breaking rendering to its statics. | +| `TNormalOcclusion` | Explicitly combine `NormalOcclusionTest.apply(this, other)` with the intended super chain. Audit existing `super.occlusionTest` calls too: they no longer route through the old trait. | +| `TIconHitEffects` | Explicitly forward `addHitEffects` and `addDestroyEffects` to `IconHitEffects`. | +| `TItemMultiPart` | Explicitly forward `onItemUse` to `JItemMultiPart`; the inherited Item method otherwise wins. | +| `TRandomUpdateTick` | Explicitly implement `onWorldJoin` with `TickScheduler.loadRandomTick(this)`. | +| `TScheduledPacketPart` | Explicitly forward `read` to `TScheduledPacketPart.readMask(this, packet)`. | +| `ScratchBitSet` | Implement both methods and storage accessors, and initialize storage explicitly; the retained `$class` helper supplies the original implementations. | + +Previously compiled calls to **retained** `$class` bridges still link. This does not apply to the removed helpers above. + +### Source syntax and generic signatures + +- An object used as a value now needs `X$.MODULE$` where that companion is retained (event handlers, proxies, + recipes, packet handlers, materials and generators). Static calls alone do not supply a singleton value. +- Object-application sugar becomes explicit `.apply(...)`, e.g. `NormalOcclusionTest.apply(...)` and + `MicroblockPlacement$.MODULE$.apply(...)`. +- Scala property assignment needs the explicit Java-authored `_$eq(...)` method, e.g. `renderID`, `loadingWorld`, + `angelicaCompat` and microblock `shape`. +- `tile.partList(i)` becomes `tile.partList.apply(i)`. Static bounds getters on Face, Corner, Edge and Post factories + need `aBounds()(index)` instead of `aBounds(index)`; Java no-argument methods may need explicit parentheses. +- `TileMultipart.getOrConvertTile2` exposes `Tuple2` instead of a Scala-typed Boolean second + element; source callers need a cast. Scala 2.11 callbacks to `operate(Function1<..., BoxedUnit>)` need an explicit + `AbstractFunction1` instead of the previous Unit-returning lambda adaptation. +- The Face, Corner, Edge, Post and Hollow factory **companions** widen `baseTrait` to + `Class` from their specific trait type. Their static facades retain the specific generic + type, and the raw JVM return descriptor remains `Class`. +- `MultiPartRegistry.registerParts(IPartFactory, String[])` and the `IPartFactory2` array overload gain Java varargs + flags. `BlockMultipart.addCollisionBoxesToList` uses raw `List` rather than `List` to override vanilla. Neither + changes its raw JVM descriptor. + +## Generated tile traits: raw artifact versus Forge runtime + +These ports replace Scala interfaces/helpers with concrete Java mixin inputs. Forge rewrites the inputs back into +interfaces and generates implementation helpers. Existing binaries retain the runtime interface calls, but code +recompiled against the **untransformed dev jar** may emit `invokevirtual` or `getfield` against a type that becomes +an interface, causing verification/linkage failures. A transformed compile stub or explicit source guidance is +required before claiming source-compatible downstream rebuilds. + +| Raw artifact change | Affected types | +| --- | --- | +| Interface + `$class` → concrete `TileMultipart` subclass | `TSlottedTile`, `TRedstoneTile`, `TTileChangeTile`, `TFluidHandlerTile`, `TileMultipartClient` | +| Interface + `$class` → concrete child mixin input | `TRandomDisplayTickTile` (extends the registered `TileMultipartClient` input) | +| Removed raw `TIInventoryTile$class`; moved implementation into `JInventoryTile` input | `TIInventoryTile` itself remains a Java interface. Source consumers should target it, not the transformed `JInventoryTile` class. | + +Inherited/foreign-field and callback workarounds add package-private access shims for redstone, tile-change, +fluid, inventory and both client traits; they are not new consumer APIs. Transformer constraints and shim recipes +are documented once in the handoff. + +The client-trait port also deliberately extends the Java-trait transformer: + +- Registered Java traits may extend an already registered Java trait; the parent runtime interface participates in + hierarchy and linearization. +- Explicit field accessors are recognized rather than duplicated. +- Transient input fields are excluded from automatic `copyFrom`. Client render caches use this opt-out; their + generated runtime fields remain ordinary private fields. + +## Shared classfile differences + +These are accepted once for the migration, not repeated for every otherwise equivalent port: + +- Java-authored types lose Scala signature/marker attributes and use Java source-file/debug metadata. Static facades + and helper classes gain private constructors where Scala emitted none. Java class initializers lack Scala's + `ACC_PUBLIC`, and singleton publication follows Java initialization rather than Scala's constructor assignment. +- Unreferenced Scala `$$anonfun$`/anonymous implementation classes and private compiler accessors disappear or are + replaced by Java helpers/lambdas. Their names are not supported API. This does **not** include named compatibility + bridges or reflective fields: audit those individually. Retained Scala traits still emit their required helpers. +- The `Object[]` renderer bridges on `ItemMicroPartRenderer$` and `ItemSawRenderer$` are ordinary Java methods rather + than synthetic Scala methods; signatures and dispatch remain available. +- The private scratch `ThreadLocal` fields on `MicroblockGenerator$` and `MultipartGenerator$` lose `ACC_FINAL` so + their public Scala-trait setters can still replace storage. +- TickScheduler's private Scala scheduler types become package-private static nested Java classes, retaining their + binary names. + +## Updating this ledger + +Add only a new effective runtime, binary, source or classfile difference, with its consequence and reason for +acceptance. Amend an existing row when a later change supersedes it. Do not add passing test counts, unchanged +behavior, build observations, performance claims or a “no divergence” section for each new port. diff --git a/JAVA_MIGRATION_HANDOFF.md b/JAVA_MIGRATION_HANDOFF.md index a582ca9..fd8a886 100644 --- a/JAVA_MIGRATION_HANDOFF.md +++ b/JAVA_MIGRATION_HANDOFF.md @@ -8,7 +8,7 @@ what breaks, and what is left. The other documents hold the reasoning. | `JAVA_MIGRATION.md` | The plan, phase state, and a running findings log | | `JAVA_MIGRATION_ABI_INVENTORY.md` | Which downstream mods use what. **The authority on whether anything is load-bearing** | | `JAVA_MIGRATION_CONSUMER_AUDIT.md` | How every consumer uses FMP at runtime: data, lifecycle, reflection, and generated tiles | -| `JAVA_MIGRATION_DIVERGENCES.md` | Every intentional difference from the reference, one entry per port | +| `JAVA_MIGRATION_DIVERGENCES.md` | Current intentional compatibility differences; shared compiler changes recorded once | | `JAVA_MIGRATION_MANUAL_CHECKS.md` | What no automated test can cover, and must be checked by hand in a client | | `JAVA_MIGRATION_PROFILE.md` | The focused baseline, first measured result, findings, and exact rerun command | @@ -29,7 +29,8 @@ Followed for every port so far. It has caught three real ABI breaks that inspect 2. **Freeze a binary consumer** if the inventory shows a load-bearing `$class` or singleton. Recipe below. 3. **Port.** Delete the `.scala`, add the `.java`. 4. **Verify.** Same tests must pass unchanged, plus the ABI diff below. -5. **Document** in `JAVA_MIGRATION_DIVERGENCES.md`, then commit as `refactor: port X to Java`. +5. **Document** results in `JAVA_MIGRATION.md` and update this handoff. Add to `JAVA_MIGRATION_DIVERGENCES.md` only + for a new effective difference not already covered there, then commit as `refactor: port X to Java`. If a characterization test will not compile after the port, that is a signal, not an inconvenience. Twice it was a real ABI change (`MissingMicroMaterial` forwarders, the `ACC_SYNTHETIC` super accessor). Investigate before adjusting the @@ -90,7 +91,8 @@ diff <(javap -p -cp /tmp/ref.jar codechicken.multipart.X | grep " public" | sor diff <(javap -p -s -cp /tmp/ref.jar codechicken.multipart.X | grep descriptor | sort) <(javap -p -s -cp "$NEW" codechicken.multipart.X | grep descriptor | sort) ``` -Also diff the emitted class list, to catch removed `$$anonfun$` artifacts that belong in the divergence log: +Also diff the emitted class list. Routine unreferenced closure removal is covered once in the divergence ledger; +record the specific comparison in the findings log, and investigate any removed named API or reflective type: ```bash diff <(unzip -Z1 /tmp/ref.jar | grep X | sort) <(unzip -Z1 "$NEW" | grep X | sort)