API 接入

EmakiGem 对外公开的是静态门面 EmakiGemApi，用于提供版本、插件名和就绪状态探针。宝石镶嵌、开孔、升级等完整玩法流程仍以配置、命令、GUI 和 PlaceholderAPI 为主要入口。

EmakiGemApi

方法	说明
`available()`	判断 API 是否已安装。
`apiVersion()`	返回 API 版本。
`pluginName()`	返回插件名。
`isReady()`	判断插件是否已完成初始化。

java

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

如果你更喜欢迁移辅助类，也可以先做可用性检查：

java

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

EmakiGemApiProvider.requireAvailable();

接入前提

服务器已安装并启用 Gem 模块。
调用方插件在 paper-plugin.yml 中声明可选依赖。
不要在异步线程直接修改 Bukkit 物品或玩家背包。

yaml

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

JavaScript 调用

CoreLib JavaScript 脚本中可通过 emaki.module("gem") 访问 Gem 脚本模块。除身份与就绪探针外，脚本模块还可以注册镶嵌规则与套装加成；Java 侧的 EmakiGemApi 不提供这些注册能力。

方法	说明
`available()`	判断 Gem API 是否已注册。
`apiVersion()`	返回 API 版本。
`pluginName()`	返回插件名。
`ready()`	判断插件是否完成初始化。
`registerSocketRule(definition)` / `registerSocketRule(id, definition)`	注册镶嵌规则。
`unregisterSocketRule(id)`	注销镶嵌规则。
`registeredSocketRules()`	返回已注册镶嵌规则 ID 列表。
`registerSetBonus(definition)` / `registerSetBonus(id, definition)`	注册套装加成。
`unregisterSetBonus(id)`	注销套装加成。
`registeredSetBonuses()`	返回已注册套装加成 ID 列表。

字段与回调约定详见 JavaScript 脚本。

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

与 EmakiItem 的物品层预览

EmakiGem 的物品层预览提供者位于自身的 integration 包，通过 EmakiItemApi 注册，层 ID 为 gem。

EmakiItem 未安装或未启用时不注册，走 no-op 路径，不影响 EmakiGem 其余功能。
EmakiItem 启用或禁用时会自动注册 / 释放该集成。
该预览能力由 EmakiItem 提供，不再经由 CoreLib。

内部服务边界

Gem 模块的核心服务类包括：

服务	职责
`GemStateService`	读取/写入装备 PDC 中的宝石状态。
`GemInlayService`	执行镶嵌、取出逻辑。
`GemUpgradeService`	执行宝石升级逻辑。
`SocketOpenerService`	执行开孔逻辑。
`GemResonanceService`	计算宝石共鸣效果。
`GemGuiService`	管理宝石 GUI 会话。

这些服务目前通过插件主类 EmakiGemPlugin 内部持有，没有作为完整玩法操作 API 暴露。外部脚本或插件不应依赖这些实现类。

线程安全

读取静态配置可以异步缓存，但最终修改 ItemStack 必须回到主线程。
不要在异步任务里直接操作玩家背包、世界掉落或事件对象。
如果通过反射或内部类访问 Gem 服务，需自行承担版本兼容风险。

什么时候不用 API

固定宝石定义：使用 gems/*.yml。
固定插槽模板：使用 items/*.yml。
玩家手动镶嵌：使用 GUI 和命令。
只需要展示数值：优先使用占位符。

API 接入 ​

推荐接入方式 ​

EmakiGemApi ​

接入前提 ​

JavaScript 调用 ​

与 EmakiItem 的物品层预览 ​

内部服务边界 ​

线程安全 ​

什么时候不用 API ​