feat: add slot refresh API

This commit is contained in:
Algent committed 2026-09-08 22:58:56 +02:00
1 parent a37e4ec3c6
commit f40a9bf90b
13 files changed
+189 -55

No files matched your search

+4 -2
View File
@@ -64,7 +64,7 @@ The phase checklists include recurring verification rules, historical work and c
| Workstream | Remaining deliverables | Gate |
| --- | --- | --- |
| Complete the supported Java surface | Physical-client validation of the documented illuminated microblock example; custom tile-trait authoring and broader lifecycle guidance; supported slot refresh for OpenComputers; supported orientation customization for Et Futurum and saw-strength customization for Iguana; finish the audited reflection/legacy-use map | Next FMP milestone; direct typed calls and documented override behavior, without requiring consumer reflection |
| Complete the supported Java surface | Physical-client validation of the documented illuminated microblock example; custom tile-trait authoring and broader lifecycle guidance; supported orientation customization for Et Futurum and saw-strength customization for Iguana; finish the audited reflection/legacy-use map | Next FMP milestone; direct typed calls and documented override behavior, without requiring consumer reflection |
| Migrate consumers and adopt releases | Patch GuideNH/Schematica to their documented APIs; migrate ProjectRed's external trait and other Scala/helper users, including OpenComputers, ProjectBlue and ForgeRelocationFMP; direct Galacticraft integration; Et Futurum/Iguana migrations; UtilitiesInExcess enumeration and `mat`/`material` fix; complete the full adoption ledger beyond these hotspots | Source patches, released versions and actual target-pack jars must all be recorded; reference checkouts are not migrated |
| Measure and improve performance | Fresh realistic profiles, ranked candidates, bounded improvements and repeated paired measurements; distinguish FMP implementation gains from migrated-consumer gains and report variability/regressions | Phase 4b starts when API/extension workloads are stable; it can overlap consumer adoption |
| Validate releases | Complete client rendering/particles/lighting/interaction and integration checklist; old-world, multiplayer, movement and preview checks; packaged/obfuscated artifacts on supported runtimes; optional-mod absent/present loading; actual patched-world MCPC hook where supported | Automated Forge tests do not replace physical-client/full-pack evidence; repeat affected checks after consumer migration and Scala removal |
@@ -651,7 +651,9 @@ same-name overload there invites a silent wrong-overload bind.
- [x] Document converter registration, candidate ownership and committed lifecycle with a compiling Java example
and registry/Forge characterization; [guide](docs/api/BLOCK_CONVERTERS.md).
- [x] Characterize raw Java tile-trait linkage failures and document stable interface/base access with a compiling
example; [guide](docs/api/TILE_TRAIT_ACCESS.md). OpenComputers slot mutation and custom tile-trait authoring remain.
example; [guide](docs/api/TILE_TRAIT_ACCESS.md).
- [x] Add a supported `refreshPartSlots` operation for OpenComputers' live slot-array mutation, preserving equality,
virtual bind dispatch, storage/ownership and caller-controlled notification behavior; [guide](docs/api/TILE_TRAIT_ACCESS.md#refreshing-a-changed-slot-mask).
- [ ] Document the supported API with compiling usage examples and an old-to-new migration guide. Validate Java
subclasses and generated extensions on the actual Forge path, including both sides where relevant.
+5 -4
View File
@@ -267,7 +267,8 @@ content only. Existing converter consumers need no API rename; their factory mig
### Stable Java tile capability access
The [guide](docs/api/TILE_TRAIT_ACCESS.md) provides ProjectRed's `TRedstoneTile.openConnections` source migration to
existing `IRedstoneTile.openConnections`. All descriptors and production method bodies remain unchanged; legacy
interface calls still link. The dev jar's raw trait classes are not safe replacements for original compile-time
interfaces: executable javac fixtures demonstrate class-call and field-read linkage failures. OpenComputers' live
`TSlottedTile.v_partMap()` array mutation remains a separate API gap and its runtime accessor must remain supported.
existing `IRedstoneTile.openConnections`. Legacy descriptors remain and interface calls still link. The dev jar's raw
trait classes are not safe replacements for original compile-time interfaces: executable javac fixtures demonstrate
class-call and field-read linkage failures. Additive `TileMultipart.refreshPartSlots(TMultiPart): void`, with the
generated `TSlottedTile` override of the same descriptor, replaces OpenComputers' live-array mutation for source
rebuilds. Keep the old `TSlottedTile.v_partMap()` accessor until released consumer and target-pack adoption.
+7 -5
View File
@@ -513,7 +513,7 @@ tied to a released minimum dependency version. Unlisted contracts remain governe
| Legacy contract | Consumer and inspected source | Supported replacement | Consumer migration/release | Target-pack adoption and removal gate |
| --- | --- | --- | --- | --- |
| `TRedstoneTile.openConnections(int)` | ProjectRed `e173952e96a4`: `transmission/redwires.scala` | Existing stable `IRedstoneTile.openConnections(int)` with the same mask/rotation logic; [guide](docs/api/TILE_TRAIT_ACCESS.md) | FMP source-access example and Forge coverage complete; consumer source patch/release pending | Retain the old runtime interface descriptor until adoption |
| `TSlottedTile.v_partMap()` array mutation | OpenComputers `2c00f79be24b`: `PrintPart.toggleState` | Pending focused slot-refresh API; preserve clearing slots equal to the part, then virtual `bindPart` dispatch | Next bounded FMP API candidate; `partMap` reads and `bindPart` alone are insufficient | Keep the live array/accessor ABI; do not replace it with reflection or a whole-tile reload |
| `TSlottedTile.v_partMap()` array mutation | OpenComputers `2c00f79be24b`: `PrintPart.toggleState` | `TileMultipart.refreshPartSlots(part)`; [equality, cache and notification contract](docs/api/TILE_TRAIT_ACCESS.md#refreshing-a-changed-slot-mask) | FMP API/example complete; consumer source patch/release pending, preserving validation and following sound/notify/packet/schedule order | Keep the live array/accessor ABI until released pack adoption; do not replace it with reflection or a whole-tile reload |
| External Scala `LightMicroblock` registered through `MicroblockGenerator.registerTrait` | ProjectRed `e173952e96a4`: `illumination/lightmicroblocks.scala` | Java source trait registered by name, `IGeneratedMaterial`, typed sibling traversal and halo helper; [example](docs/api/MICROBLOCK_EXTENSIONS.md) | FMP example tested; consumer rewrite/release, existing config/halo wiring and physical-client checks pending | Retain external Scala trait ingestion until released-consumer adoption and internal Scala-trait removal |
| `MultiPartRegistry$.registerParts(IPartFactory2, Seq)` and existing array calls | ProjectRed `e173952e96a4`: transmission, expansion and fabrication proxies | `MultiPartRegistry.registerPartFactory` with existing `IPartFactory2` methods and unchanged IDs | Source patch and release pending; Boolean-factory proxies separately need the two-method adapter described in the guide | No migrated pack version verified; retain all registration bridges and external trait support |
| `MultiPartRegistry$.registerParts(Function2, Seq)` | ForgeRelocationFMP `49a810b8c63b`: proxy init registering `rfmp_frame` | `IPartFactory2` creating a fresh `FramePart` on both paths, registered through `registerPartFactory` | Source patch and release pending; preserve `rfmp_frame` and keep converter/pass-through registration | No migrated pack version verified; retain the function companion descriptor |
@@ -765,7 +765,9 @@ for `TSlottedTile.v_partMap`; the same generated tiles work through `IRedstoneTi
its binary shape or behavior. The Java example compiles without Scala and calls the stable interface.
ProjectRed needs only a cast-owner change for its open-connection query; preserve the surrounding rotation/mask
calculation. OpenComputers' slot-array writes still need a focused capability: they clear entries equal to the toggled
print before virtual `bindPart`, followed by consumer-owned sound/notifications/description/scheduling. No replacement
is claimed for that mutation in this slice. Reference checkouts remain unchanged and no release/adoption is recorded.
Evidence: `run/migration-tile-trait-access-reference/`; custom tile-trait authoring and physical-client checks remain.
calculation. OpenComputers can replace its slot-array cast/loop plus `bindPart` call with
`tile.refreshPartSlots(this)`, preserving its preceding validation/state change and following sound, notification,
description and scheduling order. FMP clears value-equal entries from the live array, then dispatches the virtual bind
chain once; no storage, ownership or notification work is added. Reference checkouts remain unchanged and no
release/adoption is recorded. Evidence: `run/migration-tile-trait-access-reference/` and
`run/migration-slot-refresh-reference/`; custom tile-trait authoring and physical-client checks remain.
+19 -19
View File
@@ -17,7 +17,7 @@ migration checkout; `codex/tile-compatibility-fixes` was deleted after its fixes
## Current state and next target
**573 plain-JVM tests and 283 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **225 Java
**573 plain-JVM tests and 286 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **225 Java
files and 9 Scala files / 747 nonblank Scala lines**. The packaged inventory has 444 classes.
Review follow-up: restored packet-scheduler callback mutation behavior with the original Scala hash-map traversal,
@@ -32,17 +32,18 @@ use, but no override triggering these three regressions was found. All 443 class
payloads and 116 generated dumps are retained. The agreed next milestone is the documented consumer-facing Java API,
followed by consumer release/adoption and final Scala removal; see the plan's API migration design and Phases 8–10.
Latest API work adds [safe Java access guidance for transformed tile traits](docs/api/TILE_TRAIT_ACCESS.md).
Two Forge baseline cases, committed first as `bfe5b86`, execute actual raw javac callers: class-method invocation on
TRedstoneTile throws IncompatibleClassChangeError and a TSlottedTile field read throws NoSuchFieldError. Stable
IRedstoneTile/TileMultipart access works on those same generated tiles. IRedstoneTile's old internal label is corrected
in Javadocs; no production descriptor/body changes. The example compiles as Java 8 without Scala and uses the stable
interface, with an additional Forge case covering all five-bit masks and absent capabilities.
All 573 JVM / 283 Forge tests pass; 573 archived JVM / 282 archived Forge callers pass without recompilation using
their recorded version. All 444 production class APIs, 17 ScalaSignature payloads and 3,761 methods are unchanged.
Of 130 generated dumps, 128 are byte-identical; two helpers differ only by Javadoc line offsets (+4/+5). Evidence: `run/migration-tile-trait-access-reference/`. ProjectRed's cast migration, physical
client validation and consumer adoption remain pending. Converter guidance is complete; custom tile-trait authoring
and OpenComputers' slot-array mutation still need their own supported path.
Latest API work adds `TileMultipart.refreshPartSlots(TMultiPart)` to the
[transformed-tile guide](docs/api/TILE_TRAIT_ACCESS.md). Baseline commit `a37e4ec` freezes OpenComputers' live-array
sequence: clear every cached entry equal to the stored part, preserve unrelated slots, then invoke the virtual
`bindPart` chain once without changing ownership or storage. Generated slotted tiles implement that sequence;
ordinary tiles keep the base no-op. Validation, state mutation and notifications remain the consumer's responsibility.
The example compiles as Java 8 without Scala or reflection and calls the stable base API directly.
All 573 JVM / 286 Forge tests pass. All 573 archived JVM callers pass; the byte-identical archived Forge mod runs 283
of 284 cases successfully, with only its pre-addition generated-method inventory assertion reporting the intentional
addition. All 444 classes and 17 ScalaSignature payloads remain; 3,761 existing methods are unchanged and exactly two
packaged methods are added. Of 130 generated dumps, 124 are byte-identical; six add only the expected transformed
declaration, helper or slotted-composite forwarder. Evidence: `run/migration-slot-refresh-reference/`. OpenComputers'
consumer patch/release, ProjectRed's cast migration, physical-client validation and adoption remain pending.
Direct typed calls are the intended end state for supported integrations. Optional dependencies should isolate typed
compatibility code behind presence/version checks; reflection snippets in earlier guides are temporary legacy
@@ -66,17 +67,16 @@ adoption remain pending. Checkouts remain reference-only. The installed `+719` p
Java surface; supply missing capabilities, precise contracts, migration guidance and compiling examples. Cover
subclass/override behavior and generated extensions as well as ordinary calls. ProjectRed's illuminated microblocks
are the representative external extension case. Consumer mods may remain Scala internally while adopting this API.
The next bounded candidate is a supported slot-refresh operation for OpenComputers PrintPart.toggleState. Characterize
its live-array equality clearing followed by virtual bindPart dispatch before choosing the API. Preserve other parts'
slots, current ownership and consumer-controlled notifications; do not substitute a whole loadPartList reconstruction.
The broader custom tile-trait authoring example and other audited reflection use cases remain separate work.
The next bounded candidate is a compiling custom Java tile-trait authoring example with generated Forge coverage,
including staged registration, override dispatch and stable consumer access. Other audited reflection use cases remain
separate work.
Converter registration/lifecycle and stable tile capability access guidance are complete.
The illuminated microblock example supplies the representative Java extension, but physical-client construction,
connector-dependent halos, lighting and consumer adoption still need their recorded checks.
Progress: all ten Phase 9.1 table rows and Phase 9.2's internal markers are complete, plus Schematica registry lookup,
staged Java tile generation, microblock creation, typed material access and the Java illuminated extension example.
Remaining work includes slot mutation and custom tile-trait authoring and other audited reflection use cases. Consumer patches,
staged Java tile generation, microblock creation, typed material access, the Java illuminated extension example and
slot refresh. Remaining work includes custom tile-trait authoring and other audited reflection use cases. Consumer patches,
releases and pack adoption still precede final Scala removal and client/pack release validation.
Extra Utilities remains an active supported consumer. UtilitiesInExcess is the intended replacement, but the support
@@ -352,7 +352,7 @@ composite has already invoked the real base constructor, then preserves the rema
pick-block, activation or lighting behavior. The headless renderer tests cover compiled dispatch, not GPU output.
- Existing binaries retain the runtime tile interfaces. Recompilation against raw Java mixin inputs can emit invalid
class/field opcodes after Forge transforms them. [Stable capability guidance](docs/api/TILE_TRAIT_ACCESS.md) covers
redstone and ordinary base/interface calls; slot mutation and custom tile-trait authoring remain open. The server
redstone, ordinary base/interface calls and slot refresh; custom tile-trait authoring remains open. The server
pass-through fixture does not cover client exclusion.
- Run representative full-pack CPU/allocation and packaged modern-Java validation before performance/release claims.
Focused results and reruns are in the profile. The current deobfuscated dedicated-server harness uses Java 8.
+5 -2
View File
@@ -128,5 +128,8 @@ committed callback order and example state round trips. Before adopting consumer
face/framed wires with face covers and edge blockers on a physical client/server, including part changes and moves.
- [ ] Verify consumer bytecode uses the stable interface/base owner rather than raw transformed trait class calls or
fields. The [Forge fixture](docs/api/TILE_TRAIT_ACCESS.md) proves server linkage, not all client-side capabilities.
- [ ] Treat OpenComputers print slot-array mutation as still pending a supported API; retain its old binary accessor
until an equivalent source migration, release and pack adoption are validated.
- [ ] Rebuild OpenComputers `PrintPart.toggleState` using `tile.refreshPartSlots(this)`, then exercise inactive/active
and button modes on client/server. Confirm old slots clear, new slots occupy, rejected changes leave caches intact,
and sound, part notification, description update and scheduled reset still occur once in the original order.
- [ ] Verify the migrated OpenComputers bytecode no longer names `TSlottedTile`/`v_partMap`; retain the old accessor
until its released version is present in the target pack.
+13 -8
View File
@@ -27,6 +27,7 @@ Existing reflective binaries remain supported until consumer release and pack ad
| Read a microblock material's block and metadata | `BlockMicroMaterial.block()`, `meta()` — [typed GuideNH query, identity and overrides](api/MATERIAL_ACCESS.md) |
| Create a microblock with the requested material and side | `MicroblockGenerator.create(MicroblockClass, int, boolean)` — [construction, material traits and GuideNH migration](api/MICROBLOCK_CREATION.md) |
| Call generated tile capabilities from Java | `TileMultipart`, `IRedstoneTile` and ordinary interfaces — [safe compilation and raw-trait pitfalls](api/TILE_TRAIT_ACCESS.md) |
| Refresh slots after a stored part changes shape | `refreshPartSlots(TMultiPart)` — [ownership, equality and notification responsibilities](api/TILE_TRAIT_ACCESS.md#refreshing-a-changed-slot-mask) |
| Add material-specific behavior to generated microblocks | `registerTrait(String)` and `IGeneratedMaterial` — [illuminated Java extension, compilation and side contracts](api/MICROBLOCK_EXTENSIONS.md) |
| Read/index/search a tile's parts | `jPartList()` — [part collection ownership and order](api/PART_TRAVERSAL.md#collection-ownership-and-ordering) |
| Run callbacks while skipping detached parts | `forEachPart(Consumer)` — [callback and override behavior](api/PART_TRAVERSAL.md#callback-behavior) |
@@ -80,12 +81,16 @@ The registry's matching companion methods carry the same internal marker. This i
not a claim that every other public member is a supported API. See [TileMultipart's Javadocs](../src/main/scala/codechicken/multipart/TileMultipart.java)
and [registry Javadocs](../src/main/scala/codechicken/microblock/MicroMaterialRegistry.java) for method-specific details.
Two advanced methods remain supported because consumers use them directly:
Three advanced methods remain supported because consumers use them directly:
- **`bindPart(part)`** updates capability caches through generated overrides. It does not insert the part, change
its tile binding or perform placement/notifications. OpenComputers clears a print part's old slot entries before
calling it to populate a changed slot mask. A repeated call does not clear obsolete slots and may append entries
in other trait caches. Use it only with known cache semantics; full reconstruction uses `loadPartList`.
its tile binding or perform placement/notifications. The legacy OpenComputers integration clears a print part's old
slot entries before calling it to populate a changed slot mask. A repeated call does not clear obsolete slots and
may append entries in other trait caches. Use `refreshPartSlots` for that migration; full reconstruction uses
`loadPartList`.
- **`refreshPartSlots(part)`** replaces OpenComputers' direct generated-array mutation. Generated slotted tiles clear
equal cached entries and invoke the virtual bind chain once; base tiles do nothing. It leaves ownership, storage,
validation and notifications to the caller. See the [slot-refresh contract](api/TILE_TRAIT_ACCESS.md#refreshing-a-changed-slot-mask).
- **`internalPartChange(part)`** sends local `onPartChanged` callbacks through the retained `operate` hook. The base
traversal captures list order, skips parts whose binding is null at callback time, and excludes parts equal to the
changed part using `part.equals(p)`. Null broadcasts to all eligible parts. A non-null binding to another tile
@@ -93,7 +98,7 @@ Two advanced methods remain supported because consumers use them directly:
packets and external neighbors separately; this method does none of those. `notifyPartChange` also performs world
update/neighbor/lighting notifications when needed.
No reflection is needed to call either method. `operate` and `getOrConvertTile2` retain their documented legacy
No reflection is needed to call any of these methods. `operate` and `getOrConvertTile2` retain their documented legacy
contracts and Java replacements; neither receives an internal-only marker. Removing those bridges still requires
consumer and internal migration gates. The [consumer audit](../JAVA_MIGRATION_CONSUMER_AUDIT.md#api-boundary-audit)
records the checked source calls and validation.
@@ -107,9 +112,9 @@ must select the intended parameter types when a method is overloaded.
An [illuminated Java microblock extension](api/MICROBLOCK_EXTENSIONS.md) now covers registration, material traits,
light aggregation and halo geometry, with compiling examples and Forge coverage. Its physical-client rendering and
ProjectRed adoption remain open. [Converter registration and lifecycle](api/BLOCK_CONVERTERS.md) are documented and
tested. [Stable tile capability access](api/TILE_TRAIT_ACCESS.md) covers safe Java calls and ProjectRed redstone
queries; OpenComputers slot mutation, custom tile-trait authoring and the remaining audited reflection replacements
are still pending. ProjectRed's existing Scala traits remain supported until adoption.
tested. [Stable tile capability access](api/TILE_TRAIT_ACCESS.md) covers safe Java calls, ProjectRed redstone queries
and OpenComputers slot refresh. Custom tile-trait authoring and the remaining audited reflection replacements are
still pending. ProjectRed's existing Scala traits remain supported until adoption.
All ten entries in the plan's Phase 9.1 API table have Java replacements. That table is a bounded list of signatures;
the broader API, extension and consumer adoption work above remains open.
+40 -13
View File
@@ -65,13 +65,40 @@ tile.asInstanceOf[IRedstoneTile].openConnections(absDir)
That emits an interface call with the stable owner. ProjectRed can remain Scala internally. Keep its legacy
`TRedstoneTile.openConnections` binary contract until release and pack adoption.
## Slot mutation and custom extensions still need separate work
## Refreshing a changed slot mask
`TileMultipart.partMap(slot)` is sufficient for reads. OpenComputers' `PrintPart.toggleState` also clears slots equal
to itself from the live `v_partMap` array, then calls `tile.bindPart(this)`. The read API does not replace that mutation,
and `bindPart` alone does not clear old slots. A whole `loadPartList` reconstruction would run additional lifecycle and
cache work. A focused supported slot-refresh operation, preserving equality and override behavior, is the next API
candidate; do not replace the old integration with reflection or claim that it is already migrated.
Use `TileMultipart.refreshPartSlots(part)` after an already stored part validates and applies a new
`TSlottedPart.getSlotMask()`. It provides the Java replacement for OpenComputers' direct `TSlottedTile.v_partMap`
mutation:
```java
tile.refreshPartSlots(this);
tile.notifyPartChange(this);
sendDescUpdate();
```
The [compiling example](../../src/functionalTest/java/codechicken/multipart/examples/TileTraitAccessExample.java) keeps
the cache operation itself separate because validation, state changes and notification policy belong to the part:
```java
TileTraitAccessExample.refreshSlots(tile, part);
```
On a generated slotted tile, FMP scans the live slot array in index order, clears every entry for which
`Objects.equals(stored, part)` is true, then dispatches the existing virtual `bindPart(part)` once. This preserves
Scala `==` behavior, including distinct equal objects. It reads the array directly, matching the old consumer rather
than a possible `partMap` override. Unrelated slots, part-list storage and tile ownership stay unchanged. The current
mask may overwrite a slot if the caller skipped its normal replacement/occlusion check.
A tile without the slotted capability does nothing. The method does not check that the part is stored, bound to this
tile or slotted, and it does not validate placement, send notifications, mark dirty/render state or schedule updates.
Call it on the owning world thread only after the new shape passes the consumer's existing `canReplacePart` logic.
Keep the tile/part's existing notification, sound, packet and scheduling sequence afterward.
`bindPart` dispatches through every generated cache trait, so those hooks still run once. As before, some non-slot
caches append on bind and are not generally idempotent. This API matches OpenComputers' print part, whose additional
capabilities do not append such caches; it is not a general refresh for inventory/fluid capability changes. A whole
`loadPartList` reconstruction would run broader cache, binding and notification behavior and is not equivalent.
For custom generated tiles, keep consumer-callable methods on an ordinary Java capability interface and use the
stable base for existing tile hooks. Register raw trait inputs by name before class loading, during initialization.
@@ -81,19 +108,19 @@ implementor through occlusion checks. Writing custom aggregation/lifecycle trait
and inherited access. The [microblock extension](MICROBLOCK_EXTENSIONS.md) demonstrates those helper constraints,
but is not a complete custom tile-trait authoring example.
No transformed compile-stub artifact is introduced here: the redstone query already has a stable public interface.
Assess remaining trait-only requirements individually before adding build machinery. Custom tile-trait authoring,
OpenComputers slot mutation and other audited private/reflection contracts remain open.
No transformed compile-stub artifact is introduced here: redstone already has a stable interface and slot refresh is
available on the stable base tile. Assess remaining trait-only requirements individually before adding build
machinery. Custom tile-trait authoring and other audited private/reflection contracts remain open.
## Validation
[Forge fixtures](../../src/functionalTest/java/codechicken/multipart/test/TileTraitAccessFunctionalTest.java) execute
[actual javac-compiled unsafe callers](../../src/functionalTest/java/codechicken/multipart/test/RawTileTraitCalls.java)
against transformed traits and assert both linkage failures. Stable interface/base calls succeed on the same tiles,
and the example checks every five-bit mask plus absent capabilities. Packaged-jar compilation and bytecode inspection
separately verify that the example uses `invokeinterface` with `IRedstoneTile`, without Scala, reflection or raw
trait-class references. Existing binary APIs and generated executable bodies remain unchanged; two helper dumps
only shift source line numbers after Javadoc additions.
and the example checks every five-bit mask, absent capabilities and slot refresh. The slot fixtures compare the new
entry with the frozen consumer sequence, including equality, current-mask rebinding, unrelated slots, ownership and
storage. Packaged-jar compilation and bytecode inspection verify that the example uses stable owners without Scala,
reflection or raw trait-class references. Existing binary APIs remain callable; `refreshPartSlots` is additive.
This is consumer source-access coverage. It does not validate physical-client trait selection/rendering, supply all
custom extension examples, or establish that any consumer has released and adopted a migration.
+23
View File
@@ -2134,3 +2134,26 @@ differences belong in the [divergence ledger](../../JAVA_MIGRATION_DIVERGENCES.m
- Updated API index, plan, audits, handoff and physical-client adoption checks. Reference consumers were not edited,
released or counted as adopted. Custom tile-trait authoring examples, slot mutation, remaining reflection APIs and
physical-client/full-pack validation remain open. Evidence: `run/migration-tile-trait-access-reference/`.
### 2026-09-08 — Stable slot refresh for stored parts
- Traced OpenComputers PrintPart's state toggle at the recorded consumer revision. It changes its slot mask, clears
every live slot entry equal to itself, calls the virtual `bindPart` chain once, then performs its own sound, part
notification, description update and scheduling. Whole-tile reconstruction and `bindPart` alone are not equivalent.
- Committed baseline `a37e4ec` first. Its Forge characterization pins value equality, stale-slot clearing, unrelated
slot retention, current-mask rebinding, ownership and stored-list identity on the untouched implementation.
- Added `TileMultipart.refreshPartSlots(TMultiPart)`. The base method is a no-op; the generated slotted capability
clears equal entries in its live array and calls `bindPart` once. It does not validate, mutate the part, change
storage/ownership or send notifications. This adds no interface, reflection path or general cache abstraction.
- Added a compiling Java example and two Forge regressions for generated dispatch and the non-slotted no-op. Updated
the API index, transformed-tile guide, plan, ABI/adoption ledgers and manual OpenComputers check.
- Normal formatting/checkstyle/build/Forge validation passes with **573 JVM / 286 Forge** tests and zero failures,
errors or skips. All **573 archived JVM** callers pass. The byte-identical archived Forge mod finds **284** cases:
283 pass, and its exact generated-method inventory assertion reports only the intentional added method; the current
inventory assertion includes that method and passes.
- The packaged inventory remains **444 classes** and **17 ScalaSignature payloads**. All **3,761 existing methods**
are unchanged and exactly two methods are added. Of **130** generated dumps, 124 are byte-identical; the other six
add only the transformed declaration/helper and four slotted-composite forwarders. The Java example targets Java 8
without Scala/reflection/raw-trait references. Evidence: `run/migration-slot-refresh-reference/`.
- Consumer source/release/adoption remain pending. Next bounded task: a custom Java tile-trait authoring example with
generated Forge coverage; remaining audited reflection replacements and physical-client checks stay separate.
@@ -1,6 +1,7 @@
package codechicken.multipart.examples;
import codechicken.multipart.IRedstoneTile;
import codechicken.multipart.TMultiPart;
import codechicken.multipart.TileMultipart;
/** Compiling consumer example using a stable capability instead of the raw transformed trait class. */
@@ -12,4 +13,9 @@ public final class TileTraitAccessExample {
public static boolean hasOpenConnection(TileMultipart tile, int side, int mask) {
return tile instanceof IRedstoneTile && (((IRedstoneTile) tile).openConnections(side) & mask) != 0;
}
/** Call after a stored part has validated and applied a new slot mask, before its own notifications. */
public static void refreshSlots(TileMultipart tile, TMultiPart part) {
tile.refreshPartSlots(part);
}
}
@@ -229,6 +229,7 @@ class ForgeEnvironmentSmokeTest {
"copyFrom(Lcodechicken/multipart/TileMultipart;)V",
"partMap(I)Lcodechicken/multipart/TMultiPart;",
"partRemoved(Lcodechicken/multipart/TMultiPart;I)V",
"refreshPartSlots(Lcodechicken/multipart/TMultiPart;)V",
"v_partMap()[Lcodechicken/multipart/TMultiPart;",
"v_partMap_$eq([Lcodechicken/multipart/TMultiPart;)V")),
signatures);
@@ -16,6 +16,7 @@ import codechicken.multipart.TMultiPart;
import codechicken.multipart.TSlottedPart;
import codechicken.multipart.TileMultipart;
import codechicken.multipart.asm.MultipartMixinFactory;
import codechicken.multipart.examples.TileTraitAccessExample;
import codechicken.multipart.scalatraits.TSlottedTile;
import scala.collection.immutable.Nil$;
@@ -115,6 +116,43 @@ class TSlottedTileFunctionalTest {
assertSame(tile, retained.tile());
}
@Test
void javaSlotRefreshMatchesTheConsumerSequence() throws Exception {
TileMultipart tile = newSlottedTile();
EqualSlotPart changed = new EqualSlotPart(1, 1 << 1);
EqualSlotPart retained = new EqualSlotPart(2, 1 << 4);
tile.addPart_do(changed);
tile.addPart_do(retained);
partMap(tile)[3] = new EqualSlotPart(1, 1 << 3);
changed.slotMask = 1 << 5;
changed.slotMaskCalls = 0;
TileTraitAccessExample.refreshSlots(tile, changed);
assertNull(tile.partMap(1));
assertNull(tile.partMap(3));
assertSame(retained, tile.partMap(4));
assertSame(changed, tile.partMap(5));
assertEquals(Arrays.asList(changed, retained), tile.jPartList());
assertSame(tile, changed.tile());
assertSame(tile, retained.tile());
assertEquals(1, changed.slotMaskCalls, "The virtual bind chain runs once");
}
@Test
void javaSlotRefreshIsANoOpWithoutTheGeneratedSlottedCapability() {
TileMultipart tile = new TileMultipart();
EqualSlotPart part = new EqualSlotPart(1, 1);
TileMultipart owner = new TileMultipart();
part.bind(owner);
tile.refreshPartSlots(part);
assertTrue(tile.jPartList().isEmpty());
assertNull(tile.partMap(0));
assertSame(owner, part.tile());
}
@Test
void partRemovedClearsOnlyMatchingSlotsForSlottedParts() throws Exception {
TileMultipart tile = newSlottedTile();
@@ -222,6 +260,7 @@ class TSlottedTileFunctionalTest {
private final int key;
private int slotMask;
private int slotMaskCalls;
private EqualSlotPart(int key, int slotMask) {
this.key = key;
@@ -230,6 +269,7 @@ class TSlottedTileFunctionalTest {
@Override
public int getSlotMask() {
slotMaskCalls++;
return slotMask;
}
@@ -546,6 +546,20 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile {
*/
public void bindPart(TMultiPart part) {}
/**
* Refreshes the generated slot cache after an already stored part changes its {@link TSlottedPart#getSlotMask()}.
* Generated slotted tiles remove every cached entry equal to {@code part}, then dispatch
* {@link #bindPart(TMultiPart)} once to add its current slots. A tile without the slotted capability does nothing.
*
* <p>
* This does not validate placement, insert or bind the part, change the stored list, send notifications, mark the
* tile dirty/renderable or schedule updates. Call only after the part has validated its new shape and updated its
* mask, on the owning world thread. The part normally remains stored and bound to this tile; no eager validation is
* added. Other generated bind hooks also run, so callers must retain their existing cache-specific assumptions and
* perform their own notifications afterward.
*/
public void refreshPartSlots(TMultiPart part) {}
/** Internal FMP placement callback for trait overrides; do not call directly from consumers. */
public void partAdded(TMultiPart part) {}
@@ -10,8 +10,8 @@ import codechicken.multipart.TileMultipart;
/**
* Mixin implementation for slotted parts. Raw compiler input transformed into a runtime interface; consumer Java reads
* slots through {@link TileMultipart#partMap(int)}. Do not compile field accesses against this class: the runtime
* interface has accessor methods instead of fields. Existing binary accessor callers remain supported. Slot-map
* mutation, including clearing old slots before bindPart, is a separate advanced contract; partMap is read-only.
* interface has accessor methods instead of fields. Existing binary accessor callers remain supported. Use
* {@link TileMultipart#refreshPartSlots(TMultiPart)} after changing a stored part's mask; partMap is read-only.
*/
public class TSlottedTile extends TileMultipart {
@@ -73,4 +73,14 @@ public class TSlottedTile extends TileMultipart {
}
}
}
@Override
public void refreshPartSlots(TMultiPart part) {
for (int index = 0; index < v_partMap.length; index++) {
if (Objects.equals(v_partMap[index], part)) {
v_partMap[index] = null;
}
}
bindPart(part);
}
}