From bf8c9c24b898b5ac669df55672bcffb277ce114d Mon Sep 17 00:00:00 2001 From: Algent Date: Sun, 30 Aug 2026 13:33:05 +0200 Subject: [PATCH] refactor: port fluid handler trait to java Preserve the exact generated interface and ordered fluid behavior. Isolate FluidStack.amount access outside the transformed class. The transformer treats every field read as trait-owned state. --- JAVA_MIGRATION.md | 7 +- JAVA_MIGRATION_DIVERGENCES.md | 55 ++++++ JAVA_MIGRATION_HANDOFF.md | 28 +-- .../scalatraits/TFluidHandlerTile.java | 165 ++++++++++++++++++ .../scalatraits/TFluidHandlerTile.scala | 139 --------------- 5 files changed, 242 insertions(+), 152 deletions(-) create mode 100644 src/main/scala/codechicken/multipart/scalatraits/TFluidHandlerTile.java delete mode 100644 src/main/scala/codechicken/multipart/scalatraits/TFluidHandlerTile.scala diff --git a/JAVA_MIGRATION.md b/JAVA_MIGRATION.md index 978525f..46644d3 100644 --- a/JAVA_MIGRATION.md +++ b/JAVA_MIGRATION.md @@ -25,9 +25,10 @@ No trustworthy tool will produce a maintainable Java port automatically. A decom 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, `MicroRecipe` port, and the -first three Java-trait ports are complete. `TPartialOcclusionTile` proved the no-field path, `TSlottedTile` proved state -and lifecycle rewriting, and `TRedstoneTile` removed the measured redstone allocation while retaining its exact runtime -interface. See `JAVA_MIGRATION_PROFILE.md`. +first five Java-trait ports are complete. `TPartialOcclusionTile` proved the no-field path, `TSlottedTile` proved state +and lifecycle rewriting, `TRedstoneTile` removed the measured redstone allocation, `TTileChangeTile` exercised mutable +state plus inherited access, and `TFluidHandlerTile` preserved ordered Forge fluid distribution. All retain their exact +runtime interfaces. 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 diff --git a/JAVA_MIGRATION_DIVERGENCES.md b/JAVA_MIGRATION_DIVERGENCES.md index 2853089..ef731b6 100644 --- a/JAVA_MIGRATION_DIVERGENCES.md +++ b/JAVA_MIGRATION_DIVERGENCES.md @@ -1585,3 +1585,58 @@ fix, used here, is to type the shim parameters as `Object` so the cast is always - 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. diff --git a/JAVA_MIGRATION_HANDOFF.md b/JAVA_MIGRATION_HANDOFF.md index 9b248b5..e83c63b 100644 --- a/JAVA_MIGRATION_HANDOFF.md +++ b/JAVA_MIGRATION_HANDOFF.md @@ -12,7 +12,8 @@ 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`. 79 commits including the separate `TTileChangeTile` characterization and port. +Branch: `algent/java`. Base: `master`. 81 commits including separate characterization and port commits for +`TFluidHandlerTile`. ## The one rule that matters @@ -66,7 +67,7 @@ awk -F'"' '/ tankList = new LinkedList<>(); + + @Override + public void copyFrom(TileMultipart that) { + super.copyFrom(that); + if (that instanceof TFluidHandlerTile) { + tankList = ((TFluidHandlerTile) that).tankList; + } + } + + @Override + public void bindPart(TMultiPart part) { + super.bindPart(part); + if (part instanceof IFluidHandler) { + tankList.add((IFluidHandler) part); + } + } + + @Override + public void partRemoved(TMultiPart part, int position) { + super.partRemoved(part, position); + if (part instanceof IFluidHandler) { + tankList.remove(part); + } + } + + @Override + public void clearParts() { + super.clearParts(); + tankList.clear(); + } + + @Override + public FluidTankInfo[] getTankInfo(ForgeDirection direction) { + int tankCount = 0; + for (IFluidHandler handler : tankList) { + tankCount += handler.getTankInfo(direction).length; + } + + FluidTankInfo[] tanks = new FluidTankInfo[tankCount]; + int index = 0; + for (IFluidHandler handler : tankList) { + for (FluidTankInfo tank : handler.getTankInfo(direction)) { + tanks[index++] = tank; + } + } + return tanks; + } + + @Override + public int fill(ForgeDirection direction, FluidStack liquid, boolean doFill) { + int filled = 0; + int initial = TFluidHandlerTileAccess.amount(liquid); + for (IFluidHandler handler : tankList) { + FluidStack remaining = TFluidHandlerTileAccess.copy(liquid, initial - filled); + filled += handler.fill(direction, remaining, doFill); + } + return filled; + } + + @Override + public boolean canFill(ForgeDirection direction, Fluid liquid) { + for (IFluidHandler handler : tankList) { + if (handler.canFill(direction, liquid)) { + return true; + } + } + return false; + } + + @Override + public boolean canDrain(ForgeDirection direction, Fluid liquid) { + for (IFluidHandler handler : tankList) { + if (handler.canDrain(direction, liquid)) { + return true; + } + } + return false; + } + + @Override + public FluidStack drain(ForgeDirection direction, int amount, boolean doDrain) { + FluidStack drained = null; + int drainedAmount = 0; + for (IFluidHandler handler : tankList) { + int remaining = amount - drainedAmount; + FluidStack result = handler.drain(direction, remaining, false); + if (result != null && TFluidHandlerTileAccess.amount(result) > 0 + && (drained == null || drained.isFluidEqual(result))) { + if (doDrain) { + handler.drain(direction, remaining, true); + } + if (drained == null) { + drained = result; + } + drainedAmount += TFluidHandlerTileAccess.amount(result); + } + } + if (drained != null) { + TFluidHandlerTileAccess.setAmount(drained, drainedAmount); + } + return drained; + } + + @Override + public FluidStack drain(ForgeDirection direction, FluidStack liquid, boolean doDrain) { + int amount = TFluidHandlerTileAccess.amount(liquid); + FluidStack drained = null; + int drainedAmount = 0; + for (IFluidHandler handler : tankList) { + FluidStack remaining = TFluidHandlerTileAccess.copy(liquid, amount - drainedAmount); + FluidStack result = handler.drain(direction, remaining, false); + if (result != null && TFluidHandlerTileAccess.amount(result) > 0 + && (drained == null || drained.isFluidEqual(result))) { + if (doDrain) { + handler.drain(direction, remaining, true); + } + if (drained == null) { + drained = result; + } + drainedAmount += TFluidHandlerTileAccess.amount(result); + } + } + if (drained != null) { + TFluidHandlerTileAccess.setAmount(drained, drainedAmount); + } + return drained; + } +} + +/** Keeps fields owned by method arguments outside the generated trait transformer. */ +final class TFluidHandlerTileAccess { + + private TFluidHandlerTileAccess() {} + + static int amount(FluidStack stack) { + return stack.amount; + } + + static void setAmount(FluidStack stack, int amount) { + stack.amount = amount; + } + + static FluidStack copy(FluidStack stack, int amount) { + FluidStack copy = stack.copy(); + copy.amount = amount; + return copy; + } +} diff --git a/src/main/scala/codechicken/multipart/scalatraits/TFluidHandlerTile.scala b/src/main/scala/codechicken/multipart/scalatraits/TFluidHandlerTile.scala deleted file mode 100644 index ef437b9..0000000 --- a/src/main/scala/codechicken/multipart/scalatraits/TFluidHandlerTile.scala +++ /dev/null @@ -1,139 +0,0 @@ -package codechicken.multipart.scalatraits - -import net.minecraftforge.common.util.ForgeDirection -import codechicken.multipart.TMultiPart -import codechicken.multipart.TileMultipart -import net.minecraftforge.fluids.IFluidHandler -import net.minecraftforge.fluids.FluidStack -import net.minecraftforge.fluids.FluidTankInfo -import net.minecraftforge.fluids.Fluid -import java.util.LinkedList -import scala.collection.JavaConversions._ - -/** Mixin trait implementation for parts implementing IFluidHandler. Distributes - * fluid manipulation among fluid handling parts. - */ -trait TFluidHandlerTile extends TileMultipart with IFluidHandler { - var tankList = new LinkedList[IFluidHandler]() - - override def copyFrom(that: TileMultipart) { - super.copyFrom(that) - if (that.isInstanceOf[TFluidHandlerTile]) - tankList = that.asInstanceOf[TFluidHandlerTile].tankList - } - - override def bindPart(part: TMultiPart) { - super.bindPart(part) - if (part.isInstanceOf[IFluidHandler]) - tankList += part.asInstanceOf[IFluidHandler] - } - - override def partRemoved(part: TMultiPart, p: Int) { - super.partRemoved(part, p) - if (part.isInstanceOf[IFluidHandler]) - tankList -= part.asInstanceOf[IFluidHandler] - } - - override def clearParts() { - super.clearParts() - tankList.clear() - } - - override def getTankInfo(dir: ForgeDirection): Array[FluidTankInfo] = { - var tankCount: Int = 0 - tankList.foreach(t => tankCount += t.getTankInfo(dir).length) - val tanks = new Array[FluidTankInfo](tankCount) - var i = 0 - tankList.foreach(p => - p.getTankInfo(dir).foreach { t => - tanks(i) = t - i += 1 - } - ) - return tanks - } - - override def fill( - dir: ForgeDirection, - liquid: FluidStack, - doFill: Boolean - ): Int = { - var filled = 0 - val initial = liquid.amount - tankList.foreach(p => - filled += p.fill(dir, copy(liquid, initial - filled), doFill) - ) - return filled - } - - override def canFill(dir: ForgeDirection, liquid: Fluid) = - tankList.find(_.canFill(dir, liquid)).isDefined - - override def canDrain(dir: ForgeDirection, liquid: Fluid) = - tankList.find(_.canDrain(dir, liquid)).isDefined - - private def copy(liquid: FluidStack, quantity: Int): FluidStack = { - val copy = liquid.copy - copy.amount = quantity - return copy - } - - override def drain( - dir: ForgeDirection, - amount: Int, - doDrain: Boolean - ): FluidStack = { - var drained: FluidStack = null - var d_amount = 0 - tankList.foreach { p => - val drain = amount - d_amount - val ret = p.drain(dir, drain, false) - if ( - ret != null && ret.amount > 0 && (drained == null || drained - .isFluidEqual(ret)) - ) { - if (doDrain) - p.drain(dir, drain, true) - - if (drained == null) - drained = ret - - d_amount += ret.amount - } - } - if (drained != null) - drained.amount = d_amount - - return drained - } - - override def drain( - dir: ForgeDirection, - fluid: FluidStack, - doDrain: Boolean - ): FluidStack = { - val amount = fluid.amount - var drained: FluidStack = null - var d_amount = 0 - tankList.foreach { p => - val drain = copy(fluid, amount - d_amount) - val ret = p.drain(dir, drain, false) - if ( - ret != null && ret.amount > 0 && (drained == null || drained - .isFluidEqual(ret)) - ) { - if (doDrain) - p.drain(dir, drain, true) - - if (drained == null) - drained = ret - - d_amount += ret.amount - } - } - if (drained != null) - drained.amount = d_amount - - return drained - } -}