refactor: port partial occlusion tile trait to java

This commit is contained in:
Algent committed 2026-08-28 11:27:29 +03:00
1 parent 2b04a2e52b
commit 6c370c8734
7 files changed
+129 -61

No files matched your search

+23 -13
View File
@@ -24,9 +24,10 @@ No trustworthy tool will produce a maintainable Java port automatically. A decom
## Current status
The binary and source-level consumer audits, low-coupling Phase 3 queue, audit-derived immediate compatibility gate,
focused profile, first traversal optimization, complete redstone interaction helper unit, and `MicroRecipe` port are
complete. The remaining measured hot paths are generated tile traits, so the next work starts the Phase 5 Java-trait
pilot; see `JAVA_MIGRATION_PROFILE.md`.
focused profile, first traversal optimization, complete redstone interaction helper unit, `MicroRecipe` port, and the
no-field `TPartialOcclusionTile` Java-trait pilot are complete. Direct Java source now survives the existing
`registerJavaTrait` rewrite with its generated interface, super accessor, behavior, and class caching intact. The next
checkpoint is the stateful `TSlottedTile`; see `JAVA_MIGRATION_PROFILE.md`.
That audit found and this branch has now repaired one existing regression: Schematica 1.12.6 reflects the original private
`MultiPartRegistry$` field `codechicken$multipart$MultiPartRegistry$$typeMap` and casts it to a Scala mutable map. The
@@ -336,22 +337,25 @@ Status: active. `operate` now preserves its captured-sequence mutation semantics
and the six-interface `IRedstonePart`/`RedstoneInteractions$` unit is ported with its class list and descriptors intact.
The comparison proves its allocation is owned by `scalatraits/TRedstoneTile.scala`, so that part waits for Phase 5.
`MicroRecipe` is also Java: all five recipe forms and precedence are characterized, its published Scala façade remains,
and its closure-backed scans and non-local returns are gone. The remaining two hot-path items are generated traits and
will be handled through Phase 5. Start with `TPartialOcclusionTile` as the simple no-field Java-trait pilot before the
stateful slot and redstone traits.
and its closure-backed scans and non-local returns are gone. `TPartialOcclusionTile` has completed the simple no-field
Java-trait pilot. The remaining two hot-path items are stateful generated traits: port `TSlottedTile` as the field and
lifecycle checkpoint before changing `TRedstoneTile` and re-running the redstone profile.
Exit condition: identified steady-state Scala allocation sites are removed with compatible results.
### Phase 5 — Convert built-in tile traits through the existing Java path
- [ ] Characterize the interfaces, fields, lifecycle callbacks, and behavior of the Scala-generated pilot tile.
- [ ] Port one simple built-in trait as a pilot using `registerJavaTrait`.
- [ ] Verify generated methods, interfaces, field initialization, lifecycle callbacks, and class caching against the Scala version.
- [x] Characterize the direct class shape, generated interface, super dispatch, behavior, and class caching of a
no-field pilot.
- [x] Port one simple built-in trait as a pilot using `registerJavaTrait`.
- [ ] Verify generated field accessors, initialization, copying, lifecycle callbacks, and class caching on the
stateful `TSlottedTile` checkpoint. The no-field pilot proves methods/interfaces/caching but cannot prove state.
- [ ] Convert remaining traits in small related groups.
- [ ] Document or deliberately relax the Java trait restrictions only when a real trait requires it.
- [ ] Preserve pass-through interface behavior.
- [ ] For the pilot, explicitly cover OpenComputers' `TSlottedTile.v_partMap` rebinding, AE2's
`TIInventoryTile.rebuildSlotMap`, and ProjectRed/Extra Utilities `TRedstoneTile` behavior.
- [ ] Explicitly cover OpenComputers' `TSlottedTile.v_partMap` mutation/rebinding before that port, AE2's
`TIInventoryTile.rebuildSlotMap` before the inventory trait, and ProjectRed/Extra Utilities behavior before
`TRedstoneTile`.
Exit condition: built-in behavior is implemented in Java while the established runtime composition mechanism remains stable.
@@ -668,5 +672,11 @@ generated-trait compatibility work. Scala-runtime removal remains a later projec
- Ported the recipe singleton to Java with ordinary loops. The published `MicroRecipe` static façade,
`MicroRecipe$.MODULE$`, `scala.Tuple3` return and immutable Scala map descriptors remain; the 12 private Scala
closure classes and their `NonLocalReturnControl` exits are gone.
- The recipe port passes all 141 plain-JVM and 37 Forge tests. The next step is the Phase 5
`TPartialOcclusionTile` Java-trait pilot, whose generated override dispatch is already covered by the Forge harness.
- The recipe port passes all 141 plain-JVM and 37 Forge tests.
- Characterized `TPartialOcclusionTile` against the untouched Scala implementation with four focused tests covering
its exact direct class shape, partial/normal precedence, complete-occlusion behavior, and both short-circuit paths.
- Ported `TPartialOcclusionTile` to direct Java source without changing the generator. Its compiled input still has
one no-arg constructor, no fields, and the same two public descriptors; the Forge rewrite still exposes exactly the
two behavior methods plus its super accessor, caches the generated class, and passes all 37 server tests.
- The pilot raises the plain-JVM baseline to 145 tests. It deliberately proves no field or lifecycle behavior, so the
next checkpoint is `TSlottedTile`, not a bulk conversion of the remaining traits.
+1 -1
View File
@@ -502,7 +502,7 @@ behavior:
6. Treat Scala runtime removal as downstream coordination work after the Java port, not as a requirement of it.
Current-branch generator verification: `ForgeEnvironmentSmokeTest` pins cached built-in `TSlottedTile` generation,
an external Scala microblock trait registered by name like ProjectRed's `LightMicroblock`, Java
an external Scala microblock trait registered by name like ProjectRed's `LightMicroblock`, direct-Java-source
`TPartialOcclusionTile` rewriting and override dispatch, and server-only pass-through forwarding, overloading,
single-implementor selection, copying/rebinding, and removal cleanup. Full downstream mixed tiles and client-side
selection remain Phase 7 integration cases.
+46
View File
@@ -1361,3 +1361,49 @@ paths no longer pay for it.
- 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.
+17 -8
View File
@@ -12,7 +12,7 @@ what breaks, and what is left. The other documents hold the reasoning.
| `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 |
Branch: `algent/java`. Base: `master`. 68 commits including the `MicroRecipe` unit.
Branch: `algent/java`. Base: `master`. 70 commits including the `TPartialOcclusionTile` characterization and Java port.
## The one rule that matters
@@ -66,7 +66,7 @@ awk -F'"' '/<testsuite /{t+=$4;f+=$8;e+=$10} END{print "tests="t" failures="f" e
grep -o 'tests="[0-9]*" skipped="[0-9]*" failures="[0-9]*" errors="[0-9]*"' run/server/junit-out/TEST-*.xml
```
Current baseline: **141 plain-JVM tests, 37 Forge server tests, all passing at their last completed runs.**
Current baseline: **145 plain-JVM tests, 37 Forge server tests, all passing at their last completed runs.**
### ABI diff against the reference
@@ -189,14 +189,14 @@ All eight load-bearing `$class` helpers from the inventory, both registries, and
`IDWriter`, `PartialOcclusionTest`/`JPartialOcclusion`, `TCuboidPart`/`JCuboidPart`, the `TNormalOcclusion` unit,
`TFacePart`, the `TIconHitEffects` unit, `TItemMultiPart`/`JItemMultiPart`, `TEdgePart`, `Saw`, `MicroMaterialRegistry`,
`MultiPartRegistry`, `TileMultipart`, `TMultiPart`, `TickScheduler`, `BlockMultipart`, the complete
`IRedstonePart`/`RedstoneInteractions` unit, and `MicroRecipe`.
`IRedstonePart`/`RedstoneInteractions` unit, `MicroRecipe`, and the no-field `TPartialOcclusionTile` Java-trait pilot.
Plus the six marker interfaces: `TSlottedPart`, `IRandomDisplayTick`, `INeighborTileChange`, `TRandomUpdateTick`,
`ISidedHollowConnect`, `IMicroMaterialRender`, plus `MultipartHelper`, `TileCache`, `PacketScheduler` and the `ControlKeyModifer` pair.
Both `package.scala` objects are gone, removed rather than ported. `MultipartRenderer` is done.
82 Java files, 46 Scala files, ~5,884 Scala lines left (non-blank; that is the metric this figure has always used).
83 Java files, 45 Scala files, ~5,852 Scala lines left (non-blank; that is the metric this figure has always used).
## What is left, and in what order
@@ -238,15 +238,21 @@ and tag matching, all five recipe forms, class-specific gluing, saw position, an
frozen. Its internal scans are ordinary loops, and only the published `getSaw` call still constructs its required
`scala.Tuple3`. The in-repo Scala registration now names `MicroRecipe$.MODULE$` explicitly.
`TPartialOcclusionTile` is now the first built-in generated tile implementation written directly in Java. Four
plain-JVM tests freeze its input class and behavior. The Forge harness proves that `registerJavaTrait` still rewrites it
to the exact three-method runtime interface, preserves override/super dispatch, and reuses the generated composite
class. It has no fields or lifecycle callbacks, so this is not evidence for stateful traits.
**Medium.** The `handler` packages on both sides, `ItemMicroPart`,
`MicroblockPlacement`, `PlacementGrids`, `BlockMicroMaterial`, `MissingMicroMaterial`, `ConfigContent`,
`DefaultContent`.
**Phase 5, needs the `registerJavaTrait` path.** `TileMultipartClient` and everything in `multipart/scalatraits/`.
These are registered with the ASM generator; converting them is a different mechanism with documented restrictions.
Next characterize and port `TPartialOcclusionTile.scala` as the pilot. It has no fields, already takes the Java-trait
rewrite path because it is a concrete class, and the Forge harness already verifies generated override dispatch. Once
that proves direct Java source through `registerJavaTrait`, move to the stateful `TSlottedTile` pilot coverage.
The no-field `TPartialOcclusionTile` pilot is complete without a generator change. Next characterize and port
`TSlottedTile` as the stateful checkpoint. Freeze the generated getter/setter and 27-entry initialization, array identity
through `copyFrom`, clearing/removal/binding, occupied-slot rejection, super-call order, class caching, and
OpenComputers' direct `v_partMap()` mutation pattern before changing its source. Only then proceed to `TRedstoneTile`.
**Phase 6/7, last.** `Microblock` and the microblock shape hierarchy, `MicroblockGenerator`, `MultipartGenerator`, and
all of `multipart/asm/`. The ASM subsystem should be last; freeze generated-class fixtures before touching it.
@@ -260,12 +266,15 @@ all of `multipart/asm/`. The ASM subsystem should be last; freeze generated-clas
work and is required before release claims about real TPS.
- The server side of flag-sensitive pass-through registration is automated; client-side exclusion still belongs to
the packaged-client/manual compatibility run.
- The completed `TPartialOcclusionTile` pilot is stateless. It does not prove the generator's field-to-accessor rewrite,
constructor initialization injection, setter rebinding, or lifecycle ordering; `TSlottedTile` is the required
checkpoint for those mechanisms.
- Microblock-specific NBT and packet payloads still need characterization immediately before that subsystem changes;
the compact core tile/part fixture is complete.
- `TileMultipart`'s `partList` still republishes an immutable Scala `Seq` on every mutation. `operate` no longer calls
the Java port's copying `parts()` helper, but less frequent read and mutation paths still do. Optimize those only if
a representative profile identifies them; their mutable snapshots are intentional at mutation sites.
- The focused redstone allocation remains 80.5 B per three-query iteration. It is generated by
`scalatraits/TRedstoneTile.scala`, not `RedstoneInteractions`; remove it only with the Phase 5 Java-trait pilot.
`scalatraits/TRedstoneTile.scala`, not `RedstoneInteractions`; address it after the stateful `TSlottedTile` checkpoint.
- Phase 1 never properly started. GTNHLib is currently commented out in `dependencies.gradle`; it had been added at
`api` scope to satisfy a test compile rather than because a migration change needed it.
+5 -3
View File
@@ -122,6 +122,8 @@ requires the Phase 5 `registerJavaTrait` path and must not be smuggled into this
characterized, and ordinary loops replaced its range/closure scans and exception-backed non-local returns. The focused
server workload does not craft recipes, so no timing claim is made for that structural removal.
The remaining measured redstone allocation and slot-scan non-local return live in generated traits. Start Phase 5 with
the simpler `TPartialOcclusionTile` Java-source pilot, then use the proven path for `TSlottedTile` and
`TRedstoneTile`; re-run this workload when the latter changes.
The remaining measured redstone allocation and slot-scan non-local return live in generated traits. The simpler
`TPartialOcclusionTile` Java-source pilot is complete and has no profile claim because this workload does not exercise
partial-occlusion placement. It proves direct Java input, generated method/super dispatch, and class caching, but has no
fields or lifecycle callbacks. Use `TSlottedTile` as the stateful generator checkpoint, then port `TRedstoneTile` and
re-run this workload immediately before and after that change.
@@ -0,0 +1,37 @@
package codechicken.multipart.scalatraits;
import codechicken.multipart.JPartialOcclusion;
import codechicken.multipart.PartialOcclusionTest;
import codechicken.multipart.TMultiPart;
import codechicken.multipart.TileMultipart;
import scala.collection.Seq;
import scala.collection.Seq$;
import scala.collection.mutable.Builder;
/** Implementation for the partial occlusion test. */
public class TPartialOcclusionTile extends TileMultipart {
@Override
public boolean occlusionTest(Seq<TMultiPart> parts, TMultiPart newPart) {
if (newPart instanceof JPartialOcclusion) {
Builder<TMultiPart, Seq<TMultiPart>> builder = Seq$.MODULE$.newBuilder();
builder.$plus$plus$eq(parts);
builder.$plus$eq(newPart);
if (!partialOcclusionTest(builder.result())) {
return false;
}
}
return super.occlusionTest(parts, newPart);
}
public boolean partialOcclusionTest(Seq<TMultiPart> parts) {
PartialOcclusionTest test = new PartialOcclusionTest(parts.length());
for (int index = 0; index < parts.length(); index++) {
TMultiPart part = parts.apply(index);
if (part instanceof JPartialOcclusion) {
test.fill(index, (JPartialOcclusion) part);
}
}
return test.apply();
}
}
@@ -1,36 +0,0 @@
package codechicken.multipart.scalatraits
import codechicken.multipart.TileMultipart
import codechicken.multipart.TMultiPart
import codechicken.multipart.JPartialOcclusion
import codechicken.multipart.PartialOcclusionTest
/** Implementation for the partial occlusion test.
*/
class TPartialOcclusionTile extends TileMultipart {
override def occlusionTest(
parts: Seq[TMultiPart],
npart: TMultiPart
): Boolean = {
if (
npart.isInstanceOf[JPartialOcclusion] && !partialOcclusionTest(
parts :+ npart
)
)
return false
return super.occlusionTest(parts, npart)
}
def partialOcclusionTest(parts: Seq[TMultiPart]): Boolean = {
val test = new PartialOcclusionTest(parts.length)
var i = 0
while (i < parts.length) {
val part = parts(i)
if (part.isInstanceOf[JPartialOcclusion])
test.fill(i, part.asInstanceOf[JPartialOcclusion])
i += 1
}
return test()
}
}