事件 API

Item 当前有五个公开事件; 源码中不存在 ItemUpdateEvent 或 EquipmentSkillTriggerEvent, 引用前先核对类名. 事件包: emaki.jiuwu.craft.item.api.event

事件	触发时机	线程	Cancellable	可修改字段	取消/结果效果	runtime 路径
EmakiItemCreateEvent	factory 已构建 stack, 返回调用方前	global-region owner thread	是	result, 必须非 null	取消丢弃结果; 公开 create 返回 CANCELLED	进入 EmakiItemFactory 且当前拥有 global region 的创建路径
ItemRepairEvent	修复校验后, 扣费和恢复耐久前	玩家 owner thread	是	restoreAmount	取消不扣费, 不修复; <=0 也抑制修复	材料与经济修复 service, 包括公开 repair() 的经济路径
ItemSetBonusChangeEvent	active set count 实际改变后	玩家 owner thread	否	无	post 通知, 不可回滚	装备套装刷新, 每个变化 set id 一次
ItemStateChangeEvent	item state 变更已提交后	执行该次变更的 owner thread	否	无	post 通知, 不可回滚	state() 的 set/add/remove 提交路径
ItemStateThresholdEvent	数值 item state 变更跨过已配置阈值后	执行该次变更的 owner thread	否	无	post 通知, 不可回滚	提交并完成 once 阈值重置记账之后, 每跨过一个阈值一次

边界条件: factory 创建事件的 player 为 null. 调用方不拥有 global region 时, runtime 跳过创建事件并仍返回分离构建结果, 因此该事件不构成所有 ItemStack 创建的完整审计流. Migration 和普通 refresh 不派发独立公开事件. ItemSetBonusChangeEvent 是 post 事件, 取消无效

字段契约: ItemStateChangeEvent 暴露 getItem() (克隆件), getMutation(), getHolder() (无已知持有者时为 null) 以及从 mutation 转发的 getKey(), getOldValue(), getNewValue(), getDelta()

字段与派发边界: ItemStateThresholdEvent 暴露 getItem(), getHolder(), getKey(), getOldValue(), getNewValue(), getThreshold(), getThresholdId(), getDirection() (UP/DOWN), isOnce() 与 isRearmed(). 它只覆盖配置了阈值的数值字段 (INTEGER, LONG, DOUBLE); 向上跨越按阈值升序, 向下跨越按降序各派发一次. 被拒绝或未改变的变更, 保留的 meta. 元数据键, BOOLEAN 与 STRING 字段, 未配置阈值的数值字段, 新旧值处于同一侧, 仍处于 latch 状态的 once 阈值, 以及重建保留原样回写的状态都不会派发