Documentação

Instalação e integração

Guia de instalação e integração do Likizão AC na sua base.

Baixar .md
Versão

01Instalaçã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.


02Funções do frameworkconfig/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.

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

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

hasPermissionConfig.Functions.hasPermission(user_id, permission)

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

getUsersByPermissionConfig.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).

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

getUserGroupByTypeConfig.Functions.getUserGroupByType(user_id, 'job')

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

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

LabelsConfig.Labels

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


03Flagsconfig/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.

04Detecçõesconfig/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'.

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

NotifyAdminsConfig.NotifyAdmins(user_id, src, report_type, report_reason)

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

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


05Armas

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.

06Eventos 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.


07Liberando 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).

08Outros 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.1setValidation

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.2registerReportOverride

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.3overrideConfig

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.4Reports 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.


09Comandos

Comandos de jogador/staffconfig/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.

10Primeira 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',
}

Traga o Likizão
pra sua cidade

Chama no Discord e conta como está a sua base hoje. A gente analisa e diz o que dá pra fazer — sem enrolação de vendedor.