Справочник экспортов

Вызов экспорта#

Серверные экспорты вызывайте из серверных скриптов вашего ресурса, клиентские — из его клиентских скриптов. В имени ресурса есть дефис, поэтому всегда используйте форму со скобками exports['tosun-ac']. Форма exports.tosun-ac недопустима в Lua.

• Передавайте серверные id числами. Некоторые экспорты используют id напрямую как ключ таблицы.
• Некоторые экспорты выполняют синхронный запрос к базе данных и уступают управление (yield). Вызывайте их из потока или обработчика события: getBans, getBanInfo, GetDetections, isAdmin и другие проверки персонала, IsExemptFromPunish, ForensicLinksOf и refreshPanelWhitelist. scanAllResources и scanSingleResource тоже уступают управление.
• Защищённый экспорт, отклонивший ваш ресурс, возвращает false, даже если обычно возвращает nil.
• Некоторые экспорты существуют, только когда включена их функция (см. «Экспорты, зависящие от функций»). Вызов незарегистрированного экспорта вызывает ошибку, поэтому оборачивайте такие вызовы в pcall.
• Некоторых экспортов нет в списках экспортов fxmanifest.lua (например, MarkTeleport, punish и AllowWeapon). Эти списки носят лишь информационный характер; экспорты работают.
• В таблицах ниже в последнем столбце стоит «Да», если вызывающий ресурс должен быть доверенным. См. «Доверенные ресурсы».

-- серверный скрипт в вашем ресурсе
local status = exports['tosun-ac']:GetIntegrationStatus()
if not status.trusted then
    print(status.hint) -- строка, которую нужно добавить в server.cfg
end

-- сообщить AC о телепорте, затем переместить игрока
exports['tosun-ac']:MarkTeleport(src, 8000)
SetEntityCoords(GetPlayerPed(src), x, y, z)

-- клиентский скрипт в вашем ресурсе
exports['tosun-ac']:SetExempt(true, 60000, 'my_menu')

• Руководство по интеграции
• Конфигурация сервера

Доверенные ресурсы#

Экспорты с «Да» в столбце доверия меняют освобождения, права персонала, баны, здоровье, оружие или инвентарь игрока, карантин, ресурсы и сигнатуры или весь сервер. Они принимают вызовы только от доверенного ресурса. Отклонённый вызов ничего не делает и возвращает false.

Вызывающий считается доверенным, если это серверная консоль, сам tosun-ac, ресурс из ts.ExportCallerWhitelist в конфигурации или ресурс из convar tosun_ac_trusted_resources. Список в конфигурации по умолчанию: qbx_core, qb-core, es_extended, ox_inventory и ox_lib.

Предпочитайте convar. Он находится в server.cfg и сохраняется при обновлениях AC, а правки файла конфигурации могут потеряться при обновлении. Разделяйте имена запятыми или пробелами. Список доверия кешируется на 10 секунд, поэтому изменение во время работы вступает в силу в течение 10 секунд.

При первом отказе для каждой пары «ресурс + экспорт» AC выводит в серверную консоль одно предупреждение с точной строкой для server.cfg и пишет одну строку в логи панели. Строка лога панели всегда на турецком.

Режим аудита: при ts.EnforceExportCallerWhitelist = false недоверенные вызовы выполняются, а каждая пара «ресурс + экспорт» один раз выводится в серверную консоль (без строки в логе панели). По умолчанию true. Используйте режим аудита только при настройке, чтобы увидеть, какие скрипты что вызывают.

Выполните tosunac_integration в серверной консоли, чтобы вывести режим применения, доверенные ресурсы с их источником (config или convar) и последние 20 отклонённых вызовов. Из скрипта вызовите GetIntegrationStatus().

Доверие также снимает бюджет MarkTeleport: доверенные ресурсы могут отмечать телепорты без лимита времени на игрока.

