diff --git a/JAVA_MIGRATION.md b/JAVA_MIGRATION.md index 31bb65f..63e5a9a 100644 --- a/JAVA_MIGRATION.md +++ b/JAVA_MIGRATION.md @@ -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. diff --git a/JAVA_MIGRATION_ABI_INVENTORY.md b/JAVA_MIGRATION_ABI_INVENTORY.md index f962147..58ca3e0 100644 --- a/JAVA_MIGRATION_ABI_INVENTORY.md +++ b/JAVA_MIGRATION_ABI_INVENTORY.md @@ -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. diff --git a/JAVA_MIGRATION_CONSUMER_AUDIT.md b/JAVA_MIGRATION_CONSUMER_AUDIT.md index bdac14a..18e5d61 100644 --- a/JAVA_MIGRATION_CONSUMER_AUDIT.md +++ b/JAVA_MIGRATION_CONSUMER_AUDIT.md @@ -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. diff --git a/JAVA_MIGRATION_HANDOFF.md b/JAVA_MIGRATION_HANDOFF.md index 56f137f..b8da660 100644 --- a/JAVA_MIGRATION_HANDOFF.md +++ b/JAVA_MIGRATION_HANDOFF.md @@ -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. diff --git a/JAVA_MIGRATION_MANUAL_CHECKS.md b/JAVA_MIGRATION_MANUAL_CHECKS.md index 2c88b1f..4e7557a 100644 --- a/JAVA_MIGRATION_MANUAL_CHECKS.md +++ b/JAVA_MIGRATION_MANUAL_CHECKS.md @@ -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. diff --git a/docs/API.md b/docs/API.md index 6131db1..ae0b9df 100644 --- a/docs/API.md +++ b/docs/API.md @@ -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. diff --git a/docs/api/TILE_TRAIT_ACCESS.md b/docs/api/TILE_TRAIT_ACCESS.md index cd68f26..271a575 100644 --- a/docs/api/TILE_TRAIT_ACCESS.md +++ b/docs/api/TILE_TRAIT_ACCESS.md @@ -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. diff --git a/docs/migration/HISTORY.md b/docs/migration/HISTORY.md index b5c41f8..d5bb7e0 100644 --- a/docs/migration/HISTORY.md +++ b/docs/migration/HISTORY.md @@ -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. diff --git a/src/functionalTest/java/codechicken/multipart/examples/TileTraitAccessExample.java b/src/functionalTest/java/codechicken/multipart/examples/TileTraitAccessExample.java index bed6a69..cb22012 100644 --- a/src/functionalTest/java/codechicken/multipart/examples/TileTraitAccessExample.java +++ b/src/functionalTest/java/codechicken/multipart/examples/TileTraitAccessExample.java @@ -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); + } } diff --git a/src/functionalTest/java/codechicken/multipart/test/ForgeEnvironmentSmokeTest.java b/src/functionalTest/java/codechicken/multipart/test/ForgeEnvironmentSmokeTest.java index 29ccc5d..c364b1f 100644 --- a/src/functionalTest/java/codechicken/multipart/test/ForgeEnvironmentSmokeTest.java +++ b/src/functionalTest/java/codechicken/multipart/test/ForgeEnvironmentSmokeTest.java @@ -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); diff --git a/src/functionalTest/java/codechicken/multipart/test/TSlottedTileFunctionalTest.java b/src/functionalTest/java/codechicken/multipart/test/TSlottedTileFunctionalTest.java index 2a548fa..28a1755 100644 --- a/src/functionalTest/java/codechicken/multipart/test/TSlottedTileFunctionalTest.java +++ b/src/functionalTest/java/codechicken/multipart/test/TSlottedTileFunctionalTest.java @@ -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; } diff --git a/src/main/scala/codechicken/multipart/TileMultipart.java b/src/main/scala/codechicken/multipart/TileMultipart.java index d83c9e5..2e1c077 100644 --- a/src/main/scala/codechicken/multipart/TileMultipart.java +++ b/src/main/scala/codechicken/multipart/TileMultipart.java @@ -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. + * + *

+ * 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) {} diff --git a/src/main/scala/codechicken/multipart/scalatraits/TSlottedTile.java b/src/main/scala/codechicken/multipart/scalatraits/TSlottedTile.java index 1ef7061..f791b07 100644 --- a/src/main/scala/codechicken/multipart/scalatraits/TSlottedTile.java +++ b/src/main/scala/codechicken/multipart/scalatraits/TSlottedTile.java @@ -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); + } }