Referência de exports

Chamar um export#

Chame exports de servidor a partir dos scripts de servidor do seu resource e exports de cliente a partir dos scripts de cliente dele. O nome do resource tem hífen, então use sempre a forma com colchetes exports['tosun-ac']. A forma exports.tosun-ac não é Lua válido.

• Passe os ids de servidor como números. Vários exports usam o id diretamente como chave de tabela.
• Alguns exports executam uma query síncrona no banco de dados e fazem yield. Chame-os a partir de uma thread ou de um handler de evento: getBans, getBanInfo, GetDetections, isAdmin e as outras verificações de staff, IsExemptFromPunish, ForensicLinksOf e refreshPanelWhitelist. scanAllResources e scanSingleResource também fazem yield.
• Um export protegido que rejeita o seu resource retorna false, mesmo que normalmente retorne nil.
• Alguns exports só existem quando o recurso correspondente está ativado (veja Exports que dependem de recursos). Chamar um export que não está registrado gera um erro, então envolva essas chamadas em pcall.
• Vários exports não aparecem nas listas de exports do fxmanifest.lua (por exemplo MarkTeleport, punish e AllowWeapon). Essas listas são só informativas; os exports funcionam.
• As tabelas abaixo dizem Sim na última coluna quando o resource que chama precisa ser confiável. Veja Resources confiáveis.

-- script de servidor no seu próprio resource
local status = exports['tosun-ac']:GetIntegrationStatus()
if not status.trusted then
    print(status.hint) -- a linha a adicionar no server.cfg
end

-- avise o AC sobre um teleporte e depois mova o jogador
exports['tosun-ac']:MarkTeleport(src, 8000)
SetEntityCoords(GetPlayerPed(src), x, y, z)

-- script de cliente no seu próprio resource
exports['tosun-ac']:SetExempt(true, 60000, 'my_menu')

• Guia de integração
• Configuração do servidor

Resources confiáveis#

Exports marcados com Sim na coluna de confiança alteram isenções, direitos de staff, bans, vida do jogador, armas ou inventário, quarentena, resources e assinaturas, ou o servidor inteiro. Eles só aceitam chamadas de um resource confiável. Uma chamada rejeitada não faz nada e retorna false.

Quem chama é confiável quando é o console do servidor, o próprio tosun-ac, um resource listado em ts.ExportCallerWhitelist na config, ou um resource listado na convar tosun_ac_trusted_resources. A lista padrão da config é qbx_core, qb-core, es_extended, ox_inventory e ox_lib.

Prefira a convar. Ela fica no server.cfg e sobrevive às atualizações do AC, enquanto edições no arquivo de config podem se perder quando você atualiza o AC. Separe os nomes com vírgulas ou espaços. A lista de confiança fica em cache por 10 segundos, então uma mudança feita em tempo de execução vale em até 10 segundos.

Na primeira rejeição de cada par de resource e export, o AC imprime um aviso no console do servidor com a linha exata a adicionar no server.cfg e grava uma linha nos logs do painel. A linha de log do painel é sempre em turco.

Modo de auditoria: com ts.EnforceExportCallerWhitelist = false, chamadas não confiáveis rodam e cada par de resource e export é impresso uma vez no console do servidor (sem linha de log no painel). O padrão é true. Use o modo de auditoria só durante o setup, para ver quais scripts chamam o quê.

Rode tosunac_integration no console do servidor para imprimir o modo de aplicação, os resources confiáveis com a origem de cada um (config ou convar) e as últimas 20 chamadas rejeitadas. A partir de um script, chame GetIntegrationStatus().

A confiança também remove o orçamento do MarkTeleport: resources confiáveis podem marcar teleportes sem o limite de tempo por jogador.

O Tosun AC também registra exports e eventos de rede internos para o seu próprio funcionamento (bridge do painel, assinatura, varredura, licenciamento, processamento em lote). Eles não fazem parte desta referência e não são uma API suportada. Alguns são protegidos pela verificação de confiança ou por uma verificação interna de quem chama. Não os chame.

