Recipes

Short, tested patterns. Every export used here is documented in the server and client references.

Teleport a player legitimately#

Allow the teleport on the server, right before you move the player.

Lua

-- server
local function teleportPlayer(src, coords)
    exports.AstroShield:allowPlayer(src, 'teleport', 5000)
    SetEntityCoords(GetPlayerPed(src), coords.x, coords.y, coords.z)
end

On the client, call exports.AstroShield:hasTeleported() before the native instead. In most cases the shared guard does this for you.

Revive or heal#

Lua

-- client, in your revive handler
exports.AstroShield:playerRevived()
-- then your own revive code

Lua

-- server
exports.AstroShield:allowPlayer(src, 'revive', 10000)
exports.AstroShield:allowPlayer(src, 'health', 6000)

Give a weapon from a shop#

Lua

-- client, before GiveWeaponToPed
exports.AstroShield:giveWeapon('WEAPON_PISTOL')

Servers with ox_inventory, ESX, QBCore or Qbox inventories usually do not need this, because AstroShield compares the weapon with the player's inventory. See Frameworks.

Spawn a vehicle from a script#

Tell AstroShield about the model before you create it.

Lua

-- client
exports.AstroShield:CreateVehicle('adder')
local veh = CreateVehicle(`adder`, x, y, z, heading, true, false)

Lua

-- server: allow a model for everyone, or for one player
exports.AstroShield:whitelistEntity('adder')
exports.AstroShield:whitelistEntity(`adder`, src)

A model on a blacklist stays blocked.

Safe zones and invincibility#

State allowances stay until you change them, so set both sides of the change.

Lua

-- when the player enters the zone
exports.AstroShield:isInvincible(true)

-- when the player leaves
exports.AstroShield:isInvincible(false)

Raise your own detection#

Punish a cheat that only your script can see, for example a price or amount your server never sends.

Lua

RegisterNetEvent('myBank:withdraw', function(amount)
    local src = source
    if type(amount) ~= 'number' or amount ~= amount or amount < 0 then
        exports.AstroShield:punishPlayer(src, 'myBank:invalidAmount', {
            reason = 'Sent an invalid withdraw amount',
            amount = tostring(amount),
        })
        return
    end
end)

Use 'kick' or 'warn' as the fourth argument for a milder reaction.

React when somebody is punished#

Lua

AddEventHandler('astroshield:player:punished', function(info)
    if info.action == 'ban' then
        -- remove the player's data, tell your staff channel, and so on
        TriggerEvent('myBot:post', ('%s was banned for %s'):format(info.playerName, info.detection))
    end
end)

Wait until a player is ready#

Some actions look suspicious while a player is still loading. Wait for AstroShield's ready state first.

Lua

AddEventHandler('playerJoining', function()
    local src = source
    CreateThread(function()
        if exports.AstroShield:waitForPlayerAcReady(src, 60000) then
            -- the player is loaded and checked
        end
    end)
end)

Unban from a script#

Lua

RegisterCommand('myunban', function(source, args)
    if source ~= 0 then return end -- console only
    ExecuteCommand(('astroshield unban %s'):format(args[1]))
end, true)

Check that protection is live#

Lua

CreateThread(function()
    while true do
        Wait(60000)
        local s = exports.AstroShield:getStatus()
        if not s.authenticated then
            print('AstroShield is not authenticated, check its console output')
        end
    end
end)

Skip your resource's noisy events#

If a script of yours fires an event many times per second on purpose, add it to Ignored Events or the resource to Ignored Resources. See Event protection. No code is needed.

Run your own punishments only for non-admins#

Lua

if exports.AstroShield:shouldDetect(src) then
    -- the player is not an exempt admin, run your own check
end

Command Palette