From e0886ff6afd04e9c6ef2b8c981854b96a93f1628 Mon Sep 17 00:00:00 2001 From: Algent Date: Sat, 5 Sep 2026 13:42:51 +0200 Subject: [PATCH] feat: expose registered part factory lookup --- JAVA_MIGRATION.md | 5 +- JAVA_MIGRATION_ABI_INVENTORY.md | 5 ++ JAVA_MIGRATION_CONSUMER_AUDIT.md | 21 ++++- JAVA_MIGRATION_HANDOFF.md | 34 +++++---- docs/API.md | 3 +- docs/api/FACTORY_LOOKUP.md | 76 +++++++++++++++++++ docs/api/PART_REGISTRATION.md | 3 + docs/migration/HISTORY.md | 25 ++++++ .../examples/PartFactoryLookupExample.java | 21 +++++ .../test/PartFactoryLookupFunctionalTest.java | 25 ++++++ .../multipart/MultiPartRegistry$.java | 5 +- .../multipart/MultiPartRegistry.java | 16 ++++ ...MultiPartRegistryCharacterizationTest.java | 5 ++ 13 files changed, 224 insertions(+), 20 deletions(-) create mode 100644 docs/api/FACTORY_LOOKUP.md create mode 100644 src/functionalTest/java/codechicken/multipart/examples/PartFactoryLookupExample.java diff --git a/JAVA_MIGRATION.md b/JAVA_MIGRATION.md index d679f94..41d297e 100644 --- a/JAVA_MIGRATION.md +++ b/JAVA_MIGRATION.md @@ -683,7 +683,7 @@ does not close a row, and scans must distinguish a consumer's own Scala code fro | Consumer | What FMP is currently forced to preserve | Upstream fix | Can start | | --- | --- | --- | --- | | 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` | FMP exposes a supported registry lookup; Schematica uses it instead of the field | After step 1 | +| 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-only `MultipartGenerator$.MODULE$.generateCompositeTile` and `MicroblockGenerator$.create`; `partList_$eq(scala.collection.Seq)`; mixin into private `BlockMicroMaterial.block` and `.meta` | FMP exposes supported static entry points and `setPartList(List)`; GuideNH targets those and public material accessors | After step 1 and Phase 9.1 | | 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 | @@ -733,6 +733,9 @@ UtilitiesInExcess's `extrautils:*` aliases; there is no legacy-conversion risk i - [ ] Land the Galacticraft reflection signature check. - [ ] Fix the UtilitiesInExcess `mat`/`material` key mismatch and its `getIdMap()` use before it enters the pack. - [ ] Add the supported public equivalents needed by Schematica, GuideNH, Et Futurum, and Iguana as additive API. +- [x] Provide Schematica's registered-factory lookup without exposing the mutable map: `getPartFactory(String)`, + with identity/missing-name checks, exact public reflection, a compiling example and the retained private field. + Client/server composite generation remains a separate Schematica/GuideNH gap; this does not complete either migration. - [ ] Patch those four consumers and record the released versions that no longer need the private shapes. - [ ] Track all legacy FMP dependencies in the adoption ledger, including trait helper/companion calls and reflection outside the cleanup table; verify the released jars actually selected for the target pack. diff --git a/JAVA_MIGRATION_ABI_INVENTORY.md b/JAVA_MIGRATION_ABI_INVENTORY.md index 8ccccd9..9aceaf6 100644 --- a/JAVA_MIGRATION_ABI_INVENTORY.md +++ b/JAVA_MIGRATION_ABI_INVENTORY.md @@ -161,6 +161,11 @@ These fail at runtime, not at link time, so ABI tooling will not catch a break. Note that both the class and its `$` companion are named in several cases, so renaming or removing a companion object breaks these even where no bytecode reference exists. +The branch now offers `MultiPartRegistry.getPartFactory(String): IPartFactory2` to replace Schematica's private +registry-map reflection, with a [migration guide](docs/api/FACTORY_LOOKUP.md). Its old companion field retains the +exact private Scala mutable-map shape and live backing; the public addition does not authorize removing that field +before consumer release/adoption. Generator reflection and preview lifecycle remain separate contracts. + ## Consequences for the migration plan 1. Phase 8 (Scala runtime removal) should be reclassified as deferred, not scheduled. Decision 4 is answered. diff --git a/JAVA_MIGRATION_CONSUMER_AUDIT.md b/JAVA_MIGRATION_CONSUMER_AUDIT.md index 5ec3834..02154c1 100644 --- a/JAVA_MIGRATION_CONSUMER_AUDIT.md +++ b/JAVA_MIGRATION_CONSUMER_AUDIT.md @@ -355,6 +355,12 @@ inventory alone shows. as a Scala mutable-map wrapper backed by the canonical Java `HashMap`, and a regression test performs Schematica's lookup and verifies that both views resolve the same factory. +The branch now provides `MultiPartRegistry.getPartFactory(String)` as the supported replacement for map lookup. +It returns the exact registered factory or null without construction or missing-name logging. Schematica can reflect +this public static method and continue invoking `MicroblockClass.create(client, materialId)` on the returned object; +`loadPart` would incorrectly choose the server factory path for its client preview. The old private field remains. +See the [guide](docs/api/FACTORY_LOOKUP.md); consumer patch, generator migration and pack adoption remain pending. + ### UtilitiesInExcess — future replacement, already a substantial consumer UtilitiesInExcess is not in the `+700` JAR scan but is in scope because it is intended to replace Extra Utilities. @@ -491,7 +497,7 @@ behavior: ## Java API adoption ledger This ledger tracks migration of a specific legacy contract, not completion of an entire consumer's migration. -Factory registration, material enumeration, tile collection/traversal access, tile loading/storage assignment, +Factory registration/lookup, material enumeration, tile collection/traversal access, tile loading/storage assignment, tile occlusion and box queries, render-ID accessors and named tile conversion results are implemented on `algent/java`. The [API index](docs/API.md) links the guides and compiling Java examples. These additions are not yet tied to a released minimum dependency version. Unlisted contracts remain governed by the inventories above. @@ -507,7 +513,8 @@ 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 map and generator reflection remain separate contracts | No migrated pack version verified; retain the Scala loader descriptor | +| `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 now available separately, generator reflection remains pending | 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; public FMP lookup implemented, generator migration remains separate | No migrated pack version verified; retain the exact private live Scala-map field | | `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 | @@ -598,6 +605,16 @@ gate. All 566 archived JVM tests and the unchanged archived Forge test mod's 252 The `+719` rescan retains all 386 member/type/reflection rows across 27 consumers. Reference checkouts remain unchanged. Evidence: `run/migration-tile-conversion-reference/`. +Registered factory lookup is implemented as `MultiPartRegistry.getPartFactory(String)`, with the same identity and +current-map behavior as Schematica's reflected lookup. No new-name collision was found in the supplied Java/Scala +sources. The Java example compiles without Scala; exact public reflection is exercised in Forge. Both lookup paths +are checked without factory callbacks, including late mapping changes, equal names and misses. Forge additionally +checks all five built-in microblock factories, server construction and NBT loading; physical-client construction and +preview rendering remain manual because the dedicated server strips `MicroblockClass.clientTrait()`. +All 567 archived JVM tests and the byte-identical archived Forge mod's 256 cases pass against this addition. The +`+719` scan retains all 386 member/type/reflection rows across 27 consumers. The private map retains its exact binary +shape and live backing. Reference checkouts remain unchanged. Evidence: `run/migration-factory-lookup-reference/`. + ## 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 6a524f0..d91b75f 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 -**566 plain-JVM tests and 255 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **225 Java +**568 plain-JVM tests and 258 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,14 +32,16 @@ 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 addition: `TileMultipart.getOrConvertTileResult(World, BlockCoord)` returns a `TileConversionResult` with -`getTile()` / `isConverted()`. Three Forge baseline cases were committed first as `7396f2d`; three Java-entry cases -exercise the same existing/missing/converted-placeholder contracts and the compiling example. Both tuple entries -retain their bodies/descriptors with deprecations, and internal callers are unchanged. All 566 frozen JVM tests and -the archived Forge mod's 252 cases pass against the new implementation. All 443 existing classes retain their members; -one result class and one static method are added. The 17 ScalaSignature payloads, 3,755 existing method bodies and -116 generated dumps are unchanged apart from deprecation metadata and build versions. -Evidence: `run/migration-tile-conversion-reference/`; [guide](docs/api/TILE_CONVERSION.md). +Latest API addition: `MultiPartRegistry.getPartFactory(String)` returns the exact registered factory or null without +constructing a part. One JVM and one Forge baseline case were committed first as `2a52980`; one further JVM and two +Forge cases cover the Java entry, exact public reflection and compiling example. Schematica can replace its private +map/Scala Option lookup while retaining `MicroblockClass.create(client, materialId)`. The old private live Scala-map +field and all existing method bodies remain unchanged. All 567 frozen JVM tests and the archived Forge mod's 256 cases +pass against the addition. All 444 class APIs, 17 ScalaSignature payloads, 3,759 existing method bodies and 116 generated +dumps remain; exactly one public static method is added. The example compiles without Scala. Dedicated-server tests +cover server microblock construction; physical-client creation/preview rendering remain manual because Forge strips +the client's `clientTrait()` method on the server. +Evidence: `run/migration-factory-lookup-reference/`; [guide](docs/api/FACTORY_LOOKUP.md). 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. @@ -58,13 +60,15 @@ 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 supported registry lookup for Schematica, replacing its private Scala-mangled map -reflection. Read that consumer's actual lookup/use contract and existing public registry helpers, characterize the -behavior first, then supply the smallest missing Java entry and migration guide. Generator/reflection replacements, -the representative external Java extension and internal-boundary documentation remain separate work. +The next bounded candidate is a supported Java client/server composite-tile generation entry for Schematica and +GuideNH. Read their exact companion-only `generateCompositeTile` calls and the existing `MultipartHelper` helpers; +`createTileFromParts` currently creates a server tile and loads it immediately, which is not their staged contract. +Characterize generation, reuse, side selection and caller-owned loading before adding the smallest missing Java +entry. The representative external Java extension and internal-boundary documentation remain separate work. -Progress: all ten Phase 9.1 table rows now have implemented/documented Java replacements. That count excludes supported -registry/generator/reflection replacements, extension examples and internal-boundary documentation. Then consumer +Progress: all ten Phase 9.1 table rows now have implemented/documented Java replacements, plus the separate Schematica +registry lookup. Remaining work includes generator/reflection replacements, 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. diff --git a/docs/API.md b/docs/API.md index 756acf8..5ec3a1f 100644 --- a/docs/API.md +++ b/docs/API.md @@ -13,6 +13,7 @@ without converting the rest of its code to Java. | Task | API and guide | | --- | --- | | 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/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) | @@ -51,7 +52,7 @@ Deprecated Scala-facing entry points remain callable, with their descriptors and Follow the method-specific guide: a Java sibling is not automatically a replacement override hook, and reflection must select the intended parameter types when a method is overloaded. -Registry lookup/converter documentation, generator/reflection replacements +Converter documentation, remaining generator/reflection replacements and complete external microblock extension guidance are still pending. In particular, ProjectRed's Scala microblock traits remain a supported dependency; registration signatures alone do not prove a complete Java replacement. diff --git a/docs/api/FACTORY_LOOKUP.md b/docs/api/FACTORY_LOOKUP.md new file mode 100644 index 0000000..61be2c4 --- /dev/null +++ b/docs/api/FACTORY_LOOKUP.md @@ -0,0 +1,76 @@ +# Registered part factory lookup + +[Java API index](../API.md) + +`MultiPartRegistry.getPartFactory(String)` returns the registered `IPartFactory2` for an exact part type name, or +`null` when no factory is mapped. It is available on `algent/java`; no minimum published dependency version exists yet. + +```java +IPartFactory2 factory = MultiPartRegistry.getPartFactory("mcr_face"); +``` + +Lookup is case-sensitive, uses string equality and reads the current registration map. It neither constructs a part, +logs unknown names, waits for registration nor changes registry state. It does not depend on the numeric network ID +map. Look up after the owning mod has registered its types, on the initialization/game thread; no synchronization is +added. Use published, non-null type names. + +The result is the exact registered factory instance, not a copy or a mutable registry view. Do not modify its state. +Registration remains the job of [`registerPartFactory`](PART_REGISTRATION.md); lookup does not expose a replacement, +removal or enumeration operation. An earlier lookup result does not update itself if registry state later changes. + +## Choose the construction path + +Most consumers should continue using `loadPart(name, nbt)` or `readPart(input)`. Those choose the registered factory's +NBT/server or packet/client method. Their caller still invokes `part.load(nbt)` or `part.readDesc(input)`, respectively, +and later binds/places the part. See [factory and payload contracts](PART_REGISTRATION.md). + +Factory lookup is useful when a supported factory subtype provides a specialized construction method. Schematica +looks up a `MicroblockClass` and calls `create(client, materialId)` before loading the saved microblock NBT. Calling +`loadPart` instead would select the server/NBT construction path, even for a client preview. Passing a null packet or +using deprecated `createPart(name, true)` is also unsuitable: microblock packet factories read a material ID from it. + +The [compiling Java example](../../src/functionalTest/java/codechicken/multipart/examples/PartFactoryLookupExample.java) +checks for `MicroblockClass` and creates a fresh unbound microblock. The caller must resolve a valid material ID, +load the part's NBT, prepare the correct composite tile and complete its existing lifecycle. This example only covers +factory selection and construction, not a complete schematic loader. Its null result for an unsupported type must +cause the whole preview to be rejected when matching Schematica's all-parts-required policy. + +## Migrating Schematica's optional reflection + +Replace the companion singleton/private-field lookup and Scala `Map.get` / `Option` handling with: + +```java +Class registry = Class.forName("codechicken.multipart.MultiPartRegistry"); +Method lookup = registry.getMethod("getPartFactory", String.class); +Object factory = lookup.invoke(null, partID); +if (factory == null) { + return null; // Keep the caller's missing-part rejection. +} +``` + +Cache the `Method` during integration initialization as Schematica already does. Continue resolving +`MicroblockClass.create(boolean.class, int.class)` with its exact parameter types and invoking it on this factory. +Not every registered factory is a microblock class: keep the existing rejection of an unsupported factory, or check +the reflected microblock class's `isInstance(factory)` explicitly before invoking. Do not silently produce a partial preview. + +This removes the registry-map Scala dependency. It does not finish Schematica's migration: use the +[Java loading API](PART_LOADING.md#overrides-and-reflection) for its part collection, and retain the companion generator +call until a supported Java client/server composite-generation entry is provided. Material lookup, saved part order, +shape/material loading, tile NBT and subsequent notifications remain unchanged. + +The private `MultiPartRegistry$.codechicken$multipart$MultiPartRegistry$$typeMap` field keeps its exact name, modifiers, +Scala mutable-map type and live backing. Existing binary/reflection callers remain supported until a migrated consumer +release is adopted by the target pack. The reference Schematica checkout was not edited or counted as migrated. + +## Validation + +JVM characterization compares legacy reflection and Java lookup for exact factory identity, equal strings, case-sensitive +misses, replacement/removal visibility and absence of construction callbacks. Test-only registry mutations restore +their state; they are not a supported consumer API. Forge covers all five built-in microblock factories, exact public +reflection, server construction, NBT loading, unbound ownership and the Java example. The example also compiles with +Scala excluded from its classpath. Archived callers and the private field's binary shape are checked separately. + +Physical-client microblock construction and Schematica preview rendering remain +[manual release checks](../../JAVA_MIGRATION_MANUAL_CHECKS.md). A dedicated Forge server strips `clientTrait()`, so +calling client microblock creation there fails before it can exercise a real client preview; the server fixture does +not claim that coverage. diff --git a/docs/api/PART_REGISTRATION.md b/docs/api/PART_REGISTRATION.md index 44ce8fd..a78fd03 100644 --- a/docs/api/PART_REGISTRATION.md +++ b/docs/api/PART_REGISTRATION.md @@ -6,6 +6,9 @@ Use `MultiPartRegistry.registerPartFactory(IPartFactory2, String...)` on the `al existing registry and avoids the Scala types in the `registerParts` overload family. This addition does not yet have a minimum published dependency version. +To inspect a registered factory without constructing a part, see [factory lookup](FACTORY_LOOKUP.md), including +Schematica's replacement for private registry-map reflection. + ## Example and timing The [complete compiling example](../../src/functionalTest/java/codechicken/multipart/examples/PartRegistrationExample.java) diff --git a/docs/migration/HISTORY.md b/docs/migration/HISTORY.md index ae71a71..02173c5 100644 --- a/docs/migration/HISTORY.md +++ b/docs/migration/HISTORY.md @@ -1897,3 +1897,28 @@ differences belong in the [divergence ledger](../../JAVA_MIGRATION_DIVERGENCES.m unchanged. Next bounded candidate: Schematica registry lookup. Consumer adoption, internal tuple users, external Java extensions, measured performance work and actual client/pack checks remain separate gates. Evidence: `run/migration-tile-conversion-reference/`. + +### 2026-09-05 — Supported registered-factory lookup + +- Traced Schematica `3b03ee937953` from private Scala map lookup through `MicroblockClass.create(client, materialId)` + and NBT loading. Existing `loadPart` selects server construction, so it cannot replace that client-preview lookup. + Added `MultiPartRegistry.getPartFactory(String)` as a direct read of the canonical map, returning the exact factory + or null without logging, construction, registration mutation or dependency on the network ID map. +- Committed one JVM and one Forge characterization case first as `2a52980`, saving the reference jar, sources, + compiled fixtures, reports and generated dumps. Legacy reflection and the Java API share checks for factory identity, + string equality, case-sensitive misses, current-map changes and no construction callbacks. Forge checks all five + microblock factories, exact reflective construction, server side, NBT material/shape and unbound ownership. +- Added one JVM and two Forge cases for the Java API, exact public reflection and a compiling example. The example + compiles standalone without Scala. A baseline attempt at client microblock creation on the dedicated server failed + because Forge strips `MicroblockClass.clientTrait()` there; real client construction/preview rendering remain manual, + and no client coverage is claimed from the server fixture. +- Normal and clean style/build checks pass with 568 JVM and 258 Forge tests, zero failures/errors/skips. All 567 frozen + JVM tests and the byte-identical archived Forge mod's 256 cases pass against the addition. All 444 class APIs, + 17 ScalaSignature payloads, 3,759 existing method bodies and 116 generated dumps remain, with exactly one static + method added. The private Scala mutable-map field retains its exact name/modifiers/type and live backing. +- Added a factory lookup guide, typed and reflective migration examples, API-index links and a Schematica adoption + ledger row. No new-name collision was found in supplied consumer sources; the `+719` scan still matches all 386 + member/type/reflection rows across 27 consumers. Checkouts remain reference-only; no consumer release/adoption is + claimed. Next bounded task is Java client/server composite generation for Schematica and GuideNH; loading, + material/shape restoration, all-parts rejection and notifications must retain their staged lifecycle. + Evidence: `run/migration-factory-lookup-reference/`. diff --git a/src/functionalTest/java/codechicken/multipart/examples/PartFactoryLookupExample.java b/src/functionalTest/java/codechicken/multipart/examples/PartFactoryLookupExample.java new file mode 100644 index 0000000..7a83936 --- /dev/null +++ b/src/functionalTest/java/codechicken/multipart/examples/PartFactoryLookupExample.java @@ -0,0 +1,21 @@ +package codechicken.multipart.examples; + +import codechicken.microblock.Microblock; +import codechicken.microblock.MicroblockClass; +import codechicken.multipart.MultiPartRegistry; +import codechicken.multipart.MultiPartRegistry.IPartFactory2; + +/** Forge-tested compiling example for docs/api/FACTORY_LOOKUP.md. */ +public final class PartFactoryLookupExample { + + private PartFactoryLookupExample() {} + + /** Creates an unbound microblock; the caller still loads its NBT and prepares the containing tile. */ + public static Microblock createMicroblock(String type, boolean client, int material) { + IPartFactory2 factory = MultiPartRegistry.getPartFactory(type); + if (!(factory instanceof MicroblockClass)) { + return null; + } + return ((MicroblockClass) factory).create(client, material); + } +} diff --git a/src/functionalTest/java/codechicken/multipart/test/PartFactoryLookupFunctionalTest.java b/src/functionalTest/java/codechicken/multipart/test/PartFactoryLookupFunctionalTest.java index 39417d6..d612b52 100644 --- a/src/functionalTest/java/codechicken/multipart/test/PartFactoryLookupFunctionalTest.java +++ b/src/functionalTest/java/codechicken/multipart/test/PartFactoryLookupFunctionalTest.java @@ -18,13 +18,38 @@ import codechicken.microblock.MicroMaterialRegistry; import codechicken.microblock.Microblock; import codechicken.microblock.MicroblockClass; import codechicken.microblock.MicroblockClient; +import codechicken.multipart.MultiPartRegistry; import codechicken.multipart.MultiPartRegistry$; import codechicken.multipart.MultiPartRegistry.IPartFactory2; +import codechicken.multipart.examples.PartFactoryLookupExample; import cpw.mods.fml.relauncher.ReflectionHelper; import scala.Option; class PartFactoryLookupFunctionalTest { + @Test + void javaFactoriesSupportMicroblockConstructionAndLoading() throws Exception { + checkMicroblocks(MultiPartRegistry::getPartFactory); + assertSame( + MultiPartRegistry.getPartFactory("mcr_face"), + MultiPartRegistry.class.getMethod("getPartFactory", String.class).invoke(null, "mcr_face")); + assertNull( + MultiPartRegistry.class.getMethod("getPartFactory", String.class).invoke(null, "test:no_such_factory")); + } + + @Test + void javaExampleRejectsUnsupportedTypesAndCreatesFreshUnboundMicroblocks() { + int material = MicroMaterialRegistry.materialID("minecraft:stone"); + assertNull(PartFactoryLookupExample.createMicroblock("test:no_such_factory", false, material)); + assertNull(PartFactoryLookupExample.createMicroblock("mc_torch", false, material)); + Microblock part = PartFactoryLookupExample.createMicroblock("mcr_face", false, material); + assertSame(MultiPartRegistry.getPartFactory("mcr_face"), part.microClass()); + assertEquals(material, part.material()); + assertFalse(part instanceof MicroblockClient); + assertNull(part.tile()); + assertNotSame(part, PartFactoryLookupExample.createMicroblock("mcr_face", false, material)); + } + @Test @SuppressWarnings("unchecked") void reflectedFactoriesSupportMicroblockConstructionAndLoading() throws Exception { diff --git a/src/main/scala/codechicken/multipart/MultiPartRegistry$.java b/src/main/scala/codechicken/multipart/MultiPartRegistry$.java index 83ef646..b4711b1 100644 --- a/src/main/scala/codechicken/multipart/MultiPartRegistry$.java +++ b/src/main/scala/codechicken/multipart/MultiPartRegistry$.java @@ -23,7 +23,10 @@ public final class MultiPartRegistry$ { public static final MultiPartRegistry$ MODULE$ = new MultiPartRegistry$(); - /** Retained with its original name and Scala type because Schematica reflects it directly. */ + /** + * Retained with its original name and Scala type because Schematica reflects it directly. New callers should use + * {@link MultiPartRegistry#getPartFactory(String)}; this live compatibility view remains until consumer adoption. + */ @SuppressWarnings("unused") private final scala.collection.mutable.Map codechicken$multipart$MultiPartRegistry$$typeMap = JavaConversions .mapAsScalaMap(MultiPartRegistry.typeMapBacking()); diff --git a/src/main/scala/codechicken/multipart/MultiPartRegistry.java b/src/main/scala/codechicken/multipart/MultiPartRegistry.java index 52f6c8c..bc8f72f 100644 --- a/src/main/scala/codechicken/multipart/MultiPartRegistry.java +++ b/src/main/scala/codechicken/multipart/MultiPartRegistry.java @@ -279,6 +279,22 @@ public final class MultiPartRegistry { return e._2().createPart(e._1(), data); } + /** + * Returns the registered factory for an exact, case-sensitive part type name, or null if no factory is mapped. + * Reads the current registration map, independently of the network ID map, without constructing a part, logging a + * missing name or changing registration state. The returned object is the registered instance, not a copy. + * + *

