事件 API

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

事件	触发时机	可取消	可改写
SkillPreCastEvent	通过冷却/资源/条件检查后、技能效果执行前	是	仅取消
SkillPreUpgradeEvent	升级扣费与判定之前	是	setSuccessRate
SkillUpgradeEvent	升级尝试完全结束之后	否	只读
PlayerSkillSlotChangeEvent	技能槽位绑定变化之前	是	仅取消

SkillPreCastEvent

在技能通过冷却、资源、条件检查后、效果执行前触发。这是主动与被动触发的中心 pre-cast 钩子。

事件特性

• 可取消（Cancellable）：取消后不运行技能，不消耗资源、不记录冷却。
• 在服务端线程触发。

方法列表

方法	返回值	说明
getPlayer()	Player	施放技能的玩家。
getSkillId()	String	即将施放的技能 id。
getTriggerId()	String	发起施放的触发器 id。
isCancelled()	boolean	是否已取消。
setCancelled(boolean)	void	取消或恢复事件。

监听示例

@EventHandler
public void onSkillPreCast(SkillPreCastEvent event) {
    // 禁用区域内禁止施放技能
    if (inNoMagicZone(event.getPlayer().getLocation())) {
        event.setCancelled(true);
    }
}

SkillPreUpgradeEvent

在技能升级扣费与成功判定之前触发。

事件特性

• 可取消（Cancellable）：取消后不扣费、不升级。
• 可改写成功率（setSuccessRate），单位为百分比 0-100。
• 在服务端线程触发。

方法列表

方法	返回值	说明
getPlayer()	Player	执行升级的玩家。
getSkillId()	String	技能 id。
getCurrentLevel()	int	升级前等级。
getTargetLevel()	int	成功后等级。
getMaxLevel()	int	技能最高等级。
getSuccessRate()	double	用于判定的成功率（0-100）。
setSuccessRate(double)	void	改写成功率。
isCancelled()	boolean	是否已取消。
setCancelled(boolean)	void	取消或恢复事件。

监听示例

@EventHandler
public void onSkillPreUpgrade(SkillPreUpgradeEvent event) {
    // 活动期间提升升级成功率
    event.setSuccessRate(Math.min(100.0, event.getSuccessRate() + 20.0));
}

SkillUpgradeEvent

在一次技能升级尝试完全结束后触发。成功与失败都会报告，等级变化或失败降级惩罚已应用。

事件特性

• 不可取消，仅用于通知。

方法列表

方法	返回值	说明
getPlayer()	Player	执行升级的玩家。
getSkillId()	String	技能 id。
getFromLevel()	int	尝试前等级。
getToLevel()	int	尝试后等级。
getSuccessRate()	double	用于判定的成功率（0-100）。
isSuccess()	boolean	是否成功。
isDowngraded()	boolean	是否因失败惩罚降级。

PlayerSkillSlotChangeEvent

在玩家技能槽位绑定变化之前触发。

事件特性

• 可取消（Cancellable）：取消后不更新绑定，发起方法返回 false。
• 区分装备、卸下、绑定触发器三种动作。
• 在服务端线程触发。

方法列表

方法	返回值	说明
getPlayer()	Player	槽位变化的玩家。
getSlotIndex()	int	目标槽位索引。
getSkillId()	String	涉及的技能 id（UNEQUIP 时为原绑定技能 id），可能为 null。
getTriggerId()	String	BIND_TRIGGER 时的触发器 id，否则为 null。
getAction()	Action	槽位变化类型。
isCancelled()	boolean	是否已取消。
setCancelled(boolean)	void	取消或恢复事件。

Action 枚举取值：

取值	说明
EQUIP	装备技能到槽位。
UNEQUIP	从槽位卸下技能。
BIND_TRIGGER	为槽位绑定触发器。

监听示例

@EventHandler
public void onSlotChange(PlayerSkillSlotChangeEvent event) {
    // 锁定第一个槽位不允许卸下
    if (event.getSlotIndex() == 0
            && event.getAction() == PlayerSkillSlotChangeEvent.Action.UNEQUIP) {
        event.setCancelled(true);
    }
}

注意事项

• 改写成功率仅对 SkillPreUpgradeEvent 有效。
• getSkillId() 与 getTriggerId() 在部分动作下可能为 null，使用前应判空。