Guia Completo de ox_inventory para FiveM

O que é ox_inventory?

ox_inventory é um sistema de inventário moderno e de alto desempenho para FiveM que se tornou a escolha padrão para servidores de RPG sérios. Desenvolvido pela equipe Overextended, ele substitui soluções de estoque mais antigas por um sistema mais rápido, mais flexível e mais fácil de estender. Ele apresenta uma interface de usuário elegante baseada em React, gerenciamento de armas integrado, suporte de criação, lojas, esconderijos e uma API poderosa que os desenvolvedores de scripts podem usar para criar interações de itens personalizados. Esteja você construindo um novo servidor ou migrando de outro inventário, entender profundamente ox_inventory fará de você um desenvolvedor FiveM melhor.

Instalação e configuração

ox_inventory requer ox_lib como dependência e funciona com estruturas ESX e QBCore, bem como configurações independentes. A instalação envolve o download do recurso, a importação do esquema SQL para o seu banco de dados e a configuração da ponte da estrutura. O arquivo de configuração controla tudo, desde limites de peso do inventário até temporizadores de redução de itens.

-- Configuration snippet from ox_inventory
return {
    playerslots = 50,
    playerweight = 30000,
    playerweaponslots = 5,

    decay = true,
    decayInterval = 60,

    trunkslots = 50,
    trunkweight = 60000,
    gloveboxslots = 5,
    gloveboxweight = 5000,
}

Registrando itens personalizados

Os itens em ox_inventory são definidos no arquivo data/items.lua. Cada item precisa de um nome exclusivo, um rótulo, um peso e, opcionalmente, um tamanho de pilha, taxa de decaimento, descrição e manipuladores de eventos do lado do cliente ou do servidor. Compreender o esquema completo de definição de item permite criar itens que fazem exatamente o que seus scripts precisam.

-- data/items.lua
return {
    ['water_bottle'] = {
        label = 'Water Bottle',
        weight = 500,
        stack = true,
        close = true,
        description = 'A refreshing bottle of water',
        client = {
            image = 'water_bottle.png',
        }
    },

    ['lockpick'] = {
        label = 'Lockpick',
        weight = 200,
        stack = true,
        close = true,
        degrade = 300,
        description = 'Used to pick locks. Breaks after use.',
    },

    ['driver_license'] = {
        label = 'Driver License',
        weight = 0,
        stack = false,
        consume = 0,
        description = 'Issued by the DMV',
        client = {
            image = 'driver_license.png',
        }
    },
}

Usando a API do servidor ox_inventory

As exportações do lado do servidor são a parte mais comumente usada do ox_inventory, permitindo adicionar itens, remover itens, verificar o conteúdo do inventário e manipular metadados. Sempre use a API do lado do servidor para manipulação de itens para evitar a exploração por trapaceiros.

-- Server-side: Adding items to a player
RegisterNetEvent('myresource:giveReward', function(itemName, count)
    local src = source
    local success = exports.ox_inventory:AddItem(src, itemName, count)

    if success then
        TriggerClientEvent('ox_lib:notify', src, {
            title = 'Item Received',
            description = count .. 'x ' .. itemName,
            type = 'success'
        })
    else
        TriggerClientEvent('ox_lib:notify', src, {
            title = 'Inventory Full',
            description = 'Could not add item to inventory',
            type = 'error'
        })
    end
end)

-- Server-side: Check if player has required items
local function HasRequiredItems(src, requirements)
    for _, req in ipairs(requirements) do
        local count = exports.ox_inventory:GetItemCount(src, req.name)
        if count < req.amount then
            return false, req.name, req.amount - count
        end
    end
    return true
end

-- Server-side: Remove multiple items in a transaction
local function ConsumeRecipeItems(src, recipe)
    for _, ingredient in ipairs(recipe.ingredients) do
        local removed = exports.ox_inventory:RemoveItem(
            src, ingredient.name, ingredient.amount
        )
        if not removed then
            print(('[ERROR] Failed to remove %s from player %d'):format(
                ingredient.name, src
            ))
            return false
        end
    end
    return true
end

Trabalhando com metadados de itens

Os metadados de itens são um dos recursos mais poderosos do ox_inventory. Ele permite que você anexe dados arbitrários a instâncias de itens individuais, permitindo números de série exclusivos em armas, datas de validade em alimentos, nomes de jogadores em cartões de identificação e propriedades personalizadas em qualquer item.

