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

# five-arsenal

> Loja de armas e utilitários com NUI, abertura por interação no mundo, controle de acesso por permissão/serviço e compra paga via banco.

O **five-arsenal** adiciona pontos de arsenal fixos no mapa onde jogadores autorizados (ex.: polícia) compram armas, munições, anexos e utilitários via NUI. Os pontos ficam em `Arsenal.Locations`, cada um com coordenadas, permissão e um **template** de itens. A interação é por `sleepless_interact`. A compra é processada no servidor (revalida permissões item a item, soma o total, cobra via banco e gera os itens). Itens e nomes são resolvidos pelo catálogo do vRP (`ItemName`/`ItemIndex`).

## Funcionalidades

<CardGroup cols={2}>
  <Card title="Pontos de arsenal" icon="map-pin">
    Locais fixos no mapa definidos em `Arsenal.Locations`, abertos por interação no mundo.
  </Card>

  <Card title="Controle de acesso" icon="lock">
    Acesso por permissão ou serviço (`HasService` OU `HasPermission`), por local e por item.
  </Card>

  <Card title="Catálogo por template" icon="list">
    Itens organizados em categorias via templates reaproveitáveis entre vários locais.
  </Card>

  <Card title="Compra via banco" icon="money-bill">
    Compra revalidada item a item no servidor, com cobrança via `PaymentBank` e geração dos itens.
  </Card>
</CardGroup>

***

## Dependências

<CardGroup cols={2}>
  <Card title="vrp" icon="layer-group">
    Framework base (`Passport`, `HasService`, `HasPermission`, `PaymentBank`, `GenerateItem`).
  </Card>

  <Card title="sleepless_interact" icon="hand-pointer">
    Cria os pontos no mundo. Sem ele, os arsenais ficam inacessíveis.
  </Card>

  <Card title="PL_PROTECT" icon="shield">
    Declarado como dependency (anti-cheat).
  </Card>

  <Card title="sounds" icon="volume-high">
    Efeitos sonoros (`sounds:Private`).
  </Card>
</CardGroup>

***

## Configuração

Todo o ajuste fica em `config/config.lua` (tabela `Arsenal`).

<AccordionGroup>
  <Accordion title="config/config.lua — Configurações principais" icon="sliders">
    ```lua theme={null}
    Arsenal.ThemeColor = "#0143bb"
    Arsenal.ImagesUrl = "https://cdn.fivenetwork.dev/Itens/"  -- imagem: ImagesUrl .. Index .. ".png"
    Arsenal.OpenSound = true
    Arsenal.InteractLabel = "Abrir Arsenal"
    Arsenal.InteractIcon = "person-rifle"
    Arsenal.InteractDistance = 1.5
    Arsenal.CategoryOrder = { "Rifles", "Subs", "Pistolas", "Munições", "Utilitários" }
    ```
  </Accordion>

  <Accordion title="config/config.lua — Locais" icon="map-pin">
    ```lua theme={null}
    Arsenal.Locations = {
        ["PoliciaMRPD"] = {
            coords = vec3(466.32,-1000.68,30.61),
            distance = 0.7,             -- (opcional) senão usa InteractDistance
            permission = "Policia",     -- string ou tabela; satisfeita por HasService OU HasPermission
            template = "DEFAULT_POLICE",-- (opcional) senão usa o nome do local
        },
        ["BOPE"] = { coords = vec3(-1663.63,171.04,61.95), permission = "Policia", template = "DEFAULT_POLICE" },
    }
    ```
  </Accordion>

  <Accordion title="config/config.lua — Templates (catálogo)" icon="list">
    ```lua theme={null}
    Arsenal.Templates = {
        ["DEFAULT_POLICE"] = {
            ["Rifles"] = {
                { item = "WEAPON_POLICE_CARBINERIFLE", price = 1500, permission = { "Policia" } },
            },
            ["Utilitários"] = {
                { item = "armour", price = 500, permission = { "Policia" } },
                { item = "handcuff", price = 125, permission = { "Policia" } },
            },
        },
    }
    ```

    Cada item: `item` (key do vRP), `price` (unitário), `permission` (opcional, revalidada na compra). Vários locais podem reaproveitar o mesmo template.
  </Accordion>
</AccordionGroup>

***

## Comandos

Nenhum. O arsenal é aberto pela interação `sleepless_interact` nos pontos de `Arsenal.Locations`.

***

## Localizações

Pontos de arsenal definidos em `Arsenal.Locations` (`config/config.lua`). Cada um cria uma interação no mundo (raio `distance` ou `Arsenal.InteractDistance = 1.5`) e exige a permissão indicada.

| Local                  | Coordenadas                      | Tipo                              |
| ---------------------- | -------------------------------- | --------------------------------- |
| PoliciaMRPD (raio 0.7) | `vec3(466.32, -1000.68, 30.61)`  | Interação arsenal (perm. Policia) |
| PoliciaMilitar         | `vec3(2545.69, -284.57, 93.32)`  | Interação arsenal (perm. Policia) |
| PoliciaCivil           | `vec3(-995.16, -2007.55, 13.54)` | Interação arsenal (perm. Policia) |
| BOPE                   | `vec3(-1663.63, 171.04, 61.95)`  | Interação arsenal (perm. Policia) |

***

## Exports

Não há exports Lua tradicionais. A API é via **Tunnel** `five-arsenal` (consumida pelo cliente como `vSERVER`).

| Função                         | Descrição                                        |
| ------------------------------ | ------------------------------------------------ |
| `CheckPermission(Name)`        | Verifica se o jogador pode acessar o arsenal.    |
| `GetArsenalData(Name)`         | Retorna categorias/itens formatados para a NUI.  |
| `ProcessPurchase(Name, Items)` | Processa a compra; retorna `(status, mensagem)`. |

***

## Eventos

| Evento           | Descrição                                        |
| ---------------- | ------------------------------------------------ |
| `Notify`         | Notificações (`"Arsenal"`).                      |
| `sounds:Private` | Som de loja (`"shop"`) e de dinheiro (`"cash"`). |
| `post:closeUi`   | NUI callback de fechamento.                      |
| `buyProducts`    | NUI callback de compra.                          |

***

## Banco de Dados

Nenhum. O recurso não faz queries próprias — tudo via vRP.

***

## Customização

* **Novo ponto:** entrada em `Arsenal.Locations` (`coords`, `permission`, `template`).
* **Novo catálogo:** template em `Arsenal.Templates` + categorias em `Arsenal.CategoryOrder`.
* **Itens/preços:** `{ item = "<key>", price = N, permission = { "<perm>" } }` (a key precisa existir no `Item.lua`).
* **Permissões:** por local e/ou por item (string ou tabela; `HasService` OU `HasPermission`).
* **Aparência:** `Arsenal.ThemeColor`, `Arsenal.ImagesUrl`, label/ícone do prompt.