# server.cfg
set tosun_ac_trusted_resources "my-housing,my-clothing"

• Configuração do servidor
• Comandos de console

Integração e isenções#

Exports de servidor que avisam o AC sobre ações legítimas nos seus scripts e informam se um jogador está isento.

Escolher uma isenção#

Use a isenção mais restrita que cobre o seu script. Várias isenções dividem a mesma marca de isenção do cliente, então uma pode encerrar outra: ClearArea com um nome de área zera a marca que SetPlayerExempt, MarkTeleport e BypassDetection também definem.

Staff e permissões#

Leia e altere quem o AC trata como staff. As verificações de staff podem consultar o banco de dados, então chame-as a partir de uma thread ou de um handler de evento.

isAdmin retorna true para: uma concessão manual via addAdmin; as ACEs txadmin, tx.admin, txadmin.menu, txadmin.advanced, command.txadmin, command.ts, command.ban, command.kick, tosun.admin, ts.admin e qualquer uma em ts.AdminBypassAces; os principals group.admin, group.superadmin, group.moderator e group.god; command.kick/ban/resources/restart quando ts.txAdminAuth está ligado; identificadores em admins.lua, ts.AdminMenu.allowedIds e ts.AdminBypassIdentifiers; e concessões do painel no banco de dados. Uma ACE que também é concedida a builtin.everyone não conta.

isAdmin e addAdmin são registrados duas vezes no código-fonte. As versões em anticheat_server.lua carregam por último e são as que rodam; esta referência descreve essas.

Whitelist de jogadores e áreas#

Whitelist por id de servidor, whitelist por identificador e áreas nomeadas. As listas de runtime ficam só na memória e se perdem no restart; a whitelist do painel é separada.

Punições e bans#

Puna jogadores pelo pipeline do AC, bana jogadores offline e leia bans. Todos os exports de escrita aqui exigem confiança.

• Eventos

Como o punish() escolhe a punição#

punish(), ban() e BanPlayerExt() dividem um único pipeline. Esta é a ordem que ele segue.

1. A staff é pulada quando ts.AdminBypassDetections não é false. Jogadores com uma isenção ativa ou na whitelist de runtime ou do painel são pulados. ts.Debug desliga esses pulos. Chamadas puladas não fazem nada e não registram nada.
2. O jogador precisa estar online. Caso contrário, um erro é impresso no console do servidor e nada acontece.
3. Punição: um argumento punishment válido vence. Caso contrário, ts.DetectionPunishments[configKey], depois o alias dele, depois a chave da detecção, depois ts.punishType, depois BAN.
4. Todo resultado dispara o evento de servidor ts_anticheat:playerBanned, envia uma mensagem no chat quando ts.chatMessages está ligado, adiciona uma violação na nuvem e grava o log do AC e o log ao vivo.
5. LOG: envia o log com captura de tela para o Discord.
6. KICK: verifica a staff de novo, independentemente de ts.AdminBypassDetections, então a staff nunca é expulsa. Depois envia o log com captura de tela e derruba o jogador.
7. BAN: insere o ban com uma duração de ts.BanDurations em horas (configKey, alias, chave da detecção, prefixo e por fim default; 0 = permanente) e bannedBy 'anticheat:' mais a chave. Dispara ts_anticheat:banCommitted, avisa o painel e derruba o jogador (com nova tentativa depois de 3 s).

exports['tosun-ac']:punish(src, 'Money exploit', nil, 'my_shop_exploit', 'BAN')

Moderação de um único jogador#

Agem sobre um jogador. Leia a coluna de confiança com atenção: vários destes não têm verificação de confiança.

Ações para o servidor inteiro#

Ações que afetam todos os jogadores ou todas as novas conexões.

Quarentena e proteção de payload#

Isole um jogador suspeito e proteja os seus próprios eventos de rede contra payloads de crash e spam.

RegisterNetEvent('myres:buy', function(data)
    local src = source
    if not exports['tosun-ac']:RateLimit(src, 'myres:buy', 5, 10000) then return end
    if exports['tosun-ac']:crashGuardReject(src, data) then return end
    -- processa a compra
end)

