API 接入

EmakiForge 对外公开的是静态门面 EmakiForgeApi，用于提供版本、插件名和就绪状态探针。锻造执行、品质计算、材料结算等完整玩法流程仍以配方、GUI、命令和动作为主要入口；需要介入锻造结果时优先监听事件 API 或注册 JavaScript 锻造规则。

EmakiForgeApi

方法	返回值	说明
`available()`	`boolean`	判断 API 是否已安装。
`apiVersion()`	`String`	返回 API 版本，不可用时为空字符串。
`pluginName()`	`String`	返回插件名，不可用时为空字符串。
`isReady()`	`boolean`	判断插件是否已完成初始化。

java

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

迁移期也可以使用兼容辅助类 EmakiForgeApiProvider：

方法	返回值	说明
`available()`	`boolean`	等价于 `EmakiForgeApi.available()`。
`requireAvailable()`	`void`	不可用时抛出 `IllegalStateException`。

java

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

EmakiForgeApiProvider.requireAvailable();

install(Bridge) 与 uninstall(Bridge) 只由 EmakiForge 自身的生命周期调用：启用时安装桥接，禁用时卸载。第三方插件不应调用这两个方法。

接入前提

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

yaml

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

JavaScript 调用

CoreLib JavaScript 脚本中可通过 emaki.module("forge") 查询 Forge 模块是否可用。当前公开 API 只暴露身份与就绪探针；锻造执行仍通过配方、GUI 和动作流程完成。注册锻造成功率规则和结果钩子的脚本方法见 JavaScript 脚本。

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

function main(ctx) {
  if (emaki.module("forge").available() && emaki.module("forge").ready()) {
    emaki.logger.info("Forge API version=" + emaki.module("forge").apiVersion());
  }
  return true;
}

线程安全

读取静态配置可以异步缓存，但最终修改 ItemStack 必须回到主线程。
不要在异步任务里直接操作玩家背包、世界掉落或事件对象。
ForgeStartEvent 是异步锻造链开始前唯一的主线程取消点，需要在锻造前拦截时监听它。

什么时候不用 API

固定配方输入、容量和结果：使用 recipes/*.yml。
材料贡献和品质修正：使用配方中的 materials 与 config.yml 的品质配置。
玩家手动锻造：使用 GUI 和命令。
任务或成就监听：使用事件。
修改成功率或发放奖励：使用 JavaScript 规则和结果钩子。

API 接入 ​

推荐接入方式 ​

EmakiForgeApi ​

接入前提 ​

JavaScript 调用 ​

线程安全 ​