mirror of
https://github.com/GTNewHorizons/ForgeMultipart.git
synced 2026-11-18 19:39:19 +00:00
docs: cover custom Java tile traits
This commit is contained in:
1 parent
d98e48ff03
commit
bd8e473c7f
9 files changed
+250
-37
No files matched your search
+5
-2
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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
@@ -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
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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).
|
||||
@@ -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);
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user