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

# Grupos e Permissões

> Como funciona e como configurar o sistema de grupos, permissões e hierarquia da base.

<Warning>
  **Importante:** não existe um recurso isolado chamado `five-groups`. Todo o sistema de grupos/permissões/hierarquia é implementado dentro do framework **vRP** (`resources/vrp`). Esta página documenta esse sistema real: a tabela `Groups`, as funções de permissão e os comandos que concedem/removem grupos.
</Warning>

O sistema do vRP é baseado em **permissões nomeadas com nível hierárquico numérico**. Cada grupo:

<CardGroup cols={3}>
  <Card title="Chave" icon="key">
    Tem uma chave (ex.: `Admin`, `Militar`, `Ouro`).
  </Card>

  <Card title="Hierarquia" icon="layer-group">
    Define uma lista de cargos onde o índice `1` é o cargo **mais alto**.
  </Card>

  <Card title="Concessão" icon="user-check">
    É concedido a um jogador por **passaporte** com um **nível** (índice da hierarquia).
  </Card>
</CardGroup>

<Note>
  O nível funciona ao contrário do "rank visual": **nível 1 = topo**. Em `vRP.HasPermission(Passport, Permission, Level)`, o jogador passa quando `CurrentLevel <= Level`: cargos mais altos sempre satisfazem checagens de cargos mais baixos.
</Note>

Conceitos centrais (`resources/vrp/modules/groups.lua`):

* **Permission:** o campo `Permission` lista as permissões que o grupo agrega. Grupos "guarda-chuva" agregam vários (ex.: `Policia`).
* **Service (em serviço/fardado):** grupos com `Service = true` entram em serviço ao conectar.
* **Domination:** grupos com `Domination = true` participam do sistema de territórios.
* **Salary:** lista por nível, paga automaticamente a cada `SalaryCooldown` segundos.

***

## Configuração

Tudo em **`resources/vrp/config/Global.lua`**.

```lua theme={null}
Currency = "R$"          -- prefixo monetário das notificações de salário
SalaryCooldown = 1800    -- intervalo (segundos) entre pagamentos => 30 min
```

<AccordionGroup>
  <Accordion title="A tabela Groups — campos disponíveis" icon="table-list">
    Cada chave é um grupo. Campos disponíveis:

    | Campo                                             | Tipo              | Função                                         |
    | ------------------------------------------------- | ----------------- | ---------------------------------------------- |
    | `Permission`                                      | `{ Nome = true }` | Permissões que o grupo agrega. Obrigatório.    |
    | `Hierarchy`                                       | lista de strings  | Cargos, do mais alto (índice 1) ao mais baixo. |
    | `Name`                                            | string            | Nome de exibição.                              |
    | `Salary`                                          | lista de números  | Salário por nível (índice = nível).            |
    | `Service`                                         | boolean           | `true` = entra em serviço ao conectar.         |
    | `ServiceGated`                                    | boolean           | Só o nível 1 entra em serviço automático.      |
    | `Domination`                                      | boolean           | Participa da dominação de território.          |
    | `Type`                                            | string            | `"Work"`, `"Fuel"`, `"Propertys"`.             |
    | `Max`                                             | número            | Limite de vagas.                               |
    | `Chat` + `ChatIcon`/`ChatBackground`/`ChatLetter` | N/A               | Tag do grupo no chat.                          |
    | `Backpack`                                        | lista             | Slots extras de mochila por nível (VIP).       |
  </Accordion>

  <Accordion title="Exemplos reais" icon="code">
    ```lua theme={null}
    Admin = {
        Permission = { Admin = true },
        Hierarchy = { "C-Level", "Diretor", "Supervisor", "Administrador", "Moderador", "Suporte" },
        Name = "Administradores",
        Service = true,
        ServiceGated = true,
        Chat = true,
        ChatIcon = "fa-solid fa-crown", ChatBackground = "#0143bb", ChatLetter = "#ffffff",
    },

    Ouro = {
        Permission = { Ouro = true },
        Hierarchy = { "Membro" },
        Salary = { 3750 },
        Backpack = { 25 },
        Service = true,
        Block = true
    },

    Militar = {
        Permission = { Militar = true },
        Hierarchy = { "Coronel","Tenente-Coronel","Major","Capitão","Tenente","Subtenente","Sargento","Cabo","Soldado","Aluno" },
        Salary = { 10000,9500,9000,8500,8000,7500,7000,6500,6000 },
        Name = "Polícia Militar",
        Type = "Work",
        Banned = true,
    },
    ```
  </Accordion>

  <Accordion title="Grupo guarda-chuva" icon="umbrella">
    Agrega várias permissões para checagens genéricas:

    ```lua theme={null}
    Policia = {
        Permission = { Militar = true, Civil = true, CORE = true, BOPE = true, PRF = true },
        Hierarchy = { "Membro" },
    }
    ```

    Com isso, `vRP.HasGroup(Passport, "Policia")` retorna verdadeiro para qualquer uma das forças.
  </Accordion>

  <Accordion title="Como adicionar um grupo" icon="circle-plus">
    ```lua theme={null}
    Mecanica = {
        Permission = { Mecanica = true },
        Hierarchy = { "Dono", "Gerente", "Mecânico" },  -- 1=Dono ... 3=Mecânico
        Salary = { 4000, 3000, 2000 },                  -- salário por nível
        Name = "Oficina Mecânica",
        Service = true,
        Type = "Work"
    },
    ```

    Depois, reinicie o recurso `vrp` e conceda com `/group`.
  </Accordion>
