feat: add client multipart preview API

This commit is contained in:
Algent committed 2026-09-16 12:44:33 +02:00
1 parent a995189f92
commit e13389f26f
21 files changed
+316 -33

No files matched your search

+1
View File
@@ -48,6 +48,7 @@ Existing reflective binaries remain supported until consumer release and pack ad
| Run callbacks only on parts still owned by the tile | `forEachPart(Consumer)` - [callback and override behavior](api/PART_TRAVERSAL.md#callback-behavior) |
| Rebuild parts on an already prepared composite tile | `loadPartList(Collection)` - [part loading](api/PART_LOADING.md) |
| Select client/server tile capabilities before preparing state and loading | `MultipartGenerator.generateCompositeTile(TileEntity, Iterable, boolean)` - [staged generation and reflection migration](api/COMPOSITE_GENERATION.md) |
| Build and render an uninstalled client tile from saved multipart NBT | `MultipartHelper.createPreviewTileFromNBT(World, NBTTagCompound)` - [client preview lifecycle and reflection migration](api/CLIENT_PREVIEW.md) |
| 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) |
+4
View File
@@ -111,6 +111,10 @@ Direct typed calls are the intended end state. Reflection snippets in older guid
options, not the migration target. For optional integration, isolate FMP-typed code in a compatibility class loaded
only after mod-presence and version checks, and test both the absent and present cases.
Saved multipart client previews can use `MultipartHelper.createPreviewTileFromNBT` plus the existing
`MultipartRenderer.renderWorldBlock`; see the [client preview guide](api/CLIENT_PREVIEW.md). Custom `IPartFactory2`
implementations opt in through `createPartForClientPreview` when they can build their client variant from saved NBT.
## Will I have to migrate again?
No, if you migrate to the documented Java surface. That is the point of shipping it alongside the old one.
+68
View File
@@ -0,0 +1,68 @@
# Building client multipart previews
[Java API index](../API.md)
Use `MultipartHelper.createPreviewTileFromNBT(World, NBTTagCompound)` to rebuild saved multipart NBT as an
uninstalled client tile. It replaces the registry reflection, client-part promotion, Scala collection conversion,
composite generation and manual loading previously needed by preview integrations.
```java
TileMultipart preview = MultipartHelper.createPreviewTileFromNBT(clientWorld, savedTile);
if (preview == null) {
return false;
}
return MultipartRenderer.renderWorldBlock(
blockAccess, x, y, z, multipartBlock, multipartBlock.getRenderType(), renderBlocks);
```
The [compiling example](../../src/functionalTest/java/codechicken/multipart/examples/ClientPreviewExample.java) uses
only Java API types. Keep this code in a client integration class because `MultipartRenderer` is client-only.
## Reconstruction contract
The helper accepts only a `savedMultipart` tag with at least one supported part. It preserves part order, loads each
part from its original tag, generates the required client tile traits, restores tile coordinates and NBT state, and
binds the parts. With a client world it then calls `onWorldJoin`, broadcasts a local part change, marks the render and
rebuilds the client render cache. With a null world it creates a worldless staged preview; render caches initialize
lazily.
A non-null world must have `isRemote == true`. The helper does not validate placement, install the tile in a chunk,
notify neighbors, recalculate lighting or send packets. It reads the supplied NBT without mutating it.
Reconstruction is all-or-nothing. A foreign or empty tag, missing factory, or factory that does not support preview
construction returns null. Factory, part loading and generated-trait failures propagate.
## Factory support
`IPartFactory2.createPartForClientPreview(String, NBTTagCompound)` constructs the client variant needed for saved NBT.
The default returns null, so an existing packet-aware factory does not accidentally treat NBT as a description
packet. Override it when the factory can return a fresh, unbound client part without consuming or changing the tag:
```java
@Override
public TMultiPart createPartForClientPreview(String name, NBTTagCompound tag) {
return new ExamplePart();
}
```
The helper calls `part.load(tag)` afterward. Legacy Boolean and Scala-function factory adapters already route preview
construction through their client branch. Built-in microblock factories resolve the saved material name and construct
the generated client microblock before loading its shape and other state.
## Consumer migration
- Schematica can replace its private registry map, `MicroblockClass.create`, Scala iterable conversion, companion
generator, reflected loader and per-part refresh loop with this helper.
- GuideNH can replace its server-tile reconstruction, `TileMultipartClient` promotion, microblock promotion, raw part
list assignment and reflected reload/finalization with this helper. Its material export and part-stat traversal can
use the separate typed APIs linked from the index.
Optional integrations should isolate their FMP-typed client class behind mod-presence and supported-version checks.
Keep the old reflection fallback only while supporting an older FMP release that lacks this API.
## Validation limits
JVM checks pin the public method and factory opt-in default. Forge coverage checks legacy factory adapters plus ordered
NBT loading into an unbound generated client tile. The example compiles with Scala excluded. Physical-client checks
remain required for generated microblock client traits, custom preview factory implementations and GPU rendering; see
the [manual release checks](../migration/MANUAL_CHECKS.md).
+6 -2
View File
@@ -54,6 +54,10 @@ that must set state between generation and loading.
## Schematica and GuideNH migration
For saved-NBT client previews, prefer the complete [client preview helper](CLIENT_PREVIEW.md). It owns client part
construction, generation, loading and local render preparation. Use this lower-level generator for reconstruction
flows that need to prepare or reuse a candidate tile themselves.
Prefer the direct call `MultipartGenerator.generateCompositeTile(candidate, parts, client)`, as in the compiling
example. Gate optional typed integration code as described in the [API index](../API.md#direct-calls-and-optional-integration).
For temporary interoperability with an existing reflective integration, the method can also be resolved with:
@@ -67,10 +71,10 @@ TileMultipart tile = (TileMultipart) generate.invoke(null, candidate, parts, cli
An optional integration can obtain the owner through `Class.forName("codechicken.multipart.MultipartGenerator")`.
Pass a Java list directly and cache the method during integration initialization.
- **Schematica:** remove `JavaConversions.collectionAsScalaIterable` from generation; keep material resolution,
- **Older Schematica integrations:** remove `JavaConversions.collectionAsScalaIterable` from generation; keep material resolution,
[factory lookup](FACTORY_LOOKUP.md), side-specific microblock construction, per-part NBT loading and rejection when
any part is missing. Preserve its following tile `readFromNBT`, `loadPartList(parts)` and per-part notification order.
- **GuideNH:** keep promotion of parts to their client variants, then use a Java list for generation. Preserve its
- **Older GuideNH integrations:** keep promotion of parts to their client variants, then use a Java list for generation. Preserve its
same-instance branch, copying of coordinates/world/block state, storage assignment where required, loading,
`notifyTileChange` and `markRender`. Generation does not perform any of those steps automatically.
+5 -6
View File
@@ -24,12 +24,13 @@ Most consumers should continue using `loadPart(name, nbt)` or `readPart(input)`.
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
Factory lookup is useful when a supported factory subtype provides a specialized construction method. Older 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.
See [microblock creation](MICROBLOCK_CREATION.md) for side selection, material traits and caller-owned shape/NBT state.
New preview integrations should use the complete [client preview helper](CLIENT_PREVIEW.md). See
[microblock creation](MICROBLOCK_CREATION.md) when a caller specifically needs an unbound microblock.
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,
@@ -58,10 +59,8 @@ Cache the `Method` during integration initialization as Schematica already does.
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 the
[static Java composite generator](COMPOSITE_GENERATION.md). Material lookup, saved part order,
shape/material loading, tile NBT and subsequent notifications remain unchanged.
This removes only the registry-map Scala dependency. The [client preview helper](CLIENT_PREVIEW.md) replaces the
complete Schematica reconstruction path when the minimum FMP version can require it.
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
+5 -1
View File
@@ -27,7 +27,8 @@ using geometry or rendering and before [preparing/loading a composite tile](COMP
Resolve the intended material before construction. A later `part.load(tag)` or `material_$eq` updates stored material
but does not regenerate the class's material traits. For NBT reconstruction, resolve `tag.getString("material")`,
create the correctly sided part with that ID, then call `load(tag)`. Ordinary `MultiPartRegistry.loadPart` selects the
server/NBT path; it does not provide client preview construction.
server/NBT path. The complete [client preview helper](CLIENT_PREVIEW.md) selects the registered factory's preview path
and performs the remaining tile reconstruction.
Call after factory/trait registration and material-map initialization, on the initialization/game thread. Numeric IDs
belong to the active map and may change across sessions or a multiplayer handshake; persist material names, not IDs.
@@ -50,6 +51,9 @@ or authorize removing Scala-signature support before consumer release/adoption.
## GuideNH migration
GuideNH preview reconstruction should use the complete [client preview helper](CLIENT_PREVIEW.md). The direct
generator remains useful when code specifically needs to create or transform one unbound microblock.
GuideNH `7d8fb44e77b9` explicitly resolves the companion's `create(MicroblockClass, int, boolean)` and invokes it on
`MODULE$`. It does not automatically discover the existing static method. Prefer the direct typed creation example
below, with [gated optional integration](../API.md#direct-calls-and-optional-integration). The following cache is only
+5 -3
View File
@@ -12,6 +12,8 @@ loader itself does not choose traits, promote a tile or install it in the world.
For separate client/server generation before world/NBT setup and loading, use the
[staged composite-generation API](COMPOSITE_GENERATION.md).
For an uninstalled client tile reconstructed from saved multipart NBT, use the complete
[client preview helper](CLIENT_PREVIEW.md) instead of assembling these steps.
## Loading a prepared tile
@@ -85,11 +87,11 @@ The Java loader has a distinct name deliberately: the initially planned `loadPar
`loadPartList` lets the example compile without Scala on the consumer compile classpath, while retaining the legacy
hook and its name. This changes the planned Java name, not any existing entry point.
For GuideNH's migration, use a Java list of the promoted client parts, retain its existing world/position setup,
For an older GuideNH-compatible path, use a Java list of the promoted client parts, retain its existing world/position setup,
replace the raw setter with `setPartList`, and call the Collection loader. Preserve its following `notifyTileChange`
and `markRender` steps. Its tile generator now has a [static Java replacement](COMPOSITE_GENERATION.md); other
reflective dependencies remain. Schematica can select the Collection loader and pass its existing Java list directly,
using the separate [factory lookup](FACTORY_LOOKUP.md) and generation entries to remove those Scala dependencies.
reflective dependencies remain. Schematica can select the Collection loader and pass its existing Java list directly.
New versions of both integrations should use the [client preview helper](CLIENT_PREVIEW.md).
## Validation and release gates
+7 -3
View File
@@ -12,7 +12,8 @@ Schematica's replacement for private registry-map reflection.
## 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:
implements both required `IPartFactory2.createPart` methods, opts into saved-NBT client previews, and registers one
persistent type:
```java
MultiPartRegistry.registerPartFactory(new PartRegistrationExample(), PartRegistrationExample.PART_TYPE);
@@ -29,12 +30,14 @@ Both single IDs and arrays are accepted. Multiple names can share a factory that
## Factory and payload ownership
`IPartFactory2` has two methods, so it is not a single-method lambda interface:
`IPartFactory2` has two abstract methods, so it is not a single-method lambda interface. Its third method is an
optional default:
| 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 |
| Client preview/NBT | `createPartForClientPreview(String, NBTTagCompound)` receives the original tag object | [Preview reconstruction](CLIENT_PREVIEW.md) calls `part.load` with that same tag; the default returns null |
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
@@ -64,7 +67,8 @@ 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 `: _*`.
server/NBT and client/packet methods. Override `createPartForClientPreview` only when saved NBT can select a fresh
client variant. 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.
+15 -16
View File
@@ -170,10 +170,10 @@ 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](../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.
The branch now offers `MultipartHelper.createPreviewTileFromNBT` to replace Schematica's private registry map,
microblock construction, Scala collection, generator and loader reflection as one all-or-nothing preview operation.
The lower-level `MultiPartRegistry.getPartFactory(String): IPartFactory2` remains available for specialized callers.
Existing private fields, companions and descriptors remain for released consumers until adoption.
`ButtonPart.setOrientation(int, ForgeDirection): void` now replaces Et Futurum's four reflective array writes and
keeps the two direction maps consistent; [guide](../api/BUTTON_ORIENTATIONS.md). The existing public mutable static
@@ -763,7 +763,7 @@ behavior:
This ledger tracks migration of a specific legacy contract, not completion of an entire consumer's migration.
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
client preview reconstruction, tile occlusion and box queries, render-ID accessors and named tile conversion results are implemented on
`algent/java`. The [API index](../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.
@@ -780,11 +780,11 @@ tied to a released minimum dependency version. Unlisted contracts remain governe
| `TileMultipart.partList(): scala.collection.Seq` | OpenComputers `2c00f79be24b`: cable/print/network searches and aggregation | `jPartList()` with the same search/aggregation semantics | Source patch and release pending | No migrated pack version verified; retain the getter |
| `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` | Call `loadPartList(parts)` directly with its existing Java part list | Source patch and release pending; registry lookup and Java tile generation available separately | No migrated pack version verified; retain the Scala loader descriptor |
| Private `MultiPartRegistry$` Scala `typeMap` field and `Map.get` / `Option` | Schematica `3b03ee937953`: `nbt.ForgeMultipart.init` and `createPart` | Call public static `MultiPartRegistry.getPartFactory(partID)` directly; keep material lookup, `MicroblockClass.create(client, materialId)` and whole-preview rejection | Source patch/release pending; lookup and Java tile generation implemented | No migrated pack version verified; retain the exact private live Scala-map field |
| `MultipartGenerator$.generateCompositeTile(TileEntity, scala.collection.Iterable, boolean)` | Schematica `3b03ee937953` exact reflection; GuideNH `7d8fb44e77b9` static-first assignability matcher | Static `MultipartGenerator.generateCompositeTile(TileEntity, java.lang.Iterable, boolean)` with Java parts; retain subsequent state setup/loading | Source patches/releases pending; preserve client part construction, candidate-reuse branch and notification order | No migrated pack version verified; retain the companion and Scala descriptor |
| `MicroblockGenerator$.create(MicroblockClass, int, boolean)` exact reflection and private shape copy | GuideNH `7d8fb44e77b9`: `getMicroblockGeneratorCreate`, `promoteMicroblockToClient` | Existing static `MicroblockGenerator.create` with the same parameter types/order; recreate family/material and restore encoded shape through public API | Source patch/release pending; guide/example tested on server, physical client and custom shape-setter overrides require adoption checks | No migrated pack version verified; retain companion singleton and exact descriptor |
| `TileMultipart.partList(): scala.collection.Seq` plus reflective getter/setter/loading | GuideNH `7d8fb44e77b9`: `Ae2ForgeMultipartBridge`, `ForgeMultipartHelpers` | `createPreviewTileFromNBT` for preview reconstruction; `jPartList()` for later read-only traversal | Source patch and release pending; material export and part statistics still use their separate typed APIs | Retain the legacy getter/setter/loader until released adoption |
| `TileMultipart.loadParts(scala.collection.Iterable)` exact reflection | Schematica `3b03ee937953`: `nbt.ForgeMultipart` | `MultipartHelper.createPreviewTileFromNBT`; [complete preview contract](../api/CLIENT_PREVIEW.md) | Source patch and release pending; replace the whole reconstruction chain rather than one reflected method | 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` | `MultipartHelper.createPreviewTileFromNBT`; factories opt in through `createPartForClientPreview` | Source patch/release pending; all-or-nothing lookup, client construction and loading are implemented | No migrated pack version verified; retain the exact private live Scala-map field |
| `MultipartGenerator$.generateCompositeTile(TileEntity, scala.collection.Iterable, boolean)` | Schematica `3b03ee937953` exact reflection; GuideNH `7d8fb44e77b9` static-first assignability matcher | `createPreviewTileFromNBT` for saved previews; static `MultipartGenerator.generateCompositeTile` for other staged reconstruction | Source patches/releases pending; preview helper preserves saved order and owns client construction/loading | No migrated pack version verified; retain the companion and Scala descriptor |
| `MicroblockGenerator$.create(MicroblockClass, int, boolean)` exact reflection and private shape copy | GuideNH `7d8fb44e77b9`: `getMicroblockGeneratorCreate`, `promoteMicroblockToClient` | `createPreviewTileFromNBT` for whole previews; existing static `MicroblockGenerator.create` for individual unbound parts | Source patch/release pending; physical client and custom preview factories require adoption checks | No migrated pack version verified; retain companion singleton and exact descriptor |
| Private `BlockMicroMaterial.block` / `meta` accessor mixin and reflective material query | GuideNH `7d8fb44e77b9`: `AccessorBlockMicroMaterial`, `resolvePrimaryMicroblockId` | Direct `jPartList()`, `Microblock.material()`, `getMaterial(int)`, `BlockMicroMaterial.block()` / `meta()`; [typed example](../api/MATERIAL_ACCESS.md) | Source patch/release pending; remove mixin, retain export filtering/failure policy, validate getter overrides and optional loading | No migrated pack version verified; retain private fields |
| Reflective mutation of `ButtonPart.metaSideMap` / `sideMetaMap` | Et Futurum Requiem `78a5744dfd33`: `compat.CompatMisc.runModHooksInit` | Two direct `ButtonPart.setOrientation(int, ForgeDirection)` calls; [mapping and lifecycle guide](../api/BUTTON_ORIENTATIONS.md) | FMP API/example complete; consumer source patch and first released version pending | Retain both public mutable arrays until the migrated release is in the target pack and a fresh scan confirms no legacy access |
| Reflective mutation of private `ItemSaw.harvestLevel` | IguanaTweaksTConstruct `2bc09889d3e2`: `modcompat.fmp.IguanaFMPCompat.postInit` | Read `harvestLevel()` and call `setHarvestLevel(int)`; [state and lifecycle guide](../api/SAW_STRENGTH.md) | FMP API/example complete; consumer source/lifecycle patch and first released version pending | Retain the private field until the migrated release is in the target pack; ensure Iguana runs before ForgeMicroblock post-init and rescan for legacy access |
@@ -814,12 +814,11 @@ The ledger records no completed consumer releases or pack adoption; update those
ownership, partial-registration failure policy, and both NBT/packet construction paths. All legacy registration
entries remain; Schematica's private live Scala map is a separate dependency. See [registration](../api/PART_REGISTRATION.md).
- No supplied direct legacy render-ID or tuple-result caller was found. Existing tile-only `getOrConvertTile` users
need no rename. New [render-ID](../api/RENDER_ID.md) accessors do not allocate/register a renderer or replace
GuideNH renderer reflection; [conversion results](../api/TILE_CONVERSION.md) still describe uninstalled placeholders.
- [Staged generation](../api/COMPOSITE_GENERATION.md) does not copy/load/install parts automatically. Preserve exact
candidate reuse and subsequent setup. GuideNH must change both its cached companion singleton and method owner
when adopting [static microblock creation](../api/MICROBLOCK_CREATION.md). Capture factory, material and shape
before generation callbacks; restoring shape through public setters can invoke overrides that raw field writes bypassed.
need no rename. New [render-ID](../api/RENDER_ID.md) accessors do not allocate/register a renderer;
[conversion results](../api/TILE_CONVERSION.md) still describe uninstalled placeholders.
- Saved client previews should use the complete [preview helper](../api/CLIENT_PREVIEW.md). The lower-level
[staged generator](../api/COMPOSITE_GENERATION.md) still does not copy/load/install parts automatically and remains
available for reconstruction flows that need candidate reuse or custom setup.
- GuideNH's [typed material getters](../api/MATERIAL_ACCESS.md) likewise honor overrides that raw mixin fields
bypassed. Preserve first-usable-part order, export filtering and failure behavior; validate custom overrides and
optional-mod loading. Physical-client construction and GPU previews remain release checks.
+2
View File
@@ -91,6 +91,7 @@ Other retained `$class` bridges and `MODULE$` companions are not covered by this
| `TileMultipart` | `hasDynamicParts` (false by default), `renderStatic`, `renderDynamic` and `randomDisplayTick` hooks for dispatching generated overrides through a stable superclass |
| `MultipartMixinFactory` | Four additional static forwarders: `onCompiled`, `autoCompleteJavaTrait` and the two mangled `ASMMixinFactory` parent helpers. Scala emitted them when the base became Java with its original public JVM access; the Java facade retains them. Existing facade entries are unchanged. |
| `MultipartEventHandler` / `MultipartEventHandler$` | Public `playerLoggedOut(PlayerLoggedOutEvent)` and `playerCloned(PlayerEvent.Clone)` event handlers for placement-modifier state cleanup and transfer |
| `MultipartHelper` | `createPreviewTileFromNBT(World, NBTTagCompound)` builds an uninstalled client composite directly from saved multipart NBT and rejects unsupported parts as a whole |
Previously abstract JVM interface methods now have Java defaults, allowing inheritance without Scala forwarders:
@@ -105,6 +106,7 @@ Previously abstract JVM interface methods now have Java defaults, allowing inher
| `MicroMaterialRegistry.IMicroMaterial` | `loadIcons`, `canRenderInPass`, `isSolid` |
| `TScheduledPacketPart` | `writeScheduled`, `readScheduled` |
| `PlacementGrid` | `render`, `drawLines`, `glTransformFace` |
| `MultiPartRegistry.IPartFactory2` | `createPartForClientPreview`; defaults to unsupported, while legacy Boolean/function adapters and built-in microblock factories construct their client variant |
`ItemSaw` consequently no longer declares `getMaxCuttingStrength`; ordinary calls still resolve to the default,
but declared-member reflection differs. The same distinction applies to the two `MissingMicroMaterial$` methods above.
+2 -2
View File
@@ -73,8 +73,8 @@ entries complete.
| --- | --- | --- | --- | --- |
| [ ] | Saw a ProjectRed **Inverted White Lamp** into cover, hollow cover, nook/corner and strip/post shapes; test face, corner, edge and centre-post placement | ProjectRed **Inverted White Lamp**; ordinary lamps and **White Illumar** do not exercise this registration path | The lamps generate, use the correct bounds, render and light correctly | `MicroblockGenerator.registerTrait` Scala trait path / shape factory facades |
| [ ] | Place and break OpenComputers **Cable** and a **3D Print**, ProjectBlue **Control Panel** (size suffix varies), and AE2 **ME Glass Cable**; share their block space with a compatible cover | Use a **Stone Cover** with each named consumer part | No `NoSuchMethodError` or `AbstractMethodError` in the log | retained `$class` bridges |
| [ ] | Load and render a schematic containing an ordered mixed multipart tile | Schematica; capture an AE2 **ME Glass Cable** with a **Stone Cover** and ProjectRed **Red Alloy Wire** on different faces | Every part appears in the preview in the saved order; the integration does not silently disable itself | Schematica private registry-map reflection, `MicroblockClass.create`, and tile NBT reconstruction |
| [ ] | Open a GuideNH scene containing a multipart tile and export its part/material data | GuideNH; use the same **ME Glass Cable + Stone Cover + Red Alloy Wire** composite | The preview, material data and part statistics are complete | companion reflection, `MicroblockGenerator$.create`, `Microblock.microClass/material/shape`, `partList_$eq`, and `BlockMicroMaterial` mixin fields |
| [ ] | Load and render a schematic containing an ordered mixed multipart tile | Schematica; capture an AE2 **ME Glass Cable** with a **Stone Cover** and ProjectRed **Red Alloy Wire** on different faces | Every part appears in the preview in the saved order; the integration does not silently disable itself | `createPreviewTileFromNBT`, factory preview callbacks and `MultipartRenderer.renderWorldBlock` |
| [ ] | Open a GuideNH scene containing a multipart tile and export its part/material data | GuideNH; use the same **ME Glass Cable + Stone Cover + Red Alloy Wire** composite | The preview, material data and part statistics are complete | `createPreviewTileFromNBT`, typed part/material traversal and `MultipartRenderer.renderWorldBlock` |
| [ ] | Place FMP buttons on every supported face with Et Futurum loaded | Convert a vanilla **Stone Button** by adding a **Stone Cover**; repeat its supported orientations with Et Futurum Requiem installed | Button orientation matches the fixed vanilla behavior | supported `ButtonPart.setOrientation`; legacy arrays until consumer adoption |
| [ ] | With Iguana harvest-level tweaks enabled, inspect and use the Stone, Iron, Diamond, Ardite, Cobalt and Manyullyn saws against materials spanning their configured tiers | Forge Multipart supplies the first three saws; Iguana Tweaks for Tinkers' Construct supplies **Ardite**, **Cobalt** and **Manyullyn Saws** | Tooltips, saw textures and cutting recipes use the remapped tier; weaker saws do not gain the cached strongest-saw exemption | supported `ItemSaw.setHarvestLevel`; legacy field until consumer adoption |
| [ ] | Use OpenComputers **3D Printer** to make a **3D Print** with different off/on shapes that both fit beside a cover; place it with the cover and right-click to toggle | OpenComputers **3D Printer**, its resulting **3D Print**, and a Forge Multipart **Stone Cover** | Its slots are rebuilt without losing, hiding or disconnecting either part | external mutation of `TSlottedTile.v_partMap` plus `bindPart` |
@@ -0,0 +1,29 @@
package codechicken.multipart.examples;
import net.minecraft.block.Block;
import net.minecraft.client.renderer.RenderBlocks;
import net.minecraft.nbt.NBTTagCompound;
import net.minecraft.world.IBlockAccess;
import net.minecraft.world.World;
import codechicken.multipart.MultipartHelper;
import codechicken.multipart.MultipartRenderer;
import codechicken.multipart.TileMultipart;
import cpw.mods.fml.relauncher.Side;
import cpw.mods.fml.relauncher.SideOnly;
/** Compiling example for constructing and rendering an uninstalled multipart preview without reflection or Scala. */
@SideOnly(Side.CLIENT)
public final class ClientPreviewExample {
private ClientPreviewExample() {}
public static TileMultipart create(World clientWorld, NBTTagCompound savedTile) {
return MultipartHelper.createPreviewTileFromNBT(clientWorld, savedTile);
}
public static boolean render(IBlockAccess world, int x, int y, int z, Block multipartBlock, RenderBlocks renderer) {
return MultipartRenderer
.renderWorldBlock(world, x, y, z, multipartBlock, multipartBlock.getRenderType(), renderer);
}
}
@@ -31,6 +31,11 @@ public final class PartRegistrationExample implements IPartFactory2 {
return new ExamplePart();
}
@Override
public TMultiPart createPartForClientPreview(String name, NBTTagCompound nbt) {
return new ExamplePart();
}
/** Call from the server-side item/action after choosing the target position. */
public static TileMultipart place(World world, BlockCoord pos, int value) {
ExamplePart part = new ExamplePart(value);
@@ -7,6 +7,7 @@ import static org.junit.jupiter.api.Assertions.assertInstanceOf;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertSame;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
import java.util.Arrays;
@@ -27,6 +28,9 @@ import codechicken.multipart.MultiPartRegistry;
import codechicken.multipart.MultipartHelper;
import codechicken.multipart.TMultiPart;
import codechicken.multipart.TileMultipart;
import codechicken.multipart.TileMultipartClient;
import codechicken.multipart.examples.PartRegistrationExample;
import codechicken.multipart.examples.PartRegistrationExample.ExamplePart;
import codechicken.multipart.handler.MultipartSPH;
import codechicken.multipart.handler.MultipartSaveLoad;
import codechicken.multipart.minecraft.ButtonPart;
@@ -84,6 +88,30 @@ class MultipartHelperFunctionalTest {
assertSame(world, MultipartSaveLoad.loadingWorld());
}
@Test
void buildsAWorldlessClientPreviewFromSavedNbt() {
NBTTagCompound tag = previewTag(37);
TileMultipart tile = MultipartHelper.createPreviewTileFromNBT(null, tag);
assertTrue(tile instanceof TileMultipartClient);
assertNull(tile.getWorldObj());
assertEquals(31, tile.xCoord);
assertEquals(72, tile.yCoord);
assertEquals(-9, tile.zCoord);
assertEquals(1, tile.jPartList().size());
ExamplePart part = assertInstanceOf(ExamplePart.class, tile.jPartList().get(0));
assertSame(tile, part.tile());
assertEquals(37, part.value());
}
@Test
void rejectsServerWorldsBeforeConstructingPreviewParts() {
assertThrows(
IllegalArgumentException.class,
() -> MultipartHelper.createPreviewTileFromNBT(world(), previewTag(37)));
}
@Test
void writesTheExactMixedPartChunkDescriptionPacket() {
World world = world();
@@ -152,6 +180,22 @@ class MultipartHelperFunctionalTest {
return MultipartHelper.createTileFromParts(Arrays.asList(new TorchPart(5), new ButtonPart(1)));
}
private static NBTTagCompound previewTag(int value) {
NBTTagCompound part = new NBTTagCompound();
part.setString("id", PartRegistrationExample.PART_TYPE);
part.setInteger("value", value);
NBTTagList parts = new NBTTagList();
parts.appendTag(part);
NBTTagCompound tile = new NBTTagCompound();
tile.setString("id", "savedMultipart");
tile.setInteger("x", 31);
tile.setInteger("y", 72);
tile.setInteger("z", -9);
tile.setTag("parts", parts);
return tile;
}
/** Matches only its own tile class, so registering it cannot affect any real chunk load. */
private static final class MarkerTile extends TileEntity {
}
@@ -209,6 +209,12 @@ class PartRegistrationFunctionalTest {
assertEquals(name, client.getType());
assertEquals(17, packet.readUByte(), "Legacy adapters must not consume the description payload");
assertEquals(23, packet.readUByte());
Part preview = (Part) MultiPartRegistry.getPartFactory(name)
.createPartForClientPreview(name, new NBTTagCompound());
assertTrue(preview.client);
assertNull(preview.nbt);
assertNull(preview.packet);
}
}
@@ -65,4 +65,9 @@ public abstract class MicroblockClass implements IPartFactory2 {
public Microblock createPart(String name, NBTTagCompound nbt) {
return create(false, MicroMaterialRegistry.materialID(nbt.getString("material")));
}
@Override
public Microblock createPartForClientPreview(String name, NBTTagCompound nbt) {
return create(true, MicroMaterialRegistry.materialID(nbt.getString("material")));
}
}
@@ -69,6 +69,19 @@ public final class MultiPartRegistry {
* true) passes null.
*/
TMultiPart createPart(String name, MCDataInput packet);
/**
* Creates a client part from saved NBT for an off-world preview. The returned part must be fresh and unbound;
* the preview loader subsequently calls {@link TMultiPart#load(NBTTagCompound)} and binds it to a generated
* client tile. Return null when this factory cannot construct its client variant without a description packet.
*
* <p>
* The preview loader calls this only for client construction. Existing factories remain binary compatible and
* opt out by default. Do not consume or mutate the supplied tag.
*/
default TMultiPart createPartForClientPreview(String name, NBTTagCompound nbt) {
return null;
}
}
/**
@@ -131,6 +144,11 @@ public final class MultiPartRegistry {
public TMultiPart createPart(String name, NBTTagCompound nbt) {
return partFactory.createPart(name, false);
}
@Override
public TMultiPart createPartForClientPreview(String name, NBTTagCompound nbt) {
return partFactory.createPart(name, true);
}
}, types);
}
@@ -153,6 +171,11 @@ public final class MultiPartRegistry {
public TMultiPart createPart(String name, NBTTagCompound nbt) {
return partFactory.apply(name, Boolean.FALSE);
}
@Override
public TMultiPart createPartForClientPreview(String name, NBTTagCompound nbt) {
return partFactory.apply(name, Boolean.TRUE);
}
}, types);
}
@@ -1,14 +1,18 @@
package codechicken.multipart;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import net.minecraft.nbt.NBTTagCompound;
import net.minecraft.nbt.NBTTagList;
import net.minecraft.tileentity.TileEntity;
import net.minecraft.world.World;
import net.minecraft.world.chunk.Chunk;
import codechicken.lib.packet.PacketCustom;
import codechicken.multipart.handler.MultipartProxy;
import codechicken.multipart.handler.MultipartSPH;
import codechicken.multipart.handler.MultipartSaveLoad;
import scala.collection.JavaConversions;
@@ -46,6 +50,68 @@ public final class MultipartHelper {
return TileMultipart.createFromNBT(tag);
}
/**
* Builds a render-ready client multipart tile from saved NBT without installing it into a world. Every registered
* part factory must support
* {@link MultiPartRegistry.IPartFactory2#createPartForClientPreview(String, NBTTagCompound)}; otherwise the whole
* preview is rejected and null is returned. Part order and saved state are preserved.
*
* <p>
* A non-null world must be client-side. The tile receives its saved coordinates, binds every part, then runs
* {@link TMultiPart#onWorldJoin()} and local {@link TMultiPart#onPartChanged(TMultiPart)} callbacks before
* rebuilding its render state. It is not validated, placed in a chunk, or announced to neighboring blocks. A null
* world creates a worldless staged preview; render caches initialize lazily when a renderer uses the tile.
*
* @param world client preview world, or null for worldless staging
* @param tag saved multipart NBT; it is read but not mutated
* @return a prepared client tile, or null for a foreign/empty tag, missing factory, or unsupported preview part
* @throws IllegalArgumentException if world is server-side
*/
public static TileMultipart createPreviewTileFromNBT(World world, NBTTagCompound tag) {
if (tag == null || !tag.getString("id").equals("savedMultipart")) {
return null;
}
if (world != null && !world.isRemote) {
throw new IllegalArgumentException("Multipart previews require a client world");
}
NBTTagList partTags = tag.getTagList("parts", 10);
List<TMultiPart> parts = new ArrayList<>(partTags.tagCount());
for (int i = 0; i < partTags.tagCount(); i++) {
NBTTagCompound partTag = partTags.getCompoundTagAt(i);
String partId = partTag.getString("id");
MultiPartRegistry.IPartFactory2 factory = MultiPartRegistry.getPartFactory(partId);
if (factory == null) {
MultipartProxy.logger().error("Missing mapping for preview part with ID: " + partId);
return null;
}
TMultiPart part = factory.createPartForClientPreview(partId, partTag);
if (part == null) {
MultipartProxy.logger().warn("Part factory does not support client previews for ID: " + partId);
return null;
}
part.load(partTag);
parts.add(part);
}
if (parts.isEmpty()) {
return null;
}
TileMultipart tile = MultipartGenerator.generateCompositeTile(null, parts, true);
tile.readFromNBT(tag);
tile.loadPartList(parts);
tile.setWorldObj(world);
if (world != null) {
tile.forEachPart(TMultiPart::onWorldJoin);
}
tile.internalPartChange(null);
if (world != null) {
tile.markRender();
}
return tile;
}
/**
* Note. This method should only be used to send tiles that have been created on the server mid-game via an NBT load
* to clients.
@@ -41,6 +41,8 @@ class MicroblockClassCharacterizationTest {
"createPart(Ljava/lang/String;Lcodechicken/lib/data/MCDataInput;)Lcodechicken/multipart/TMultiPart;",
"createPart(Ljava/lang/String;Lnet/minecraft/nbt/NBTTagCompound;)Lcodechicken/microblock/Microblock;",
"createPart(Ljava/lang/String;Lnet/minecraft/nbt/NBTTagCompound;)Lcodechicken/multipart/TMultiPart;",
"createPartForClientPreview(Ljava/lang/String;Lnet/minecraft/nbt/NBTTagCompound;)Lcodechicken/microblock/Microblock;",
"createPartForClientPreview(Ljava/lang/String;Lnet/minecraft/nbt/NBTTagCompound;)Lcodechicken/multipart/TMultiPart;",
"getName()Ljava/lang/String;",
"getResistanceFactor()F",
"register()V");
@@ -82,6 +82,14 @@ class MultiPartRegistryCharacterizationTest {
assertFalse(MultiPartRegistry.loaded());
}
@Test
void packetAwareFactoriesOptInToNbtPreviewConstruction() {
TestFactory factory = new TestFactory(new TestPart());
assertNull(factory.createPartForClientPreview("test:preview", new NBTTagCompound()));
assertEquals(0, factory.calls);
}
@Test
void unknownModContainerThrowsRatherThanReturningNull() {
assertThrows(NoSuchElementException.class, () -> MultiPartRegistry.getModContainer("test:nosuchpart"));
@@ -36,10 +36,13 @@ class MultipartHelperCharacterizationTest {
@Test
void aTagThatIsNotASavedMultipartReturnsNullBeforeTouchingTheLoader() {
assertNull(MultipartHelper.createTileFromNBT(null, new NBTTagCompound()));
assertNull(MultipartHelper.createPreviewTileFromNBT(null, null));
assertNull(MultipartHelper.createPreviewTileFromNBT(null, new NBTTagCompound()));
NBTTagCompound wrongId = new NBTTagCompound();
wrongId.setString("id", "somethingElse");
assertNull(MultipartHelper.createTileFromNBT(null, wrongId));
assertNull(MultipartHelper.createPreviewTileFromNBT(null, wrongId));
}
/** The other half of the same probe: the matching branch does reach the loader. */
@@ -117,6 +120,11 @@ class MultipartHelperCharacterizationTest {
assertSame(void.class, sendDescPacket.getReturnType());
assertPublicStatic(sendDescPacket);
Method createPreviewTileFromNBT = MultipartHelper.class
.getDeclaredMethod("createPreviewTileFromNBT", World.class, NBTTagCompound.class);
assertSame(TileMultipart.class, createPreviewTileFromNBT.getReturnType());
assertPublicStatic(createPreviewTileFromNBT);
Class<?> companion = Class.forName("codechicken.multipart.MultipartHelper$");
Field module = companion.getField("MODULE$");
assertSame(companion, module.getType());