Script de Inventário FiveM — Sistema de Itens Visual

O módulo de Inventário adiciona um sistema visual de itens ao seu servidor FiveM. Os jogadores gerenciam seus pertences através de uma interface gráfica com arrastar e soltar, respeitando limites de peso configuráveis por personagem.

Funcionalidades

Interface visual com arrastar e soltar
Sistema de peso configurável por personagem
Hotbar com slots rápidos
Itens usáveis com callbacks personalizáveis
Inventário de caixas e cofres no mundo do jogo
Troca de itens entre jogadores
Integração com ox_inventory e qb-inventory
Histórico de movimentação de itens

Configuração Básica

Defina os limites e o comportamento padrão do inventário no config.lua. O maxWeight controla o peso total que um personagem pode carregar; itens com weight zerado não afetam a capacidade.

config.lua

Config.Inventory = {
    maxWeight   = 30.0,   -- Peso máximo em kg
    hotbarSlots = 5,      -- Número de slots visíveis na hotbar
    gridColumns = 5,      -- Colunas na grade do inventário
    gridRows    = 6,      -- Linhas na grade (total de slots = colunas × linhas)
    enableDrops = true,   -- Permite largar itens no chão do mundo
    dropExpiry  = 600,    -- Itens largados no chão somem após X segundos
}

Configuração de Itens

Registre todos os itens disponíveis no servidor em config.lua. O campo image aponta para um arquivo dentro da pasta html/images/ do recurso. Itens com unique = true não podem ser empilhados nem duplicados no mesmo inventário.

config.lua

Config.Items = {
    ['water'] = {
        label     = 'Água',
        weight    = 0.5,
        usable    = true,
        stackable = true,
        image     = 'water.png',   -- Arquivo em html/images/water.png
    },
    ['bandage'] = {
        label     = 'Curativo',
        weight    = 0.2,
        usable    = true,
        stackable = true,
    },
    ['lockpick'] = {
        label     = 'Gazua',
        weight    = 0.1,
        usable    = true,
        stackable = false,
        unique    = true,          -- Impede duplicatas no mesmo inventário
    },
}

Itens Usáveis

Registre um callback no servidor para executar lógica quando o jogador usar um item. O callback roda no lado servidor; use TriggerClientEvent para aplicar efeitos visuais no cliente.

server/items.lua

exports['inventario']:RegisterUsableItem('water', function(source)
    -- Remove o item do inventário e aplica o efeito no cliente
    TriggerClientEvent('inventario:drinkWater', source)
end)

O nome do export ('inventario') deve ser o mesmo nome do recurso definido no seu fxmanifest.lua. Substitua conforme o nome que você usou ao instalar o módulo.

Comandos do Módulo Inventário

Comando	Permissão	Descrição
`/inv`	Qualquer jogador	Abre o próprio inventário
`/giveitem [id] [item] [qtd]`	`inventory.admin`	Dá um item para o jogador com o ID especificado
`/removeitem [id] [item] [qtd]`	`inventory.admin`	Remove uma quantidade de item do jogador
`/clearinv [id]`	`inventory.admin`	Limpa completamente o inventário do jogador

API — Integrações via Exports e Eventos

Adicionar item ao inventário de um jogador (servidor)

local success = exports['inventario']:AddItem(source, 'water', 2)
-- Retorna true se o item foi adicionado, false se o peso máximo foi atingido

Remover item do inventário de um jogador (servidor)

local success = exports['inventario']:RemoveItem(source, 'water', 1)
-- Retorna true se o item existia e foi removido, false caso contrário

Verificar se jogador tem um item (servidor)

local hasItem = exports['inventario']:HasItem(source, 'lockpick', 1)
-- Retorna true se o jogador tiver ao menos a quantidade informada

Evento disparado ao usar um item (cliente)

AddEventHandler('inventario:onItemUsed', function(itemName)
    print('Item usado: ' .. itemName)
end)

Resolução de Problemas

Problema	Causa provável	Solução
Item não aparece na interface	Item não cadastrado em `Config.Items`	Adicione o item e reinicie o recurso
Imagem do item não carrega	Arquivo ausente em `html/images/`	Adicione a imagem com o nome exato definido no campo `image`
Callback de item usável não dispara	Nome do export incorreto	Confirme que o nome do recurso no export bate com o do `fxmanifest.lua`
Jogador não consegue pegar item	Peso máximo atingido	Aumente `maxWeight` ou oriente o jogador a descartar itens

Introdução

Guias

Scripts

Referência

Suporte

Script de Inventário FiveM — Sistema de Itens Visual

Funcionalidades

Configuração Básica

Configuração de Itens

Itens Usáveis

Comandos do Módulo Inventário

API — Integrações via Exports e Eventos

Adicionar item ao inventário de um jogador (servidor)

Remover item do inventário de um jogador (servidor)

Verificar se jogador tem um item (servidor)

Evento disparado ao usar um item (cliente)

Resolução de Problemas

​Funcionalidades

​Configuração Básica

​Configuração de Itens

​Itens Usáveis

​Comandos do Módulo Inventário

​API — Integrações via Exports e Eventos

​Adicionar item ao inventário de um jogador (servidor)

​Remover item do inventário de um jogador (servidor)

​Verificar se jogador tem um item (servidor)

​Evento disparado ao usar um item (cliente)

​Resolução de Problemas

Funcionalidades

Configuração Básica

Configuração de Itens

Itens Usáveis

Comandos do Módulo Inventário

API — Integrações via Exports e Eventos

Adicionar item ao inventário de um jogador (servidor)

Remover item do inventário de um jogador (servidor)

Verificar se jogador tem um item (servidor)

Evento disparado ao usar um item (cliente)

Resolução de Problemas