事件大全

所属：开发者　·　相关：API 参考 · 动作处理器开发

QI 抛出一系列 Bukkit 事件，覆盖物品生命周期、战斗、动作。本页逐个列出：何时触发、字段、是否可取消。

---

1. 物品生命周期事件（event/QinhItemEvents.kt）

QinhItemGenerateEvent —— 可取消

物品实例数据生成时触发。

class QinhItemGenerateEvent(
    val definition: QinhItemDefinition,
    var instanceData: QinhItemInstanceData,   // 可改
    val player: Player?,
) : Event(false), Cancellable

用途：在装配前修改实例数据（如注入自定义初始值）。

QinhItemAssembleEvent —— 可取消

物品从定义装配时触发，pre=true 装配前、pre=false 装配后。

class QinhItemAssembleEvent(
    val definition: QinhItemDefinition,
    val itemStack: ItemStack,
    val instanceData: QinhItemInstanceData,
    val pre: Boolean,
) : Event(), Cancellable

QinhItemsReloadEvent —— 不可取消

/qi reload 完成后触发。

class QinhItemsReloadEvent(
    val itemCount: Int,
    val actionCount: Int,
    val setCount: Int,
) : Event()

QinhItemUseCheckEvent —— 可取消

QinhItemsAPI.canUse() 调用时触发，用于自定义限制（如职业 / 阵营）。

class QinhItemUseCheckEvent(
    val player: Player,
    val item: ItemStack,
    val itemId: String,
    val restrictions: List<String>,
) : Event(), Cancellable {
    var denyReason: String? = null
}

取消（cancelled=true）= 拒绝使用，可设 denyReason 回报原因。

---

2. 战斗事件（event/QinhCombatEvents.kt）

QinhEquipmentChangeEvent —— 不可取消

玩家装备的 QI 物品变化时触发（属性同步后）。

class QinhEquipmentChangeEvent(
    val player: Player,
    val scannedSlots: List<String>,
    val equipped: Map<String, ItemStack> = emptyMap(),
) : Event(false)

QinhCombatSwingEvent —— 可取消

玩家用 QI 物品挥击 / 攻击时触发。

class QinhCombatSwingEvent(
    val player: Player,
    val item: ItemStack,
    val itemId: String,
    val swingMode: String,        // "light" / "heavy" 等
    var target: Entity? = null,   // 可改命中目标
) : Event(false), Cancellable

---

3. 动作事件（action/ActionEvents.kt）

QinhActionTriggerEvent —— 可取消

动作派发前触发（触发器命中）。取消可阻止派发。

class QinhActionTriggerEvent(
    val trigger: String,
    val player: Player,
    val item: ItemStack,
    val itemId: String,
    val triggerDef: ActionTriggerDef,
) : Event(), Cancellable

QinhActionDispatchedEvent —— 不可取消

每个处理器执行后触发（信息性）。

class QinhActionDispatchedEvent(
    val trigger: String,
    val player: Player,
    val item: ItemStack,
    val itemId: String,
    val handlerId: String,
    val payload: String,
    val result: ActionDispatchResult,
    val compileEpoch: Long?,
) : Event()

---

4. 编译事件（bridge/BridgeContracts.kt）

QinhItemCompiledEvent —— 可取消

物品定义编译成 ItemStack 后触发。供桥接 / 后处理。

class QinhItemCompiledEvent(
    val definition: QinhItemDefinition,
    val stack: ItemStack,
    val providerSnapshot: ProviderSnapshot,
    val compiledState: CompiledState,
    val compileEpoch: Long,
) : Event() {
    fun isCancelled(): Boolean
    fun setCancelled(cancel: Boolean)
}

---

5. 监听示例

@EventHandler
public void onSwing(QinhCombatSwingEvent e) {
    if (e.getItemId().equals("legendary_sword")) {
        // 改命中目标、或取消默认挥击
        e.setCancelled(true);
    }
}

@EventHandler
public void onUseCheck(QinhItemUseCheckEvent e) {
    // 自定义职业限制
    for (String r : e.getRestrictions()) {
        if (r.startsWith("class:") && !hasClass(e.getPlayer(), r.substring(6))) {
            e.setCancelled(true);
            e.setDenyReason("职业不符");
        }
    }
}

---

事件速查表

事件	时机	可取消
QinhItemGenerateEvent	实例数据生成	✅
QinhItemAssembleEvent	装配前 / 后	✅
QinhItemsReloadEvent	reload 完成	❌
QinhItemUseCheckEvent	canUse 检查	✅
QinhEquipmentChangeEvent	装备变化后	❌
QinhCombatSwingEvent	挥击 / 攻击	✅
QinhActionTriggerEvent	动作派发前	✅
QinhActionDispatchedEvent	处理器执行后	❌
QinhItemCompiledEvent	编译完成	✅

---

下一步

• 动作处理器开发
• Provider 与桥