diff --git a/JAVA_MIGRATION.md b/JAVA_MIGRATION.md index 63e5a9a..ec49459 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 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; 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 | @@ -654,6 +654,8 @@ same-name overload there invites a silent wrong-overload bind. 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). +- [x] Document custom Java tile-trait authoring with a compiling marker/trait/capability example, registration and + state/lifecycle contracts, and generated server/client Forge coverage; [guide](docs/api/CUSTOM_TILE_TRAITS.md). - [ ] 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. @@ -785,7 +787,8 @@ UtilitiesInExcess's `extrautils:*` aliases; there is no legacy-conversion risk i both sides. - [ ] Migrate Galacticraft to direct registration in gated compatibility code; exact-signature reflection is an interim option. - [ ] Fix the UtilitiesInExcess `mat`/`material` key mismatch and its `getIdMap()` use before it enters the pack. -- [ ] Add the supported public equivalents needed by Schematica, GuideNH, Et Futurum, and Iguana as additive API. +- [ ] Add the supported public equivalents needed by Et Futurum and Iguana as additive API. Schematica and GuideNH's + identified FMP-side replacements are complete; their consumer migrations remain pending. - [x] Provide Schematica's registered-factory lookup without exposing the mutable map: `getPartFactory(String)`, with identity/missing-name checks, exact public reflection, a compiling example and the retained private field. This does not complete Schematica's consumer migration. diff --git a/JAVA_MIGRATION_ABI_INVENTORY.md b/JAVA_MIGRATION_ABI_INVENTORY.md index 58ca3e0..5765e7c 100644 --- a/JAVA_MIGRATION_ABI_INVENTORY.md +++ b/JAVA_MIGRATION_ABI_INVENTORY.md @@ -272,3 +272,12 @@ trait classes are not safe replacements for original compile-time interfaces: ex 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. + +### Custom Java tile-trait authoring + +`MultipartGenerator.registerTrait(String, String)` and its side-specific overload now document their existing Java +trait path, registration timing and first-mapping behavior. The [four-type example](docs/api/CUSTOM_TILE_TRAITS.md) +separates the part marker, stable consumer capability, transformed input and access helper, and runs through actual +server/client composite generation. This adds no production class, method, descriptor or behavior. The example remains +functional-test content. No supplied consumer directly registers a custom multipart tile trait; existing pass-through +and external Scala-trait contracts remain supported and their release/adoption gates are unchanged. diff --git a/JAVA_MIGRATION_CONSUMER_AUDIT.md b/JAVA_MIGRATION_CONSUMER_AUDIT.md index 18e5d61..f7d3800 100644 --- a/JAVA_MIGRATION_CONSUMER_AUDIT.md +++ b/JAVA_MIGRATION_CONSUMER_AUDIT.md @@ -770,4 +770,17 @@ calculation. OpenComputers can replace its slot-array cast/loop plus `bindPart` 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. +`run/migration-slot-refresh-reference/`; physical-client checks remain. + +## Custom Java tile-trait authoring + +The [authoring guide](docs/api/CUSTOM_TILE_TRAITS.md) now covers the existing name-based +`MultipartGenerator.registerTrait` path with a top-level Java input, separate marker and stable capability interfaces, +an ordinary helper and no reflection. The Forge example exercises both side selections, transformed dispatch, binding, +exact tile reuse and generated-class caching. It owns no state and derives its aggregate from the live part list; +stateful extensions retain the documented copy, persistence, synchronization and lifecycle responsibilities. + +The supplied consumer source audit found no direct custom multipart tile-trait registration. Consumers currently use +built-in traits, generated pass-through interfaces, or ProjectRed's separate microblock-trait registration path. +Accordingly this is supported extension coverage, not a consumer migration or a basis for retiring any current binary +contract. Evidence: `run/migration-custom-tile-trait-reference/`. diff --git a/JAVA_MIGRATION_HANDOFF.md b/JAVA_MIGRATION_HANDOFF.md index b8da660..1178708 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 286 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **225 Java +**573 plain-JVM tests and 287 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,18 +32,15 @@ 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 `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. +Latest API work documents [custom Java tile-trait authoring](docs/api/CUSTOM_TILE_TRAITS.md) over the existing +`MultipartGenerator.registerTrait` overloads. Baseline commit `d98e48f` adds a compiling four-type example and real +Forge registration. It separates the requesting part marker, stable caller capability, transformed input and ordinary +helper, then verifies generated server/client tiles, aggregation, binding, exact reuse and class caching. The example +uses derived state, so it needs no new cache, NBT or packet contract. No production method body or descriptor changed. +All 573 JVM / 287 Forge tests pass, including the frozen baseline callers. All 444 classes, 17 ScalaSignature payloads, +3,763 packaged methods and 134 generated dumps retain their executable shape. Evidence: +`run/migration-custom-tile-trait-reference/`. No supplied consumer directly registers a custom multipart tile trait; +this is supported extension coverage, not consumer adoption. 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 @@ -67,16 +64,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 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. +The next bounded candidate is a supported orientation customization API for Et Futurum, replacing its mutation of +`ButtonPart.metaSideMap` and `sideMetaMap`, with exact mapping and placement coverage. 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, the Java illuminated extension example and -slot refresh. Remaining work includes 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, slot +refresh and custom Java tile-trait authoring. Remaining work includes 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,8 +349,9 @@ 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, ordinary base/interface calls and slot refresh; custom tile-trait authoring remains open. The server - pass-through fixture does not cover client exclusion. + redstone, ordinary base/interface calls and slot refresh; [custom authoring guidance](docs/api/CUSTOM_TILE_TRAITS.md) + covers marker registration, stable capabilities and transformer constraints. 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/docs/API.md b/docs/API.md index ae0b9df..dcb6730 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) | +| Add aggregate or lifecycle behavior to generated multipart tiles | `registerTrait(marker, trait)` — [custom Java tile traits, stable capabilities and transformer constraints](api/CUSTOM_TILE_TRAITS.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) | @@ -55,7 +56,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 [safe capability access](api/TILE_TRAIT_ACCESS.md) and 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 [custom tile-trait authoring](api/CUSTOM_TILE_TRAITS.md) and [safe capability access](api/TILE_TRAIT_ACCESS.md) | 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. @@ -113,8 +114,9 @@ An [illuminated Java microblock extension](api/MICROBLOCK_EXTENSIONS.md) now cov 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, 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. +and OpenComputers slot refresh. [Custom Java tile-trait authoring](api/CUSTOM_TILE_TRAITS.md) covers registration, +stable capabilities, lifecycle/state rules and transformer constraints with generated Forge coverage. 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/CUSTOM_TILE_TRAITS.md b/docs/api/CUSTOM_TILE_TRAITS.md new file mode 100644 index 0000000..887f990 --- /dev/null +++ b/docs/api/CUSTOM_TILE_TRAITS.md @@ -0,0 +1,143 @@ +# Custom generated tile traits from Java + +[API index](../API.md) · [Stable capability access](TILE_TRAIT_ACCESS.md) · [Composite generation](COMPOSITE_GENERATION.md) + +A custom tile trait adds behavior to every generated `TileMultipart` that contains a part implementing a chosen marker +interface. Use it for tile-wide aggregation or lifecycle behavior. If the tile only needs to expose one interface and +forward its methods to one implementing part, use `MultipartGenerator.registerPassThroughInterface` instead; FMP +already generates that forwarding and rejects a second implementor through occlusion. + +The complete compiling example has four small types: + +- [CustomTileTraitPart.java](../../src/functionalTest/java/codechicken/multipart/examples/CustomTileTraitPart.java) is + the marker and contribution contract implemented by requesting parts. +- [CustomTileTraitCapability.java](../../src/functionalTest/java/codechicken/multipart/examples/CustomTileTraitCapability.java) + is the stable interface used by callers. +- [CustomTileTrait.java](../../src/functionalTest/java/codechicken/multipart/examples/CustomTileTrait.java) is the raw + input class FMP transforms, plus its ordinary helper. +- [CustomTileTraitExample.java](../../src/functionalTest/java/codechicken/multipart/examples/CustomTileTraitExample.java) + registers and accesses the capability. + +These files live in the functional-test source set and are examples, not classes shipped in the production artifact. + +## Registration and selection + +Register during common mod initialization, before FMP first inspects any part class implementing the marker: + +```java +private static final String TRAIT = "example.multipart.ContributionTileTrait"; + +public static void register() { + MultipartGenerator.registerTrait(ContributionPart.class.getName(), TRAIT); +} +``` + +Keep the trait name as a string literal. `ContributionTileTrait.class.getName()` loads the untransformed class before +FMP can rewrite it. The marker is an ordinary interface, so its class literal is safe. Names may contain dots or +slashes. + +The two-argument overload installs the same trait on client and server generated tiles. Use +`registerTrait(marker, clientTrait, serverTrait)` when the sides differ; either trait name may be null. The order is +client first, then server. Register a parent Java trait before a child trait. + +Registration is global for the running game. A second mapping for the same marker and side logs an error and leaves +the first mapping active. Registration loads and validates the trait bytes, so missing or invalid traits fail at that +point. It does not register a part type, construct a tile, load parts or bind ownership. + +When FMP first sees a concrete part class, it records every registered marker that class implements. Composite classes +are then cached by the exact selected trait set and side. Registering after that inspection is too late for the cached +part class. + +## Trait and stable capability + +The transformed input is a top-level class extending `TileMultipart`. It may be abstract and needs a no-argument +constructor. Put the API that other code calls on a separate ordinary interface: + +```java +public interface ContributionTileCapability { + int totalContribution(); +} + +public abstract class ContributionTileTrait extends TileMultipart + implements ContributionTileCapability { + + @Override + public int totalContribution() { + return ContributionTileTraitAccess.total(this); + } +} +``` + +At runtime FMP rewrites `ContributionTileTrait` into an interface and copies its method bodies into a generated helper. +Calling through the untransformed class can therefore emit invalid class method or field bytecode. Callers use the +stable capability instead: + +```java +int total = tile instanceof ContributionTileCapability + ? ((ContributionTileCapability) tile).totalContribution() + : 0; +``` + +Keep the absent-capability behavior in the caller-facing helper. The example returns zero for null and ordinary tiles. +Adding or removing a requesting part may replace the tile with another generated class, so retain the tile returned by +FMP's normal placement and removal APIs. + +## Transformer-safe method bodies + +The current Java trait transformer supports the example's small delegating method. Keep substantial work in an +ordinary top-level helper outside the transformed class: + +```java +final class ContributionTileTraitAccess { + static int total(Object receiver) { + TileMultipart tile = (TileMultipart) receiver; + int total = 0; + for (TMultiPart part : tile.jPartList()) { + if (part instanceof ContributionPart) { + total += ((ContributionPart) part).contribution(); + } + } + return total; + } +} +``` + +The helper parameter must be `Object`. If it is typed as the raw trait, javac can remove the cast to `TileMultipart`; +after transformation the verifier then sees an interface receiver where the bytecode expected a class. The helper is +also where inherited field/method access and field access on method arguments belong, because the transformer can +otherwise mistake those reads for trait-owned state. + +Keep the transformed class free of nested, local and anonymous classes, lambdas and compiler-generated inner-class +helpers. Primitive-array allocation is also unsupported in a trait body. Put those operations in the ordinary helper. +Client-only members may use Forge's `@SideOnly(Side.CLIENT)`; FMP removes opposite-side members before collecting the +trait. Test the resulting generated class on each selected side. + +## State and lifecycle + +Prefer derived behavior when it is cheap enough. The example sums the current `jPartList()` and owns no tile state, +which avoids NBT, packet, invalidation and transition rules. + +If a trait declares fields, FMP generates `copyFrom(TileMultipart)` when the trait does not declare one. It copies each +non-transient field only when the source tile has the same trait; transient fields are excluded. Persistent or +client-synchronized state still needs explicit NBT/description handling. A custom `copyFrom` replaces the generated +field copier, so it must preserve the normal superclass chain and define behavior for sources without the trait. + +Cached aggregates must also follow every lifecycle path that can change them. Override the relevant `bindPart`, +`partRemoved` and `clearParts` hooks, call `super` in the established order, and cover tile promotion/demotion and +loading with a focused Forge test. Do not use a custom cache unless measurement shows the derived scan is too costly. + +`MultipartGenerator.generateCompositeTile` only chooses or constructs the empty composite class. If using that advanced +API directly, prepare world/position or saved state and then call `loadPartList`; ordinary placement performs the +required transition itself. See the [staged generation guide](COMPOSITE_GENERATION.md) for ownership and failure rules. + +## Validation and adoption + +[CustomTileTraitFunctionalTest.java](../../src/functionalTest/java/codechicken/multipart/test/CustomTileTraitFunctionalTest.java) +registers the real example during Forge initialization. It checks server and client selections, transformed capability +dispatch, mixed-part aggregation, part binding, exact tile reuse and generated-class caching. The four example sources +also compile as Java 8 against the packaged dev artifact without Scala. + +No supplied active consumer directly registers a custom `MultipartGenerator` tile trait; their current generated-tile +extensions use built-in traits or pass-through interfaces. This guide establishes the supported Java extension pattern +and does not count any consumer as migrated. Existing Scala trait inputs and binary contracts remain supported until +their release and target-pack adoption gates pass. diff --git a/docs/api/TILE_TRAIT_ACCESS.md b/docs/api/TILE_TRAIT_ACCESS.md index 271a575..ad7d561 100644 --- a/docs/api/TILE_TRAIT_ACCESS.md +++ b/docs/api/TILE_TRAIT_ACCESS.md @@ -101,16 +101,13 @@ capabilities do not append such caches; it is not a general refresh for inventor `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. -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. +stable base for existing tile hooks. The [custom tile-trait guide](CUSTOM_TILE_TRAITS.md) provides the complete +registration, helper, state/lifecycle and access pattern. Pass-through registration remains the smaller choice when +a tile should only forward one interface to one implementing part. 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. +machinery. Other audited private/reflection contracts remain open. ## Validation @@ -122,5 +119,6 @@ entry with the frozen consumer sequence, including equality, current-mask rebind 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. +This is consumer source-access coverage. It does not validate physical-client rendering or establish that any consumer +has released and adopted a migration. Generated custom tile traits have separate both-side coverage in the +[authoring guide](CUSTOM_TILE_TRAITS.md#validation-and-adoption). diff --git a/docs/migration/HISTORY.md b/docs/migration/HISTORY.md index d5bb7e0..7073ad5 100644 --- a/docs/migration/HISTORY.md +++ b/docs/migration/HISTORY.md @@ -2157,3 +2157,24 @@ differences belong in the [divergence ledger](../../JAVA_MIGRATION_DIVERGENCES.m 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. + +### 2026-09-08 — Custom Java tile-trait authoring + +- Committed baseline `d98e48f` before production documentation changes. Its Forge example registers a top-level Java + trait by name during initialization and verifies server/client selection, stable capability dispatch, mixed-part + aggregation, part binding, exact tile reuse and generated-class caching. +- Added the [custom tile-trait guide](../api/CUSTOM_TILE_TRAITS.md) and expanded both `registerTrait` Javadocs. The + four-type pattern separates the requesting marker, consumer capability, transformed input and ordinary helper. It + records class-loading order, side-specific registration, first-mapping behavior, state/lifecycle ownership and the + current transformer constraints. The example uses a derived aggregate instead of adding a cache. +- No supplied active consumer directly registers a custom multipart tile trait. Current consumers use built-in traits, + pass-through interfaces or ProjectRed's distinct microblock-trait path. Reference checkouts remain unchanged and no + migration/release/adoption is claimed. +- Normal and clean formatting/checkstyle/build/Forge validation passes with **573 JVM / 287 Forge** cases, zero + failures/errors/skips. All **573 archived JVM / 287 archived Forge** callers pass. The example targets Java 8 against + the dev artifact without Scala or reflection and calls only the stable capability/base API. +- All **444** production classes, **17** ScalaSignature payloads and **3,763** packaged methods remain. All **134** + generated dumps retain executable equivalence; only source-line metadata moves in the facade class. Evidence: + `run/migration-custom-tile-trait-reference/`. +- Next bounded task: expose supported button-orientation customization for Et Futurum, then cover Iguana's saw-strength + customization. Consumer adoption, physical-client/full-pack checks and measured performance remain separate gates. diff --git a/src/main/scala/codechicken/multipart/MultipartGenerator.java b/src/main/scala/codechicken/multipart/MultipartGenerator.java index e5bfce0..6d9d070 100644 --- a/src/main/scala/codechicken/multipart/MultipartGenerator.java +++ b/src/main/scala/codechicken/multipart/MultipartGenerator.java @@ -57,12 +57,38 @@ public final class MultipartGenerator { MultipartGenerator$.MODULE$.silentAddTile(world, pos, tile); } - /** Registers the same tile trait for both sides. */ + /** + * Registers a marker interface implemented by parts with the same generated tile trait on both sides. Names may use + * dots or slashes. Call during common mod initialization, before FMP first inspects an implementing part class. + * + *

