AstroShield Docs

Command Palette

Search for a command to run...

Developer overview

How your own resources talk to AstroShield, which side each export lives on and what is supported.

AstroShield gives your scripts three things:

  • Allowances. Tell AstroShield that a teleport, heal, weapon or spawn is legitimate, so it is not punished. See Allowances.
  • Punishments. Raise your own detection with punishPlayer and let AstroShield ban, kick or warn through its normal flow. See Server exports.
  • Hooks and state. Events when someone is punished or banned, and exports to read the license, the configuration and the players. See Events.

Calling an export#

The resource must be called AstroShield. Exports are called through the standard FiveM export mechanism.

Lua
-- server side
exports.AstroShield:allowPlayer(source, 'teleport', 5000)

-- client side
exports.AstroShield:playerRevived()

Check that the resource is running before you call it, so your script does not fail when AstroShield is stopped:

Lua
if GetResourceState('AstroShield') == 'started' then
    exports.AstroShield:allowPlayer(source, 'teleport', 5000)
end

Server and client#

AstroShield exports different functions on the server and on the client. A few names exist on both sides and mean the same, such as getConfig and shouldDetect.

WherePageTypical use
ServerServer exportsPunish players, allow actions, read license and player data.
ClientClient exportsTell AstroShield about a heal, teleport, spawn or weapon your script just did.
BothAllowancesThe list of what can be allowed, with its time limits.
BothEventsEvents you can listen to or trigger.
ServerBan recordsRead and manage bans from a script.
BothRecipesCopy-paste solutions for common situations.

Do you need exports at all?#

Often not. Once astroinstall has added the shared guard to your resources, the common actions of your own scripts are recognized automatically: teleporting a player, healing, giving armor or a weapon, spawning vehicles, peds or objects, changing a model, entering a vehicle, and so on.

Use the exports when:

  • a detection still fires on something your script does on purpose,
  • the action happens in a resource that the guard does not cover,
  • you want to raise your own punishment (punishPlayer),
  • you want AstroShield's data in your own script (license state, players, config).

What is supported#

Every export and event documented in this section is supported and is kept working between versions. Anything not documented here, such as the astroshield:hb:* events and the exports the dashboard bridge uses, is internal and can change without notice.

Test your integration with Dev Mode. Detections are then printed to the server console with their data, so you can see what fires and why without banning anybody.

Good practice#

  • Never trust the client. Call allowPlayer and the other server exports from server code. Do not add an event that lets a client allow itself, or a cheater will use it.
  • Keep allowances short. Allow just before the action and for as short a time as you can.
  • Do not store the configuration. getConfig can contain your webhook URLs. Read it when you need it and never send it to clients.
  • Listen with AddEventHandler. Events that AstroShield fires on the server are local events. Do not register them as net events, or a player could trigger them.
PreviousShared guardNextServer exports