docs: define direct Java material access

This commit is contained in:
Algent committed 2026-09-05 14:58:24 +02:00
1 parent 079739ea80
commit 37d5ea98f6
13 files changed
+311 -31

No files matched your search

+14 -4
View File
@@ -211,6 +211,16 @@ implementation. Avoid two independently maintained implementations. Where an old
preserve its virtual dispatch while it remains supported: moving an algorithm behind a new Java method must not
bypass old subclass overrides. Define and test the dispatch path for each such pair, without recursive forwarding.
### Direct consumer access
Supported integration tasks must be possible through direct, statically typed public calls, without reflection,
private-field accessor mixins or Scala companion lookup. Reuse existing methods first; expose a missing capability
only when an audited consumer needs it. Do not turn unrelated implementation details into public contracts.
Optional integrations should isolate FMP-typed code behind mod-presence and supported-version checks; optionality
alone is not a reason to require reflection. Validate both absent and present mod loading in consumer adoption.
Existing reflective integrations remain supported during migration. Reflection snippets in the guides describe
legacy interoperability options, not the intended completion point; consumer patches should use the typed examples.
### Consumer API milestone and retained Scala stopping point
The first release milestone is **a complete, documented Java API that every supported GTNH integration can migrate
@@ -684,15 +694,15 @@ does not close a row, and scans must distinguish a consumer's own Scala code fro
| --- | --- | --- | --- |
| ProjectRed | Runtime Scala-signature decoding and external trait registration, reached through `MicroblockGenerator.registerTrait(classOf[LightMicroblock])` | Rewrite the ~60-line `LightMicroblock` trait as a Java mixin registered through the `registerJavaTrait` path | FMP compiler prerequisites complete; consumer rewrite and release remain |
| Schematica | Private Scala-mangled field `codechicken$multipart$MultiPartRegistry$$typeMap`, cast to `scala.collection.mutable.Map` | `MultiPartRegistry.getPartFactory(String)` is implemented; [guide and example](docs/api/FACTORY_LOOKUP.md). Schematica replaces map/Option lookup with the public method and retains its microblock creation/rejection policy | FMP lookup ready; consumer patch/release/adoption pending |
| GuideNH | Companion `MultipartGenerator$.MODULE$.generateCompositeTile` and `MicroblockGenerator$.create`; `partList_$eq(scala.collection.Seq)`; mixin into private `BlockMicroMaterial.block` and `.meta` | Static Java tile generation/loading and existing microblock creation are documented/tested; [microblock guide](docs/api/MICROBLOCK_CREATION.md). Validate public material accessors next | Creation/loading ready; private material access and consumer adoption pending |
| GuideNH | Companion `MultipartGenerator$.MODULE$.generateCompositeTile` and `MicroblockGenerator$.create`; `partList_$eq(scala.collection.Seq)`; mixin into private `BlockMicroMaterial.block` and `.meta` | Direct Java tile generation/loading, microblock creation and existing `block()` / `meta()` access are documented/tested; [typed material query](docs/api/MATERIAL_ACCESS.md). Remove reflection/accessor mixins when migrating | These FMP paths ready; broader consumer migration/release/adoption pending |
| Et Futurum Requiem | Mutable static `int[] ButtonPart.metaSideMap` and `sideMetaMap` must stay public and mutable | FMP exposes a supported orientation-override API; Et Futurum uses it | After step 1 |
| IguanaTweaksTConstruct | Private `ItemSaw.harvestLevel` field name and type | FMP exposes a supported harvest-level setter; Iguana uses it | After step 1 |
| Galacticraft | Selects the first public method named `registerMaterial` without checking its signature, so FMP cannot add any overload of that name | Make the reflection check the parameter types | Immediately; independent of the port |
| Galacticraft | Selects the first public method named `registerMaterial` without checking its signature, so FMP cannot add any overload of that name | Call `registerMaterial` directly from gated compatibility code; exact-signature reflection is an interim hardening option | Existing public API; consumer migration can start |
| UtilitiesInExcess | `MicroMaterialRegistry.getIdMap(): scala.Tuple2[]` | Both call sites read only the name, so `materialCount()` from Phase 9.1 plus the existing `materialName(int)` covers them; no material object is needed | After Phase 9.1, before it enters the pack |
| UtilitiesInExcess | Not an FMP constraint, but a shipping hazard: the server factory reads NBT key `material` while `MaterialBasedPart.save` writes `mat` | Fix on the UtilitiesInExcess side; FMP must not special-case it | Immediately; no FMP change needed |
Galacticraft's reflection signature check needs no FMP change. Its wrong-overload failure is silent because the
reflection sits inside an empty `catch (Exception)`.
Galacticraft needs no FMP change for direct registration. As interim hardening, its reflection can check exact
parameter types; the current wrong-overload failure is silent because it sits inside an empty `catch (Exception)`.
ProjectRed's `LightMicroblock` is the audited external constraint on retiring runtime Scala-signature decoding.
Its Java rewrite removes that external dependency only after the updated consumer is released into the pack;
+7 -1
View File
@@ -197,7 +197,7 @@ method on it. So for most entries the companion is a fallback. The exceptions be
| `TileMultipart` | `partList()`, `partList_$eq(scala.collection.Seq)`, `loadParts(...)`, `notifyTileChange()`, `markRender()` | instance |
| `Microblock` | `microClass()`, `material()`, `shape()` | instance |
| `TMultiPart` | `getDrops()` | instance |
| `IMicroMaterial` | `block()`, `meta()` | instance |
| `BlockMicroMaterial` | `block()`, `meta()` | instance; absent from general `IMicroMaterial` |
Types used only for `isInstanceOf`: `BlockMultipart`, `TileMultipart`, `TileMultipartClient`, `Microblock`,
`MicroblockClient`, `BlockMicroMaterial`.
@@ -233,3 +233,9 @@ Types used only for `isInstanceOf`: `BlockMultipart`, `TileMultipart`, `TileMult
`MultipartHelper$` is retained on the strength of the fallback path alone: the static is found first today, so the
companion is never reached in practice. That is a weaker justification than the two "companion only" entries above,
but the cost of keeping a four-method forwarder is negligible against a silent break.
GuideNH's private `BlockMicroMaterial.block: Block` and `meta: int` fields remain unchanged for its accessor mixin.
Existing public virtual `block()` / `meta()` now have a [typed query guide](docs/api/MATERIAL_ACCESS.md) and regression
coverage; no descriptor or method body changed. The mixin reads constructor fields whereas direct calls honor
subclass overrides, as the old reflective fallback already did. Remove the consumer's mixin only when adopting the
typed query; FMP field removal still waits for released-consumer adoption.
+12 -2
View File
@@ -515,10 +515,11 @@ tied to a released minimum dependency version. Unlisted contracts remain governe
| `TileMultipart.partList(): scala.collection.Seq` | AE2 `87f2b3817c2a`: `FMPPlacementHelper.getPart` and `removePart` | Iterate `jPartList()`; retain last-match lookup and removal/break behavior | Source patch and release pending | No migrated pack version verified; retain the getter |
| `TileMultipart.partList(): scala.collection.Seq` | Extra Utilities 1.2.12: multipart renderer iterators | Iterate `jPartList()` without adding detached-part filtering | Retirement/replacement pending | Confirm absence or migration in the target pack before retiring the getter |
| `TileMultipart.partList(): scala.collection.Seq` plus reflective getter/setter/loading | GuideNH `7d8fb44e77b9`: `Ae2ForgeMultipartBridge`, `ForgeMultipartHelpers` | `jPartList()` for reads, `setPartList(List)` for staging, `loadPartList(Collection)` for binding/cache reconstruction | Source patch and release pending; preserve world/position setup and following tile/render notifications | Retain the legacy getter/setter/loader until adoption; companion-only generator migration is separate |
| `TileMultipart.loadParts(scala.collection.Iterable)` exact reflection | Schematica `3b03ee937953`: `nbt.ForgeMultipart` | Reflect `loadPartList(Collection.class)` and pass its existing Java part list directly | Source patch and release pending; registry lookup and Java tile generation available separately | No migrated pack version verified; retain the Scala loader descriptor |
| Private `MultiPartRegistry$` Scala `typeMap` field and `Map.get` / `Option` | Schematica `3b03ee937953`: `nbt.ForgeMultipart.init` and `createPart` | Reflect public static `MultiPartRegistry.getPartFactory(String.class)`; keep material lookup, `MicroblockClass.create(client, materialId)` and whole-preview rejection | Source patch/release pending; lookup and Java tile generation implemented | No migrated pack version verified; retain the exact private live Scala-map field |
| `TileMultipart.loadParts(scala.collection.Iterable)` exact reflection | Schematica `3b03ee937953`: `nbt.ForgeMultipart` | Call `loadPartList(parts)` directly with its existing Java part list | Source patch and release pending; registry lookup and Java tile generation available separately | No migrated pack version verified; retain the Scala loader descriptor |
| Private `MultiPartRegistry$` Scala `typeMap` field and `Map.get` / `Option` | Schematica `3b03ee937953`: `nbt.ForgeMultipart.init` and `createPart` | Call public static `MultiPartRegistry.getPartFactory(partID)` directly; keep material lookup, `MicroblockClass.create(client, materialId)` and whole-preview rejection | Source patch/release pending; lookup and Java tile generation implemented | No migrated pack version verified; retain the exact private live Scala-map field |
| `MultipartGenerator$.generateCompositeTile(TileEntity, scala.collection.Iterable, boolean)` | Schematica `3b03ee937953` exact reflection; GuideNH `7d8fb44e77b9` static-first assignability matcher | Static `MultipartGenerator.generateCompositeTile(TileEntity, java.lang.Iterable, boolean)` with Java parts; retain subsequent state setup/loading | Source patches/releases pending; preserve client part construction, candidate-reuse branch and notification order | No migrated pack version verified; retain the companion and Scala descriptor |
| `MicroblockGenerator$.create(MicroblockClass, int, boolean)` exact reflection and private shape copy | GuideNH `7d8fb44e77b9`: `getMicroblockGeneratorCreate`, `promoteMicroblockToClient` | Existing static `MicroblockGenerator.create` with the same parameter types/order; recreate family/material and restore encoded shape through public API | Source patch/release pending; guide/example tested on server, physical client and custom shape-setter overrides require adoption checks | No migrated pack version verified; retain companion singleton and exact descriptor |
| Private `BlockMicroMaterial.block` / `meta` accessor mixin and reflective material query | GuideNH `7d8fb44e77b9`: `AccessorBlockMicroMaterial`, `resolvePrimaryMicroblockId` | Direct `jPartList()`, `Microblock.material()`, `getMaterial(int)`, `BlockMicroMaterial.block()` / `meta()`; [typed example](docs/api/MATERIAL_ACCESS.md) | Source patch/release pending; remove mixin, retain export filtering/failure policy, validate getter overrides and optional loading | No migrated pack version verified; retain private fields |
| `NormalOcclusionTest$.apply(Traversable, Traversable)` | OpenComputers `2c00f79be24b`: `common.block.Cable.canConnectFromSideFMP`, `server.network.Network.canConnectFromSideFMP` | `NormalOcclusionTest.testBoxes(ownBounds.asJava, otherBounds)`; `otherBounds` already comes from Java `getOcclusionBoxes()` | Source patch and release pending; retain side/color/face filtering | No migrated pack version verified; retain the companion and descriptor |
| `NormalOcclusionTest$.apply(Traversable, Traversable)` | ForgeRelocationFMP `49a810b8c63b`: `FramePart.occlusionTest` | `NormalOcclusionTest.testBoxes(boxes.asJava, getOcclusionBoxes)`; retain combined normal/partial/collision boxes and caller order | Source patch and release pending; preserve temporary face bounds and replacement protocol | No migrated pack version verified; retain the companion and descriptor |
@@ -646,6 +647,15 @@ from the unchanged archived Forge mod pass. Physical-client creation/GPU preview
server strips the client's factory method. All 386 pack ABI/reflection rows remain across 27 consumers, and reference
checkouts are unchanged. Evidence: `run/migration-microblock-creation-reference/`.
GuideNH's block/meta query now has a [typed example and contract](docs/api/MATERIAL_ACCESS.md) using existing public
methods throughout. The baseline pins constructor identity/raw metadata and the distinction between virtual getters
and raw mixin fields. Forge exercises first-usable-part ordering, non-block/invalid-block filtering, registry aliases,
metadata formatting and failure propagation. Getter overrides are intentional public semantics; the old mixin bypasses
them while its reflective fallback respects them. No new accessors or production behavior changes were needed.
Consumer migrations should use direct calls, including optional integrations gated on presence/version. Reflection
snippets remain legacy interoperability options only. Supplied consumer checkouts remain reference-only.
Evidence: `run/migration-material-access-reference/`; archived validation retains 570 JVM and 270 Forge cases.
## Practical priority for the current branch
1. Keep the existing `+678` ABI fixture as the exact binary floor and correct failures before source cleanup.
+24 -19
View File
@@ -17,7 +17,7 @@ migration checkout; `codex/tile-compatibility-fixes` was deleted after its fixes
## Current state and next target
**568 plain-JVM tests and 269 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **225 Java
**570 plain-JVM tests and 272 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **225 Java
files and 9 Scala files / 747 nonblank Scala lines**. The packaged inventory has 444 classes.
Review follow-up: restored packet-scheduler callback mutation behavior with the original Scala hash-map traversal,
@@ -32,15 +32,21 @@ use, but no override triggering these three regressions was found. All 443 class
payloads and 116 generated dumps are retained. The agreed next milestone is the documented consumer-facing Java API,
followed by consumer release/adoption and final Scala removal; see the plan's API migration design and Phases 8–10.
Latest API work documents and validates existing `MicroblockGenerator.create(MicroblockClass, int, boolean)` for
GuideNH. Two Forge baseline cases were committed first as `5d572ef`; two more test the compiling recreation example,
all encoded shape bytes and capturing source state before material callbacks. Static/companion reflection, fresh
parts, caller-owned shape/NBT, material trait injection and callback failure/scratch reuse are covered. No production
API or behavior changed: all 444 class APIs, 17 ScalaSignature payloads, 3,761 method bodies and 116 generated dumps
remain, with no additions/deprecations. All 568 archived JVM tests and the unchanged archived Forge mod's 267 cases
pass. The example compiles without Scala. Physical-client creation/previews and custom shape-setter override checks
remain consumer validation gates; GuideNH's old private shape write bypassed the public setter's virtual dispatch.
Evidence: `run/migration-microblock-creation-reference/`; [guide](docs/api/MICROBLOCK_CREATION.md).
Latest API work documents GuideNH's material query through direct `jPartList()`, `Microblock.material()`,
`MicroMaterialRegistry.getMaterial(int)` and existing `BlockMicroMaterial.block()` / `meta()` calls. Two JVM and one
Forge baseline cases were committed first as `079739e`; two Forge example cases cover ordering/filtering, metadata
formatting, registry aliases, getter overrides and failure propagation. No production API or behavior changed:
all 444 class APIs, 17 ScalaSignature payloads and 3,761 method bodies remain. Of 116 generated dumps, 114 match
exactly; the face/post pair matches after swapping only allocation-order class names. All 570 archived
JVM tests and the unchanged archived Forge mod's 270 cases pass. The example compiles without Scala or reflection.
The old private-field mixin bypasses virtual getters; the supported API honors them, like GuideNH's reflective
fallback. Consumer patches, custom-material exports and absent/present optional loading remain adoption gates.
Evidence: `run/migration-material-access-reference/`; [guide](docs/api/MATERIAL_ACCESS.md).
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
interoperability options, not a reason to leave consumers depending on reflection. Add purposeful missing capabilities
where needed, without exposing unrelated internals. Keep existing private fields/bridges until release and adoption.
Naming correction: the planned `loadParts(Collection)` overload made javac require `scala.collection.Iterable` even
for Java arguments. The distinct `loadPartList` name allows compilation without Scala on the example's classpath.
@@ -59,17 +65,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 GuideNH's private `BlockMicroMaterial.block` / `meta` access. Trace its accessor mixin
and reflection fallbacks, then document/test the existing public material accessors wherever they cover the same
contract. Preserve private fields until consumer release/adoption and keep virtual-accessor behavior explicit.
The representative external Java extension and internal-boundary documentation remain separate work.
The next bounded candidate is Phase 9.2: recheck the audited internal-hook caller inventory, document those hooks
as internal, and document externally used `bindPart` / `internalPartChange` as supported API. Keep descriptors and
behavior unchanged and preserve explicit legacy override contracts. The representative external Java microblock
extension remains separate work; use it before claiming complete consumer extension coverage.
Progress: all ten Phase 9.1 table rows now have implemented/documented Java replacements, plus the separate Schematica
registry lookup, staged Java tile generation and existing Java microblock-creation guidance. Remaining work includes
private material/reflection guidance, extension examples and internal-boundary
documentation. Then consumer
patches, releases and pack adoption must precede final Scala removal and client/pack release validation; it is not
a percentage of the whole migration.
registry lookup, staged Java tile generation, microblock-creation guidance and typed GuideNH material query. Remaining
work includes internal-boundary documentation, converter/extension guidance and other audited reflection use cases.
Then consumer patches, releases and pack adoption must precede final Scala removal and client/pack release validation;
it is not a percentage of the whole migration.
A separate [Phase 4b performance pass](JAVA_MIGRATION.md#phase-4b--measured-performance-pass) is planned once the API
and representative extension workloads are stable, alongside consumer migration. Use fresh realistic profiles and
+9
View File
@@ -8,6 +8,14 @@ Consumers can use the Java surface without importing Scala types. FMP still reta
compatibility bridges, and some extension contracts still need migration. A Scala-authored mod can adopt the Java API
without converting the rest of its code to Java.
## Direct calls and optional integration
The intended consumer API uses direct typed public calls, without reflection, private-field mixins or Scala
companion lookup. Reuse existing entry points where they cover the task. For optional support, isolate FMP-typed
code in a compatibility class loaded only after mod-presence and supported-version checks; test absent and present
mod loading. Reflection snippets in older guides are legacy interoperability options, not the migration target.
Existing reflective binaries remain supported until consumer release and pack adoption.
## Choose a guide
| Task | API and guide |
@@ -15,6 +23,7 @@ without converting the rest of its code to Java.
| Register part factories during mod initialization | `registerPartFactory(IPartFactory2, String...)` — [factory timing, payload ownership and migration](api/PART_REGISTRATION.md) |
| Find the factory registered for a part type | `getPartFactory(String)` — [lookup ownership and Schematica reflection migration](api/FACTORY_LOOKUP.md) |
| Enumerate microblock materials by numeric ID | `materialCount()`, `materialName(int)`, `getMaterial(int)` — [material enumeration](api/MATERIAL_ENUMERATION.md) |
| Read a microblock material's block and metadata | `BlockMicroMaterial.block()`, `meta()` — [typed GuideNH query, identity and overrides](api/MATERIAL_ACCESS.md) |
| Create a microblock with the requested material and side | `MicroblockGenerator.create(MicroblockClass, int, boolean)` — [construction, material traits and GuideNH migration](api/MICROBLOCK_CREATION.md) |
| Read/index/search a tile's parts | `jPartList()` — [part collection ownership and order](api/PART_TRAVERSAL.md#collection-ownership-and-ordering) |
| Run callbacks while skipping detached parts | `forEachPart(Consumer)` — [callback and override behavior](api/PART_TRAVERSAL.md#callback-behavior) |
+5 -2
View File
@@ -54,7 +54,9 @@ that must set state between generation and loading.
## Schematica and GuideNH migration
The public static method can be resolved with:
Prefer the direct call `MultipartGenerator.generateCompositeTile(candidate, parts, client)`, as in the compiling
example. Gate optional typed integration code as described in the [API index](../API.md#direct-calls-and-optional-integration).
For temporary interoperability with an existing reflective integration, the method can also be resolved with:
```java
Method generate = MultipartGenerator.class.getMethod(
@@ -77,7 +79,8 @@ body, deprecated for callers in favor of the static Java entry. Existing interna
argument-assignability matcher still rejects the Java parameter for a Scala sequence and falls back to the companion;
Schematica's exact old reflective lookup remains valid. Consumer source patches/releases and pack adoption remain pending.
GuideNH's separate microblock-generator call has an [existing Java replacement](MICROBLOCK_CREATION.md).
Private-material access remains a separate migration contract; neither is closed by this tile API alone.
Private-material access has a separate [typed material query](MATERIAL_ACCESS.md); neither consumer adoption contract
is closed by this tile API alone.
## Validation
+4 -1
View File
@@ -39,7 +39,10 @@ cause the whole preview to be rejected when matching Schematica's all-parts-requ
## Migrating Schematica's optional reflection
Replace the companion singleton/private-field lookup and Scala `Map.get` / `Option` handling with:
Prefer direct `MultiPartRegistry.getPartFactory(partID)` calls, as in the compiling example above. Isolate typed
optional integration code behind mod-presence/version checks; see the [direct-call policy](../API.md#direct-calls-and-optional-integration).
The following is only a legacy interoperability option for a consumer retaining reflection temporarily. It replaces
the companion singleton/private-field lookup and Scala `Map.get` / `Option` handling:
```java
Class<?> registry = Class.forName("codechicken.multipart.MultiPartRegistry");
+58
View File
@@ -0,0 +1,58 @@
# Read a microblock's block and metadata
Use the existing public `BlockMicroMaterial.block()` and `meta()` methods. Neither reflection nor an accessor mixin
is needed. The [compiling Java example](../../src/functionalTest/java/codechicken/multipart/examples/MaterialAccessExample.java)
implements GuideNH's complete primary-material query using typed calls:
1. Traverse `TileMultipart.jPartList()` in its stored order.
2. For each `Microblock`, resolve `material()` through `MicroMaterialRegistry.getMaterial(int)`.
3. If the result is a `BlockMicroMaterial`, read `block()` then `meta()`.
4. Skip null/air blocks and absent/empty block registry names; return the first usable block ID.
For example, wool with metadata 14 exports as `minecraft:wool:14`. GuideNH appends a metadata suffix only when the
value is positive; zero and negative values export the unsuffixed block ID. This is GuideNH's export convention,
not a general material serialization format. The example preserves positive values above 15 without masking.
## Identity, lifecycle and overrides
- `block()` returns the constructor's block by identity in the base implementation, including null. `meta()` returns
the original integer unchanged. Both are public virtual methods; consumer calls must respect subclass overrides.
- A microblock's numeric `material()` value is an ID in the active material map, not block metadata. Query after
registry initialization and, on a client, material-ID synchronization. Do not persist these numeric IDs across
sessions; see [material enumeration](MATERIAL_ENUMERATION.md).
- `IMicroMaterial` does not promise a block/meta representation. Skip non-block materials for this block-only query;
do not cast every registered material to `BlockMicroMaterial` or infer its block from an item drop.
- `blockKey()` caches the constructor block's registry name. It can differ from an overridden `block()` and from
the material's registered name. Export the registry name of the returned block, as the example does.
- This is a read operation with no binding, world access, material registration or tile mutation. Observe the
[part-list ownership contract](PART_TRAVERSAL.md#collection-ownership-and-ordering); the traversal is not a snapshot.
## GuideNH migration
Replace `resolvePrimaryMicroblockId`'s reflective part traversal, material lookup and `AccessorBlockMicroMaterial`
field reads with the typed example. Remove that mixin and its configuration entry when the consumer migrates. Keep
FMP's private fields unchanged until the migrated consumer release is adopted; this branch does not edit the
reference consumer checkout or claim adoption.
The old mixin reads constructor fields directly, bypassing overrides. The old reflection fallback already calls
the public virtual getters. The supported typed path follows those getters too, so custom materials that override
them may produce a different export from the mixin. Validate those materials in GuideNH; do not introduce raw-field
accessors to preserve an implementation detail that disagrees with the material's public behavior.
The example returns null for a null/non-multipart tile or no usable block. Invalid material IDs and exceptions from
custom accessors propagate. GuideNH currently logs query failures and returns null from its outer integration
boundary; retain that policy around the typed call. Do not catch a broken material and silently select a later part.
Metadata is read before the null/air check, preserving accessor order even for a skipped block.
For optional FMP support, isolate typed code in a compatibility class and load it only after checking mod presence
and the supported dependency version. Keep FMP types out of classes loaded unconditionally when FMP is absent.
An optional dependency does not itself require reflection. The [API index](../API.md) describes the current
unreleased branch/version status; pin an artifact containing every method used by the integration.
## Validation
JVM characterization pins constructor identity, every metadata bit, virtual dispatch and the retained private
fields. Dedicated-server Forge tests cover initialized material lookup, ordered filtering, registry aliases,
null/air/unregistered blocks, non-block materials, metadata formatting, overridden accessors and failure propagation.
The example compiles with Scala excluded from its classpath and contains no reflection, companion or Scala calls.
Actual GuideNH exports and optional-mod absent/present loading remain consumer adoption checks.
+4 -2
View File
@@ -51,7 +51,9 @@ or authorize removing Scala-signature support before consumer release/adoption.
## GuideNH migration
GuideNH `7d8fb44e77b9` explicitly resolves the companion's `create(MicroblockClass, int, boolean)` and invokes it on
`MODULE$`. It does not automatically discover the existing static method. Its optional integration can instead cache:
`MODULE$`. It does not automatically discover the existing static method. Prefer the direct typed creation example
below, with [gated optional integration](../API.md#direct-calls-and-optional-integration). The following cache is only
a temporary interoperability option for consumers retaining reflection:
```java
Class<?> generator = Class.forName("codechicken.microblock.MicroblockGenerator");
@@ -75,7 +77,7 @@ capturing shape after creation could copy a callback-modified value instead of t
Public `setShape` uses the virtual shape setter; GuideNH's old private-field write bypassed that dispatch. Validate
custom traits overriding these hooks before adopting the change. Preserve its existing missing/failed-promotion
handling, part order, Java collection migration, tile state setup and subsequent loading/notifications. Do not copy
the source tile binding to the new part. Private material-field access is a separate remaining GuideNH contract.
the source tile binding to the new part. Private material-field access has a separate [typed query guide](MATERIAL_ACCESS.md).
## Side and validation limits
+29
View File
@@ -1971,3 +1971,32 @@ differences belong in the [divergence ledger](../../JAVA_MIGRATION_DIVERGENCES.m
Physical-client creation/previews remain manual because the dedicated server strips client factory methods.
Next bounded task: GuideNH's private material access versus existing public accessors.
Evidence: `run/migration-microblock-creation-reference/`.
### 2026-09-05 — Typed GuideNH material access
- Confirmed that existing `BlockMicroMaterial.block()` / `meta()` cover GuideNH's private-field read use case. Added
Javadocs and a compiling complete material query using direct typed part traversal, material lookup and block
registry access. No new facade, accessor aliases or production behavior changes were necessary.
- Committed the passing baseline first as `079739e`: two JVM cases pin constructor identity, raw integer metadata,
virtual override dispatch and retained private-field values; one Forge case pins initialized block/material lookup.
- Two Forge example cases cover first usable part order, non-microblock/non-block material filtering, null/air and
unregistered blocks, material aliases, all metadata bits, getter ordering/overrides and failure propagation. The
query preserves GuideNH's positive-only metadata suffix policy; failures are handled at the consumer boundary.
- Public getters honor overrides whereas GuideNH's old accessor mixin reads constructor fields. Its reflective
fallback already calls virtual getters. Documented that distinction and retained private fields until released
consumer adoption, rather than adding raw-field accessors. Custom exports and optional-mod loading need consumer
validation; reference checkouts were not modified or counted as migrated.
- Updated the plan and API guides: supported integrations must have direct typed public access. Optional support
uses gated compatibility classes. Reflection snippets are legacy interoperability options, not the migration target.
- Validation: clean formatting/checkstyle/build and Java 8 Forge run pass with **570 JVM / 272 Forge tests**, zero
failures/errors/skips. All **570 archived JVM / 270 archived Forge** tests pass; the frozen Forge mod is byte-identical.
The typed example compiles with Scala excluded and has no Scala/reflection calls. All **444 class APIs, 17
ScalaSignature payloads and 3,761 production method bodies** are unchanged. Of 116 generated dumps, 114 match
byte-for-byte; the face/post pair differs only by swapped allocation-order names (`Microblock_cmp$$0` / `$$1`)
because the added example tests create the face earlier. Explicit pairwise renaming proves identical bodies;
no generator behavior changed. The installed
`+719` pack retains all 386 ABI/reflection rows across 27 consumers. Packaged source and Java 8 bytecode are checked,
and the post-commit rebuild verifies all five mod versions in dev/release artifacts. Evidence:
`run/migration-material-access-reference/`.
- Next bounded task: Phase 9.2 internal-boundary Javadocs with a fresh caller audit, including supported `bindPart`
and `internalPartChange`; external Java extension guidance and the measured performance pass remain separate.
@@ -0,0 +1,38 @@
package codechicken.multipart.examples;
import net.minecraft.block.Block;
import net.minecraft.init.Blocks;
import net.minecraft.tileentity.TileEntity;
import codechicken.microblock.BlockMicroMaterial;
import codechicken.microblock.MicroMaterialRegistry;
import codechicken.microblock.MicroMaterialRegistry.IMicroMaterial;
import codechicken.microblock.Microblock;
import codechicken.multipart.TMultiPart;
import codechicken.multipart.TileMultipart;
/** Forge-tested compiling example for docs/api/MATERIAL_ACCESS.md. */
public final class MaterialAccessExample {
private MaterialAccessExample() {}
/** Returns the first usable block ID using GuideNH's metadata suffix policy; failures propagate to the caller. */
public static String resolvePrimaryMicroblockId(TileEntity tile) {
if (!(tile instanceof TileMultipart)) return null;
for (TMultiPart part : ((TileMultipart) tile).jPartList()) {
if (!(part instanceof Microblock)) continue;
IMicroMaterial material = MicroMaterialRegistry.getMaterial(((Microblock) part).material());
if (!(material instanceof BlockMicroMaterial)) continue;
BlockMicroMaterial blockMaterial = (BlockMicroMaterial) material;
Block block = blockMaterial.block();
int meta = blockMaterial.meta();
if (block == null || block == Blocks.air) continue;
Object registryName = Block.blockRegistry.getNameForObject(block);
if (registryName == null) continue;
String blockId = registryName.toString();
if (blockId.isEmpty()) continue;
return meta > 0 ? blockId + ":" + meta : blockId;
}
return null;
}
}
@@ -2,25 +2,118 @@ package codechicken.multipart.test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertSame;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import net.minecraft.block.Block;
import net.minecraft.block.material.Material;
import net.minecraft.entity.player.EntityPlayer;
import net.minecraft.init.Blocks;
import net.minecraft.item.Item;
import net.minecraft.item.ItemStack;
import net.minecraft.server.MinecraftServer;
import net.minecraft.tileentity.TileEntity;
import net.minecraft.world.WorldServer;
import net.minecraftforge.common.util.FakePlayerFactory;
import org.junit.jupiter.api.Test;
import codechicken.microblock.BlockMicroMaterial;
import codechicken.microblock.FaceMicroClass$;
import codechicken.microblock.MicroMaterialRegistry;
import codechicken.microblock.MicroMaterialRegistry.IMicroMaterial;
import codechicken.microblock.Microblock;
import codechicken.microblock.MissingMicroMaterial$;
import codechicken.multipart.TileMultipart;
import codechicken.multipart.examples.MaterialAccessExample;
import scala.Tuple2;
class BlockMicroMaterialFunctionalTest {
@Test
void typedQueryUsesFirstUsableBlockAndGuideNhMetadataFormatting() {
assertNull(MaterialAccessExample.resolvePrimaryMicroblockId(null));
assertNull(MaterialAccessExample.resolvePrimaryMicroblockId(new TileEntity()));
TileMultipart tile = new TileMultipart();
assertNull(MaterialAccessExample.resolvePrimaryMicroblockId(tile));
Microblock first = FaceMicroClass$.MODULE$.create(false, 0);
Microblock second = FaceMicroClass$.MODULE$.create(false, 1);
tile.setPartList(Arrays.asList(new MultipartGeneratorFunctionalTest.PlainPart(), first, second));
Tuple2<String, IMicroMaterial>[] materials = MicroMaterialRegistry.getIdMap();
Tuple2<String, IMicroMaterial> originalFirst = materials[0];
Tuple2<String, IMicroMaterial> originalSecond = materials[1];
try {
materials[1] = new Tuple2<>("test:second", new BlockMicroMaterial(Blocks.stone, 0));
for (int meta : new int[] { Integer.MIN_VALUE, -1, 0, 15, 17, Integer.MAX_VALUE }) {
materials[0] = new Tuple2<>("test:alias", new BlockMicroMaterial(Blocks.wool, meta));
assertEquals(
meta > 0 ? "minecraft:wool:" + meta : "minecraft:wool",
MaterialAccessExample.resolvePrimaryMicroblockId(tile));
}
for (IMicroMaterial skipped : new IMicroMaterial[] { MissingMicroMaterial$.MODULE$, null,
new BlockMicroMaterial(null, 0), new BlockMicroMaterial(Blocks.air, 0),
new BlockMicroMaterial(new Block(Material.rock) {}, 0) }) {
materials[0] = new Tuple2<>("test:skipped", skipped);
assertEquals("minecraft:stone", MaterialAccessExample.resolvePrimaryMicroblockId(tile));
}
materials[1] = materials[0];
assertNull(MaterialAccessExample.resolvePrimaryMicroblockId(tile));
} finally {
materials[0] = originalFirst;
materials[1] = originalSecond;
}
}
@Test
void typedQueryUsesVirtualAccessorsAndPropagatesFailuresWithoutSelectingALaterPart() {
Microblock first = FaceMicroClass$.MODULE$.create(false, 0);
Microblock second = FaceMicroClass$.MODULE$.create(false, 1);
TileMultipart tile = new TileMultipart();
tile.setPartList(Arrays.asList(first, second));
Tuple2<String, IMicroMaterial>[] materials = MicroMaterialRegistry.getIdMap();
Tuple2<String, IMicroMaterial> original = materials[0];
List<String> calls = new ArrayList<>();
RuntimeException failure = new IllegalStateException("material failure");
try {
materials[0] = new Tuple2<>("test:override", new BlockMicroMaterial(null, 3) {
@Override
public Block block() {
calls.add("block");
return Blocks.wool;
}
@Override
public int meta() {
calls.add("meta");
return 23;
}
});
assertEquals("minecraft:wool:23", MaterialAccessExample.resolvePrimaryMicroblockId(tile));
assertEquals(Arrays.asList("block", "meta"), calls);
materials[0] = new Tuple2<>("test:failure", new BlockMicroMaterial(null, 0) {
@Override
public int meta() {
throw failure;
}
});
assertSame(
failure,
assertThrows(RuntimeException.class, () -> MaterialAccessExample.resolvePrimaryMicroblockId(tile)));
first.material_$eq(Integer.MAX_VALUE);
assertThrows(IndexOutOfBoundsException.class, () -> MaterialAccessExample.resolvePrimaryMicroblockId(tile));
} finally {
materials[0] = original;
}
}
@Test
void registeredMaterialsExposeBlockAndMetadataWithoutClientInitialization() throws Exception {
int id = MicroMaterialRegistry.materialID("minecraft:stone");
@@ -84,14 +84,28 @@ public class BlockMicroMaterial implements IMicroMaterial {
BlockMicroMaterial$.MODULE$.createAndRegister(block, meta, name, oldName);
}
/**
* Returns this material's block for direct consumer access. The base implementation returns the constructor
* argument by identity, including null; subclasses may override it. Call this method instead of reading the private
* compatibility field so material overrides are respected.
*/
public Block block() {
return block;
}
/**
* Returns this material's metadata for direct consumer access. The base implementation returns the constructor
* value without masking or validation; subclasses may override it. This is not a numeric micro-material ID.
*/
public int meta() {
return meta;
}
/**
* Returns the block registry name cached at construction, possibly null. This is neither the micro-material's
* registered name nor a fresh lookup of an overridden {@link #block()}; query the returned block's registry name
* when exporting its current identity.
*/
public String blockKey() {
return blockKey;
}