Référence des exports

Appeler un export#

Appelez les exports serveur depuis les scripts serveur de votre ressource et les exports client depuis ses scripts client. Le nom de la ressource contient un tiret : utilisez donc toujours la forme avec crochets exports['tosun-ac']. La forme exports.tosun-ac n'est pas du Lua valide.

• Passez les id serveur sous forme de nombres. Plusieurs exports utilisent l'id directement comme clé de table.
• Certains exports lancent une requête synchrone en base et cèdent la main (yield). Appelez-les depuis un thread ou un gestionnaire d'événement : getBans, getBanInfo, GetDetections, isAdmin et les autres vérifications du staff, IsExemptFromPunish, ForensicLinksOf et refreshPanelWhitelist. scanAllResources et scanSingleResource cèdent aussi la main.
• Un export protégé qui refuse votre ressource renvoie false, même s'il renvoie normalement nil.
• Certains exports n'existent que lorsque leur fonctionnalité est activée (voir Exports dépendant d'une fonctionnalité). Appeler un export non enregistré lève une erreur : entourez donc ces appels d'un pcall.
• Plusieurs exports manquent dans les listes d'exports de fxmanifest.lua (par exemple MarkTeleport, punish et AllowWeapon). Ces listes sont seulement informatives ; les exports fonctionnent.
• Les tableaux ci-dessous indiquent Oui dans la dernière colonne quand la ressource appelante doit être de confiance. Voir Ressources de confiance.

-- script serveur dans votre propre ressource
local status = exports['tosun-ac']:GetIntegrationStatus()
if not status.trusted then
    print(status.hint) -- la ligne server.cfg à ajouter
end

-- signaler une téléportation à l'AC, puis déplacer le joueur
exports['tosun-ac']:MarkTeleport(src, 8000)
SetEntityCoords(GetPlayerPed(src), x, y, z)

-- script client dans votre propre ressource
exports['tosun-ac']:SetExempt(true, 60000, 'my_menu')

• Guide d'intégration
• Configuration du serveur

Ressources de confiance#

Les exports marqués Oui dans la colonne de confiance modifient les exemptions, les droits staff, les bans, la santé, les armes ou l'inventaire des joueurs, la quarantaine, les ressources et les signatures, ou le serveur entier. Ils n'acceptent que les appels d'une ressource de confiance. Un appel refusé ne fait rien et renvoie false.

Un appelant est de confiance quand il s'agit de la console du serveur, de tosun-ac lui-même, d'une ressource listée dans ts.ExportCallerWhitelist dans la config, ou d'une ressource listée dans la convar tosun_ac_trusted_resources. La liste par défaut de la config est qbx_core, qb-core, es_extended, ox_inventory et ox_lib.

Préférez la convar. Elle se trouve dans server.cfg et survit aux mises à jour de l'AC, alors que les modifications du fichier de config peuvent être perdues lors d'une mise à jour. Séparez les noms par des virgules ou des espaces. La liste de confiance est mise en cache 10 secondes : une modification faite en cours d'exécution s'applique donc dans les 10 secondes.

Au premier refus pour chaque couple ressource et export, l'AC affiche un avertissement dans la console du serveur avec la ligne exacte à ajouter à server.cfg, et écrit une ligne dans les logs du panel. La ligne de log du panel est toujours en turc.

Mode audit : avec ts.EnforceExportCallerWhitelist = false, les appels non fiables s'exécutent et chaque couple ressource et export est affiché une fois dans la console du serveur (sans ligne de log dans le panel). La valeur par défaut est true. N'utilisez le mode audit que pendant l'installation, pour voir quels scripts appellent quoi.

Lancez tosunac_integration dans la console du serveur pour afficher le mode d'application, les ressources de confiance avec leur source (config ou convar) et les 20 derniers appels refusés. Depuis un script, appelez GetIntegrationStatus().

La confiance supprime aussi le budget de MarkTeleport : les ressources de confiance peuvent marquer des téléportations sans la limite de temps par joueur.

