# Likizão AntiCheat — Guia de Instalação e Integração

---

## 1. Instalação

1. Coloque o resource na sua pasta `resources/` e garanta que ele inicie **antes** dos
   scripts do seu framework que criam veículos/objetos — ele valida as entidades no momento
   em que são criadas, então precisa estar rodando antes delas existirem.
2. Edite os arquivos dentro de `config/`:
   - `shared_flags.lua` — flags de funcionalidade (seção 3).
   - `shared_func.lua` — funções de ponte com o framework (seção 2).
   - `shared_commands.lua` — comandos e permissões (seção 8).
   - `shared_weapons.lua` — mapa hash → nome de exibição usado pela wall e pelos logs.
   - `sv_detections.lua` — comportamento por detecção (seção 4).
   - `sv_webhooks.lua` — webhooks do Discord.
   - `sv_report_handler.lua` — filtro de reports, notificação de admins e função de ban.
3. Inicie o resource e confirme que o console imprime `(likizao_ac) -> Carregado com sucesso!`.

> **Um servidor por licença.** Uma licença não pode ser compartilhada entre vários servidores —
> só um servidor ativo é permitido por licença. Se você precisa de um segundo servidor (um de
> teste ou desenvolvimento, por exemplo), ele precisa da própria licença.

---

## 2. Funções do framework (`config/shared_func.lua`)

O anticheat nunca fala diretamente com o seu framework — ele só chama as funções abaixo.
Preencha com o que o seu framework usa. O arquivo padrão vem escrito para vRP.

### `Config.Functions.getUserId(source)`

Retorna um **ID único e estável por conta**, derivado do `source` do jogador.

- vRP: `vRP.getUserId(source)`
- ESX: `ESX.GetPlayerFromId(source).identifier`
- QBCore: `QBCore.Functions.GetPlayer(source).PlayerData.citizenid`
- Sem nenhum sistema de contas: apenas `return source` — funciona bem, o valor só é usado
  para logs, chamadas de ban e o rótulo da wall.

Precisa retornar `nil` quando o jogador ainda não carregou; o anticheat trata esse caso e
registra o report usando os identificadores brutos.

```lua
Config.Functions.getUserId = function(source)
    return vRP.getUserId(source)
end
```

### `Config.Functions.getUserSource(user_id)`

O inverso de `getUserId`: dado o ID, retorna o `source` atual, ou `nil` se estiver offline.
Usado para notificar admins online.

### `Config.Functions.hasPermission(user_id, permission)`

Retorna `true`/`false`. `permission` é a string que você definir em `shared_commands.lua`
(`player.wall`, `player.propmanager`, `player.cleanarea`).

### `Config.Functions.getUsersByPermission(permission)`

Retorna uma lista de `user_id` que possuem a permissão. Usada por `Config.NotifyAdmins` para
descobrir quem deve receber os alertas de detecção (consulta `player.noclip` por padrão).

### `Config.Functions.getIdentity(user_id)`

Retorna a identidade do personagem para a wall. Qualquer um destes formatos é aceito:
`{ name, firstname }`, `{ name, name2 }` ou `{ nome, sobrenome }`. Retornar `nil` faz a wall
mostrar `SEM NOME`.

### `Config.Functions.getUserGroupByType(user_id, 'job')`

Retorna o nome do emprego do jogador (string) para o rótulo da wall, ou `nil`/`false`.

### `Config.Functions.Notify(src, type, message)`

Seu sistema de notificação. `type` é um entre `sucesso`, `negado`, `importante`. Mapeie esses
valores para os tipos do seu próprio sistema na tabela `VALID_TYPES` logo acima da função.

### `Config.Labels`

Textos de mensagens da wall e de permissão. Traduza à vontade.

---

## 3. Flags (`config/shared_flags.lua`)

Flags são apenas strings em `Config.Flags`. Tudo que não estiver listado ali fica desativado.

```lua
Config.Flags = {
    '--heartbeat-v2',
    '--enable-custom-object',
    '--enable-vehicle-check',
}
```

