docs: cover custom Java tile traits

This commit is contained in:
Algent committed 2026-09-08 23:41:17 +02:00
1 parent d98e48ff03
commit bd8e473c7f
9 files changed
+250 -37

No files matched your search

+5 -2
View File
@@ -64,7 +64,7 @@ The phase checklists include recurring verification rules, historical work and c
| Workstream | Remaining deliverables | Gate |
| --- | --- | --- |
| Complete the supported Java surface | Physical-client validation of the documented illuminated microblock example; custom tile-trait authoring and broader lifecycle guidance; supported 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.
+9
View File
@@ -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.
+14 -1
View File
@@ -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/`.
+18 -20
View File
@@ -17,7 +17,7 @@ migration checkout; `codex/tile-compatibility-fixes` was deleted after its fixes
## Current state and next target
**573 plain-JVM tests and 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
+5 -3
View File
@@ -27,6 +27,7 @@ Existing reflective binaries remain supported until consumer release and pack ad
| Read a microblock material's block and metadata | `BlockMicroMaterial.block()`, `meta()` — [typed GuideNH query, identity and overrides](api/MATERIAL_ACCESS.md) |
| Create a microblock with the requested material and side | `MicroblockGenerator.create(MicroblockClass, int, boolean)` — [construction, material traits and GuideNH migration](api/MICROBLOCK_CREATION.md) |
| Call generated tile capabilities from Java | `TileMultipart`, `IRedstoneTile` and ordinary interfaces — [safe compilation and raw-trait pitfalls](api/TILE_TRAIT_ACCESS.md) |
| 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.
+143
View File
@@ -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.
+7 -9
View File
@@ -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).
+21
View File
@@ -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.
@@ -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.
*
* <p>
* 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.
*
* <p>
* 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);
}