Server
setPlayerInventory
Creates and sets the player's inventory.
exports.ox_inventory:setPlayerInventory(player, data)
- player:
table
- source:
number
- identifier:
string
- name:
string
- groups?:
table
- sex?:
string
- dateofbirth?:
string
- source:
- data?:
table
- If not provided will load player's inventory data from the db.
forceOpenInventory
Opens an inventory using the passed data. Forces a player to open an inventory, without usual security checks (groups, coords).
exports.ox_inventory:forceOpenInventory(playerId, invType, data)
- playerId:
number
- invType:
string
'player'
'stash'
'container'
'drop'
'glovebox'
'trunk'
'dumpster'
- data:
number
orstring
ortable
Open the target player's inventory.
exports.ox_inventory:forceOpenInventory(1, 'player', 3)
Admin command to open a player's inventory.
RegisterCommand('openplayerinv', function(source, args)
exports.ox_inventory:forceOpenInventory(source, 'player', tonumber(args[1]))
end, true)
UpdateVehicle
Update the internal reference to vehicle stashes, without triggering a save or updating the database.
exports.ox_inventory:UpdateVehicle(oldPlate, newPlate)
- oldPlate:
string
- newPlate:
string
Items
Returns a table of all registered items. The format is as defined in data/items.lua (opens in a new tab).
Optionally takes the name of an item, returning only data for that item (getting all data is not recommended).
exports.ox_inventory:Items(itemName)
- itemName?:
string
The following snippet can be used in crafting resources such as okokCrafting or core_crafting, rather than querying the database.
local itemNames
ESX.RegisterServerCallback('crafting:itemNames', function(source, cb)
if not itemNames then
itemNames = {}
for item, data in pairs(exports.ox_inventory:Items()) do
itemNames[item] = data.label
end
end
cb(itemNames)
end)
AddItem
Adds an item into the specified inventory.
Should be used alongside CanCarryItem otherwise, the maximum weight may be exceeded.
exports.ox_inventory:AddItem(inv, item, count, metadata, slot, cb)
- inv:
table
orstring
ornumber
- The inventory's unique id, or a table with the id and owner.
- playerId:
1
- inventoryId:
gloveVGH283
{ id = 'personallocker', owner = 'license:xxxxxx'}
- playerId:
- The inventory's unique id, or a table with the id and owner.
- item:
string
- The name of the item to add to the target.
- count:
number
- The number of items to add.
- metadata?:
table
orstring
- A table of unique data to attach to the item object. A string will create a table with the "type" field.
- slot?:
number
- A specific slot to add the item to. If the slot is invalid, the first available slot will be used instead.
- cb?: function(success:
boolean
, response?:string
)
If used for glovebox, trunk or stash you must first check the inventory is loaded with GetInventory
Returns success, response
if cb is undefined, otherwise they are used in the callback only.
Possible value of the "response" argument, on failure:
- "invalid_item": the item doesn't exist
- "invalid_inventory": the inventory doesn't exist
- "inventory_full": no free slots
Example
local success, response = exports.ox_inventory:AddItem('gloveVGH283', 'bread', 4)
if not success then
-- if no slots are available, the value will be "inventory_full"
return print(response)
end
print(json.encode(response, {indent=true}))
--[[
{
"metadata": [],
"label": "Bread",
"slot": 1,
"stack": true,
"close": true,
"name": "bread",
"count": 1,
"weight": 150
}
]]
RemoveItem
Removes the specified item from the specified inventory.
exports.ox_inventory:RemoveItem(inv, item, count, metadata, slot, ignoreTotal)
- inv:
table
orstring
ornumber
- The inventory's unique id, or a table with the id and owner.
- playerId:
1
- inventoryId:
gloveVGH283
{ id = 'personallocker', owner = 'license:xxxxxx'}
- playerId:
- The inventory's unique id, or a table with the id and owner.
- item:
string
- The name of the item to remove from the target.
- count:
number
- The number of items to remove.
- metadata?:
table
orstring
- Only remove items with matching metadata properties.
- slot?:
number
- A specific slot to remove the item from. If the slot is invalid, the first available slot will be used instead.
- ignoreTotal?:
boolean
- Removes as many items as possible up to count.
Returns success: boolean
, response: string?
.
Possible values of "response" on failure:
- "invalid_item": the item doesn't exist
- "invalid_inventory": the inventory doesn't exist
- "not_enough_items": inventory did not contain enough of the given item
Example
-- Removes 2 water from the glovebox for the given plate.
local success = exports.ox_inventory:RemoveItem('gloveVGH283', 'water', 2)
GetItem
Returns generic item data from the specified inventory, with the total count.
exports.ox_inventory:GetItem(inv, item, metadata, returnsCount)
- inv:
table
orstring
ornumber
- item:
table
orstring
- Can be items array.
- metadata?:
any
- Only returns the count of items that strictly match the given metadata.
- returnsCount?:
boolean
If returnsCount
is set to true, the returned value will be the count
based on
how many times the item was found.
Otherwise returns the data related to the item and its total count found in the inventory.
Example
local item = ox_inventory:GetItem(source, 'water', nil, false)
print(json.encode(item, {indent=true}))
--[[
{
"consume": 1,
"count": 15,
"stack": true,
"name": "water",
"weight": 500,
"label": "Water",
"close": true
}
]]
ConvertItems
Takes traditional item data and updates it to support ox_inventory.
exports.ox_inventory:ConvertItems(playerId, items)
- playerId:
number
- items:
table
Data Conversion Example
Old: [{"cola":1, "bread":3}]
New: [{"slot":1,"name":"cola","count":1},
{"slot":2,"name":"bread","count":3}]
CanCarryItem
Returns true or false depending if the inventory can carry the specified item.
The function checks for inventory weight and available slots.
exports.ox_inventory:CanCarryItem(inv, item, count, metadata)
- inv:
table
orstring
ornumber
- item
table
orstring
- Can be array of items.
- count:
number
- metadata?:
table
orstring
- If metadata is passed as string then
metadata.type
will be checked.
- If metadata is passed as string then
Example
-- Checks if the player calling the event can carry 3 water items
if exports.ox_inventory:CanCarryItem(source, 'water', 3) then
-- Do stuff if can carry
else
-- Do stuff if can't carry
end
CanCarryAmount
Returns the amount a player can hold based on available weight.
exports.ox_inventory:CanCarryAmount(inv, item)
- inv:
table
orstring
ornumber
- item:
table
orstring
- Can be array to check multiple items.
Example
-- Checks how much you can carry
amountToAdd = exports.ox_inventory:CanCarryAmount(inv, 'stone')
-- Adds the amount
exports.ox_inventory:AddItem(inv, 'stone', amountToAdd)
CanCarryWeight
Returns if inventory can carry specified weight and free inventory weight.
exports.ox_inventory:CanCarryWeight(inv, weight)
- inv:
table
orstring
ornumber
- weight:
number
Example
-- Checks if player can carry 1000 grams.
local fillAmount = 1000
local canCarryWeight, freeWeight = ox_inventory:CanCarryWeight(playerId, fillAmount)
if freeWeight == 0 then
-- Player can't carry weight.
return
elseif not canCarryWeight then
-- Modify fillAmount, because inventory can't carry specified weight
fillAmount = freeWeight
end
-- Do something
SetMaxWeight
Sets the maximum weight available for an inventory.
exports.ox_inventory:SetMaxWeight(inv, maxWeight)
- inv:
table
orstring
ornumber
- maxWeight:
number
Example
local ox_inventory = exports.ox_inventory
-- Set the max weight for player 1's inventory to 20kg.
ox_inventory:SetMaxWeight(1, 20000)
CanSwapItem
Returns true if the item swap is possible based on inventory weight.
exports.ox_inventory:CanSwapItem(inv, firstItem, firstItemCount, testItem, testItemCount)
- inv:
table
orstring
ornumber
- firstItem:
string
- firstItemCount:
number
- testItem:
string
- testItemCount:
number
GetItemCount
Get the total item count for all items in an inventory with the given name and metadata.
exports.ox_inventory:GetItemCount(inv, itemName, metadata, strict)
- inv:
table
orstring
ornumber
- itemName:
string
- metadata?:
table
- strict?:
boolean
- Strictly match metadata properties, otherwise use partial matching.
Return:
- itemCount:
number
GetItemSlots
Returns the number of slots the specified item is in, the item's total count and the remaining empty slots.
exports.ox_inventory:GetItemSlots(inv, item, metadata)
- inv:
table
orstring
ornumber
- item:
table
orstring
- metadata?:
table
GetSlot
Returns the specified slot data as a table.
exports.ox_inventory:GetSlot(inv, slot)
- inv:
table
orstring
ornumber
- slot:
number
Example
local slot = exports.ox_inventory:GetSlot(source, 1)
print(json.encode(slot, {indent=true}))
--[[
{
"weight": 2000,
"name": "water",
"metadata": [],
"slot": 1,
"label": "Water",
"close": true,
"stack": true,
"count: 4
}
]]
GetSlotForItem
Get the slot id of an existing item matching the given data, or an empty slot.
exports.ox_inventory:GetSlotForItem(inv, itemName, metadata)
- inv:
table
orstring
ornumber
- itemName:
string
- metadata:
table?
Return:
- slotId:
number?
GetSlotIdWithItem
Get a slot id in an inventory matching the given item name and metadata.
exports.ox_inventory:GetSlotIdWithItem(inv, itemName, metadata, strict)
- inv:
table
orstring
ornumber
- itemName:
string
- metadata?:
table
- strict?:
boolean
- Strictly match metadata properties, otherwise use partial matching.
Return:
- slotId:
number?
GetSlotIdsWithItem
Get all slot ids in an inventory matching the given name and metadata.
exports.ox_inventory:GetSlotIdsWithItem(inv, itemName, metadata, strict)
- inv:
table
orstring
ornumber
- itemName:
string
- metadata?:
table
- strict?:
boolean
- Strictly match metadata properties, otherwise use partial matching.
Return:
- slotIds:
number[]?
GetSlotWithItem
Get data for a slot in an inventory matching the given name and metadata.
exports.ox_inventory:GetSlotWithItem(inv, itemName, metadata, strict)
- inv:
table
orstring
ornumber
- itemName:
string
- metadata?:
table
- strict?:
boolean
- Strictly match metadata properties, otherwise use partial matching.
Return:
- slotData:
table?
GetSlotsWithItem
Get data all slots in an inventory matching the given name and metadata.
exports.ox_inventory:GetSlotsWithItem(inv, itemName, metadata, strict)
- inv:
table
orstring
ornumber
- itemName:
string
- metadata?:
table
- strict?:
boolean
- Strictly match metadata properties, otherwise use partial matching.
Return:
- slotsData:
table[]?
GetEmptySlot
Get the first available empty slot in an inventory.
exports.ox_inventory:GetEmptySlot(inv)
- inv:
table
orstring
ornumber
Return:
- slotId:
number?
GetContainerFromSlot
Returns the inventory associated with the container linked in the slot of the given inventory.
exports.ox_inventory:GetContainerFromSlot(inv, slotId)
- inv:
table
orstring
ornumber
- slotId:
number
Return:
- containerData:
table?
SetSlotCount
Sets the number of slots available for an inventory.
exports.ox_inventory:SetSlotCount(inv, slots)
- inv:
table
orstring
ornumber
- slots:
number
Example
local ox_inventory = exports.ox_inventory
-- Set the slot count for player 1's inventory to 10.
ox_inventory:SetSlotCount(1, 10)
GetInventory
Returns the inventory associated with the ID (and owner if defined). Otherwise returns null.
exports.ox_inventory:GetInventory(inv, owner)
- inv:
number
ortable
- owner?:
string
orboolean
Example
local inventory = exports.ox_inventory:GetInventory('example_stash', false)
print(json.encode(inventory, {indent = true}))
--[[
{
"id": "example_stash,
"label": "Police Stash",
"type": "stash,
"slots": 50,
"weight": 0,
"maxWeight": 100000,
"owner": false,
...
}
]]
GetInventoryItems
Returns all slots with items in a inventory.
exports.ox_inventory:GetInventoryItems(inv, owner)
- inv:
number
ortable
- owner?:
string
orboolean
Example
local playerItems = exports.ox_inventory:GetInventoryItems(source)
InspectInventory
Inspect the player their inventory. You will not be able to modify the inventory.
exports.ox_inventory:InspectInventory(target, source)
- target:
number
- source:
number
ConfiscateInventory
Clears a player's inventory and saves it to a stash.
Use ReturnInventory to return the confiscated inventory back to the player.
exports.ox_inventory:ConfiscateInventory(source)
- source:
number
ReturnInventory
Returns the confiscated inventory back to the player.
Use it alongside ConfiscateInventory.
exports.ox_inventory:ReturnInventory(source)
- source:
number
ClearInventory
Clears the specified inventory. The keep
argument is either a string or an array of strings containing the name(s) of the item(s) to keep in the inventory after clearing.
exports.ox_inventory:ClearInventory(inv, keep)
- inv:
table
orstring
ornumber
- keep?:
string
orstring[]
Search
Searches an inventory for a specified item.
exports.ox_inventory:Search(inv, search, item, metadata)
- inv:
table
orstring
ornumber
- search:
string
- item:
table
orstring
- metadata?:
table
orstring
search
can be either 'slots'
or 'count'
, where slots will return a table of data
and count will return the found amount of the specified item.
RegisterStash
Creates a new custom stash.
exports.ox_inventory:RegisterStash(id, label, slots, maxWeight, owner, groups, coords)
- id:
string
ornumber
- Stash identifier when loading from the database.
- label:
string
- Display name when inventory is open.
- slots:
number
- maxWeight:
number
- owner:
string
orboolean
ornil
string
: Can only access the stash linked to the owner.true
: Each player has a unique stash but can request other player's stashes.nil
: Always shared.
- groups:
table
- Table of player groups (jobs) able to access the stash.
- Table of group names where the numeric value is the minimum grade required.
{['police'] = 0, ['ambulance'] = 2}
- coords?:
vector3
orvector3[]
This function needs to be triggered before a player can open the stash.
Example
For a use case example on this function check out the written Guide for it.
CreateTemporaryStash
Creates a temporary stash which will be removed after some time.
exports.ox_inventory:CreateTemporaryStash(properties)
- properties:
table
- label:
string
- slots:
number
- maxWeight:
number
- owner?:
string
number
orboolean
string
: Can only access the stash linked to the owner.true
: Each player has a unique stash but can request other player's stashes.- The inventory is always shared if
false
ornil
.
- groups?:
table<string, number>
- Table of group names (e.g. jobs) where the numeric value is the minimum grade required.
{['police'] = 0, ['ambulance'] = 2}
- coords?:
vector3
- Stash can only be accessed while nearby.
- items?:
{ [number]: string, [number]: number, [number]?: table }[]
- An array of tables, containing a sequence of itemName, count, metadata.
- label:
Return:
- inventoryId:
string
Example
local mystash = exports.ox_inventory:CreateTemporaryStash({
label = 'mystash',
slots = 5,
maxWeight = 5000,
items = {
{ 'WEAPON_MINISMG', 1 },
{ 'ammo-9', 69 },
{ 'water', 2, { label = 'Mineral water' } }
}
})
TriggerClientEvent('ox_inventory:openInventory', 1, 'stash', mystash)
CustomDrop
Drops can be created from other resources, containing a variety of items and utilising a custom label (instead of 'Drop 32648').
exports.ox_inventory:CustomDrop(prefix, items, coords, slots, maxWeight, instance, model)
- prefix:
string
- items:
table
- name:
string
- count:
number
- metadata?:
table
- name:
- coords:
vector3
- slots?:
number
- maxWeight?:
number
- instance?:
string
ornumber
- model?:
number
-- Create a generic drop with a marker
exports.ox_inventory:CustomDrop('Carcass', {
{'meat', 5, { grade = 2, type = 'deer' }},
{'hide', 5, { grade = 2, type = 'deer' }}
}, coords)
-- Create a drop with an entity
exports.ox_inventory:CustomDrop('SMG', {
{ 'WEAPON_MINISMG', 1 },
{ 'ammo-9', 69 },
}, GetEntityCoords(GetPlayerPed(1)), 5, 10000, nil, `w_sb_minismg`)
CreateDropFromPlayer
Creates a new drop with the contents of a player's inventory.
exports.ox_inventory:CreateDropFromPlayer(playerId)
- playerId:
number
Return:
- dropId:
string
Example
local dropId = exports.ox_inventory:CreateDropFromPlayer(1)
GetCurrentWeapon
Returns the player's currently equipped weapon as a table.
-- inv: string or number
exports.ox_inventory:GetCurrentWeapon(inv)
- inv:
table
orstring
ornumber
SetDurability
Sets durability onto the specified slot.
Can be used for repairing weapons.
exports.ox_inventory:SetDurability(inv, slot, durability)
- inv:
table
orstring
ornumber
- slot:
number
- durability:
number
Example
local ox_inventory = exports.ox_inventory
-- Set the durability of the item in slot 3 of source player's inventory to 100
ox_inventory:SetDurability(source, 3, 100)
-- Set the durability of the source player's current weapon to 100
local weapon = ox_inventory:GetCurrentWeapon(source)
if weapon then
ox_inventory:SetDurability(source, weapon.slot, 100)
end
SetMetadata
Sets metadata on the specified slot.
ox_inventory:SetMetadata(inv, slot, metadata)
- inv:
table
orstring
ornumber
- slot:
number
- metadata:
table
Example
local ox_inventory = exports.ox_inventory
local water = ox_inventory:Search(source, 1, 'water')
for k, v in pairs(water) do
print('\n______________'..'\n- index '..k)
print(v.name, 'slot: '..v.slot, 'metadata: '..json.encode(v.metadata))
water = v
break
end
water.metadata.type = 'clean'
ox_inventory:SetMetadata(source, water.slot, water.metadata)
print(('modified %sx water in slot %s with new metadata'):format(water.count, water.slot))