Tosun AC также регистрирует внутренние экспорты и сетевые события для собственной инфраструктуры (мост панели, подписи, сканирование, лицензирование, пакетная запись). Они не входят в этот справочник и не являются поддерживаемым API. Некоторые защищены проверкой доверия или внутренней проверкой вызывающего. Не вызывайте их.

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

• Конфигурация сервера
• Консольные команды

Интеграция и освобождения#

Серверные экспорты, сообщающие AC о легитимных действиях ваших скриптов и показывающие, освобождён ли игрок.

Выбор освобождения#

Используйте самое узкое освобождение, покрывающее ваш скрипт. Несколько освобождений используют один и тот же клиентский флаг, поэтому одно может завершить другое: ClearArea с именем зоны сбрасывает флаг, который также устанавливают SetPlayerExempt, MarkTeleport и BypassDetection.

Персонал и права#

Чтение и изменение того, кого AC считает персоналом. Проверки персонала могут обращаться к базе данных, поэтому вызывайте их из потока или обработчика события.

isAdmin возвращает true для: ручной выдачи через addAdmin; ACE txadmin, tx.admin, txadmin.menu, txadmin.advanced, command.txadmin, command.ts, command.ban, command.kick, tosun.admin, ts.admin и любых из ts.AdminBypassAces; principal group.admin, group.superadmin, group.moderator и group.god; command.kick/ban/resources/restart при включённом ts.txAdminAuth; идентификаторов в admins.lua, ts.AdminMenu.allowedIds и ts.AdminBypassIdentifiers; прав из панели в базе данных. ACE, который также выдан builtin.everyone, не учитывается.

isAdmin и addAdmin зарегистрированы в исходном коде дважды. Версии из anticheat_server.lua загружаются последними и именно они работают; этот справочник описывает их.

Белый список игроков и зоны#

Белый список по серверному id, белый список по идентификаторам и именованные зоны. Списки времени выполнения хранятся только в памяти и теряются при перезапуске; белый список панели — отдельный.

Наказания и баны#

Наказание игроков через конвейер AC, баны игроков не в сети и чтение банов. Все экспорты записи здесь требуют доверия.

• События

Как punish() выбирает наказание#

punish(), ban() и BanPlayerExt() используют один конвейер. Вот порядок его работы.

1. Персонал пропускается, если ts.AdminBypassDetections не равен false. Игроки с активным освобождением или в белом списке времени выполнения или панели пропускаются. ts.Debug отключает эти пропуски. Пропущенные вызовы ничего не делают и ничего не пишут в лог.
2. Игрок должен быть онлайн. Иначе в серверную консоль выводится ошибка, и ничего не происходит.
3. Наказание: побеждает допустимый аргумент punishment. Иначе ts.DetectionPunishments[configKey], затем его псевдоним, затем ключ обнаружения, затем ts.punishType, затем BAN.
4. Каждый исход вызывает серверное событие ts_anticheat:playerBanned, публикует сообщение в чат при включённом ts.chatMessages, добавляет облачное нарушение и пишет лог AC и живой лог.
5. LOG: отправляет лог со скриншотом в Discord.
6. KICK: повторно проверяет персонал независимо от ts.AdminBypassDetections, поэтому персонал никогда не кикается. Затем отправляет лог со скриншотом и отключает игрока.
7. BAN: вставляет бан с длительностью из ts.BanDurations в часах (configKey, псевдоним, ключ обнаружения, префикс, затем default; 0 = навсегда) и bannedBy 'anticheat:' плюс ключ. Вызывает ts_anticheat:banCommitted, уведомляет панель и отключает игрока (повтор через 3 с).

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

Модерация отдельного игрока#

Действия над одним игроком. Внимательно смотрите на столбец доверия: у некоторых из этих экспортов нет проверки доверия.

Действия на весь сервер#

Действия, затрагивающие всех игроков или все новые подключения.

Карантин и защита от вредных данных#

Изоляция подозрительного игрока и защита ваших сетевых событий от краш-данных и спама.

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
    -- обработать покупку
