事件 API

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

事件	触发时机	可取消	可改写
PlayerExpGainEvent	经验写入之前	是	setAmount
PlayerLevelUpEvent	经验驱动升级之后	否	只读
PlayerLevelChangeEvent	任意等级变更之后	否	只读
PlayerMaxLevelReachedEvent	首次达到最高等级时	否	只读

PlayerExpGainEvent

在经验写入玩家之前触发。amount 是已应用倍率与每日上限后、加给玩家前的值。

事件特性

• 可取消（Cancellable）：取消后不增加经验。
• 可改写经验量（setAmount）。值小于等于 0 会抑制本次获取。
• 在主线程触发；异步路径会跳过事件。

方法列表

方法	返回值	说明
getPlayer()	Player	获取经验的玩家，可能为 null。
getTypeId()	String	等级类型 id。
getCurrentLevel()	int	本次获取前等级。
getCurrentExp()	double	本次获取前经验。
getReason()	String	来源原因标记。
getAmount()	double	将增加的经验（除非改写或取消）。
setAmount(double)	void	改写经验量；值小于等于 0 抑制获取。
isCancelled()	boolean	是否已取消。
setCancelled(boolean)	void	取消或恢复事件。

监听示例

@EventHandler
public void onExpGain(PlayerExpGainEvent event) {
    // 双倍经验活动
    event.setAmount(event.getAmount() * 2);
}

PlayerLevelUpEvent

在经验驱动的升级完成后触发。等级已应用、奖励与成功动作已执行。

事件特性

• 不可取消，仅用于通知。
• 仅覆盖经验驱动的升级（命令或 API 直接改等级走 PlayerLevelChangeEvent）。

方法列表

方法	返回值	说明
getPlayer()	Player	升级的玩家，可能为 null。
getTypeId()	String	等级类型 id。
getOldLevel()	int	升级前等级。
getNewLevel()	int	升级后等级。
getCause()	LevelUpCause	触发升级的原因（emaki.jiuwu.craft.level.api.LevelUpCause），可能为 null。

PlayerLevelChangeEvent

在任意等级变更之后触发，覆盖命令或 API 的直接等级变更（区别于仅经验驱动的 PlayerLevelUpEvent）。变更已应用且不可回退。

事件特性

• 不可取消，仅用于通知。
• 覆盖增减、设置、升级、重置等各类等级操作。

方法列表

方法	返回值	说明
getPlayer()	Player	受影响玩家，离线时可能为 null。
getTypeId()	String	等级类型 id。
getOldLevel()	int	变化前等级。
getNewLevel()	int	变化后等级。
getOperationType()	LevelOperationType	引发变更的操作类型（emaki.jiuwu.craft.level.api.LevelOperationType）。
isIncrease()	boolean	是否升高（新等级大于旧等级）。

PlayerMaxLevelReachedEvent

在玩家首次经验驱动达到配置的最高等级时触发一次的里程碑事件。

事件特性

• 不可取消，仅用于通知。
• 每个等级类型首次满级触发一次。

方法列表

方法	返回值	说明
getPlayer()	Player	达到满级的玩家，可能为 null。
getTypeId()	String	等级类型 id。
getMaxLevel()	int	配置的最高等级。
getCause()	LevelUpCause	升级原因（LevelUpCause），可能为 null。

监听示例

@EventHandler
public void onMaxLevel(PlayerMaxLevelReachedEvent event) {
    Player player = event.getPlayer();
    if (player != null) {
        Bukkit.broadcastMessage(player.getName()
            + " 的 " + event.getTypeId() + " 已满级！");
    }
}

注意事项

• getPlayer() 在离线场景可能返回 null，使用前应判空。
• PlayerLevelUpEvent 仅经验驱动触发；命令或 API 直接改等级请监听 PlayerLevelChangeEvent。
• LevelUpCause 与 LevelOperationType 是 EmakiLevel API 公开的枚举，位于 emaki.jiuwu.craft.level.api 包。