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

> Punições administrativas: amarrar, prender na ilha, banir permanente e banir temporário, com persistência em banco, restauração ao reconectar e HUD para o jogador punido.

O **five-punishments** centraliza punições aplicadas por staff via comandos, com persistência em banco, restauração ao reconectar e HUD para o jogador punido. As punições `block`/`prison` ficam em memória, são persistidas em `five_punishments` e restauradas no `Connect`.

## Funcionalidades

<CardGroup cols={2}>
  <Card title="Amarrar (block)" icon="link">
    Desativa controles do jogador por tempo determinado (sem teleporte).
  </Card>

  <Card title="Prisão na ilha (prison)" icon="island-tropical">
    Teleporta para a ilha e mantém no raio; revive se cair; solta ao expirar.
  </Card>

  <Card title="Ban permanente (ban)" icon="ban">
    Via `vRP.SetBanned` (+ opcional `PL_PROTECT`).
  </Card>

  <Card title="Ban temporário (tempban)" icon="clock">
    Bane por tempo, bloqueia no `playerConnecting` pela `license`, expira sozinho.
  </Card>
</CardGroup>

***

## Dependências

<CardGroup cols={2}>
  <Card title="vrp" icon="cube">
    Framework base. Obrigatório.
  </Card>

  <Card title="oxmysql" icon="database">
    Persistência das punições. Obrigatório.
  </Card>

  <Card title="keyboard" icon="keyboard">
    Entradas dos comandos via janelas de teclado. Obrigatório.
  </Card>
</CardGroup>

<Info>
  Opcionais: `five_logs`, `PL_PROTECT` (anti-cheat) e `Notify`.
</Info>

***

## Configuração

<AccordionGroup>
  <Accordion title="config/config.lua — tabela Punishments" icon="sliders">
    ```lua theme={null}
    Punishments.CleanupInterval = 60000   -- ms da thread de limpeza
    Punishments.ReviveDelay = 5           -- checagens com vida baixa antes de reviver na ilha

    Punishments.Permission = "Admin"      -- grupo verificado
    Punishments.Levels = { Tie = 6, Prison = 6, Check = 6, Ban = 4, TempBan = 4 }  -- nível mín. por categoria

    Punishments.PrisonCoords = vector3(-2169.79, 5190.47, 18.97)  -- centro da ilha
    Punishments.PrisonRadius = 120.0
    Punishments.PrisonRelease = vector3(189.83, -938.46, 31.36)   -- soltura

    Punishments.Commands = {
        Tie = "amarrar", Untie = "desamarrar", CheckTie = "verificaramarrar", ToggleTie = "toggleamarrar",
        Prison = "prisaoadm", UnPrison = "remprisaoadm", CheckPrison = "verificarprisao",
        Ban = "ban", Unban = "unban", TempBan = "tempban",
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Comandos

As entradas são pedidas por janelas de teclado (não por argumentos). A permissão segue `Punishments.Levels`.

| Comando                        | Categoria   | Ação                                          |
| ------------------------------ | ----------- | --------------------------------------------- |
| `/amarrar` / `/desamarrar`     | Tie (6)     | Amarra/desamarra (passaporte, tempo, motivo). |
| `/verificaramarrar`            | Check (6)   | Mostra a amarração ativa.                     |
| `/prisaoadm` / `/remprisaoadm` | Prison (6)  | Prende/solta na ilha.                         |
| `/verificarprisao`             | Check (6)   | Mostra a prisão ativa.                        |
| `/toggleamarrar`               | N/A         | Liga/desliga a HUD de punição própria.        |
| `/ban` / `/unban`              | Ban (4)     | Ban permanente / remove.                      |
| `/tempban`                     | TempBan (4) | Ban temporário (tempo).                       |

<Note>
  **Formato de tempo:** número + `m`/`h`/`d` (sem unidade = minutos).
</Note>

***

## Localizações

As localizações são definidas em `config/config.lua` (tabela `Punishments`). Não há NPCs, blips ou lojas: apenas os pontos da prisão na ilha.

| Local                   | Coordenadas                         | Tipo                                                             |
| ----------------------- | ----------------------------------- | ---------------------------------------------------------------- |
| Prisão (centro da ilha) | `vector3(-2169.79, 5190.47, 18.97)` | Ponto de teleporte (`PrisonCoords`, raio `PrisonRadius = 120.0`) |
| Soltura da prisão       | `vector3(189.83, -938.46, 31.36)`   | Ponto de liberação (`PrisonRelease`)                             |

***

## Exports

Exports disponíveis nos lados servidor e cliente.

```lua theme={null}
-- servidor (recebe passaporte):
exports["five-punishments"]:IsTied(uid)      -- true, segundos, motivo
exports["five-punishments"]:IsPrisoned(uid)
-- cliente (jogador local):
exports["five-punishments"]:IsTied()         -- bool
exports["five-punishments"]:IsPrisoned()
```

***

## Banco de Dados

A tabela `five_punishments` é criada automaticamente.

| Coluna              | Descrição                                  |
| ------------------- | ------------------------------------------ |
| `passport` + `type` | Chave primária (PK).                       |
| `remaining`         | Tempo restante da punição.                 |
| `expires`           | Momento de expiração.                      |
| `license`           | Licença do jogador (usada pelo `tempban`). |
| `reason`            | Motivo da punição.                         |
| `admin`             | Staff que aplicou.                         |
| `created_at`        | Data de criação.                           |

<Note>
  O `tempban` usa `license`/`expires` para bloquear no login.
</Note>

***

## Customização

* **Comandos/permissões:** `Punishments.Commands`, `Permission`, `Levels`.
* **Prisão:** `PrisonCoords`, `PrisonRadius`, `PrisonRelease`.
* **Integrações:** isoladas em `config/functions.lua` (vRP, oxmysql, `five_logs`, `PL_PROTECT`).
* **Controles bloqueados:** thread em `client-side/core.lua` (`DisableControlAction`).