Events

Events are the second way to work with AstroShield, next to exports. There are events you listen to, and events you trigger.

Listen with AddEventHandler, not RegisterNetEvent

The events AstroShield fires on the server are local events. Register your handlers with AddEventHandler. If you register them as net events, a player could trigger them from their client and fake a ban.

Events you can listen to#

All of these are fired on the server.

astroshield:player:punished#

Fired after AstroShield bans, kicks or warns a player, whether through a detection, a custom rule or punishPlayer.

Lua

AddEventHandler('astroshield:player:punished', function(info)
    print(('%s [%s] was %s for %s'):format(info.playerName, info.playerId, info.action, info.detection))
end)

Field	Type	Meaning
`playerId`	number	The server ID the player had.
`playerName`	string	The player's name.
`detection`	string	The detection key, your own name from `punishPlayer`, or `Custom Rule: <name>`.
`action`	string	`ban`, `kick` or `warn`.
`reason`	string	The reason.
`data`	table	The detection data. Not present for rule punishments.
`timestamp`	number	Unix time.
`caseId`	string	The case ID, for example `AS-261009143012-12-K3F9`. Not present for rule punishments.
`banId`	string	The ban ID for a ban, once it is known. Not present for rule punishments.
`evidence`	string	URL of the video clip, when there is one.

Use it to log to your own Discord bot, to clean up the player's data, or to tell other scripts.

astroshield:ban:created#

Fired when a ban is stored for this server. The argument is the ban record. See Ban records.

Lua

AddEventHandler('astroshield:ban:created', function(record)
    print('New ban', record.id, record.username, record.detection)
end)

astroshield:ban:deleted#

Fired when a ban is removed, for example from the dashboard. The argument is the ban record that was deleted.

astroshield:records:loaded#

Fired whenever the list of bans is refreshed from the backend. The arguments are the kind ('bans') and the list.

Lua

AddEventHandler('astroshield:records:loaded', function(kind, list)
    print(kind, #list)
end)

astroshield:ban:error and astroshield:records:error#

Fired when the backend could not store or read a record. The argument describes the error. Use them to notice that bans are not being saved.

astroshield:license:status#

Fired when the backend answers a connection attempt, with the license state.

Lua

AddEventHandler('astroshield:license:status', function(status)
    if not status.valid then
        print('AstroShield license problem: ' .. tostring(status.status))
    end
end)

Field	Meaning
`valid`	`true` when the license was accepted.
`status`	`active`, `expiring`, `lifetime`, `expired`, `banned`, `inactive` or `ip_mismatch`. See License statuses.
`plan`, `expiresOn`, `daysLeft`	Plan, expiry date and days left, when the license was accepted.
`currentIp`, `allowedIp`	The IP the server connected from and the IP the license is locked to.

Events you can trigger#

astroshield:detection:trigger#

A server-side local event that raises a detection. It calls punishPlayer with the same arguments, without the action.

Lua

TriggerEvent('astroshield:detection:trigger', playerId, 'myDetection', 'The reason')

It is a local event, so clients cannot trigger it. Another resource on the server can.

astroshield:allow#

Sent from the server to one client. It tells that client's AstroShield to allow something. See Allowances.

Lua

TriggerClientEvent('astroshield:allow', src, 'teleport', 5000)

astroshield:triggerDetection#

Sent from the server to one client. It asks that player's client to raise a detection. The client reports it to the server and the normal ban flow, including the video clip, follows.

Lua

TriggerClientEvent('astroshield:triggerDetection', src, 'antiTeleport', 'Reason', { extra = 'data' })

The detection must be a known one that is switched on in the configuration, and a client reports the same detection at most once every 15 seconds. For your own detection names use punishPlayer instead.

Compatibility events#

These server-to-client events exist for older scripts. Each one allows one action, like the matching client export.

Event	Same as
`astroshield:antiArmour:granted`	`grantedArmour()`
`astroshield:antiTeleport:hasTeleported`	`hasTeleported()`
`astroshield:antiVehiclePlateChanger:plateChanged`	`ChangeVehiclePlate()`
`astroshield:setVehiclePlate`	`ChangeVehiclePlate()`

All of them are accepted only when the server sends them.

Command Palette