API Integration

EmakiStrengthen exposes the static facade EmakiStrengthenApi for reading strengthen state, previewing attempts, performing strengthening, and rebuilding the strengthen layer presentation. Prefer configuration and GUI for normal gameplay; use the API only for cross-plugin integration.

Requirements

dependencies:
  server:
    EmakiStrengthen:
      load: BEFORE
      required: false
      join-classpath: true

Callers should check available() after the plugin is enabled and degrade gracefully when the module is absent. Do not assume every server has Strengthen installed.

EmakiStrengthenApi

Method	Returns	Description
available()	boolean	Whether the API bridge is installed.
canStrengthen(ItemStack)	boolean	Whether the item can be strengthened. null returns false.
readState(ItemStack)	StrengthenState	Read the item's current strengthen state. Never null.
preview(Player, AttemptContext)	AttemptPreview	Compute a non-committing preview. Never null.
attempt(Player, AttemptContext)	AttemptResult	Perform an attempt and charge configured economy costs. Never null.
rebuild(ItemStack)	ItemStack	Rebuild the strengthen layer presentation from stored state. Returns the original item when unavailable.

Model classes live in the emaki.jiuwu.craft.strengthen.model package. When the API is unavailable, readState returns an ineligible state and preview / attempt return results carrying strengthen.error.api_unavailable.

Reading strengthen state

ItemStack item = player.getInventory().getItemInMainHand();
if (!EmakiStrengthenApi.available() || !EmakiStrengthenApi.canStrengthen(item)) {
    return;
}

StrengthenState state = EmakiStrengthenApi.readState(item);
player.sendMessage("Current strengthen star: +" + state.currentStar());

Common StrengthenState methods: eligible(), eligibleReason(), recipeId(), currentStar(), temperLevel(), crackLevel(), successCount(), failureCount(), branchPath(), hasLayer(), firstReachFlags().

Previewing and performing a strengthen

AttemptPreview preview = EmakiStrengthenApi.preview(player, context);
if (!preview.eligible()) {
    player.sendMessage("Cannot strengthen: " + preview.errorKey());
    return;
}

AttemptResult result = EmakiStrengthenApi.attempt(player, context);
if (result.resultItem() != null) {
    player.getInventory().setItemInMainHand(result.resultItem());
}

attempt treats AttemptContext as cloned input data: it does not mutate or remove the target item or material stacks supplied in the context. Callers must apply the returned resultItem() themselves and handle any external inventory material consumption. The built-in GUI consumes or returns its hosted material stacks after reading the result preview's per-slot consumed amounts.

Use AttemptResult.success() to determine the outcome, outcome() to distinguish commit semantics (AttemptOutcome), and operationId() to correlate one operation.

Thread safety

• Strengthening modifies ItemStacks and player inventories and must run on the main server thread.
• StrengthenPreAttemptEvent and StrengthenTransferEvent fire only on the player's owner thread; non-owner paths skip the events.
• Economy and database work can be prepared asynchronously, but return to the main thread before writing back to the item.
• Replace the original item with the returned item so stale references are not mutated by other logic.

Usage boundaries

• Fixed success rates, materials, and protection materials: use recipe configuration.
• Manual player strengthening: use the GUI.
• Quest or achievement listeners: use the events.
• Adjusting success rates or adding result side effects: use events or JavaScript rules.

JavaScript access

CoreLib JavaScript scripts can use emaki.module("strengthen") to inspect strengthen state. The JS wrapper only exposes safe read/display helpers; actual strengthen attempts should still go through Strengthen recipes, GUI, or the Java API because they involve materials, economy, and inventory writes.

Method	Description
available()	Whether the Strengthen API is registered.
canStrengthen(itemKey)	Whether a contextual item can be strengthened.
readState(itemKey)	Return a strengthen state summary map.
rebuild(itemKey)	Return a rebuilt item summary; does not write back to inventory.

See JavaScript for registering chance rules and result hooks.

function main(ctx) {
  if (!emaki.module("strengthen").available()) {
    return { skipped: true, message: "Strengthen not installed" };
  }

  const state = emaki.module("strengthen").readState("target_item");
  if (state.eligible) {
    emaki.player.sendMessage("Current strengthen star: +" + state.currentStar);
  }
  return true;
}