Script de Inventário FiveM — Sistema de Itens Visual

Sistema de inventário visual para FiveM com arrastar e soltar, controle de peso, itens usáveis, hotbar e integração com outros módulos.

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