事件 API
Level 当前有 5 个同步 Bukkit 事件。runtime 只在当前线程拥有在线玩家时发布；公开同步写 API 对错误线程返回 WRONG_THREAD。
| 事件 | 触发时机 | Cancellable | 可修改字段 | 取消/结果效果 |
|---|---|---|---|---|
PlayerExpGainEvent | 倍率/日上限调整后、经验和日配额写入前 | 是 | amount | 取消或最终 <=0 阻止经验与配额消耗；正数仍受剩余配额限制 |
PlayerPreLevelUpEvent | 全部校验后、journal/扣费/等级/奖励/actions 前 | 是 | 无 | 阻止整次 level-up transaction |
PlayerLevelUpEvent | 经验驱动升级、奖励与 success actions 提交后 | 否 | 无 | post，不可回滚 |
PlayerMaxLevelReachedEvent | 经验驱动升级首次跨到配置上限后 | 否 | 无 | milestone post；直接 setLevel 不属于此路径 |
PlayerLevelChangeEvent | add/remove/set/reset 等管理型等级变更实际提交后 | 否 | 无 | post；不替代经验驱动 PlayerLevelUpEvent |
所有事件均在玩家 owner thread。事件表示内存 transaction 的对应阶段，不保证异步持久化已经落盘。监听器不得阻塞等待 I/O；跨玩家工作应分别重新调度。