Event Reference

Belongs to: Developer　·　Related: API Reference · Action Handler Development

QI fires a series of Bukkit events covering the item lifecycle, combat, and actions. This page lists each one: when it triggers, its fields, and whether it is cancellable.

---

1. Item Lifecycle Events (event/QinhItemEvents.kt)

QinhItemGenerateEvent —— Cancellable

Triggered when item instance data is generated.

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

Purpose: modify instance data before assembly (e.g. inject custom initial values).

QinhItemAssembleEvent —— Cancellable

Triggered when an item is assembled from its definition; pre=true before assembly, pre=false after assembly.

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

QinhItemsReloadEvent —— Not cancellable

Triggered after /qi reload completes.

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

QinhItemUseCheckEvent —— Cancellable

Triggered when QinhItemsAPI.canUse() is called, for custom restrictions (e.g. class / faction).

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

Cancelling (cancelled=true) = deny use; you can set denyReason to report the reason.

---

2. Combat Events (event/QinhCombatEvents.kt)

QinhEquipmentChangeEvent —— Not cancellable

Triggered when the QI items equipped by a player change (after attribute sync).

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

QinhCombatSwingEvent —— Cancellable

Triggered when a player swings / attacks with a QI item.

class QinhCombatSwingEvent(
    val player: Player,
    val item: ItemStack,
    val itemId: String,
    val swingMode: String,        // "light" / "heavy" etc.
    var target: Entity? = null,   // mutable hit target
) : Event(false), Cancellable

---

3. Action Events (action/ActionEvents.kt)

QinhActionTriggerEvent —— Cancellable

Triggered before an action is dispatched (trigger matched). Cancelling prevents dispatch.

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

QinhActionDispatchedEvent —— Not cancellable

Triggered after each handler executes (informational).

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. Compilation Events (bridge/BridgeContracts.kt)

QinhItemCompiledEvent —— Cancellable

Triggered after an item definition is compiled into an ItemStack. For bridging / post-processing.

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. Listening Example

@EventHandler
public void onSwing(QinhCombatSwingEvent e) {
    if (e.getItemId().equals("legendary_sword")) {
        // change the hit target, or cancel the default swing
        e.setCancelled(true);
    }
}

@EventHandler
public void onUseCheck(QinhItemUseCheckEvent e) {
    // custom class restriction
    for (String r : e.getRestrictions()) {
        if (r.startsWith("class:") && !hasClass(e.getPlayer(), r.substring(6))) {
            e.setCancelled(true);
            e.setDenyReason("Class does not match");
        }
    }
}

---

Event Quick Reference

Event	Timing	Cancellable
QinhItemGenerateEvent	Instance data generated	✅
QinhItemAssembleEvent	Before / after assembly	✅
QinhItemsReloadEvent	Reload complete	❌
QinhItemUseCheckEvent	canUse check	✅
QinhEquipmentChangeEvent	After equipment change	❌
QinhCombatSwingEvent	Swing / attack	✅
QinhActionTriggerEvent	Before action dispatch	✅
QinhActionDispatchedEvent	After handler executes	❌
QinhItemCompiledEvent	Compilation complete	✅

---

Next Steps

• Action Handler Development
• Provider and Bridge