| Flag | Efeito |
|------|--------|
| `--enable-custom-object` | Ativa a proteção de objetos e peds. Os objetos precisam estar liberados (seção 7) e peds que não são jogadores são bloqueados. Sem ela, nenhum objeto ou ped é validado. |
| `--enable-vehicle-check` | Ativa a validação de spawn de veículos: um veículo criado por um jogador precisa ser autorizado antes (seção 6). Veículos criados no servidor são aceitos automaticamente. |
| `--enable-sv.vehicle-spawn` | Para servidores que criam veículos **apenas** no lado servidor: todo veículo novo precisa ser confirmado como legítimo em vez de ser confiado, então spawns vindos do client não são mantidos. |
| `--enable-explosions` | Permite explosões e projéteis para jogadores que tenham uma arma autorizada. Sem ela, explosões e projéteis são bloqueados no servidor inteiro. |
| `--disable-player-constraints` | Afrouxa as regras de bucket para as checagens de arma e ativa o vigia de noclip. Use em servidores que dependem bastante de routing buckets. |
| `--disable-weapon-handler` | Desliga o módulo de armas por completo. Apenas para depuração. |
| `--disable-unarmed-damage` | Pula a validação de dano desarmado. Útil com dano corpo a corpo customizado. |
| `--disable-attachment-check` | Desativa a checagem de objetos anexados à entidade de outro jogador. Ela pode gerar falsos positivos por divergência de dono, já que entidades criadas no servidor não têm dono no client e acabam parecendo de outra pessoa. |
| `--disable-citizen-check` | Lado client: desativa as checagens de integridade do client. |
| `--disable-scenario-check` | Desativa a checagem de spam de cenário. |
| `--anticl2` | Uma sessão por licença: se a mesma licença entra duas vezes, as duas sessões são derrubadas. |
| `--set-population` | Para servidores que usam população ambiente (trânsito de IA, pedestres, NPCs de cenário). |
| `--heartbeat-v2` | Heartbeat melhorado. Recomendada — mantenha ativa por padrão. |
| `--canary` | Novo tratamento para spawns de veículo feitos no servidor. Ative se tiver problemas com veículos criados no servidor. |

---

## 4. Detecções (`config/sv_detections.lua`)

```lua
Config.Detections = {
    ['Weapon Spawn 12'] = true,   -- ban imediato
    ['Weapon Spawn 10'] = 2,      -- ban após 2 detecções
    ['Spawn de Objeto']  = false, -- apenas log
}
```

- `true` → ban na primeira detecção.
- `number` → ban após essa quantidade de detecções (o contador zera a cada 50 segundos).
- `false` ou ausente → apenas registra no webhook `suspicious`, sem ação.


Bans podem ser desligados globalmente com a convar `set likizao_enable_ban 0` (padrão `1`).

Chaves opcionais extras que você pode adicionar ao config:

| Chave | Finalidade |
|-----|---------|
| `Config.DefaultBucket` | O bucket em que seus jogadores normalmente ficam. Quando definido como `0`, **qualquer** bucket maior que 0 desativa a checagem de armas para aquele jogador. Quando definido como outro valor (ou deixado em branco), o limite é `1000000` (veja a seção 5). |
| `Config.ObjectsWhitelist` | Whitelist extra de objetos mesclada ao módulo de objetos na inicialização, no mesmo formato da seção 7 (`[modelo] = quantidade`, modelo como hash ou string). |
| `Config.Locales` | `[nome_da_deteccao] = "nome traduzido"`, aplicado ao texto de log/notificação. |
| `Config.SendLog(type, user_id, src, reason, additionalData)` | Defina para assumir o logging por completo; o embed padrão do Discord é então ignorado. `type` é `'suspicious'` ou `'banned'`. |

### `Config.ReportHandler(src, reason, additionalData)`

Chamada antes de tudo em todo report. **Retorne `false` para descartar o report** (sem log,
sem contagem, sem ban). Use para bypass de staff, whitelist de eventos, etc.

### `Config.NotifyAdmins(user_id, src, report_type, report_reason)`

Chamada depois do log. `report_type` é `'suspicious'` ou `'banned'`.

### `Config.BanUser(user_id, src, identifiers)`

Sua implementação de ban. `identifiers` é a tabela bruta de `GetPlayerIdentifiers(src)`. O
jogador é desconectado com `Config.DisconnectMessage` logo após essa chamada.

---

## 5. Armas

### Dar uma arma vs. apenas liberá-la

