ForgeMultipart/docs/api/PART_REGISTRATION.md

# Registering part factories from Java

[API index](../API.md)

Use `MultiPartRegistry.registerPartFactory(IPartFactory2, String...)`. It delegates to the existing registry and
avoids the Scala types in the `registerParts` overload family.

To inspect a registered factory without constructing a part, see [factory lookup](FACTORY_LOOKUP.md), including
Schematica's replacement for private registry-map reflection.

## Example and timing

The [complete compiling example](../../src/functionalTest/java/codechicken/multipart/examples/PartRegistrationExample.java)
implements both required `IPartFactory2.createPart` methods, opts into saved-NBT client previews, and registers one
persistent type:

```java
MultiPartRegistry.registerPartFactory(new PartRegistrationExample(), PartRegistrationExample.PART_TYPE);
```

Call from your mod's common `preInit` or `init` handler on both sides, before FMP closes registration in `postInit`.
FML must have an active mod container; that container becomes the owner returned by `getModContainer(type)`.
Registration stores the factory without constructing, loading, binding or placing a part.

The example creates fresh, unbound instances whose `getType()` returns `yourmod:part`. Replace that sample ID and part
implementation with your own. Geometry, rendering and gameplay callbacks belong to the real part. Preserve already
published IDs exactly when migrating; adding a namespace to an existing ID changes its save/network identity.
Both single IDs and arrays are accepted. Multiple names can share a factory that selects the part class by name.

## Factory and payload ownership

`IPartFactory2` has two abstract methods, so it is not a single-method lambda interface. Its third method is an
optional default:

| Construction path | Factory input | What happens next |
| --- | --- | --- |
| Server/NBT | `createPart(String, NBTTagCompound)` receives the original tag object | Normal reconstruction calls `part.load` with that same tag |
| Client/description | `createPart(String, MCDataInput)` receives the original input, after the registry ID | Normal reconstruction calls `part.readDesc` with that same input at its current cursor |
| Client preview/NBT | `createPartForClientPreview(String, NBTTagCompound)` receives the original tag object | [Preview reconstruction](CLIENT_PREVIEW.md) calls `part.load` with that same tag; the default returns null |

A factory may inspect NBT or consume a packet discriminator to choose a class. There is no packet copy or rewind;
coordinate any consumed prefix with the part's `writeDesc` and `readDesc` protocol. FMP's microblock factory consumes
the material ID this way. Do not call `load` or `readDesc` in the factory merely to initialize the remaining payload,
because normal reconstruction calls them afterward. Return a fresh, unbound part for every supported name.

Direct `MultiPartRegistry.loadPart` and `readPart` calls only construct the part; their caller remains responsible for
the following payload/lifecycle work. The deprecated `createPart(name, boolean)` passes a null NBT or packet argument;
factories reached through that old path must tolerate it. Neither registration entry adds eager factory validation.

## Ordering and failures

IDs are processed in array order. The array itself is not retained, so changing it afterward does not rename registered
parts. The factory object is retained. A duplicate ID throws immediately, leaving any earlier IDs from that call
registered and skipping the suffix. Registration is not transactional; fix duplicate IDs rather than retrying the
whole batch. Later server ID-map setup sorts registered names; registration order is not a stable network numeric ID.

The new entry preserves the old Java array entry's failure order: a closed registry fails first, then the registry
enters its registering state and checks FML's active container, then it reads the array. Empty arrays still perform
the state/container checks; a null array fails after them. Supply a non-null factory and valid, unique non-null names;
the legacy implementation does not eagerly validate those values. Iterator conversion in the retained Scala sequence
entry still occurs before these checks, so malformed Scala inputs can fail earlier.

Factory exceptions propagate when constructing parts, not during registration. A registration call does not probe
factory results or promise that a later NBT/packet will be accepted.

## Migrating old callers

- `IPartFactory2` callers: retain the factory and IDs, then call `registerPartFactory`. ProjectRed can keep its existing
  server/NBT and client/packet methods. Override `createPartForClientPreview` only when saved NBT can select a fresh
  client variant. Scala code can pass a `String[]`/`Array[String]` as Java varargs using `: _*`.
- `IPartFactory` or Scala `(String, Boolean) => TMultiPart` callers: implement `IPartFactory2`; route the NBT method to
  the old constructor with `false` and the packet method with `true`. Keep any side-specific class selection. A factory
  that ignores the old Boolean, such as ForgeRelocationFMP's frame factory, can construct the same part class in both.
- Keep [converter registration](BLOCK_CONVERTERS.md) and trait registration separate. This change neither replaces `registerConverter` nor
  completes ProjectRed's external microblock trait migration or Schematica's private registry-map migration.

All eight old static/companion registration descriptors remain. Both `IPartFactory2` sequence entries are now
deprecated; the older Boolean/function entries were already deprecated and now point to the supported replacement.
The old Java array entries remain callable too. Prefer the new name for consumer Java source: the old overload family
requires `scala.collection.Seq` and `scala.Function2` on the compile classpath even for Java factory/string inputs.