事件 API

EmakiForge 对外公开 Bukkit 事件，外部插件可以监听这些事件来拦截或记录锻造流程。事件类位于 emaki.jiuwu.craft.forge.api.event 包，使用标准 HandlerList 样板。

事件	触发时机	可取消	可改写
ForgeStartEvent	异步锻造执行开始之前	是	只读
ForgeCompletedEvent	一次锻造尝试完全结束之后	否	只读

ForgeStartEvent

在异步锻造执行开始之前触发。这是锻造流程中唯一运行于主线程、且在异步链开始前的取消点。

事件特性

• 可取消（Cancellable）：取消后不进入锻造流程。
• successRate 只读：成功率由配置和 JavaScript 规则决定，本事件不提供改写入口。
• 在主线程触发；异步路径会跳过事件。

方法列表

方法	返回值	说明
getPlayer()	Player	执行锻造的玩家。
getRecipeId()	String	锻造配方 id。
isFirstCraft()	boolean	是否该配方首次锻造。
getSuccessRate()	double	配置的配方成功率（0-100），只读。
isCancelled()	boolean	是否已取消。
setCancelled(boolean)	void	取消或恢复事件。

监听示例

@EventHandler
public void onForgeStart(ForgeStartEvent event) {
    // 限制某配方仅首次锻造
    if (!event.isFirstCraft() && event.getRecipeId().equals("legendary_blade")) {
        event.setCancelled(true);
    }
}

ForgeCompletedEvent

在一次锻造尝试完全结束后触发。成功和失败都会触发，可通过 isSuccess() 区分；但发生异常错误时不触发。

事件特性

• 不可取消，仅用于通知。
• 在主线程触发。

方法列表

方法	返回值	说明
getPlayer()	Player	执行尝试的玩家。
getRecipeId()	String	锻造配方 id。
isSuccess()	boolean	是否成功。
getResultItem()	ItemStack	产出物品，失败时为 null。
getQuality()	String	解析出的品质档位 id，可能为空。
getMultiplier()	double	解析出的品质倍率。

监听示例

@EventHandler
public void onForgeCompleted(ForgeCompletedEvent event) {
    if (event.isSuccess()) {
        getLogger().info(event.getPlayer().getName()
            + " 锻造成功，品质 " + event.getQuality());
    }
}

注意事项

• 失败时 getResultItem() 返回 null，读取前应判空。
• getQuality() 可能为空字符串或 null，取决于配方是否启用品质系统。