-- Server: Create a driver license with metadata
RegisterNetEvent('myresource:issueLicense', function(targetId, licenseType)
    local src = source

    local metadata = {
        type = licenseType,
        issued = os.date('%Y-%m-%d'),
        issuedBy = GetPlayerName(src),
        holder = GetPlayerName(targetId),
        expires = os.date('%Y-%m-%d', os.time() + 30 * 86400),
    }

    exports.ox_inventory:AddItem(targetId, 'driver_license', 1, metadata)
end)

-- Client: Reading metadata when using an item
exports('driver_license', function(data, slot)
    local item = exports.ox_inventory:GetSlot(slot)
    if not item or not item.metadata then return end

    local meta = item.metadata
    lib.notify({
        title = 'Driver License',
        description = ('Holder: %s\nType: %s\nExpires: %s'):format(
            meta.holder or 'Unknown',
            meta.type or 'Standard',
            meta.expires or 'N/A'
        ),
        type = 'inform'
    })
end)

Criando Lojas Personalizadas

ox_inventory inclui um sistema de loja integrado que você pode configurar com catálogos de itens personalizados, preços, restrições de trabalho e locais. As lojas são definidas em data/shops.lua e podem ser anexadas a fornecedores ped, locais de blip ou acionadas programaticamente.

-- data/shops.lua
return {
    ['hardware_store'] = {
        name = 'Hardware Store',
        inventory = {
            { name = 'lockpick',    price = 150,  count = 10 },
            { name = 'screwdriver', price = 80,   count = 20 },
            { name = 'radio',       price = 250,  count = 5  },
            { name = 'repairkit',   price = 1000, count = 5  },
        },
        locations = {
            vec3(45.6, -1749.3, 29.6),
            vec3(2747.8, 3472.9, 55.7),
        },
        targets = {
            ped = 's_m_y_hardware_01',
            scenario = 'WORLD_HUMAN_STAND_IMPATIENT',
            distance = 2.5,
        },
    },
}

Sistema de armazenamento e contêineres personalizados

Stashes são contêineres de armazenamento persistentes que os jogadores podem acessar em locais específicos. ox_inventory oferece suporte a esconderijos pessoais vinculados a um identificador de jogador, esconderijos compartilhados acessíveis a qualquer pessoa e esconderijos com restrição de trabalho para salas de evidências policiais e armazenamento hospitalar.

-- Server: Register a custom stash for a property
local function CreatePropertyStash(propertyId, owner)
    local stashId = ('property_%s'):format(propertyId)

    exports.ox_inventory:RegisterStash(
        stashId,
        ('Property #%s Storage'):format(propertyId),
        100,     -- slots
        200000,  -- max weight
        owner    -- owner identifier (or false for shared)
    )

    return stashId
end

-- Client: Open a stash when interacting with a storage point
RegisterNetEvent('myresource:openPropertyStorage', function(propertyId)
    local stashId = ('property_%s'):format(propertyId)
    exports.ox_inventory:openInventory('stash', stashId)
end)

Práticas recomendadas para integração com ox_inventory

• Sempre valide o lado do servidor. Nunca confie nas verificações de inventário do lado do cliente. Use exportações de servidor como GetItemCount e RemoveItem para toda a lógica crítica do jogo.
• Use metadados com moderação. Embora os metadados sejam poderosos, o armazenamento excessivo de dados em cada item aumenta o tamanho do banco de dados e o tráfego da rede. Armazene apenas o que você realmente precisa.
• Lide com inventários cheios com elegância. Sempre verifique o valor de retorno de AddItem e forneça feedback claro ao jogador quando seu inventário estiver cheio.
• Use a degradação de itens para obter realismo. A propriedade de degradação cria coletores naturais de itens que mantêm sua economia equilibrada. Defina tempos de decomposição apropriados para produtos e ferramentas perecíveis.
• Aproveite o sistema de criação integrado. Em vez de criar sua própria lógica de criação, use bancos de criação ox_inventory que lidam com verificações, remoções e criação automaticamente.
• Mantenha a consistência das imagens dos itens. Coloque todas as imagens dos itens em web/images/ com nomes de arquivo correspondentes. Use arquivos PNG de 100 x 100 com fundos transparentes para obter uma aparência mais limpa.