API 接入

当前版本的 EmakiGem 没有暴露稳定的 public API 接口（源码中不存在 EmakiGemApi 接口类）。如果需要在其他插件中读取装备宝石状态或执行镶嵌操作，推荐通过以下方式接入：

推荐接入方式

命令：使用 /egem inspect 或 /egem gui 命令完成管理操作。
PlaceholderAPI：通过 %emakigem_mainhand_*% 占位符读取装备宝石状态。
PDC 读取：直接读取物品 PDC 中 emaki_gem namespace 下的数据（需要了解内部格式，不保证跨版本兼容）。
配置驱动：通过 gems/*.yml、items/*.yml 和 config.yml 配置完成绝大多数需求。

接入前提

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

yaml

softdepend:
  - EmakiGem

内部服务边界

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

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

这些服务目前通过插件主类 EmakiGemPlugin 内部持有，没有通过 Bukkit ServicesManager 暴露。如果未来版本提供稳定 API，文档会同步更新。

线程安全

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

什么时候不用 API

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