From 542e910faf79f03b291566a1fc73fb0a4f6b5593 Mon Sep 17 00:00:00 2001 From: Algent Date: Sat, 5 Sep 2026 11:03:27 +0200 Subject: [PATCH] feat: add Java part factory registration --- JAVA_MIGRATION.md | 11 ++- JAVA_MIGRATION_ABI_INVENTORY.md | 5 ++ JAVA_MIGRATION_CONSUMER_AUDIT.md | 17 +++- JAVA_MIGRATION_HANDOFF.md | 30 +++---- README.md | 2 +- docs/API.md | 5 +- docs/api/PART_REGISTRATION.md | 88 +++++++++++++++++++ docs/migration/HISTORY.md | 22 +++++ .../examples/PartRegistrationExample.java | 37 ++++++++ .../test/PartRegistrationFunctionalTest.java | 21 ++++- .../multipart/MultiPartRegistry$.java | 7 ++ .../multipart/MultiPartRegistry.java | 52 +++++++++-- 12 files changed, 264 insertions(+), 33 deletions(-) create mode 100644 docs/api/PART_REGISTRATION.md create mode 100644 src/functionalTest/java/codechicken/multipart/examples/PartRegistrationExample.java diff --git a/JAVA_MIGRATION.md b/JAVA_MIGRATION.md index 3732bbf..2be226d 100644 --- a/JAVA_MIGRATION.md +++ b/JAVA_MIGRATION.md @@ -522,13 +522,13 @@ changes separate from mechanical compiler extraction, and do not add a deprecati #### 9.1 — Scala-typed signatures -Each row keeps its existing descriptor for binary compatibility and gains a Java-shaped sibling. The registry -`registerParts` sibling already exists and still needs the annotation and javadoc. +Each row keeps its existing descriptor for binary compatibility and gains a Java-shaped sibling. The registry's +existing Java `registerParts` overload still required Scala during javac resolution; `registerPartFactory` avoids it. | Deprecate | Java-shaped replacement | Notes | | --- | --- | --- | | `TileMultipart.partList(): scala.collection.Seq` | `jPartList(): java.util.List` | Getter deprecated; captured-sequence view documented in the [guide and compiling example](docs/api/PART_TRAVERSAL.md) | -| `MultiPartRegistry.registerParts(IPartFactory2, scala.collection.Seq)` | `registerParts(IPartFactory2, String...)` | Sibling already exists | +| `MultiPartRegistry.registerParts(IPartFactory2, scala.collection.Seq)` and companion entry | `registerPartFactory(IPartFactory2, String...)` | Implemented over existing Java registration; distinct name compiles without Scala. [Guide and example](docs/api/PART_REGISTRATION.md) also cover the retained Boolean/function adapters and their migration | | `MicroMaterialRegistry.getIdMap(): scala.Tuple2[]` | `materialCount(): int` plus existing `materialName(int)` and `getMaterial(int)` | Implemented with static/companion deprecation; [guide and compiling example](docs/api/MATERIAL_ENUMERATION.md). Consumer release/adoption remains pending | | `TileMultipart.operate(scala.Function1)` | `forEachPart(java.util.function.Consumer)` | Implemented through the legacy virtual hook; preserves captured traversal, detached-part filtering and callback failures. Lifecycle still calls `operate` | | `TileMultipart.occlusionTest(scala.collection.Seq, TMultiPart)` | `testOcclusion(Collection, TMultiPart)` | Implemented with an input snapshot and legacy virtual dispatch, including generated partial occlusion; [guide](docs/api/OCCLUSION.md). Distinct Java name avoids Scala overload resolution | @@ -554,10 +554,13 @@ same-name overload there invites a silent wrong-overload bind. generated partial-occlusion coverage; [guide and compiling example](docs/api/OCCLUSION.md). - [x] Add direct `testBoxes(Iterable, Iterable)` with eager input snapshots, ordered intersection callbacks and retained static/companion bridges; [migration guide](docs/api/OCCLUSION.md#box-versus-box-queries). +- [x] Add `registerPartFactory(IPartFactory2, String...)`, deprecate the remaining Scala sequence entries, and document + initialization/factory/payload contracts with a compiling example and real Forge initialization coverage. - [ ] For remaining siblings, compile external Java examples with Scala excluded from the compile classpath before finalizing names. The proposed `loadParts(Collection)` overload required `scala.collection.Iterable` during javac overload resolution; the implemented `loadPartList(Collection)` avoids that dependency. Apply this gate to the - remaining registration overloads as well as checking the emitted consumer bytecode. + remaining APIs as well as checking the emitted consumer bytecode. Registration hit the same constraint with + `scala.collection.Seq` and `scala.Function2`; `registerPartFactory` passes this gate. - [ ] Mark the remaining legacy entries above `@Deprecated` with javadoc naming a working replacement. - [ ] Confirm every original descriptor still exists in the ABI fixture after the change. - [ ] Document the supported API with compiling usage examples and an old-to-new migration guide. Validate Java diff --git a/JAVA_MIGRATION_ABI_INVENTORY.md b/JAVA_MIGRATION_ABI_INVENTORY.md index 0d1cdaa..8ccccd9 100644 --- a/JAVA_MIGRATION_ABI_INVENTORY.md +++ b/JAVA_MIGRATION_ABI_INVENTORY.md @@ -136,6 +136,11 @@ contract. Both old `apply(Traversable, Traversable)` entries remain, with deprec The shipping ForgeRelocationFMP/OpenComputers companion calls still require their exact descriptor until adoption; see the [migration guide](docs/api/OCCLUSION.md#box-versus-box-queries) and consumer ledger. +`MultiPartRegistry.registerPartFactory(IPartFactory2, String...)` now provides the Java registration entry without +Scala overload resolution. Both `registerParts(IPartFactory2, Seq)` entries are deprecated; all eight existing +registration descriptors remain. ProjectRed's sequence and ForgeRelocationFMP's function companion calls still need +their bridges until release/adoption. See the [registration guide](docs/api/PART_REGISTRATION.md). + `IDWriter`, ported on this branch, has **zero** downstream references. Its four deprecated Scala function accessors are not load-bearing and can be dropped. diff --git a/JAVA_MIGRATION_CONSUMER_AUDIT.md b/JAVA_MIGRATION_CONSUMER_AUDIT.md index 027af50..19ee284 100644 --- a/JAVA_MIGRATION_CONSUMER_AUDIT.md +++ b/JAVA_MIGRATION_CONSUMER_AUDIT.md @@ -491,12 +491,14 @@ behavior: ## Java API adoption ledger This ledger tracks migration of a specific legacy contract, not completion of an entire consumer's migration. -Material enumeration, tile collection/traversal access, tile loading/storage assignment, tile occlusion and box queries are implemented on +Factory registration, material enumeration, tile collection/traversal access, tile loading/storage assignment, tile occlusion and box queries 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. | Legacy contract | Consumer and inspected source | Supported replacement | Consumer migration/release | Target-pack adoption and removal gate | | --- | --- | --- | --- | --- | +| `MultiPartRegistry$.registerParts(IPartFactory2, Seq)` and existing array calls | ProjectRed `e173952e96a4`: transmission, expansion and fabrication proxies | `MultiPartRegistry.registerPartFactory` with existing `IPartFactory2` methods and unchanged IDs | Source patch and release pending; Boolean-factory proxies separately need the two-method adapter described in the guide | No migrated pack version verified; retain all registration bridges and external trait support | +| `MultiPartRegistry$.registerParts(Function2, Seq)` | ForgeRelocationFMP `49a810b8c63b`: proxy init registering `rfmp_frame` | `IPartFactory2` creating a fresh `FramePart` on both paths, registered through `registerPartFactory` | Source patch and release pending; preserve `rfmp_frame` and keep converter/pass-through registration | No migrated pack version verified; retain the function companion descriptor | | `MicroMaterialRegistry.getIdMap(): scala.Tuple2[]` | UtilitiesInExcess `3e107a1fe9bc15fcb6a808242ffda1354dac7c3a`: `FMPRecipeLoader.run`, `UEMultipartItem.getSubItems` | `materialCount()` with `materialName(int)` and, when needed, `getMaterial(int)` | Source patch and first released version pending; checkout used as reference only | No migrated pack version verified; retain the bridge | | `MicroMaterialRegistry.getIdMap(): scala.Tuple2[]` | Extra Utilities 1.2.12 decompiled reference: both NEI microblock handlers and `multipart.microblock.ItemMicroBlock` | Same ID-based Java enumeration | No editable upstream consumer in scope; retirement/replacement remains pending | Verify Extra Utilities is absent and its replacement uses the new API before retiring this dependency | | `TileMultipart.partList(): scala.collection.Seq` | ProjectRed `e173952e96a4`: illumination aggregation, packet indices and rendered-part lookup | `jPartList()` with unchanged indices, filters and aggregation | Source patch and release pending; Scala consumer code may remain Scala | No migrated pack version verified; retain the getter and external trait support | @@ -561,6 +563,19 @@ its generic input to accept box subclasses. The source check found the three box `testBoxes` collision. The installed `+719` rescan retains all 386 member/type/reflection rows from `+678` across 27 consumers. Evidence: `run/migration-box-occlusion-reference/`; [guide](docs/api/OCCLUSION.md#box-versus-box-queries). +Factory registration is implemented as `registerPartFactory(IPartFactory2, String...)`, with a +[guide and compiling example](docs/api/PART_REGISTRATION.md). A probe against the old Java overload family required +Scala `Seq`/`Function2` even for Java arrays and factories; the new name compiles without Scala. All eight legacy +static/companion entries retain their bodies/descriptors. Both `IPartFactory2` sequence entries are deprecated, and +the older Boolean/function adapter deprecations now identify the supported replacement. + +Four baseline Forge cases register through the legacy APIs during real initialization, then check ownership, +lazy construction, duplicate-prefix retention, array ownership, failure order and both NBT/packet paths. The new +entry runs through the same checks plus an example case. All 563 archived JVM tests and the byte-identical archived +Forge test mod's 247 cases pass against the new implementation. The `+719` rescan retains all 386 ABI/reflection rows +across 27 consumers. Schematica's private registry-map dependency is separate and remains pending; the supplied +checkouts remain unchanged. Evidence: `run/migration-registration-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 609d339..e45d62e 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 -**563 plain-JVM tests and 243 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **224 Java +**563 plain-JVM tests and 248 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **224 Java files and 9 Scala files / 747 nonblank Scala lines**. The packaged inventory has 443 classes. Review follow-up: restored packet-scheduler callback mutation behavior with the original Scala hash-map traversal, @@ -32,17 +32,18 @@ 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: `NormalOcclusionTest.testBoxes(Iterable, Iterable)` snapshots -both inputs before using the existing geometry loop. Three JVM baseline cases were committed first as `c7a3ed9`; -four more cases exercise the Java entry and compiling example. All 559 pre-change compiled JVM tests pass with their -recorded version. All 443 classes retain their existing members, with one method added and two legacy entries -deprecated; 17 ScalaSignature payloads, 3,751 existing method bodies and 116 generated dumps are unchanged apart from -expected deprecation metadata and build-version literals. The private copy helper's generic input alone widens to -accept box subclasses. Evidence: `run/migration-box-occlusion-reference/`; [guide](docs/api/OCCLUSION.md#box-versus-box-queries). +Latest API addition: `MultiPartRegistry.registerPartFactory(IPartFactory2, String...)` delegates to existing Java +registration. Four Forge baseline cases were committed first as `e4deac8`; the new entry runs through those contracts +plus a compiling example registered in real mod initialization. All 563 frozen JVM tests and the archived Forge test +mod's 247 cases pass against the new implementation. All 443 classes retain existing members, with one method added +and two legacy entries deprecated; 17 ScalaSignature payloads, 3,752 existing method bodies and 116 generated dumps +are unchanged apart from deprecation metadata and build-version literals. Evidence: `run/migration-registration-reference/`; +[guide](docs/api/PART_REGISTRATION.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. -Keep this compilation gate for remaining registration APIs; checking only imports or bytecode is insufficient. +The old `registerParts` family also required `scala.collection.Seq`/`scala.Function2` for Java array/factory arguments; +`registerPartFactory` compiles without Scala. Keep this gate for remaining APIs; import/bytecode checks alone are insufficient. Internal storage writes and reconstruction still dispatch through the old setter/loader hooks, not the Java siblings. The [API index](docs/API.md) orients consumers to entry points, compiling examples and migration status. Material @@ -56,13 +57,12 @@ 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 API candidate is multipart factory registration: characterize the `IPartFactory2`/Scala function -entries and their existing Java siblings, verify compilation without Scala before choosing names, and document factory -timing/registration semantics with an example and deprecations. Preserve static/companion descriptors for ProjectRed -and ForgeRelocationFMP. Registry lookup for Schematica is a separate capability to assess after registration. +The next API-table entry is `TileMultipart` render-ID accessors: add `getRenderID`/`setRenderID` over the existing +static state with baseline initial-value/shared-state checks and retained static/companion descriptors. Document that +this is a global render registration ID, not per-tile state. Registry lookup for Schematica remains a separate gap. -Progress: seven of the ten Phase 9.1 rows now have implemented/documented Java replacements. The remaining rows are -registration, render-ID accessors and the tuple-returning tile conversion result. That count excludes supported +Progress: eight of the ten Phase 9.1 rows now have implemented/documented Java replacements. The remaining rows are +render-ID accessors and the tuple-returning tile conversion result. That count excludes supported registry/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/README.md b/README.md index 054f4e3..b425eb1 100644 --- a/README.md +++ b/README.md @@ -16,4 +16,4 @@ If you only want to use the API and not modify it: Implementation of all parts of the API should be clean and easy in Java. The minecraft multipart mod is implemented in java as a test case. See the [Java API index](docs/API.md) for supported entry points, compiling examples, ownership/lifecycle contracts -and migration status. It links to material enumeration, part traversal, tile loading and occlusion guides. +and migration status. It links to factory registration, material enumeration, part traversal, tile loading and occlusion guides. diff --git a/docs/API.md b/docs/API.md index 54ef6aa..a12014b 100644 --- a/docs/API.md +++ b/docs/API.md @@ -12,6 +12,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) | | 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) | @@ -33,7 +34,7 @@ compile classpath for overload resolution, as the [loading guide](api/PART_LOADI | Area | Starting points | | --- | --- | | Define a custom part | Extend [TMultiPart](../src/main/scala/codechicken/multipart/TMultiPart.java); implement the required capability interfaces. The [built-in parts](../src/main/scala/codechicken/multipart/minecraft) show Java implementations | -| Register part factories and block converters | [MultiPartRegistry](../src/main/scala/codechicken/multipart/MultiPartRegistry.java): `registerParts(IPartFactory, String...)`, `registerParts(IPartFactory2, String...)`, `registerConverter(IPartConverter)` | +| Register block converters | [MultiPartRegistry](../src/main/scala/codechicken/multipart/MultiPartRegistry.java): `registerConverter(IPartConverter)`; part factories have a [separate Java guide](api/PART_REGISTRATION.md) | | Find, place and remove parts | [TileMultipart](../src/main/scala/codechicken/multipart/TileMultipart.java): `getTile`, `canPlacePart`, `addPart`, `remPart`. Retain the tile returned by changes because generated capabilities can replace the instance | | Construct a server composite tile from parts, or restore saved multipart NBT | [MultipartHelper](../src/main/scala/codechicken/multipart/MultipartHelper.java): `createTileFromParts(Iterable)`, `createTileFromNBT(World, NBTTagCompound)` | | Register microblock materials | [MicroMaterialRegistry](../src/main/scala/codechicken/microblock/MicroMaterialRegistry.java) and [BlockMicroMaterial](../src/main/scala/codechicken/microblock/BlockMicroMaterial.java) | @@ -48,7 +49,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. -Remaining registry bridges/documentation, generator/reflection replacements +Registry lookup/converter documentation, 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/PART_REGISTRATION.md b/docs/api/PART_REGISTRATION.md new file mode 100644 index 0000000..44ce8fd --- /dev/null +++ b/docs/api/PART_REGISTRATION.md @@ -0,0 +1,88 @@ +# Registering part factories from Java + +[API index](../API.md) + +Use `MultiPartRegistry.registerPartFactory(IPartFactory2, String...)` on the `algent/java` branch. It delegates to the +existing registry and avoids the Scala types in the `registerParts` overload family. This addition does not yet have +a minimum published dependency version. + +## Example and timing + +The [complete compiling example](../../src/functionalTest/java/codechicken/multipart/examples/PartRegistrationExample.java) +implements both `IPartFactory2.createPart` methods and registers one persistent type: + +```java +MultiPartRegistry.registerPartFactory(new PartRegistrationExample(), PartRegistrationExample.PART_TYPE); +``` + +Call from your mod's common `preInit` or `init` handler on both sides, before FMP closes registration in `postInit`. +FML must have an active mod container; that container becomes the owner returned by `getModContainer(type)`. +Registration stores the factory without constructing, loading, binding or placing a part. + +The example creates fresh, unbound instances whose `getType()` returns `yourmod:part`. Replace that sample ID and part +implementation with your own. Geometry, rendering and gameplay callbacks belong to the real part. Preserve already +published IDs exactly when migrating; adding a namespace to an existing ID changes its save/network identity. +Both single IDs and arrays are accepted. Multiple names can share a factory that selects the part class by name. + +## Factory and payload ownership + +`IPartFactory2` has two methods, so it is not a single-method lambda interface: + +| Construction path | Factory input | What happens next | +| --- | --- | --- | +| Server/NBT | `createPart(String, NBTTagCompound)` receives the original tag object | Normal reconstruction calls `part.load` with that same tag | +| Client/description | `createPart(String, MCDataInput)` receives the original input, after the registry ID | Normal reconstruction calls `part.readDesc` with that same input at its current cursor | + +A factory may inspect NBT or consume a packet discriminator to choose a class. There is no packet copy or rewind; +coordinate any consumed prefix with the part's `writeDesc` and `readDesc` protocol. FMP's microblock factory consumes +the material ID this way. Do not call `load` or `readDesc` in the factory merely to initialize the remaining payload, +because normal reconstruction calls them afterward. Return a fresh, unbound part for every supported name. + +Direct `MultiPartRegistry.loadPart` and `readPart` calls only construct the part; their caller remains responsible for +the following payload/lifecycle work. The deprecated `createPart(name, boolean)` passes a null NBT or packet argument; +factories reached through that old path must tolerate it. Neither registration entry adds eager factory validation. + +## Ordering and failures + +IDs are processed in array order. The array itself is not retained, so changing it afterward does not rename registered +parts. The factory object is retained. A duplicate ID throws immediately, leaving any earlier IDs from that call +registered and skipping the suffix. Registration is not transactional; fix duplicate IDs rather than retrying the +whole batch. Later server ID-map setup sorts registered names; registration order is not a stable network numeric ID. + +The new entry preserves the old Java array entry's failure order: a closed registry fails first, then the registry +enters its registering state and checks FML's active container, then it reads the array. Empty arrays still perform +the state/container checks; a null array fails after them. Supply a non-null factory and valid, unique non-null names; +the legacy implementation does not eagerly validate those values. Iterator conversion in the retained Scala sequence +entry still occurs before these checks, so malformed Scala inputs can fail earlier. + +Factory exceptions propagate when constructing parts, not during registration. A registration call does not probe +factory results or promise that a later NBT/packet will be accepted. + +## Migrating old callers + +- `IPartFactory2` callers: retain the factory and IDs, then call `registerPartFactory`. ProjectRed can keep its existing + server/NBT and client/packet methods. Scala code can pass a `String[]`/`Array[String]` as Java varargs using `: _*`. +- `IPartFactory` or Scala `(String, Boolean) => TMultiPart` callers: implement `IPartFactory2`; route the NBT method to + the old constructor with `false` and the packet method with `true`. Keep any side-specific class selection. A factory + that ignores the old Boolean, such as ForgeRelocationFMP's frame factory, can construct the same part class in both. +- Keep converter registration and trait registration separate. This change neither replaces `registerConverter` nor + completes ProjectRed's external microblock trait migration or Schematica's private registry-map migration. + +All eight old static/companion registration descriptors remain. Both `IPartFactory2` sequence entries are now +deprecated; the older Boolean/function entries were already deprecated and now point to the supported replacement. +The old Java array entries remain callable too. Prefer the new name for consumer Java source: a compiler probe found +that the old overload family required `scala.collection.Seq` and `scala.Function2` even for Java factory/string inputs. +The new example compiles with Scala excluded from its classpath. FMP still requires Scala internally. + +The consumer ledger records ProjectRed and ForgeRelocationFMP migration directions. Their reference checkouts were +not changed; consumer releases and target-pack adoption are still required before retiring the old entries. + +## Validation + +Forge tests register through all old entries during real mod initialization and exercise lazy construction, active +container ownership, array ownership, partial duplicate registration, failure ordering, both factory paths and shared +payload objects/cursors. The new entry runs through the same checks, and the example registers during initialization. +The archived pre-change Forge test mod and JVM fixtures run against the new implementation without recompiling their +callers. Existing member descriptors, method bodies, Scala signatures and generated output are checked separately. +The dedicated-server suite invokes the client construction method with a real packet; physical-client rendering and +full-pack adoption remain [manual release checks](../../JAVA_MIGRATION_MANUAL_CHECKS.md). diff --git a/docs/migration/HISTORY.md b/docs/migration/HISTORY.md index 88a37f9..942fb1e 100644 --- a/docs/migration/HISTORY.md +++ b/docs/migration/HISTORY.md @@ -1825,3 +1825,25 @@ differences belong in the [divergence ledger](../../JAVA_MIGRATION_DIVERGENCES.m ForgeRelocationFMP's combined geometry check. The installed `+719` rescan retains all 386 ABI/reflection rows across 27 consumers. Reference checkouts are unchanged; consumer release/adoption and manual client/pack checks remain pending. Next: multipart factory registration. Evidence: `run/migration-box-occlusion-reference/`. + +### 2026-09-05 — Java part factory registration + +- Committed four Forge baseline cases as `e4deac8`. Real mod initialization exercises all eight old registration + descriptors. Tests pin lazy construction, owner/array identity, partial duplicate failures, closed-state ordering, + Boolean side adapters and the NBT/packet factory handoff. Saved the pre-API jar, registry sources, 563 JVM fixtures, + the compiled Forge test mod, reports and 116 generated dumps before implementation. +- Added `registerPartFactory(IPartFactory2, String...)` as one forwarder over existing Java registration. The old + same-name overload family required Scala `Seq`/`Function2` even with Java factory/string arguments. The distinct + name and a complete Java factory example compile with Scala excluded. Both `IPartFactory2` sequence entries are + now deprecated; older Boolean/function deprecations point to the supported replacement. +- The new entry runs through the existing registration cases, and an additional Forge example case checks fresh, + unbound construction. Normal/clean build/style checks pass: 563 JVM and 248 Forge tests, all with zero failures, + errors or skips. All 563 frozen JVM fixtures and the byte-identical archived Forge test mod's 247 tests also pass + against the new implementation. The example ID sorts after built-ins so existing exact packet fixtures remain intact. +- All 443 classes, 17 ScalaSignature payloads, 3,752 existing method bodies and 116 generated dumps remain. Exactly + one public method and two deprecations are added; only expected deprecation/build-version metadata differs. +- Added the factory guide/index entry, documented payload ownership and migration directions for ProjectRed and + ForgeRelocationFMP, and retained all eight old registration descriptors. The `+719` scan retains all 386 member/type/ + reflection rows across 27 consumers. Reference checkouts and adoption status are unchanged. Registry lookup, + external trait migration and physical-client/pack checks remain separate. Next API-table entry: render-ID accessors. + Evidence: `run/migration-registration-reference/`. diff --git a/src/functionalTest/java/codechicken/multipart/examples/PartRegistrationExample.java b/src/functionalTest/java/codechicken/multipart/examples/PartRegistrationExample.java new file mode 100644 index 0000000..8255792 --- /dev/null +++ b/src/functionalTest/java/codechicken/multipart/examples/PartRegistrationExample.java @@ -0,0 +1,37 @@ +package codechicken.multipart.examples; + +import net.minecraft.nbt.NBTTagCompound; + +import codechicken.lib.data.MCDataInput; +import codechicken.multipart.MultiPartRegistry; +import codechicken.multipart.MultiPartRegistry.IPartFactory2; +import codechicken.multipart.TMultiPart; + +/** Compiling example for docs/api/PART_REGISTRATION.md; geometry and gameplay callbacks belong to the real part. */ +public final class PartRegistrationExample implements IPartFactory2 { + + public static final String PART_TYPE = "yourmod:part"; + + /** Call from the mod's common preInit/init handler, on both sides. */ + public static void register() { + MultiPartRegistry.registerPartFactory(new PartRegistrationExample(), PART_TYPE); + } + + @Override + public TMultiPart createPart(String name, NBTTagCompound nbt) { + return new ExamplePart(); + } + + @Override + public TMultiPart createPart(String name, MCDataInput packet) { + return new ExamplePart(); + } + + private static final class ExamplePart extends TMultiPart { + + @Override + public String getType() { + return PART_TYPE; + } + } +} diff --git a/src/functionalTest/java/codechicken/multipart/test/PartRegistrationFunctionalTest.java b/src/functionalTest/java/codechicken/multipart/test/PartRegistrationFunctionalTest.java index 3f1d0e1..6a76930 100644 --- a/src/functionalTest/java/codechicken/multipart/test/PartRegistrationFunctionalTest.java +++ b/src/functionalTest/java/codechicken/multipart/test/PartRegistrationFunctionalTest.java @@ -24,6 +24,7 @@ import codechicken.multipart.MultiPartRegistry$; import codechicken.multipart.MultiPartRegistry.IPartFactory; import codechicken.multipart.MultiPartRegistry.IPartFactory2; import codechicken.multipart.TMultiPart; +import codechicken.multipart.examples.PartRegistrationExample; import cpw.mods.fml.common.Loader; import cpw.mods.fml.common.ModContainer; import scala.collection.JavaConversions; @@ -36,7 +37,8 @@ class PartRegistrationFunctionalTest { (factory, types) -> MultiPartRegistry.registerParts(factory, types), (factory, types) -> MultiPartRegistry$.MODULE$.registerParts(factory, types), (factory, types) -> MultiPartRegistry.registerParts(factory, seq(types)), - (factory, types) -> MultiPartRegistry$.MODULE$.registerParts(factory, seq(types))); + (factory, types) -> MultiPartRegistry$.MODULE$.registerParts(factory, seq(types)), + MultiPartRegistry::registerPartFactory); private static final IPartFactory2 FACTORY = new IPartFactory2() { @Override @@ -88,6 +90,23 @@ class PartRegistrationFunctionalTest { NullPointerException.class, () -> MultiPartRegistry.registerParts(FACTORY, (String[]) null)); callsAfterRegistration = factoryCalls; + PartRegistrationExample.register(); + } + + @Test + void javaExampleRegistersDuringInitAndCreatesFreshUnboundPartsOnBothPaths() { + TMultiPart server = MultiPartRegistry.loadPart(PartRegistrationExample.PART_TYPE, new NBTTagCompound()); + TMultiPart another = MultiPartRegistry.loadPart(PartRegistrationExample.PART_TYPE, new NBTTagCompound()); + PacketCustom packet = packet(server); + TMultiPart client = MultiPartRegistry.readPart(packet); + assertEquals(PartRegistrationExample.PART_TYPE, server.getType()); + assertEquals(server.getType(), client.getType()); + assertNotSame(server, another); + assertNotSame(server, client); + assertNull(server.tile()); + assertNull(client.tile()); + assertSame(owner, MultiPartRegistry.getModContainer(server.getType())); + assertEquals(17, packet.readUByte(), "This example has no constructor discriminator"); } @Test diff --git a/src/main/scala/codechicken/multipart/MultiPartRegistry$.java b/src/main/scala/codechicken/multipart/MultiPartRegistry$.java index acf5b92..83ef646 100644 --- a/src/main/scala/codechicken/multipart/MultiPartRegistry$.java +++ b/src/main/scala/codechicken/multipart/MultiPartRegistry$.java @@ -30,11 +30,13 @@ public final class MultiPartRegistry$ { private MultiPartRegistry$() {} + /** @deprecated Implement {@link IPartFactory2} and use {@link MultiPartRegistry#registerPartFactory}. */ @Deprecated public void registerParts(IPartFactory partFactory, String... types) { MultiPartRegistry.registerParts(partFactory, types); } + /** @deprecated Implement {@link IPartFactory2} and use {@link MultiPartRegistry#registerPartFactory}. */ @Deprecated public void registerParts(scala.Function2 partFactory, scala.collection.Seq types) { @@ -45,6 +47,11 @@ public final class MultiPartRegistry$ { MultiPartRegistry.registerParts(partFactory, types); } + /** + * @deprecated Use {@link MultiPartRegistry#registerPartFactory(IPartFactory2, String...)}. Retained with its exact + * descriptor for compiled Scala consumers. + */ + @Deprecated public void registerParts(IPartFactory2 partFactory, scala.collection.Seq types) { MultiPartRegistry.registerParts(partFactory, types); } diff --git a/src/main/scala/codechicken/multipart/MultiPartRegistry.java b/src/main/scala/codechicken/multipart/MultiPartRegistry.java index 551181c..52f6c8c 100644 --- a/src/main/scala/codechicken/multipart/MultiPartRegistry.java +++ b/src/main/scala/codechicken/multipart/MultiPartRegistry.java @@ -30,7 +30,8 @@ public final class MultiPartRegistry { * Interface to be registered for constructing parts. Every instance of every multipart is constructed from an * implementor of this. * - * @deprecated Use IPartFactory2 + * @deprecated Implement {@link IPartFactory2} and use + * {@link MultiPartRegistry#registerPartFactory(IPartFactory2, String...)}. */ @Deprecated public interface IPartFactory { @@ -43,22 +44,29 @@ public final class MultiPartRegistry { TMultiPart createPart(String name, boolean client); } - /** Will replace IPartFactory in 1.8. */ + /** + * Factory with separate server/NBT and client/packet construction paths. Register during mod initialization with + * {@link MultiPartRegistry#registerPartFactory(IPartFactory2, String...)}. Registration does not call the factory. + * Return a fresh, unbound part with a stable registered {@link TMultiPart#getType()} for each supported name. + */ public interface IPartFactory2 { /** * Create a new server instance of the part with the specified type name identifier. * - * @param nbt The tag compound that will be passed to part.load, can be used to change the class of part - * returned + * @param nbt The same tag compound the reconstruction caller subsequently passes to part.load; may be inspected + * to select the part class. The registry does not call load. Legacy createPart(name, false) passes + * null, so factories used through that deprecated path must handle it. */ TMultiPart createPart(String name, NBTTagCompound nbt); /** * Create a new client instance of the part with the specified type name identifier. * - * @param packet The packet that will be passed to part.readDesc, can be used to change the class of part - * returned + * @param packet The same input the reconstruction caller subsequently passes to part.readDesc, positioned after + * the registry ID. A factory may consume a constructor discriminator; readDesc continues at the + * resulting cursor without a rewind. The registry does not call readDesc. Legacy createPart(name, + * true) passes null. */ TMultiPart createPart(String name, MCDataInput packet); } @@ -94,7 +102,7 @@ public final class MultiPartRegistry { /** * Register a part factory with an array of types it is capable of instantiating. Must be called before postInit. * - * @deprecated Use IPartFactory2 + * @deprecated Implement {@link IPartFactory2} and use {@link #registerPartFactory(IPartFactory2, String...)}. */ @Deprecated public static void registerParts(IPartFactory partFactory, String... types) { @@ -115,7 +123,7 @@ public final class MultiPartRegistry { /** * Scala function version of registerParts. * - * @deprecated Use IPartFactory2 + * @deprecated Implement {@link IPartFactory2} and use {@link #registerPartFactory(IPartFactory2, String...)}. */ @Deprecated public static void registerParts(scala.Function2 partFactory, @@ -134,13 +142,21 @@ public final class MultiPartRegistry { }, types); } - /** Scala va-args version of registerParts. */ + /** + * Scala va-args version of registerParts. + * + * @deprecated Use {@link #registerPartFactory(IPartFactory2, String...)} with Java strings/arrays. Retained for + * existing Scala callers; sequence conversion still precedes registry-state checks. + */ + @Deprecated public static void registerParts(IPartFactory2 partFactory, scala.collection.Seq types) { registerParts(partFactory, JavaConversions.seqAsJavaList(types).toArray(new String[0])); } /** * Register a part factory with an array of types it is capable of instantiating. Must be called before postInit. + * Prefer {@link #registerPartFactory(IPartFactory2, String...)} in Java sources compiled without Scala: this legacy + * overload family contains Scala parameter types that javac may require during overload resolution. */ public static void registerParts(IPartFactory2 partFactory, String... types) { if (loaded()) { @@ -164,6 +180,24 @@ public final class MultiPartRegistry { } } + /** + * Registers a factory for stable part identifiers during a mod's preInit/init, before FMP's postInit closes the + * registry. Requires FML's active mod container, which becomes the owner of each ID. Register on both sides using + * the same IDs; construction later selects the NBT/server or packet/client factory method. + * + *

+ * Processes IDs in array order without calling the factory or retaining the array. A duplicate throws immediately; + * earlier registrations from this call remain. Factory and ID validity are not eagerly checked, so callers must + * supply a non-null factory and valid non-null, stable names. A null array fails after the existing state/container + * checks. Empty arrays still perform those checks. This entry retains all legacy failure/state behavior. + * + * @param partFactory factory retained for later construction; it does not load, bind or place parts at registration + * @param types unique persistent type names; preserve published names when migrating existing parts + */ + public static void registerPartFactory(IPartFactory2 partFactory, String... types) { + registerParts(partFactory, types); + } + /** Register a part converter instance. */ public static void registerConverter(IPartConverter c) { for (Block block : c.blockTypes()) {