> ## 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 Admin FiveM — Painel e Ferramentas de Moderação

> Ferramentas completas de administração para servidores FiveM: ban, kick, menu de admin, teleporte, logs de ações e gerenciamento de jogadores.

O módulo de **Admin** fornece todas as ferramentas necessárias para moderar e gerenciar o seu servidor FiveM. Através do menu de admin e comandos de console, você controla jogadores, aplica punições, consulta logs e realiza ações de manutenção diretamente em jogo.

## Funcionalidades

* Menu de admin acessível via tecla configurável
* Sistema de ban (temporário e permanente) com identificadores
* Kick com mensagem personalizada
* Teleporte para jogadores e coordenadas
* Modo invisível e noclip para admins
* Logs de ações exportáveis para webhook do Discord
* Visualização de identificadores de jogadores
* Ferramentas de spawn de veículos e objetos
* Compatível com o sistema de ACE nativo do FiveM

## Configuração de Permissões

Defina grupos de administração no `config.lua`. Cada grupo recebe um conjunto de permissões que determinam quais ações seus membros podem executar. Você pode criar quantos grupos precisar (ex: `'head_admin'`, `'trial_mod'`).

```lua config.lua theme={null}
Config.AdminGroups = {
    ['superadmin'] = {
        label             = 'Super Admin',
        canBanPermanent   = true,
        canBanTemp        = true,
        canKick           = true,
        canSpawnVehicle   = true,
        canTeleport       = true,
        canViewLogs       = true,
        canManagePlayers  = true,
    },
    ['moderator'] = {
        label             = 'Moderador',
        canBanPermanent   = false,
        canBanTemp        = true,    -- Bans temporários permitidos para este grupo
        canKick           = true,
        canSpawnVehicle   = false,
        canTeleport       = true,
        canViewLogs       = true,
        canManagePlayers  = false,
    },
}
```

## Configuração do Menu de Admin

O menu de admin é aberto com `F10` por padrão. Altere a tecla conforme a preferência da equipe:

```lua config.lua theme={null}
Config.AdminMenuKey = 'F10'  -- Tecla para abrir o menu de admin
```

Através do menu você acessa:

* Lista de jogadores online com ações rápidas (kick, ban, teleporte)
* Histórico de bans ativos e ferramentas para desbanir
* Spawner de veículos e objetos
* Painel de logs das ações recentes

## Configuração de Logs

Os logs registram todas as ações administrativas e podem ser enviados automaticamente para um canal do Discord via webhook.

```lua config.lua theme={null}
Config.Logs = {
    enabled    = true,
    logToFile  = true,    -- Salva logs em arquivo na pasta do recurso
    webhookURL = 'https://discord.com/api/webhooks/SEU_ID/SEU_TOKEN',
    logActions = {
        ban       = true,
        kick      = true,
        spawn     = true,
        teleport  = false,  -- Desativado por padrão para evitar excesso de entradas
    },
}
```

<Warning>
  Nunca compartilhe a URL do webhook do Discord publicamente. Com ela, qualquer pessoa pode enviar mensagens para o canal sem autenticação. Mantenha o `config.lua` fora de repositórios públicos.
</Warning>

## Comandos de Moderação

### Punições de Jogadores

| Comando                      | Permissão        | Descrição                                         |
| ---------------------------- | ---------------- | ------------------------------------------------- |
| `/kick [id] [motivo]`        | `admin.kick`     | Expulsa um jogador do servidor                    |
| `/ban [id] [tempo] [motivo]` | `admin.ban`      | Bane um jogador (ex: `1d`, `7d`, `perm`)          |
| `/unban [identificador]`     | `admin.ban`      | Remove um ban pelo identificador                  |
| `/freeze [id]`               | `admin.moderate` | Congela um jogador no lugar                       |
| `/spectate [id]`             | `admin.moderate` | Entra em modo espectador para observar um jogador |

### Ferramentas Administrativas

| Comando        | Permissão        | Descrição                             |
| -------------- | ---------------- | ------------------------------------- |
| `/tp [id]`     | `admin.teleport` | Teleporta você até outro jogador      |
| `/tphere [id]` | `admin.teleport` | Teleporta outro jogador até você      |
| `/coords`      | `admin.teleport` | Exibe suas coordenadas atuais no mapa |
| `/noclip`      | `admin.noclip`   | Ativa ou desativa o voo livre         |
| `/invis`       | `admin.invis`    | Ativa ou desativa invisibilidade      |
| `/adminmenu`   | `admin.menu`     | Abre o menu de admin manualmente      |

## API — Integrações via Exports e Eventos

### Verificar se jogador é admin (servidor)

```lua theme={null}
local isAdmin = exports['admin']:IsPlayerAdmin(source)
-- Retorna true se o jogador tiver qualquer grupo de admin configurado
```

### Obter grupo do jogador (servidor)

```lua theme={null}
local group = exports['admin']:GetPlayerGroup(source)
-- Retorna a chave do grupo (ex: 'superadmin', 'moderator') ou nil
```

### Registrar ação no log (servidor)

```lua theme={null}
exports['admin']:LogAction(source, 'custom_action', 'Descrição da ação realizada')
-- Parâmetros: source (admin que agiu), tipo (string), descrição (string)
```

### Evento disparado ao banir jogador (servidor)

```lua theme={null}
AddEventHandler('admin:onPlayerBanned', function(adminId, targetId, duration, reason)
    print('Admin ' .. adminId .. ' baniu ' .. targetId .. ' por: ' .. reason)
end)
```

## Resolução de Problemas

| Problema                      | Causa provável                         | Solução                                                              |
| ----------------------------- | -------------------------------------- | -------------------------------------------------------------------- |
| Comando de admin não funciona | Jogador sem grupo de admin configurado | Verifique a atribuição de grupo via ACE ou `Config.AdminGroups`      |
| Logs não aparecem no Discord  | URL de webhook incorreta ou desativada | Confirme a URL no `config.lua` e verifique se `enabled = true`       |
| Menu de admin não abre        | Tecla conflitante com outro recurso    | Altere `Config.AdminMenuKey` para uma tecla não usada                |
| Ban temporário não expira     | Formato de tempo inválido              | Use o formato correto: `1d` (1 dia), `7d` (7 dias), `24h` (24 horas) |