+ * For a Java source trait, pass its binary name as a string instead of loading its class. The trait is a top-level + * class extending {@link TileMultipart}, possibly abstract, with a no-argument constructor; FMP rewrites it into a + * runtime interface. Consumer-callable methods belong on a separate ordinary interface implemented by the trait. Do + * not instantiate or invoke the raw trait class from consumer code. + * + *

+ * Registration only associates the marker with generated behavior. It does not construct a tile, load or bind + * parts, or register a part factory. Repeating a marker registration for a side logs an error and retains the first + * mapping. See {@code docs/api/CUSTOM_TILE_TRAITS.md} for the compiling pattern and transformer constraints. + * + * @param marker binary name of the ordinary interface implemented by requesting parts + * @param trait binary name of the generated tile trait + */ public static void registerTrait(String marker, String trait) { MultipartGenerator$.MODULE$.registerTrait(marker, trait); } - /** Registers side-specific tile traits; either trait may be null to exclude that side. */ + /** + * Registers side-specific generated tile traits for a part marker. This has the same timing, class-loading and + * trait authoring contract as {@link #registerTrait(String, String)}. Either trait may be null to omit the + * capability from that side; the argument order is client, then server. Register parent Java traits before child + * traits. + * + * @param marker binary name of the ordinary interface implemented by requesting parts + * @param clientTrait client trait binary name, or null for none + * @param serverTrait server trait binary name, or null for none + */ public static void registerTrait(String marker, String clientTrait, String serverTrait) { MultipartGenerator$.MODULE$.registerTrait(marker, clientTrait, serverTrait); }