From fbef5d46531066cb61d07f94e5eec5f0b43b363d Mon Sep 17 00:00:00 2001 From: Algent Date: Sat, 5 Sep 2026 11:53:28 +0200 Subject: [PATCH] feat: add named Java tile conversion result --- JAVA_MIGRATION.md | 19 ++++-- JAVA_MIGRATION_CONSUMER_AUDIT.md | 16 ++++- JAVA_MIGRATION_HANDOFF.md | 30 ++++----- docs/API.md | 4 ++ docs/api/TILE_CONVERSION.md | 63 +++++++++++++++++++ docs/migration/HISTORY.md | 24 +++++++ .../examples/TileConversionExample.java | 19 ++++++ .../test/TileConversionFunctionalTest.java | 30 +++++++++ .../multipart/TileConversionResult.java | 29 +++++++++ .../codechicken/multipart/TileMultipart$.java | 2 + .../codechicken/multipart/TileMultipart.java | 30 ++++++++- 11 files changed, 243 insertions(+), 23 deletions(-) create mode 100644 docs/api/TILE_CONVERSION.md create mode 100644 src/functionalTest/java/codechicken/multipart/examples/TileConversionExample.java create mode 100644 src/main/scala/codechicken/multipart/TileConversionResult.java diff --git a/JAVA_MIGRATION.md b/JAVA_MIGRATION.md index cf70e32..d679f94 100644 --- a/JAVA_MIGRATION.md +++ b/JAVA_MIGRATION.md @@ -581,14 +581,14 @@ existing Java `registerParts` overload still required Scala during javac resolut | `TileMultipart.loadParts(scala.collection.Iterable)` | `loadPartList(Collection)` | Implemented through the legacy virtual hook; binding, world notifications, input iteration and partial failure retained. [Loading guide](docs/api/PART_LOADING.md) | | `TileMultipart.partList_$eq(scala.collection.Seq)` | `setPartList(List)` | Implemented through the legacy setter; Java list copied without binding, null sentinel supported. GuideNH's old reflective name remains supported | | `TileMultipart.renderID()` / `renderID_$eq(int)` and companion entries | `getRenderID()` / `setRenderID(int)` | Implemented over the same global value; four legacy entries deprecated. [Guide and compiling example](docs/api/RENDER_ID.md). Reading does not initialize the client renderer | -| `TileMultipart.getOrConvertTile2(): scala.Tuple2` | Small immutable result type with named accessors | No consumer in the audited set calls this | +| `TileMultipart.getOrConvertTile2(): scala.Tuple2` and companion entry | `getOrConvertTileResult(World, BlockCoord): TileConversionResult` with `getTile()` / `isConverted()` | Implemented over the retained tuple path; [guide and compiling example](docs/api/TILE_CONVERSION.md) distinguish existing tiles, uninstalled placeholders and failed conversion. No audited direct tuple caller | Explicitly **not** renamed: `TMultiPart.world()`, `x()`, `y()`, `z()`, and `tile()`. These carry Scala accessor naming but no Scala type, so renaming is cosmetic churn across 27 consumers with no compatibility or performance payoff. `tile()` is additionally unsafe to rename toward `getTile()`, which already exists with a different return type; a 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 +- [x] Add the ten table rows' 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 @@ -603,13 +603,15 @@ same-name overload there invites a silent wrong-overload bind. initialization/factory/payload contracts with a compiling example and real Forge initialization coverage. - [x] Add Java render-ID accessors with shared global-state/sentinel checks, retained static/companion entries and explicit client initialization versus assignment semantics; [guide](docs/api/RENDER_ID.md). -- [ ] For remaining siblings, compile external Java examples with Scala excluded from the compile classpath before +- [x] Add the named tile conversion result, preserving both tuple descriptors and documenting placeholder versus + installed-tile lifecycle; [guide](docs/api/TILE_CONVERSION.md). All ten table entries now have replacements. +- [x] For these table siblings, compile external Java examples with Scala excluded from the compile classpath before finalizing names. The proposed `loadParts(Collection)` overload required `scala.collection.Iterable` during javac overload resolution; the implemented `loadPartList(Collection)` avoids that dependency. Apply this gate to the remaining APIs as well as checking the emitted consumer bytecode. Registration hit the same constraint with `scala.collection.Seq` and `scala.Function2`; `registerPartFactory` passes this gate. -- [ ] Mark the remaining legacy entries above `@Deprecated` with javadoc naming a working replacement. -- [ ] Confirm every original descriptor still exists in the ABI fixture after the change. +- [x] Mark the legacy table entries above `@Deprecated` with javadoc naming a working replacement. +- [x] Confirm every original descriptor still exists in the ABI fixture after these table changes. - [ ] Document the supported API with compiling usage examples and an old-to-new migration guide. Validate Java subclasses and generated extensions on the actual Forge path, including both sides where relevant. @@ -623,13 +625,18 @@ 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`; `MicroMaterialRegistry.setupIDMap`, +`copyFrom`, `loadFrom`, `setValid`; `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. +`getOrConvertTile2` also has no audited external callers. Its retained static/companion entries are deprecated for +callers in favor of the supported `getOrConvertTileResult` API; keep the explicit placeholder contract instead of +marking that lookup internal. Internal placement tuple users, including `MicroblockPlacement.gtile()`, still need +their own migration before Scala removal. Completing the table does not finish the broader extension API audit. + Two similar-looking members **are** externally load-bearing and must not be marked internal: | Member | Consumer | Call site | diff --git a/JAVA_MIGRATION_CONSUMER_AUDIT.md b/JAVA_MIGRATION_CONSUMER_AUDIT.md index 3ce60ba..5ec3834 100644 --- a/JAVA_MIGRATION_CONSUMER_AUDIT.md +++ b/JAVA_MIGRATION_CONSUMER_AUDIT.md @@ -491,7 +491,8 @@ behavior: ## Java API adoption ledger This ledger tracks migration of a specific legacy contract, not completion of an entire consumer's migration. -Factory registration, material enumeration, tile collection/traversal access, tile loading/storage assignment, tile occlusion and box queries are implemented on +Factory registration, 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 `algent/java`. The [API index](docs/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. @@ -584,6 +585,19 @@ with deprecations. This addition does not replace GuideNH's renderer reflection JVM and dedicated-server checks preserve the -1 sentinel, unrestricted integer assignment and shared block state; physical-client rendering remains a separate gate. Evidence: `run/migration-render-id-reference/`. +Tile conversion is available as `TileMultipart.getOrConvertTileResult(World, BlockCoord)`, returning an immutable +`TileConversionResult` with `getTile()` / `isConverted()`; see the [guide](docs/api/TILE_CONVERSION.md). Both legacy +static/companion tuple methods remain with deprecations and unchanged bodies/descriptors. The new API wraps their +existing path, retaining existing-tile identity, converter dispatch and uninstalled-placeholder behavior. + +The supplied consumer source search found no `getOrConvertTile2` caller or new-name collision. The frozen member +inventory likewise has no direct tuple-method reference. AE2, Chisel, OpenComputers and Extra Utilities already call +the supported tile-only `getOrConvertTile`; they need no rename for this contract. Internal generator and microblock +placement tuple calls remain, including `MicroblockPlacement.gtile()`; their migration is a separate Scala-removal +gate. All 566 archived JVM tests and the unchanged archived Forge test mod's 252 cases pass against this addition. +The `+719` rescan retains all 386 member/type/reflection rows across 27 consumers. Reference checkouts remain unchanged. +Evidence: `run/migration-tile-conversion-reference/`. + ## Practical priority for the current branch 1. Keep the existing `+678` ABI fixture as the exact binary floor and correct failures before source cleanup. diff --git a/JAVA_MIGRATION_HANDOFF.md b/JAVA_MIGRATION_HANDOFF.md index 45217de..6a524f0 100644 --- a/JAVA_MIGRATION_HANDOFF.md +++ b/JAVA_MIGRATION_HANDOFF.md @@ -17,8 +17,8 @@ migration checkout; `codex/tile-compatibility-fixes` was deleted after its fixes ## Current state and next target -**566 plain-JVM tests and 249 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **224 Java -files and 9 Scala files / 747 nonblank Scala lines**. The packaged inventory has 443 classes. +**566 plain-JVM tests and 255 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **225 Java +files and 9 Scala files / 747 nonblank Scala lines**. The packaged inventory has 444 classes. Review follow-up: restored packet-scheduler callback mutation behavior with the original Scala hash-map traversal, virtual tile accessor dispatch throughout `TMultiPart`, and null-safe equality for scheduled-tick deduplication. @@ -32,13 +32,14 @@ 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: `TileMultipart.getRenderID()` / `setRenderID(int)` share the existing global render ID, retaining -the -1 sentinel and unrestricted integer assignment without client initialization. Two JVM cases and one Forge case -were committed first as `3c22ab6`; one further JVM case and stronger Forge assertions cover the Java entry/example. -All 565 frozen JVM tests and the archived Forge test mod's 249 cases pass against the new implementation. All 443 -classes retain existing members, with two methods added and four legacy accessors deprecated; 17 ScalaSignature -payloads, 3,753 existing method bodies and 116 generated dumps are unchanged apart from deprecation metadata and build -versions. Evidence: `run/migration-render-id-reference/`; [guide](docs/api/RENDER_ID.md). +Latest API addition: `TileMultipart.getOrConvertTileResult(World, BlockCoord)` returns a `TileConversionResult` with +`getTile()` / `isConverted()`. Three Forge baseline cases were committed first as `7396f2d`; three Java-entry cases +exercise the same existing/missing/converted-placeholder contracts and the compiling example. Both tuple entries +retain their bodies/descriptors with deprecations, and internal callers are unchanged. All 566 frozen JVM tests and +the archived Forge mod's 252 cases pass against the new implementation. All 443 existing classes retain their members; +one result class and one static method are added. The 17 ScalaSignature payloads, 3,755 existing method bodies and +116 generated dumps are unchanged apart from deprecation metadata and build versions. +Evidence: `run/migration-tile-conversion-reference/`; [guide](docs/api/TILE_CONVERSION.md). Naming correction: the planned `loadParts(Collection)` overload made javac require `scala.collection.Iterable` even for Java arguments. The distinct `loadPartList` name allows compilation without Scala on the example's classpath. @@ -57,13 +58,12 @@ adoption remain pending. Checkouts remain reference-only. The installed `+719` p Java surface; supply missing capabilities, precise contracts, migration guidance and compiling examples. Cover subclass/override behavior and generated extensions as well as ordinary calls. ProjectRed's illuminated microblocks are the representative external extension case. Consumer mods may remain Scala internally while adopting this API. -The final API-table entry is `TileMultipart.getOrConvertTile2`, whose Scala tuple exposes the tile and conversion flag. -Characterize existing-tile, missing-tile and converted-placeholder behavior before adding a named Java result; retain -the legacy descriptor and clarify that a converted placeholder has not been installed in the world. Registry lookup -for Schematica remains a separate gap. +The next bounded candidate is supported registry lookup for Schematica, replacing its private Scala-mangled map +reflection. Read that consumer's actual lookup/use contract and existing public registry helpers, characterize the +behavior first, then supply the smallest missing Java entry and migration guide. Generator/reflection replacements, +the representative external Java extension and internal-boundary documentation remain separate work. -Progress: nine of the ten Phase 9.1 rows now have implemented/documented Java replacements. The remaining row is -the tuple-returning tile conversion result. That count excludes supported +Progress: all ten Phase 9.1 table rows now have implemented/documented Java replacements. That count excludes supported registry/generator/reflection replacements, extension examples and internal-boundary documentation. Then consumer patches, releases and pack adoption must precede final Scala removal and client/pack release validation; it is not a percentage of the whole migration. diff --git a/docs/API.md b/docs/API.md index cc816d5..756acf8 100644 --- a/docs/API.md +++ b/docs/API.md @@ -21,6 +21,7 @@ without converting the rest of its code to Java. | Test a candidate against a selected collection of parts | `testOcclusion(Collection, candidate)` — [occlusion queries and generated hooks](api/OCCLUSION.md) | | Test two groups of bounding boxes directly | `NormalOcclusionTest.testBoxes(Iterable, Iterable)` — [box-versus-box queries](api/OCCLUSION.md#box-versus-box-queries) | | Read FMP's global render registration ID | `TileMultipart.getRenderID()` — [render-ID meaning, lifecycle and setter](api/RENDER_ID.md) | +| Inspect an existing tile or converted placeholder with a named result | `getOrConvertTileResult(World, BlockCoord)` — [conversion outcomes and placement lifecycle](api/TILE_CONVERSION.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 @@ -54,6 +55,9 @@ Registry lookup/converter 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. +All ten entries in the plan's Phase 9.1 API table have Java replacements. That table is a bounded list of signatures; +the broader API, extension and consumer adoption work above remains open. + FMP-side implementation is separate from consumer releases and target-pack adoption. Retiring legacy bridges or the Scala dependency requires those gates and removal of FMP's remaining internal Scala users. diff --git a/docs/api/TILE_CONVERSION.md b/docs/api/TILE_CONVERSION.md new file mode 100644 index 0000000..bdf2259 --- /dev/null +++ b/docs/api/TILE_CONVERSION.md @@ -0,0 +1,63 @@ +# Tile lookup and conversion results + +[Java API index](../API.md) + +`TileMultipart.getOrConvertTileResult(World, BlockCoord)` returns a `TileConversionResult` with `getTile()` and +`isConverted()` accessors. It is available on `algent/java`, with no minimum published dependency version yet. + +```java +TileConversionResult result = TileMultipart.getOrConvertTileResult(world, pos); +TileMultipart tile = result.getTile(); // May be null. +boolean placeholder = result.isConverted(); +``` + +The [compiling example](../../src/functionalTest/java/codechicken/multipart/examples/TileConversionExample.java) selects a +converted placeholder for inspection. It also compiles with Scala excluded from the compile classpath. + +## Outcomes and ownership + +| World state | `getTile()` | `isConverted()` | +| --- | --- | --- | +| A multipart tile already exists | That exact tile | `false` | +| A registered converter accepts the block | A fresh generated placeholder with its converted part bound | `true` | +| No multipart tile and no successful conversion | `null` | `false` | + +An unrelated tile entity does not count as a multipart tile. Converters still get a chance to handle its block. +The existing-tile path returns before querying the block or converters. Conversion follows the existing registry +dispatch and uses the world's client/server side when generating the tile. + +The result is an immutable record of one lookup; the referenced tile and its parts remain mutable. There is no +snapshot of tile contents, ownership transfer, synchronization or automatic update when the world later changes. + +## Placeholder lifecycle + +A converted placeholder has world and position assigned and its converted part bound. FMP has not replaced the +original block or installed the tile in the world. This lookup does not invoke the part's `onAdded` or `onConverted` +callbacks. Repeating it can create another tile and part; do not rely on identity across conversion queries. + +Converters and binding hooks execute normally and can have side effects or throw. This is not a pure query or a +placement permission check. Call it on the appropriate world thread after FMP initialization. Converter failures +propagate without a new fallback or rollback guarantee. + +For ordinary placement, use `canPlacePart(world, pos, part)` and then `addPart(world, pos, part)`, retaining the tile +returned by the addition. Addition performs conversion again and handles installation, callbacks and generated tile +replacement. Do not manually install the earlier placeholder, and do not treat it as a reservation of that location. + +Use `getTile(world, pos)` to find only an existing multipart tile. The existing `getOrConvertTile(world, pos)` remains +supported when only the tile is needed; it has the same placeholder caveat and does not need migration. + +## Compatibility and validation + +Both static and companion `getOrConvertTile2(World, BlockCoord)` tuple entries remain, with unchanged descriptors and +bodies, deprecated in favor of the named Java result. The new method delegates to that existing path. Internal +generator and microblock placement callers retain their tuple calls; `MicroblockPlacement.gtile()` remains a separate +Scala-shaped accessor whose eventual migration belongs to placement/extension guidance. + +No direct tuple-method use or new-name collision was found in the supplied consumer sources, and the frozen pack +inventory has no reference to that tuple method. AE2, Chisel, OpenComputers and Extra Utilities already use the +tile-only method and need no rename for this contract. Consumer checkouts remain reference-only. + +Forge tests run the same scenarios through both legacy entries and the Java entry: existing tile identity, air, +nonconvertible solid blocks, unrelated tile entities, bound torch placeholders, repeated conversions and subsequent +normal placement. Archived callers, class/member APIs and generated outputs are checked separately. Actual client +preview rendering remains a [manual release check](../../JAVA_MIGRATION_MANUAL_CHECKS.md). diff --git a/docs/migration/HISTORY.md b/docs/migration/HISTORY.md index 657b2f2..ae71a71 100644 --- a/docs/migration/HISTORY.md +++ b/docs/migration/HISTORY.md @@ -1873,3 +1873,27 @@ differences belong in the [divergence ledger](../../JAVA_MIGRATION_DIVERGENCES.m artifact, retains correctness/compatibility gates, and requires raw evidence, variability and reported regressions. It can overlap consumer migration once representative API/extension workloads are stable. No new performance measurements or speedup claims are introduced by this plan update. + +### 2026-09-05 — Named Java tile conversion result + +- Committed three Forge characterization cases as `7396f2d` before production edits. Both legacy entries preserve + existing-tile identity, null/false for nonconvertible blocks (including unrelated tile entities), and bound torch + placeholders without world installation. Repeated conversion produces fresh objects; subsequent normal placement + installs its own tile. Saved the reference jar, sources, 566 compiled JVM tests, Forge test mod and generated dumps. +- Added `getOrConvertTileResult(World, BlockCoord)` and immutable `TileConversionResult` with `getTile()` and + `isConverted()`. The wrapper delegates to the unchanged tuple method; both old tuple entries are deprecated. The + tile-only method remains supported, and internal generator/placement tuple calls are unchanged. The result uses + Java 8 syntax at the existing joint-compilation boundary without new compiler machinery. +- Three additional Forge cases exercise the Java entry and example against the same characterization. The example + lives in the Forge source set because lookup needs an initialized world; it also compiles standalone without Scala. + Normal/clean style/build checks pass with 566 JVM and 255 Forge tests, zero failures/errors/skips. All 566 frozen + JVM tests and the byte-identical archived Forge mod's 252 cases pass against the addition. +- All 443 old class APIs, 17 ScalaSignature payloads, 3,755 existing method bodies and 116 generated dumps remain. + Added one result class and one static entry; only intended deprecation/build-version metadata changes on old + members. All 444 packaged classes target Java 8. Source inventory is 225 Java and 9 Scala / 747 nonblank Scala lines. +- Added the conversion lifecycle guide and index entry, completed all ten Phase 9.1 table rows, and clarified that + the broader extension/API audit is still open. No direct tuple consumer or new-name collision was found; the + installed `+719` scan retains all 386 member/type/reflection rows across 27 consumers. Reference checkouts remain + unchanged. Next bounded candidate: Schematica registry lookup. Consumer adoption, internal tuple users, external + Java extensions, measured performance work and actual client/pack checks remain separate gates. + Evidence: `run/migration-tile-conversion-reference/`. diff --git a/src/functionalTest/java/codechicken/multipart/examples/TileConversionExample.java b/src/functionalTest/java/codechicken/multipart/examples/TileConversionExample.java new file mode 100644 index 0000000..2018326 --- /dev/null +++ b/src/functionalTest/java/codechicken/multipart/examples/TileConversionExample.java @@ -0,0 +1,19 @@ +package codechicken.multipart.examples; + +import net.minecraft.world.World; + +import codechicken.lib.vec.BlockCoord; +import codechicken.multipart.TileConversionResult; +import codechicken.multipart.TileMultipart; + +/** Forge-tested compiling example for docs/api/TILE_CONVERSION.md. */ +public final class TileConversionExample { + + private TileConversionExample() {} + + /** Returns only a newly converted placeholder, for inspection without installing it. */ + public static TileMultipart findConvertedPlaceholder(World world, BlockCoord pos) { + TileConversionResult result = TileMultipart.getOrConvertTileResult(world, pos); + return result.isConverted() ? result.getTile() : null; + } +} diff --git a/src/functionalTest/java/codechicken/multipart/test/TileConversionFunctionalTest.java b/src/functionalTest/java/codechicken/multipart/test/TileConversionFunctionalTest.java index 8c70089..c60516c 100644 --- a/src/functionalTest/java/codechicken/multipart/test/TileConversionFunctionalTest.java +++ b/src/functionalTest/java/codechicken/multipart/test/TileConversionFunctionalTest.java @@ -19,13 +19,43 @@ import org.junit.jupiter.api.Test; import codechicken.lib.vec.BlockCoord; import codechicken.multipart.TMultiPart; +import codechicken.multipart.TileConversionResult; import codechicken.multipart.TileMultipart; import codechicken.multipart.TileMultipart$; +import codechicken.multipart.examples.TileConversionExample; import codechicken.multipart.minecraft.TorchPart; import scala.Tuple2; class TileConversionFunctionalTest { + @Test + void javaExistingTileIsReturnedWithoutConversion() { + checkExisting(TileConversionFunctionalTest::javaLookup); + } + + @Test + void javaNonConvertibleBlocksReturnNullAndFalse() { + checkMissing(TileConversionFunctionalTest::javaLookup); + } + + @Test + void javaConversionCreatesBoundPlaceholdersWithoutInstallingThem() { + checkConverted(TileConversionFunctionalTest::javaLookup); + } + + private static Tuple2 javaLookup(World world, BlockCoord pos) { + TileConversionResult result = TileMultipart.getOrConvertTileResult(world, pos); + TileMultipart example = TileConversionExample.findConvertedPlaceholder(world, pos); + if (result.isConverted()) { + assertNotSame(result.getTile(), example); + assertSame(world, example.getWorldObj()); + assertEquals(pos, new BlockCoord(example)); + } else { + assertNull(example); + } + return new Tuple2<>(result.getTile(), result.isConverted()); + } + @Test void legacyExistingTileIsReturnedWithoutConversion() { checkExisting(TileMultipart::getOrConvertTile2); diff --git a/src/main/scala/codechicken/multipart/TileConversionResult.java b/src/main/scala/codechicken/multipart/TileConversionResult.java new file mode 100644 index 0000000..a775a26 --- /dev/null +++ b/src/main/scala/codechicken/multipart/TileConversionResult.java @@ -0,0 +1,29 @@ +package codechicken.multipart; + +/** + * Immutable outcome of a tile lookup. The referenced tile remains mutable; this result does not track later world + * changes or own the tile's lifecycle. Obtain results through {@link TileMultipart#getOrConvertTileResult}. + */ +public final class TileConversionResult { + + private final TileMultipart tile; + private final boolean converted; + + TileConversionResult(TileMultipart tile, boolean converted) { + this.tile = tile; + this.converted = converted; + } + + /** Returns the existing tile or converted placeholder, or null if neither is available. */ + public TileMultipart getTile() { + return tile; + } + + /** + * Returns true only when this lookup created a converted placeholder. Such a tile has a bound part, world and + * coordinates, but has not been installed in the world. False covers both an existing tile and a null tile. + */ + public boolean isConverted() { + return converted; + } +} diff --git a/src/main/scala/codechicken/multipart/TileMultipart$.java b/src/main/scala/codechicken/multipart/TileMultipart$.java index 83bdf18..a4193f8 100644 --- a/src/main/scala/codechicken/multipart/TileMultipart$.java +++ b/src/main/scala/codechicken/multipart/TileMultipart$.java @@ -34,6 +34,8 @@ public final class TileMultipart$ { return TileMultipart.getOrConvertTile(world, pos); } + /** @deprecated Use {@link TileMultipart#getOrConvertTileResult(World, BlockCoord)}. */ + @Deprecated public Tuple2 getOrConvertTile2(World world, BlockCoord pos) { return TileMultipart.getOrConvertTile2(world, pos); } diff --git a/src/main/scala/codechicken/multipart/TileMultipart.java b/src/main/scala/codechicken/multipart/TileMultipart.java index 7a36608..4aa5f75 100644 --- a/src/main/scala/codechicken/multipart/TileMultipart.java +++ b/src/main/scala/codechicken/multipart/TileMultipart.java @@ -776,18 +776,46 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile { renderID = value; } - /** Gets a multipart tile instance at pos, converting if necessary. */ + /** + * Gets an existing tile or converted placeholder, or null. Conversion does not install the tile in the world. Use + * {@link #getOrConvertTileResult(World, BlockCoord)} when the conversion flag is also needed. + */ public static TileMultipart getOrConvertTile(World world, BlockCoord pos) { return getOrConvertTile2(world, pos)._1(); } + /** + * Looks up an existing tile, otherwise asks registered block converters for a multipart representation. An existing + * tile is returned by identity with {@link TileConversionResult#isConverted()} false. A successful conversion + * returns a fresh, uninstalled placeholder with the flag true; no match returns a null tile and false. + * + *