</AccordionGroup>

***

## Comandos

Definidos em `resources/[scripts]/admin/server-side/core.lua`:

| Comando    | Sintaxe                                        | Permissão           | Efeito                                  |
| ---------- | ---------------------------------------------- | ------------------- | --------------------------------------- |
| `/group`   | `/group [passaporte] [permissao] [hierarquia]` | `Admin` nível ≤ 4   | Concede a permissão no nível informado. |
| `groupc`   | `groupc [passaporte] [permissao] [hierarquia]` | Somente **console** | Igual ao `/group`, pelo console.        |
| `/ungroup` | `/ungroup [passaporte] [permissao]`            | `Admin` nível ≤ 2   | Remove a permissão.                     |

<Note>
  O 3º argumento (`hierarquia`) é o nível; se omitido, usa o cargo mais baixo.
</Note>

***

## Funções (interface vRP)

Outros recursos usam `vRP = Proxy.getInterface("vRP")`:

| Função                                                 | Descrição                                                  |
| ------------------------------------------------------ | ---------------------------------------------------------- |
| `vRP.HasPermission(Passport, Permission[, Level])`     | Nível atual na permissão ou `false`.                       |
| `vRP.HasGroup(Passport, Permission[, Level])`          | Verifica via a tabela `Permission` (suporta guarda-chuva). |
| `vRP.HasService(Passport, Permission[, Level])`        | Igual a `HasGroup` mas exige estar **em serviço**.         |
| `vRP.SetPermission(Passport, Permission, Level, Mode)` | Define a permissão (`Mode = "Demote"` rebaixa).            |
| `vRP.RemovePermission(Passport, Permission)`           | Remove a permissão.                                        |
| `vRP.UserGroups(Passport)`                             | `{ Permissao = nivel }` de todos os grupos.                |
| `vRP.NameHierarchy(Permission, Level)`                 | Nome do cargo num nível.                                   |

***

## Banco de Dados

<AccordionGroup>
  <Accordion title="entitydata — associação jogador↔grupo" icon="database">
    Chave-valor JSON. Chave `Permissions:<Grupo>` → `{"<passaporte>": <nivel>}`. Seed que torna o passaporte 1 admin C-Level:

    ```sql theme={null}
    INSERT INTO `entitydata` (`Name`, `Information`) VALUES ('Permissions:Admin', '{"1":1}');
    ```
  </Accordion>

  <Accordion title="permissions — metadados por grupo" icon="table">
    Metadados por grupo (`Members`, `Tags`, `Experience`, `Points`, `Bank`, `Premium`).
  </Accordion>
</AccordionGroup>

***

## Customização

* **Primeiro admin:** o seed `Permissions:Admin = {"1":1}` dá `Admin` nível 1 ao passaporte 1. Para outro, use o console: `groupc <passaporte> Admin 1`.
* **Novo VIP:** duplique `Ouro`/`Prata`/`Bronze`, ajuste `Salary` e `Backpack`.
* **Salários:** valores em cada `Salary`; intervalo em `SalaryCooldown`; moeda em `Currency`.
* **Tag de chat:** `ChatIcon` (FontAwesome), `ChatBackground`, `ChatLetter` (requer `Chat = true`).
* **Território de dominação:** crie entrada com `Domination = true` e hierarquia de facção (`Lider`/`SubLider`/`Gerente`/`Membro`/`Novato`).