feat: add Java part traversal

This commit is contained in:
Algent committed 2026-09-04 23:48:10 +02:00
1 parent 5c1e7604f0
commit 533dc6a11e
10 files changed
+383 -23

No files matched your search

+11 -5
View File
@@ -522,15 +522,15 @@ 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. Two rows already have
their sibling and only need the annotation and javadoc.
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.
| Deprecate | Java-shaped replacement | Notes |
| --- | --- | --- |
| `TileMultipart.partList(): scala.collection.Seq` | `jPartList(): java.util.List` | Sibling already exists |
| `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). Setter/loading migrations remain separate |
| `MultiPartRegistry.registerParts(IPartFactory2, scala.collection.Seq)` | `registerParts(IPartFactory2, String...)` | Sibling already exists |
| `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<TMultiPart, BoxedUnit>)` | `forEachPart(java.util.function.Consumer<TMultiPart>)` | Preserve the existing skip-unbound-part behavior |
| `TileMultipart.operate(scala.Function1<TMultiPart, BoxedUnit>)` | `forEachPart(java.util.function.Consumer<TMultiPart>)` | 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)` | `occlusionTest(Collection<TMultiPart>, TMultiPart)` | |
| `TileMultipart.loadParts(scala.collection.Iterable)` | `loadParts(Collection<TMultiPart>)` | Schematica and GuideNH reflect the Scala descriptor; see Phase 10 |
| `TileMultipart.partList_$eq(scala.collection.Seq)` | `setPartList(List<TMultiPart>)` | GuideNH reflects the `_$eq` name; see Phase 10 |
@@ -545,6 +545,8 @@ same-name overload there invites a silent wrong-overload bind.
- [ ] Add the missing Java-shaped siblings over shared behavior, preserving legacy override dispatch and avoiding
recursive forwarding as required by the API migration design.
- [x] Add and document `materialCount()` with existing indexed lookups; retain and deprecate both `getIdMap()` entries.
- [x] Document `jPartList()` and add `forEachPart(Consumer)`; deprecate the legacy getter/callback entries while retaining
their override dispatch. JVM and generated-tile Forge cases cover the [documented contract](docs/api/PART_TRAVERSAL.md).
- [ ] Mark all nine rows `@Deprecated` with javadoc naming the 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
@@ -560,9 +562,13 @@ deprecation, and no new dependency for a marker annotation.
Verified against all 28 consumer checkouts as having **zero external callers**:
`TileMultipart.addPart_impl`, `addPart_do`, `remPart_impl`, `writeAddPart`, `partAdded`, `partRemoved`, `from`,
`copyFrom`, `loadFrom`, `setValid`, `getOrConvertTile2`, `operate`; `MicroMaterialRegistry.setupIDMap`,
`copyFrom`, `loadFrom`, `setValid`, `getOrConvertTile2`; `MicroMaterialRegistry.setupIDMap`,
`calcMaxCuttingStrength`, `loadIcons`, `writeIDMap`, `readIDMap`.
`TileMultipart.operate` also has no audited external callers, but remains a supported legacy override hook. It is
deprecated for callers in favor of `forEachPart`; lifecycle dispatch still uses it. Keep that explicit contract rather
than applying the internal-only marker to it. The new convenience method does not replace the lifecycle override hook.
Two similar-looking members **are** externally load-bearing and must not be marked internal:
| Member | Consumer | Call site |
+26 -3
View File
@@ -491,14 +491,20 @@ behavior:
## Java API adoption ledger
This ledger tracks migration of a specific legacy contract, not completion of an entire consumer's migration.
The FMP material-enumeration addition is implemented on `algent/java`, with the
[documented Java replacement](docs/api/MATERIAL_ENUMERATION.md) and a compiling example. It is not yet a released
minimum dependency version. Unlisted contracts remain governed by the inventories above.
Material enumeration and tile collection/traversal access are implemented on `algent/java`, with
[material](docs/api/MATERIAL_ENUMERATION.md) and [part traversal](docs/api/PART_TRAVERSAL.md) guides and compiling Java
examples. Neither addition is 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 |
| --- | --- | --- | --- | --- |
| `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 |
| `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; Java setter/loading replacements still pending | Read migration alone does not migrate client-tile reconstruction | Retain `partList`, `partList_$eq` and `loadParts` until their separate gates pass |
Evidence for the FMP addition is under ignored `run/migration-material-enumeration-reference/`. The original
reference-compiled Scala consumer still exercises the companion and tuple-array descriptor. The new compiling Java
@@ -508,6 +514,23 @@ they do not establish that an updated UtilitiesInExcess release has shipped or e
FMP's own `ItemMicroPart` and `MicroRecipe$` still use the legacy array internally. Their migration, any additional
retained companion users, and the other Scala-facing contracts remain separate removal gates.
Tile traversal evidence is under ignored `run/migration-part-traversal-reference/`. Re-scanning the supplied Java/Scala
sources found no FMP `operate` calls/overrides or `forEachPart` name collisions; two unrelated no-argument renderer
`operate()` implementations were excluded. The existing `operate(Function1)` override hook nevertheless remains
supported. The Java convenience delegates through it, while lifecycle callbacks continue calling it directly.
Deprecation is caller guidance, not permission to remove or bypass existing overrides. All 538 frozen pre-change JVM
tests, including the legacy getter/callback subclass cases, run against the addition without recompilation.
Existing `jPartList()` consumers such as ProjectBlue, BuildCraftCompat, GT5U, WitchingGadgets, MatterManipulator and
UtilitiesInExcess already have Java collection access. They need no rename for this contract. The new `forEachPart`
convenience is not a blanket replacement for their loops: its detached-part filtering can change read/query behavior.
The reference checkouts were not edited, built or counted as released migrations.
The installed GTNH daily `2026-09-04+719` rescan scanned 241 jars and excluded one FMP jar. Its 27 consumers still
reference the exact same 35 inherited types, 255 members, 76 other types and 20 reflection strings as the frozen
`+678` inventory, compared by full row rather than counts alone. The report is archived with the traversal evidence;
source revisions above remain the inspected checkout revisions, not a claim of source parity with every newer jar.
## Practical priority for the current branch
1. Keep the existing `+678` ABI fixture as the exact binary floor and correct failures before source cleanup.
+21 -14
View File
@@ -16,7 +16,7 @@ migration checkout; `codex/tile-compatibility-fixes` was deleted after its fixes
## Current state and next target
**535 plain-JVM tests and 238 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **224 Java
**542 plain-JVM tests and 239 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,
@@ -31,25 +31,32 @@ 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: `MicroMaterialRegistry.materialCount()` completes ID-based enumeration with the existing
`materialName(int)` and `getMaterial(int)` methods. Both `getIdMap()` entries are deprecated with unchanged descriptors
and live-array behavior. Two baseline cases were committed first as `9b78099`; three further JVM cases and one Forge
case cover the new API and a compiling Java example. All 532 pre-change compiled tests pass with their recorded
version. The 443 class APIs retain all existing members, with one public static method added; 17 ScalaSignature
payloads, 3,746 existing method bodies and 116 generated dumps are unchanged apart from expected deprecation metadata
and build-version literals. Evidence: `run/migration-material-enumeration-reference/`.
Latest API addition: `TileMultipart.forEachPart(Consumer)` reuses the existing adapter and virtual `operate` hook.
`jPartList()` now documents its captured-sequence view. Both legacy getter/callback entries are deprecated while
retaining their descriptors and bodies. Three baseline tests were committed first as `5c1e760`; four further JVM cases,
a compiling Java example and one Forge generated-tile case cover the new API. All 538 pre-change compiled tests pass
with their recorded version. The 443 class APIs retain all existing members, with one method added; 17 ScalaSignature
payloads, 3,747 existing method bodies and 116 generated dumps are unchanged apart from expected deprecation metadata
and build-version literals. Evidence: `run/migration-part-traversal-reference/`.
The [material enumeration guide](docs/api/MATERIAL_ENUMERATION.md) documents lifecycle, server ID ordering and failure
boundaries. The consumer audit's adoption ledger records the inspected UtilitiesInExcess revision and Extra Utilities
1.2.12; their source migrations, releases and pack adoption remain pending. The supplied checkouts remain reference-only.
The [part traversal guide](docs/api/PART_TRAVERSAL.md) covers ownership, callback mutation/reentrancy, failure timing,
detached/rebound parts and override dispatch. Lifecycle still uses `operate`; overriding `forEachPart` alone does not
intercept lifecycle callbacks. The adoption ledger names five legacy-getter consumers and the remaining GuideNH
setter/loading gap. The installed `+719` pack rescan matches every member/type/reflection row in the `+678` floor:
27 consumers, 35 inherited types, 255 members, 76 other types and 20 strings. Consumer releases/adoption remain pending.
`MicroMaterialRegistry.materialCount()` and its indexed lookups are also complete, with both `getIdMap()` entries
deprecated; see the [material enumeration guide](docs/api/MATERIAL_ENUMERATION.md) and previous history entry.
The supplied consumer checkouts remain reference-only.
**Next priority: close the Java API gaps in Phases 2 and 9 and map consumer migrations in Phase 10.** Reuse the existing
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 `TileMultipart` collection/traversal access, preserving legacy getter and callback
overrides, captured-sequence mutation behavior and detached-part filtering. Do not repeat material enumeration as an
unimplemented gap or treat its FMP-side completion as consumer adoption.
The next bounded API candidate is Java tile loading/state access: `loadParts(Collection<TMultiPart>)` and
`setPartList(List<TMultiPart>)`, with distinct binding/lifecycle contracts and preserved legacy setter/loading dispatch.
GuideNH's client-tile reconstruction makes the old descriptors load-bearing. Do not repeat material enumeration or
tile read/traversal access as unimplemented gaps, or treat FMP-side completion as consumer adoption.
Pause mechanical extraction of retained Scala shells unless it enables that API, fixes a demonstrated issue or has
a measured benefit. `ScalaSignature.ClassSymbolRef.info` remains an optional bounded extraction, not the default next
+1
View File
@@ -18,3 +18,4 @@ Implementation of all parts of the API should be clean and easy in Java. The min
Java API migration guides:
* [Enumerating microblock materials](docs/api/MATERIAL_ENUMERATION.md), including a compiling example and legacy API replacements.
* [Reading and visiting multipart parts](docs/api/PART_TRAVERSAL.md), including collection ownership, callback behavior and legacy overrides.
+101
View File
@@ -0,0 +1,101 @@
# Reading and visiting multipart parts from Java
Use `TileMultipart.jPartList()` for ordered collection access. The `algent/java` branch also adds
`forEachPart(Consumer<TMultiPart>)` for callbacks that skip detached parts. Consumers using the new method must require
an FMP release containing it; no minimum released version is established yet. Both methods work on generated tiles.
## Examples
Read all part types in list order:
```java
public static List<String> partTypes(TileMultipart tile) {
List<String> types = new ArrayList<>();
for (TMultiPart part : tile.jPartList()) {
types.add(part.getType());
}
return types;
}
```
To visit only parts that still have a tile binding:
```java
public static List<String> boundPartTypes(TileMultipart tile) {
List<String> types = new ArrayList<>();
tile.forEachPart(part -> types.add(part.getType()));
return types;
}
```
The [complete Java example](../../src/test/java/codechicken/multipart/examples/PartTraversalExample.java) compiles and
runs in the normal test task. Its imports and compiled references contain no Scala types. FMP still needs its retained
Scala runtime internally. The example also compiles with Scala excluded from its classpath. The returned name lists
are independent copies.
## Collection ownership and ordering
`jPartList()` wraps the sequence returned by the virtual `partList()` getter at that call. It preserves every entry,
its index and its object identity, including detached parts. Use it for indexing, searches, serialization and ordinary
iteration. It does not require parts to have joined a world.
Normal FMP additions/removals replace an immutable sequence. A previously returned Java list keeps the old sequence;
call `jPartList()` again for the tile's new contents. A legacy setter or getter override can instead supply a mutable
sequence, in which case mutations of that sequence remain visible through its Java view. Therefore the method does
not promise either an independent snapshot or an unmodifiable list for every implementation.
Treat the view as read-only. Editing it, even when the backing sequence permits it, does not perform part binding,
slot updates, notifications or synchronization. Use `TileMultipart.addPart(world, pos, part)` and `tile.remPart(part)`
for normal world changes, retaining their returned tile because adding/removing capabilities can replace the tile
instance. To capture independent list storage, use `new ArrayList<>(tile.jPartList())`; the part objects remain shared.
## Callback behavior
Use the game thread. The default `forEachPart` traversal has the same behavior as the legacy `operate` hook:
- Capture the current sequence once and visit it in order. Normal additions during a callback publish a new sequence,
so the current traversal does not visit the added parts.
- Check `part.tile() != null` immediately before each callback. A part detached by an earlier callback is skipped;
a part rebound to another tile is still visited. This check is not an ownership test against the original tile.
- A nested traversal captures the sequence anew and can observe the updated list. Each call has its own traversal state.
- Propagate the original callback exception immediately and stop that traversal. Side effects already performed remain.
- Preserve the iterator behavior of legacy mutable sequences. Do not structurally mutate such a sequence during traversal.
- Pass a non-null callback. For compatibility, there is no eager null check: with the default hook, null throws
`NullPointerException` only when a bound part reaches the callback. Empty/all-detached sequences invoke nothing.
`tile.jPartList().forEach(action)` visits every entry, including detached parts. It is not equivalent to
`tile.forEachPart(action)`. Preserve the consumer's original filtering and callback behavior when migrating.
## Overrides and legacy entry points
The dispatch paths are `jPartList()` → virtual `partList()`, and `forEachPart(consumer)` → virtual `operate(adapter)`.
The existing Java adapter and traversal implementation are shared; the legacy methods keep their descriptors and
bodies. Both legacy methods are deprecated for callers, with replacements named in their Javadocs.
Existing getter and `operate` overrides remain supported and can customize these behaviors. Lifecycle callbacks still
call `operate` directly. Overriding `forEachPart` intercepts calls to that convenience method only; it does not intercept
ticks, chunk callbacks or other lifecycle dispatch. Keep a legacy `operate` override in place if it supplies that hook.
No replacement lifecycle override contract is introduced by this addition.
## Consumer migration
| Existing use | Java replacement |
| --- | --- |
| `partList().size()` / `isEmpty()` / `indexOf(part)` | The corresponding `jPartList()` list method |
| Scala sequence indexing (`partList().apply(index)` or `tile.partList(index)`) | `tile.jPartList().get(index)` |
| Scala iterator for reading/searching every part | Enhanced `for` loop over `tile.jPartList()` |
| `operate(scalaFunction)` callback | `forEachPart(javaConsumer)`; preserve any existing hook overrides |
AE2's placement helper and Extra Utilities' renderer loops can use `jPartList()` without adding detached-part filtering.
ProjectRed's illumination calculations and packet/render indices, and OpenComputers' cable/print/network searches,
must retain their original order, filters and aggregation. Those mods can remain Scala internally while calling Java
collection methods. Existing Java consumers already using `jPartList()` need no rename.
GuideNH also reflects `partList`, `partList_$eq` and `loadParts` while reconstructing client tiles. Moving read-only
uses to the Java getter does not migrate its setter/loading contracts. Their Java replacements and the consumer patch,
release and pack adoption remain separate work. No reference checkout was edited.
The [adoption ledger](../../JAVA_MIGRATION_CONSUMER_AUDIT.md#java-api-adoption-ledger) records inspected revisions and
the remaining release gates. JVM checks cover both getter forms, mutable storage, callback mutation/reentrancy,
detached/rebound parts, override dispatch and failures. The Forge test removes and adds real parts during traversal
of a generated slotted tile. Client rendering and full-pack adoption remain manual release checks.
+22
View File
@@ -1741,3 +1741,25 @@ differences belong in the [divergence ledger](../../JAVA_MIGRATION_DIVERGENCES.m
- Added the material-enumeration guide and the first consumer adoption ledger rows. UtilitiesInExcess's two source
call sites and Extra Utilities' tuple-array readers have supported replacements; consumer changes, releases and
pack adoption remain pending. Evidence is under ignored `run/migration-material-enumeration-reference/`.
### 2026-09-04 — Java tile collection and traversal API
- Committed three baseline cases first as `5c1e760`, pinning captured Java views, lifecycle override dispatch,
non-null binding checks and callback failure propagation. Saved the pre-API jar, source, reports, generated dumps
and all 538 compiled JVM tests before implementation.
- Added `TileMultipart.forEachPart(Consumer<TMultiPart>)` through the existing adapter and virtual `operate` hook.
Documented the existing `jPartList()` view and deprecated `partList()`/`operate(Function1)` for callers, retaining
their descriptors, bodies and override contracts. Lifecycle still calls `operate` directly; no new lifecycle hook
or independently maintained traversal was introduced.
- Added four JVM cases, a compiling Java example and one Forge generated-tile case that removes/adds real parts
during traversal. Normal/clean style and build checks pass: 542 JVM tests, 239 Java 8 Forge tests and all 538 frozen
pre-change tests. The example also compiles with Scala excluded from its classpath and has no Scala bytecode references.
- Binary comparison retains all 443 class APIs with exactly one new public instance method and two deprecations.
All 17 ScalaSignature payloads, 3,747 existing method bodies and 116 generated dumps are unchanged, allowing only
the expected deprecation metadata and build-version literals. No production class or dependency was added.
- Added the traversal guide and consumer ledger entries for ProjectRed, OpenComputers, AE2, Extra Utilities and
GuideNH. Getter migration does not cover GuideNH's reflective setter/loading contracts. The supplied source search
found no FMP `operate` overrides or `forEachPart` collisions; existing override support remains required.
- Rescanned the installed GTNH daily `2026-09-04+719`: 241 jars scanned, one FMP jar excluded, 27 consumers. All
386 member/type/reflection rows match the frozen `+678` inventory; consumer version changes do not permit bridge
removal. Reference checkouts were not modified. Evidence: `run/migration-part-traversal-reference/`.
@@ -27,6 +27,7 @@ class TileMultipartLifecycleFunctionalTest {
private static final BlockCoord ADD_REMOVE_POS = new BlockCoord(32, 200, 32);
private static final BlockCoord MOVE_FROM = new BlockCoord(34, 200, 32);
private static final BlockCoord MOVE_TO = new BlockCoord(36, 200, 32);
private static final BlockCoord TRAVERSAL_POS = new BlockCoord(38, 200, 32);
@Test
void addAndRemovePreserveOrderSlotsAndPartCallbackOrder() {
@@ -121,6 +122,41 @@ class TileMultipartLifecycleFunctionalTest {
}
}
@Test
void javaTraversalSurvivesRealPartRemovalAndAdditionOnAGeneratedTile() {
World world = world();
clear(world, TRAVERSAL_POS);
List<String> events = new ArrayList<>();
RecordingPart first = new RecordingPart("first", 2, events);
RecordingPart removed = new RecordingPart("removed", 7, events);
RecordingPart added = new RecordingPart("added", 8, events);
try {
TileMultipart.addPart(world, TRAVERSAL_POS, first);
TileMultipart tile = TileMultipart.addPart(world, TRAVERSAL_POS, removed);
List<TMultiPart> captured = tile.jPartList();
List<TMultiPart> visited = new ArrayList<>();
tile.forEachPart(part -> {
visited.add(part);
if (part == first) {
assertSame(tile, tile.remPart(removed));
assertSame(tile, TileMultipart.addPart(world, TRAVERSAL_POS, added));
}
});
assertTrue(tile instanceof TSlottedTile);
assertEquals(Arrays.asList(first), visited);
assertEquals(Arrays.asList(first, removed), captured);
assertEquals(Arrays.asList(first, added), tile.jPartList());
assertNull(removed.tile());
assertNull(tile.partMap(7));
assertSame(added, tile.partMap(8));
assertSame(tile, added.tile());
} finally {
clear(world, TRAVERSAL_POS);
}
}
private static World world() {
World world = MinecraftServer.getServer().worldServers[0];
world.getChunkFromBlockCoords(ADD_REMOVE_POS.x, ADD_REMOVE_POS.z);
@@ -44,6 +44,11 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile {
private boolean doesTick = false;
/**
* @deprecated Use {@link #jPartList()} for Java collection access. Retained as the virtual storage accessor for
* existing subclasses and binaries.
*/
@Deprecated
public Seq<TMultiPart> partList() {
return partList;
}
@@ -82,16 +87,55 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile {
return null;
}
/** Implicit java conversion of part list. */
/**
* Returns an ordered Java view of the sequence returned by {@link #partList()} at this call. Includes detached
* parts; replacing the tile's sequence does not update an existing view. Normally the sequence is immutable, but a
* mutable sequence supplied through the legacy setter remains live through this view.
*
* <p>
* Treat the view as read-only: list edits do not perform multipart binding, notifications or synchronization. Use
* {@link #addPart(World, BlockCoord, TMultiPart)} and {@link #remPart(TMultiPart)} for world changes. Copy into an
* {@link ArrayList} when independent list storage is needed; the parts themselves remain shared.
*
* @return a view of the captured sequence, with its original order and part identities
*/
public List<TMultiPart> jPartList() {
return JavaConversions.seqAsJavaList(partList());
}
/**
* Visits parts in sequence order, skipping those whose {@link TMultiPart#tile()} is null when reached. Delegates
* through the legacy {@link #operate(Function1)} hook, so existing overrides still control traversal.
*
* <p>
* The default hook captures {@link #partList()} once. Normal additions publish a new sequence and are not visited
* by the current call; parts detached by an earlier callback are skipped. A part rebound to another tile is still
* visited. Legacy mutable sequences retain their own iterator behavior and must not be structurally edited during
* traversal. Each nested call captures its own sequence. Callback exceptions propagate immediately, stopping the
* current traversal.
*
* <p>
* Call on the game thread. Lifecycle callbacks continue to dispatch through {@code operate}, not through overrides
* of this convenience method. With the default hook, a null callback fails only when a bound part is visited.
*
* @param consumer action to apply to each visited part
*/
public void forEachPart(Consumer<TMultiPart> consumer) {
operate(action(consumer));
}
@Override
public boolean canUpdate() {
return doesTick;
}
/**
* Legacy traversal hook, also used by multipart lifecycle callbacks.
*
* @deprecated Call {@link #forEachPart(Consumer)} from Java. Existing overrides remain supported and intercept both
* that API and lifecycle callbacks; keep such overrides here while this compatibility hook is retained.
*/
@Deprecated
// Direct list traversal avoids measured iterator/wrapper allocations; the setter also accepts other Seq types.
@SuppressWarnings("unchecked")
public void operate(Function1<TMultiPart, BoxedUnit> f) {
@@ -21,6 +21,7 @@ import net.minecraft.util.Vec3;
import org.junit.jupiter.api.Test;
import codechicken.lib.raytracer.ExtendedMOP;
import codechicken.multipart.examples.PartTraversalExample;
import scala.Function1;
import scala.Tuple2;
import scala.collection.JavaConversions;
@@ -332,6 +333,98 @@ class TileMultipartCharacterizationTest {
assertEquals(Arrays.asList("rebound"), visited);
}
@Test
void javaTraversalKeepsAccessorDispatchAndCallbackMutationSemantics() {
AccessorTile tile = new AccessorTile();
CountingPart first = new CountingPart("first");
CountingPart removed = new CountingPart("removed");
CountingPart rebound = new CountingPart("rebound");
CountingPart added = new CountingPart("added");
tile.parts = seq(first, removed, rebound);
tile.loadFrom(new TileMultipart());
List<String> visited = new ArrayList<>();
List<String> nested = new ArrayList<>();
tile.forEachPart(part -> {
visited.add(part.getType());
if (part == first) {
tile.partList_$eq(seq(first, rebound, added));
removed.bind(null);
rebound.bind(new TileMultipart());
added.bind(tile);
tile.forEachPart(p -> nested.add(p.getType()));
}
});
assertEquals(Arrays.asList("first", "rebound"), visited);
assertEquals(Arrays.asList("first", "rebound", "added"), nested);
}
@Test
void javaTraversalUsesTheLegacyOverrideAndDoesNotReplaceItsLifecycleHook() {
CountingPart supplied = new CountingPart("supplied");
List<String> calls = new ArrayList<>();
TileMultipart tile = new TileMultipart() {
@Override
public void operate(Function1<TMultiPart, BoxedUnit> f) {
calls.add("operate");
f.apply(supplied);
}
@Override
public void forEachPart(Consumer<TMultiPart> consumer) {
calls.add("forEachPart");
super.forEachPart(consumer);
}
};
List<TMultiPart> visited = new ArrayList<>();
tile.forEachPart(visited::add);
tile.onChunkLoad();
assertEquals(Arrays.asList("forEachPart", "operate", "operate"), calls);
assertEquals(Arrays.asList(supplied), visited);
assertEquals(1, supplied.chunkLoads);
}
@Test
void javaTraversalRetainsMutableSequenceAndCallbackFailureBehavior() {
TileMultipart tile = new TileMultipart();
tile.forEachPart(null);
CountingPart detached = new CountingPart("detached");
tile.partList_$eq(seq(detached));
tile.forEachPart(null);
detached.bind(tile);
assertThrows(NullPointerException.class, () -> tile.forEachPart(null));
CountingPart last = new CountingPart("last");
last.bind(tile);
tile.partList_$eq(JavaConversions.asScalaBuffer(new ArrayList<>(Arrays.asList(detached, last))));
List<TMultiPart> visited = new ArrayList<>();
tile.forEachPart(visited::add);
assertEquals(Arrays.asList(detached, last), visited);
visited.clear();
IllegalStateException failure = new IllegalStateException("callback failed");
assertSame(failure, assertThrows(IllegalStateException.class, () -> tile.forEachPart(part -> {
visited.add(part);
throw failure;
})));
assertEquals(Arrays.asList(detached), visited);
}
@Test
void javaExamplesDistinguishCollectionAccessFromBoundPartTraversal() {
TileMultipart tile = new TileMultipart();
CountingPart first = new CountingPart("first");
CountingPart detached = new CountingPart("detached");
tile.addPart_do(first);
tile.addPart_do(detached);
detached.bind(null);
assertEquals(Arrays.asList("first", "detached"), PartTraversalExample.partTypes(tile));
assertEquals(Arrays.asList("first"), PartTraversalExample.boundPartTypes(tile));
}
@Test
void ticksOnlyOnceATickingPartIsPresent() {
TileMultipart quiet = new TileMultipart();
@@ -0,0 +1,27 @@
package codechicken.multipart.examples;
import java.util.ArrayList;
import java.util.List;
import codechicken.multipart.TMultiPart;
import codechicken.multipart.TileMultipart;
/** Compiling examples for docs/api/PART_TRAVERSAL.md; call on the game thread. */
public final class PartTraversalExample {
private PartTraversalExample() {}
public static List<String> partTypes(TileMultipart tile) {
List<String> types = new ArrayList<>();
for (TMultiPart part : tile.jPartList()) {
types.add(part.getType());
}
return types;
}
public static List<String> boundPartTypes(TileMultipart tile) {
List<String> types = new ArrayList<>();
tile.forEachPart(part -> types.add(part.getType()));
return types;
}
}