# Events and hooks

## Server events

| Event | Arguments | When |
|---|---|---|
| `koja-inventory-v2:itemsReady` | none | The inventory finished starting. Register runtime items and slots here. |
| `koja-inventory-v2:usedItem` | `source, name, itemId, metadata` | An item was used. |
| `koja-inventory-v2:slotChanged` | `source, key, item \| nil` | An equipment slot changed (built-in or custom). |
| `koja-inventory-v2:statusApplied` | `source, status` | A usable item applied hunger/thirst status. |
| `koja-inventory-v2:settingsChanged` | `paths` | An admin saved settings in the panel. |
| `ox_inventory:usedItem` | `source, name, itemId, metadata` | Same as `usedItem`, for ox scripts. |
| `ox_inventory:openedInventory` | `source, inventoryName` | A player opened a second inventory. |
| `ox_inventory:closedInventory` | `source, inventoryName` | A player closed it. |

```lua
AddEventHandler('koja-inventory-v2:usedItem', function(source, name, itemId, metadata)
    if name == 'phone' then TriggerClientEvent('my_phone:open', source) end
end)
```

## Client events

| Event | Arguments | When |
|---|---|---|
| `koja-inventory-v2:client:slotChanged` | `key, item \| nil` | One of your equipment slots changed. |
| `koja-inventory-v2:client:settingsChanged` | `paths` | Settings changed in the admin panel. |
| `ox_inventory:currentWeapon` | `weapon \| nil` | A weapon was drawn or holstered. |

## Hooks

Hooks let your script inspect an action and block it by returning `false`. Register them with `RegisterHook` (or ox `registerHook`), remove them with `RemoveHooks`.

```lua
local hookId = exports['koja-inventory-v2']:RegisterHook('swapItems', function(payload)
    if payload.toType == 'player' and payload.fromSlot.name == 'evidence_bag' then
        return false
    end
end, {
    itemFilter = { evidence_bag = true },
    inventoryFilter = { '^police_' },
})
```

| Option | Description |
|---|---|
| `itemFilter` | `{ [itemName] = true }`. The hook only runs for these items. |
| `inventoryFilter` | Patterns (Lua `string.match`) or exact names. The hook only runs when one of the involved inventories matches. |

| Hook | Payload | Notes |
|---|---|---|
| `swapItems` | `source, action, fromInventory, toInventory, fromType, toType, fromSlot, count` | Runs when an item moves between two different inventories. `action` is `'move'`, `'throw'` and similar; `fromSlot` is the item in ox format. |
| `openInventory` | `source, inventoryId, inventoryType` | Runs when a player opens a stash. |
| `usingItem` | `source, item, inventoryId, slot, consume` | Runs before an item is used. |
| `createItem` | `inventoryId, item, count, metadata` | Runs when an item is added through the ox `AddItem`. Return a table to replace the metadata. |

Returning anything other than `false` lets the action continue. Errors in a hook are ignored.