Tosun AC enregistre aussi des exports et des événements réseau internes pour son propre fonctionnement (pont du panel, signature, analyse, licences, traitement par lots). Ils ne font pas partie de cette référence et ne constituent pas une API prise en charge. Certains sont protégés par la vérification de confiance ou par une vérification interne de l'appelant. Ne les appelez pas.

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

• Configuration du serveur
• Commandes console

Intégration et exemptions#

Exports serveur qui informent l'AC des actions légitimes de vos scripts, et qui indiquent si un joueur est exempté.

Choisir une exemption#

Utilisez l'exemption la plus étroite qui couvre votre script. Plusieurs exemptions partagent le même indicateur d'exemption client, si bien que l'une peut mettre fin à une autre : ClearArea avec un nom de zone réinitialise l'indicateur que SetPlayerExempt, MarkTeleport et BypassDetection définissent aussi.

Staff et permissions#

Lire et modifier qui l'AC considère comme staff. Les vérifications du staff peuvent interroger la base de données : appelez-les depuis un thread ou un gestionnaire d'événement.

isAdmin renvoie true pour : une attribution manuelle via addAdmin ; les ACE txadmin, tx.admin, txadmin.menu, txadmin.advanced, command.txadmin, command.ts, command.ban, command.kick, tosun.admin, ts.admin et ceux de ts.AdminBypassAces ; les principals group.admin, group.superadmin, group.moderator et group.god ; command.kick/ban/resources/restart quand ts.txAdminAuth est actif ; les identifiants de admins.lua, ts.AdminMenu.allowedIds et ts.AdminBypassIdentifiers ; et les autorisations du panel en base de données. Un ACE également accordé à builtin.everyone ne compte pas.

isAdmin et addAdmin sont enregistrés deux fois dans le code source. Les versions de anticheat_server.lua se chargent en dernier et sont celles qui s'exécutent ; cette référence décrit celles-ci.

Liste blanche des joueurs et zones#

Liste blanche par id serveur, liste blanche par identifiant et zones nommées. Les listes gérées à l'exécution ne vivent qu'en mémoire et sont perdues au redémarrage ; la liste blanche du panel est distincte.

Sanctions et bans#

Sanctionner des joueurs via le circuit de l'AC, bannir des joueurs hors ligne et lire les bans. Tous les exports d'écriture de cette section nécessitent la confiance.

• Événements

Comment punish() choisit la sanction#

punish(), ban() et BanPlayerExt() partagent un même circuit. Voici l'ordre qu'il suit.

1. Le staff est ignoré quand ts.AdminBypassDetections n'est pas false. Les joueurs avec une exemption active ou présents dans la liste blanche en mémoire ou celle du panel sont ignorés. ts.Debug désactive ces exclusions. Les appels ignorés ne font rien et ne journalisent rien.
2. Le joueur doit être en ligne. Sinon, une erreur est affichée dans la console du serveur et rien ne se passe.
3. Sanction : un argument punishment valide l'emporte. Sinon ts.DetectionPunishments[configKey], puis son alias, puis la clé de détection, puis ts.punishType, puis BAN.
4. Chaque issue déclenche l'événement serveur ts_anticheat:playerBanned, publie un message dans le chat quand ts.chatMessages est actif, ajoute une violation cloud et écrit le log de l'AC et le log en direct.
5. LOG : envoie le log de capture d'écran sur Discord.
6. KICK : revérifie le staff quel que soit ts.AdminBypassDetections, si bien que le staff n'est jamais expulsé. Envoie ensuite le log de capture d'écran et déconnecte le joueur.
7. BAN : insère le ban avec une durée tirée de ts.BanDurations en heures (configKey, alias, clé de détection, préfixe, puis default ; 0 = permanent) et bannedBy 'anticheat:' suivi de la clé. Déclenche ts_anticheat:banCommitted, prévient le panel et déconnecte le joueur (nouvelle tentative après 3 s).

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

Modération d'un seul joueur#

Agir sur un joueur. Lisez attentivement la colonne de confiance : plusieurs de ces exports n'ont aucune vérification de confiance.

Actions sur tout le serveur#

Actions qui affectent tous les joueurs ou toutes les nouvelles connexions.

Quarantaine et protection des données reçues#

