diff --git a/JAVA_MIGRATION.md b/JAVA_MIGRATION.md index ba5d4b4..5985815 100644 --- a/JAVA_MIGRATION.md +++ b/JAVA_MIGRATION.md @@ -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; diff --git a/JAVA_MIGRATION_ABI_INVENTORY.md b/JAVA_MIGRATION_ABI_INVENTORY.md index 367e9d7..a8c12cf 100644 --- a/JAVA_MIGRATION_ABI_INVENTORY.md +++ b/JAVA_MIGRATION_ABI_INVENTORY.md @@ -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. diff --git a/JAVA_MIGRATION_CONSUMER_AUDIT.md b/JAVA_MIGRATION_CONSUMER_AUDIT.md index 96bbe2e..f99386c 100644 --- a/JAVA_MIGRATION_CONSUMER_AUDIT.md +++ b/JAVA_MIGRATION_CONSUMER_AUDIT.md @@ -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. diff --git a/JAVA_MIGRATION_HANDOFF.md b/JAVA_MIGRATION_HANDOFF.md index 2d415ae..370ae19 100644 --- a/JAVA_MIGRATION_HANDOFF.md +++ b/JAVA_MIGRATION_HANDOFF.md @@ -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 diff --git a/docs/API.md b/docs/API.md index 379bbc4..6e72b0b 100644 --- a/docs/API.md +++ b/docs/API.md @@ -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) | diff --git a/docs/api/COMPOSITE_GENERATION.md b/docs/api/COMPOSITE_GENERATION.md index 5377365..395d932 100644 --- a/docs/api/COMPOSITE_GENERATION.md +++ b/docs/api/COMPOSITE_GENERATION.md @@ -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 diff --git a/docs/api/FACTORY_LOOKUP.md b/docs/api/FACTORY_LOOKUP.md index c55927b..ba4eba1 100644 --- a/docs/api/FACTORY_LOOKUP.md +++ b/docs/api/FACTORY_LOOKUP.md @@ -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"); diff --git a/docs/api/MATERIAL_ACCESS.md b/docs/api/MATERIAL_ACCESS.md new file mode 100644 index 0000000..ee9cbd2 --- /dev/null +++ b/docs/api/MATERIAL_ACCESS.md @@ -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. diff --git a/docs/api/MICROBLOCK_CREATION.md b/docs/api/MICROBLOCK_CREATION.md index 6dc8a09..df535c4 100644 --- a/docs/api/MICROBLOCK_CREATION.md +++ b/docs/api/MICROBLOCK_CREATION.md @@ -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 diff --git a/docs/migration/HISTORY.md b/docs/migration/HISTORY.md index 03e2a53..04d8d0c 100644 --- a/docs/migration/HISTORY.md +++ b/docs/migration/HISTORY.md @@ -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. diff --git a/src/functionalTest/java/codechicken/multipart/examples/MaterialAccessExample.java b/src/functionalTest/java/codechicken/multipart/examples/MaterialAccessExample.java new file mode 100644 index 0000000..5e83d53 --- /dev/null +++ b/src/functionalTest/java/codechicken/multipart/examples/MaterialAccessExample.java @@ -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; + } +} diff --git a/src/functionalTest/java/codechicken/multipart/test/BlockMicroMaterialFunctionalTest.java b/src/functionalTest/java/codechicken/multipart/test/BlockMicroMaterialFunctionalTest.java index d25a389..5cc058a 100644 --- a/src/functionalTest/java/codechicken/multipart/test/BlockMicroMaterialFunctionalTest.java +++ b/src/functionalTest/java/codechicken/multipart/test/BlockMicroMaterialFunctionalTest.java @@ -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[] materials = MicroMaterialRegistry.getIdMap(); + Tuple2 originalFirst = materials[0]; + Tuple2 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[] materials = MicroMaterialRegistry.getIdMap(); + Tuple2 original = materials[0]; + List 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"); diff --git a/src/main/scala/codechicken/microblock/BlockMicroMaterial.java b/src/main/scala/codechicken/microblock/BlockMicroMaterial.java index f2b18d0..1af69a6 100644 --- a/src/main/scala/codechicken/microblock/BlockMicroMaterial.java +++ b/src/main/scala/codechicken/microblock/BlockMicroMaterial.java @@ -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; }