mirror of
https://github.com/GTNewHorizons/ForgeMultipart.git
synced 2026-11-22 13:09:44 +00:00
docs: guide stable Java tile capability access
This commit is contained in:
1 parent
bfe5b86c34
commit
9e6add4fe4
13 files changed
+240
-22
No files matched your search
+3
-1
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+21
-17
@@ -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
|
||||
|
||||
@@ -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.
|
||||
+5
-2
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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/`.
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
@@ -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()));
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
@@ -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.
|
||||
*
|
||||
* <p>
|
||||
* 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 {
|
||||
|
||||
|
||||
@@ -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];
|
||||
|
||||
Reference in new issue
Block a user