One Studios
Server

Hooks

Cancellable beforeX hooks.

Hooks let you gate an inventory action before it happens. Register a callback for a beforeX event, inspect the payload, optionally mutate it in place, and return false to cancel.

local id = exports.one_inventory:RegisterHook('beforeItemAdd', function(payload)
    if payload.item == 'lockpick' and not isAllowed(payload.source) then
        return false  -- cancels the AddItem call
    end
    -- mutating in place is supported
    payload.count = math.min(payload.count, 5)
end)

-- later
exports.one_inventory:RemoveHook(id)
Returning false cancels the operation. Returning true, nil or nothing allows it. Callbacks run in registration order. Errors are caught and logged, they do not abort the chain.
For post-action notifications ("an item was added"), use Events instead.

beforeItemAdd

Fires before an item is added to an inventory. Cancel to block the add.

payload.source
number
Server id of the player, or nil for non-player inventories.
payload.inventoryId
string
payload.item
string
payload.count
number
Mutable.
payload.metadata
table
Mutable. A callback may replace or mutate payload.metadata; the add uses the mutated value.
payload.slot
number
payload.inventoryType
string
Resolved inventory type (player, stash, trunk, ...).
payload.itemDef
table
The resolved item definition, or nil if the item is unknown.

beforeItemRemove

Fires before an item is removed from an inventory. Cancel to block the removal.

payload.source
number
Server id of the player, or nil for non-player inventories.
payload.inventoryId
string
payload.item
string
payload.count
number
Mutable.
payload.metadata
table
payload.slot
number

beforeItemUse

Fires before a player uses or consumes an item. Cancel to block the use.

payload.source
number
payload.item
string
Item name.
payload.slot
number
payload.metadata
table
payload.inventoryId
string
payload.itemTable
table
The full slot item (name, count, slot, metadata).
payload.consume
number
The item's configured consume value.

beforeItemSwap

Fires before an item swap between slots or between inventories. Cancel to block the swap.

payload.source
number
payload.fromInventory
string
payload.toInventory
string
payload.fromSlot
number
payload.toSlot
number
payload.count
number
payload.item
string
Name of the item being moved.
payload.fromType
string
Type of the source inventory.
payload.toType
string
Type of the destination inventory.
payload.fromItem
table
The full source slot item.
payload.toItem
table
The full destination slot item, or nil when the target slot is empty.
payload.action
string
One of move (target empty), stack (same stackable item), or swap (different items).

beforeShopPurchase

Fires before a shop purchase is finalised. Cancel to block the sale.

payload.source
number
payload.shop
string
Shop name.
payload.item
string
payload.count
number
payload.currency
string
payload.price
number
Total price (unitPrice * count).
payload.shopId
string
payload.shopType
string
Same value as shopId.
payload.toInventory
string
Buyer's inventory id.
payload.toSlot
number
Target slot in the buyer's inventory.
payload.fromSlot
table
The shop slot being purchased from.
payload.itemName
string
payload.metadata
table
payload.unitPrice
number
Per-unit price after dynamic pricing.

beforeShopOpen

Fires before a shop UI opens. Cancel to block the open.

payload.source
number
payload.shopId
string
payload.shopType
string
Same value as shopId.
payload.label
string
Shop label.
payload.slots
number
Shop slot count.
payload.items
table
The shop's slot table.
payload.currency
string
Shop currency.

beforeItemCraft

Fires before a craft begins. Cancel to block the craft.

payload.source
number
payload.bench
string
Crafting bench name.
payload.item
string
Output item.
payload.count
number
payload.metadata
table
Mutable.
payload.benchId
string
Same value as bench.
payload.benchIndex
number
Recipe slot index on the bench.
payload.recipe
table
The recipe slot.
payload.toInventory
string
Crafter's inventory id, or nil.
payload.toSlot
number
Always nil at fire time.

beforeItemDrop

Fires before an item is dropped on the ground. Cancel to block the drop.

payload.source
number
payload.item
string
payload.count
number
payload.fromInventory
string
payload.fromSlot
number
payload.fromType
string
Type of the source inventory.
payload.fromItem
table
The full source slot item.

beforeItemGive

Fires before a player-to-player item transfer. Cancel to block the give.

payload.source
number
The giver.
payload.targetSource
number
The receiver.
payload.item
string
payload.count
number
payload.fromSlot
number
payload.fromBackpackId
string
Set when the give originated from an open backpack instead of the player's main inventory.

beforeItemSearch

Fires before a player frisks another player's inventory. Cancel to block the search.

payload.source
number
The searcher.
payload.targetSource
number
The player being searched.

beforeInventoryOpen

Fires before any inventory UI opens. Cancel to block the open.

payload.source
number
payload.data
table
Type-specific payload (stash name, plate, drop id, ...).
payload.inventoryId
string
Resolved inventory id.
payload.inventoryType
string
Resolved inventory type (player, stash, shop, crafting, drop, dumpster, vehicle:trunk, vehicle:glovebox).
payload.slot
number
Slot, when present in data.
payload.netId
number
Vehicle net id, when present in data.

beforeInventoryClose

Fires before an inventory UI closes. Cancel to keep it open.

payload.source
number
payload.data
table

Exports

See RegisterHook and RemoveHook for the export signatures.

Events

Server-side events.

Exports

Client-side exports.