Event Listener Examples

Belongs to: Developer　·　Related: Event Reference · API Recipes

Event Reference lists the signatures; this page gives each event one complete, usable listener (Java), with a typical use case.

Register a listener: Bukkit.getPluginManager().registerEvents(new MyListener(), this);

---

QinhItemGenerateEvent —— Modify instance data

Use case: inject custom initial values when an item is freshly generated.

@EventHandler
public void onGenerate(QinhItemGenerateEvent e) {
    // Stamp a source marker on all newly generated legendary items
    if ("LEGENDARY".equals(e.getDefinition().getTier())) {
        var data = e.getInstanceData();
        // instanceData is mutable (var field); rebuild and write back as needed
        // e.g. record the generation timestamp into custom storage
        myTracker.markGenerated(e.getDefinition().getId());
    }
}

Cancellable (prevents generation).

---

QinhItemAssembleEvent —— Intervene before/after assembly

Use case: append custom NBT to a specific item after assembly.

@EventHandler
public void onAssemble(QinhItemAssembleEvent e) {
    if (!e.isPre()) {                       // after assembly
        ItemStack stack = e.getItemStack();
        if ("boss_drop_blade".equals(e.getDefinition().getId())) {
            // Add your own PDC marker on the stack
            myNbt.tag(stack, "from_boss", true);
        }
    }
}

pre=true before assembly, false after assembly. Cancellable.

---

QinhItemsReloadEvent —— Refresh caches after reload

Use case: rebuild your plugin's item cache after /qi reload.

@EventHandler
public void onReload(QinhItemsReloadEvent e) {
    getLogger().info("QI reload: items " + e.getItemCount()
        + " actions " + e.getActionCount() + " sets " + e.getSetCount());
    myItemCache.invalidateAll();            // rebuild cache
}

Not cancellable.

---

QinhItemUseCheckEvent —— Custom usage restrictions

Use case: implement class restrictions (class:Warrior).

@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("Requires class: " + need);
                return;
            }
        }
    }
}

Cancel = deny use; you can set denyReason. Configure on the item via options.restrictions: ["class:Warrior"].

---

QinhEquipmentChangeEvent —— React to equipment changes

Use case: refresh your plugin's UI / scoreboard when a player changes gear.

@EventHandler
public void onEquipChange(QinhEquipmentChangeEvent e) {
    Player p = e.getPlayer();
    // The equipped QI items changed, recompute your display
    myScoreboard.update(p);
}

Not cancellable. Fires after attribute sync.

---

QinhCombatSwingEvent —— Intercept / rewrite swings

Use case: change the hit target for a specific weapon or cancel the default swing.

@EventHandler
public void onSwing(QinhCombatSwingEvent e) {
    if ("legendary_sword".equals(e.getItemId())) {
        if ("heavy".equals(e.getSwingMode())) {
            // Turn heavy attacks into an area effect, cancel the default single-target swing
            myAoe.strike(e.getPlayer());
            e.setCancelled(true);
        }
    }
}

Cancellable; the target field is mutable.

---

QinhActionTriggerEvent —— Intercept before dispatch

Use case: globally restrict a trigger (e.g. disable teleport-type actions during combat).

@EventHandler
public void onTrigger(QinhActionTriggerEvent e) {
    if (myCombatTag.isInCombat(e.getPlayer())
        && e.getTrigger().contains("recall")) {
        e.setCancelled(true);               // block dispatch
        e.getPlayer().sendMessage("§cCannot be used in combat");
    }
}

Cancellable (blocks the entire dispatch).

---

QinhActionDispatchedEvent —— Stats after dispatch

Use case: count skill usage / auditing.

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

Not cancellable (informational).

---

QinhItemCompiledEvent —— Post-compile processing

Use case: register an item into an external system after it is compiled into an ItemStack.

@EventHandler
public void onCompiled(QinhItemCompiledEvent e) {
    // Read the provider snapshot, do your own bridging
    var snap = e.getProviderSnapshot();
    if (snap.provider("myplugin") != null) {
        myExternal.register(e.getDefinition().getId(), e.getStack());
    }
}

Cancellable (setCancelled). Can also hook in via QinhBridgeHook, see Provider and Bridge.

---

Event Selection Cheatsheet

I want to…	Listen to
Modify new item initial data	QinhItemGenerateEvent
Process the ItemStack after assembly	QinhItemAssembleEvent
Refresh caches after reload	QinhItemsReloadEvent
Custom usage restrictions	QinhItemUseCheckEvent
React to gear changes	QinhEquipmentChangeEvent
Modify / intercept swings	QinhCombatSwingEvent
Intercept action dispatch	QinhActionTriggerEvent
Stats on actions	QinhActionDispatchedEvent
Bridge after compile	QinhItemCompiledEvent

---

Next steps

• Event Reference: field signatures
• API Recipes: finished code
• Action Handler Development