+ * A placeholder uses the world's client/server side and has its coordinates, world and converted part bound. This + * lookup does not replace the block, install the tile or invoke the part's placement/conversion callbacks. Repeated + * lookups can construct different placeholders. Converter callbacks run normally and their exceptions propagate; + * this is not a side-effect-free query. Use on the appropriate world thread after FMP initialization. + * + *

+ * For ordinary placement, use {@link #canPlacePart(World, BlockCoord, TMultiPart)} followed by + * {@link #addPart(World, BlockCoord, TMultiPart)} and retain the tile returned by the addition. Do not install this + * placeholder directly. Use {@link #getTile(World, BlockCoord)} if conversion should not be attempted. + * + * @return a non-null result recording this lookup; its tile reference may be null + */ + public static TileConversionResult getOrConvertTileResult(World world, BlockCoord pos) { + Tuple2 result = getOrConvertTile2(world, pos); + return new TileConversionResult(result._1(), (Boolean) result._2()); + } + /** * Gets a multipart tile instance at pos, converting if necessary. Note converted tiles are merely a structure * formality, they do not actually exist in world until they are required to by the addition of another multipart to * their space. * * @return the tile or null if there was none, and true if the tile is a result of a conversion + * @deprecated Use {@link #getOrConvertTileResult(World, BlockCoord)} for a Java result with named accessors. */ + @Deprecated public static Tuple2 getOrConvertTile2(World world, BlockCoord pos) { TileEntity t = world.getTileEntity(pos.x, pos.y, pos.z); if (t instanceof TileMultipart) {