> ## Documentation Index
> Fetch the complete documentation index at: https://docs.temacstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```lua config.lua theme={null}
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.

```lua config.lua theme={null}
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.

```lua server/items.lua theme={null}
exports['inventario']:RegisterUsableItem('water', function(source)
    -- Remove o item do inventário e aplica o efeito no cliente
    TriggerClientEvent('inventario:drinkWater', source)
end)
```

<Note>
  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.
</Note>

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

```lua theme={null}
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)

```lua theme={null}
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)

```lua theme={null}
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)

```lua theme={null}
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              |