Algent
ed861b6ca5
- drop per-guide Validation sections; manual gates stay in MANUAL_CHECKS - drop audit/provenance lines (reference checkouts, dated refreshes, commit pins) - state version status and Scala-free compile check once in API.md - replace API.md status prose with link to migration status - fix RELEASE_NOTES dangling sentence - rewrite README for GTNH fork and Java port
3.1 KiB
Tile lookup and conversion results
TileMultipart.getOrConvertTileResult(World, BlockCoord) returns a TileConversionResult with getTile() and
isConverted() accessors.
TileConversionResult result = TileMultipart.getOrConvertTileResult(world, pos);
TileMultipart tile = result.getTile(); // May be null.
boolean placeholder = result.isConverted();
The compiling example selects a converted placeholder for inspection.
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.
To implement conversion, see block converter registration and lifecycle.
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.
Legacy compatibility
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.
MicroblockPlacement.gtile() remains a separate Scala-shaped accessor.
AE2, Chisel, OpenComputers and Extra Utilities already use the tile-only method and need no change for this contract.