事件监听实例

所属：开发者　·　相关：事件大全 · API 配方集

事件大全 列签名，本页给每个事件一段完整可用的 listener（Java），含典型用例。

注册 listener：Bukkit.getPluginManager().registerEvents(new MyListener(), this);

---

QinhItemGenerateEvent —— 改实例数据

用例：物品全新生成时注入自定义初始值。

@EventHandler
public void onGenerate(QinhItemGenerateEvent e) {
    // 给所有新生成的传说物品打一个来源标记
    if ("LEGENDARY".equals(e.getDefinition().getTier())) {
        var data = e.getInstanceData();
        // instanceData 可改（var 字段）；按需重建并回填
        // 例：记录生成时间戳到自定义存储
        myTracker.markGenerated(e.getDefinition().getId());
    }
}

可取消（阻止生成）。

---

QinhItemAssembleEvent —— 装配前/后干预

用例：装配后给特定物品追加自定义 NBT。

@EventHandler
public void onAssemble(QinhItemAssembleEvent e) {
    if (!e.isPre()) {                       // 装配后
        ItemStack stack = e.getItemStack();
        if ("boss_drop_blade".equals(e.getDefinition().getId())) {
            // 在 stack 上加你自己的 PDC 标记
            myNbt.tag(stack, "from_boss", true);
        }
    }
}

pre=true 装配前、false 装配后。可取消。

---

QinhItemsReloadEvent —— 重载后刷新缓存

用例：/qi reload 后重建你插件的物品缓存。

@EventHandler
public void onReload(QinhItemsReloadEvent e) {
    getLogger().info("QI 重载：物品 " + e.getItemCount()
        + " 动作 " + e.getActionCount() + " 段 " + e.getSetCount());
    myItemCache.invalidateAll();            // 重建缓存
}

不可取消。

---

QinhItemUseCheckEvent —— 自定义使用限制

用例：实现职业限制（class:战士）。

@EventHandler
public void onUseCheck(QinhItemUseCheckEvent e) {
    for (String r : e.getRestrictions()) {
        if (r.startsWith("class:")) {
            String need = r.substring(6);
            if (!myClassSystem.hasClass(e.getPlayer(), need)) {
                e.setCancelled(true);
                e.setDenyReason("需要职业：" + need);
                return;
            }
        }
    }
}

取消 = 拒绝使用，可设 denyReason。物品里配 options.restrictions: ["class:战士"]。

---

QinhEquipmentChangeEvent —— 装备变化响应

用例：玩家换装时刷新你插件的 UI / 计分板。

@EventHandler
public void onEquipChange(QinhEquipmentChangeEvent e) {
    Player p = e.getPlayer();
    // 装备的 QI 物品变了，重算你的展示
    myScoreboard.update(p);
}

不可取消。属性同步后触发。

---

QinhCombatSwingEvent —— 拦截 / 改写挥击

用例：对特定武器改命中目标或取消默认挥击。

@EventHandler
public void onSwing(QinhCombatSwingEvent e) {
    if ("legendary_sword".equals(e.getItemId())) {
        if ("heavy".equals(e.getSwingMode())) {
            // 重击改为范围效果，取消单体默认挥击
            myAoe.strike(e.getPlayer());
            e.setCancelled(true);
        }
    }
}

可取消；target 字段可改。

---

QinhActionTriggerEvent —— 派发前拦截

用例：全局限制某触发器（如战斗中禁用传送类动作）。

@EventHandler
public void onTrigger(QinhActionTriggerEvent e) {
    if (myCombatTag.isInCombat(e.getPlayer())
        && e.getTrigger().contains("recall")) {
        e.setCancelled(true);               // 阻止派发
        e.getPlayer().sendMessage("§c战斗中无法使用");
    }
}

可取消（阻止整个派发）。

---

QinhActionDispatchedEvent —— 派发后统计

用例：统计技能使用次数 / 审计。

@EventHandler
public void onDispatched(QinhActionDispatchedEvent e) {
    if (e.getResult() == ActionDispatchResult.HANDLED) {
        myStats.increment(e.getItemId(), e.getHandlerId());
    }
}

不可取消（信息性）。

---

QinhItemCompiledEvent —— 编译后处理

用例：物品编译成 ItemStack 后注册进外部系统。

@EventHandler
public void onCompiled(QinhItemCompiledEvent e) {
    // 读 provider 快照，做你自己的桥接
    var snap = e.getProviderSnapshot();
    if (snap.provider("myplugin") != null) {
        myExternal.register(e.getDefinition().getId(), e.getStack());
    }
}

可取消（setCancelled）。也可通过 QinhBridgeHook 接入，见 Provider 与桥。

---

事件选择速查

我想…	监听
改新物品初始数据	QinhItemGenerateEvent
装配后加工 ItemStack	QinhItemAssembleEvent
reload 后刷新缓存	QinhItemsReloadEvent
自定义使用限制	QinhItemUseCheckEvent
换装响应	QinhEquipmentChangeEvent
改 / 拦挥击	QinhCombatSwingEvent
拦动作派发	QinhActionTriggerEvent
统计动作	QinhActionDispatchedEvent
编译后桥接	QinhItemCompiledEvent

---

下一步

• 事件大全：字段签名
• API 配方集：成品代码
• 动作处理器开发