Export 参考

调用 export#

在你资源的服务器脚本中调用服务器 export，在其客户端脚本中调用客户端 export。资源名包含连字符，因此请始终使用方括号形式 exports['tosun-ac']。exports.tosun-ac 这种写法不是有效的 Lua。

• 服务器 id 请以数字传入。有几个 export 直接把 id 用作表的键。
• 有些 export 会执行同步数据库查询并让出（yield）。请在线程或事件处理器中调用它们：getBans、getBanInfo、GetDetections、isAdmin 及其他管理人员检查、IsExemptFromPunish、ForensicLinksOf 和 refreshPanelWhitelist。scanAllResources 和 scanSingleResource 也会让出。
• 受保护的 export 拒绝你的资源时会返回 false，即使它通常返回 nil。
• 有些 export 只有在对应功能启用时才存在（参见“依赖功能的 exports”）。调用未注册的 export 会抛出错误，因此请用 pcall 包裹这些调用。
• 有几个 export 没有出现在 fxmanifest.lua 的 export 列表中（例如 MarkTeleport、punish 和 AllowWeapon）。这些列表仅供参考；export 本身可以正常工作。
• 下面的表格中，调用方资源必须受信任时，最后一列为“是”。参见“受信任资源”。

-- 你自己资源中的服务器脚本
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')

• 服务器集成
• 服务器配置

受信任资源#

信任列中标为“是”的 export 会更改豁免、管理人员权限、封禁、玩家生命值、武器或背包、隔离、资源和特征码，或影响整个服务器。它们只接受来自受信任资源的调用。被拒绝的调用不做任何事并返回 false。

满足以下条件之一的调用方即为受信任：服务器控制台、tosun-ac 本身、配置中 ts.ExportCallerWhitelist 列出的资源，或 convar tosun_ac_trusted_resources 中列出的资源。默认配置列表为 qbx_core、qb-core、es_extended、ox_inventory 和 ox_lib。

优先使用 convar。它位于 server.cfg 中，AC 更新后仍然保留，而对配置文件的修改可能会在更新 AC 时丢失。名称之间用逗号或空格分隔。信任列表缓存 10 秒，因此运行时所做的更改会在 10 秒内生效。

对于每个资源与 export 的组合，第一次被拒绝时，AC 会在服务器控制台输出一条警告，其中包含需要添加的准确 server.cfg 行，并在面板日志中写入一行。面板日志行始终为土耳其语。

审计模式：设置 ts.EnforceExportCallerWhitelist = false 时，不受信任的调用会被执行，每个资源与 export 的组合会在服务器控制台输出一次（不写面板日志）。默认值为 true。审计模式只应在设置期间使用，用来查看哪些脚本调用了什么。

在服务器控制台运行 tosunac_integration，可输出执行模式、受信任资源及其来源（config 或 convar），以及最近 20 次被拒绝的调用。在脚本中可调用 GetIntegrationStatus()。

信任还会取消 MarkTeleport 额度：受信任资源可以标记传送，不受按玩家计算的时间限制。

Tosun AC 还为自身的内部机制（面板桥接、签名、扫描、授权、批处理）注册了内部 exports 和网络事件。它们不属于本参考，也不是受支持的 API。其中一些受信任检查或内部调用方检查保护。不要调用它们。

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

• 服务器配置
• 控制台命令

集成和豁免#

这些服务器 export 用于告知 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 中的任意 ACE；主体 group.admin、group.superadmin、group.moderator 和 group.god；ts.txAdminAuth 开启时的 command.kick/ban/resources/restart；admins.lua、ts.AdminMenu.allowedIds 和 ts.AdminBypassIdentifiers 中的标识符；以及数据库中的面板授权。同时授予了 builtin.everyone 的 ACE 不算。

isAdmin 和 addAdmin 在源码中注册了两次。anticheat_server.lua 中的版本最后加载，是实际运行的版本；本参考描述的就是这些版本。

玩家白名单和区域#

服务器 id 白名单、标识符白名单和命名区域。运行时列表只保存在内存中，重启后丢失；面板白名单是独立的。

惩罚和封禁#

通过 AC 流程惩罚玩家、封禁离线玩家以及读取封禁。这里所有写入类 export 都需要信任。

• 事件

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 的日志写入类 export 属于内部接口，不在此列出。

• 面板连接

状态和诊断#

为仪表盘和健康检查读取 AC 状态。

资源防护（Resource Guard）#

读取和更改已批准的资源基线。即使资源防护被禁用，这些 export 也都会注册。

• 控制台命令

特征码、后门和事件扫描#

运行扫描并管理特征码、误报例外和 escrow 跳过项。扫描可能需要一些时间；请在线程中运行。

蜜罐事件#

把事件名变成陷阱或解除陷阱。两者都会写入 ac_protected_events 并从数据库重新加载。

依赖功能的 exports#

这些 export 只有在对应功能开启时才会注册。功能关闭时调用它们会抛出错误。

• 设置与性能

客户端 exports#

在客户端脚本中调用这些 export。任何客户端资源都可以调用；没有信任检查。它们只影响该客户端上的检查，永远不会改变服务器端的执行。

-- 角色选择
exports['tosun-ac']:SetSpawned(false)
-- ... 玩家选择角色 ...
exports['tosun-ac']:SetSpawned(true)

JavaScript exports#

Tosun AC 在服务器上注册了几个 JavaScript export，用于资源扫描和许可证验证。它们是内部接口，不受受信任资源检查保护，也不是受支持的 API。不要调用它们。没有公开的 JavaScript export。

桥接文件：设置#

tosun-ac/bridge 中的可选桥接文件会为你的资源提供一个带简短辅助函数的全局 TosunAC 表。它们在 pcall 中调用 export，因此 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 export，因此只在客户端放宽检查。

任何资源都能调用的 exports#

这些 export 没有信任检查，并且有副作用。每个服务器资源都可以调用它们。只运行你信任的资源；注意，任何服务器资源本来就可以通过 FiveM native 踢出玩家或触发客户端事件。

• 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：向玩家发送手机或聊天消息。

旧名称和易误解的名称#

这些 export 仍然可用，但它们的名称或旧文档暗示了它们实际上并不做的事情。

• 旧指南（9.6.6 的 INTEGRATION.md、8.6.1 的 CONFIG-EXPORTS-MULTILANG.md，以及重定向占位文件 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。
• 客户端豁免期间，大多数客户端检查会被完全跳过。只有仍进入封禁路径的检测才会变成带 [exempt] 标签的 LOG 记录。
• 只有 ts.cloudBridge.threatIntelAction = 'kick' 时，NoteCloudViolation 才会阻止之后的加入。
• 使用客户端桥接时，convar tosun_ac_resource 和 tosun_ac_bridge_client_ms 必须用 setr 设置，而不是 set。
• MarkTeleport 的单次调用上限（ts.Integration.markTeleportMaxMs）同样适用于受信任的调用方。只有每 10 分钟 180 秒的额度是针对不受信任调用方的。