JavaScript Scripting

EmakiStrengthen registers a scripting module through the CoreLib scripting system. The module ID is strengthen. Inside a script you obtain the module facade with emaki.module("strengthen") to read strengthen state and register strengthen chance rules and result hooks.

This page covers only the EmakiStrengthen-specific script methods, registration fields, context and examples. For the generic scripting mechanism see CoreLib JavaScript Scripting.

Always guard with available() before calling any business method. EmakiStrengthen is a CoreLib softdepend.

Obtaining the module

function main(ctx) {
  const strengthen = emaki.module("strengthen");
  if (!strengthen.available()) {
    return { skipped: true, message: "EmakiStrengthen unavailable" };
  }
  // ...
  return true;
}

Probe methods

Method	Returns	Description
available()	boolean	Whether the module is available.

The EmakiStrengthen module facade only exposes available(); it has no ready() / apiVersion() / pluginName().

Item queries and rebuild

The methods below take an itemKey, which resolves an ItemStack from the current action context by attribute key. The available keys are determined by the module that triggers the script.

Method	Returns	Description
canStrengthen(itemKey)	boolean	Whether the item can be strengthened.
readState(itemKey)	map	Read the strengthen state summary.
rebuild(itemKey)	map	Rebuild the item and return an item summary (type / amount / displayName).

Fields returned by readState(itemKey):

Field	Type	Description
eligible	boolean	Whether the item can be strengthened.
eligibleReason	string	Reason key when not eligible.
hasLayer	boolean	Whether a strengthen layer exists.
baseSource	string	Base item source.
baseSourceSignature	string	Base item source signature.
recipeId	string	Matched strengthen recipe id.
currentStar	int	Current star.
crackLevel	int	Temper level.
milestoneFlags	list	Stars already reached.
successCount	int	Total successes.
failureCount	int	Total failures.
lastAttemptAt	long	Timestamp of the last attempt.
branchPath	string	Branch path.
fractureLevel	int	Fracture level.

Returns an empty map when called inside a script worker boundary.

Strengthen chance rules

Chance rules run during strengthen resolution. They can read the context and modify the success rate, the resulting star on failure, the temper value on failure and whether protection is applied.

Method	Returns	Description
registerChanceRule(definition)	boolean	Register a chance rule.
registerChanceRule(id, definition)	boolean	Overload: merge id into the definition, then register.
unregisterChanceRule(id)	void	Unregister a rule by id.
registeredChanceRules()	list	Return the list of registered chance rule ids.

Rule definition fields

Field	Type	Required	Default	Description
id	string	yes	none	Unique rule id (normalized); registration fails when blank.
function	string	no	modifyChance	Rule callback function name; execute also works.
priority	int	no	0	Priority; lower runs first, ties broken by id.
timeoutMillis	long	no	engine default	Per-call script timeout.

Rule callback ctx fields

Field	Type	Description
ruleId	string	Current rule id.
playerUuid	string	Player UUID.
playerName	string	Player name.
recipeId	string	Strengthen recipe id.
currentStar	int	Current star level.
targetStar	int	Target star level.
temperLevel	int	Current temper / crack value.
originalSuccessRate	double	Original success rate.
successRate	double	Current accumulated success rate.
failureStar	int	Resulting star on failure.
failureTemper	int	Resulting temper on failure.
protectionApplied	boolean	Whether protection is applied.
targetItem	map	Summary of the item being strengthened: type / amount / displayName, optional lore (plain lines) / customModelData.
requiredMaterials	list	Required materials, each with item / requiredAmount / availableAmount / consumedAmount / optional / protection / temperBoost.
optionalMaterials	list	Optional materials, same fields as requiredMaterials.
traces	list	Traces from previous rules, each with id / before / after / message.

A rule only runs when the current strengthen preview is eligible.

Rule callback return fields

Return field	Type	Description
successRate or chance	number	Set the success rate directly (takes priority).
successBonus	number	Add to the current success rate (when no successRate).
successMultiplier	number	Multiply the current success rate (applied after bonus).
failureStar	int	Override the resulting star on failure.
failureTemper	int	Override the resulting temper on failure.
protectionApplied	boolean	Override whether protection is applied.
failureProtected	boolean	Failure-protection alias: applies protection and pins the resulting star to the current star.
downgradeProtected	boolean	Downgrade-protection alias, same effect as failureProtected.
extraCosts	list	Extra cost entries (read-only exposure for display/audit; not actually consumed in this batch).
message	string	Message written to the trace.