São duas coisas diferentes que você pode fazer, e essa é a maior fonte de confusão:

**`exports.likizao_ac:giveWeapons(src, weapons)` — dá a arma E a libera.**

```lua
exports.likizao_ac:giveWeapons(source, {
    ['WEAPON_PISTOL'] = 250,                                        -- só munição
    ['WEAPON_CARBINERIFLE'] = { ammo = 120, isHidden = false, bForceInHand = true },
})
```

O ped realmente recebe a arma (`GiveWeaponToPed`) e ela é registrada como autorizada.
As chaves aceitam nome de arma ou hash; o valor é a quantidade de munição ou uma tabela.

**`TriggerEvent('likizao_ac:setWeapons', src, weapons)` — apenas libera, não dá nada.**

```lua
TriggerEvent('likizao_ac:setWeapons', source, {
    ['WEAPON_PISTOL'] = true,
    ['WEAPON_CARBINERIFLE'] = true,
})
```

Isso **substitui** a lista de armas autorizadas do jogador sem tocar no ped. Use quando o seu
inventário já entrega a arma no client e você só precisa que o anticheat pare de reportá-la.
Para adicionar uma arma sem apagar a lista, use:

```lua
TriggerEvent('likizao_ac:setPlayerWeapon', source, 'WEAPON_PISTOL', 250)
```

Outros exports de armas:

| Export | Descrição |
|--------|-------------|
| `exports.likizao_ac:removeWeapons(src)` | Remove todas as armas do ped (`RemoveAllPedWeapons`). |
| `exports.likizao_ac:addAmmo(src, _, weapon, newValue)` | Define a munição daquela arma. O segundo argumento é ignorado (mantido por compatibilidade). |
| `exports.likizao_ac:SetWeaponsAlias(aliasTable)` | Substitui a tabela de aliases usada para mapear hashes de armas customizadas/skin para a arma base: `[hash] = "WEAPON_BASE"` ou `[hash] = { "WEAPON_A", "WEAPON_B" }`. Aliases dos resources `skins` e `skin-weapon` são carregados automaticamente quando esses resources existem. |

### Routing buckets e a checagem de armas

A validação de dano de arma é ignorada dependendo do routing bucket de quem atira:

- Se `Config.DefaultBucket == 0`: qualquer bucket **> 0** pula a checagem.
- Caso contrário: qualquer bucket **> 1000000** pula a checagem. Essa é a forma recomendada de
  rodar minigames, arenas, estandes de tiro ou qualquer evento customizado — coloque os
  jogadores em um bucket acima de 1000000 e a proteção de armas é ignorada para eles.


---

## 6. Eventos para autorizar ações

Todos estes são `TriggerEvent` do **lado servidor** (não são net events, então um cheater não
consegue dispará-los pelo client).

### Veículos

```lua
-- Autoriza um modelo para um jogador, opcionalmente restrito a uma posição
TriggerEvent('likizao_ac:onVehicleSpawn', { src = source, name = 'adder', position = coords })
TriggerEvent('likizao_ac:onSpawnVehicle', { src = source, name = 'adder' })

-- Libera coordenadas: qualquer veículo criado a até 30m destes pontos é aceito
TriggerEvent('likizao_ac:setCoordsBypass', { vec3(x, y, z), vec3(x2, y2, z2) })
```

`exports.likizao_ac:setSpawnClient(src, model)` faz o mesmo que `onSpawnVehicle` e ainda
pré-autoriza o modelo de objeto correspondente.

**Spawns no servidor.** Veículos criados com `CreateVehicle` no servidor não têm dono no
client, então com `--enable-vehicle-check` eles são aceitos sem precisar ser anunciados — os
eventos acima só são necessários para veículos que o **client** cria. Se veículos criados no
servidor chegarem a ser deletados ou reportados (por exemplo quando `--set-population` também
está ativa), ligue `--canary`, que trata esses spawns para você.

### Peds

```lua
-- Permite que um jogador crie um modelo de ped por `ttl` segundos (padrão 30)
TriggerEvent('likizao_ac:allowPedModel', source, 'a_m_y_business_01', 30)
TriggerEvent('likizao_ac:allowPedModel', source, { 'model_a', 'model_b' }, 60)
TriggerEvent('likizao_ac:allowPedModel', source, '*', 15)  -- qualquer modelo de ped
```

