Server

setPlayerInventory

Cria e seta o inventário do jogador.

exports.ox_inventory:setPlayerInventory(player, data)

player: table
- source: number
- identifier: string
- name: string
- groups?: table
- sex?: string
- dateofbirth?: string
data?: table
- Se não fornecido.

forceOpenInventory

Abre um inventário usando os dados fornecidos. Força um jogador a abrir um inventário, sem as checagens de segurança usuais (grupos, coordenadas).

exports.ox_inventory:forceOpenInventory(playerId, invType, data)

playerId: number
invType: string
- 'player'
- 'stash'
- 'container'
- 'drop'
- 'glovebox'
- 'trunk'
- 'dumpster'
data: number ou string ou table

Open the target player's inventory.

exports.ox_inventory:forceOpenInventory(1, 'player', 3)

Comando de administrador para abrir o inventário de um jogador.

RegisterCommand('openplayerinv', function(source, args)
    exports.ox_inventory:forceOpenInventory(source, 'player', tonumber(args[1]))
end, true)

Abre um inventário de stash, (criado no servidor com RegisterStash).

exports.ox_inventory:forceOpenInventory(1, 'stash', 'society_police')

Abre um stash de um jogador.

exports.ox_inventory:forceOpenInventory(1, 'stash', { id = 'police_locker', owner = 'license:xxxxxxxx' })

Items

Retorna uma tabela com todos os itens registrados. O formato é o definido em data/items.lua.

Opcionalmente recebe o nome de um item, retornando apenas os dados daquele item (obter todos os dados não é recomendado).

exports.ox_inventory:Items(itemName)

itemName?: string

O trecho abaixo pode ser usado em recursos de crafting como okokCrafting ou core_crafting, em vez de consultar o banco de dados.

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

Adiciona um item no inventário especificado.

Deve ser usado em conjunto com CanCarryItem, caso contrário o peso máximo pode ser excedido.

exports.ox_inventory:AddItem(inv, item, count, metadata, slot, cb)

inv: table ou string ou number
- O id único do inventário, ou uma tabela com o id e proprietário.
  - playerId: 1
  - inventoryId: gloveVGH283
  - { id = 'personallocker', owner = 'license:xxxxxx'}
item: string
- Nome do item a ser adicionado no destino.
count: number
- Quantidade de itens a adicionar.
metadata?: table ou string
- Uma tabela de dados únicos a serem anexados ao objeto item. Uma string criará uma tabela com o campo "type".
slot?: number
- Slot específico para adicionar o item. Se o slot for inválido, o primeiro slot disponível será usado.
cb?: function(success: boolean, response?: string)

Se usado para glovebox, trunk ou stash, verifique primeiro se o inventário está carregado com GetInventory.

Retorna success, response se cb for undefined; caso contrário, os valores são repassados pelo callback.

Possíveis valores do argumento "response" em caso de falha:

"invalid_item": o item não existe
"invalid_inventory": o inventário não existe
"inventory_full": sem slots livres

Exemplo

local success, response = exports.ox_inventory:AddItem('gloveVGH283', 'bread', 4)

