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

+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).