> For the complete documentation index, see [llms.txt](https://tgiann.gitbook.io/tgiann/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tgiann.gitbook.io/tgiann/scripts/tgiann-inventory/hooks.md).

# Hooks

Event hooks allow 3rd party resources to define new behaviour without modifying the inventory code directly.

{% hint style="danger" %}
All hooks work server-side only.
{% endhint %}

{% hint style="success" %}
Usage is identical to [`ox_inventory`](https://overextended.dev/ox_inventory/Functions/Server/Hooks), with additional features included.

As with ox\_inventory, you can cancel the operation or change the item's data using the return command.
{% endhint %}

## RegisterHook <a href="#registerhook" id="registerhook"></a>

```lua
exports["tgiann-inventory"]:RegisterHook(eventName, function(payload) end, options)
```

* eventName: `string` `swapItems` | `openInventory` | `createItem` | `buyItem` | `usingItem` | `dropWhenDieCash` | `pickupItem` | `pickupCash`
* payload: `table`
* options?: `table`
  * print?: `boolean`
    * Print to the console when triggering the event.
  * itemFilter?: `{ [string]: true }`
    * The event will only trigger for items defined as keys in a set.
  * inventoryFilter?: `string[]`
    * The event will only trigger for inventories that match one of the [patterns](http://www.easyuo.com/openeuo/wiki/index.php/Lua_Patterns_and_Captures_\(Regular_Expressions\)) in the array.
  * toInventoryFilter?: `string[]`
    * The event will only trigger for other(right Inventory) inventories that match one of the [patterns](http://www.easyuo.com/openeuo/wiki/index.php/Lua_Patterns_and_Captures_\(Regular_Expressions\)) in the array.
  * fromInventoryFilter?: `string[]`
    * The event will only trigger for player(left Inventory) inventories that match one of the [patterns](http://www.easyuo.com/openeuo/wiki/index.php/Lua_Patterns_and_Captures_\(Regular_Expressions\)) in the array.
  * typeFilter?: `{ [string]: true }`
    * The event will only trigger for inventories with one of the provided types (e.g. 'player', 'stash')

Return:

* hookId: `number`

{% hint style="info" %}
Inventory ids in the payloads are the internal key names: player inventories are `player_<source>`, trunks `trunk_<plate>`, gloveboxes `glovebox_<plate>`, drops `drop_<id>` and stashes use their stash name (`name:citizenid` for owner stashes).
{% endhint %}

***

### swapItems <a href="#swapitems" id="swapitems"></a>

Triggered when moving any item from one slot to another, when dropping it on the ground or when "giving" an item.\
By returning `false`, you can cancel the action and revert the inventory state.

On the grid an item can push several other items out of its way. The hook then runs once for the moved item and once for every item it displaces, and returning `false` for any of them cancels the whole move.

* Payload: `table`
  * source: `number`
  * action: `'move'` or `'stack'` or `'swap'` or `'give'` (`give` when the item is handed to another player)
  * fromInventory: `string`
  * toInventory: `string`
  * fromType: `string`
  * toType: `string`
  * fromSlot: `table` the item data being moved
  * toSlot?: `number` the top left cell the item lands on
  * count: `number`
  * dropId?: `string` only when the item is dropped on the ground

**Example**

Blacklists "water" from being moved into or from gloveboxes and trunks.

```lua
local hookId = exports["tgiann-inventory"]:registerHook('swapItems', function(payload)
    print(json.encode(payload, { indent = true }))
    return false
end, {
    print = true,
    itemFilter = {
        water = true,
    },
    inventoryFilter = {
        '^glove[%w]+',
        '^trunk[%w]+',
    }
})
```

***

### openInventory <a href="#openinventory" id="openinventory"></a>

* Payload: `table`
  * source: `number`
  * inventoryId: `string`
  * inventoryType: `string`

Triggered when a player tries to open a secondary inventory.

**Example**

```lua
local hookId = exports["tgiann-inventory"]:registerHook('openInventory', function(payload)
    print(json.encode(payload, { indent = true }))
end, {
    print = true,
    inventoryFilter = {
        '^glove[%w]+',
        '^trunk[%w]+',
    }
})
```

***

### createItem <a href="#createitem" id="createitem"></a>

* Payload: `table`
  * source?: `number`
  * inventoryId?: `number` or `string`
  * metadata: `table`
  * item: `table`
  * count: `number`

Triggered when an item is created, either by buying it, using AddItem, or when converting inventory data. Returning a table replaces the item metadata.

**Example**

```lua
local hookId = exports["tgiann-inventory"]:registerHook('createItem', function(payload)
    print(json.encode(payload, { indent = true }))
end, {
    print = true,
    itemFilter = {
        water = true
    }
})
```

***

### buyItem <a href="#buyitem" id="buyitem"></a>

* Payload: `table`
  * source: `number`
  * shopType: `string` shop name, the key inside `config.Products`
  * toInventory: `string`
  * toSlot?: `number`
  * itemName: `string`
  * count: `number`
  * price: `number` unit price
  * totalPrice: `number`
  * currency: `'cash'` or `'bank'` the payment method chosen at checkout, or the one forced by the shop

Triggered when an item is about to be purchased. When the player buys a cart with several products, the hook runs once per product.

**Example**

```lua
local hookId = exports["tgiann-inventory"]:registerHook('buyItem', function(payload)
    print(json.encode(payload, { indent = true, sort_keys = true }))
end, {
    print = true,
    itemFilter = {
        water = true
     },
})
```

***

### usingItem

* Payload: `table`
  * source: `number`
  * inventoryId: `number`
  * item: `table`
  * consume?: `number`

Triggered before an item is used. Returning `false` cancels the use.

**Example**

```lua
local hookId = exports["tgiann-inventory"]:registerHook('usingItem', function(payload)
    print(json.encode(payload, { indent = true, sort_keys = true }))
end, {
    print = true,
    itemFilter = {
        water = true
     },
})
```

***

### dropWhenDieCash

* Payload: `table`
  * source: `number`
  * count: `number` cash that is about to drop

Triggered when a player dies and their cash is about to be dropped on the ground (`config.dropWhenDie.money`). Returning `false` keeps the cash on the player.

**Example**

```lua
local hookId = exports["tgiann-inventory"]:registerHook('dropWhenDieCash', function(payload)
    if exports["tgiann-safezone"]:isPlayerInSafezone(payload.source) then return false end
end)
```

***

### pickupItem

* Payload: `table`
  * source: `number`
  * type: `'weapon'` or `'item'`
  * item: `table` the item data being picked up (`name`, `amount`, `info`)
  * count: `number`

Triggered when a player picks up an item or a weapon lying on the ground as a world object (thrown items, weapons and items dropped when a player dies). Returning `false` leaves it on the ground. When the drop holds several items, the hook runs once per item and only the cancelled ones stay behind.

**Example**

Stops players from picking up weapons dropped inside a safe zone.

```lua
local hookId = exports["tgiann-inventory"]:registerHook('pickupItem', function(payload)
    if payload.type == "weapon" and exports["tgiann-safezone"]:isPlayerInSafezone(payload.source) then
        return false
    end
end)
```

***

### pickupCash

* Payload: `table`
  * source: `number`
  * count: `number` cash that is about to be picked up

Triggered when a player picks up cash lying on the ground. Returning `false` leaves the cash on the ground.

**Example**

```lua
local hookId = exports["tgiann-inventory"]:registerHook('pickupCash', function(payload)
    print(("%s picked up $%s"):format(GetPlayerName(payload.source), payload.count))
end)
```

## RemoveHooks <a href="#removehooks" id="removehooks"></a>

Removes a hook created by the invoking resource with the the specified id.\
If no id is specified then all hooks registered by the resource are removed.

```lua
exports["tgiann-inventory"]:RemoveHooks(id)
```

* id?: `number`