mirror of
https://github.com/GTNewHorizons/ForgeMultipart.git
synced 2026-11-21 12:42:51 +00:00
feat: add Java collection occlusion query
This commit is contained in:
1 parent
6744f5b04c
commit
d70f69e79f
11 files changed
+317
-25
No files matched your search
+3
-2
@@ -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
|
||||
|
||||
@@ -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).
|
||||
@@ -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/`.
|
||||
Reference in new issue
Block a user