JavaScript Scripting

EmakiGem registers a scripting module through the CoreLib scripting system. The module ID is gem. Inside a script you obtain the module facade with emaki.module("gem") to register socket rules and set bonuses.

This page covers only the EmakiGem-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. EmakiGem is a CoreLib softdepend.

Obtaining the module

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

Probe methods

Method	Returns	Description
available()	boolean	Whether the module is available.
ready()	boolean	Whether the module finished initialization.
apiVersion()	string	EmakiGem API version.
pluginName()	string	Plugin name.

Socket rules

Socket rules run during socket resolution. They can read the context and modify the success rate, allow/deny socketing, and set the prompt message.

Method	Returns	Description
registerSocketRule(definition)	boolean	Register a socket rule.
registerSocketRule(id, definition)	boolean	Overload: merge id into the definition, then register.
unregisterSocketRule(id)	void	Unregister a rule by id.
registeredSocketRules()	list	Return the list of registered socket 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	checkSocket	Rule callback function name; execute also works.
priority	int	no	0	Priority; lower runs first, ties broken by id.
gemIds	string / list	no	empty (all gems)	Gem ids the rule applies to; gems also works.
socketTypes	string / list	no	empty (all sockets)	Socket types the rule applies to; sockets also works.
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.
itemId	string	Target item id.
slotIndex	int	Socket index.
socketType	string	Socket type.
gemId	string	Gem id.
gemType	string	Gem type.
gemLevel	int	Gem level.
inlaidGems	list	Gems already socketed on the target item (before this socketing), each with slot / gemId / gemType / gemLevel.
inlaidGemCount	int	Number of gems currently socketed.
allowed	boolean	Whether socketing is currently allowed.
originalSuccessRate	double	Original success rate.
successRate	double	Current accumulated success rate.
messageKey	string	Current message key, defaults to gem.error.condition_not_met.
message	string	Current message.
traces	list	Traces from previous rules, each with id / before / after / message.

Rule callback return fields

Return field	Type	Description
cancel	boolean	When true, forcibly disallows socketing.
allowed	boolean	Whether allowed; combined with !cancel.
successRate	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).
messageKey	string	Override the message key.
message	string	Override the message text.

The final success rate is clamped to 0~100. Rules run serially in ascending priority order and stop as soon as a rule disallows socketing.

Set bonuses

A set bonus is evaluated per item and can append name actions and lore actions.

Method	Returns	Description
registerSetBonus(definition)	boolean	Register a set bonus.
registerSetBonus(id, definition)	boolean	Overload: merge id into the definition, then register.
unregisterSetBonus(id)	void	Unregister a set bonus by id.
registeredSetBonuses()	list	Return the list of registered set bonus ids.

Bonus definition fields

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

Set bonuses have no priority and no gem/socket filtering; all bonuses are evaluated per item in id lexical order.

Bonus callback ctx fields

Field	Type	Description
bonusId	string	Current bonus id.
itemId	string	Item id.
gems	list	Socketed gems, each with id / type / level.
gemIds	list	List of gem ids.
gemTypes	list	List of gem types.
socketCount	int	Number of socket assignments.

Bonus callback return fields

Return field	Type	Description
nameActions	list	Item name modification actions passed to the action system.
loreActions	list	Item lore modification actions, e.g. {op:"append", value:"..."}.

The result is only collected and applied when at least one of nameActions or loreActions is non-empty.

Full example

EmakiGem ships the example script scripts/examples/gem_status.js:

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

  gem.registerSocketRule({
    id: "example_socket_bonus",
    priority: 10,
    function: "checkSocket"
  });

  gem.registerSetBonus({
    id: "example_lore_bonus",
    function: "applySetBonus"
  });
}

function checkSocket(ctx) {
  if (ctx.gemLevel >= 3) {
    return {
      successBonus: 5,
      message: "Example: +5% socket success for gems above level 3"
    };
  }
  return {};
}

function applySetBonus(ctx) {
  if (ctx.gemIds.length >= 3) {
    return {
      loreActions: [{
        op: "append",
        value: "<gold>JavaScript set example: 3+ gems socketed"
      }]
    };
  }
  return {};
}

Enabling extension scripts

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

plugins/EmakiCoreLib/scripts/extensions/global/gem_status.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, EmakiGem 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:

/gem debug module script

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 bonuses have no effect but raise no error.
• Socket rules run in ascending priority order (lower first) and stop subsequent rules as soon as one disallows socketing.