if not success then
    -- Se não possui slots disponíveis, o valor será `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

Remove o item especificado do inventário indicado.

exports.ox_inventory:RemoveItem(inv, item, count, metadata, slot, ignoreTotal, strict)

inv: table ou string ou number
- O id único do inventário, ou uma tabela com o id e proprietário.
  - playerId: 1
  - inventoryId: gloveVGH283
  - { id = 'personallocker', owner = 'license:xxxxxx'}
item: string
- Nome do item a ser removido do destino.
count: number
- Quantidade de itens a remover.
metadata?: table ou string
- Remove apenas itens com propriedades de metadata compatíveis.
slot?: number
- Slot específico para remover o item. Se o slot for inválido, o primeiro slot disponível será usado.
ignoreTotal?: boolean
- Remove os itens sem se preocupar com o total.
strict?: boolean
- Se true (padrão), exige correspondência exata do item + metadados; se false, permite correspondências parciais/mais flexíveis.

Retorna success: boolean, response: string?.

Possíveis valores de "response" em caso de falha:

"invalid_item": o item não existe
"invalid_inventory": o inventário não existe
"not_enough_items": o inventário não continha itens suficientes

Exemplo

-- Remove 2 water do glovebox para a placa indicada.
local success = exports.ox_inventory:RemoveItem('gloveVGH283', 'water', 2)

GetItem

Retorna dados genéricos do item no inventário especificado, com a contagem total.

exports.ox_inventory:GetItem(inv, item, metadata, returnsCount)

inv: table ou string ou number
item: table ou string
- Pode ser um array de itens.
metadata?: any
- Retorna apenas itens com propriedades de metadata compatíveis.
returnsCount?: boolean

Se returnsCount for true, o valor retornado será o a conta baseada em quantas vezes o item foi encontrado. De outra forma, retorna os dados relacionados ao item e a contagem total encontrada no inventário.

Exemplo

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

Pega um array de items e transforma-os para o formato do ox_inventory.

exports.ox_inventory:ConvertItems(playerId, items)

playerId: number
items: table

Exemplo de conversão de dados

Old: [{"cola":1, "bread":3}]
New: [{"slot":1,"name":"cola","count":1},
{"slot":2,"name":"bread","count":3}]

CanCarryItem

Retornar true ou false, dependendo se o inventário pode transportar o item especificado.

A função checa o peso do inventário e o slot disponível.

exports.ox_inventory:CanCarryItem(inv, item, count, metadata)

inv: table ou string ou number
item table ou string
- Pode ser um array de itens.
count: number
metadata?: table ou string
- Se metadata for uma string, metadata.type será verificado.

Exemplo

-- Verifica se o jogador chamando o evento pode carregar 3 itens de água.
if exports.ox_inventory:CanCarryItem(source, 'water', 3) then
    -- Faça algo se puder carregar
else
    -- Faça algo se não puder carregar
end

CanCarryAmount

Retorna a quantidade um jogador pode carregar com base no peso disponível.

exports.ox_inventory:CanCarryAmount(inv, item)

inv: table ou string ou number
item: table ou string
- Pode ser um array de itens.

Exemplo

-- Verifica quantas pedras você pode carregar
amountToAdd = exports.ox_inventory:CanCarryAmount(inv, 'stone')
-- Adiciona a quantidade
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 ou string ou number
weight: number

Exemplo

-- Verifica se o jogador pode carregar 1000g.
local fillAmount = 1000
local canCarryWeight, freeWeight = ox_inventory:CanCarryWeight(playerId, fillAmount)

if freeWeight == 0 then
  -- Jogador não pode carregar.
  return
elseif not canCarryWeight then
  -- Modifica `fillAmount`, porque o inventário não consegue carregar a quantidade desejada.
  fillAmount = freeWeight
end

-- Faça algo

SetMaxWeight

Configura o peso máximo do inventário.

exports.ox_inventory:SetMaxWeight(inv, maxWeight)

inv: table ou string ou number
maxWeight: number

Exemplo

local ox_inventory = exports.ox_inventory

-- Seta o peso máximo do inventário do jogador 1 para 20kg.
ox_inventory:SetMaxWeight(1, 20000)

CanSwapItem

Retorna true se a troca for possível baseadao no peso suportado pelo inventário.

exports.ox_inventory:CanSwapItem(inv, firstItem, firstItemCount, testItem, testItemCount)

inv: table ou string ou number
firstItem: string
firstItemCount: number
testItem: string
testItemCount: number

GetItemCount

Pega o total de de todos os itens no inventário com o nome e metadados especificados.

exports.ox_inventory:GetItemCount(inv, itemName, metadata, strict)

inv: table ou string ou number
itemName: string
metadata?: table
strict?: boolean
- Analisa os metadados estritamente. Caso contrário, usará análise parcial.

Retorno:

itemCount: number

GetItemSlots

Retorna o número de slots que o item se encontra, o total de itens e o total de slots vazios.

exports.ox_inventory:GetItemSlots(inv, item, metadata)

inv: table ou string ou number
item: table ou string
metadata?: table

GetSlot

Retorna os dados do slot especificado como uma tabela.


exports.ox_inventory:GetSlot(inv, slot)

inv: table ou string ou number
slot: number

Exemplo

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 ou string ou number
itemName: string
metadata: table?

Retorno:

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 ou string ou number
itemName: string
metadata?: table
strict?: boolean
- Strictly match metadata properties, otherwise use partial matching.

Retorno:

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 ou string ou number
itemName: string
metadata?: table
strict?: boolean
- Strictly match metadata properties, otherwise use partial matching.

Retorno:

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 ou string ou number
itemName: string
metadata?: table
strict?: boolean
- Strictly match metadata properties, otherwise use partial matching.

Retorno:

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 ou string ou number
itemName: string
metadata?: table
strict?: boolean
- Strictly match metadata properties, otherwise use partial matching.

Retorno:

slotsData: table[]?

GetEmptySlot

Get the first available empty slot in an inventory.

exports.ox_inventory:GetEmptySlot(inv)

inv: table ou string ou number

Retorno:

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 ou string ou number
slotId: number

Retorno:

containerData: table?

SetSlotCount

Sets the number of slots available for an inventory.

exports.ox_inventory:SetSlotCount(inv, slots)

inv: table ou string ou number
slots: number

Exemplo

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 ou table
owner?: string ou boolean

Exemplo

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,
        ...
    }
]]

GetInventories

Retorna os IDs de todos os inventários carregados que correspondem ao type informado. Se detailed for true, retorna os dados completos do inventário em vez de apenas o ID do inventário.

exports.ox_inventory:GetInventories(invType, detailed)

invType: string
detailed?: boolean retorna os dados completos do inventário em vez de apenas o ID do inventário

Exemplo

local inventories = exports.ox_inventory:GetInventories('glovebox')

print(json.encode(inventories, {indent = true}))

--[[
    [
        "gloveK7M2Q9X4",
        "gloveP3L8V1ZN"
    ]
]]

Com detailed ativado, a função retorna os dados completos do inventário:

local inventories = exports.ox_inventory:GetInventories('glovebox', true)

print(json.encode(inventories, {indent = true}))

--[[
    [
        {
            "entityId": 184732,
            "weight": 12500,
            "netid": 73421,
            "get": {
                "__cfx_functionReference": "ox_inventory:48291:127"
            },
            "maxWeight": 88000,
            "slots": 11,
            "open": false,
            "openedBy": [],
            "id": "gloveK7M2Q9X4",
            "dbId": "K7M2Q9X4",
            "type": "glovebox",
            "label": "K7M2Q9X4",
            "owner": false,
            "minimal": {
                "__cfx_functionReference": "ox_inventory:48291:126"
            },
            "changed": false,
            "set": {
                "__cfx_functionReference": "ox_inventory:48291:125"
            },
            "items": [],
            "time": 1787604127
        },
        {
            "entityId": 192845,
            "weight": 3200,
            "netid": 73435,
            "get": {
                "__cfx_functionReference": "ox_inventory:48291:130"
            },
            "maxWeight": 88000,
            "slots": 11,
            "open": true,
            "openedBy": [12],
            "id": "gloveP3L8V1ZN",
            "dbId": "P3L8V1ZN",
            "type": "glovebox",
            "label": "P3L8V1ZN",
            "owner": false,
            "minimal": {
                "__cfx_functionReference": "ox_inventory:48291:129"
            },
            "changed": true,
            "set": {
                "__cfx_functionReference": "ox_inventory:48291:128"
            },
            "items": [],
            "time": 1787603984
        }
    ]
]]

GetInventoryItems

Returns all slots with items in a inventory.

exports.ox_inventory:GetInventoryItems(inv, owner)

inv: number ou table
owner?: string ou boolean

Exemplo

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 ou string ou number
keep?: string ou string[]

RemoveInventory

Remove um inventário da execução e salva se não for um stash temporário, dumpster ou drop.

exports.ox_inventory:RemoveInventory(inv)

inv: table ou string ou number

Search

Searches an inventory for a specified item.

exports.ox_inventory:Search(inv, search, item, metadata)

inv: table ou string ou number
search: string
item: table ou string
metadata?: table ou string

search can be either 'slots' ou '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 ou number
- Stash identifier when loading from the database.
label: string
- Display name when inventory is open.
slots: number
maxWeight: number
owner: string ou boolean ou nil
- string: Vincula o stash a um identificador específico no banco de dados, usado para buscas e exclusão.
- true: Cada jogador tem um stash único, mas pode solicitar os stashes de outros jogadores (ou seja, lockers pessoais).
- 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 ou vector3[]
instance?: number | string
- Restringe o acesso ao stash com base na instância do jogador.

Esta função precisa ser disparada antes que um jogador possa abrir o stash.

O parâmetro owner não serve para controle de acesso ao stash, use o hook openInventory para controle de acesso.

Exemplo

Para um caso de uso desta função, consulte o Guia.

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 ou boolean
  - 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 ou nil.
- 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.

Retorno:

inventoryId: string

Exemplo

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
coords: vector3
slots?: number
maxWeight?: number
instance?: string ou number
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

Retorno:

dropId: string

Exemplo

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 ou string ou number

SetDurability

Sets durability onto the specified slot.

Can be used for repairing weapons.

exports.ox_inventory:SetDurability(inv, slot, durability)

inv: table ou string ou number
slot: number
durability: number

Exemplo

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 ou string ou number
slot: number
metadata: table

Exemplo

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))

setContainerProperties

Define o item como um container e configura suas propriedades.

exports.ox_inventory:setContainerProperties(itemName, properties)

itemName: string
properties: table
- slots: number
  - Número de slots disponíveis no container.
- maxWeight: number
  - Peso máximo que o container pode armazenar.
- whitelist?: table<string, true> | string[]
  - Uma tabela com os nomes dos itens permitidos no container.
  - Se não informado, todos os itens são permitidos, exceto os da blacklist.
- blacklist?: table<string, true> | string[]
  - Uma tabela com os nomes dos itens não permitidos no container.
  - Se não informado, nenhum item entra na blacklist, a menos que uma whitelist seja fornecida.

Exemplo

-- Sets pizzabox as a container with 1 slot, maximum weight of 1000 grams and whitelists only the pizza item.
exports.ox_inventory:setContainerProperties('pizzabox', {
    slots = 1,
    maxWeight = 1000,
    whitelist = { 'pizza' },
})

On this page