mirror of
https://github.com/GTNewHorizons/ForgeMultipart.git
synced 2026-11-17 11:05:06 +00:00
73 lines
4.3 KiB
Markdown
73 lines
4.3 KiB
Markdown
# Enumerating microblock materials from Java
|
|
|
|
[API index](../API.md)
|
|
|
|
The `algent/java` branch adds `MicroMaterialRegistry.materialCount()`. Use it with the existing
|
|
`materialName(int)` and `getMaterial(int)` methods to enumerate materials without importing Scala types.
|
|
This API is not yet tied to a published release; consumers must require an FMP version containing the addition.
|
|
|
|
## Example
|
|
|
|
The following method copies the active material names in numeric ID order:
|
|
|
|
```java
|
|
public static List<String> materialNames() {
|
|
int count = MicroMaterialRegistry.materialCount();
|
|
List<String> names = new ArrayList<>(count);
|
|
for (int id = 0; id < count; id++) {
|
|
names.add(MicroMaterialRegistry.materialName(id));
|
|
}
|
|
return names;
|
|
}
|
|
```
|
|
|
|
Imports and the enclosing class are in the [compiling example](../../src/test/java/codechicken/microblock/examples/MaterialEnumerationExample.java).
|
|
It is compiled and exercised by the normal `test` task. It also compiles with only the FMP dev jar and Java 8 APIs on
|
|
the compile classpath; this does not remove FMP's runtime dependencies. Use `MicroMaterialRegistry.getMaterial(id)` in the loop when
|
|
you also need the `IMicroMaterial`, for example to obtain its item. That returns the registered instance, not a copy.
|
|
The example's list is an independent copy; editing it does not change the registry.
|
|
|
|
## Timing, order and identity
|
|
|
|
- Enumerate after ForgeMicroblock has built its ID map during post-initialization. A consumer's own post-init handler
|
|
needs suitable mod ordering if it enumerates there; later lifecycle/game callbacks can use the initialized map.
|
|
Consumers must not call `setupIDMap()` themselves to force readiness.
|
|
- On a multiplayer client, enumeration of the connected server's IDs requires a completed, successful FMP handshake.
|
|
FMP also rebuilds the local map before server startup. Reacquire IDs after map replacement.
|
|
- Use the game/lifecycle thread. The calls are live lookups, not an atomic snapshot: do not rebuild the map or perform
|
|
registration/handshake work from inside an enumeration loop.
|
|
- Local setup orders IDs by material name. A multiplayer client adopts server order; do not sort or filter IDs when
|
|
preserving a mapping. Store material names in saved data and resolve their numeric IDs for the active map.
|
|
- `materialCount()` counts ID slots, including the missing-material placeholder when present. It throws
|
|
`IllegalStateException` before initialization and returns zero for an initialized empty map.
|
|
- A failed handshake can leave unresolved slots. The count includes them; `materialName(id)` and `getMaterial(id)`
|
|
retain their existing `NullPointerException` for such slots. FMP disconnects the client for missing mappings.
|
|
The count is not a handshake-success indicator, and callers should not silently skip unresolved IDs.
|
|
- The existing indexed lookups throw `ArrayIndexOutOfBoundsException` outside the active ID range and
|
|
`NullPointerException` before map initialization.
|
|
|
|
## Migrating existing consumers
|
|
|
|
| Legacy expression | Java API |
|
|
| --- | --- |
|
|
| `getIdMap().length` | `materialCount()` |
|
|
| `getIdMap()[id]._1()` | `materialName(id)` |
|
|
| `getIdMap()[id]._2()` | `getMaterial(id)` |
|
|
| Loop over the tuple array | Loop over IDs from zero to `materialCount()`, exclusive |
|
|
|
|
For UtilitiesInExcess, apply this to `FMPRecipeLoader.run()` and `UEMultipartItem.getSubItems()`: replace each tuple
|
|
loop with an ID loop and use `materialName(id)` wherever the tuple name was used. Preserve its recipe/item ordering,
|
|
filters and material-name NBT. A material object, when needed, is available from `getMaterial(id)`.
|
|
Extra Utilities' NEI handlers use both tuple fields; both indexed replacements are available.
|
|
|
|
The static and companion `getIdMap()` methods are deprecated, with their original descriptors and live-array
|
|
behavior retained. This change does not authorize removal of either method. The
|
|
[consumer adoption ledger](../../JAVA_MIGRATION_CONSUMER_AUDIT.md#java-api-adoption-ledger) records the migrations and
|
|
released pack versions still needed.
|
|
|
|
## Validation
|
|
|
|
The JVM tests cover the legacy array contract, initialization, server ordering, empty maps, unresolved slots, the
|
|
compiled Java example and the frozen Scala consumer. The Forge test checks that the Java enumeration matches the
|
|
initialized registry and the material-ID handshake payload. The public addition does not change packet or NBT formats.
|