Isoler un joueur suspect, et protéger vos propres événements réseau contre les payloads de crash et le 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
    -- traiter l'achat
end)

Joueurs et détections#

Rechercher des joueurs, des identifiants, les bans d'un joueur, des scores de menace et des comptes liés. Certains résultats contiennent des données personnelles comme des adresses IP.

Notifications et langue#

Envoyer des notifications téléphone et utiliser les tables de traduction de l'AC. phoneNotify et phoneNotifyAdmins n'existent que lorsque ts.AdminMenu.enable est actif.

Captures d'écran#

Demander des captures d'écran de joueurs pour le panel. Les exports d'écriture de logs de l'AC sont internes et ne sont pas listés ici.

• Configuration du panel

État et diagnostic#

Lire l'état de l'AC pour des tableaux de bord et des contrôles de santé.

Resource guard#

Lire et modifier la baseline des ressources approuvées. Tous ces exports sont enregistrés même quand le resource guard est désactivé.

• Commandes console

Scans de signatures, de backdoors et d'événements#

Lancer des scans et gérer les signatures, les exceptions de faux positifs et les exclusions escrow. Les scans peuvent prendre du temps ; lancez-les depuis un thread.

Événements honeypot#

Transformer des noms d'événements en pièges ou les libérer. Les deux exports écrivent dans ac_protected_events et rechargent depuis la base.

Exports dépendant d'une fonctionnalité#

Ces exports ne sont enregistrés que lorsque leur fonctionnalité est active. Si la fonctionnalité est désactivée, les appeler lève une erreur.

• Config et performances

Exports côté client#

Appelez-les depuis des scripts client. N'importe quelle ressource client peut les appeler ; il n'y a aucune vérification de confiance. Ils n'affectent que les vérifications sur ce client et ne changent jamais l'application côté serveur.

-- sélection du personnage
exports['tosun-ac']:SetSpawned(false)
-- ... le joueur choisit un personnage ...
exports['tosun-ac']:SetSpawned(true)

Exports JavaScript#

Tosun AC enregistre quelques exports JavaScript sur le serveur pour l'analyse des ressources et la vérification de licence. Ils sont internes, ne passent pas par la vérification des ressources de confiance et ne constituent pas une API prise en charge. Ne les appelez pas. Il n'existe aucun export JavaScript public.

Fichiers bridge : installation#

Les fichiers bridge facultatifs de tosun-ac/bridge donnent à votre ressource une table globale TosunAC avec de petites fonctions utilitaires. Ils appellent les exports dans un pcall : votre script continue donc de tourner quand l'AC est arrêté. L'AC voit votre ressource comme appelante.

1. Ajoutez le bridge au fxmanifest.lua de votre ressource : server_script '@tosun-ac/bridge/tosun_ac_server.lua' et, si besoin, client_script '@tosun-ac/bridge/tosun_ac_client.lua'.
2. Si le dossier de l'AC porte un autre nom, ajoutez setr tosun_ac_resource "folder-name" à server.cfg. Utilisez setr : le bridge client lit cette convar sur le client.
3. Facultatif : set tosun_ac_bridge_server_ms (60000 par défaut), set tosun_ac_bridge_cooldown_ms (750 par défaut, 0 désactive) et setr tosun_ac_bridge_client_ms (60000 par défaut).
4. Pour des exemptions serveur complètes, ajoutez votre ressource à tosun_ac_trusted_resources. Sans confiance, TosunAC.PlayerExempt se rabat sur une exemption souple et affiche une seule fois un conseil dans la console du serveur (le texte du conseil est en turc).

-- fxmanifest.lua de votre ressource
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 serveur
local ok, mode = TosunAC.PlayerExempt(src, 'long', 'clothing')
-- mode vaut 'full' (de confiance) ou 'soft' (mouvement uniquement, 15 s max)

• Guide d'intégration
• Configuration du serveur

Bridge : fonctions serveur#

Définies par bridge/tosun_ac_server.lua dans votre ressource. Préréglages : SHORT 30000, MEDIUM 60000, LONG 120000, XL 180000 ms (TosunAC.Presets). TosunAC.Version vaut '1.2'.

