docs: mark the internal API boundary

This commit is contained in:
Algent committed 2026-09-05 15:11:34 +02:00
1 parent 8b12dfe507
commit 4ec29ec49f
9 files changed
+203 -30

No files matched your search

+11 -4
View File
@@ -632,7 +632,10 @@ hooks as though they were API, and a consumer author cannot distinguish `addPart
practical API defect than the Scala types above, and the fix is javadoc only: no rename, no descriptor change, no
deprecation, and no new dependency for a marker annotation.
Verified against all 28 consumer checkouts as having **zero external callers**:
Completed with a fresh 2026-09-05 search across 28 source checkouts plus the Extra Utilities decompiled reference:
**no external calls to these FMP members were found**. The installed `+719` binary scan retains the same baseline.
Javadocs on the declarations below and the five matching material-registry companion bridges mark them internal;
see the [API boundary guide](docs/API.md#supported-api-and-internal-hooks).
`TileMultipart.addPart_impl`, `addPart_do`, `remPart_impl`, `writeAddPart`, `partAdded`, `partRemoved`, `from`,
`copyFrom`, `loadFrom`, `setValid`; `MicroMaterialRegistry.setupIDMap`,
@@ -654,10 +657,14 @@ Two similar-looking members **are** externally load-bearing and must not be mark
| `TileMultipart.bindPart` | OpenComputers | `li/cil/oc/integration/fmp/PrintPart.scala:171` |
| `TileMultipart.internalPartChange` | ProjectRed | `mrtjp/projectred/integration/gatepartrs.scala:74` |
- [ ] Add an internal-marker javadoc line to each zero-caller member listed above.
- [ ] Leave `bindPart` and `internalPartChange` documented as supported API and add them to the consumer audit's
- [x] Add an internal-marker javadoc line to each zero-caller member listed above, including registry companion bridges.
- [x] Leave `bindPart` and `internalPartChange` documented as supported API and add them to the consumer audit's
cross-cutting map.
- [ ] Do not add an annotations dependency for this; javadoc is sufficient and changes no descriptor.
- [x] Do not add an annotations dependency for this; javadoc is sufficient and changes no descriptor.
The registry-wide `loadIcons` dispatcher is internal; `IMicroMaterial.loadIcons` remains a supported material
extension callback. Internal tile lifecycle hooks still participate in trait overrides and generated state copying.
This slice changes documentation only, and does not complete the broader extension-example exit condition below.
Exit condition: every Scala-typed public entry has a documented Java-shaped replacement and a deprecation pointing at
it, supported extension paths have buildable examples and Forge coverage, implementation-hook members are documented
+9
View File
@@ -239,3 +239,12 @@ Existing public virtual `block()` / `meta()` now have a [typed query guide](docs
coverage; no descriptor or method body changed. The mixin reads constructor fields whereas direct calls honor
subclass overrides, as the old reflective fallback already did. Remove the consumer's mixin only when adopting the
typed query; FMP field removal still waits for released-consumer adoption.
### Documented internal boundary (2026-09-05)
The [Phase 9.2 audit](JAVA_MIGRATION_CONSUMER_AUDIT.md#api-boundary-audit) marks 15 zero-observed-caller tile/material
hooks and five registry companion bridges as internal in Javadocs. All binary shapes and behavior remain unchanged;
this does not authorize removing or narrowing these members. The shipped `TileMultipart.bindPart(TMultiPart): void`
and `internalPartChange(TMultiPart): void` calls remain supported and are documented in the API guide, as are existing
legacy override contracts. The registry's internal `loadIcons()` dispatcher is distinct from its supported material
interface callback. The `+719` rescan retains all 386 member/type/reflection rows across the same 27 consumers.
+25
View File
@@ -96,6 +96,8 @@ present. Only the plugin is one of the 27 FMP consumers.
| Dynamic composite tiles | ProjectRed, Extra Utilities, AE2, ForgeRelocationFMP, WR-CBE, WitchingGadgets, UtilitiesInExcess; GuideNH and Schematica reconstruct them | Trait-bit selection, generated subclass caching, pass-through interfaces, client/server selection, promotion of an existing tile |
| External Scala trait generation | ProjectRed illuminated microblocks | `MicroblockGenerator.registerTrait`, ScalaSignature decoding, `$class` helper handling, correct trait initialization and dispatch |
| Tile collections and slot state | ProjectRed, Extra Utilities, OpenComputers, AE2, ProjectBlue, GT5U, BuildCraftCompat, WitchingGadgets, MatterManipulator, GuideNH | `partList(): Seq`, `jPartList(): List`, ordering, `partMap(int)`, mutable `TSlottedTile.v_partMap`, `bindPart`, slot-map rebuilds |
| Capability-cache refresh | OpenComputers `PrintPart.toggleState` | Supported `TileMultipart.bindPart` dispatch, caller-cleared old slot entries, no implicit list insertion or part binding |
| Local part-change notification | ProjectRed `RedstoneGatePart.onOutputChange` | Supported `TileMultipart.internalPartChange`, equality filtering and `operate` dispatch; caller retains packet/dirty/external-neighbor policy |
| Placement/removal/replacement | Most custom-part mods | `getTile`/`getOrConvertTile`, `canPlacePart`, `canAddPart`, `canReplacePart`, `addPart`, `remPart`, binding and notifications in their current order |
| Move lifecycle | ForgeRelocationFMP, MatterManipulator | A live `TileMultipart` can be detached/reinserted, coordinates rewritten, then `onMoved`; render, dirty, lighting, and description synchronization remain coherent |
| Occlusion and geometry | ProjectRed, Extra Utilities, OpenComputers, AE2, ForgeRelocationFMP, Chisel, WR-CBE, WitchingGadgets, UtilitiesInExcess | Normal and partial occlusion, collision/subpart boxes, `PartMap` numbering, Java iterable adapters, Scala `Traversable` overload |
@@ -656,6 +658,29 @@ Consumer migrations should use direct calls, including optional integrations gat
snippets remain legacy interoperability options only. Supplied consumer checkouts remain reference-only.
Evidence: `run/migration-material-access-reference/`; archived validation retains 570 JVM and 270 Forge cases.
## API boundary audit
Rechecked 2026-09-05 against 28 source checkouts and the Extra Utilities decompiled reference. Searches cover method
names, FMP-importing Java/Scala source, reflective names and the installed `+719` constant-pool inventory. No external
calls were found to the 15 tile/material-registry hooks listed in [Phase 9.2](JAVA_MIGRATION.md#92--mark-the-internal-boundary).
The registry's five companion forwarders carry matching Javadocs. Common-name matches included GuideNH comments
explicitly avoiding `from` / `copyFrom` and WR-CBE's unrelated `RenderWireless.loadIcons`; neither calls these hooks.
This is an audit of the supplied references, not proof about every possible external mod or dynamic lookup.
The supported exceptions are actual calls: OpenComputers `2c00f79be24b`, `PrintPart.scala:171`, clears the old slot
entries before `tile.bindPart(this)`; ProjectRed `e173952e96a4`, `gatepartrs.scala:74`, calls
`tile.internalPartChange(this)` between its own packet/dirty work and selective external-neighbor notification.
The [API guide](docs/API.md#supported-api-and-internal-hooks) preserves both contracts. The old `bindPart` comment's
blanket prohibition on external calls was incorrect. Cache binding does not place/rebind a part, and it is not a
universal idempotent refresh; local part notification does not implicitly perform world updates.
One new JVM baseline pins captured traversal, detachment/rebinding, callback failure propagation and worldless local
notification. One new Forge baseline pins cache-only binding and the old-slot clearing requirement. Existing equality,
loading, generated-trait, registry and handshake fixtures remain in the full suite. No API/member/behavior changes or
new deprecations are introduced; `operate`, `getOrConvertTile2` and material `loadIcons` keep their distinct supported
legacy/extension contracts. No consumer checkout was modified or counted as migrated.
Evidence: `run/migration-api-boundary-reference/`, including source revisions and reviewed caller searches.
## 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 -20
View File
@@ -17,7 +17,7 @@ migration checkout; `codex/tile-compatibility-fixes` was deleted after its fixes
## Current state and next target
**570 plain-JVM tests and 272 Java 8 Forge tests pass, with zero failures/errors/skips.** Sources total **225 Java
**571 plain-JVM tests and 273 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,
@@ -32,16 +32,16 @@ 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 work documents GuideNH's material query through direct `jPartList()`, `Microblock.material()`,
`MicroMaterialRegistry.getMaterial(int)` and existing `BlockMicroMaterial.block()` / `meta()` calls. Two JVM and one
Forge baseline cases were committed first as `079739e`; two Forge example cases cover ordering/filtering, metadata
formatting, registry aliases, getter overrides and failure propagation. No production API or behavior changed:
all 444 class APIs, 17 ScalaSignature payloads and 3,761 method bodies remain. Of 116 generated dumps, 114 match
exactly; the face/post pair matches after swapping only allocation-order class names. All 570 archived
JVM tests and the unchanged archived Forge mod's 270 cases pass. The example compiles without Scala or reflection.
The old private-field mixin bypasses virtual getters; the supported API honors them, like GuideNH's reflective
fallback. Consumer patches, custom-material exports and absent/present optional loading remain adoption gates.
Evidence: `run/migration-material-access-reference/`; [guide](docs/api/MATERIAL_ACCESS.md).
Latest API work completes the bounded Phase 9.2 internal-boundary documentation. A fresh search of 28 source
checkouts plus the Extra Utilities decompiled reference confirms no external calls to the 15 listed hooks; the five
material-registry companion bridges carry the same internal marker. `bindPart` and `internalPartChange` remain
supported for OpenComputers/ProjectRed. The material `IMicroMaterial.loadIcons` callback and existing legacy override
contracts remain supported. One JVM and one Forge baseline were committed first as `8b12dfe`, pinning local callback
mutation/failures and cache-only binding with caller-cleared old slots. All 571 archived JVM tests and the unchanged
archived Forge mod's 273 cases pass. Production APIs and behavior remain unchanged: 444 class APIs, 17 ScalaSignature
payloads, 3,761 method bodies and all 116 generated dump names/hashes match. No visibility changes, deprecations or
annotation dependency were added. Evidence: `run/migration-api-boundary-reference/`;
[boundary guide](docs/API.md#supported-api-and-internal-hooks), [caller audit](JAVA_MIGRATION_CONSUMER_AUDIT.md#api-boundary-audit).
Direct typed calls are the intended end state for supported integrations. Optional dependencies should isolate typed
compatibility code behind presence/version checks; reflection snippets in earlier guides are temporary legacy
@@ -65,16 +65,17 @@ 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 next bounded candidate is Phase 9.2: recheck the audited internal-hook caller inventory, document those hooks
as internal, and document externally used `bindPart` / `internalPartChange` as supported API. Keep descriptors and
behavior unchanged and preserve explicit legacy override contracts. The representative external Java microblock
extension remains separate work; use it before claiming complete consumer extension coverage.
The next bounded candidate is a representative external Java microblock extension based on ProjectRed's
`LightMicroblock` / `LightMicroMaterial` contract. Trace its registration, material behavior, state and side-only
callbacks; provide a compiling Java example with generated Forge coverage. Keep the reference checkout untouched
and retain the external Scala trait path until consumer release/adoption. Compiler prerequisites are complete, but
that alone does not establish the complete extension contract or physical-client rendering.
Progress: all ten Phase 9.1 table rows now have implemented/documented Java replacements, plus the separate Schematica
registry lookup, staged Java tile generation, microblock-creation guidance and typed GuideNH material query. Remaining
work includes internal-boundary documentation, converter/extension guidance and other audited reflection use cases.
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.
Progress: all ten Phase 9.1 table rows and Phase 9.2's internal markers are complete, plus the separate Schematica
registry lookup, staged Java tile generation, microblock-creation guidance and typed GuideNH material query.
Remaining work includes converter/extension guidance and other audited reflection use cases. 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.
A separate [Phase 4b performance pass](JAVA_MIGRATION.md#phase-4b--measured-performance-pass) is planned once the API
and representative extension workloads are stable, alongside consumer migration. Use fresh realistic profiles and
+39
View File
@@ -57,6 +57,45 @@ compile classpath for overload resolution, as the [loading guide](api/PART_LOADI
New API examples use Java 8 language/library features. The source path `src/main/scala` also contains Java classes
because of the current joint-compilation layout; it does not imply that those APIs require Scala source in a consumer.
## Supported API and internal hooks
Public visibility alone does not make a method a consumer entry point. Scala's former package-private methods are
public in bytecode. Source Javadocs now mark the following audited implementation hooks **Internal FMP**; keep
consumer code on the public operations in the right column. These markers change no visibility, descriptor or
behavior and do not deprecate or authorize removing a method. Trait callbacks and generated overrides still run.
| Internal hooks | Consumer operation or responsibility |
| --- | --- |
| `TileMultipart.addPart_impl`, `addPart_do`, `writeAddPart` | Place through `TileMultipart.addPart(world, pos, part)`; use [part loading](api/PART_LOADING.md) for prepared reconstruction |
| `TileMultipart.remPart_impl` | Remove through `tile.remPart(part)` on the server and retain the returned tile |
| `TileMultipart.partAdded`, `partRemoved` | Lifecycle callbacks for trait overrides; callers use placement/removal APIs |
| `TileMultipart.from`, `copyFrom`, `loadFrom`, `setValid` | FMP composite transitions; use [staged generation](api/COMPOSITE_GENERATION.md) and [loading](api/PART_LOADING.md) for consumer reconstruction |
| `MicroMaterialRegistry.setupIDMap`, `calcMaxCuttingStrength` | FMP initializes IDs and cutting strength; register materials at initialization and read the resulting values |
| `MicroMaterialRegistry.loadIcons` | FMP dispatches client texture callbacks; override the supported `IMicroMaterial.loadIcons()` material callback |
| `MicroMaterialRegistry.writeIDMap`, `readIDMap` | FMP's whole-map handshake; part packets use `writeMaterialID` / `readMaterialID` for individual IDs |
The registry's matching companion methods carry the same internal marker. This is the bounded Phase 9.2 audit,
not a claim that every other public member is a supported API. See [TileMultipart's Javadocs](../src/main/scala/codechicken/multipart/TileMultipart.java)
and [registry Javadocs](../src/main/scala/codechicken/microblock/MicroMaterialRegistry.java) for method-specific details.
Two advanced methods remain supported because consumers use them directly:
- **`bindPart(part)`** updates capability caches through generated overrides. It does not insert the part, change
its tile binding or perform placement/notifications. OpenComputers clears a print part's old slot entries before
calling it to populate a changed slot mask. A repeated call does not clear obsolete slots and may append entries
in other trait caches. Use it only with known cache semantics; full reconstruction uses `loadPartList`.
- **`internalPartChange(part)`** sends local `onPartChanged` callbacks through the retained `operate` hook. The base
traversal captures list order, skips parts whose binding is null at callback time, and excludes parts equal to the
changed part using `part.equals(p)`. Null broadcasts to all eligible parts. A non-null binding to another tile
still qualifies. Callback failures stop traversal and propagate. ProjectRed deliberately handles dirty state,
packets and external neighbors separately; this method does none of those. `notifyPartChange` also performs world
update/neighbor/lighting notifications when needed.
No reflection is needed to call either method. `operate` and `getOrConvertTile2` retain their documented legacy
contracts and Java replacements; neither receives an internal-only marker. Removing those bridges still requires
consumer and internal migration gates. The [consumer audit](../JAVA_MIGRATION_CONSUMER_AUDIT.md#api-boundary-audit)
records the checked source calls and validation.
## Compatibility and remaining work
Deprecated Scala-facing entry points remain callable, with their descriptors and supported override dispatch retained.
+28
View File
@@ -2000,3 +2000,31 @@ differences belong in the [divergence ledger](../../JAVA_MIGRATION_DIVERGENCES.m
`run/migration-material-access-reference/`.
- Next bounded task: Phase 9.2 internal-boundary Javadocs with a fresh caller audit, including supported `bindPart`
and `internalPartChange`; external Java extension guidance and the measured performance pass remain separate.
### 2026-09-05 — Document the internal API boundary
- Rechecked Phase 9.2 against 28 source checkouts plus decompiled Extra Utilities. Found no external calls to the
15 listed implementation hooks. Reviewed name collisions: WR-CBE calls its own renderer's `loadIcons`; GuideNH
explicitly avoids `from` / `copyFrom` in comments. OpenComputers still calls `bindPart` at `PrintPart.scala:171`,
and ProjectRed calls `internalPartChange` at `gatepartrs.scala:74`. Recorded source revisions and searches locally.
- Committed the passing baseline first as `8b12dfe`: one JVM test pins local callback order under list replacement,
detachment/rebinding and failure, with no world required; one Forge test pins cache-only slot binding, no list
insertion or part rebinding, and the requirement to clear old slot entries after a slot-mask change.
- Added internal Javadocs to all 15 hooks and the five registry companion bridges. Corrected the blanket prohibition
on externally calling `bindPart`, and documented both supported advanced methods and their caller responsibilities.
Repeated binding is not a universal cache refresh; local notifications exclude equal parts, retain legacy `operate`
dispatch and do not send packets or external-world notifications. Marked only the registry-wide texture dispatcher
internal; material `IMicroMaterial.loadIcons` remains a supported extension callback. Lifecycle override behavior,
including generated `copyFrom`, remains unchanged. No new methods, deprecations, annotations or visibility changes.
- Updated the API index, cross-cutting consumer map and plan's Phase 9.2 checkboxes. The boundary list is bounded and
does not imply every unlisted public member is supported. Complete external extension guidance remains open.
- Validation: normal and clean formatting/checkstyle/build plus the Java 8 Forge lane pass with **571 JVM / 273 Forge
tests**, zero failures/errors/skips. The **571 archived JVM / 273 archived Forge** cases pass without recompilation;
the archived Forge mod is byte-identical. All **444 class APIs, 17 ScalaSignature payloads, 3,761 production method
bodies and 116 generated dump names/hashes** remain unchanged. The installed `+719` scan retains all 386 ABI/reflection
rows across 27 consumers. Source-jar contents match the three edited production files; packaged classes remain
Java 8, and the post-commit rebuild verifies all five mod versions in both dev/release jars. Evidence:
`run/migration-api-boundary-reference/`.
- Next: a compiling representative Java microblock extension based on ProjectRed's illuminated material/trait,
with generated Forge coverage. Reference consumers remain unmodified; consumer releases/adoption, physical-client
rendering and the focused measured performance pass remain separate gates.
@@ -37,6 +37,7 @@ public final class MicroMaterialRegistry$ {
MicroMaterialRegistry.remapName(oldName, newName);
}
/** Internal FMP lifecycle bridge; see {@link MicroMaterialRegistry#setupIDMap()}. */
public void setupIDMap() {
MicroMaterialRegistry.setupIDMap();
}
@@ -45,10 +46,12 @@ public final class MicroMaterialRegistry$ {
return MicroMaterialRegistry.getMissingId();
}
/** Internal FMP lifecycle bridge; see {@link MicroMaterialRegistry#calcMaxCuttingStrength()}. */
public void calcMaxCuttingStrength() {
MicroMaterialRegistry.calcMaxCuttingStrength();
}
/** Internal FMP client texture-lifecycle bridge; see {@link MicroMaterialRegistry#loadIcons()}. */
public void loadIcons() {
MicroMaterialRegistry.loadIcons();
}
@@ -57,10 +60,12 @@ public final class MicroMaterialRegistry$ {
return MicroMaterialRegistry.getMaxCuttingStrength();
}
/** Internal FMP handshake bridge; see {@link MicroMaterialRegistry#writeIDMap(PacketCustom)}. */
public void writeIDMap(PacketCustom packet) {
MicroMaterialRegistry.writeIDMap(packet);
}
/** Internal FMP handshake bridge; see {@link MicroMaterialRegistry#readIDMap(PacketCustom)}. */
public List<String> readIDMap(PacketCustom packet) {
return MicroMaterialRegistry.readIDMap(packet);
}
@@ -36,7 +36,10 @@ public final class MicroMaterialRegistry {
@SideOnly(Side.CLIENT)
IIcon getBreakingIcon(int side);
/** Callback to load icons from the underlying block/etc. */
/**
* Supported material extension callback to load icons from the underlying block/etc., invoked by FMP on the
* client.
*/
@SideOnly(Side.CLIENT)
default void loadIcons() {}
@@ -148,6 +151,10 @@ public final class MicroMaterialRegistry {
remap.put(oldName, newName);
}
/**
* Internal FMP lifecycle step that rebuilds material IDs. Consumers register materials during initialization and
* enumerate the initialized map through {@link #materialCount()}; do not rebuild IDs from consumer code.
*/
@SuppressWarnings("unchecked")
public static void setupIDMap() {
List<Map.Entry<String, IMicroMaterial>> entries = new ArrayList<>(typeMap.entrySet());
@@ -176,6 +183,7 @@ public final class MicroMaterialRegistry {
return missingId;
}
/** Internal FMP lifecycle calculation; consumers read {@link #getMaxCuttingStrength()} after initialization. */
public static void calcMaxCuttingStrength() {
int max = Integer.MIN_VALUE;
boolean found = false;
@@ -193,6 +201,10 @@ public final class MicroMaterialRegistry {
maxCuttingStrength = max;
}
/**
* Internal FMP client texture-lifecycle dispatcher; do not call directly from consumers. The per-material
* {@link IMicroMaterial#loadIcons()} callback remains a supported extension hook.
*/
public static void loadIcons() {
if (idMap != null) {
for (Tuple2<String, IMicroMaterial> entry : idMap) {
@@ -205,6 +217,10 @@ public final class MicroMaterialRegistry {
return maxCuttingStrength;
}
/**
* Internal FMP handshake writer for the entire material map. Consumer part packets use
* {@link #writeMaterialID(MCDataOutput, int)} for an individual material ID instead.
*/
public static void writeIDMap(PacketCustom packet) {
packet.writeInt(idMap.length);
for (Tuple2<String, IMicroMaterial> entry : idMap) {
@@ -212,7 +228,10 @@ public final class MicroMaterialRegistry {
}
}
/** Reads the server's id map, returning the names this client has no material for. */
/**
* Internal FMP handshake reader: replaces this client's ID map with the server's, returning missing material names.
* Consumer part packets use {@link #readMaterialID(MCDataInput)} for an individual material ID instead.
*/
@SuppressWarnings("unchecked")
public static List<String> readIDMap(PacketCustom packet) {
int k = packet.readInt();
@@ -78,12 +78,18 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile {
partList_$eq(parts == null ? null : toSeq(parts));
}
/**
* Internal FMP composite-transition hook: copies trait state, then rebinds the stored parts. Not a consumer entry
* point.
*/
public void from(TileMultipart that) {
copyFrom(that);
loadFrom(that);
}
/**
* Internal FMP composite-transition hook; do not call directly from consumers.
*
* This method should be used for copying all the data from the fields in that container tile. This method will be
* automatically generated on java tile traits with fields if it is not overridden.
*/
@@ -92,6 +98,10 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile {
doesTick = that.doesTick;
}
/**
* Internal FMP composite-transition hook: rebinds this tile's stored parts and restores ticking after state copy.
* For consumer reconstruction, use {@link #loadPartList(Collection)} on a prepared composite instead.
*/
public void loadFrom(TileMultipart that) {
Iterator<TMultiPart> iterator = partList().iterator();
while (iterator.hasNext()) {
@@ -198,6 +208,7 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile {
operate(action(TMultiPart::onChunkLoad));
}
/** Internal FMP validity update that bypasses multipart lifecycle callbacks. Not a consumer entry point. */
public final void setValid(boolean b) {
if (b) {
super.validate();
@@ -247,7 +258,17 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile {
worldObj.func_147451_t(xCoord, yCoord, zCoord);
}
/** Notifies parts sharing this host of a change. */
/**
* Supported consumer API for local part-change notifications, used by ProjectRed. Calls
* {@link TMultiPart#onPartChanged(TMultiPart)} through the retained {@link #operate(Function1)} hook. Its base
* traversal captures the current list/order and skips parts whose tile binding is null at callback time; a non-null
* binding to another tile still qualifies. Parts equal to {@code part} (using {@code part.equals(p)}) are excluded;
* null broadcasts to all eligible parts. Callback failures propagate and stop traversal.
*
* This method does not mark the tile dirty, send updates or notify neighboring blocks/lighting. Keep the caller's
* synchronization and external-notification policy, or use {@link #notifyPartChange(TMultiPart)} when world
* notifications are needed as well.
*/
public void internalPartChange(TMultiPart part) {
operate(action(p -> {
if (part == null ? p != null : !part.equals(p)) {
@@ -467,6 +488,10 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile {
return MultipartSPH.getTileStream(worldObj, new BlockCoord(this));
}
/**
* Internal FMP placement lifecycle and synchronization hook. Consumers use
* {@link #addPart(World, BlockCoord, TMultiPart)} so composite selection and world installation also run.
*/
public void addPart_impl(TMultiPart part) {
if (!worldObj.isRemote) {
writeAddPart(part);
@@ -481,12 +506,17 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile {
markRender();
}
/** Internal FMP add-part packet writer; not a consumer entry point. Use the public placement API. */
public void writeAddPart(TMultiPart part) {
MCDataOutput stream = writeStream().writeByte(253);
MultiPartRegistry.writePartID(stream, part);
part.writeDesc(stream);
}
/**
* Internal FMP storage/cache/binding step, without the complete placement lifecycle. Consumers use
* {@link #addPart(World, BlockCoord, TMultiPart)} or {@link #loadPartList(Collection)} for prepared reconstruction.
*/
public void addPart_do(TMultiPart part) {
if (partList().size() >= 250) {
throw new AssertionError(
@@ -504,10 +534,19 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile {
}
}
/** Bind this part to an internal cache. Provided for trait overrides, do not call externally. */
/**
* Supported advanced consumer API and trait override hook for adding a part to this tile's capability caches. The
* base implementation is empty; generated traits supply cache behavior. Does not insert the part into the part
* list, change {@link TMultiPart#tile()}, run placement callbacks or send notifications.
*
* OpenComputers uses this to refresh a changed slot mask after clearing that part's old slot entries. Rebinding
* alone does not clear obsolete slots, and other traits may append cache entries on every call; this is not a
* general-purpose idempotent refresh. Only use it with known capability/cache semantics. For placement use
* {@link #addPart(World, BlockCoord, TMultiPart)}; for full reconstruction use {@link #loadPartList(Collection)}.
*/
public void bindPart(TMultiPart part) {}
/** Called when a part is added (placement). Provided for trait overrides, do not call externally. */
/** Internal FMP placement callback for trait overrides; do not call directly from consumers. */
public void partAdded(TMultiPart part) {}
/**
@@ -521,6 +560,7 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile {
return remPart_impl(part);
}
/** Internal FMP removal/synchronization hook. Consumers use {@link #remPart(TMultiPart)} on the server. */
public TileMultipart remPart_impl(TMultiPart part) {
remPart_do(part, !worldObj.isRemote);
@@ -571,7 +611,7 @@ public class TileMultipart extends TileEntity implements IChunkLoadTile {
return r;
}
/** Remove this part from internal cache. Provided for trait overrides, do not call externally. */
/** Internal FMP cache-removal callback for trait overrides; do not call directly from consumers. */
public void partRemoved(TMultiPart part, int p) {}
/**