### Forçando um report pelos seus próprios scripts

```lua
TriggerEvent('AC:ForceBan', source, {
    reason = 'Minha detecção customizada',
    additionalData = 'informação extra',
    forceBan = true,
})
```

O anticheat também emite `AC:Suspect` com `{ reason, user_id }` sempre que acontece um report
que não gera ban, e `likizao:PropManager:DeleteEntitys` (`user_id`, entidades, isMassDelete)
quando um admin deleta entidades — conecte-se a esses eventos para o seu próprio log.

---

## 7. Liberando objetos no config

O controle de objetos só roda com `--enable-custom-object` ativa. A whitelist pode ser
estendida pelo config com `Config.ObjectsWhitelist` ou em tempo de execução com os exports
abaixo.

```lua
Config.ObjectsWhitelist = {
    ['prop_cs_phone_01'] = 1,
    [GetHashKey('prop_beer_box_01')] = 1,
    ['cdev_pets_bowl1_a'] = 999,
}
```

**O número é a quantidade máxima daquele objeto que um único jogador pode ter ao mesmo tempo.**

- `= 1` → o jogador pode ter **apenas um** daquele objeto por vez. Um segundo criado é tratado
  como abuso por duplicação.
- `> 1` (ex.: `2`, `10`, `999`) → **várias instâncias ao mesmo tempo são permitidas**, nenhuma
  checagem de duplicidade é feita. Use para props como camas de pet, cones, luzes ou qualquer
  coisa que um jogador legitimamente posicione mais de uma vez.

Valor `0` ou entrada ausente significa que o objeto **não** está liberado: ele é cancelado e o
jogador é reportado com `Spawn de Objeto`.


Exports em tempo de execução:

| Export | Descrição |
|--------|-------------|
| `exports.likizao_ac:RegisterModel(model, amount)` | Libera um modelo. `model` aceita hash ou nome. Mesma regra de `1` vs. `> 1`. |
| `exports.likizao_ac:RegisterModels({ [model] = amount, ... })` | Libera vários modelos de uma vez. |
| `exports.likizao_ac:IsObjectAllowed(owner, model, coords)` | Retorna `true`/`false` usando as mesmas regras (whitelist + 30m + checagem de duplicidade). |
| `exports.likizao_ac:SetBypass(src, 'entities')` | O jogador passa a ser totalmente ignorado pelo módulo de objetos/peds. Passe `nil` para remover. |
| `exports.likizao_ac:setUserBypass(src, true)` | Bypass global: todo report daquele jogador é descartado. Passe `false` para remover. |
| `exports.likizao_ac:DisableBan()` | Desativa o ban dentro do módulo de entidades (apenas logs). |

---

## 8. Outros exports

| Export | Descrição |
|--------|-------------|
| `exports.likizao_ac:setValidation(detection_name, callback)` | Registra uma validação extra para uma detecção (seção 8.1). |
| `exports.likizao_ac:removeValidation(detection_name)` | Remove a validação. Retorna `false` se não havia nenhuma registrada. |
| `exports.likizao_ac:getValidations()` | Retorna a tabela de validações registradas no momento. |
| `exports.likizao_ac:registerReportOverride(detection_name, callback)` | Reescreve ou descarta um report antes dele ser processado (seção 8.2). |
| `exports.likizao_ac:overrideConfig({ ['Detection'] = value })` | Altera entradas de `Config.Detections` em tempo de execução (seção 8.3). |
| `exports.likizao_ac:Report(src, reason, forceBan, additionalData)` | Reporta um jogador (um report por motivo por ciclo). |
| `exports.likizao_ac:ReportAfterCount(src, reason, maxCount, ban, additionalData)` | Reporta somente após `maxCount` ocorrências. |

### Onde cada hook roda

Todo report passa por este pipeline, nesta ordem:

1. `Config.ReportHandler(src, reason, additionalData)` — retorne `false` para descartá-lo.
2. Callback de **`setValidation`** daquela detecção — retorne `true` para descartá-lo.
3. Callback de **`registerReportOverride`** daquela detecção — retorne `false` para descartá-lo,
   ou uma tabela para reescrever o report.
4. `Config.Detections[reason]` (ou o que **`overrideConfig`** tiver definido por último) decide
   entre log e ban.

