feat: add Java collection occlusion query

This commit is contained in:
Algent committed 2026-09-05 00:48:38 +02:00
1 parent 6744f5b04c
commit d70f69e79f
11 files changed
+317 -25

No files matched your search

+3 -2
View File
@@ -17,6 +17,7 @@ without converting the rest of its code to Java.
| Run callbacks while skipping detached parts | `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) |
| 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) |
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
@@ -46,8 +47,8 @@ Deprecated Scala-facing entry points remain callable, with their descriptors and
Follow the method-specific guide: a Java sibling is not automatically a replacement override hook, and reflection
must select the intended parameter types when a method is overloaded.
Java collection occlusion access, remaining registry bridges/documentation, generator/reflection replacements and
complete external microblock extension guidance are still pending. In particular, ProjectRed's Scala microblock traits
Direct box-versus-box Java occlusion access, remaining registry bridges/documentation, generator/reflection replacements
and complete external microblock extension guidance are still pending. In particular, ProjectRed's Scala microblock traits
remain a supported dependency; registration signatures alone do not prove a complete Java replacement.
FMP-side implementation is separate from consumer releases and target-pack adoption. Retiring legacy bridges or the
+78
View File
@@ -0,0 +1,78 @@
# Testing part occlusion from Java
[API index](../API.md)
The `algent/java` branch adds `TileMultipart.testOcclusion(Collection<? extends TMultiPart>, TMultiPart)`.
It tests a supplied collection of parts through the tile's existing occlusion hook, including generated
partial-occlusion checks. This addition is not yet tied to a minimum published dependency version.
## Example
Use a `NormallyOccludedPart` to test a normal bounding shape against a supplied group of parts:
```java
public static boolean fitsShape(TileMultipart tile, Collection<? extends TMultiPart> parts, Cuboid6 bounds) {
return tile.testOcclusion(parts, new NormallyOccludedPart(bounds));
}
```
The [complete Java example](../../src/test/java/codechicken/multipart/examples/OcclusionExample.java) compiles and runs
in the test suite. It also compiles with Scala excluded from its classpath and has no Scala bytecode references.
FMP still retains its Scala runtime internally. Collections of part subclasses, such as `List<NormallyOccludedPart>`,
are accepted without a cast.
Pass `tile.jPartList()` to test against the tile's currently stored parts, or pass a separate collection for a preview
or selected subset. To exercise a real candidate's custom occlusion behavior, pass that part instead of the shape
wrapper. The wrapper represents normal bounding geometry, not all the capabilities of a custom part.
## What the query checks
The base tile tests each supplied part against the candidate, then tests the candidate against that same part. It
proceeds in input iteration order and stops immediately when either direction rejects. Unbound/detached parts and
duplicate entries participate; the candidate is not automatically excluded if it is also in the collection.
Generated partial-occlusion tiles retain their extra aggregate check. When the candidate implements `JPartialOcclusion`,
the existing trait checks the group plus the candidate before the ordinary pair callbacks. A plain `TileMultipart`
does not gain that capability just because the supplied parts need it. Use the appropriate composite tile; this method
does not generate or select tile traits.
This is an occlusion query, not full placement approval. It does not check placement permissions, duplicate membership,
slot occupancy or world replaceability, and does not bind/store parts or send notifications. For ordinary placement
and replacement, continue using `canPlacePart`, `canAddPart` and `canReplacePart` as appropriate. In particular,
`canReplacePart(outgoing, candidate)` performs its existing outgoing-part exclusion; this collection query does not.
## Ownership, callbacks and failures
The Java entry copies the input into an immutable sequence before calling the legacy hook. Order, duplicates, null
entries and part identities are preserved. Callback edits to the caller's collection do not change the current
query's sequence. Part objects are shared, so mutations of their state can affect later callbacks. A nested query
takes its own copy.
Copying failures, including a null collection, propagate before the legacy hook is called. There is no eager
candidate/null-entry validation: with the base implementation, an empty collection accepts even a null candidate,
and an early rejection can avoid a later null dereference. Callback exceptions propagate unchanged and stop the query;
callback side effects already performed are not undone. Overrides may add checks or customize these boundaries.
Use the game thread when querying live parts. A geometric query may invoke arbitrary part callbacks, including ones
that read or modify world/part state; it is not a thread-safety guarantee.
## Overrides and migration
Dispatch is `testOcclusion(Collection, candidate)` → virtual `occlusionTest(scala.collection.Seq, candidate)`.
The old method keeps its descriptor and body, and is deprecated for callers. Existing subclasses and generated traits
continue to override it. `canAddPart` and `canReplacePart` still call that hook directly; overriding only the new
Java method does not intercept their checks. The distinct Java name avoids introducing another Scala/Java overload
pair, following the [loader compilation finding](PART_LOADING.md#overrides-and-reflection).
No direct consumer calls or overrides of the two-argument tile hook were found in the supplied source/ABI audit.
Consumers such as ProjectRed and ForgeRelocationFMP already use the Java-typed `canReplacePart` API and need no rename
for that contract. Part-level `occlusionTest(TMultiPart)` remains supported as-is. The Scala `NormalOcclusionTest.apply`
box-versus-box entry is a separate, still-used contract whose Java replacement remains pending.
## Validation
JVM tests cover both directions, early rejection, original exceptions, null boundaries, snapshot ownership, duplicates,
subtype/non-list collections, override routing and the shape example. A Forge test demonstrates that the generated
partial trait rejects overlapping partial parts that plain pair tests accept. Existing descriptors, generated output,
and frozen pre-change callers are checked separately. Actual client previews and full-pack adoption remain covered
by the [manual release checks](../../JAVA_MIGRATION_MANUAL_CHECKS.md).
+22
View File
@@ -1784,3 +1784,25 @@ differences belong in the [divergence ledger](../../JAVA_MIGRATION_DIVERGENCES.m
- Added `docs/API.md` as the consumer entry point, a loading/storage guide, compiling examples, and reciprocal guide
links. Updated the plan, ABI notes and GuideNH/Schematica adoption ledger; reference checkouts remain unchanged and
consumer releases/pack adoption are pending. Evidence: `run/migration-part-loading-reference/`.
### 2026-09-05 — Java collection occlusion query
- Committed three JVM baseline cases and stronger generated-trait assertions first as `6744f5b`. They pin pair order,
both rejection directions, lazy null behavior, original exceptions and replacement-hook dispatch. Saved the pre-API
jar, source, reports, 116 generated dumps and all 552 compiled JVM tests before implementation.
- Added `TileMultipart.testOcclusion(Collection<? extends TMultiPart>, TMultiPart)` as an adapter through the old
virtual `occlusionTest(Seq, TMultiPart)`. It takes a shallow immutable snapshot, retains order/duplicates/identities,
and accepts subtype collections. The distinct name avoids a Scala/Java overload pair. The legacy hook is deprecated
for callers, with its descriptor and body unchanged; placement/replacement still dispatch directly through it.
- Four new JVM cases and a compiling Java shape example cover snapshot/callback behavior, non-list/subtype inputs,
failures, override routing and touching/overlapping bounds. One new Forge case proves aggregate partial-occlusion
rejection through the generated trait when plain pair tests would accept the same parts.
- Normal/clean build/style checks pass: 556 JVM tests, 243 Java 8 Forge tests and all 552 frozen pre-change JVM tests.
The Java example compiles with Scala excluded from the classpath and contains no Scala bytecode references.
All 443 existing class APIs, 17 ScalaSignature payloads, 3,750 existing method bodies and 116 generated dumps are
retained, with exactly one added public method and one deprecation. Only expected deprecation metadata and build
versions differ; no production class or dependency is added.
- Added the occlusion guide and API index entry. No direct consumer use of the two-argument tile hook or collision
with the new name was found. The separately load-bearing Scala box-list `NormalOcclusionTest.apply` contract now
has an explicit plan row and is the next candidate. Reference checkouts remain unchanged; client previews and
consumer release/adoption remain separate gates. Evidence: `run/migration-part-occlusion-reference/`.