事件 API

EmakiGem 对外公开 Bukkit 事件，外部插件可以监听这些事件来拦截或改写宝石操作。事件类位于 emaki.jiuwu.craft.gem.api.event 包，使用标准 HandlerList 样板。所有事件都在扣费、判定之前触发。

事件	触发时机	可取消	可改写
GemInlayEvent	镶嵌成功判定之前	是	setSuccessChance
GemUpgradeEvent	升级扣费与判定之前	是	setSuccessChance
GemExtractEvent	拆卸扣费与移除之前	是	仅取消
GemSocketOpenEvent	开孔与消耗开孔器之前	是	仅取消

玩家取值方法差异

GemInlayEvent、GemExtractEvent、GemSocketOpenEvent 使用 getActor() 获取操作玩家，而 GemUpgradeEvent 使用 getPlayer()。

GemInlayEvent

在镶嵌的成功判定之前触发。可用于拦截镶嵌或改写成功几率。

事件特性

• 可取消（Cancellable）：取消后不进行镶嵌。
• 可改写成功几率（setSuccessChance），单位为百分比 0-100。
• 仅当操作玩家由当前线程拥有时才触发；不满足线程归属时跳过事件，流程照常继续。

方法列表

方法	返回值	说明
getActor()	Player	执行镶嵌的玩家。
getEquipment()	ItemStack	接收宝石的装备。
getGemItem()	ItemStack	被镶嵌的宝石物品。
getSlotIndex()	int	目标孔位索引。
getGemId()	String	宝石定义 id。
getGemLevel()	int	宝石等级。
getSuccessChance()	double	用于判定的成功几率（0-100）。
setSuccessChance(double)	void	改写成功几率。
isCancelled()	boolean	是否已取消。
setCancelled(boolean)	void	取消或恢复事件。

监听示例

@EventHandler
public void onGemInlay(GemInlayEvent event) {
    // VIP 玩家镶嵌必定成功
    if (event.getActor().hasPermission("server.vip")) {
        event.setSuccessChance(100.0);
    }
}

GemUpgradeEvent

在宝石升级扣费与成功判定之前触发。

事件特性

• 可取消（Cancellable）：取消后不扣费、不升级。
• 可改写成功几率（setSuccessChance），单位为百分比 0-100。
• 仅当操作玩家由当前线程拥有时才触发；不满足线程归属时跳过事件，流程照常继续。

方法列表

方法	返回值	说明
getPlayer()	Player	执行升级的玩家。
getGemItem()	ItemStack	被升级的宝石物品；已镶嵌升级时为装备。
getGemId()	String	宝石定义 id。
getCurrentLevel()	int	升级前等级。
getTargetLevel()	int	成功后等级。
getSlotIndex()	int	已镶嵌升级的孔位索引；直接升级宝石物品时为 -1。
getSuccessChance()	double	用于判定的成功几率（0-100）。
setSuccessChance(double)	void	改写成功几率。
isCancelled()	boolean	是否已取消。
setCancelled(boolean)	void	取消或恢复事件。

监听示例

@EventHandler
public void onGemUpgrade(GemUpgradeEvent event) {
    // 已镶嵌的宝石不允许升级
    if (event.getSlotIndex() >= 0) {
        event.setCancelled(true);
    }
}

GemExtractEvent

在拆卸宝石的扣费与移除之前触发。

事件特性

• 可取消（Cancellable）：取消后不拆卸。
• 仅当操作玩家由当前线程拥有时才触发；不满足线程归属时跳过事件，流程照常继续。

方法列表

方法	返回值	说明
getActor()	Player	执行拆卸的玩家。
getEquipment()	ItemStack	被拆宝石的装备。
getSlotIndex()	int	被清空的孔位索引。
getGemId()	String	宝石定义 id。
getGemLevel()	int	宝石等级。
getReturnMode()	String	配置的返还模式（如 destroy、downgrade、return）。
isCancelled()	boolean	是否已取消。
setCancelled(boolean)	void	取消或恢复事件。

GemSocketOpenEvent

在开孔与消耗开孔器之前触发。

事件特性

• 可取消（Cancellable）：取消后不开孔、不消耗开孔器。
• 仅当操作玩家由当前线程拥有时才触发；不满足线程归属时跳过事件，流程照常继续。

方法列表

方法	返回值	说明
getActor()	Player	执行开孔的玩家。
getEquipment()	ItemStack	接收新孔位的装备。
getOpenerItem()	ItemStack	使用的开孔道具，可能为 null。
getOpenerId()	String	开孔道具配置 id。
getSlotIndex()	int	解析出的孔位索引。
getItemDefinitionId()	String	装备的宝石物品定义 id。
isCancelled()	boolean	是否已取消。
setCancelled(boolean)	void	取消或恢复事件。

注意事项

• 改写成功几率仅对 GemInlayEvent 与 GemUpgradeEvent 有效；拆卸与开孔事件只能取消。
• 成功几率单位统一为百分比 0-100。