API Integration

EmakiGem exposes a static facade, EmakiGemApi, for version, plugin-name, and readiness probes. Full gem inlay, extraction, socket opening, and upgrade flows should still use configuration, commands, GUI, and PlaceholderAPI.

Recommended integration

1. Public API probes: Use EmakiGemApi or CoreLib JavaScript emaki.module("gem") to check whether the module is available.
2. Commands: Use /egem inspect or /egem gui for management operations.
3. PlaceholderAPI: Use %emakigem_mainhand_*% placeholders to read gem state.
4. Configuration-driven: Use gems/*.yml, items/*.yml, and config.yml for most needs.

EmakiGemApi

Method	Description
available()	Whether the API is installed.
apiVersion()	Return the API version.
pluginName()	Return the plugin name.
isReady()	Whether the plugin has finished initializing.

if (EmakiGemApi.available() && EmakiGemApi.isReady()) {
    logger.info("Gem API version: " + EmakiGemApi.apiVersion());
}

If you prefer the migration helper, check availability first:

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

EmakiGemApiProvider.requireAvailable();

Requirements

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

Do not modify player inventories or Bukkit ItemStacks from asynchronous threads.

JavaScript access

CoreLib JavaScript scripts access the Gem script module through emaki.module("gem"). Besides identity and readiness probes, the script module can register socket rules and set bonuses; the Java-side EmakiGemApi does not offer these registration capabilities.

Method	Description
registerSocketRule(definition) / registerSocketRule(id, definition)	Register a socket rule.
unregisterSocketRule(id)	Unregister a socket rule.
registeredSocketRules()	Return registered socket rule ids.
registerSetBonus(definition) / registerSetBonus(id, definition)	Register a set bonus.
unregisterSetBonus(id)	Unregister a set bonus.
registeredSetBonuses()	Return registered set bonus ids.

Field and callback contracts are documented in JavaScript.

Method	Description
available()	Whether the Gem API is registered.
apiVersion()	Return the API version.
pluginName()	Return the plugin name.
ready()	Whether the plugin has finished initializing.

function main(ctx) {
  if (emaki.module("gem").available() && emaki.module("gem").ready()) {
    emaki.logger.info("Gem module ready: " + emaki.module("gem").apiVersion());
  }
  return true;
}

Item layer preview with EmakiItem

EmakiGem's item layer preview provider lives in its own integration package and registers through EmakiItemApi under the layer id gem.

• When EmakiItem is absent or disabled, nothing is registered and the no-op path is used; the rest of EmakiGem is unaffected.
• The integration is registered and released automatically as EmakiItem is enabled or disabled.
• This preview capability is provided by EmakiItem and no longer goes through CoreLib.

Internal service boundary

Core service classes in source:

Service	Responsibility
GemStateService	Read/write gem state in item PDC.
GemInlayService	Execute inlay and extraction logic.
GemUpgradeService	Execute gem upgrade logic.
SocketOpenerService	Execute socket opening logic.
GemResonanceService	Evaluate gem resonance effects.
GemGuiService	Manage gem GUI sessions.

These services are held internally by EmakiGemPlugin and are not exposed as a full gameplay operation API. External scripts and plugins should not depend on these implementation classes.

Thread safety

• Static config reads can be cached asynchronously, but ItemStack mutations must happen on the main thread.
• Do not operate on player inventories, world drops, or event objects from async tasks.
• If you access Gem services via reflection or internal classes, you assume version compatibility risk.

When you do not need an API

• Fixed gem definitions: use gems/*.yml.
• Fixed socket templates: use items/*.yml.
• Player manual socketing: use GUI and commands.
• Display values only: prefer placeholders.