diff --git a/JAVA_MIGRATION.md b/JAVA_MIGRATION.md index c4b7553..31bb65f 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; broader extension/lifecycle guidance; safe Java compilation guidance for transformed traits; 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 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 | | 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 | @@ -650,6 +650,8 @@ same-name overload there invites a silent wrong-overload bind. - [x] Confirm every original descriptor still exists in the ABI fixture after these table changes. - [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. - [ ] 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 2ce4aea..f962147 100644 --- a/JAVA_MIGRATION_ABI_INVENTORY.md +++ b/JAVA_MIGRATION_ABI_INVENTORY.md @@ -263,3 +263,11 @@ remain in force. The example itself lives only in the functional-test source set existing ownership and lifecycle behavior; [guide](docs/api/BLOCK_CONVERTERS.md). All static/companion descriptors, production method bodies and ScalaSignature payloads remain unchanged. The compiling example is functional-test content only. Existing converter consumers need no API rename; their factory migration and adoption gates remain. + +### 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. diff --git a/JAVA_MIGRATION_CONSUMER_AUDIT.md b/JAVA_MIGRATION_CONSUMER_AUDIT.md index 826d30a..bdac14a 100644 --- a/JAVA_MIGRATION_CONSUMER_AUDIT.md +++ b/JAVA_MIGRATION_CONSUMER_AUDIT.md @@ -512,6 +512,8 @@ 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 | | 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 | @@ -753,3 +755,17 @@ fresh candidates, rejected probes, original-tile ownership and invalidate/replac The example adds initialized converter/factory registration and NBT/packet/placement coverage, compiled without Scala. Evidence: `run/migration-converter-reference/`; physical-client conversion and real inventory/network transfers still require integration validation. This is FMP API coverage, not a released consumer migration. + +## Stable Java access to transformed tile traits + +The [tile access guide](docs/api/TILE_TRAIT_ACCESS.md) distinguishes raw dev-jar classes from runtime interfaces. +Actual javac callers reproduce `IncompatibleClassChangeError` for `TRedstoneTile.openConnections` and `NoSuchFieldError` +for `TSlottedTile.v_partMap`; the same generated tiles work through `IRedstoneTile` and `TileMultipart.partMap`. +`IRedstoneTile` is now documented as a supported capability, correcting its former internal label without changing +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. diff --git a/JAVA_MIGRATION_HANDOFF.md b/JAVA_MIGRATION_HANDOFF.md index 80d9eb4..56f137f 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 280 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **225 Java +**573 plain-JVM tests and 283 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,15 +32,17 @@ 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 documents existing block converter registration and the committed conversion lifecycle, with a -[compiling Java example](docs/api/BLOCK_CONVERTERS.md). Two JVM tests and one Forge baseline were committed first as -`a56f90c`, covering registration ownership/duplicates, failure propagation, rejected probes and callback ordering. -One further Forge case exercises the initialized example, fresh conversion, NBT/packet state and normal installation. -All 573 JVM / 280 Forge tests pass; 573 archived JVM / 279 archived Forge tests pass without rebuilding their callers. -Production APIs and all 3,761 method bodies remain unchanged (444 classes, 17 ScalaSignature payloads), as do all 130 -generated dumps. The example compiles as Java 8 without Scala. Evidence: `run/migration-converter-reference/`. -Consumer state-transfer rules, physical-client validation and release/adoption remain separate gates. The previous -[illuminated extension](docs/api/MICROBLOCK_EXTENSIONS.md) likewise still needs physical-client/ProjectRed adoption. +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. 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 @@ -64,16 +66,17 @@ 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 Java source-compilation guidance for transformed tile traits: characterize consumer -calls against the published dev artifact, document safe stable-base/capability access, and determine whether any -remaining trait-only calls need a supported Java entry or transformed compile stubs. Other audited reflection use -cases remain separate work. Converter registration and lifecycle guidance are complete. +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. +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 broader extension/compilation guidance and other audited reflection use cases. Consumer patches, +Remaining work includes slot mutation and 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 @@ -348,8 +351,9 @@ composite has already invoked the real base constructor, then preserves the rema placement crash is fixed (`36e1a58`), but that does not establish all rendering, particles, selection/collision, 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; provide transformed compile stubs or source guidance before - claiming source-compatible rebuilds. The server pass-through fixture does not cover client exclusion. + 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 + 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. - Core NBT, descriptions and one-byte shape updates are frozen; characterize each remaining shape's state immediately diff --git a/JAVA_MIGRATION_MANUAL_CHECKS.md b/JAVA_MIGRATION_MANUAL_CHECKS.md index 962f1f1..2c88b1f 100644 --- a/JAVA_MIGRATION_MANUAL_CHECKS.md +++ b/JAVA_MIGRATION_MANUAL_CHECKS.md @@ -121,3 +121,12 @@ committed callback order and example state round trips. Before adopting consumer without duplicate drops, lost contents or ghost connections. Exercise rejection as well as successful placement. - [ ] Recheck consumer side-specific constructors and descriptions; the headless example packet test does not cover physical-client class selection or rendering. Record consumer release and actual pack adoption separately. + +## Stable tile capability adoption + +- [ ] Rebuild ProjectRed's open-connection query against `IRedstoneTile`, retaining its rotation/mask logic; validate + 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. diff --git a/docs/API.md b/docs/API.md index 2be0edd..6131db1 100644 --- a/docs/API.md +++ b/docs/API.md @@ -26,6 +26,7 @@ Existing reflective binaries remain supported until consumer release and pack ad | Enumerate microblock materials by numeric ID | `materialCount()`, `materialName(int)`, `getMaterial(int)` — [material enumeration](api/MATERIAL_ENUMERATION.md) | | 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) | | 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) | @@ -53,7 +54,7 @@ compile classpath for overload resolution, as the [loading guide](api/PART_LOADI | Find, place and remove parts | [TileMultipart](../src/main/scala/codechicken/multipart/TileMultipart.java): `getTile`, `canPlacePart`, `addPart`, `remPart`. Retain the tile returned by changes because generated capabilities can replace the instance | | Construct a server composite tile from parts, or restore saved multipart NBT | [MultipartHelper](../src/main/scala/codechicken/multipart/MultipartHelper.java): `createTileFromParts(Iterable)`, `createTileFromNBT(World, NBTTagCompound)` | | Register microblock materials | [MicroMaterialRegistry](../src/main/scala/codechicken/microblock/MicroMaterialRegistry.java) and [BlockMicroMaterial](../src/main/scala/codechicken/microblock/BlockMicroMaterial.java) | -| Register generated tile traits or pass-through interfaces | [MultipartGenerator](../src/main/scala/codechicken/multipart/MultipartGenerator.java); see the [extension constraints](../JAVA_MIGRATION_HANDOFF.md#retained-compiler-constraints) before migrating custom traits | +| Register generated tile traits or pass-through interfaces | [MultipartGenerator](../src/main/scala/codechicken/multipart/MultipartGenerator.java); see [safe capability access](api/TILE_TRAIT_ACCESS.md) and the [extension constraints](../JAVA_MIGRATION_HANDOFF.md#retained-compiler-constraints) before migrating custom traits | New API examples use Java 8 language/library features. The source path `src/main/scala` also contains Java classes because of the current joint-compilation layout; it does not imply that those APIs require Scala source in a consumer. @@ -106,7 +107,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; broader extension/compilation guidance 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 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. 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 new file mode 100644 index 0000000..cd68f26 --- /dev/null +++ b/docs/api/TILE_TRAIT_ACCESS.md @@ -0,0 +1,99 @@ +# Calling generated tile capabilities from Java + +[API index](../API.md) · [Composite generation](COMPOSITE_GENERATION.md) + +Call generated tiles through `TileMultipart` or a stable public capability interface. Several dev-jar classes under +`scalatraits`, and `TileMultipartClient`, are raw inputs to FMP's transformer: Forge changes them into interfaces +before generating a concrete tile. A Java signature that compiles against those classes can still fail at runtime. + +## Why raw trait calls fail + +These consumer expressions compile against the current dev jar but are unsafe: + +```java +((TRedstoneTile) tile).openConnections(side); // javac emits invokevirtual for a class +((TSlottedTile) tile).v_partMap; // javac emits getfield +``` + +At runtime `TRedstoneTile` is an interface, so the first call throws `IncompatibleClassChangeError`. `TSlottedTile` +has generated accessor methods instead of that field, so the second throws `NoSuchFieldError`. A cast or an +`instanceof` check alone can still succeed; that does not make subsequent class-method/field bytecode valid. +Merely adding Scala to the compile classpath does not turn these raw Java classes into interface stubs. + +Already compiled consumers using the original interface/accessor descriptors remain supported. Recompiling source +against the raw Java port is a separate gate. Do not instantiate or subclass raw trait inputs in consumer code, or +call their generated `$class` helpers as a new integration strategy. Reflection is not the migration target. + +## Stable entry points + +| Need | Compile against | Contract | +| --- | --- | --- | +| Parts, slot reads, placement, lifecycle | `TileMultipart` | `jPartList()`, `partMap(slot)`, placement and documented notifications dispatch through generated overrides | +| Open redstone geometry | `IRedstoneTile` | `openConnections(side)`; capability is present when the tile hosts a redstone part | +| Offered redstone connections or masked power | `IRedstoneConnector` | `getConnectionMask(side)`, `weakPowerLevel(side, mask)`; also used by non-FMP connectors | +| Ordinary tile power queries | `TileMultipart` | `strongPowerLevel(side)`, `weakPowerLevel(side)`; preserve each method's side convention | +| Inventory or sided inventory | Minecraft `IInventory` / `ISidedInventory` | Use the interface implemented by the tile, rather than raw `JInventoryTile` or its internal caches | +| Fluid operations | Forge `IFluidHandler` | Use the interface rather than raw `TFluidHandlerTile` or `tankList` | +| A consumer-owned pass-through capability | The original ordinary Java interface | Register with `MultipartGenerator.registerPassThroughInterface`; generated calls forward to the implementing part | + +Test the capability when it is optional. Keep using the tile returned by placement/removal because adding or removing +capabilities can replace the tile instance. These interfaces do not give a snapshot, reserve a tile, or add thread +safety. Apply the owning method's lifecycle and side rules. Client-only rendering calls remain client-only even when +a stable base method exists; a headless success does not establish physical-client rendering. + +## Compiling redstone example + +[TileTraitAccessExample.java](../../src/functionalTest/java/codechicken/multipart/examples/TileTraitAccessExample.java) +uses only `TileMultipart` and `IRedstoneTile` and compiles as Java 8 without Scala on the classpath: + +```java +boolean open = TileTraitAccessExample.hasOpenConnection(tile, side, mask); +``` + +The example returns false for a null tile or absent capability. Its caller supplies a Minecraft side in 0..5 and +a mask using bits 0..3 for rotations around that side and bit 4 for the center. `openConnections` describes openings +after face/edge obstruction; `getConnectionMask` describes the connections offered by contained parts. They are not +interchangeable. The API does not validate the side or add a cache. + +ProjectRed's `transmission/redwires.scala` already knows its tile supports redstone. Its migration can change only +the cast type, preserving the surrounding mask and rotation calculation: + +```scala +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 + +`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. + +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. +Pass-through registration is sufficient when a tile should forward one interface to one part; it rejects a second +implementor through occlusion checks. Writing custom aggregation/lifecycle traits still needs the compiler's +[Java trait restrictions](../../JAVA_MIGRATION_HANDOFF.md#retained-compiler-constraints), including helper placement +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. + +## 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. + +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 59027da..b5c41f8 100644 --- a/docs/migration/HISTORY.md +++ b/docs/migration/HISTORY.md @@ -2106,3 +2106,31 @@ differences belong in the [divergence ledger](../../JAVA_MIGRATION_DIVERGENCES.m - Evidence: `run/migration-converter-reference/`. Updated the API index, plan, audits, handoff and manual integration checks. Next: source-compilation guidance and safe public access for transformed tile traits. Remaining reflection capabilities, client validation, downstream releases/adoption and final Scala removal stay open. + +### 2026-09-05 — Stable Java access to transformed tile traits + +- Committed baseline `bfe5b86` before production documentation changes. Two Forge tests execute javac-compiled raw + consumer calls: `TRedstoneTile.openConnections` fails with IncompatibleClassChangeError and `TSlottedTile.v_partMap` + field access fails with NoSuchFieldError after runtime transformation. Stable IRedstoneTile and TileMultipart calls + succeed on the same generated tiles. This characterizes a known source-compilation constraint, not a new runtime + regression in existing interface-compiled consumers. +- Added the [safe access guide](../api/TILE_TRAIT_ACCESS.md) and a Java example using the existing IRedstoneTile + interface. An additional Forge case covers all five-bit masks and null/non-redstone tiles. Corrected IRedstoneTile's + old internal label to a supported capability contract and warned on both raw trait inputs. No new interface, + reflection workaround, compile-stub artifact or production method body was needed. +- Confirmed ProjectRed's redwire query can change its cast owner to IRedstoneTile while retaining its existing mask + and rotation calculation. Added that adoption-ledger row. OpenComputers PrintPart's slot mutation is explicitly + separate: it clears array entries equal to itself, then dispatches bindPart before its own notifications. A focused + slot-refresh API is the next bounded candidate; whole-tile reload and bindPart alone are not equivalent. +- Normal and clean formatting/checkstyle/build/Forge validation passes: **573 JVM / 283 Forge** cases, zero + failures/errors/skips. **573 archived JVM / 282 archived Forge** callers pass without recompilation using their + recorded version; the archived Forge test jar is byte-identical. The example compiles with Java 8 targeting and no + Scala library against the dev artifact, and javap confirms invokeinterface through IRedstoneTile. Its bytecode has + no Scala, reflection or raw trait-class references. +- All **444** production class APIs, **17** ScalaSignature payloads and **3,761** method bodies remain unchanged. + Of **130** generated dumps, **128** are byte-identical; the TRedstoneTile/TSlottedTile helpers differ only by exact + LINENUMBER offsets of +4/+5 from Javadoc additions. No executable generation difference or new divergence exists. + Release/dev jars remain Java 8 and their five @Mod versions are checked after the final commit. +- 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/`. diff --git a/src/functionalTest/java/codechicken/multipart/examples/TileTraitAccessExample.java b/src/functionalTest/java/codechicken/multipart/examples/TileTraitAccessExample.java new file mode 100644 index 0000000..bed6a69 --- /dev/null +++ b/src/functionalTest/java/codechicken/multipart/examples/TileTraitAccessExample.java @@ -0,0 +1,15 @@ +package codechicken.multipart.examples; + +import codechicken.multipart.IRedstoneTile; +import codechicken.multipart.TileMultipart; + +/** Compiling consumer example using a stable capability instead of the raw transformed trait class. */ +public final class TileTraitAccessExample { + + private TileTraitAccessExample() {} + + /** Returns false for null/non-redstone tiles; side is 0..5 and mask uses the low five connection bits. */ + public static boolean hasOpenConnection(TileMultipart tile, int side, int mask) { + return tile instanceof IRedstoneTile && (((IRedstoneTile) tile).openConnections(side) & mask) != 0; + } +} diff --git a/src/functionalTest/java/codechicken/multipart/test/TileTraitAccessFunctionalTest.java b/src/functionalTest/java/codechicken/multipart/test/TileTraitAccessFunctionalTest.java index 18db78a..7ea91ec 100644 --- a/src/functionalTest/java/codechicken/multipart/test/TileTraitAccessFunctionalTest.java +++ b/src/functionalTest/java/codechicken/multipart/test/TileTraitAccessFunctionalTest.java @@ -1,6 +1,7 @@ package codechicken.multipart.test; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertSame; import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; @@ -15,9 +16,21 @@ import codechicken.multipart.MultipartHelper; import codechicken.multipart.TFacePart; import codechicken.multipart.TMultiPart; import codechicken.multipart.TileMultipart; +import codechicken.multipart.examples.TileTraitAccessExample; class TileTraitAccessFunctionalTest { + @Test + void javaExampleUsesGeneratedCapabilityAndHandlesAbsentCapability() { + TileMultipart tile = MultipartHelper.createTileFromParts(Arrays.asList(new PowerPart(), new CoverPart())); + for (int mask = 0; mask < 32; mask++) { + assertEquals((mask & 0x15) != 0, TileTraitAccessExample.hasOpenConnection(tile, 0, mask)); + } + TileMultipart noRedstone = MultipartHelper.createTileFromParts(Arrays.asList(new CoverPart())); + assertFalse(TileTraitAccessExample.hasOpenConnection(noRedstone, 0, 0x1F)); + assertFalse(TileTraitAccessExample.hasOpenConnection(null, 0, 0x1F)); + } + @Test void rawClassInvocationFailsWhileTheStableRedstoneInterfaceDispatches() throws Exception { TileMultipart tile = MultipartHelper.createTileFromParts(Arrays.asList(new PowerPart(), new CoverPart())); diff --git a/src/main/scala/codechicken/multipart/IRedstoneTile.java b/src/main/scala/codechicken/multipart/IRedstoneTile.java index 00f2703..211fbbc 100644 --- a/src/main/scala/codechicken/multipart/IRedstoneTile.java +++ b/src/main/scala/codechicken/multipart/IRedstoneTile.java @@ -1,7 +1,19 @@ package codechicken.multipart; -/** Internal interface for multipart tiles hosting {@link IRedstonePart}. */ +/** + * Supported redstone capability of generated multipart tiles hosting {@link IRedstonePart}. Use this stable Java + * interface for consumer calls, rather than the transformed TRedstoneTile implementation class. Not every multipart + * tile implements it; test instanceof when the caller does not already require this capability. Other connector + * implementations may implement only {@link IRedstoneConnector}. + */ public interface IRedstoneTile extends IRedstoneConnector { + /** + * Returns the geometrically open connection mask for a Minecraft side (0..5): bits 0..3 are the four rotations + * around that side and bit 4 is the center. Face and edge parts can obstruct these connections. This is not the + * mask of connections actually offered by contained redstone parts; use getConnectionMask for that query. Reads + * current part/slot state without caching or notifications. The caller supplies a valid side and uses the world's + * thread; this interface adds no validation or synchronization. + */ int openConnections(int side); } diff --git a/src/main/scala/codechicken/multipart/scalatraits/TRedstoneTile.java b/src/main/scala/codechicken/multipart/scalatraits/TRedstoneTile.java index 0947266..4a1e6e5 100644 --- a/src/main/scala/codechicken/multipart/scalatraits/TRedstoneTile.java +++ b/src/main/scala/codechicken/multipart/scalatraits/TRedstoneTile.java @@ -15,6 +15,10 @@ import scala.collection.Seq; /** * Mixin implementation for multipart redstone queries. Direct list walks avoid measured iterator/wrapper allocations; * the public part-list setter also accepts other Seq types, which need the iterator fallback. + * + *
+ * Raw compiler input: Forge transforms this class into a runtime interface. Consumer Java calls must use the stable + * {@link IRedstoneTile} / {@link TileMultipart} contracts, not method invocations compiled against this raw class. */ public class TRedstoneTile extends TileMultipart implements IRedstoneTile { diff --git a/src/main/scala/codechicken/multipart/scalatraits/TSlottedTile.java b/src/main/scala/codechicken/multipart/scalatraits/TSlottedTile.java index e6ea420..1ef7061 100644 --- a/src/main/scala/codechicken/multipart/scalatraits/TSlottedTile.java +++ b/src/main/scala/codechicken/multipart/scalatraits/TSlottedTile.java @@ -7,7 +7,12 @@ import codechicken.multipart.TMultiPart; import codechicken.multipart.TSlottedPart; import codechicken.multipart.TileMultipart; -/** Mixin implementation for slotted parts. */ +/** + * 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. + */ public class TSlottedTile extends TileMultipart { public TMultiPart[] v_partMap = new TMultiPart[27];