ForgeMultipart/docs/api/MATERIAL_ACCESS.md

Read a microblock's block and metadata

Use the existing public BlockMicroMaterial.block() and meta() methods. Neither reflection nor an accessor mixin is needed. The compiling Java example implements GuideNH's complete primary-material query using typed calls:

1. Traverse TileMultipart.jPartList() in its stored order.
2. For each Microblock, resolve material() through MicroMaterialRegistry.getMaterial(int).
3. If the result is a BlockMicroMaterial, read block() then meta().
4. Skip null/air blocks and absent/empty block registry names; return the first usable block ID.

For example, wool with metadata 14 exports as minecraft:wool:14. GuideNH appends a metadata suffix only when the value is positive; zero and negative values export the unsuffixed block ID. This is GuideNH's export convention, not a general material serialization format. The example preserves positive values above 15 without masking.

Identity, lifecycle and overrides

• block() returns the constructor's block by identity in the base implementation, including null. meta() returns the original integer unchanged. Both are public virtual methods; consumer calls must respect subclass overrides.
• A microblock's numeric material() value is an ID in the active material map, not block metadata. Query after registry initialization and, on a client, material-ID synchronization. Do not persist these numeric IDs across sessions; see material enumeration.
• IMicroMaterial does not promise a block/meta representation. Skip non-block materials for this block-only query; do not cast every registered material to BlockMicroMaterial or infer its block from an item drop.
• blockKey() caches the constructor block's registry name. It can differ from an overridden block() and from the material's registered name. Export the registry name of the returned block, as the example does.
• This is a read operation with no binding, world access, material registration or tile mutation. Observe the part-list ownership contract; the traversal is not a snapshot.

GuideNH migration

Replace resolvePrimaryMicroblockId's reflective part traversal, material lookup and AccessorBlockMicroMaterial field reads with the typed example. Remove that mixin and its configuration entry when the consumer migrates. Keep FMP's private fields unchanged until the migrated consumer release is adopted; this branch does not edit the reference consumer checkout or claim adoption.

The old mixin reads constructor fields directly, bypassing overrides. The old reflection fallback already calls the public virtual getters. The supported typed path follows those getters too, so custom materials that override them may produce a different export from the mixin. Validate those materials in GuideNH; do not introduce raw-field accessors to preserve an implementation detail that disagrees with the material's public behavior.

The example returns null for a null/non-multipart tile or no usable block. Invalid material IDs and exceptions from custom accessors propagate. GuideNH currently logs query failures and returns null from its outer integration boundary; retain that policy around the typed call. Do not catch a broken material and silently select a later part. Metadata is read before the null/air check, preserving accessor order even for a skipped block.

For optional FMP support, isolate typed code in a compatibility class and load it only after checking mod presence and the supported dependency version. Keep FMP types out of classes loaded unconditionally when FMP is absent. An optional dependency does not itself require reflection. The API index describes the current unreleased branch/version status; pin an artifact containing every method used by the integration.

Validation

JVM characterization pins constructor identity, every metadata bit, virtual dispatch and the retained private fields. Dedicated-server Forge tests cover initialized material lookup, ordered filtering, registry aliases, null/air/unregistered blocks, non-block materials, metadata formatting, overridden accessors and failure propagation. The example compiles with Scala excluded from its classpath and contains no reflection, companion or Scala calls. Actual GuideNH exports and optional-mod absent/present loading remain consumer adoption checks.