Server exports

These exports are available to server scripts. See Developer overview for how to call them from Lua, JavaScript and C#. In the signatures below, ? marks an optional parameter.

Punish and allow#

punishPlayer#

Punishes a player through the normal AstroShield flow, exactly like a built-in detection would. Use it for your own detections, for example an exploit in one of your scripts.

exports.AstroShield:punishPlayer(playerId, detection, data?, action?) --> boolean

Returns true when a punishment was started, and false when it was not. That happens when:

• the player is not connected, or is already being banned,
• the player is an admin excluded by the txAdmin whitelist,
• Dev Mode is on, in which case the detection is only logged,
• the action is log or none, or the detection is configured as no-punishment.

What happens next depends on the action. A ban isolates the player, requests a video clip, stores the ban and drops the player with your ban message. See Punishments. AstroShield also fires astroshield:player:punished.

RegisterNetEvent('myShop:buy', function(item, price)
    local src = source
    if price < 0 then
        exports.AstroShield:punishPlayer(src, 'myShop:priceExploit', {
            reason = 'Sent a negative price to the shop',
            item = item,
            price = price,
        })
        return
    end
    -- ...
end)

Another resource can also trigger the detection with the local server event astroshield:detection:trigger, which calls punishPlayer for it. See Events.

allowPlayer#

Tells AstroShield that something about a player is about to change legitimately, so neither the server nor the client checks punish it.

exports.AstroShield:allowPlayer(playerId, kind, ms?) --> boolean

The allowed kind values are teleport, revive, fade, attach, warpVehicle, superJump, playerSwitch, screenFade, camera, health and armour. Any other value makes the call return false.

Returns true when the allowance was applied. The player's client is told as well, so its own checks stay quiet.

-- Teleport a player to a hospital, legitimately
exports.AstroShield:allowPlayer(src, 'teleport', 5000)
SetEntityCoords(GetPlayerPed(src), 340.0, -1396.0, 32.5)

The full list of kinds, including the ones that only exist on the client, is in Allowances.

whitelistEntity#

Allows a model to be spawned on purpose, so AstroShield does not treat it as a spoofed or spam spawn.

exports.AstroShield:whitelistEntity(modelHash, playerId?) --> boolean

Returns true when added and false when the model is not valid. A model that is on a blacklist is still blocked, whitelisting does not override a blacklist.

removeWhitelist#

Removes an entry added with whitelistEntity. Use the same arguments.

exports.AstroShield:removeWhitelist(modelHash, playerId?) --> boolean

State and configuration#

getConfig#

Returns the configuration table that AstroShield received from the dashboard, or nil while it has not arrived yet. getAnticheatConfig is the same function under its older name.

local config = exports.AstroShield:getConfig()
if config and config.Settings and config.Settings.general.devMode then
    print('AstroShield is in Dev Mode')
end

getStatus#

Returns the connection and license state of the resource.

local status = exports.AstroShield:getStatus()

Use it to check that protection is live, for example to show a warning in your admin tools when authenticated is false.

shouldDetect#

exports.AstroShield:shouldDetect(playerId) --> boolean

Returns false when the player is exempt from detections because the txAdmin Whitelist is on and the player counts as an admin, and true otherwise. Use it before you run your own punishments, so you treat admins the same way AstroShield does.

isPlayerAdmin#

exports.AstroShield:isPlayerAdmin(playerId) --> boolean

Returns true when AstroShield counts the player as an admin. See Permissions and whitelisting for what that means. The answer does not depend on the whitelist setting.

isTxAdminWhitelistEnabled#

exports.AstroShield:isTxAdminWhitelistEnabled() --> boolean

Returns whether txAdmin Whitelist is switched on.

isPlayerAcReady#

exports.AstroShield:isPlayerAcReady(playerId) --> boolean

Returns true once the player has spawned and a short grace period is over. Until then AstroShield does not run its checks on them.

waitForPlayerAcReady#

exports.AstroShield:waitForPlayerAcReady(playerId, timeoutMs?) --> boolean

Waits, in the calling thread, until the player is ready and then returns true. It returns false if the player leaves or the time runs out. timeoutMs defaults to 60000 and is limited to 300000. Call it from a thread or an event handler, because it yields.

CreateThread(function()
    if exports.AstroShield:waitForPlayerAcReady(src, 30000) then
        -- safe to run actions that look suspicious during loading
    end
end)

isEventProtected#

exports.AstroShield:isEventProtected(eventName) --> boolean

Returns false when the event protection is switched off, or when eventName is on the ignore list, and true otherwise. Useful to find out why an event of yours is or is not guarded.

checkPlayerName#

Rejects players whose name contains a word from the Anti Blacklisted Names list. Call it when a player connects.

exports.AstroShield:checkPlayerName(source, playerName, deferrals) --> boolean

It returns true when the name is fine. Otherwise it ends the connection with a message that names the word, through deferrals.done, and returns false. AstroShield already applies this check to every connection, so you only need this export if you handle the connection yourself.

Players#

These return the same data the dashboard shows.

exports.AstroShield:getPlayers()                    --> { { id, name, ping, role, vehicle, identifiers }, ... }
exports.AstroShield:getPlayer(playerId)             --> { id, name, ping, identifiers } or nil
exports.AstroShield:getPlayerCount()                --> number
exports.AstroShield:getPlayerPositions()            --> { { id, name, coords = { x, y, z } }, ... }
exports.AstroShield:getPlayerFrameworkStatus(id)    --> { success, data } or { success = false, error }

• identifiers is a table with license, license2, steam, discord, fivem, xbl, live and ip, as far as the player has them.
• vehicle is true while the player is in a vehicle.
• getPlayerFrameworkStatus reads health, armor and, when ESX, QBCore, Qbox or ox_core is running, hunger, thirst, job, money and inventory. See Frameworks.

Bans#

getLocalRecords#

Returns the bans that this server currently knows, as last sent by the backend. Expired timed bans are left out.

local bans = exports.AstroShield:getLocalRecords('bans')
for _, ban in ipairs(bans) do
    print(ban.id, ban.username, ban.detection)
end

Only 'bans' is stored by the backend. 'warns' and 'kicks' return empty lists.

getRecords#

Asks the backend for the current bans. It waits for the answer, so call it from a thread or an event handler.

local result = exports.AstroShield:getRecords('bans', nil, 5000)
if result.success then
    print(#result.data .. ' bans')
else
    -- the backend did not answer, `result.data` is the last known list
    print('using cached list:', result.cached, result.error)
end

See Ban records for the fields of a ban and the events that tell you when it changes.

Heartbeat and diagnostics#

exports.AstroShield:getHeartbeatStatus(playerId?)   --> table
exports.AstroShield:getServerResources()            --> { [resourceName] = started }
exports.AstroShield:validateExecution()             --> true

• getHeartbeatStatus(playerId) returns { lastSeen, seq, started, alerted } for one player: when AstroShield's client part last reported in, how many reports it sent, which monitored resources it saw running and whether an alert was already raised. Without an argument it returns a table of all players keyed by server ID, and nil for an unknown player.
• getServerResources() returns every resource and whether it is started.
• validateExecution() always returns true. It exists so that older resources that call it keep working.