事件 API

EmakiItem 对外公开 Bukkit 事件，外部插件可以监听这些事件来拦截、改写或记录物品流程。事件类位于 emaki.jiuwu.craft.item.api.event 包，使用标准 HandlerList 样板。

事件	触发时机	可取消	可改写
EmakiItemCreateEvent	自定义物品创建后、返回调用方之前	否	setResult
ItemRepairEvent	修复扣费与耐久恢复之前	是	setRestoreAmount
ItemSetBonusChangeEvent	套装激活件数变化之后	否	只读

EmakiItemCreateEvent

在自定义物品创建后、返回给调用方之前触发。该事件不可取消，但可以通过 setResult 替换最终物品。

事件特性

• 不可取消，但可改写产物（setResult）。传入 null 会被忽略。
• 在物品已创建、尚未返回调用方时触发。
• 只在全局主线程所有权成立时触发；不满足时创建流程直接返回物品，不触发事件。

方法列表

方法	返回值	说明
getId()	String	物品定义 id。
getAmount()	int	解析出的数量。
getPlayer()	Player	物品创建对象玩家。当前创建流程不传入玩家，实际始终为 null，监听器必须判空。
getResult()	ItemStack	产出物品（可能已被监听器替换）。
setResult(ItemStack)	void	替换返回给调用方的物品；传 null 会被忽略。

监听示例

@EventHandler
public void onItemCreate(EmakiItemCreateEvent event) {
    // 给指定物品追加自定义 NBT 或 Lore
    if (event.getId().equals("starter_sword")) {
        ItemStack result = event.getResult();
        // ... 修改 result ...
        event.setResult(result);
    }
}

ItemRepairEvent

在物品修复的扣费与耐久恢复之前触发。

事件特性

• 可取消（Cancellable）：取消后不扣费、不修复。
• 可改写恢复的耐久量（setRestoreAmount）。值小于等于 0 会抑制本次修复。
• 只在当前线程拥有该玩家实体所有权时触发；不满足时按未取消、恢复量不变继续修复。
• 材料修复与货币修复都会触发，通过 getSource() 区分。

方法列表

方法	返回值	说明
getPlayer()	Player	执行修复的玩家。
getEquipment()	ItemStack	被修复的装备。
getItemId()	String	EmakiItem 定义 id。
getSource()	String	修复来源（如 material、economy）。
getCurrentDamage()	int	修复前当前损耗。
getMaxDamage()	int	最大损耗。
getRestoreAmount()	int	将恢复的耐久（除非改写或取消）。
setRestoreAmount(int)	void	改写恢复耐久量；值小于等于 0 抑制修复。
isCancelled()	boolean	是否已取消。
setCancelled(boolean)	void	取消或恢复事件。

监听示例

@EventHandler
public void onItemRepair(ItemRepairEvent event) {
    // 货币修复时翻倍恢复量
    if (event.getSource().equals("economy")) {
        event.setRestoreAmount(event.getRestoreAmount() * 2);
    }
}

方法命名

改写恢复量的方法是 setRestoreAmount(int)，配套 getter 是 getRestoreAmount()，不是 setRepairAmount。

ItemSetBonusChangeEvent

在套装激活件数实际发生变化后触发的信息型事件。仅当激活件数变化时触发（边沿触发）。

事件特性

• 不可取消，仅用于通知。
• 套装加成已经应用，本事件用于外部插件感知变化。
• 只在激活件数实际变化时触发，且要求当前线程拥有该玩家实体所有权；不满足时状态仍会更新，但不发事件。
• 每个发生变化的套装 ID 各触发一次。

方法列表

方法	返回值	说明
getPlayer()	Player	套装状态变化的玩家。
getSetId()	String	套装 id。
getOldActiveCount()	int	变化前激活件数。
getNewActiveCount()	int	变化后激活件数。
getTotalPieces()	int	套装总件数。
getActiveThresholds()	List<Integer>	当前激活的各档位所需件数（不可变列表）。
getTrigger()	String	触发刷新的来源。

监听示例

@EventHandler
public void onSetBonusChange(ItemSetBonusChangeEvent event) {
    if (event.getNewActiveCount() > event.getOldActiveCount()) {
        event.getPlayer().sendMessage("套装激活：" + event.getSetId()
            + " (" + event.getNewActiveCount() + "/" + event.getTotalPieces() + ")");
    }
}

注意事项

• EmakiItemCreateEvent 不可取消，若要阻止物品产出请在调用方层处理。
• ItemSetBonusChangeEvent 的 getActiveThresholds() 返回不可变列表，不要尝试修改。