end)

Игроки и обнаружения#

Поиск игроков, идентификаторов, банов игрока, показателей угрозы и связанных аккаунтов. Некоторые результаты содержат персональные данные, например IP-адреса.

Уведомления и язык#

Отправка уведомлений на телефон и использование таблиц переводов AC. phoneNotify и phoneNotifyAdmins существуют, только когда включён ts.AdminMenu.enable.

Скриншоты#

Запрос скриншотов игроков для панели. Экспорты AC для записи логов внутренние и здесь не перечислены.

• Настройка панели

Статус и диагностика#

Чтение состояния AC для дашбордов и проверок работоспособности.

Resource Guard#

Чтение и изменение утверждённого базового списка ресурсов. Все эти экспорты регистрируются, даже если Resource Guard отключён.

• Консольные команды

Сканирование сигнатур, бэкдоров и событий#

Запуск сканирований и управление сигнатурами, исключениями для ложных срабатываний и пропусками escrow. Сканирование может занять время; запускайте его из потока.

События-ловушки (honeypot)#

Превращение имён событий в ловушки или их освобождение. Оба экспорта пишут в ac_protected_events и перезагружают данные из базы данных.

Экспорты, зависящие от функций#

Эти экспорты регистрируются, только когда их функция включена. Если функция выключена, их вызов вызывает ошибку.

• Конфигурация и производительность

Клиентские экспорты#

Вызывайте их из клиентских скриптов. Их может вызвать любой клиентский ресурс; проверки доверия нет. Они влияют только на проверки на этом клиенте и никогда не меняют серверный контроль.

-- выбор персонажа
exports['tosun-ac']:SetSpawned(false)
-- ... игрок выбирает персонажа ...
exports['tosun-ac']:SetSpawned(true)

Экспорты JavaScript#

Tosun AC регистрирует на сервере несколько экспортов JavaScript для сканирования ресурсов и проверки лицензии. Они внутренние, не защищены проверкой доверенных ресурсов и не являются поддерживаемым API. Не вызывайте их. Публичных экспортов JavaScript нет.

Файлы моста: настройка#

Необязательные файлы моста в tosun-ac/bridge дают вашему ресурсу глобальную таблицу TosunAC с короткими вспомогательными функциями. Они вызывают экспорты внутри pcall, поэтому ваш скрипт продолжает работать, когда AC остановлен. AC видит вызывающим ваш ресурс.

1. Добавьте мост в fxmanifest.lua вашего ресурса: server_script '@tosun-ac/bridge/tosun_ac_server.lua' и при необходимости client_script '@tosun-ac/bridge/tosun_ac_client.lua'.
2. Если папка AC называется иначе, добавьте в server.cfg setr tosun_ac_resource "folder-name". Используйте setr: клиентский мост читает этот convar на клиенте.
3. Необязательно: задайте set tosun_ac_bridge_server_ms (по умолчанию 60000), set tosun_ac_bridge_cooldown_ms (по умолчанию 750, 0 отключает) и setr tosun_ac_bridge_client_ms (по умолчанию 60000).
4. Для полных серверных освобождений добавьте свой ресурс в tosun_ac_trusted_resources. Без доверия TosunAC.PlayerExempt переходит к мягкому освобождению и один раз выводит подсказку в серверную консоль (текст подсказки на турецком).

-- fxmanifest.lua вашего ресурса
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"

-- серверный скрипт
local ok, mode = TosunAC.PlayerExempt(src, 'long', 'clothing')
-- mode равен 'full' (доверенный) или 'soft' (только движение, максимум 15 с)

• Руководство по интеграции
• Конфигурация сервера

Мост: серверные функции#

Определены в bridge/tosun_ac_server.lua внутри вашего ресурса. Пресеты: SHORT 30000, MEDIUM 60000, LONG 120000, XL 180000 мс (TosunAC.Presets). TosunAC.Version равен '1.2'.

Мост: клиентские функции#