Jogadores e detecções#

Consulte jogadores, identificadores, bans por jogador, pontuações de ameaça e contas vinculadas. Alguns resultados contêm dados pessoais, como endereços IP.

Notificações e idioma#

Envie notificações de celular e use as tabelas de tradução do AC. phoneNotify e phoneNotifyAdmins só existem quando ts.AdminMenu.enable está ligado.

Capturas de tela#

Solicite capturas de tela de jogadores para o painel. Os exports do AC que gravam logs são internos e não estão listados aqui.

• Configuração do painel

Status e diagnóstico#

Leia o estado do AC para dashboards e verificações de saúde.

Resource guard#

Leia e altere a baseline de resources aprovados. Todos estes exports são registrados mesmo quando o resource guard está desativado.

• Comandos de console

Varreduras de assinaturas, backdoors e eventos#

Execute varreduras e gerencie assinaturas, exceções de falso positivo e skips de escrow. As varreduras podem demorar; rode-as a partir de uma thread.

Eventos honeypot#

Transforme nomes de eventos em armadilhas ou libere-os. Os dois gravam em ac_protected_events e recarregam do banco de dados.

Exports que dependem de recursos#

Estes exports só são registrados quando o recurso correspondente está ligado. Se o recurso estiver desligado, chamá-los gera um erro.

• Config e desempenho

Exports do lado do cliente#

Chame estes a partir de scripts de cliente. Qualquer resource de cliente pode chamá-los; não há verificação de confiança. Eles só afetam as verificações naquele cliente e nunca mudam a aplicação das regras no servidor.

-- seleção de personagem
exports['tosun-ac']:SetSpawned(false)
-- ... o jogador escolhe um personagem ...
exports['tosun-ac']:SetSpawned(true)

Exports em JavaScript#

O Tosun AC registra alguns exports em JavaScript no servidor para a varredura de resources e a verificação de licença. Eles são internos, não passam pela verificação de resource confiável e não são uma API suportada. Não os chame. Não existem exports públicos em JavaScript.

Arquivos de bridge: setup#

Os arquivos de bridge opcionais em tosun-ac/bridge dão ao seu resource uma tabela global TosunAC com helpers curtos. Eles chamam os exports dentro de pcall, então o seu script continua rodando quando o AC está parado. O AC vê o seu resource como quem chama.

1. Adicione a bridge ao fxmanifest.lua do seu resource: server_script '@tosun-ac/bridge/tosun_ac_server.lua' e, se precisar, client_script '@tosun-ac/bridge/tosun_ac_client.lua'.
2. Se a pasta do AC tiver outro nome, adicione setr tosun_ac_resource "folder-name" ao server.cfg. Use setr: a bridge do cliente lê essa convar no cliente.
3. Opcional: set tosun_ac_bridge_server_ms (padrão 60000), set tosun_ac_bridge_cooldown_ms (padrão 750, 0 desativa) e setr tosun_ac_bridge_client_ms (padrão 60000).
4. Para isenções completas no servidor, adicione o seu resource a tosun_ac_trusted_resources. Sem confiança, TosunAC.PlayerExempt recorre a uma isenção leve e imprime uma dica única no console do servidor (o texto da dica é em turco).

-- fxmanifest.lua do seu resource
server_script '@tosun-ac/bridge/tosun_ac_server.lua'
client_script '@tosun-ac/bridge/tosun_ac_client.lua'

# server.cfg
setr tosun_ac_resource "tosun-ac"
set tosun_ac_trusted_resources "my-resource"

-- script de servidor
local ok, mode = TosunAC.PlayerExempt(src, 'long', 'clothing')
-- mode é 'full' (confiável) ou 'soft' (só movimento, máx. 15 s)

• Guia de integração
• Configuração do servidor

Bridge: helpers do servidor#

Definidos por bridge/tosun_ac_server.lua dentro do seu resource. Presets: SHORT 30000, MEDIUM 60000, LONG 120000, XL 180000 ms (TosunAC.Presets). TosunAC.Version é '1.2'.