### 8.1 `setValidation`

Registra uma checagem por detecção que decide, no momento do report, se aquele jogador deve
ser ignorado. **Retornar `true` significa "isso é legítimo, descarte o report".**

> O callback precisa ser passado entre resources (uma referência de função do CFX), então
> chame este export a partir de **outro resource**, não de dentro do `likizao_ac`. As
> validações são removidas automaticamente quando o resource que as registrou para.

```lua
-- Chamado como callback(src, ...) onde os argumentos extras dependem da detecção.
exports.likizao_ac:setValidation('Weapon Spawn', function(src, weaponHash)
    -- 'EXPLOSION' é passado no lugar de um hash quando a checagem vem de um
    -- evento de explosão/projétil (somente com --enable-explosions).
    if weaponHash == 'EXPLOSION' then
        return isPlayerInEventZone(src)
    end

    -- Caso contrário weaponHash é o hash da arma com sinal, já resolvido pela tabela de aliases.
    return myInventory.hasWeapon(src, weaponHash)
end)
```

Qualquer nome de detecção funciona, não só `Weapon Spawn`; para todas as outras detecções o
callback recebe apenas o source:

```lua
exports.likizao_ac:setValidation('Spawn de Objeto', function(src)
    return isStaffOnDuty(src)
end)

exports.likizao_ac:removeValidation('Spawn de Objeto')
```

Só pode existir uma validação por detecção — registrar uma segunda sobrescreve a primeira e
imprime um aviso no console.

### 8.2 `registerReportOverride`

Roda depois da validação e permite **alterar** o report em vez de apenas aceitá-lo ou
rejeitá-lo. O callback recebe `(src, report)`, onde `report` é
`{ reason, additionalData, forceBan }`, e deve retornar:

- `false` (ou `nil`) → o report é descartado;
- uma tabela → seus campos são mesclados ao report antes dele ser logado/banido.

```lua
exports.likizao_ac:registerReportOverride('TASK_SPAM', function(src, report)
    local task = GetPedScriptTaskCommand(GetPlayerPed(src))

    if task == -129606530 then
        return false -- ignorar?
    end

    if task == -874453556 then
        return {                       -- mesma detecção, nome diferente nos logs
            reason = 'Crashar Players (02)',
            additionalData = '',
        }
    end

    return { additionalData = 'Task: ' .. task }  -- mantém o report, só enriquece o log
end)
```

Retornar `{ forceBan = true }` promove aquele report específico a ban imediato,
independentemente do que `Config.Detections` diz.

### 8.3 `overrideConfig`

Altera `Config.Detections` em tempo de execução, com a mesma semântica do arquivo de config
(`true` = ban imediato, número = ban após N detecções, `false` = apenas log). Útil para
suavizar detecções durante um evento e restaurá-las depois.

```lua
exports.likizao_ac:overrideConfig({
    ['Weapon Spawn']   = false,  -- apenas log
    ['Spawn de Objeto'] = 3,     -- ban após 3 detecções
    ['Super Soco (1)']  = true,  -- ban imediato
})
```

Cada alteração é impressa no console do servidor.

### 8.4 Reports customizados do seu próprio resource

```lua
exports.likizao_ac:Report(src, 'Minha Detecção', false, 'informação extra')
exports.likizao_ac:ReportAfterCount(src, 'Minha Detecção', 3, true, 'informação extra')
```

`Report` dispara apenas uma vez por `src`+`reason` por ciclo. `ReportAfterCount` só reporta
após `maxCount` ocorrências, e `ban` decide se esse report final bane o jogador.

---

## 9. Comandos

### Comandos de jogador/staff (configuráveis em `config/shared_commands.lua`)

```lua
Config.Wall        = { command = 'wall',        permission = 'player.wall',        outline = true, opacity = 246 }
Config.PropManager = { command = 'propmanager', permission = 'player.propmanager' }
Config.CleanArea   = { command = 'cleanarea',   permission = 'player.cleanarea' }
```

