mirror of
https://github.com/GTNewHorizons/ForgeMultipart.git
synced 2026-11-21 04:32:24 +00:00
docs: define direct Java material access
This commit is contained in:
1 parent
079739ea80
commit
37d5ea98f6
13 files changed
+311
-31
No files matched your search
+14
-4
@@ -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;
|
||||
|
||||
@@ -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.
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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) |
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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");
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
+93
@@ -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;
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user