Bridge : fonctions client#

Définies par bridge/tosun_ac_client.lua dans votre ressource. Elles enveloppent l'export client SetExempt et n'apportent donc qu'un soulagement côté client.

Exports que n'importe quelle ressource peut appeler#

Ces exports n'ont aucune vérification de confiance et ont des effets de bord. Toute ressource serveur peut les appeler. N'utilisez que des ressources de confiance ; notez que n'importe quelle ressource serveur peut déjà expulser des joueurs ou déclencher des événements client via les natives FiveM.

• MarkTeleport : exemption de mouvement, limitée par le budget par joueur.
• spectatePlayer : téléporte un joueur et accorde à chaque appel une exemption de mouvement de 15 s hors budget.
• NoteCloudViolation : augmente le score de menace d'un joueur et peut signaler la licence à la base de menaces inter-serveurs.
• warnPlayer et mutePlayer : écrivent des enregistrements d'avertissement et de mute.
• freezePlayer et slayPlayer : agissent directement sur un joueur.
• crashGuardReject : ajoute des avertissements (strikes) qui peuvent mener à une expulsion ou un ban.
• screenCapture, v6ScreenWatchRequest et RequestShieldScreenshot : demandent des captures d'écran.
• rescanResources, scanAllResources, scanSingleResource, tsScanBackdoors et tsScanEvents : lancent des scans. scanAllResources peut bloquer des ressources et tsScanBackdoors peut en arrêter quand le blocage automatique ou la quarantaine automatique est actif.
• applyWeatherWithFramework et applyTimeWithFramework : changent la météo et l'heure pour tout le monde.
• invalidateSignatureCache, reloadSignatureExceptions, reloadSignatureScanCaches et refreshPanelWhitelist : rechargent des caches.
• setPlayerLocale et unmutePlayer : modifient l'état d'un joueur.
• phoneNotify et phoneNotifyAdmins : envoient des messages téléphone ou dans le chat aux joueurs.

Noms historiques et trompeurs#

Ces exports fonctionnent toujours, mais leur nom ou une ancienne documentation suggère quelque chose qu'ils ne font pas.

• Les anciens guides (INTEGRATION.md pour la 9.6.6, CONFIG-EXPORTS-MULTILANG.md pour la 8.6.1, et la page de redirection TOSUN-AC-EXPORTS.md) sont obsolètes. En cas de différence, cette référence correspond au code de la 9.6.15.
• SetPlayerExempt, PausePlayerDetections, PauseAllDetections, BypassDetection, AddWhitelist, RemoveWhitelist, WhitelistArea, ClearArea, addAdmin, fakeTriggerTrap et fakeTriggerWhitelist nécessitent une ressource de confiance, bien que CONFIG-EXPORTS-MULTILANG.md les liste sans cette exigence.
• La liste de confiance par défaut est qbx_core, qb-core, es_extended, ox_inventory et ox_lib. INSTALLER-READY.md omet qb-core et es_extended.
• GetIntegrationStatus() renvoie aussi un champ version.
• punish, ban, BanPlayerExt, KickPlayer, offlineBan et offlineBanByLicense nécessitent une ressource de confiance.
• ban() et BanPlayerExt() suivent ts.punishType et ts.BanDurations['default'] : ils ne sont donc pas toujours permanents.
• KickPlayer ne vérifie pas les exemptions. Dans le circuit punish, KICK épargne toujours le staff, alors que BAN et LOG suivent ts.AdminBypassDetections.
• Pendant une exemption client, la plupart des vérifications client sont entièrement ignorées. Seules les détections qui atteignent quand même le chemin de ban deviennent des entrées LOG marquées [exempt].
• NoteCloudViolation ne bloque les connexions suivantes qu'avec ts.cloudBridge.threatIntelAction = 'kick'.
• Avec le bridge client, les convars tosun_ac_resource et tosun_ac_bridge_client_ms doivent être définies avec setr, pas set.
• Le plafond par appel de MarkTeleport (ts.Integration.markTeleportMaxMs) s'applique aussi aux appelants de confiance. Seul le budget de 180 s par 10 minutes concerne les appelants non fiables.