| Comando | Permissão | Descrição |
|---------|-----------|-------------|
| `/wall` | `player.wall` | Liga/desliga a wall de ESP (nomes, empregos, tags de admin/novato, contadores de detecção). |
| `/propmanager` | `player.propmanager` | Abre a UI do prop manager para inspecionar e deletar entidades em rede e seus donos. |
| `/cleanarea` | `player.cleanarea` | Deleta peds e objetos num raio de 60m. Passando qualquer argumento (ex.: `/cleanarea veh`) também deleta veículos num raio de 40m. |
| `/wallconfig` | — (client, afeta só a wall de quem chamou) | `linhas`, `nome`, `source`, `logs`, `killer`, `distancia <n>`. As configurações são salvas por client. |

Definir `Config.Wall`, `Config.PropManager` ou `Config.CleanArea` como `nil` desativa aquele
módulo por completo.

### Comandos do console do servidor

| Comando | Descrição |
|---------|-------------|
| `likizao_toggle_veh_check` | Alterna o módulo de checagem de veículos entre os comportamentos v1 e v2. |
| `likizao_ac_debug_vehicle` | Liga/desliga o log detalhado do módulo de veículos no servidor. |
| `likizao_block_object <hash>` | Bloqueia um hash de modelo na hora e deleta todas as instâncias existentes dele. |

### Convars

| Convar | Padrão | Descrição |
|--------|---------|-------------|
| `likizao_enable_ban` | `1` | Defina como `0` para registrar detecções sem nunca banir. |

---

## 10. Primeira configuração recomendada

1. Escolha suas flags com "De quais flags o meu servidor precisa?" abaixo, e deixe
   `Config.Detections` vazio (apenas a linha de comentário obrigatória). Qualquer detecção que
   não esteja listada ali é apenas log, então ninguém é banido enquanto você ainda está
   ajustando.
2. Preencha `Config.Functions` e confirme que `/wall` mostra os nomes corretos — isso prova que
   `getUserId`, `getIdentity` e `hasPermission` estão ligados corretamente.
3. Ative um módulo por vez (`--enable-custom-object`, depois `--enable-vehicle-check`),
   acompanhando o webhook `suspicious` em busca de falsos positivos.
4. Autorize seus próprios scripts com os eventos da seção 6 e a whitelist de objetos da
   seção 7 até os logs ficarem limpos.
5. Só então mude as detecções em que você confia para `true` ou para um limite numérico.

### De quais flags o meu servidor precisa?

Responda estas quatro perguntas e você tem o seu `Config.Flags`.

Comece com `--heartbeat-v2`, que é recomendada em todo servidor, e depois responda o resto.

**Você usa população ambiente (trânsito de IA, pedestres, NPCs de cenário)?**
Adicione `--set-population`. Sem ela todo ped que não é jogador é cancelado, então um servidor
com vida ambiente vai parecer completamente vazio. Se o seu servidor não tem nenhuma população
de IA (peds e trânsito desativados), deixe de fora — a proteção fica mais rígida assim.

**Quem cria os seus veículos?**

- **Client e servidor misturados** (garagens, menus de admin, empregos no lado client): use
  `--enable-vehicle-check`. Os spawns do client precisam ser anunciados com os eventos da
  seção 6, e os spawns do servidor são aceitos automaticamente, então essa flag sozinha
  cobre os dois casos.
- **Apenas no servidor** (todo veículo vem de `CreateVehicle` no servidor): use
  `--enable-sv.vehicle-spawn`, que confirma cada veículo em vez de confiar nele. Não use se
  alguma parte do seu servidor ainda cria veículos pelo client.

De qualquer forma, ligue `--canary` se tiver problemas com veículos criados no servidor.

**Os jogadores posicionam props (itens de inventário, pets, varas de pesca, placas, objetos de trabalho)?**
Adicione `--enable-custom-object` e libere esses modelos como descrito na seção 7. Essa é a
flag que anda junto com a de veículos em quase todo servidor.

**Você usa routing buckets bastante (instâncias, casas, minigames)?**
Adicione `--disable-player-constraints` para as checagens de arma pararem de brigar com os seus
buckets, e lembre que qualquer bucket acima de 1000000 ignora a proteção de armas por completo
(seção 5).

Um servidor de roleplay típico com população ambiente, veículos no client e no servidor, e
props termina com:

```lua
Config.Flags = {
    '--heartbeat-v2',
    '--set-population',
    '--enable-vehicle-check',
    '--enable-custom-object',
}
```
