From 4ec29ec49f8148599a54342500ef2a710ef86f4f Mon Sep 17 00:00:00 2001 From: Algent Date: Sat, 5 Sep 2026 15:11:34 +0200 Subject: [PATCH] docs: mark the internal API boundary --- JAVA_MIGRATION.md | 15 ++++-- JAVA_MIGRATION_ABI_INVENTORY.md | 9 ++++ JAVA_MIGRATION_CONSUMER_AUDIT.md | 25 ++++++++++ JAVA_MIGRATION_HANDOFF.md | 41 ++++++++-------- docs/API.md | 39 +++++++++++++++ docs/migration/HISTORY.md | 28 +++++++++++ .../microblock/MicroMaterialRegistry$.java | 5 ++ .../microblock/MicroMaterialRegistry.java | 23 ++++++++- .../codechicken/multipart/TileMultipart.java | 48 +++++++++++++++++-- 9 files changed, 203 insertions(+), 30 deletions(-) diff --git a/JAVA_MIGRATION.md b/JAVA_MIGRATION.md index 5985815..19ae30f 100644 --- a/JAVA_MIGRATION.md +++ b/JAVA_MIGRATION.md @@ -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 diff --git a/JAVA_MIGRATION_ABI_INVENTORY.md b/JAVA_MIGRATION_ABI_INVENTORY.md index a8c12cf..24bfe7b 100644 --- a/JAVA_MIGRATION_ABI_INVENTORY.md +++ b/JAVA_MIGRATION_ABI_INVENTORY.md @@ -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. diff --git a/JAVA_MIGRATION_CONSUMER_AUDIT.md b/JAVA_MIGRATION_CONSUMER_AUDIT.md index f99386c..574f0b0 100644 --- a/JAVA_MIGRATION_CONSUMER_AUDIT.md +++ b/JAVA_MIGRATION_CONSUMER_AUDIT.md @@ -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. diff --git a/JAVA_MIGRATION_HANDOFF.md b/JAVA_MIGRATION_HANDOFF.md index 370ae19..ca5b38f 100644 --- a/JAVA_MIGRATION_HANDOFF.md +++ b/JAVA_MIGRATION_HANDOFF.md @@ -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 diff --git a/docs/API.md b/docs/API.md index 6e72b0b..4b750f7 100644 --- a/docs/API.md +++ b/docs/API.md @@ -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. diff --git a/docs/migration/HISTORY.md b/docs/migration/HISTORY.md index 04d8d0c..d0a2bca 100644 --- a/docs/migration/HISTORY.md +++ b/docs/migration/HISTORY.md @@ -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. diff --git a/src/main/scala/codechicken/microblock/MicroMaterialRegistry$.java b/src/main/scala/codechicken/microblock/MicroMaterialRegistry$.java index 31b80eb..9d8906c 100644 --- a/src/main/scala/codechicken/microblock/MicroMaterialRegistry$.java +++ b/src/main/scala/codechicken/microblock/MicroMaterialRegistry$.java @@ -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 readIDMap(PacketCustom packet) { return MicroMaterialRegistry.readIDMap(packet); } diff --git a/src/main/scala/codechicken/microblock/MicroMaterialRegistry.java b/src/main/scala/codechicken/microblock/MicroMaterialRegistry.java index 7ae9dbb..a85f460 100644 --- a/src/main/scala/codechicken/microblock/MicroMaterialRegistry.java +++ b/src/main/scala/codechicken/microblock/MicroMaterialRegistry.java @@ -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> 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 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 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 readIDMap(PacketCustom packet) { int k = packet.readInt(); diff --git a/src/main/scala/codechicken/multipart/TileMultipart.java b/src/main/scala/codechicken/multipart/TileMultipart.java index 4aa5f75..d83c9e5 100644 --- a/src/main/scala/codechicken/multipart/TileMultipart.java +++ b/src/main/scala/codechicken/multipart/TileMultipart.java @@ -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 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) {} /**