Bridge: helpers do cliente#

Definidos por bridge/tosun_ac_client.lua dentro do seu resource. Eles envolvem o export de cliente SetExempt, então dão alívio só do lado do cliente.

Exports que qualquer resource pode chamar#

Estes exports não têm verificação de confiança e têm efeitos colaterais. Qualquer resource do servidor pode chamá-los. Rode só resources em que você confia; lembre que qualquer resource do servidor já pode expulsar jogadores ou disparar eventos de cliente pelos natives do FiveM.

• MarkTeleport: isenção de movimento, limitada pelo orçamento por jogador.
• spectatePlayer: teleporta um jogador e concede, a cada chamada, uma isenção de movimento de 15 s sem orçamento.
• NoteCloudViolation: aumenta a pontuação de ameaça de um jogador e pode reportar a license ao banco de dados de ameaças entre servidores.
• warnPlayer e mutePlayer: gravam registros de aviso e de mute.
• freezePlayer e slayPlayer: agem diretamente sobre um jogador.
• crashGuardReject: adiciona strikes que podem expulsar ou banir.
• screenCapture, v6ScreenWatchRequest e RequestShieldScreenshot: solicitam capturas de tela.
• rescanResources, scanAllResources, scanSingleResource, tsScanBackdoors e tsScanEvents: iniciam varreduras. scanAllResources pode bloquear e tsScanBackdoors pode parar resources quando o bloqueio automático ou a quarentena automática estão ligados.
• applyWeatherWithFramework e applyTimeWithFramework: mudam o clima e o horário para todos.
• invalidateSignatureCache, reloadSignatureExceptions, reloadSignatureScanCaches e refreshPanelWhitelist: recarregam caches.
• setPlayerLocale e unmutePlayer: mudam o estado do jogador.
• phoneNotify e phoneNotifyAdmins: enviam mensagens de celular ou de chat para os jogadores.

Nomes legados e enganosos#

Estes exports ainda funcionam, mas os nomes deles ou a documentação antiga sugerem algo que eles não fazem.

• Guias antigos (INTEGRATION.md da 9.6.6, CONFIG-EXPORTS-MULTILANG.md da 8.6.1 e o stub de redirecionamento TOSUN-AC-EXPORTS.md) estão desatualizados. Onde houver diferença, esta referência segue o código da 9.6.15.
• SetPlayerExempt, PausePlayerDetections, PauseAllDetections, BypassDetection, AddWhitelist, RemoveWhitelist, WhitelistArea, ClearArea, addAdmin, fakeTriggerTrap e fakeTriggerWhitelist exigem um resource confiável, embora o CONFIG-EXPORTS-MULTILANG.md os liste sem essa exigência.
• A lista padrão de confiáveis é qbx_core, qb-core, es_extended, ox_inventory e ox_lib. O INSTALLER-READY.md omite qb-core e es_extended.
• GetIntegrationStatus() também retorna um campo version.
• punish, ban, BanPlayerExt, KickPlayer, offlineBan e offlineBanByLicense exigem um resource confiável.
• ban() e BanPlayerExt() seguem ts.punishType e ts.BanDurations['default'], então nem sempre são permanentes.
• KickPlayer não verifica isenções. No pipeline de punição, KICK sempre poupa a staff, enquanto BAN e LOG seguem ts.AdminBypassDetections.
• Durante uma isenção de cliente, a maioria das verificações do cliente é pulada por completo. Só as detecções que ainda chegam ao caminho de ban viram entradas LOG com a tag [exempt].
• NoteCloudViolation só bloqueia entradas futuras com ts.cloudBridge.threatIntelAction = 'kick'.
• Com a bridge do cliente, as convars tosun_ac_resource e tosun_ac_bridge_client_ms precisam ser definidas com setr, não com set.
• O teto por chamada do MarkTeleport (ts.Integration.markTeleportMaxMs) vale também para quem chama confiável. Só o orçamento de 180 s a cada 10 minutos é para quem chama não confiável.