Определены в bridge/tosun_ac_client.lua внутри вашего ресурса. Они оборачивают клиентский экспорт SetExempt, поэтому дают облегчение только на стороне клиента.

Экспорты, которые может вызвать любой ресурс#

У этих экспортов нет проверки доверия, и у них есть побочные эффекты. Их может вызвать любой серверный ресурс. Запускайте только ресурсы, которым доверяете; учтите, что любой серверный ресурс и так может кикать игроков или вызывать клиентские события через нативные функции FiveM.

• MarkTeleport: освобождение от проверок движения, ограниченное бюджетом на игрока.
• spectatePlayer: телепортирует игрока и при каждом вызове даёт освобождение от проверок движения на 15 с без учёта бюджета.
• NoteCloudViolation: повышает показатель угрозы игрока и может сообщить license в межсерверную базу угроз.
• warnPlayer и mutePlayer: записывают предупреждения и муты.
• freezePlayer и slayPlayer: действуют на игрока напрямую.
• crashGuardReject: добавляет страйки, которые могут привести к кику или бану.
• screenCapture, v6ScreenWatchRequest и RequestShieldScreenshot: запрашивают скриншоты.
• rescanResources, scanAllResources, scanSingleResource, tsScanBackdoors и tsScanEvents: запускают сканирование. scanAllResources может блокировать ресурсы, а tsScanBackdoors — останавливать их при включённых автоблокировке или автокарантине.
• applyWeatherWithFramework и applyTimeWithFramework: меняют погоду и время для всех.
• invalidateSignatureCache, reloadSignatureExceptions, reloadSignatureScanCaches и refreshPanelWhitelist: перезагружают кеши.
• setPlayerLocale и unmutePlayer: меняют состояние игрока.
• phoneNotify и phoneNotifyAdmins: отправляют игрокам сообщения на телефон или в чат.

Устаревшие и вводящие в заблуждение имена#

Эти экспорты по-прежнему работают, но их имена или старая документация предполагают то, чего они не делают.

• Старые руководства (INTEGRATION.md для 9.6.6, CONFIG-EXPORTS-MULTILANG.md для 8.6.1 и заглушка-перенаправление TOSUN-AC-EXPORTS.md) устарели. Где они расходятся, этот справочник соответствует коду 9.6.15.
• SetPlayerExempt, PausePlayerDetections, PauseAllDetections, BypassDetection, AddWhitelist, RemoveWhitelist, WhitelistArea, ClearArea, addAdmin, fakeTriggerTrap и fakeTriggerWhitelist требуют доверенного ресурса, хотя CONFIG-EXPORTS-MULTILANG.md перечисляет их без этого требования.
• Список доверенных по умолчанию: qbx_core, qb-core, es_extended, ox_inventory и ox_lib. В INSTALLER-READY.md нет qb-core и es_extended.
• GetIntegrationStatus() также возвращает поле version.
• punish, ban, BanPlayerExt, KickPlayer, offlineBan и offlineBanByLicense требуют доверенного ресурса.
• ban() и BanPlayerExt() следуют ts.punishType и ts.BanDurations['default'], поэтому не всегда банят навсегда.
• KickPlayer не проверяет освобождения. В конвейере punish KICK всегда щадит персонал, а BAN и LOG следуют ts.AdminBypassDetections.
• Во время клиентского освобождения большинство клиентских проверок полностью пропускается. Только обнаружения, всё же дошедшие до пути бана, становятся записями LOG с тегом [exempt].
• NoteCloudViolation блокирует последующие входы только при ts.cloudBridge.threatIntelAction = 'kick'.
• При использовании клиентского моста convar tosun_ac_resource и tosun_ac_bridge_client_ms нужно задавать через setr, а не через set.
• Лимит MarkTeleport на один вызов (ts.Integration.markTeleportMaxMs) применяется и к доверенным вызывающим. Только бюджет 180 с за 10 минут относится к недоверенным вызывающим.