From 4df9badc4f50a501fee117f43c653ee88e6f14fb Mon Sep 17 00:00:00 2001 From: Algent Date: Sat, 5 Sep 2026 11:32:24 +0200 Subject: [PATCH] feat: add Java render ID accessors --- JAVA_MIGRATION.md | 4 +- JAVA_MIGRATION_CONSUMER_AUDIT.md | 8 ++++ JAVA_MIGRATION_HANDOFF.md | 27 +++++++------ docs/API.md | 1 + docs/api/RENDER_ID.md | 40 +++++++++++++++++++ docs/migration/HISTORY.md | 17 ++++++++ .../test/ForgeEnvironmentSmokeTest.java | 5 +++ .../codechicken/multipart/TileMultipart$.java | 4 ++ .../codechicken/multipart/TileMultipart.java | 22 ++++++++++ .../multipart/TileMultipartRenderIdTest.java | 23 +++++++++++ .../multipart/examples/RenderIdExample.java | 13 ++++++ 11 files changed, 150 insertions(+), 14 deletions(-) create mode 100644 docs/api/RENDER_ID.md create mode 100644 src/test/java/codechicken/multipart/examples/RenderIdExample.java diff --git a/JAVA_MIGRATION.md b/JAVA_MIGRATION.md index 2be226d..0450a4e 100644 --- a/JAVA_MIGRATION.md +++ b/JAVA_MIGRATION.md @@ -535,7 +535,7 @@ existing Java `registerParts` overload still required Scala during javac resolut | `NormalOcclusionTest.apply(scala.collection.Traversable, scala.collection.Traversable)` and companion entry | `testBoxes(Iterable, Iterable)` | Implemented over the existing Java loop; both inputs snapshotted before geometry tests. [Guide and compiling example](docs/api/OCCLUSION.md#box-versus-box-queries). ForgeRelocationFMP/OpenComputers adoption remains pending | | `TileMultipart.loadParts(scala.collection.Iterable)` | `loadPartList(Collection)` | Implemented through the legacy virtual hook; binding, world notifications, input iteration and partial failure retained. [Loading guide](docs/api/PART_LOADING.md) | | `TileMultipart.partList_$eq(scala.collection.Seq)` | `setPartList(List)` | Implemented through the legacy setter; Java list copied without binding, null sentinel supported. GuideNH's old reflective name remains supported | -| `TileMultipart.renderID()` / `renderID_$eq(int)` | `getRenderID()` / `setRenderID(int)` | | +| `TileMultipart.renderID()` / `renderID_$eq(int)` and companion entries | `getRenderID()` / `setRenderID(int)` | Implemented over the same global value; four legacy entries deprecated. [Guide and compiling example](docs/api/RENDER_ID.md). Reading does not initialize the client renderer | | `TileMultipart.getOrConvertTile2(): scala.Tuple2` | Small immutable result type with named accessors | No consumer in the audited set calls this | Explicitly **not** renamed: `TMultiPart.world()`, `x()`, `y()`, `z()`, and `tile()`. These carry Scala accessor naming @@ -556,6 +556,8 @@ same-name overload there invites a silent wrong-overload bind. 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. +- [x] Add Java render-ID accessors with shared global-state/sentinel checks, retained static/companion entries and + explicit client initialization versus assignment semantics; [guide](docs/api/RENDER_ID.md). - [ ] 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 diff --git a/JAVA_MIGRATION_CONSUMER_AUDIT.md b/JAVA_MIGRATION_CONSUMER_AUDIT.md index 19ee284..3ce60ba 100644 --- a/JAVA_MIGRATION_CONSUMER_AUDIT.md +++ b/JAVA_MIGRATION_CONSUMER_AUDIT.md @@ -576,6 +576,14 @@ Forge test mod's 247 cases pass against the new implementation. The `+719` resca across 27 consumers. Schematica's private registry-map dependency is separate and remains pending; the supplied checkouts remain unchanged. Evidence: `run/migration-registration-reference/`. +Render-ID access is implemented as `TileMultipart.getRenderID()` / `setRenderID(int)`, with a +[lifecycle guide](docs/api/RENDER_ID.md). No direct use of the four old static/companion accessors or new-name collision +was found in FMP-related consumer source, and the frozen member inventory contains none of those descriptors. +Internal block/renderer calls retain the old paths and share the same global value; all four legacy entries remain +with deprecations. This addition does not replace GuideNH's renderer reflection or allocate/register a renderer. +JVM and dedicated-server checks preserve the -1 sentinel, unrestricted integer assignment and shared block state; +physical-client rendering remains a separate gate. Evidence: `run/migration-render-id-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 e45d62e..099bea3 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 248 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **224 Java +**566 plain-JVM tests and 249 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,13 +32,13 @@ 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: `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). +Latest API addition: `TileMultipart.getRenderID()` / `setRenderID(int)` share the existing global render ID, retaining +the -1 sentinel and unrestricted integer assignment without client initialization. Two JVM cases and one Forge case +were committed first as `3c22ab6`; one further JVM case and stronger Forge assertions cover the Java entry/example. +All 565 frozen JVM tests and the archived Forge test mod's 249 cases pass against the new implementation. All 443 +classes retain existing members, with two methods added and four legacy accessors deprecated; 17 ScalaSignature +payloads, 3,753 existing method bodies and 116 generated dumps are unchanged apart from deprecation metadata and build +versions. Evidence: `run/migration-render-id-reference/`; [guide](docs/api/RENDER_ID.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. @@ -57,12 +57,13 @@ 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 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. +The final API-table entry is `TileMultipart.getOrConvertTile2`, whose Scala tuple exposes the tile and conversion flag. +Characterize existing-tile, missing-tile and converted-placeholder behavior before adding a named Java result; retain +the legacy descriptor and clarify that a converted placeholder has not been installed in the world. Registry lookup +for Schematica remains a separate gap. -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 +Progress: nine of the ten Phase 9.1 rows now have implemented/documented Java replacements. The remaining row is +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/docs/API.md b/docs/API.md index a12014b..cc816d5 100644 --- a/docs/API.md +++ b/docs/API.md @@ -20,6 +20,7 @@ without converting the rest of its code to Java. | Assign stored parts during reconstruction, without binding or notifications | `setPartList(List)` — [storage assignment](api/PART_LOADING.md#storage-assignment) | | Test a candidate against a selected collection of parts | `testOcclusion(Collection, candidate)` — [occlusion queries and generated hooks](api/OCCLUSION.md) | | Test two groups of bounding boxes directly | `NormalOcclusionTest.testBoxes(Iterable, Iterable)` — [box-versus-box queries](api/OCCLUSION.md#box-versus-box-queries) | +| Read FMP's global render registration ID | `TileMultipart.getRenderID()` — [render-ID meaning, lifecycle and setter](api/RENDER_ID.md) | Each guide explains ownership, lifecycle, legacy replacements and limitations, and links to a compiling Java example exercised by the test suite. The loading/setter APIs are advanced reconstruction operations; ordinary placement and diff --git a/docs/api/RENDER_ID.md b/docs/api/RENDER_ID.md new file mode 100644 index 0000000..519db8c --- /dev/null +++ b/docs/api/RENDER_ID.md @@ -0,0 +1,40 @@ +# Multipart render ID + +[API index](../API.md) + +`TileMultipart.getRenderID()` and `setRenderID(int)` expose FMP's existing global block-render registration ID on +the `algent/java` branch. They have no minimum published dependency version yet. + +```java +int renderType = TileMultipart.getRenderID(); +``` + +The [compiling example](../../src/test/java/codechicken/multipart/examples/RenderIdExample.java) also builds with Scala +excluded from its classpath. Reading the ID does not initialize a client renderer, allocate an ID or access a tile. + +## Meaning and lifecycle + +The initial value is `-1`. FMP's client renderer obtains an ID from Forge's `RenderingRegistry` when the renderer +singleton is first initialized, normally from client postInit. `BlockMultipart.getRenderType()` and the renderer's +`getRenderId()` read that same shared value. The dedicated server normally retains `-1`. + +This is not a per-tile setting, a part type ID, a microblock material ID or a persistent identifier. Read the value +after normal client initialization when comparing render types; do not cache `-1` as the eventual client ID. + +The setter is for controlled render setup. It only assigns the existing field, accepting every `int` unchanged, +including negative values. It does not reserve an ID, register a handler, update Forge's mapping, synchronize clients +or rebuild rendering. FMP's later renderer initialization still performs its own assignment. Ordinary integrations +should read the value and leave registration to FMP. Make any intentional setup changes on the initialization/game +thread; there is no new synchronization guarantee. + +## Compatibility and validation + +The old static and companion `renderID()` / `renderID_$eq(int)` methods remain with unchanged descriptors and bodies, +and are deprecated in favor of the Java names. All readers and writers share the original storage. Existing internal +block/renderer calls still use their old paths. No direct old-accessor use or Java-name collision was found in the +supplied consumer sources or the frozen downstream member inventory; consumer checkouts are unchanged. + +JVM tests cover the initial sentinel, both legacy setters, Java accessors, signed integer boundaries and multiple +block instances reading the global value. Forge verifies the server sentinel and shared block state without loading +the client renderer. Frozen callers, class APIs and generated output are checked separately. Actual client allocation, +handler registration and GPU rendering remain [manual release checks](../../JAVA_MIGRATION_MANUAL_CHECKS.md). diff --git a/docs/migration/HISTORY.md b/docs/migration/HISTORY.md index 942fb1e..9c0a74b 100644 --- a/docs/migration/HISTORY.md +++ b/docs/migration/HISTORY.md @@ -1847,3 +1847,20 @@ differences belong in the [divergence ledger](../../JAVA_MIGRATION_DIVERGENCES.m 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/`. + +### 2026-09-05 — Java render-ID accessors + +- Committed two JVM cases and one Forge case as `3c22ab6` before changing production code. They pin the initial -1 + sentinel, shared static/companion storage, all integer values and block render-type reads. Saved the reference jar, + sources, 565 compiled JVM fixtures, the Forge test mod, reports and 116 generated dumps. +- Added `getRenderID()` / `setRenderID(int)` as adapters over existing accessors. The four old static/companion + accessors are deprecated, preserving their bodies/descriptors. Client renderer initialization/ID allocation and + internal block/renderer call sites are unchanged. The Java example compiles without Scala. +- Normal/clean build/style checks pass: 566 JVM and 249 Forge tests. All 565 frozen JVM fixtures and the archived + Forge mod's 249 cases pass without recompiling their callers. All 443 classes, 17 ScalaSignature payloads, + 3,753 existing method bodies and 116 generated dumps remain, with exactly two public methods and four deprecations + added; only expected deprecation/build-version metadata differs. +- Added a lifecycle guide and API index entry. No direct consumer use/name collision was found; the `+719` scan still + retains all 386 member/type/reflection rows across 27 consumers. Reference checkouts are unchanged. Physical-client + allocation/registration/rendering remain manual gates. Next API-table entry: the tile conversion result. + Evidence: `run/migration-render-id-reference/`. diff --git a/src/functionalTest/java/codechicken/multipart/test/ForgeEnvironmentSmokeTest.java b/src/functionalTest/java/codechicken/multipart/test/ForgeEnvironmentSmokeTest.java index cafd5b2..29ccc5d 100644 --- a/src/functionalTest/java/codechicken/multipart/test/ForgeEnvironmentSmokeTest.java +++ b/src/functionalTest/java/codechicken/multipart/test/ForgeEnvironmentSmokeTest.java @@ -64,10 +64,15 @@ class ForgeEnvironmentSmokeTest { void renderIdRemainsUninitializedOnTheDedicatedServerAndSharesBlockState() { int previous = TileMultipart.renderID(); assertEquals(-1, previous); + assertEquals(previous, TileMultipart.getRenderID()); try { TileMultipart.renderID_$eq(37); assertEquals(37, codechicken.multipart.handler.MultipartProxy.block().getRenderType()); assertEquals(37, codechicken.multipart.TileMultipart$.MODULE$.renderID()); + assertEquals(37, TileMultipart.getRenderID()); + TileMultipart.setRenderID(38); + assertEquals(38, codechicken.multipart.handler.MultipartProxy.block().getRenderType()); + assertEquals(38, TileMultipart.renderID()); } finally { TileMultipart.renderID_$eq(previous); } diff --git a/src/main/scala/codechicken/multipart/TileMultipart$.java b/src/main/scala/codechicken/multipart/TileMultipart$.java index 8acb19b..83bdf18 100644 --- a/src/main/scala/codechicken/multipart/TileMultipart$.java +++ b/src/main/scala/codechicken/multipart/TileMultipart$.java @@ -18,10 +18,14 @@ public final class TileMultipart$ { private TileMultipart$() {} + /** @deprecated Use {@link TileMultipart#getRenderID()}. Retained for compiled companion callers. */ + @Deprecated public int renderID() { return TileMultipart.renderID(); } + /** @deprecated Use {@link TileMultipart#setRenderID(int)}. Retained for compiled companion callers. */ + @Deprecated public void renderID_$eq(int value) { TileMultipart.renderID_$eq(value); } diff --git a/src/main/scala/codechicken/multipart/TileMultipart.java b/src/main/scala/codechicken/multipart/TileMultipart.java index 57d71b0..7a36608 100644 --- a/src/main/scala/codechicken/multipart/TileMultipart.java +++ b/src/main/scala/codechicken/multipart/TileMultipart.java @@ -746,10 +746,32 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile { private static int renderID = -1; + /** + * Returns FMP's global block-render registration ID. Initially -1; reading it does not initialize the client + * renderer or allocate an ID. This is shared state, not a per-tile or persistent part ID. + */ + public static int getRenderID() { + return renderID(); + } + + /** + * Assigns the global render ID, preserving all integer values including -1. Intended for controlled render setup; + * this only changes the stored value and does not allocate an ID, register a handler or update Forge's mapping. + * FMP's client renderer still performs its own allocation when first initialized. Use on the initialization/game + * thread, not as a per-tile rendering control. + */ + public static void setRenderID(int value) { + renderID_$eq(value); + } + + /** @deprecated Use {@link #getRenderID()}. Retained for existing static/companion callers. */ + @Deprecated public static int renderID() { return renderID; } + /** @deprecated Use {@link #setRenderID(int)}. Retained with unchanged shared-state behavior. */ + @Deprecated public static void renderID_$eq(int value) { renderID = value; } diff --git a/src/test/java/codechicken/multipart/TileMultipartRenderIdTest.java b/src/test/java/codechicken/multipart/TileMultipartRenderIdTest.java index 11f6f21..dab3b65 100644 --- a/src/test/java/codechicken/multipart/TileMultipartRenderIdTest.java +++ b/src/test/java/codechicken/multipart/TileMultipartRenderIdTest.java @@ -4,8 +4,31 @@ import static org.junit.jupiter.api.Assertions.assertEquals; import org.junit.jupiter.api.Test; +import codechicken.multipart.examples.RenderIdExample; + class TileMultipartRenderIdTest { + @Test + void javaAccessorsAndExampleShareAllLegacyReadersAndWriters() { + int previous = TileMultipart.getRenderID(); + BlockMultipart block = new BlockMultipart(); + try { + for (int value : new int[] { -1, 0, 37, Integer.MIN_VALUE, Integer.MAX_VALUE }) { + TileMultipart.setRenderID(value); + assertEquals(value, TileMultipart.renderID()); + assertEquals(value, TileMultipart$.MODULE$.renderID()); + assertEquals(value, RenderIdExample.multipartRenderType()); + assertEquals(value, block.getRenderType()); + TileMultipart.renderID_$eq(~value); + assertEquals(~value, TileMultipart.getRenderID()); + TileMultipart$.MODULE$.renderID_$eq(value); + assertEquals(value, TileMultipart.getRenderID()); + } + } finally { + TileMultipart.setRenderID(previous); + } + } + @Test void uninitializedRenderIdIsTheSharedMinusOneSentinel() { assertEquals(-1, TileMultipart.renderID()); diff --git a/src/test/java/codechicken/multipart/examples/RenderIdExample.java b/src/test/java/codechicken/multipart/examples/RenderIdExample.java new file mode 100644 index 0000000..fd86a63 --- /dev/null +++ b/src/test/java/codechicken/multipart/examples/RenderIdExample.java @@ -0,0 +1,13 @@ +package codechicken.multipart.examples; + +import codechicken.multipart.TileMultipart; + +/** Compiling example for docs/api/RENDER_ID.md; does not initialize the client renderer. */ +public final class RenderIdExample { + + private RenderIdExample() {} + + public static int multipartRenderType() { + return TileMultipart.getRenderID(); + } +}