The final success rate is clamped to 0~100. Multiple rules accumulate serially in ascending priority order.

Strengthen result hooks

Result hooks fire after strengthen resolution, for side effects such as rewards and broadcasts.

Method	Returns	Description
onResult(definition)	boolean	Register a strengthen result hook.
onResult(id, definition)	boolean	Overload: merge id into the definition, then register.
unregisterResultHook(id)	void	Unregister a result hook by id.
registeredResultHooks()	list	Return the list of registered result hook ids.

Hook definition fields

Field	Type	Required	Default	Description
id	string	yes	none	Unique hook id; registration fails when blank.
function	string	no	onStrengthenResult	Callback function name; execute also works.
timeoutMillis	long	no	engine default	Per-call script timeout.

Result hooks have no priority field; multiple hooks fire in id lexical order.

Hook callback event fields

Field	Type	Description
hookId	string	Hook id.
playerUuid	string	Player UUID.
playerName	string	Player name.
success	boolean	Whether the strengthen succeeded.
errorKey	string	Failure error key.
resultingStar	int	Resulting star level.
resultingTemper	int	Resulting temper value.
newlyReachedStars	list	Star levels newly reached this attempt.
replacements	map	Text replacement map.

When the attempt carries preview information, the event also includes recipeId, currentStar, targetStar, successRate, failureStar, failureTemper, protectionApplied and maxLevel (boolean, whether the resulting star already reached the recipe's maximum star).

The hook callback may return { actions: [...] }, where actions is an array of action-line strings that the plugin runs in order through the CoreLib ActionExecutor. The action-line syntax matches the actions used in recipes, e.g. "sendmessage text=\"<green>...\"", "playsound sound=minecraft:... volume=1 pitch=1". A failure only logs a warning to the console and does not affect the completed strengthen result.

Placeholders available in action lines:

Placeholder	Description
%success%	Whether the attempt succeeded.
%strengthen_star%	Resulting star level.
%strengthen_temper%	Resulting temper value.
%strengthen_recipe_id%	Strengthen recipe id.

Example returning actions:

function onStrengthenResult(event) {
  if (event.success) {
    return {
      actions: [
        "sendmessage text=\"<green>Strengthen succeeded, now %strengthen_star% stars\"",
        "playsound sound=minecraft:entity.player.levelup volume=1 pitch=1"
      ]
    };
  }
  return {};
}

Full example

EmakiStrengthen ships the example script scripts/examples/strengthen_success.js:

function register() {
  const strengthen = emaki.module("strengthen");

  strengthen.registerChanceRule({
    id: "example_vip_bonus",
    priority: 10,
    function: "modifyChance"
  });

  strengthen.onResult({
    id: "example_result_notice",
    function: "onStrengthenResult"
  });
}

function modifyChance(ctx) {
  if (ctx.playerName && ctx.targetStar >= 5) {
    return {
      successBonus: 2.5,
      message: "Example: +2.5% success rate above 5 stars"
    };
  }
  return {};
}

function onStrengthenResult(event) {
  emaki.logger.info("Strengthen result hook: recipe=" + event.recipeId + ", success=" + event.success + ", star=" + event.resultingStar);
}

Enabling extension scripts

Put the script into CoreLib's global extension directory and reload:

plugins/EmakiCoreLib/scripts/extensions/global/strengthen_success.js

/corelib script reload

The example file is released to plugins/EmakiCoreLib/scripts/examples/ by default and is not auto-enabled.

Script debugging

When you enable the debug submodule named script, EmakiStrengthen writes the per-rule execution trace to the server console every time its JS rules run, which helps server administrators debug script rules.

Enable command:

/estrengthen debug module script

Available debug submodules: attempt, state, gui, script, pdc.

Trace fields: rule id, before (value before execution), after (value after execution) and message. This output goes to the server console for server administrators to debug; it is not shown to players.

Notes

• Every registration method requires the CoreLib scripting system to be enabled; otherwise registration returns false or is silently skipped.
• When CoreLib is missing the module degrades gracefully: rules and hooks have no effect but raise no error.
• Chance rules run in ascending priority order (lower first).