+ * Look up after the owning mod has registered its parts, on the initialization/game thread. This method neither + * waits for registration nor adds synchronization. It grants no right to mutate the registry or factory state. For + * ordinary NBT/packet construction use {@link #loadPart(String, NBTTagCompound)} or {@link #readPart(MCDataInput)}. + * Specialized callers may inspect the factory's supported type, for example a microblock class needed to create a + * client preview from a material ID. Factory construction still requires the caller to load and bind the part. + */ + public static IPartFactory2 getPartFactory(String name) { + return typeMap.get(name); + } + /** Uses instantiators to create a new part from a tag compound. */ public static TMultiPart loadPart(String name, NBTTagCompound nbt) { IPartFactory2 factory = typeMap.get(name); diff --git a/src/test/java/codechicken/multipart/MultiPartRegistryCharacterizationTest.java b/src/test/java/codechicken/multipart/MultiPartRegistryCharacterizationTest.java index d6dc2cc..84a97aa 100644 --- a/src/test/java/codechicken/multipart/MultiPartRegistryCharacterizationTest.java +++ b/src/test/java/codechicken/multipart/MultiPartRegistryCharacterizationTest.java @@ -34,6 +34,11 @@ import scala.Option; */ class MultiPartRegistryCharacterizationTest { + @Test + void javaFactoryLookupTracksRegistryWithoutConstructingParts() { + checkFactoryLookup(MultiPartRegistry::getPartFactory); + } + @Test void reflectedFactoryLookupTracksRegistryWithoutConstructingParts() throws IllegalAccessException { checkFactoryLookup(reflectedFactoryLookup());