API

EmakiItem exposes item creation, identification, and query capabilities. The public API is a static facade, EmakiItemApi; the plugin installs a bridge during enable and removes it on disable.

EmakiItemApi

Method	Return	Description
available()	boolean	Whether the EmakiItem API is installed.
isReady()	boolean	Whether EmakiItem finished initializing and can resolve item definitions. Returns false while a reload is in progress.
exists(String id)	boolean	Whether an item id is loaded.
create(String id, int amount)	ItemStack	Create a new ItemStack from an EmakiItem id. Returns null if missing or unavailable.
identify(ItemStack itemStack)	String	Identify the EmakiItem id from an ItemStack. Returns null if not an EmakiItem.
definitionIds()	Set<String>	All loaded item ids.
displayName(String id)	String	Plain display name for an item id; empty string for an unknown id or unavailable API.
definition(String id)	ConfiguredItemDefinition	Return the normalized shared base-item definition; null for an unknown id or unavailable API.
registerLayerPreview(Plugin plugin, ItemLayerPreviewProvider provider)	ItemLayerPreviewRegistration	Register an item layer preview provider; returns a safely closeable no-op handle when EmakiItem is unavailable.

Getting the API

if (EmakiItemApi.available()) {
    ItemStack stack = EmakiItemApi.create("example_sword", 1);
}

Or use the provider helper:

if (!EmakiItemApiProvider.available()) {
    return;
}

EmakiItemApiProvider.requireAvailable();
ItemStack stack = EmakiItemApi.create("example_sword", 1);

Notes

• Check availability after EmakiItem has loaded.
• If the API is unavailable, degrade gracefully instead of crashing a soft dependency.
• create returns a fresh item with PDC and presentation data.
• identify uses PDC identity data and does not rely on lore or display name.
• definition returns a version-independent CoreLib API DTO and does not expose EmakiItem internals or Paper experimental component value classes.
• definition is additive; the Bridge default returns null, preserving linkage for older bridge implementations.
• available() only reports that the bridge is installed. Use isReady() when item definitions must be resolvable.

Item layer preview SPI

The item layer preview SPI lives in the EmakiItemApi module under emaki.jiuwu.craft.item.api.preview. Third parties register providers through EmakiItemApi.registerLayerPreview.

Type	Description
ItemLayerPreviewProvider	Provider interface: id() returns the stable layer id, order() controls ordering (default 100, lower applies first), and preview(request) produces the result.
ItemLayerPreviewRequest	Immutable request snapshot with itemId, baseItem, currentItem, and options. Item fields are cloned on both input and output.
ItemLayerPreviewResult	Immutable result with id, available, reason, itemStack, details, options, and selected, plus available(...) and unavailable(...) factories.
ItemLayerPreviewRegistration	Closeable registration handle implementing AutoCloseable; noop() returns a reusable empty handle.

Registry semantics (EmakiItemLayerPreviewRegistry, instance-level and owner-aware):

• Layer ids are normalized by trimming and lowercasing. A blank id or a null provider/owner yields a no-op handle.
• Re-registering the same id replaces the previous record and is generation-guarded, so closing a stale handle never removes a newer registration.
• Lookups return a stable order: ascending order(), then lexicographic id.
• Providers owned by a disabled plugin are removed automatically, and PluginDisableEvent triggers cleanup for that owner.
• If a provider throws or returns null, only that layer degrades to unavailable; the remaining layers still run.

ItemLayerPreviewRegistration registration = EmakiItemApi.registerLayerPreview(this, new ItemLayerPreviewProvider() {
    @Override
    public String id() {
        return "my_layer";
    }

    @Override
    public ItemLayerPreviewResult preview(ItemLayerPreviewRequest request) {
        return ItemLayerPreviewResult.unavailable(id(), "not configured", Map.of(), Map.of());
    }
});

Call registration.close() on plugin disable to release the registration. strengthen and gem are built-in layer ids and appear as unavailable placeholders when those modules are not loaded.

JavaScript access

CoreLib JavaScript scripts reach the EmakiItem module facade through emaki.module("item"); emaki.module("items") is an equivalent alias. emaki.item is still the contextual ItemStack helper; emaki.module("item") is the plugin API entry.

Method	Description
available()	Whether the EmakiItem API is registered.
exists(id)	Whether an item definition is loaded.
create(id, amount)	Return an item summary snapshot; does not put it into an inventory.
identify(itemKey)	Identify the EmakiItem id of the item stored under that context attribute key.
definitionIds()	Return all item definition ids.
displayName(id)	Return the plain display name.

See JavaScript scripting for the full method set, including runtime definition and item factory registration.

function main(ctx) {
  const item = emaki.module("item");
  if (!item.available()) {
    return { skipped: true, message: "EmakiItem not installed" };
  }

  const id = item.identify("item_stack");
  const preview = item.create("example_sword", 1);
  emaki.logger.info("current=" + id + ", preview=" + preview.displayName);
  return true;
}