Multi Theft Auto: Wiki - User contributions [en]

OnExplosion

2025-12-17T09:25:22Z

DColeman: Add explosion sync information

__NOTOC__
{{Server event}}
{{Added feature/item|1.6.1|1.6.0|21914|This event is triggered every time an explosion is created either by server-side [[createExplosion]], or when reported by [[player]].}}
==Parameters==
<syntaxhighlight lang="lua">
float x, float y, float z, int theType
</syntaxhighlight>
*'''x:''' X coordinate of where the explosion was created
*'''y:''' Y coordinate of where the explosion was created
*'''z:''' Z coordinate of where the explosion was created
*'''theType:''' the type of explosion created, see: [[Explosion types]]
==Source==
The [[event system#Event source|source]] of this event is the [[player]] who notified server about explosion, or [[root]] if explosion was created server-side along without specifying creator in [[createExplosion]].

===Canceling===
If this event is [[Event system #Canceling|canceled]], the explosion will not occur.
If an explosion is notified by a player, that explosion will still be visible to this player.

==Example==
This example outputs information about occuring explosion.
<syntaxhighlight lang="lua">
local debugMsgLevel = 4
local debugMsgR = 255
local debugMsgG = 127
local debugMsgB = 0
local explosionTypes = {
[0] = "Grenade",
[1] = "Molotov",
[2] = "Rocket",
[3] = "Rocket Weak",
[4] = "Car",
[5] = "Car Quick",
[6] = "Boat",
[7] = "Aircraft",
[8] = "Mine",
[9] = "Object",
[10] = "Tank Grenade",
[11] = "Small",
[12] = "Tiny",
}

function onExplosion(explosionX, explosionY, explosionZ, explosionType)
local explosionPos = explosionX..", "..explosionY..", "..explosionZ
local explosionTypeName = explosionTypes[explosionType]
local explosionSource = inspect(source)
local debugMsg = explosionTypeName.." explosion has occured at "..explosionPos.." (source: "..explosionSource..")"

outputDebugString(debugMsg, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)
end
addEventHandler("onExplosion", root, onExplosion)
</syntaxhighlight>
{{See also/Server event|Server events}}

AddDebugHook

2025-09-16T09:42:24Z

DColeman: /* Required Arguments */

__NOTOC__
{{Server client function}}
{{New feature/item|3.0136|1.3|5939|
This function allows tracing of MTA functions and events. It should only be used when debugging scripts as it may degrade script performance.

Debug hooks are not recursive, so functions and events triggered inside the hook callback will not be traced.
}}

==Syntax==
<syntaxhighlight lang="lua">
bool addDebugHook ( string hookType, function callbackFunction [, table nameList ] )
</syntaxhighlight>

===Required Arguments===
*'''hookType:''' The type of hook to add. This can be:
** preEvent
** postEvent
** preFunction
** postFunction
** preEventFunction
** postEventFunction
*'''callbackFunction:''' The function to call
** Returning the string "skip" from the callback function will cause the original function/event to be skipped

===Optional Arguments===
*'''nameList:''' Table of strings for restricting which functions and events the hook will be triggered on
** addDebugHook and removeDebugHook will only be hooked if they are specified in the name list

===Returns===
Returns ''true'' if the hook was successfully added, or ''false'' otherwise.

==Callback parameters==
<syntaxhighlight lang="lua">
string preFunction( resource sourceResource, string functionName, bool isAllowedByACL, string luaFilename, int luaLineNumber, ...functionArguments )
postFunction( resource sourceResource, string functionName, bool isAllowedByACL, string luaFilename, int luaLineNumber, ...functionArguments )
string preEvent( resource sourceResource, string eventName, element eventSource, element eventClient, string luaFilename, int luaLineNumber, ...eventArguments )
postEvent( resource sourceResource, string eventName, element eventSource, element eventClient, string luaFilename, int luaLineNumber, ...eventArguments )
</syntaxhighlight>
{{New feature/item|3.0158|1.5.5|11856|
<syntaxhighlight lang="lua">
string preEventFunction ( resource eventResource, string eventName, element eventSource, element eventClient, string eventFilename, int eventLineNumber, resource functionResource, string functionFilename, int functionLineNumber, ...eventArgs )
postEventFunction ( resource eventResource, string eventName, element eventSource, element eventClient, string eventFilename, int eventLineNumber, resource functionResource, string functionFilename, int functionLineNumber, ...eventArgs )
</syntaxhighlight>
}}

==Example==
This example will dump info about all triggered events:
<syntaxhighlight lang="lua">
function onPreEvent( sourceResource, eventName, eventSource, eventClient, luaFilename, luaLineNumber, ... )
local args = { ... }
local srctype = eventSource and getElementType(eventSource)
local resname = sourceResource and getResourceName(sourceResource)
local plrname = eventClient and getPlayerName(eventClient)
outputDebugString( "preEvent"
.. " " .. tostring(resname)
.. " " .. tostring(eventName)
.. " source:" .. tostring(srctype)
.. " player:" .. tostring(plrname)
.. " file:" .. tostring(luaFilename)
.. "(" .. tostring(luaLineNumber) .. ")"
.. " numArgs:" .. tostring(#args)
.. " arg1:" .. tostring(args[1])
)
end
addDebugHook( "preEvent", onPreEvent )
</syntaxhighlight>
This example will dump info about all called MTA functions:
<syntaxhighlight lang="lua">
function onPreFunction( sourceResource, functionName, isAllowedByACL, luaFilename, luaLineNumber, ... )
local args = { ... }
local resname = sourceResource and getResourceName(sourceResource)
outputDebugString( "preFunction"
.. " " .. tostring(resname)
.. " " .. tostring(functionName)
.. " allowed:" .. tostring(isAllowedByACL)
.. " file:" .. tostring(luaFilename)
.. "(" .. tostring(luaLineNumber) .. ")"
.. " numArgs:" .. tostring(#args)
.. " arg1:" .. tostring(args[1])
)
end
addDebugHook( "preFunction", onPreFunction)
</syntaxhighlight>

This example adds a hook which will only be triggered for the named functions
<syntaxhighlight lang="lua">
addDebugHook( "preFunction", onPreFunction, {"setElementPosition","loadstring"} )
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.5-9.06054|Added clientside}}
{{ChangelogItem|1.3.5-9.06142|Added option to restrict to specified functions and events }}
{{ChangelogItem|1.5.2-9.07957|Added option to skip original function/event <br/>Added ability to hook addDebugHook and removeDebugHook }}
{{ChangelogItem|1.5.5-9.11856|Added pre/postEventFunction hooks }}
{{ChangelogItem|1.6.0-9.22741|Removed ability to skip 'addDebugHook' }}

==See Also==
{{Utility functions}}

User:DColeman/RU:Безопасность скриптов

2025-05-23T14:26:25Z

DColeman: /* Обнаружение и обезвреживание бэкдоров и читов */

==Информация по памяти клиента==

Начиная с самых основ:
* Вы должны понимать, что все, что вы храните на стороне клиента, включая .lua файлы, находится под риском. Любая конфиденциальная или критическая информация, которая как-либо оказывается на клиентской стороне (ПК игрока), может быть прочитана и/или изменена чит-клиентами.
* Чтобы сохранить конфиденциальную информацию и логику скрипта в секрете - используйте серверную сторону.
* Обратите внимание, что скрипты, отмеченные как общие ('''shared''') также действуют как '''клиентские''', что означает, что все вышеперечисленное также применяется и к ним. Например, объявление скрипта:

<syntaxhighlight lang="xml">
<script src="script.lua" type="shared"/> 
</syntaxhighlight>

То же самое, что и объявление:

<syntaxhighlight lang="xml">
<script src="script.lua" type="client"/> 
<script src="script.lua" type="server"/> 
</syntaxhighlight>

==Дополнительный слой защиты==

Чтобы значительно ''усложнить жизнь*'' тем, у кого есть плохие намерения по отношению к вашему серверу, вы можете использовать аттрибут cache (и/или [https://luac.mtasa.com/ скомпилированные lua скрипты (также известные как Luac) с '''3''' уровнем дополнительной обфускации] - [https://wiki.multitheftauto.com/wiki/Lua_compilation_API API]), доступный в [https://wiki.multitheftauto.com/wiki/Meta.xml meta.xml], вместе с настройкой встроенного античита МТА с включением SD (специальными кодами обнаружения), для дополнительной информации смотрите [https://wiki.multitheftauto.com/wiki/Anti-cheat_guide гайд по античиту].

<syntaxhighlight lang="xml">
<script src="shared.lua" type="shared" cache="false"/> 
<script src="client.lua" type="client" cache="false"/> 
</syntaxhighlight>

* ''Усложнить жизнь'' '''не означает "сделать невозможным"''' получение вашего клиентского Lua кода, это означает, что '''большинство''' людей не смогут просмотреть ваши .lua файлы - тех, кто ищет логические ошибки (баги) или отсутствующие/некорректные проверки безопасности.
* Может использоваться на '''client''' и '''shared''' типах скриптов (не имеет эффекта на серверных скриптах).
* Это не удалит Lua файлы, которые были загружены ранее.

==Обнаружение и обезвреживание бэкдоров и читов==
'''Чтобы минимизировать (или исключить) урон, причиненный Lua скриптами:'''
* Всегда обновляйте ваш сервер до самой актуальной версии, вы можете [https://nightly.multitheftauto.com/ загрузить новейшие сборки сервера отсюда.] С информацией по определенным сборкам можно ознакомиться [https://buildinfo.multitheftauto.com/ здесь.]
* Всегда обновляйте ресурсы, установленные на сервере, до самой актуальной версии, вы можете [https://github.com/multitheftauto/mtasa-resources загрузить новейшие (стандартные) ресурсы из репозитория GitHub.] Они часто содержат обновления безопасности, которые влияют на устойчивость вашего сервера к атакам.
* Убедитесь, что [https://wiki.multitheftauto.com/wiki/Access%20Control%20List ACL (список контроля доступа)] правильно сконфигурирован - он поможет заблокировать ресурсам некоторые потенциально опасные функции.
* Никогда не выдавайте админ-права ресурсам (включая карты), полученным из неизвестных источников.
* Перед запуском недоверенного ресурса, изучите:
** Его [https://wiki.multitheftauto.com/wiki/Meta.xml meta.xml], на наличие возможных скрытых скриптов, которые скрываются под видом файлов с другими расширениями.
** Его исходный код, на наличие вредоносной логики.
* Не запускайте и не используйте скомпилированные ресурсы (скрипты), в легитимности которых вы не уверены.

'''Чтобы минимизировать урон, причиненный читером, зашедшим на сервер:'''
* При создании скриптов '''никогда не доверяйте данным, полученным со стороны клиента'''.
* При просмотре скриптов на наличие дыр безопасности, сверяйтесь с данными, поступающими от клиента, которому можно доверять.
* Отправлены могут быть любые данные, поэтому любые серверные скрипты, которые коммуницируют с клиентскими и получают информацию от игроков, '''должны проверять информацию на корректность''' перед дальнейшим использованием. Подделка данных чаще всего происходит с помощью [[setElementData]] и [[triggerServerEvent]].
* Вы не должны полагаться только на [https://wiki.multitheftauto.com/wiki/Serial серийный номер] игрока, когда он используется для критических действий (авто-входа/администраторских действий). '''Не гарантируется, что серийный номер игрока уникален и не подделан'''. Это причина, почему вы должны '''поместить его за''' системой аккаунтов, в качестве '''важного аутентификационного фактора'''.
* Серверная логика '''не может быть обойдена''' (если только сервер не взломан или в коде нет ошибки, но это совсем другой сценарий.) - '''используйте это в своих интересах'''. В большинстве случаев, вы можете реализовать проверки безопасности только на серверной стороне, не привлекая клиент.
* Следование аксиоме '''''“Все параметры, включая source могут быть подделаны и им нельзя доверять. Глобальной переменной client можно доверять.”''''' дает вам уверенность в том, что игрок, к которому вы обращаетесь (через переменную '''client''') '''именно тот, кто вызвал событие'''. Это защищает вас от тех ситуаций, когда читер может вызывать, например, админские события (например, кик/бан игрока), указывая реального администратора ('''второй''' аргумент '''[[triggerServerEvent]]'''), или вызывать события за других игроков (будто они вызвали их, но в реальности это сделал читер) - всего лишь из-за использования некорректной переменной. Чтобы убедиться, что вы это поняли, обратимся к коду:

<syntaxhighlight lang="lua">
--[[
НИКОГДА НЕ ИСПОЛЬЗУЙТЕ ЭТОТ КОД - ОН АБСОЛЮТНО НЕВЕРНЫЙ И НЕБЕЗОПАСНЫЙ
ПРОБЛЕМА: ИСПОЛЬЗУЯ ПЕРЕМЕННУЮ 'source' В hasObjectPermissionTo ВЫ ОСТАВЛЯЕТЕ ДЫРУ ДЛЯ ЧИТЕРОВ
]]

function onServerWrongAdminEvent(playerToBan)
if (not client) then -- 'client' указывает на игрока, который вызвал событие, и должен использоваться в качестве проверки безопасности (для предотвращения подмены игрока)
return false -- если эта переменная не существует (по неизвестной причине), останавливаем выполнение кода
end

local defaultPermission = false -- по стандарту не разрешаем действие, сморите: https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo
local canAdminBanPlayer = hasObjectPermissionTo(source, "function.banPlayer", defaultPermission) -- эксплойт находится здесь...

if (not canAdminBanPlayer) then -- если у игрока нет прав
return false -- останавливаем выполнение кода
end

local validElement = isElement(playerToBan) -- проверяем, что аргумент, переданный игроком, является элементом
if (not validElement) then -- если нет...
return false -- останавливаем выполнение кода
end

local elementType = getElementType(playerToBan) -- это элемент, получаем его тип
local playerType = (elementType == "player") -- проверяем, что тип элемента - игрок

if (not playerType) then -- это не игрок
return false -- останавливаемся
end

-- banPlayer(...) -- делаем, что нужно
end
addEvent("onServerWrongAdminEvent", true)
addEventHandler("onServerWrongAdminEvent", root, onServerWrongAdminEvent)

--[[
onServerCorrectAdminEvent ПРЕКРАСНО ЗАЩИЩЕН, ТАК, КАК ДОЛЖНО БЫТЬ
ЗДЕСЬ НЕТ ПРОБЛЕМ: МЫ ИСПОЛЬЗУЕМ 'client' В hasObjectPermissionTo, ЧТО ЗАЩИЩАЕТ НАС ОТ ПОДМЕНЫ ИГРОКА, КОТОРЫЙ ВЫЗВАЛ СОБЫТИЕ
]]--

function onServerCorrectAdminEvent(playerToBan)
if (not client) then -- 'client' указывает на игрока, который вызвал событие, и должен использоваться в качестве проверки безопасности (для предотвращения подмены игрока)
return false -- если эта переменная не существует (по неизвестной причине), останавливаем выполнение кода
end

local defaultPermission = false -- по стандарту не разрешаем действие, сморите: https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo
local canAdminBanPlayer = hasObjectPermissionTo(client, "function.banPlayer", defaultPermission) -- если игрок имеет права

if (not canAdminBanPlayer) then -- если у игрока нет прав
return false -- останавливаем выполнение кода
end

local validElement = isElement(playerToBan) -- проверяем, что аргумент, переданный игроком, является элементом
if (not validElement) then -- если нет...
return false -- останавливаем выполнение кода
end

local elementType = getElementType(playerToBan) -- это элемент, получаем его тип
local playerType = (elementType == "player") -- проверяем, что тип элемента - игрок

if (not playerType) then -- это не игрок
return false -- останавливаемся
end

-- banPlayer(...) -- делаем, что нужно
end
addEvent("onServerCorrectAdminEvent", true)
addEventHandler("onServerCorrectAdminEvent", root, onServerCorrectAdminEvent)
</syntaxhighlight>

==Securing setElementData==

* You should refrain from using [[element data]] everywhere, it should be only used when really necessary. It is advised to replace it with [[triggerClientEvent]] instead.
* If you still insist on using it, it is recommended to set '''4th''' argument in [[setElementData]] to '''false''' (disabling sync for this, certain data) and use subscriber mode - [[addElementDataSubscriber]], for both security & performance reasons described in [https://wiki.multitheftauto.com/wiki/Script_security#Securing_triggerServerEvent event section.]
{{Important Note|Disabling sync however, doesn't fully protect data key. It would be still vulnerable by default, but in this case you are not leaving it in plain sight. Using [[getAllElementData]] or digging in RAM wouldn't expose it, since it won't be synced to client in first place. Therefore, it needs to be added to anti-cheat as well.}}
* All parameters including '''source''' can be faked and should not be trusted.
* Global variable '''client''' can be trusted.

----------
<section name="Server" class="server" show="true">
Example of basic element data anti-cheat.
<syntaxhighlight lang="lua">
local function reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue) -- helper function to log and revert changes
local logClient = inspect(clientElement) -- in-depth view of player which forced element data sync
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = tostring(sourceElement) -- element which received data
local logOldValue = tostring(oldValue) -- old value
local logNewValue = tostring(newValue) -- new value
local logText = -- fill our report with data
"=======================================\n"..
"Detected element data abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Data key: "..dataKey.."\n"..
"Old data value: "..logOldValue.."\n"..
"New data value: "..logNewValue.."\n"..
"======================================="

local logVisibleTo = root -- specify who will see this log in console, in this case each player connected to server
local hadData = (oldValue ~= nil) -- check if element had such data before

if (hadData) then -- if element had such data before
setElementData(sourceElement, dataKey, oldValue, true) -- revert changes, it will call onElementDataChange event, but will fail (stop) on first condition - because server (not client) forced change
else
removeElementData(sourceElement, dataKey) -- remove it completely
end

outputConsole(logText, logVisibleTo) -- print it to console

return true -- all success
end

function onElementDataChangeBasicAC(dataKey, oldValue, newValue) -- the heart of our anti-cheat, which does all the magic security measurements
if (not client) then -- check if data is coming from client
return false -- if it's not, do not go further
end

local checkSpecialThing = (dataKey == "special_thing") -- compare whether dataKey matches "special_thing"
local checkFlagWaving = (dataKey == "flag_waving") -- compare whether dataKey matches "flag_waving"

if (checkSpecialThing) then -- if it does, do our security checks
local invalidElement = (client ~= source) -- verify whether source element is different from player which changed data

if (invalidElement) then -- if it's so
reportAndRevertDataChange(client, source, dataKey, oldValue, newValue) -- revert data change, because "special_thing" can only be set for player himself
end
end

if (checkFlagWaving) then -- if it does, do our security checks
local playerVehicle = getPedOccupiedVehicle(client) -- get player's current vehicle
local invalidVehicle = (playerVehicle ~= source) -- verify whether source element is different from player's vehicle

if (invalidVehicle) then -- if it's so
reportAndRevertDataChange(client, source, dataKey, oldValue, newValue) -- revert data change, because "flag_waving" can only be set for player's own vehicle
end
end
end
addEventHandler("onElementDataChange", root, onElementDataChangeBasicAC)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
Example of advanced element data anti-cheat.
<syntaxhighlight lang="lua">
--[[
For maximum security set punishPlayerOnDetect, punishmentBan, allowOnlyProtectedKeys to true (as per default configuration)
If allowOnlyProtectedKeys is enabled, do not forget to add every client-side element data key to protectedKeys table - otherwise you will face false-positives

Anti-cheat (handleDataChange) table structure and it's options:

["keyName"] = { -- name of key which would be protected
onlyForPlayerHimself = true, -- enabling this (true) will make sure that this element data key can only be set on player who synced it (ignores onlyForOwnPlayerVeh and allowForElements), use false/nil to disable this
onlyForOwnPlayerVeh = false, -- enabling this (true) will make sure that this element data key can only be set on player's current vehicle who synced it (ignores allowForElements), use false/nil to disable this
allowForElements = { -- restrict this key for certain element type(s), set to false/nil or leave it empty to not check this (full list of element types: https://wiki.multitheftauto.com/wiki/GetElementsByType)
["player"] = true,
["ped"] = true,
["vehicle"] = true,
["object"] = true,
},
allowedDataTypes = { -- restrict this key for certain value type(s), set to false/nil or leave it empty to not check this
["string"] = true,
["number"] = true,
["table"] = true,
["boolean"] = true,
["nil"] = true,
},
allowedStringLength = {1, 32}, -- if value is a string, then it's length must be in between (min-max), set it to false/nil to not check string length - do note that allowedDataTypes must contain ["string"] = true
allowedTableLength = {1, 64}, -- if value is a table, then it's length must be in between (min-max), set it to false/nil to not check table length - do note that allowedDataTypes must contain ["table"] = true
allowedNumberRange = {1, 128}, -- if value is a number, then it must be in between (min-max), set it to false/nil to not check number range - do note that allowedDataTypes must contain ["number"] = true
}
]]

local punishPlayerOnDetect = true -- should player be punished upon detection (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Altering element data" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local allowOnlyProtectedKeys = true -- disallow (remove by using removeElementData) every element data besides those given in protectedKeys table; in case someone wanted to flood server with garbage keys, which would be kept in memory until server restart or manual remove - setElementData(source, key, nil) won't remove it; it has to be removeElementData
local debugLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugR = 255 -- debug message - red color
local debugG = 127 -- debug message - green color
local debugB = 0 -- debug message - blue color
local protectedKeys = {
["vehicleNumber"] = { -- we want vehicleNumber to be set only on vehicles, with stricte numbers in range of 1-100
allowForElements = {
["vehicle"] = true,
},
allowedDataTypes = {
["number"] = true,
},
allowedNumberRange = {1, 100},
},
["personalVehData"] = { -- we want be able to set personalVehData only on current vehicle, also it should be a string with length between 1-24
onlyForOwnPlayerVeh = true,
allowedDataTypes = {
["string"] = true,
},
allowedStringLength = {1, 24},
},
-- perform security checks on keys stored in this table, in a convenient way
}

local function reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- helper function to log and revert changes
local logClient = inspect(clientElement) -- in-depth view of player which forced element data sync
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = inspect(sourceElement) -- in-depth view of element which received data
local logOldValue = inspect(oldValue) -- in-depth view of old value
local logNewValue = inspect(newValue) -- in-depth view of new value
local logText = -- fill our report with data
"*\n"..
"Detected element data abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Data key: "..dataKey.."\n"..
"Old data value: "..logOldValue.."\n"..
"New data value: "..logNewValue.."\n"..
"Fail reason: "..failReason.."\n"..
"*"

outputDebugString(logText, debugLevel, debugR, debugG, debugB) -- print it to debug

if (forceRemove) then -- we don't want this element data key to exist at all
removeElementData(sourceElement, dataKey) -- remove it

return true -- return success and stop here, we don't need further checks
end

setElementData(sourceElement, dataKey, oldValue, true) -- revert changes, it will call onElementDataChange event, but will fail (stop) on first condition - because server (not client) forced change

return true -- return success
end

local function handleDataChange(clientElement, sourceElement, dataKey, oldValue, newValue) -- the heart of our anti-cheat, which does all the magic security measurements, returns true if there was no altering from client (based on data from protectedKeys), false otherwise
local protectedKey = protectedKeys[dataKey] -- look up whether key changed is stored in protectedKeys table

if (not protectedKey) then -- if it's not

if (allowOnlyProtectedKeys) then -- if we don't want garbage keys
local failReason = "Key isn't present in protectedKeys" -- reason shown in report
local forceRemove = true -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end

return true -- this key isn't protected, let it through
end

local onlyForPlayerHimself = protectedKey.onlyForPlayerHimself -- if key has "self-set" lock
local onlyForOwnPlayerVeh = protectedKey.onlyForOwnPlayerVeh -- if key has "self-vehicle" lock
local allowForElements = protectedKey.allowForElements -- if key has element type check
local allowedDataTypes = protectedKey.allowedDataTypes -- if key has allowed data type check

if (onlyForPlayerHimself) then -- if "self-set" lock is active
local matchingElement = (clientElement == sourceElement) -- verify whether player who set data is equal to element which received data

if (not matchingElement) then -- if it's not matching
local failReason = "Can only set on player himself" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (onlyForOwnPlayerVeh) then -- if "self-vehicle" lock is active
local playerVehicle = getPedOccupiedVehicle(clientElement) -- get current vehicle of player which set data
local matchingVehicle = (playerVehicle == sourceElement) -- check whether it matches the one which received data

if (not matchingVehicle) then -- if it doesn't match
local failReason = "Can only set on player's own vehicle" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowForElements) then -- check if it's one of them
local elementType = getElementType(sourceElement) -- get type of element whose data changed
local matchingElementType = allowForElements[elementType] -- verify whether it's allowed

if (not matchingElementType) then -- this isn't matching
local failReason = "Invalid element type" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedDataTypes) then -- if there's allowed data types
local valueType = type(newValue) -- get data type of value
local matchingType = allowedDataTypes[valueType] -- check if it's one of allowed

if (not matchingType) then -- if it's not then
local failReason = "Invalid data type" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end

local allowedStringLength = protectedKey.allowedStringLength -- if key has specified string length check
local dataString = (valueType == "string") -- make sure it's a string

if (allowedStringLength and dataString) then -- if we should check string length
local minLength = allowedStringLength[1] -- retrieve min length
local maxLength = allowedStringLength[2] -- retrieve max length
local stringLength = utf8.len(newValue) -- get length of data string
local matchingLength = (stringLength >= minLength) and (stringLength <= maxLength) -- compare whether value fits in between

if (not matchingLength) then -- if it doesn't
local failReason = "Invalid string length (must be between "..minLength.."-"..maxLength..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedTableLength = protectedKey.allowedTableLength -- if key has table length check
local dataTable = (valueType == "table") -- make sure it's a table

if (allowedTableLength and dataTable) then -- if we should check table length
local minLength = allowedTableLength[1] -- retrieve min length
local maxLength = allowedTableLength[2] -- retrieve max length
local minLengthAchieved = false -- variable which checks 'does minimum length was achieved'
local maxLengthExceeded = false -- variable which checks 'does length has exceeds more than allowed maximum'
local tableLength = 0 -- store initial table length

for _, _ in pairs(newValue) do -- loop through whole table
tableLength = (tableLength + 1) -- add + 1 on each table entry
minLengthAchieved = (tableLength >= minLength) -- is length bigger or at very minimum we require
maxLengthExceeded = (tableLength > maxLength) -- does table exceeded more than max length?

if (maxLengthExceeded) then -- it is bigger than it should be
break -- break the loop (due of condition above being worthy, it makes no point to count further and waste CPU, on a table which potentially could have huge amount of entries)
end
end

local matchingLength = (minLengthAchieved and not maxLengthExceeded) -- check if min length has been achieved, and make sure that it doesn't go beyond max length

if (not matchingLength) then -- this table doesn't match requirements
local failReason = "Invalid table length (must be between "..minLength.."-"..maxLength..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedNumberRange = protectedKey.allowedNumberRange -- if key has allowed number range check
local dataNumber = (valueType == "number") -- make sure it's a number

if (allowedNumberRange and dataNumber) then -- if we should check number range
local minRange = allowedNumberRange[1] -- retrieve min number range
local maxRange = allowedNumberRange[2] -- retrieve max number range
local matchingRange = (newValue >= minRange) and (newValue <= maxRange) -- compare whether value fits in between

if (not matchingRange) then -- if it doesn't
local failReason = "Invalid number range (must be between "..minRange.."-"..maxRange..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end
end

return true -- security checks passed, we are all clear with this data key
end

function onElementDataChangeAdvancedAC(dataKey, oldValue, newValue) -- this event makes use of handleDataChange, the code was split for better readability
if (not client) then -- check if data is coming from client
return false -- if it's not, do not continue
end

local approvedChange = handleDataChange(client, source, dataKey, oldValue, newValue) -- run our security checks

if (approvedChange) then -- it's all cool and good
return false -- we don't need further action
end

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(client, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(client, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onElementDataChange", root, onElementDataChangeAdvancedAC)
</syntaxhighlight>
</section>

==Securing triggerServerEvent==

* All parameters including '''source''' can be faked and should not be trusted.
* Global variable '''client''' can be trusted.
* '''Admin''' styled '''events''' should be verifying player (client) '''ACL rights''', either by [https://wiki.multitheftauto.com/wiki/IsObjectInACLGroup isObjectInACLGroup] or [https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo hasObjectPermissionTo].
* Do '''not''' use the same name for your custom event as MTA native server events (which aren't remotely triggerable by default), e.g: '''onPlayerLogin'''; doing so would open door for cheaters manipulations.
* Be aware to which players event is sent via [[triggerClientEvent]]. For both security & performance reasons, admin like events should be received by admins only (to prevent confidential data being accessed), in the same time you shouldn't send each event to everyone on server (e.g: login success event which hides login panel for certain player). [[triggerClientEvent]] allows you to specify the event receiver as first (optional) argument. It defaults to [[root]], meaning if you don't specify it, it will be sent to everyone connected to server - even those who are still downloading server cache (which results in ''Server triggered clientside event eventName, but event is not added clientside.''). You can either pass player element or table with receivers:
<syntaxhighlight lang="lua">
local playersToReceiveEvent = {player1, player2, player3} -- each playerX is player element

triggerClientEvent(playersToReceiveEvent, ...) -- do not forget to fill the latter part of arguments
</syntaxhighlight>

----------
<section name="Server" class="server" show="true">
Example of anti-cheat function designed for events, used for data validation for both normal, and admin events which are called from client-side.
<syntaxhighlight lang="lua">
--[[
For maximum security set punishPlayerOnDetect, punishmentBan to true (as per default configuration)

Anti-cheat (processServerEventData) table structure and it's options:

checkACLGroup = { -- check whether player who called event belongs to at least one group below, set to false/nil to not check this
"Admin",
},
checkPermissions = { -- check whether player who called event has permission to at least one thing below, set to false/nil to not check this
"function.kickPlayer",
},
checkEventData = {
{
debugData = "source", -- optional details for report shown in debug message
eventData = source, -- data we want to verify
equalTo = client, -- compare whether eventData == equalTo
allowedElements = { -- restrict eventData to be certain element type(s), set to false/nil or leave it empty to not check this (full list of element types: https://wiki.multitheftauto.com/wiki/GetElementsByType)
["player"] = true,
["ped"] = true,
["vehicle"] = true,
["object"] = true,
},
allowedDataTypes = { -- restrict eventData to be certain value type(s), set to false/nil or leave it empty to not check this
["string"] = true,
["number"] = true,
["table"] = true,
["boolean"] = true,
["nil"] = true,
},
allowedStringLength = {1, 32}, -- if eventData is a string, then it's length must be in between (min-max), set it to false/nil to not check string length - do note that allowedDataTypes must contain ["string"] = true
allowedTableLength = {1, 64}, -- if eventData is a table, then it's length must be in between (min-max), set it to false/nil to not check table length - do note that allowedDataTypes must contain ["table"] = true
allowedNumberRange = {1, 128}, -- if eventData is a number, then it must be in between (min-max), set it to false/nil to not check number range - do note that allowedDataTypes must contain ["number"] = true
},
},
]]

local punishPlayerOnDetect = true -- should player be punished upon detection (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Altering server event data" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugR = 255 -- debug message - red color
local debugG = 127 -- debug message - green color
local debugB = 0 -- debug message - blue color

function processServerEventData(clientElement, sourceElement, serverEvent, securityChecks) -- the heart of our anti-cheat, which does all the magic security measurements, returns true if there was no altering from client (based on data from securityChecks), false otherwise
if (not securityChecks) then -- if we haven't passed any security checks
return true -- nothing to check, let code go further
end

if (not clientElement) then -- if client variable isn't available for some reason (although it should never happen)
local failReason = "Client variable not present" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local checkACLGroup = securityChecks.checkACLGroup -- if there's any ACL groups to check
local checkPermissions = securityChecks.checkPermissions -- if there's any permissions to check
local checkEventData = securityChecks.checkEventData -- if there's any data checks

if (checkACLGroup) then -- let's check player ACL groups
local playerAccount = getPlayerAccount(clientElement) -- get current account of player
local guestAccount = isGuestAccount(playerAccount) -- if account is guest (meaning player is not logged in)

if (guestAccount) then -- it's the case
local failReason = "Can't retrieve player login - guest account" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local accountName = getAccountName(playerAccount) -- get name of player's current account
local aclString = "user."..accountName -- format it for further use in isObjectInACLGroup function

for groupID = 1, #checkACLGroup do -- iterate over table of given groups
local groupName = checkACLGroup[groupID] -- get each group name
local aclGroup = aclGetGroup(groupName) -- check if such group exists

if (not aclGroup) then -- it doesn't
local failReason = "ACL group '"..groupName.."' is missing" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local playerInACLGroup = isObjectInACLGroup(aclString, aclGroup) -- check if player belong to the group

if (playerInACLGroup) then -- yep, it's the case
return true -- so it's a success
end
end

local failReason = "Player doesn't belong to any given ACL group" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

if (checkPermissions) then -- check if player has at least one desired permission
local allowedByDefault = false -- does he have access by default

for permissionID = 1, #checkPermissions do -- iterate over all permissions
local permissionName = checkPermissions[permissionID] -- get permission name
local hasPermission = hasObjectPermissionTo(clientElement, permissionName, allowedByDefault) -- check whether player is allowed to perform certain action

if (hasPermission) then -- if player has access
return true -- one is available (and enough), server won't bother to check others (as return keywords also breaks loop)
end
end

local failReason = "Not enough permissions" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

if (checkEventData) then -- if there is some data to verify

for dataID = 1, #checkEventData do -- iterate over each of data
local dataToCheck = checkEventData[dataID] -- get each data set
local eventData = dataToCheck.eventData -- this is the one we'll be verifying
local equalTo = dataToCheck.equalTo -- we want to compare whether eventData == equalTo
local allowedElements = dataToCheck.allowedElements -- check whether is element, and whether belongs to certain element types
local allowedDataTypes = dataToCheck.allowedDataTypes -- do we restrict data to be certain type?
local debugData = dataToCheck.debugData -- additional helper data
local debugText = debugData and " ("..debugData..")" or "" -- if it's present, format it nicely

if (equalTo) then -- equal check exists
local matchingData = (eventData == equalTo) -- compare whether those two values are equal

if (not matchingData) then -- they aren't
local failReason = "Data isn't equal @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedElements) then -- we do check whether is an element, and belongs to at least one given in the list
local validElement = isElement(eventData) -- check if it's actual element

if (not validElement) then -- it's not
local failReason = "Data isn't element @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local elementType = getElementType(eventData) -- it's element, so we want to know it's type
local matchingElementType = allowedElements[elementType] -- verify whether it's allowed

if (not matchingElementType) then -- it's not allowed
local failReason = "Invalid element type @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedDataTypes) then -- let's check allowed data types
local dataType = type(eventData) -- get data type
local matchingType = allowedDataTypes[dataType] -- verify whether it's allowed

if (not matchingType) then -- it isn't
local failReason = "Invalid data type @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local allowedStringLength = dataToCheck.allowedStringLength -- if data has string length check
local dataString = (dataType == "string") -- make sure it's a string

if (allowedStringLength and dataString) then -- if we should check string length
local minLength = allowedStringLength[1] -- retrieve min length
local maxLength = allowedStringLength[2] -- retrieve max length
local stringLength = utf8.len(eventData) -- get length of data string
local matchingLength = (stringLength >= minLength) and (stringLength <= maxLength) -- compare whether value fits in between

if (not matchingLength) then -- if it doesn't
local failReason = "Invalid string length (must be between "..minLength.."-"..maxLength..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedTableLength = dataToCheck.allowedTableLength -- if data has table length check
local dataTable = (dataType == "table") -- make sure it's a table

if (allowedTableLength and dataTable) then -- if we should check table length
local minLength = allowedTableLength[1] -- retrieve min length
local maxLength = allowedTableLength[2] -- retrieve max length
local minLengthAchieved = false -- variable which checks 'does minimum length was achieved'
local maxLengthExceeded = false -- variable which checks 'does length has exceeds more than allowed maximum'
local tableLength = 0 -- store initial table length

for _, _ in pairs(eventData) do -- loop through whole table
tableLength = (tableLength + 1) -- add + 1 on each table entry
minLengthAchieved = (tableLength >= minLength) -- is length bigger or at very minimum we require
maxLengthExceeded = (tableLength > maxLength) -- does table exceeded more than max length?

if (maxLengthExceeded) then -- it is bigger than it should be
break -- break the loop (due of condition above being worthy, it makes no point to count further and waste CPU, on a table which potentially could have huge amount of entries)
end
end

local matchingLength = (minLengthAchieved and not maxLengthExceeded) -- check if min length has been achieved, and make sure that it doesn't go beyond max length

if (not matchingLength) then -- this table doesn't match requirements
local failReason = "Invalid table length (must be between "..minLength.."-"..maxLength..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedNumberRange = dataToCheck.allowedNumberRange -- if data has number range check
local dataNumber = (dataType == "number") -- make sure it's a number

if (allowedNumberRange and dataNumber) then -- if we should check number range
local minRange = allowedNumberRange[1] -- retrieve min number range
local maxRange = allowedNumberRange[2] -- retrieve max number range
local matchingRange = (eventData >= minRange) and (eventData <= maxRange) -- compare whether value fits in between

if (not matchingRange) then -- if it doesn't
local failReason = "Invalid number range (must be between "..minRange.."-"..maxRange..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end
end
end
end

return true -- security checks passed, we are all clear with this event call
end

function reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- helper function to log and handle accidents
local logClient = inspect(clientElement) -- in-depth view player which called event
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = inspect(sourceElement) -- in-depth view of source element
local logText = -- fill our report with data
"*\n"..
"Detected event abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Event: "..serverEvent.."\n"..
"Reason: "..failReason.."\n"..
"*"

outputDebugString(logText, debugLevel, debugR, debugG, debugB) -- print it to debug

if (not punishPlayerOnDetect or skipPunishment) then -- we don't want to punish player for some reason
return true -- stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(clientElement, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(clientElement, punishedBy, punishmentReason) -- simply kick player out of server
end

return true -- all done, report success
end

function onServerEvent(clientData)
--[[
Assume this server event (function) is called in such way:

local dataToPass = 10

triggerServerEvent("onServerEvent", localPlayer, dataToPass)
]]

local shouldProcessServerCode = processServerEventData(
client, -- client element - responsible for calling event
source, -- source element - passed in triggerServerEvent (as 2nd argument)
eventName, -- name of event - in this case 'onServerEvent'
{
checkEventData = { -- we want to verify everything what comes from client
{
eventData = source, -- first to check, source variable
equalTo = client, -- we want to check whether it matches player who called event
debugData = "source", -- helper details which would be shown in report
},
{
eventData = clientData, -- let's check the data which client sent to us
allowedDataTypes = {
["number"] = true, -- we want it to be only number
},
allowedNumberRange = {1, 100}, -- in range of 1 to 100
debugData = "clientData", -- if something goes wrong, let server know where (it will appear in debug report)
},
},
}
)

if (not shouldProcessServerCode) then -- something isn't right, no green light for processing code behind this scope
return false -- stop code execution
end

-- do code as usual
end
addEvent("onServerEvent", true)
addEventHandler("onServerEvent", root, onServerEvent)

function onServerAdminEvent(playerToBan)
--[[
Assume this server admin event (function) is called in such way:

local playerToBan = getPlayerFromName("playerToBan")

triggerServerEvent("onServerAdminEvent", localPlayer, playerToBan)
]]

local shouldProcessServerCode = processServerEventData(
client, -- client element - responsible for calling event
source, -- source element - passed in triggerServerEvent (as 2nd argument)
eventName, -- name of event - in this case 'onServerAdminEvent'
{
checkACLGroup = { -- we need to check whether player who called event belongs to ACL groups
"Admin", -- in this case admin group
},
checkEventData = { -- we want to verify everything what comes from client
{
eventData = source, -- first to check, source variable
equalTo = client, -- we want to check whether it matches player who called event
debugData = "source", -- helper details which would be shown in report
},
{
eventData = playerToBan, -- let's check the data which client sent to us
allowedDataTypes = {
["player"] = true, -- we want it to be player
},
debugData = "playerToBan", -- if something goes wrong, let server know where (it will appear in debug report)
},
},
}
)

if (not shouldProcessServerCode) then -- something isn't right, no green light for processing code behind this scope
return false -- stop code execution
end

-- do code as usual
end
addEvent("onServerAdminEvent", true)
addEventHandler("onServerAdminEvent", root, onServerAdminEvent)
</syntaxhighlight>
</section>

==Securing server-only events==
* It is very important to '''disable remote triggering''' ability in [https://wiki.multitheftauto.com/wiki/AddEvent addEvent], to prevent calling server-side only events from client-side.
* '''Admin''' styled '''events''' should be verifying player '''ACL rights''', either by [https://wiki.multitheftauto.com/wiki/IsObjectInACLGroup isObjectInACLGroup] or [https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo hasObjectPermissionTo].

----------
<section name="Server" class="server" show="true">
This example shows how you should make event server-side only.
<syntaxhighlight lang="lua">
function onServerSideOnlyEvent()
-- do some server-side stuff
end
addEvent("onServerSideOnlyEvent", false) -- set second argument (allowRemoteTriger) to false, so it can't be called from client
addEventHandler("onServerSideOnlyEvent", root, onServerSideOnlyEvent) -- associate our event with function onServerSideOnlyEvent
</syntaxhighlight>
</section>

==Securing projectiles & explosions==
This section (and '''code''' is '''work in progress''') - '''use at your own risk'''.

----------
<section name="Server" class="server" show="false">
Projectile ammo tracker:
<syntaxhighlight lang="lua">
local playerProjectileAmmo = {} -- store player-held weapons ammo here
local playerWeaponsToTrack = { -- keep track of ammo for certain player-held weapon types, basically those which create projectile; [weaponID] = weaponSlot
[16] = 8, -- grenade
[17] = 8, -- teargas
[18] = 8, -- molotov
[35] = 7, -- rocket launcher
[36] = 7, -- rocket launcher (heat-seeking)
[39] = 8, -- satchel charge
}

local function updateProjectileAmmoForPlayer(playerElement)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

for weaponID, weaponSlot in pairs(playerWeaponsToTrack) do
local weaponInSlot = getPedWeapon(playerElement, weaponSlot)
local weaponTotalAmmo = getPedTotalAmmo(playerElement, weaponSlot)
local weaponHasAmmo = (weaponTotalAmmo > 0)
local weaponMatching = (weaponInSlot == weaponID)
local updateWeaponAmmo = (weaponMatching and weaponHasAmmo)

if (updateWeaponAmmo) then
local storedProjectileAmmo = playerProjectileAmmo[playerElement]
local newWeaponAmmo = (updateWeaponAmmo and weaponTotalAmmo or nil)

if (not storedProjectileAmmo) then
playerProjectileAmmo[playerElement] = {}
storedProjectileAmmo = playerProjectileAmmo[playerElement]
end

storedProjectileAmmo[weaponID] = newWeaponAmmo
end
end

return true
end

function hasPlayerProjectileAmmo(playerElement, projectileWeapon)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

local projectileData = playerProjectileAmmo[playerElement]
local projectileAmmo = (projectileData and projectileData[projectileWeapon])

return projectileAmmo
end

function decreasePlayerProjectileAmmo(playerElement, projectileWeapon)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

local playerProjectileData = playerProjectileAmmo[playerElement]

if (not playerProjectileData) then
return false
end

local projectileWeaponAmmo = playerProjectileData[projectileWeapon]
local tempProjectileAmmo = (projectileWeaponAmmo - 1)
local newProjectileAmmo = (tempProjectileAmmo > 0 and tempProjectileAmmo or nil)

playerProjectileData[projectileWeapon] = newProjectileAmmo

return true
end

function onPlayerWeaponSwitchAntiCheat(previousWeaponID, currentWeaponID)
setTimer(updateProjectileAmmoForPlayer, 50, 1, source)
end
addEventHandler("onPlayerWeaponSwitch", root, onPlayerWeaponSwitchAntiCheat)

function onResourceStartAntiCheat()
local playersTable = getElementsByType("player")

for playerID = 1, #playersTable do
local playerElement = playersTable[playerID]

updateProjectileAmmoForPlayer(playerElement)
end
end
addEventHandler("onResourceStart", resourceRoot, onResourceStartAntiCheat)

function onPlayerWastedQuitAntiCheat()
playerProjectileAmmo[source] = nil
end
addEventHandler("onPlayerWasted", root, onPlayerWastedQuitAntiCheat)
addEventHandler("onPlayerQuit", root, onPlayerWastedQuitAntiCheat)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
Projectile handler:
<syntaxhighlight lang="lua">
local playerCreatedProjectiles = {} -- store count of legitimately created player projectiles; [playerElement] = {[projectileType] = activeProjectiles}
local projectileTypes = {
[16] = { -- Grenade
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[16] = true, -- grenade
},
},
[17] = { -- Teargas
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[17] = true, -- teargas
},
},
[18] = { -- Molotov
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[18] = true, -- molotov
},
},
[19] = { -- Rocket
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileMaxVelocity = 2,
projectileAllowedWeapons = {
[35] = true, -- rocket launcher
},
projectileAllowedVehicles = {
[425] = true, -- hunter
[520] = true, -- hydra
},
},
[20] = { -- Rocket (heat-seeking)
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileMaxVelocity = 2,
projectileAllowedWeapons = {
[36] = true, -- rocket launcher (heat-seeking)
},
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
[21] = { -- Airbomb
projectileAllowed = true,
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
[39] = { -- Satchel charge
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[39] = true, -- satchel charge
},
},
[58] = { -- Hydra flare
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
}

local reportAbnormality = true -- whether to report about abnormality in debug script - by default
local punishPlayerOnDetect = false -- should player be punished upon detection; true - yes, or false to not do anything (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Projectile/explosion anti-cheat" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugMsgLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugMsgR = 255 -- debug message - red color
local debugMsgG = 127 -- debug message - green color
local debugMsgB = 0 -- debug message - blue color

local function reportProjectileAbnormality(playerElement, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ, detectionCode)
local projectileSyncer = inspect(playerElement)
local projectilePosition = projectileX..", "..projectileY..", "..projectileZ
local projectileZoneName = getZoneName(projectileX, projectileY, projectileZ, false)
local projectileCityName = getZoneName(projectileX, projectileY, projectileZ, true)
local projectileLog =
"* Detected projectile abnormality - "..detectionCode.." *\n"..
"Projectile syncer: "..projectileSyncer.."\n"..
"Projectile type: "..projectileType.."\n"..
"Projectile position: "..projectilePosition.. " ("..projectileZoneName..", "..projectileCityName..")\n"

outputDebugString(projectileLog, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)

return true
end

local function processProjectileChecks(playerElement, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)
local projectileData = projectileTypes[projectileType]
local projectileAllowed = projectileData.projectileAllowed

if (not projectileAllowed) then
return false, "Projectile not allowed"
end

local projectileAllowedWeapons = projectileData.projectileAllowedWeapons

if (projectileAllowedWeapons) then
local playerWeapon = getPedWeapon(playerElement)
local allowedWeapon = projectileAllowedWeapons[playerWeapon]

if (not allowedWeapon) then
return false, "Player is not holding correct weapon"
end

local weaponAmmo = hasPlayerProjectileAmmo(playerElement, playerWeapon)
local playerHasAmmo = (weaponAmmo > 0)

if (not playerHasAmmo) then
return false, "Player doesn't have ammo for weapon"
end

decreasePlayerProjectileAmmo(playerElement, playerWeapon)
end

local playerVehicle = getPedOccupiedVehicle(playerElement)

if (playerVehicle) then
local projectileAllowedVehicles = projectileData.projectileAllowedVehicles

if (projectileAllowedVehicles) then
local vehicleModel = getElementModel(playerVehicle)
local allowedVehicle = projectileAllowedVehicles[vehicleModel]

if (not allowedVehicle) then
return false, "Player is not inside allowed vehicles"
end

local vehicleDriver = getVehicleController(playerVehicle)
local playerDriver = (playerElement == vehicleDriver)

if (not playerDriver) then
return false, "Player is not vehicle driver"
end

return true
end

return false, "Player in vehicle"
end

local projectileMaxDistanceFromCreator = projectileData.projectileMaxDistanceFromCreator

if (projectileMaxDistanceFromCreator) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToProjectile = getDistanceBetweenPoints3D(playerX, playerY, playerZ, projectileX, projectileY, projectileZ)
local matchingProjectileDistance = (distanceToProjectile <= projectileMaxDistanceFromCreator)

if (not matchingProjectileDistance) then
return false, "Projectile distance mismatch"
end
end

local projectileMaxVelocity = projectileData.projectileMaxVelocity

if (projectileMaxVelocity) then
local projectileVelocity = (projectileVX ^ 2 + projectileVY ^ 2 + projectileVZ ^ 2)
local projectileSpeed = math.sqrt(projectileVelocity)
local matchingProjectileVelocity = (projectileSpeed <= projectileMaxVelocity)

if (not matchingProjectileVelocity) then
return false, "Projectile velocity mismatch"
end
end

return true
end

local function trackPlayerProjectile(playerElement, projectileID)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerProjectiles = playerCreatedProjectiles[playerElement]

if (not playerProjectiles) then
playerCreatedProjectiles[playerElement] = {}
playerProjectiles = playerCreatedProjectiles[playerElement]
end

local projectilesByType = playerProjectiles[projectileID] or 0
local newProjectilesCount = (projectilesByType + 1)

playerProjectiles[projectileID] = newProjectilesCount

return true
end

local function getProjectileDetectionOverwrittenBehavior(projectileType)
local projectileData = projectileTypes[projectileType]

if (not projectileData) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local projectileBehaviour = projectileData.projectileOverwriteBehaviour

if (not projectileBehaviour) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local overwriteReport = projectileBehaviour.reportAbnormality
local overwritePunish = projectileBehaviour.punishPlayerOnDetect
local overwriteBan = projectileBehaviour.punishmentBan

return overwriteReport, overwritePunish, overwriteBan
end

function decreasePlayerProjectiles(playerElement, projectileID)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerProjectiles = playerCreatedProjectiles[playerElement]

if (not playerProjectiles) then
return false, true
end

local projectilesByType = playerProjectiles[projectileID]

if (not projectilesByType) then
return false, true
end

local tempProjectilesCount = (projectilesByType - 1)
local newProjectilesCount = (tempProjectilesCount > 0 and tempProjectilesCount or nil)

playerProjectiles[projectileID] = newProjectilesCount

return true
end

function onPlayerProjectileCreationAntiCheat(projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)
local approvedProjectile, detectionCode = processProjectileChecks(source, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)

if (approvedProjectile) then
trackPlayerProjectile(source, projectileType)

return true
end

local reportAbnormality, punishPlayerOnDetect, punishmentBan = getProjectileDetectionOverwrittenBehavior(projectileType)

if (reportAbnormality) then
reportProjectileAbnormality(source, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ, detectionCode)
end

cancelEvent()

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(source, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(source, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onPlayerProjectileCreation", root, onPlayerProjectileCreationAntiCheat)

function onPlayerQuitAntiCheat()
playerCreatedProjectiles[source] = nil
end
addEventHandler("onPlayerQuit", root, onPlayerQuitAntiCheat)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
Explosions handler:
<syntaxhighlight lang="lua">
local rocketInstantExplosionDistanceThreshold = 1.55 -- distance below which only explosion will be created (and not rocket projectile, hence not calling onPlayerProjectileCreation); do not change it
local explosionTypes = { -- more specific info on explosion, and whether it is allowed
[0] = { -- Grenade
explosionAllowed = true,
explosionAllowedProjectiles = {
[16] = true, -- grenade
},
},
[1] = { -- Molotov
explosionAllowed = true,
explosionAllowedProjectiles = {
[18] = true, -- molotov
},
},
[2] = { -- Rocket
explosionAllowed = true,
explosionAllowedWeapons = {
[35] = true, -- rocket launcher
[36] = true, -- rocket launcher (heat-seeking)
},
explosionAllowedProjectiles = {
[19] = true, -- rocket
[20] = true, -- rocket (heat-seeking)
},
},
[3] = { -- Rocket weak
explosionAllowed = true,
explosionAllowedProjectiles = {
[19] = true, -- rocket
[20] = true, -- rocket (heat-seeking)
},
},
[4] = { -- Car
explosionAllowed = true,
},
[5] = { -- Car quick
explosionAllowed = true,
},
[6] = { -- Boat
explosionAllowed = true,
},
[7] = { -- Heli
explosionAllowed = true,
},
[8] = { -- Mine
explosionAllowed = true,
},
[9] = { -- Object
explosionAllowed = true,
},
[10] = { -- Tank grenade
explosionAllowed = true,
explosionMaxDistanceFromCreator = 80,
explosionAllowedVehicles = {
[432] = true,
}
},
[11] = { -- Small
explosionAllowed = true,
},
[12] = { -- Tiny
explosionAllowed = true,
},
}

local reportAbnormality = true -- whether to report about abnormality in debug script - by default
local punishPlayerOnDetect = false -- should player be punished upon detection; true - yes, or false to not do anything (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Projectile/explosion anti-cheat" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugMsgLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugMsgR = 255 -- debug message - red color
local debugMsgG = 127 -- debug message - green color
local debugMsgB = 0 -- debug message - blue color

local function reportExplosionAbnormality(playerElement, explosionType, explosionX, explosionY, explosionZ, detectionCode)
local explosionSyncer = inspect(playerElement)
local explosionType = explosionType
local explosionPosition = explosionX..", "..explosionY..", "..explosionZ
local explosionZoneName = getZoneName(explosionX, explosionY, explosionZ, false)
local explosionCityName = getZoneName(explosionX, explosionY, explosionZ, true)
local explosionLog =
"* Detected explosion abnormality - "..detectionCode.." *\n"..
"Explosion syncer: "..explosionSyncer.."\n"..
"Explosion type: "..explosionType.."\n"..
"Explosion position: "..explosionPosition.. " ("..explosionZoneName..", "..explosionCityName..")\n"

outputDebugString(explosionLog, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)

return true
end

local function processExplosionChecks(playerElement, explosionType, explosionX, explosionY, explosionZ)
local explosionData = explosionTypes[explosionType]
local explosionAllowed = explosionData.explosionAllowed

if (not explosionAllowed) then
return false, "Explosion type not allowed"
end

local rocketExplosion = (explosionType == 2)

if (rocketExplosion) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToExplosion = getDistanceBetweenPoints3D(playerX, playerY, playerZ, explosionX, explosionY, explosionZ)
local instantExplosion = (distanceToExplosion < rocketInstantExplosionDistanceThreshold)

if (instantExplosion) then
local explosionAllowedWeapons = explosionData.explosionAllowedWeapons
local playerWeapon = getPedWeapon(playerElement)
local allowedWeapon = explosionAllowedWeapons[playerWeapon]

if (not allowedWeapon) then
return false, "Player is not holding rocket launcher"
end

local weaponAmmo = hasPlayerProjectileAmmo(playerElement, playerWeapon)
local playerHasAmmo = (weaponAmmo > 0)

if (not playerHasAmmo) then
return false, "Player doesn't have ammo for rocket launcher"
end

decreasePlayerProjectileAmmo(playerElement, playerWeapon)

return true
end
end

local explosionAllowedProjectiles = explosionData.explosionAllowedProjectiles

if (explosionAllowedProjectiles) then

for projectileID, _ in pairs(explosionAllowedProjectiles) do
local atleastOneProjectile = decreasePlayerProjectiles(playerElement, projectileID)

if (atleastOneProjectile) then
return true
end
end

return false, "Explosion created without respective projectile"
end

local explosionAllowedVehicles = explosionData.explosionAllowedVehicles

if (explosionAllowedVehicles) then
local playerVehicle = getPedOccupiedVehicle(playerElement)

if (not playerVehicle) then
return false, "Player is not in vehicle"
end

local vehicleModel = getElementModel(playerVehicle)
local allowedVehicle = explosionAllowedVehicles[vehicleModel]

if (not allowedVehicle) then
return false, "Player is inside not allowed vehicles"
end

local vehicleDriver = getVehicleController(playerVehicle)
local playerDriver = (playerElement == vehicleDriver)

if (not playerDriver) then
return false, "Player is not vehicle driver"
end
end

local explosionMaxDistanceFromCreator = explosionData.explosionMaxDistanceFromCreator

if (explosionMaxDistanceFromCreator) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToExplosion = getDistanceBetweenPoints3D(playerX, playerY, playerZ, explosionX, explosionY, explosionZ)
local matchingExplosionDistance = (distanceToExplosion < explosionMaxDistanceFromCreator)

if (not matchingExplosionDistance) then
return false, "Explosion distance mismatch"
end
end

return true
end

local function getExplosionDetectionOverwrittenBehavior(explosionType)
local explosionData = explosionTypes[explosionType]

if (not explosionData) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local explosionBehaviour = explosionData.explosionOverwriteBehaviour

if (not explosionBehaviour) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local overwriteReport = explosionBehaviour.reportAbnormality
local overwritePunish = explosionBehaviour.punishPlayerOnDetect
local overwriteBan = explosionBehaviour.punishmentBan

return overwriteReport, overwritePunish, overwriteBan
end

function onExplosionAntiCheat(explosionX, explosionY, explosionZ, explosionType)
local serverSyncExplosion = (source == root)

if (serverSyncExplosion) then
return true
end

local approvedExplosion, detectionCode = processExplosionChecks(source, explosionType, explosionX, explosionY, explosionZ)

if (approvedExplosion) then
return true
end

local reportAbnormality, punishPlayerOnDetect, punishmentBan = getExplosionDetectionOverwrittenBehavior(explosionType)

if (reportAbnormality) then
reportExplosionAbnormality(source, explosionType, explosionX, explosionY, explosionZ, detectionCode)
end

cancelEvent()

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(source, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(source, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onExplosion", root, onExplosionAntiCheat)
</syntaxhighlight>
</section>

==Handling non-registered events==

See: [[onPlayerTriggerInvalidEvent]]

==Handling events spam==
See: [[onPlayerTriggerEventThreshold]]

AddDebugHook

2025-05-11T06:39:33Z

DColeman: We cannot skip 'addDebugHook' anymore

__NOTOC__
{{Server client function}}
{{New feature/item|3.0136|1.3|5939|
This function allows tracing of MTA functions and events. It should only be used when debugging scripts as it may degrade script performance.

Debug hooks are not recursive, so functions and events triggered inside the hook callback will not be traced.
}}

==Syntax==
<syntaxhighlight lang="lua">
bool addDebugHook ( string hookType, function callbackFunction [, table nameList ] )
</syntaxhighlight>

===Required Arguments===
*'''hookType:''' The type of hook to add. This can be:
** preEvent
** postEvent
** preFunction
** postFunction
{{New feature/item|3.0158|1.5.5|11856|
* preEventFunction
* postEventFunction
}}
*'''callbackFunction:''' The function to call
** Returning the string "skip" from the callback function will cause the original function/event to be skipped

===Optional Arguments===
*'''nameList:''' Table of strings for restricting which functions and events the hook will be triggered on
** addDebugHook and removeDebugHook will only be hooked if they are specified in the name list

===Returns===
Returns ''true'' if the hook was successfully added, or ''false'' otherwise.

==Callback parameters==
<syntaxhighlight lang="lua">
string preFunction( resource sourceResource, string functionName, bool isAllowedByACL, string luaFilename, int luaLineNumber, ...functionArguments )
postFunction( resource sourceResource, string functionName, bool isAllowedByACL, string luaFilename, int luaLineNumber, ...functionArguments )
string preEvent( resource sourceResource, string eventName, element eventSource, element eventClient, string luaFilename, int luaLineNumber, ...eventArguments )
postEvent( resource sourceResource, string eventName, element eventSource, element eventClient, string luaFilename, int luaLineNumber, ...eventArguments )
</syntaxhighlight>
{{New feature/item|3.0158|1.5.5|11856|
<syntaxhighlight lang="lua">
string preEventFunction ( resource eventResource, string eventName, element eventSource, element eventClient, string eventFilename, int eventLineNumber, resource functionResource, string functionFilename, int functionLineNumber, ...eventArgs )
postEventFunction ( resource eventResource, string eventName, element eventSource, element eventClient, string eventFilename, int eventLineNumber, resource functionResource, string functionFilename, int functionLineNumber, ...eventArgs )
</syntaxhighlight>
}}

==Example==
This example will dump info about all triggered events:
<syntaxhighlight lang="lua">
function onPreEvent( sourceResource, eventName, eventSource, eventClient, luaFilename, luaLineNumber, ... )
local args = { ... }
local srctype = eventSource and getElementType(eventSource)
local resname = sourceResource and getResourceName(sourceResource)
local plrname = eventClient and getPlayerName(eventClient)
outputDebugString( "preEvent"
.. " " .. tostring(resname)
.. " " .. tostring(eventName)
.. " source:" .. tostring(srctype)
.. " player:" .. tostring(plrname)
.. " file:" .. tostring(luaFilename)
.. "(" .. tostring(luaLineNumber) .. ")"
.. " numArgs:" .. tostring(#args)
.. " arg1:" .. tostring(args[1])
)
end
addDebugHook( "preEvent", onPreEvent )
</syntaxhighlight>
This example will dump info about all called MTA functions:
<syntaxhighlight lang="lua">
function onPreFunction( sourceResource, functionName, isAllowedByACL, luaFilename, luaLineNumber, ... )
local args = { ... }
local resname = sourceResource and getResourceName(sourceResource)
outputDebugString( "preFunction"
.. " " .. tostring(resname)
.. " " .. tostring(functionName)
.. " allowed:" .. tostring(isAllowedByACL)
.. " file:" .. tostring(luaFilename)
.. "(" .. tostring(luaLineNumber) .. ")"
.. " numArgs:" .. tostring(#args)
.. " arg1:" .. tostring(args[1])
)
end
addDebugHook( "preFunction", onPreFunction)
</syntaxhighlight>

This example adds a hook which will only be triggered for the named functions
<syntaxhighlight lang="lua">
addDebugHook( "preFunction", onPreFunction, {"setElementPosition","loadstring"} )
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.5-9.06054|Added clientside}}
{{ChangelogItem|1.3.5-9.06142|Added option to restrict to specified functions and events }}
{{ChangelogItem|1.5.2-9.07957|Added option to skip original function/event <br/>Added ability to hook addDebugHook and removeDebugHook }}
{{ChangelogItem|1.5.5-9.11856|Added pre/postEventFunction hooks }}
{{ChangelogItem|1.6.0-9.22741|Removed ability to skip 'addDebugHook' }}

==See Also==
{{Utility functions}}

User:DColeman/RU:Безопасность скриптов

2025-05-10T19:58:14Z

DColeman: /* Дополнительный слой защиты */

==Информация по памяти клиента==

Начиная с самых основ:
* Вы должны понимать, что все, что вы храните на стороне клиента, включая .lua файлы, находится под риском. Любая конфиденциальная или критическая информация, которая как-либо оказывается на клиентской стороне (ПК игрока), может быть прочитана и/или изменена чит-клиентами.
* Чтобы сохранить конфиденциальную информацию и логику скрипта в секрете - используйте серверную сторону.
* Обратите внимание, что скрипты, отмеченные как общие ('''shared''') также действуют как '''клиентские''', что означает, что все вышеперечисленное также применяется и к ним. Например, объявление скрипта:

<syntaxhighlight lang="xml">
<script src="script.lua" type="shared"/> 
</syntaxhighlight>

То же самое, что и объявление:

<syntaxhighlight lang="xml">
<script src="script.lua" type="client"/> 
<script src="script.lua" type="server"/> 
</syntaxhighlight>

==Дополнительный слой защиты==

Чтобы значительно ''усложнить жизнь*'' тем, у кого есть плохие намерения по отношению к вашему серверу, вы можете использовать аттрибут cache (и/или [https://luac.mtasa.com/ скомпилированные lua скрипты (также известные как Luac) с '''3''' уровнем дополнительной обфускации] - [https://wiki.multitheftauto.com/wiki/Lua_compilation_API API]), доступный в [https://wiki.multitheftauto.com/wiki/Meta.xml meta.xml], вместе с настройкой встроенного античита МТА с включением SD (специальными кодами обнаружения), для дополнительной информации смотрите [https://wiki.multitheftauto.com/wiki/Anti-cheat_guide гайд по античиту].

<syntaxhighlight lang="xml">
<script src="shared.lua" type="shared" cache="false"/> 
<script src="client.lua" type="client" cache="false"/> 
</syntaxhighlight>

* ''Усложнить жизнь'' '''не означает "сделать невозможным"''' получение вашего клиентского Lua кода, это означает, что '''большинство''' людей не смогут просмотреть ваши .lua файлы - тех, кто ищет логические ошибки (баги) или отсутствующие/некорректные проверки безопасности.
* Может использоваться на '''client''' и '''shared''' типах скриптов (не имеет эффекта на серверных скриптах).
* Это не удалит Lua файлы, которые были загружены ранее.

==Обнаружение и обезвреживание бэкдоров и читов==
'''Чтобы минимизировать (или исключить) урон, причиненный Lua скриптами:'''
* Всегда обновляйте ваш сервер до самой актуальной версии, вы можете [https://nightly.multitheftauto.com/ загрузить новейшие сборки сервера отсюда.] С информацией по определенным сборкам можно ознакомиться [https://buildinfo.multitheftauto.com/ здесь.]
* Всегда обновляйте ресурсы, установленные на сервере, до самой актуальной версии, вы можете [https://github.com/multitheftauto/mtasa-resources загрузить новейшие (стандартные) ресурсы из репозитория GitHub.] Они часто содержат обновления безопасности, которые влияют на устойчивость вашего сервера к атакам.
* Убедитесь, что [https://wiki.multitheftauto.com/wiki/Access%20Control%20List ACL (список контроля доступа)] правильно сконфигурирован - он поможет заблокировать ресурсам некоторые потенциально опасные функции.
* Никогда не выдавайте админ-права ресурсам (включая карты), полученным из неизвестных источников.
* Перед запуском недоверенного ресурса, изучите:
** Его [https://wiki.multitheftauto.com/wiki/Meta.xml meta.xml], на наличие возможных скрытых скриптов, которые скрываются под видом файлов с другими расширениями.
** Его исходный код, на наличие вредоносной логики.
* Не запускайте и не используйте скомпилированные ресурсы (скрипты), в легитимности которых вы не уверены.

'''Чтобы минимизировать урон, причиненный читером, зашедшим на сервер:'''
* При создании скриптов '''никогда не доверяйте данным, полученным со стороны клиента'''.
* При просмотре скриптов на наличие дыр безопасности, сверяйтесь с данными, поступающими от клиента, которому можно доверять.
* Отправлены могут быть любые данные, поэтому любые серверные скрипты, которые коммуницируют с клиентскими и получают информацию от игроков, '''должны проверять информацию на корректность''' перед дальнейшим использованием. Подделка данных чаще всего происходит с помощью [[setElementData]] и [[triggerServerEvent]].
* Вы не должны полагаться только на [https://wiki.multitheftauto.com/wiki/Serial серийный номер] игрока, когда они используются для критических действий (авто-входа/администраторских действий). '''Не гарантируется, что серийный номер игрока уникален и не подделан'''. Это причина, почему вы должны '''поместить его за''' системой аккаунтов, в качестве '''важного аутентификационного фактора'''.
* Серверная логика '''не может быть обойдена''' (если только сервер не взломан или в коде нет ошибки, но это совсем другой сценарий.) - '''используйте это в своих интересах'''. В большинстве случаев, вы можете реализовать проверки безопасности только на серверной стороне, не привлекая клиент.
* Следование аксиоме '''''“Все параметры, включая source могут быть подделаны и им нельзя доверять. Глобальной переменной client можно доверять.”''''' дает вам уверенность в том, что игрок, к которому вы обращаетесь (через переменную '''client''') '''именно тот, кто вызвал событие'''. Это защищает вас от тех ситуаций, когда читер может вызывать, например, админские события (например, кик/бан игрока), указывая реального администратора ('''второй''' аргумент '''[[triggerServerEvent]]'''), или вызывать события за других игроков (будто они вызвали их, но в реальности это сделал читер) - всего лишь из-за использования некорректной переменной. Чтобы убедиться, что вы это поняли, обратимся к коду:

<syntaxhighlight lang="lua">
--[[
НИКОГДА НЕ ИСПОЛЬЗУЙТЕ ЭТОТ КОД - ОН АБСОЛЮТНО НЕВЕРНЫЙ И НЕБЕЗОПАСНЫЙ
ПРОБЛЕМА: ИСПОЛЬЗУЯ ПЕРЕМЕННУЮ 'source' В hasObjectPermissionTo ВЫ ОСТАВЛЯЕТЕ ДЫРУ ДЛЯ ЧИТЕРОВ
]]

function onServerWrongAdminEvent(playerToBan)
if (not client) then -- 'client' указывает на игрока, который вызвал событие, и должен использоваться в качестве проверки безопасности (для предотвращения подмены игрока)
return false -- если эта переменная не существует (по неизвестной причине), останавливаем выполнение кода
end

local defaultPermission = false -- по стандарту не разрешаем действие, сморите: https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo
local canAdminBanPlayer = hasObjectPermissionTo(source, "function.banPlayer", defaultPermission) -- эксплойт находится здесь...

if (not canAdminBanPlayer) then -- если у игрока нет прав
return false -- останавливаем выполнение кода
end

local validElement = isElement(playerToBan) -- проверяем, что аргумент, переданный игроком, является элементом
if (not validElement) then -- если нет...
return false -- останавливаем выполнение кода
end

local elementType = getElementType(playerToBan) -- это элемент, получаем его тип
local playerType = (elementType == "player") -- проверяем, что тип элемента - игрок

if (not playerType) then -- это не игрок
return false -- останавливаемся
end

-- banPlayer(...) -- делаем, что нужно
end
addEvent("onServerWrongAdminEvent", true)
addEventHandler("onServerWrongAdminEvent", root, onServerWrongAdminEvent)

--[[
onServerCorrectAdminEvent ПРЕКРАСНО ЗАЩИЩЕН, ТАК, КАК ДОЛЖНО БЫТЬ
ЗДЕСЬ НЕТ ПРОБЛЕМ: МЫ ИСПОЛЬЗУЕМ 'client' В hasObjectPermissionTo, ЧТО ЗАЩИЩАЕТ НАС ОТ ПОДМЕНЫ ИГРОКА, КОТОРЫЙ ВЫЗВАЛ СОБЫТИЕ
]]--

function onServerCorrectAdminEvent(playerToBan)
if (not client) then -- 'client' указывает на игрока, который вызвал событие, и должен использоваться в качестве проверки безопасности (для предотвращения подмены игрока)
return false -- если эта переменная не существует (по неизвестной причине), останавливаем выполнение кода
end

local defaultPermission = false -- по стандарту не разрешаем действие, сморите: https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo
local canAdminBanPlayer = hasObjectPermissionTo(client, "function.banPlayer", defaultPermission) -- если игрок имеет права

if (not canAdminBanPlayer) then -- если у игрока нет прав
return false -- останавливаем выполнение кода
end

local validElement = isElement(playerToBan) -- проверяем, что аргумент, переданный игроком, является элементом
if (not validElement) then -- если нет...
return false -- останавливаем выполнение кода
end

local elementType = getElementType(playerToBan) -- это элемент, получаем его тип
local playerType = (elementType == "player") -- проверяем, что тип элемента - игрок

if (not playerType) then -- это не игрок
return false -- останавливаемся
end

-- banPlayer(...) -- делаем, что нужно
end
addEvent("onServerCorrectAdminEvent", true)
addEventHandler("onServerCorrectAdminEvent", root, onServerCorrectAdminEvent)
</syntaxhighlight>

==Securing setElementData==

* You should refrain from using [[element data]] everywhere, it should be only used when really necessary. It is advised to replace it with [[triggerClientEvent]] instead.
* If you still insist on using it, it is recommended to set '''4th''' argument in [[setElementData]] to '''false''' (disabling sync for this, certain data) and use subscriber mode - [[addElementDataSubscriber]], for both security & performance reasons described in [https://wiki.multitheftauto.com/wiki/Script_security#Securing_triggerServerEvent event section.]
{{Important Note|Disabling sync however, doesn't fully protect data key. It would be still vulnerable by default, but in this case you are not leaving it in plain sight. Using [[getAllElementData]] or digging in RAM wouldn't expose it, since it won't be synced to client in first place. Therefore, it needs to be added to anti-cheat as well.}}
* All parameters including '''source''' can be faked and should not be trusted.
* Global variable '''client''' can be trusted.

----------
<section name="Server" class="server" show="true">
Example of basic element data anti-cheat.
<syntaxhighlight lang="lua">
local function reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue) -- helper function to log and revert changes
local logClient = inspect(clientElement) -- in-depth view of player which forced element data sync
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = tostring(sourceElement) -- element which received data
local logOldValue = tostring(oldValue) -- old value
local logNewValue = tostring(newValue) -- new value
local logText = -- fill our report with data
"=======================================\n"..
"Detected element data abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Data key: "..dataKey.."\n"..
"Old data value: "..logOldValue.."\n"..
"New data value: "..logNewValue.."\n"..
"======================================="

local logVisibleTo = root -- specify who will see this log in console, in this case each player connected to server
local hadData = (oldValue ~= nil) -- check if element had such data before

if (hadData) then -- if element had such data before
setElementData(sourceElement, dataKey, oldValue, true) -- revert changes, it will call onElementDataChange event, but will fail (stop) on first condition - because server (not client) forced change
else
removeElementData(sourceElement, dataKey) -- remove it completely
end

outputConsole(logText, logVisibleTo) -- print it to console

return true -- all success
end

function onElementDataChangeBasicAC(dataKey, oldValue, newValue) -- the heart of our anti-cheat, which does all the magic security measurements
if (not client) then -- check if data is coming from client
return false -- if it's not, do not go further
end

local checkSpecialThing = (dataKey == "special_thing") -- compare whether dataKey matches "special_thing"
local checkFlagWaving = (dataKey == "flag_waving") -- compare whether dataKey matches "flag_waving"

if (checkSpecialThing) then -- if it does, do our security checks
local invalidElement = (client ~= source) -- verify whether source element is different from player which changed data

if (invalidElement) then -- if it's so
reportAndRevertDataChange(client, source, dataKey, oldValue, newValue) -- revert data change, because "special_thing" can only be set for player himself
end
end

if (checkFlagWaving) then -- if it does, do our security checks
local playerVehicle = getPedOccupiedVehicle(client) -- get player's current vehicle
local invalidVehicle = (playerVehicle ~= source) -- verify whether source element is different from player's vehicle

if (invalidVehicle) then -- if it's so
reportAndRevertDataChange(client, source, dataKey, oldValue, newValue) -- revert data change, because "flag_waving" can only be set for player's own vehicle
end
end
end
addEventHandler("onElementDataChange", root, onElementDataChangeBasicAC)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
Example of advanced element data anti-cheat.
<syntaxhighlight lang="lua">
--[[
For maximum security set punishPlayerOnDetect, punishmentBan, allowOnlyProtectedKeys to true (as per default configuration)
If allowOnlyProtectedKeys is enabled, do not forget to add every client-side element data key to protectedKeys table - otherwise you will face false-positives

Anti-cheat (handleDataChange) table structure and it's options:

["keyName"] = { -- name of key which would be protected
onlyForPlayerHimself = true, -- enabling this (true) will make sure that this element data key can only be set on player who synced it (ignores onlyForOwnPlayerVeh and allowForElements), use false/nil to disable this
onlyForOwnPlayerVeh = false, -- enabling this (true) will make sure that this element data key can only be set on player's current vehicle who synced it (ignores allowForElements), use false/nil to disable this
allowForElements = { -- restrict this key for certain element type(s), set to false/nil or leave it empty to not check this (full list of element types: https://wiki.multitheftauto.com/wiki/GetElementsByType)
["player"] = true,
["ped"] = true,
["vehicle"] = true,
["object"] = true,
},
allowedDataTypes = { -- restrict this key for certain value type(s), set to false/nil or leave it empty to not check this
["string"] = true,
["number"] = true,
["table"] = true,
["boolean"] = true,
["nil"] = true,
},
allowedStringLength = {1, 32}, -- if value is a string, then it's length must be in between (min-max), set it to false/nil to not check string length - do note that allowedDataTypes must contain ["string"] = true
allowedTableLength = {1, 64}, -- if value is a table, then it's length must be in between (min-max), set it to false/nil to not check table length - do note that allowedDataTypes must contain ["table"] = true
allowedNumberRange = {1, 128}, -- if value is a number, then it must be in between (min-max), set it to false/nil to not check number range - do note that allowedDataTypes must contain ["number"] = true
}
]]

local punishPlayerOnDetect = true -- should player be punished upon detection (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Altering element data" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local allowOnlyProtectedKeys = true -- disallow (remove by using removeElementData) every element data besides those given in protectedKeys table; in case someone wanted to flood server with garbage keys, which would be kept in memory until server restart or manual remove - setElementData(source, key, nil) won't remove it; it has to be removeElementData
local debugLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugR = 255 -- debug message - red color
local debugG = 127 -- debug message - green color
local debugB = 0 -- debug message - blue color
local protectedKeys = {
["vehicleNumber"] = { -- we want vehicleNumber to be set only on vehicles, with stricte numbers in range of 1-100
allowForElements = {
["vehicle"] = true,
},
allowedDataTypes = {
["number"] = true,
},
allowedNumberRange = {1, 100},
},
["personalVehData"] = { -- we want be able to set personalVehData only on current vehicle, also it should be a string with length between 1-24
onlyForOwnPlayerVeh = true,
allowedDataTypes = {
["string"] = true,
},
allowedStringLength = {1, 24},
},
-- perform security checks on keys stored in this table, in a convenient way
}

local function reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- helper function to log and revert changes
local logClient = inspect(clientElement) -- in-depth view of player which forced element data sync
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = inspect(sourceElement) -- in-depth view of element which received data
local logOldValue = inspect(oldValue) -- in-depth view of old value
local logNewValue = inspect(newValue) -- in-depth view of new value
local logText = -- fill our report with data
"*\n"..
"Detected element data abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Data key: "..dataKey.."\n"..
"Old data value: "..logOldValue.."\n"..
"New data value: "..logNewValue.."\n"..
"Fail reason: "..failReason.."\n"..
"*"

outputDebugString(logText, debugLevel, debugR, debugG, debugB) -- print it to debug

if (forceRemove) then -- we don't want this element data key to exist at all
removeElementData(sourceElement, dataKey) -- remove it

return true -- return success and stop here, we don't need further checks
end

setElementData(sourceElement, dataKey, oldValue, true) -- revert changes, it will call onElementDataChange event, but will fail (stop) on first condition - because server (not client) forced change

return true -- return success
end

local function handleDataChange(clientElement, sourceElement, dataKey, oldValue, newValue) -- the heart of our anti-cheat, which does all the magic security measurements, returns true if there was no altering from client (based on data from protectedKeys), false otherwise
local protectedKey = protectedKeys[dataKey] -- look up whether key changed is stored in protectedKeys table

if (not protectedKey) then -- if it's not

if (allowOnlyProtectedKeys) then -- if we don't want garbage keys
local failReason = "Key isn't present in protectedKeys" -- reason shown in report
local forceRemove = true -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end

return true -- this key isn't protected, let it through
end

local onlyForPlayerHimself = protectedKey.onlyForPlayerHimself -- if key has "self-set" lock
local onlyForOwnPlayerVeh = protectedKey.onlyForOwnPlayerVeh -- if key has "self-vehicle" lock
local allowForElements = protectedKey.allowForElements -- if key has element type check
local allowedDataTypes = protectedKey.allowedDataTypes -- if key has allowed data type check

if (onlyForPlayerHimself) then -- if "self-set" lock is active
local matchingElement = (clientElement == sourceElement) -- verify whether player who set data is equal to element which received data

if (not matchingElement) then -- if it's not matching
local failReason = "Can only set on player himself" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (onlyForOwnPlayerVeh) then -- if "self-vehicle" lock is active
local playerVehicle = getPedOccupiedVehicle(clientElement) -- get current vehicle of player which set data
local matchingVehicle = (playerVehicle == sourceElement) -- check whether it matches the one which received data

if (not matchingVehicle) then -- if it doesn't match
local failReason = "Can only set on player's own vehicle" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowForElements) then -- check if it's one of them
local elementType = getElementType(sourceElement) -- get type of element whose data changed
local matchingElementType = allowForElements[elementType] -- verify whether it's allowed

if (not matchingElementType) then -- this isn't matching
local failReason = "Invalid element type" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedDataTypes) then -- if there's allowed data types
local valueType = type(newValue) -- get data type of value
local matchingType = allowedDataTypes[valueType] -- check if it's one of allowed

if (not matchingType) then -- if it's not then
local failReason = "Invalid data type" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end

local allowedStringLength = protectedKey.allowedStringLength -- if key has specified string length check
local dataString = (valueType == "string") -- make sure it's a string

if (allowedStringLength and dataString) then -- if we should check string length
local minLength = allowedStringLength[1] -- retrieve min length
local maxLength = allowedStringLength[2] -- retrieve max length
local stringLength = utf8.len(newValue) -- get length of data string
local matchingLength = (stringLength >= minLength) and (stringLength <= maxLength) -- compare whether value fits in between

if (not matchingLength) then -- if it doesn't
local failReason = "Invalid string length (must be between "..minLength.."-"..maxLength..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedTableLength = protectedKey.allowedTableLength -- if key has table length check
local dataTable = (valueType == "table") -- make sure it's a table

if (allowedTableLength and dataTable) then -- if we should check table length
local minLength = allowedTableLength[1] -- retrieve min length
local maxLength = allowedTableLength[2] -- retrieve max length
local minLengthAchieved = false -- variable which checks 'does minimum length was achieved'
local maxLengthExceeded = false -- variable which checks 'does length has exceeds more than allowed maximum'
local tableLength = 0 -- store initial table length

for _, _ in pairs(newValue) do -- loop through whole table
tableLength = (tableLength + 1) -- add + 1 on each table entry
minLengthAchieved = (tableLength >= minLength) -- is length bigger or at very minimum we require
maxLengthExceeded = (tableLength > maxLength) -- does table exceeded more than max length?

if (maxLengthExceeded) then -- it is bigger than it should be
break -- break the loop (due of condition above being worthy, it makes no point to count further and waste CPU, on a table which potentially could have huge amount of entries)
end
end

local matchingLength = (minLengthAchieved and not maxLengthExceeded) -- check if min length has been achieved, and make sure that it doesn't go beyond max length

if (not matchingLength) then -- this table doesn't match requirements
local failReason = "Invalid table length (must be between "..minLength.."-"..maxLength..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedNumberRange = protectedKey.allowedNumberRange -- if key has allowed number range check
local dataNumber = (valueType == "number") -- make sure it's a number

if (allowedNumberRange and dataNumber) then -- if we should check number range
local minRange = allowedNumberRange[1] -- retrieve min number range
local maxRange = allowedNumberRange[2] -- retrieve max number range
local matchingRange = (newValue >= minRange) and (newValue <= maxRange) -- compare whether value fits in between

if (not matchingRange) then -- if it doesn't
local failReason = "Invalid number range (must be between "..minRange.."-"..maxRange..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end
end

return true -- security checks passed, we are all clear with this data key
end

function onElementDataChangeAdvancedAC(dataKey, oldValue, newValue) -- this event makes use of handleDataChange, the code was split for better readability
if (not client) then -- check if data is coming from client
return false -- if it's not, do not continue
end

local approvedChange = handleDataChange(client, source, dataKey, oldValue, newValue) -- run our security checks

if (approvedChange) then -- it's all cool and good
return false -- we don't need further action
end

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(client, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(client, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onElementDataChange", root, onElementDataChangeAdvancedAC)
</syntaxhighlight>
</section>

==Securing triggerServerEvent==

* All parameters including '''source''' can be faked and should not be trusted.
* Global variable '''client''' can be trusted.
* '''Admin''' styled '''events''' should be verifying player (client) '''ACL rights''', either by [https://wiki.multitheftauto.com/wiki/IsObjectInACLGroup isObjectInACLGroup] or [https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo hasObjectPermissionTo].
* Do '''not''' use the same name for your custom event as MTA native server events (which aren't remotely triggerable by default), e.g: '''onPlayerLogin'''; doing so would open door for cheaters manipulations.
* Be aware to which players event is sent via [[triggerClientEvent]]. For both security & performance reasons, admin like events should be received by admins only (to prevent confidential data being accessed), in the same time you shouldn't send each event to everyone on server (e.g: login success event which hides login panel for certain player). [[triggerClientEvent]] allows you to specify the event receiver as first (optional) argument. It defaults to [[root]], meaning if you don't specify it, it will be sent to everyone connected to server - even those who are still downloading server cache (which results in ''Server triggered clientside event eventName, but event is not added clientside.''). You can either pass player element or table with receivers:
<syntaxhighlight lang="lua">
local playersToReceiveEvent = {player1, player2, player3} -- each playerX is player element

triggerClientEvent(playersToReceiveEvent, ...) -- do not forget to fill the latter part of arguments
</syntaxhighlight>

----------
<section name="Server" class="server" show="true">
Example of anti-cheat function designed for events, used for data validation for both normal, and admin events which are called from client-side.
<syntaxhighlight lang="lua">
--[[
For maximum security set punishPlayerOnDetect, punishmentBan to true (as per default configuration)

Anti-cheat (processServerEventData) table structure and it's options:

checkACLGroup = { -- check whether player who called event belongs to at least one group below, set to false/nil to not check this
"Admin",
},
checkPermissions = { -- check whether player who called event has permission to at least one thing below, set to false/nil to not check this
"function.kickPlayer",
},
checkEventData = {
{
debugData = "source", -- optional details for report shown in debug message
eventData = source, -- data we want to verify
equalTo = client, -- compare whether eventData == equalTo
allowedElements = { -- restrict eventData to be certain element type(s), set to false/nil or leave it empty to not check this (full list of element types: https://wiki.multitheftauto.com/wiki/GetElementsByType)
["player"] = true,
["ped"] = true,
["vehicle"] = true,
["object"] = true,
},
allowedDataTypes = { -- restrict eventData to be certain value type(s), set to false/nil or leave it empty to not check this
["string"] = true,
["number"] = true,
["table"] = true,
["boolean"] = true,
["nil"] = true,
},
allowedStringLength = {1, 32}, -- if eventData is a string, then it's length must be in between (min-max), set it to false/nil to not check string length - do note that allowedDataTypes must contain ["string"] = true
allowedTableLength = {1, 64}, -- if eventData is a table, then it's length must be in between (min-max), set it to false/nil to not check table length - do note that allowedDataTypes must contain ["table"] = true
allowedNumberRange = {1, 128}, -- if eventData is a number, then it must be in between (min-max), set it to false/nil to not check number range - do note that allowedDataTypes must contain ["number"] = true
},
},
]]

local punishPlayerOnDetect = true -- should player be punished upon detection (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Altering server event data" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugR = 255 -- debug message - red color
local debugG = 127 -- debug message - green color
local debugB = 0 -- debug message - blue color

function processServerEventData(clientElement, sourceElement, serverEvent, securityChecks) -- the heart of our anti-cheat, which does all the magic security measurements, returns true if there was no altering from client (based on data from securityChecks), false otherwise
if (not securityChecks) then -- if we haven't passed any security checks
return true -- nothing to check, let code go further
end

if (not clientElement) then -- if client variable isn't available for some reason (although it should never happen)
local failReason = "Client variable not present" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local checkACLGroup = securityChecks.checkACLGroup -- if there's any ACL groups to check
local checkPermissions = securityChecks.checkPermissions -- if there's any permissions to check
local checkEventData = securityChecks.checkEventData -- if there's any data checks

if (checkACLGroup) then -- let's check player ACL groups
local playerAccount = getPlayerAccount(clientElement) -- get current account of player
local guestAccount = isGuestAccount(playerAccount) -- if account is guest (meaning player is not logged in)

if (guestAccount) then -- it's the case
local failReason = "Can't retrieve player login - guest account" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local accountName = getAccountName(playerAccount) -- get name of player's current account
local aclString = "user."..accountName -- format it for further use in isObjectInACLGroup function

for groupID = 1, #checkACLGroup do -- iterate over table of given groups
local groupName = checkACLGroup[groupID] -- get each group name
local aclGroup = aclGetGroup(groupName) -- check if such group exists

if (not aclGroup) then -- it doesn't
local failReason = "ACL group '"..groupName.."' is missing" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local playerInACLGroup = isObjectInACLGroup(aclString, aclGroup) -- check if player belong to the group

if (playerInACLGroup) then -- yep, it's the case
return true -- so it's a success
end
end

local failReason = "Player doesn't belong to any given ACL group" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

if (checkPermissions) then -- check if player has at least one desired permission
local allowedByDefault = false -- does he have access by default

for permissionID = 1, #checkPermissions do -- iterate over all permissions
local permissionName = checkPermissions[permissionID] -- get permission name
local hasPermission = hasObjectPermissionTo(clientElement, permissionName, allowedByDefault) -- check whether player is allowed to perform certain action

if (hasPermission) then -- if player has access
return true -- one is available (and enough), server won't bother to check others (as return keywords also breaks loop)
end
end

local failReason = "Not enough permissions" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

if (checkEventData) then -- if there is some data to verify

for dataID = 1, #checkEventData do -- iterate over each of data
local dataToCheck = checkEventData[dataID] -- get each data set
local eventData = dataToCheck.eventData -- this is the one we'll be verifying
local equalTo = dataToCheck.equalTo -- we want to compare whether eventData == equalTo
local allowedElements = dataToCheck.allowedElements -- check whether is element, and whether belongs to certain element types
local allowedDataTypes = dataToCheck.allowedDataTypes -- do we restrict data to be certain type?
local debugData = dataToCheck.debugData -- additional helper data
local debugText = debugData and " ("..debugData..")" or "" -- if it's present, format it nicely

if (equalTo) then -- equal check exists
local matchingData = (eventData == equalTo) -- compare whether those two values are equal

if (not matchingData) then -- they aren't
local failReason = "Data isn't equal @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedElements) then -- we do check whether is an element, and belongs to at least one given in the list
local validElement = isElement(eventData) -- check if it's actual element

if (not validElement) then -- it's not
local failReason = "Data isn't element @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local elementType = getElementType(eventData) -- it's element, so we want to know it's type
local matchingElementType = allowedElements[elementType] -- verify whether it's allowed

if (not matchingElementType) then -- it's not allowed
local failReason = "Invalid element type @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedDataTypes) then -- let's check allowed data types
local dataType = type(eventData) -- get data type
local matchingType = allowedDataTypes[dataType] -- verify whether it's allowed

if (not matchingType) then -- it isn't
local failReason = "Invalid data type @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local allowedStringLength = dataToCheck.allowedStringLength -- if data has string length check
local dataString = (dataType == "string") -- make sure it's a string

if (allowedStringLength and dataString) then -- if we should check string length
local minLength = allowedStringLength[1] -- retrieve min length
local maxLength = allowedStringLength[2] -- retrieve max length
local stringLength = utf8.len(eventData) -- get length of data string
local matchingLength = (stringLength >= minLength) and (stringLength <= maxLength) -- compare whether value fits in between

if (not matchingLength) then -- if it doesn't
local failReason = "Invalid string length (must be between "..minLength.."-"..maxLength..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedTableLength = dataToCheck.allowedTableLength -- if data has table length check
local dataTable = (dataType == "table") -- make sure it's a table

if (allowedTableLength and dataTable) then -- if we should check table length
local minLength = allowedTableLength[1] -- retrieve min length
local maxLength = allowedTableLength[2] -- retrieve max length
local minLengthAchieved = false -- variable which checks 'does minimum length was achieved'
local maxLengthExceeded = false -- variable which checks 'does length has exceeds more than allowed maximum'
local tableLength = 0 -- store initial table length

for _, _ in pairs(eventData) do -- loop through whole table
tableLength = (tableLength + 1) -- add + 1 on each table entry
minLengthAchieved = (tableLength >= minLength) -- is length bigger or at very minimum we require
maxLengthExceeded = (tableLength > maxLength) -- does table exceeded more than max length?

if (maxLengthExceeded) then -- it is bigger than it should be
break -- break the loop (due of condition above being worthy, it makes no point to count further and waste CPU, on a table which potentially could have huge amount of entries)
end
end

local matchingLength = (minLengthAchieved and not maxLengthExceeded) -- check if min length has been achieved, and make sure that it doesn't go beyond max length

if (not matchingLength) then -- this table doesn't match requirements
local failReason = "Invalid table length (must be between "..minLength.."-"..maxLength..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedNumberRange = dataToCheck.allowedNumberRange -- if data has number range check
local dataNumber = (dataType == "number") -- make sure it's a number

if (allowedNumberRange and dataNumber) then -- if we should check number range
local minRange = allowedNumberRange[1] -- retrieve min number range
local maxRange = allowedNumberRange[2] -- retrieve max number range
local matchingRange = (eventData >= minRange) and (eventData <= maxRange) -- compare whether value fits in between

if (not matchingRange) then -- if it doesn't
local failReason = "Invalid number range (must be between "..minRange.."-"..maxRange..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end
end
end
end

return true -- security checks passed, we are all clear with this event call
end

function reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- helper function to log and handle accidents
local logClient = inspect(clientElement) -- in-depth view player which called event
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = inspect(sourceElement) -- in-depth view of source element
local logText = -- fill our report with data
"*\n"..
"Detected event abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Event: "..serverEvent.."\n"..
"Reason: "..failReason.."\n"..
"*"

outputDebugString(logText, debugLevel, debugR, debugG, debugB) -- print it to debug

if (not punishPlayerOnDetect or skipPunishment) then -- we don't want to punish player for some reason
return true -- stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(clientElement, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(clientElement, punishedBy, punishmentReason) -- simply kick player out of server
end

return true -- all done, report success
end

function onServerEvent(clientData)
--[[
Assume this server event (function) is called in such way:

local dataToPass = 10

triggerServerEvent("onServerEvent", localPlayer, dataToPass)
]]

local shouldProcessServerCode = processServerEventData(
client, -- client element - responsible for calling event
source, -- source element - passed in triggerServerEvent (as 2nd argument)
eventName, -- name of event - in this case 'onServerEvent'
{
checkEventData = { -- we want to verify everything what comes from client
{
eventData = source, -- first to check, source variable
equalTo = client, -- we want to check whether it matches player who called event
debugData = "source", -- helper details which would be shown in report
},
{
eventData = clientData, -- let's check the data which client sent to us
allowedDataTypes = {
["number"] = true, -- we want it to be only number
},
allowedNumberRange = {1, 100}, -- in range of 1 to 100
debugData = "clientData", -- if something goes wrong, let server know where (it will appear in debug report)
},
},
}
)

if (not shouldProcessServerCode) then -- something isn't right, no green light for processing code behind this scope
return false -- stop code execution
end

-- do code as usual
end
addEvent("onServerEvent", true)
addEventHandler("onServerEvent", root, onServerEvent)

function onServerAdminEvent(playerToBan)
--[[
Assume this server admin event (function) is called in such way:

local playerToBan = getPlayerFromName("playerToBan")

triggerServerEvent("onServerAdminEvent", localPlayer, playerToBan)
]]

local shouldProcessServerCode = processServerEventData(
client, -- client element - responsible for calling event
source, -- source element - passed in triggerServerEvent (as 2nd argument)
eventName, -- name of event - in this case 'onServerAdminEvent'
{
checkACLGroup = { -- we need to check whether player who called event belongs to ACL groups
"Admin", -- in this case admin group
},
checkEventData = { -- we want to verify everything what comes from client
{
eventData = source, -- first to check, source variable
equalTo = client, -- we want to check whether it matches player who called event
debugData = "source", -- helper details which would be shown in report
},
{
eventData = playerToBan, -- let's check the data which client sent to us
allowedDataTypes = {
["player"] = true, -- we want it to be player
},
debugData = "playerToBan", -- if something goes wrong, let server know where (it will appear in debug report)
},
},
}
)

if (not shouldProcessServerCode) then -- something isn't right, no green light for processing code behind this scope
return false -- stop code execution
end

-- do code as usual
end
addEvent("onServerAdminEvent", true)
addEventHandler("onServerAdminEvent", root, onServerAdminEvent)
</syntaxhighlight>
</section>

==Securing server-only events==
* It is very important to '''disable remote triggering''' ability in [https://wiki.multitheftauto.com/wiki/AddEvent addEvent], to prevent calling server-side only events from client-side.
* '''Admin''' styled '''events''' should be verifying player '''ACL rights''', either by [https://wiki.multitheftauto.com/wiki/IsObjectInACLGroup isObjectInACLGroup] or [https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo hasObjectPermissionTo].

----------
<section name="Server" class="server" show="true">
This example shows how you should make event server-side only.
<syntaxhighlight lang="lua">
function onServerSideOnlyEvent()
-- do some server-side stuff
end
addEvent("onServerSideOnlyEvent", false) -- set second argument (allowRemoteTriger) to false, so it can't be called from client
addEventHandler("onServerSideOnlyEvent", root, onServerSideOnlyEvent) -- associate our event with function onServerSideOnlyEvent
</syntaxhighlight>
</section>

==Securing projectiles & explosions==
This section (and '''code''' is '''work in progress''') - '''use at your own risk'''.

----------
<section name="Server" class="server" show="false">
Projectile ammo tracker:
<syntaxhighlight lang="lua">
local playerProjectileAmmo = {} -- store player-held weapons ammo here
local playerWeaponsToTrack = { -- keep track of ammo for certain player-held weapon types, basically those which create projectile; [weaponID] = weaponSlot
[16] = 8, -- grenade
[17] = 8, -- teargas
[18] = 8, -- molotov
[35] = 7, -- rocket launcher
[36] = 7, -- rocket launcher (heat-seeking)
[39] = 8, -- satchel charge
}

local function updateProjectileAmmoForPlayer(playerElement)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

for weaponID, weaponSlot in pairs(playerWeaponsToTrack) do
local weaponInSlot = getPedWeapon(playerElement, weaponSlot)
local weaponTotalAmmo = getPedTotalAmmo(playerElement, weaponSlot)
local weaponHasAmmo = (weaponTotalAmmo > 0)
local weaponMatching = (weaponInSlot == weaponID)
local updateWeaponAmmo = (weaponMatching and weaponHasAmmo)

if (updateWeaponAmmo) then
local storedProjectileAmmo = playerProjectileAmmo[playerElement]
local newWeaponAmmo = (updateWeaponAmmo and weaponTotalAmmo or nil)

if (not storedProjectileAmmo) then
playerProjectileAmmo[playerElement] = {}
storedProjectileAmmo = playerProjectileAmmo[playerElement]
end

storedProjectileAmmo[weaponID] = newWeaponAmmo
end
end

return true
end

function hasPlayerProjectileAmmo(playerElement, projectileWeapon)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

local projectileData = playerProjectileAmmo[playerElement]
local projectileAmmo = (projectileData and projectileData[projectileWeapon])

return projectileAmmo
end

function decreasePlayerProjectileAmmo(playerElement, projectileWeapon)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

local playerProjectileData = playerProjectileAmmo[playerElement]

if (not playerProjectileData) then
return false
end

local projectileWeaponAmmo = playerProjectileData[projectileWeapon]
local tempProjectileAmmo = (projectileWeaponAmmo - 1)
local newProjectileAmmo = (tempProjectileAmmo > 0 and tempProjectileAmmo or nil)

playerProjectileData[projectileWeapon] = newProjectileAmmo

return true
end

function onPlayerWeaponSwitchAntiCheat(previousWeaponID, currentWeaponID)
setTimer(updateProjectileAmmoForPlayer, 50, 1, source)
end
addEventHandler("onPlayerWeaponSwitch", root, onPlayerWeaponSwitchAntiCheat)

function onResourceStartAntiCheat()
local playersTable = getElementsByType("player")

for playerID = 1, #playersTable do
local playerElement = playersTable[playerID]

updateProjectileAmmoForPlayer(playerElement)
end
end
addEventHandler("onResourceStart", resourceRoot, onResourceStartAntiCheat)

function onPlayerWastedQuitAntiCheat()
playerProjectileAmmo[source] = nil
end
addEventHandler("onPlayerWasted", root, onPlayerWastedQuitAntiCheat)
addEventHandler("onPlayerQuit", root, onPlayerWastedQuitAntiCheat)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
Projectile handler:
<syntaxhighlight lang="lua">
local playerCreatedProjectiles = {} -- store count of legitimately created player projectiles; [playerElement] = {[projectileType] = activeProjectiles}
local projectileTypes = {
[16] = { -- Grenade
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[16] = true, -- grenade
},
},
[17] = { -- Teargas
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[17] = true, -- teargas
},
},
[18] = { -- Molotov
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[18] = true, -- molotov
},
},
[19] = { -- Rocket
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileMaxVelocity = 2,
projectileAllowedWeapons = {
[35] = true, -- rocket launcher
},
projectileAllowedVehicles = {
[425] = true, -- hunter
[520] = true, -- hydra
},
},
[20] = { -- Rocket (heat-seeking)
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileMaxVelocity = 2,
projectileAllowedWeapons = {
[36] = true, -- rocket launcher (heat-seeking)
},
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
[21] = { -- Airbomb
projectileAllowed = true,
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
[39] = { -- Satchel charge
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[39] = true, -- satchel charge
},
},
[58] = { -- Hydra flare
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
}

local reportAbnormality = true -- whether to report about abnormality in debug script - by default
local punishPlayerOnDetect = false -- should player be punished upon detection; true - yes, or false to not do anything (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Projectile/explosion anti-cheat" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugMsgLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugMsgR = 255 -- debug message - red color
local debugMsgG = 127 -- debug message - green color
local debugMsgB = 0 -- debug message - blue color

local function reportProjectileAbnormality(playerElement, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ, detectionCode)
local projectileSyncer = inspect(playerElement)
local projectilePosition = projectileX..", "..projectileY..", "..projectileZ
local projectileZoneName = getZoneName(projectileX, projectileY, projectileZ, false)
local projectileCityName = getZoneName(projectileX, projectileY, projectileZ, true)
local projectileLog =
"* Detected projectile abnormality - "..detectionCode.." *\n"..
"Projectile syncer: "..projectileSyncer.."\n"..
"Projectile type: "..projectileType.."\n"..
"Projectile position: "..projectilePosition.. " ("..projectileZoneName..", "..projectileCityName..")\n"

outputDebugString(projectileLog, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)

return true
end

local function processProjectileChecks(playerElement, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)
local projectileData = projectileTypes[projectileType]
local projectileAllowed = projectileData.projectileAllowed

if (not projectileAllowed) then
return false, "Projectile not allowed"
end

local projectileAllowedWeapons = projectileData.projectileAllowedWeapons

if (projectileAllowedWeapons) then
local playerWeapon = getPedWeapon(playerElement)
local allowedWeapon = projectileAllowedWeapons[playerWeapon]

if (not allowedWeapon) then
return false, "Player is not holding correct weapon"
end

local weaponAmmo = hasPlayerProjectileAmmo(playerElement, playerWeapon)
local playerHasAmmo = (weaponAmmo > 0)

if (not playerHasAmmo) then
return false, "Player doesn't have ammo for weapon"
end

decreasePlayerProjectileAmmo(playerElement, playerWeapon)
end

local playerVehicle = getPedOccupiedVehicle(playerElement)

if (playerVehicle) then
local projectileAllowedVehicles = projectileData.projectileAllowedVehicles

if (projectileAllowedVehicles) then
local vehicleModel = getElementModel(playerVehicle)
local allowedVehicle = projectileAllowedVehicles[vehicleModel]

if (not allowedVehicle) then
return false, "Player is not inside allowed vehicles"
end

local vehicleDriver = getVehicleController(playerVehicle)
local playerDriver = (playerElement == vehicleDriver)

if (not playerDriver) then
return false, "Player is not vehicle driver"
end

return true
end

return false, "Player in vehicle"
end

local projectileMaxDistanceFromCreator = projectileData.projectileMaxDistanceFromCreator

if (projectileMaxDistanceFromCreator) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToProjectile = getDistanceBetweenPoints3D(playerX, playerY, playerZ, projectileX, projectileY, projectileZ)
local matchingProjectileDistance = (distanceToProjectile <= projectileMaxDistanceFromCreator)

if (not matchingProjectileDistance) then
return false, "Projectile distance mismatch"
end
end

local projectileMaxVelocity = projectileData.projectileMaxVelocity

if (projectileMaxVelocity) then
local projectileVelocity = (projectileVX ^ 2 + projectileVY ^ 2 + projectileVZ ^ 2)
local projectileSpeed = math.sqrt(projectileVelocity)
local matchingProjectileVelocity = (projectileSpeed <= projectileMaxVelocity)

if (not matchingProjectileVelocity) then
return false, "Projectile velocity mismatch"
end
end

return true
end

local function trackPlayerProjectile(playerElement, projectileID)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerProjectiles = playerCreatedProjectiles[playerElement]

if (not playerProjectiles) then
playerCreatedProjectiles[playerElement] = {}
playerProjectiles = playerCreatedProjectiles[playerElement]
end

local projectilesByType = playerProjectiles[projectileID] or 0
local newProjectilesCount = (projectilesByType + 1)

playerProjectiles[projectileID] = newProjectilesCount

return true
end

local function getProjectileDetectionOverwrittenBehavior(projectileType)
local projectileData = projectileTypes[projectileType]

if (not projectileData) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local projectileBehaviour = projectileData.projectileOverwriteBehaviour

if (not projectileBehaviour) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local overwriteReport = projectileBehaviour.reportAbnormality
local overwritePunish = projectileBehaviour.punishPlayerOnDetect
local overwriteBan = projectileBehaviour.punishmentBan

return overwriteReport, overwritePunish, overwriteBan
end

function decreasePlayerProjectiles(playerElement, projectileID)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerProjectiles = playerCreatedProjectiles[playerElement]

if (not playerProjectiles) then
return false, true
end

local projectilesByType = playerProjectiles[projectileID]

if (not projectilesByType) then
return false, true
end

local tempProjectilesCount = (projectilesByType - 1)
local newProjectilesCount = (tempProjectilesCount > 0 and tempProjectilesCount or nil)

playerProjectiles[projectileID] = newProjectilesCount

return true
end

function onPlayerProjectileCreationAntiCheat(projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)
local approvedProjectile, detectionCode = processProjectileChecks(source, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)

if (approvedProjectile) then
trackPlayerProjectile(source, projectileType)

return true
end

local reportAbnormality, punishPlayerOnDetect, punishmentBan = getProjectileDetectionOverwrittenBehavior(projectileType)

if (reportAbnormality) then
reportProjectileAbnormality(source, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ, detectionCode)
end

cancelEvent()

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(source, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(source, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onPlayerProjectileCreation", root, onPlayerProjectileCreationAntiCheat)

function onPlayerQuitAntiCheat()
playerCreatedProjectiles[source] = nil
end
addEventHandler("onPlayerQuit", root, onPlayerQuitAntiCheat)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
Explosions handler:
<syntaxhighlight lang="lua">
local rocketInstantExplosionDistanceThreshold = 1.55 -- distance below which only explosion will be created (and not rocket projectile, hence not calling onPlayerProjectileCreation); do not change it
local explosionTypes = { -- more specific info on explosion, and whether it is allowed
[0] = { -- Grenade
explosionAllowed = true,
explosionAllowedProjectiles = {
[16] = true, -- grenade
},
},
[1] = { -- Molotov
explosionAllowed = true,
explosionAllowedProjectiles = {
[18] = true, -- molotov
},
},
[2] = { -- Rocket
explosionAllowed = true,
explosionAllowedWeapons = {
[35] = true, -- rocket launcher
[36] = true, -- rocket launcher (heat-seeking)
},
explosionAllowedProjectiles = {
[19] = true, -- rocket
[20] = true, -- rocket (heat-seeking)
},
},
[3] = { -- Rocket weak
explosionAllowed = true,
explosionAllowedProjectiles = {
[19] = true, -- rocket
[20] = true, -- rocket (heat-seeking)
},
},
[4] = { -- Car
explosionAllowed = true,
},
[5] = { -- Car quick
explosionAllowed = true,
},
[6] = { -- Boat
explosionAllowed = true,
},
[7] = { -- Heli
explosionAllowed = true,
},
[8] = { -- Mine
explosionAllowed = true,
},
[9] = { -- Object
explosionAllowed = true,
},
[10] = { -- Tank grenade
explosionAllowed = true,
explosionMaxDistanceFromCreator = 80,
explosionAllowedVehicles = {
[432] = true,
}
},
[11] = { -- Small
explosionAllowed = true,
},
[12] = { -- Tiny
explosionAllowed = true,
},
}

local reportAbnormality = true -- whether to report about abnormality in debug script - by default
local punishPlayerOnDetect = false -- should player be punished upon detection; true - yes, or false to not do anything (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Projectile/explosion anti-cheat" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugMsgLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugMsgR = 255 -- debug message - red color
local debugMsgG = 127 -- debug message - green color
local debugMsgB = 0 -- debug message - blue color

local function reportExplosionAbnormality(playerElement, explosionType, explosionX, explosionY, explosionZ, detectionCode)
local explosionSyncer = inspect(playerElement)
local explosionType = explosionType
local explosionPosition = explosionX..", "..explosionY..", "..explosionZ
local explosionZoneName = getZoneName(explosionX, explosionY, explosionZ, false)
local explosionCityName = getZoneName(explosionX, explosionY, explosionZ, true)
local explosionLog =
"* Detected explosion abnormality - "..detectionCode.." *\n"..
"Explosion syncer: "..explosionSyncer.."\n"..
"Explosion type: "..explosionType.."\n"..
"Explosion position: "..explosionPosition.. " ("..explosionZoneName..", "..explosionCityName..")\n"

outputDebugString(explosionLog, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)

return true
end

local function processExplosionChecks(playerElement, explosionType, explosionX, explosionY, explosionZ)
local explosionData = explosionTypes[explosionType]
local explosionAllowed = explosionData.explosionAllowed

if (not explosionAllowed) then
return false, "Explosion type not allowed"
end

local rocketExplosion = (explosionType == 2)

if (rocketExplosion) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToExplosion = getDistanceBetweenPoints3D(playerX, playerY, playerZ, explosionX, explosionY, explosionZ)
local instantExplosion = (distanceToExplosion < rocketInstantExplosionDistanceThreshold)

if (instantExplosion) then
local explosionAllowedWeapons = explosionData.explosionAllowedWeapons
local playerWeapon = getPedWeapon(playerElement)
local allowedWeapon = explosionAllowedWeapons[playerWeapon]

if (not allowedWeapon) then
return false, "Player is not holding rocket launcher"
end

local weaponAmmo = hasPlayerProjectileAmmo(playerElement, playerWeapon)
local playerHasAmmo = (weaponAmmo > 0)

if (not playerHasAmmo) then
return false, "Player doesn't have ammo for rocket launcher"
end

decreasePlayerProjectileAmmo(playerElement, playerWeapon)

return true
end
end

local explosionAllowedProjectiles = explosionData.explosionAllowedProjectiles

if (explosionAllowedProjectiles) then

for projectileID, _ in pairs(explosionAllowedProjectiles) do
local atleastOneProjectile = decreasePlayerProjectiles(playerElement, projectileID)

if (atleastOneProjectile) then
return true
end
end

return false, "Explosion created without respective projectile"
end

local explosionAllowedVehicles = explosionData.explosionAllowedVehicles

if (explosionAllowedVehicles) then
local playerVehicle = getPedOccupiedVehicle(playerElement)

if (not playerVehicle) then
return false, "Player is not in vehicle"
end

local vehicleModel = getElementModel(playerVehicle)
local allowedVehicle = explosionAllowedVehicles[vehicleModel]

if (not allowedVehicle) then
return false, "Player is inside not allowed vehicles"
end

local vehicleDriver = getVehicleController(playerVehicle)
local playerDriver = (playerElement == vehicleDriver)

if (not playerDriver) then
return false, "Player is not vehicle driver"
end
end

local explosionMaxDistanceFromCreator = explosionData.explosionMaxDistanceFromCreator

if (explosionMaxDistanceFromCreator) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToExplosion = getDistanceBetweenPoints3D(playerX, playerY, playerZ, explosionX, explosionY, explosionZ)
local matchingExplosionDistance = (distanceToExplosion < explosionMaxDistanceFromCreator)

if (not matchingExplosionDistance) then
return false, "Explosion distance mismatch"
end
end

return true
end

local function getExplosionDetectionOverwrittenBehavior(explosionType)
local explosionData = explosionTypes[explosionType]

if (not explosionData) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local explosionBehaviour = explosionData.explosionOverwriteBehaviour

if (not explosionBehaviour) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local overwriteReport = explosionBehaviour.reportAbnormality
local overwritePunish = explosionBehaviour.punishPlayerOnDetect
local overwriteBan = explosionBehaviour.punishmentBan

return overwriteReport, overwritePunish, overwriteBan
end

function onExplosionAntiCheat(explosionX, explosionY, explosionZ, explosionType)
local serverSyncExplosion = (source == root)

if (serverSyncExplosion) then
return true
end

local approvedExplosion, detectionCode = processExplosionChecks(source, explosionType, explosionX, explosionY, explosionZ)

if (approvedExplosion) then
return true
end

local reportAbnormality, punishPlayerOnDetect, punishmentBan = getExplosionDetectionOverwrittenBehavior(explosionType)

if (reportAbnormality) then
reportExplosionAbnormality(source, explosionType, explosionX, explosionY, explosionZ, detectionCode)
end

cancelEvent()

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(source, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(source, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onExplosion", root, onExplosionAntiCheat)
</syntaxhighlight>
</section>

==Handling non-registered events==

See: [[onPlayerTriggerInvalidEvent]]

==Handling events spam==
See: [[onPlayerTriggerEventThreshold]]

TakePlayerScreenShot

2025-05-10T19:06:06Z

DColeman: Use client instead of source in example

__NOTOC__
{{Server function}}
This function forces a client to capture the current screen output and send it back to the server. The image will contain the GTA HUD and the output of any dxDraw functions that are not flagged as 'post GUI'. The image specifically excludes the chat box and all GUI (including the client console). The result is received with the event [[onPlayerScreenShot]].

==Syntax==
<syntaxhighlight lang="lua">
bool takePlayerScreenShot ( player thePlayer, int width, int height [, string tag = "", int quality = 30, int maxBandwidth = 5000, int maxPacketSize = 500 ] )
</syntaxhighlight>
{{OOP||[[player]]:takeScreenShot||}}
===Required Arguments===
*'''thePlayer:''' the player to get the screen capture from.
*'''width:''' the width of the capture image.
*'''height:''' the height of the capture image.

===Optional Arguments===
*'''tag:''' A string to help identify the screen capture. The string is passed to the matching [[onPlayerScreenShot]] event for your personal convenience.
*'''quality:''' Quality of the final JPEG image from 0 to 100. A lower value can reduce the memory used by the image considerably which will result in faster and less intrusive uploads.
*'''maxBandwidth:''' The amount of client upload bandwidth to use (in bytes per second) when sending the image.
*'''maxPacketSize: ''' The maximum size of one packet.

===Returns===
Returns ''true'' if the function was successfully, ''false'' if invalid arguments are specified.

==Example==
===Example 1===
This example will take a player screenshot whenever a player takes a picture with the camera weapon and then send the picture to all clients, which will render the latest screenshot in the bottom right corner of their screen.

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
local screenSizeX,screenSizeY = guiGetScreenSize() -- save the current screen dimensions
local imgtexture
local takenBy

function wepFire(weapon)
if weapon == 43 then -- if the weapon the player just fired is the camera
triggerServerEvent("onPlayerTakesPhoto",localPlayer)
end
end
addEventHandler("onClientPlayerWeaponFire",localPlayer,wepFire)

function updateLatestPhoto(img)
if imgtexture then -- clean up the old dxTextrue if there is one
destroyElement(imgtexture)
end
imgtexture = dxCreateTexture(img) -- create a new dxTexture from the image data so that we can render it using dxDrawImage
takenBy = "taken by "..getPlayerName(source) -- let's also credit the photographer
end
addEvent("updatePhoto",true)
addEventHandler("updatePhoto",root,updateLatestPhoto)

function renderPhoto()
if imgtexture then
local sizeX, sizeY = 320, 240
dxDrawImage(screenSizeX-sizeX,screenSizeY-sizeY,sizeX,sizeY,imgtexture) -- render the picture as well as the name of the photographer in the bottom right corner of the screen
dxDrawText(takenBy,screenSizeX-sizeX,screenSizeY-sizeY,screenSizeX,screenSizeY,tocolor(0,0,0))
end
end
addEventHandler("onClientRender",root,renderPhoto)
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function requestScreenshot()
takePlayerScreenShot(client,320,240,"cameraphoto",50) -- the player just took a picture with the camera, let's request a screenshot to see what they took a photo of
end
addEvent("onPlayerTakesPhoto",true)
addEventHandler("onPlayerTakesPhoto",root,requestScreenshot)

function incomingPlayerScreenshot(res,status,img,timestamp,tag)
if status == "ok" and tag == "cameraphoto" then -- make sure a picture was taken successfully and that we're the ones who requested this screenshot
triggerClientEvent("updatePhoto",source,img) -- trigger a client event to share the image with everyone on the server
end
end
addEventHandler("onPlayerScreenShot",root,incomingPlayerScreenshot)
</syntaxhighlight>
</section>

==See Also==
{{Player functions|server}}

User:DColeman/RU:Безопасность скриптов

2025-05-10T12:32:39Z

DColeman: /* Обнаружение и обезвреживание бэкдоров и читов */ typo fix

==Информация по памяти клиента==

Начиная с самых основ:
* Вы должны понимать, что все, что вы храните на стороне клиента, включая .lua файлы, находится под риском. Любая конфиденциальная или критическая информация, которая как-либо оказывается на клиентской стороне (ПК игрока), может быть прочитана и/или изменена чит-клиентами.
* Чтобы сохранить конфиденциальную информацию и логику скрипта в секрете - используйте серверную сторону.
* Обратите внимание, что скрипты, отмеченные как общие ('''shared''') также действуют как '''клиентские''', что означает, что все вышеперечисленное также применяется и к ним. Например, объявление скрипта:

<syntaxhighlight lang="xml">
<script src="script.lua" type="shared"/> 
</syntaxhighlight>

То же самое, что и объявление:

<syntaxhighlight lang="xml">
<script src="script.lua" type="client"/> 
<script src="script.lua" type="server"/> 
</syntaxhighlight>

==Дополнительный слой защиты==

Чтобы незначительно ''усложнить жизнь*'' тем, у кого есть плохие намерения по отношению к вашему серверу, вы можете использовать аттрибут cache (и/или [https://luac.mtasa.com/ скомпилированные lua скрипты (также известные как Luac) с '''3''' уровнем дополнительной обфускации] - [https://wiki.multitheftauto.com/wiki/Lua_compilation_API API]), доступный в [https://wiki.multitheftauto.com/wiki/Meta.xml meta.xml], вместе с настройкой встроенного античита МТА с включением SD (специальными кодами обнаружения), для дополнительной информации смотрите [https://wiki.multitheftauto.com/wiki/Anti-cheat_guide гайд по античиту].

<syntaxhighlight lang="xml">
<script src="shared.lua" type="shared" cache="false"/> 
<script src="client.lua" type="client" cache="false"/> 
</syntaxhighlight>

* ''Усложнить жизнь'' '''не означает "сделать невозможным"''' получение вашего клиентского Lua кода, это означает, что '''большинство''' людей не смогут просмотреть ваши .lua файлы - тех, кто ищет логические ошибки (баги) или отсутствующие/некорректные проверки безопасности.
* Может использоваться на '''client''' и '''shared''' типах скриптов (не имеет эффекта на серверных скриптах).
* Это не удалит Lua файлы, которые были загружены ранее.

==Обнаружение и обезвреживание бэкдоров и читов==
'''Чтобы минимизировать (или исключить) урон, причиненный Lua скриптами:'''
* Всегда обновляйте ваш сервер до самой актуальной версии, вы можете [https://nightly.multitheftauto.com/ загрузить новейшие сборки сервера отсюда.] С информацией по определенным сборкам можно ознакомиться [https://buildinfo.multitheftauto.com/ здесь.]
* Всегда обновляйте ресурсы, установленные на сервере, до самой актуальной версии, вы можете [https://github.com/multitheftauto/mtasa-resources загрузить новейшие (стандартные) ресурсы из репозитория GitHub.] Они часто содержат обновления безопасности, которые влияют на устойчивость вашего сервера к атакам.
* Убедитесь, что [https://wiki.multitheftauto.com/wiki/Access%20Control%20List ACL (список контроля доступа)] правильно сконфигурирован - он поможет заблокировать ресурсам некоторые потенциально опасные функции.
* Никогда не выдавайте админ-права ресурсам (включая карты), полученным из неизвестных источников.
* Перед запуском недоверенного ресурса, изучите:
** Его [https://wiki.multitheftauto.com/wiki/Meta.xml meta.xml], на наличие возможных скрытых скриптов, которые скрываются под видом файлов с другими расширениями.
** Его исходный код, на наличие вредоносной логики.
* Не запускайте и не используйте скомпилированные ресурсы (скрипты), в легитимности которых вы не уверены.

'''Чтобы минимизировать урон, причиненный читером, зашедшим на сервер:'''
* При создании скриптов '''никогда не доверяйте данным, полученным со стороны клиента'''.
* При просмотре скриптов на наличие дыр безопасности, сверяйтесь с данными, поступающими от клиента, которому можно доверять.
* Отправлены могут быть любые данные, поэтому любые серверные скрипты, которые коммуницируют с клиентскими и получают информацию от игроков, '''должны проверять информацию на корректность''' перед дальнейшим использованием. Подделка данных чаще всего происходит с помощью [[setElementData]] и [[triggerServerEvent]].
* Вы не должны полагаться только на [https://wiki.multitheftauto.com/wiki/Serial серийный номер] игрока, когда они используются для критических действий (авто-входа/администраторских действий). '''Не гарантируется, что серийный номер игрока уникален и не подделан'''. Это причина, почему вы должны '''поместить его за''' системой аккаунтов, в качестве '''важного аутентификационного фактора'''.
* Серверная логика '''не может быть обойдена''' (если только сервер не взломан или в коде нет ошибки, но это совсем другой сценарий.) - '''используйте это в своих интересах'''. В большинстве случаев, вы можете реализовать проверки безопасности только на серверной стороне, не привлекая клиент.
* Следование аксиоме '''''“Все параметры, включая source могут быть подделаны и им нельзя доверять. Глобальной переменной client можно доверять.”''''' дает вам уверенность в том, что игрок, к которому вы обращаетесь (через переменную '''client''') '''именно тот, кто вызвал событие'''. Это защищает вас от тех ситуаций, когда читер может вызывать, например, админские события (например, кик/бан игрока), указывая реального администратора ('''второй''' аргумент '''[[triggerServerEvent]]'''), или вызывать события за других игроков (будто они вызвали их, но в реальности это сделал читер) - всего лишь из-за использования некорректной переменной. Чтобы убедиться, что вы это поняли, обратимся к коду:

<syntaxhighlight lang="lua">
--[[
НИКОГДА НЕ ИСПОЛЬЗУЙТЕ ЭТОТ КОД - ОН АБСОЛЮТНО НЕВЕРНЫЙ И НЕБЕЗОПАСНЫЙ
ПРОБЛЕМА: ИСПОЛЬЗУЯ ПЕРЕМЕННУЮ 'source' В hasObjectPermissionTo ВЫ ОСТАВЛЯЕТЕ ДЫРУ ДЛЯ ЧИТЕРОВ
]]

function onServerWrongAdminEvent(playerToBan)
if (not client) then -- 'client' указывает на игрока, который вызвал событие, и должен использоваться в качестве проверки безопасности (для предотвращения подмены игрока)
return false -- если эта переменная не существует (по неизвестной причине), останавливаем выполнение кода
end

local defaultPermission = false -- по стандарту не разрешаем действие, сморите: https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo
local canAdminBanPlayer = hasObjectPermissionTo(source, "function.banPlayer", defaultPermission) -- эксплойт находится здесь...

if (not canAdminBanPlayer) then -- если у игрока нет прав
return false -- останавливаем выполнение кода
end

local validElement = isElement(playerToBan) -- проверяем, что аргумент, переданный игроком, является элементом
if (not validElement) then -- если нет...
return false -- останавливаем выполнение кода
end

local elementType = getElementType(playerToBan) -- это элемент, получаем его тип
local playerType = (elementType == "player") -- проверяем, что тип элемента - игрок

if (not playerType) then -- это не игрок
return false -- останавливаемся
end

-- banPlayer(...) -- делаем, что нужно
end
addEvent("onServerWrongAdminEvent", true)
addEventHandler("onServerWrongAdminEvent", root, onServerWrongAdminEvent)

--[[
onServerCorrectAdminEvent ПРЕКРАСНО ЗАЩИЩЕН, ТАК, КАК ДОЛЖНО БЫТЬ
ЗДЕСЬ НЕТ ПРОБЛЕМ: МЫ ИСПОЛЬЗУЕМ 'client' В hasObjectPermissionTo, ЧТО ЗАЩИЩАЕТ НАС ОТ ПОДМЕНЫ ИГРОКА, КОТОРЫЙ ВЫЗВАЛ СОБЫТИЕ
]]--

function onServerCorrectAdminEvent(playerToBan)
if (not client) then -- 'client' указывает на игрока, который вызвал событие, и должен использоваться в качестве проверки безопасности (для предотвращения подмены игрока)
return false -- если эта переменная не существует (по неизвестной причине), останавливаем выполнение кода
end

local defaultPermission = false -- по стандарту не разрешаем действие, сморите: https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo
local canAdminBanPlayer = hasObjectPermissionTo(client, "function.banPlayer", defaultPermission) -- если игрок имеет права

if (not canAdminBanPlayer) then -- если у игрока нет прав
return false -- останавливаем выполнение кода
end

local validElement = isElement(playerToBan) -- проверяем, что аргумент, переданный игроком, является элементом
if (not validElement) then -- если нет...
return false -- останавливаем выполнение кода
end

local elementType = getElementType(playerToBan) -- это элемент, получаем его тип
local playerType = (elementType == "player") -- проверяем, что тип элемента - игрок

if (not playerType) then -- это не игрок
return false -- останавливаемся
end

-- banPlayer(...) -- делаем, что нужно
end
addEvent("onServerCorrectAdminEvent", true)
addEventHandler("onServerCorrectAdminEvent", root, onServerCorrectAdminEvent)
</syntaxhighlight>

==Securing setElementData==

* You should refrain from using [[element data]] everywhere, it should be only used when really necessary. It is advised to replace it with [[triggerClientEvent]] instead.
* If you still insist on using it, it is recommended to set '''4th''' argument in [[setElementData]] to '''false''' (disabling sync for this, certain data) and use subscriber mode - [[addElementDataSubscriber]], for both security & performance reasons described in [https://wiki.multitheftauto.com/wiki/Script_security#Securing_triggerServerEvent event section.]
{{Important Note|Disabling sync however, doesn't fully protect data key. It would be still vulnerable by default, but in this case you are not leaving it in plain sight. Using [[getAllElementData]] or digging in RAM wouldn't expose it, since it won't be synced to client in first place. Therefore, it needs to be added to anti-cheat as well.}}
* All parameters including '''source''' can be faked and should not be trusted.
* Global variable '''client''' can be trusted.

----------
<section name="Server" class="server" show="true">
Example of basic element data anti-cheat.
<syntaxhighlight lang="lua">
local function reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue) -- helper function to log and revert changes
local logClient = inspect(clientElement) -- in-depth view of player which forced element data sync
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = tostring(sourceElement) -- element which received data
local logOldValue = tostring(oldValue) -- old value
local logNewValue = tostring(newValue) -- new value
local logText = -- fill our report with data
"=======================================\n"..
"Detected element data abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Data key: "..dataKey.."\n"..
"Old data value: "..logOldValue.."\n"..
"New data value: "..logNewValue.."\n"..
"======================================="

local logVisibleTo = root -- specify who will see this log in console, in this case each player connected to server
local hadData = (oldValue ~= nil) -- check if element had such data before

if (hadData) then -- if element had such data before
setElementData(sourceElement, dataKey, oldValue, true) -- revert changes, it will call onElementDataChange event, but will fail (stop) on first condition - because server (not client) forced change
else
removeElementData(sourceElement, dataKey) -- remove it completely
end

outputConsole(logText, logVisibleTo) -- print it to console

return true -- all success
end

function onElementDataChangeBasicAC(dataKey, oldValue, newValue) -- the heart of our anti-cheat, which does all the magic security measurements
if (not client) then -- check if data is coming from client
return false -- if it's not, do not go further
end

local checkSpecialThing = (dataKey == "special_thing") -- compare whether dataKey matches "special_thing"
local checkFlagWaving = (dataKey == "flag_waving") -- compare whether dataKey matches "flag_waving"

if (checkSpecialThing) then -- if it does, do our security checks
local invalidElement = (client ~= source) -- verify whether source element is different from player which changed data

if (invalidElement) then -- if it's so
reportAndRevertDataChange(client, source, dataKey, oldValue, newValue) -- revert data change, because "special_thing" can only be set for player himself
end
end

if (checkFlagWaving) then -- if it does, do our security checks
local playerVehicle = getPedOccupiedVehicle(client) -- get player's current vehicle
local invalidVehicle = (playerVehicle ~= source) -- verify whether source element is different from player's vehicle

if (invalidVehicle) then -- if it's so
reportAndRevertDataChange(client, source, dataKey, oldValue, newValue) -- revert data change, because "flag_waving" can only be set for player's own vehicle
end
end
end
addEventHandler("onElementDataChange", root, onElementDataChangeBasicAC)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
Example of advanced element data anti-cheat.
<syntaxhighlight lang="lua">
--[[
For maximum security set punishPlayerOnDetect, punishmentBan, allowOnlyProtectedKeys to true (as per default configuration)
If allowOnlyProtectedKeys is enabled, do not forget to add every client-side element data key to protectedKeys table - otherwise you will face false-positives

Anti-cheat (handleDataChange) table structure and it's options:

["keyName"] = { -- name of key which would be protected
onlyForPlayerHimself = true, -- enabling this (true) will make sure that this element data key can only be set on player who synced it (ignores onlyForOwnPlayerVeh and allowForElements), use false/nil to disable this
onlyForOwnPlayerVeh = false, -- enabling this (true) will make sure that this element data key can only be set on player's current vehicle who synced it (ignores allowForElements), use false/nil to disable this
allowForElements = { -- restrict this key for certain element type(s), set to false/nil or leave it empty to not check this (full list of element types: https://wiki.multitheftauto.com/wiki/GetElementsByType)
["player"] = true,
["ped"] = true,
["vehicle"] = true,
["object"] = true,
},
allowedDataTypes = { -- restrict this key for certain value type(s), set to false/nil or leave it empty to not check this
["string"] = true,
["number"] = true,
["table"] = true,
["boolean"] = true,
["nil"] = true,
},
allowedStringLength = {1, 32}, -- if value is a string, then it's length must be in between (min-max), set it to false/nil to not check string length - do note that allowedDataTypes must contain ["string"] = true
allowedTableLength = {1, 64}, -- if value is a table, then it's length must be in between (min-max), set it to false/nil to not check table length - do note that allowedDataTypes must contain ["table"] = true
allowedNumberRange = {1, 128}, -- if value is a number, then it must be in between (min-max), set it to false/nil to not check number range - do note that allowedDataTypes must contain ["number"] = true
}
]]

local punishPlayerOnDetect = true -- should player be punished upon detection (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Altering element data" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local allowOnlyProtectedKeys = true -- disallow (remove by using removeElementData) every element data besides those given in protectedKeys table; in case someone wanted to flood server with garbage keys, which would be kept in memory until server restart or manual remove - setElementData(source, key, nil) won't remove it; it has to be removeElementData
local debugLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugR = 255 -- debug message - red color
local debugG = 127 -- debug message - green color
local debugB = 0 -- debug message - blue color
local protectedKeys = {
["vehicleNumber"] = { -- we want vehicleNumber to be set only on vehicles, with stricte numbers in range of 1-100
allowForElements = {
["vehicle"] = true,
},
allowedDataTypes = {
["number"] = true,
},
allowedNumberRange = {1, 100},
},
["personalVehData"] = { -- we want be able to set personalVehData only on current vehicle, also it should be a string with length between 1-24
onlyForOwnPlayerVeh = true,
allowedDataTypes = {
["string"] = true,
},
allowedStringLength = {1, 24},
},
-- perform security checks on keys stored in this table, in a convenient way
}

local function reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- helper function to log and revert changes
local logClient = inspect(clientElement) -- in-depth view of player which forced element data sync
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = inspect(sourceElement) -- in-depth view of element which received data
local logOldValue = inspect(oldValue) -- in-depth view of old value
local logNewValue = inspect(newValue) -- in-depth view of new value
local logText = -- fill our report with data
"*\n"..
"Detected element data abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Data key: "..dataKey.."\n"..
"Old data value: "..logOldValue.."\n"..
"New data value: "..logNewValue.."\n"..
"Fail reason: "..failReason.."\n"..
"*"

outputDebugString(logText, debugLevel, debugR, debugG, debugB) -- print it to debug

if (forceRemove) then -- we don't want this element data key to exist at all
removeElementData(sourceElement, dataKey) -- remove it

return true -- return success and stop here, we don't need further checks
end

setElementData(sourceElement, dataKey, oldValue, true) -- revert changes, it will call onElementDataChange event, but will fail (stop) on first condition - because server (not client) forced change

return true -- return success
end

local function handleDataChange(clientElement, sourceElement, dataKey, oldValue, newValue) -- the heart of our anti-cheat, which does all the magic security measurements, returns true if there was no altering from client (based on data from protectedKeys), false otherwise
local protectedKey = protectedKeys[dataKey] -- look up whether key changed is stored in protectedKeys table

if (not protectedKey) then -- if it's not

if (allowOnlyProtectedKeys) then -- if we don't want garbage keys
local failReason = "Key isn't present in protectedKeys" -- reason shown in report
local forceRemove = true -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end

return true -- this key isn't protected, let it through
end

local onlyForPlayerHimself = protectedKey.onlyForPlayerHimself -- if key has "self-set" lock
local onlyForOwnPlayerVeh = protectedKey.onlyForOwnPlayerVeh -- if key has "self-vehicle" lock
local allowForElements = protectedKey.allowForElements -- if key has element type check
local allowedDataTypes = protectedKey.allowedDataTypes -- if key has allowed data type check

if (onlyForPlayerHimself) then -- if "self-set" lock is active
local matchingElement = (clientElement == sourceElement) -- verify whether player who set data is equal to element which received data

if (not matchingElement) then -- if it's not matching
local failReason = "Can only set on player himself" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (onlyForOwnPlayerVeh) then -- if "self-vehicle" lock is active
local playerVehicle = getPedOccupiedVehicle(clientElement) -- get current vehicle of player which set data
local matchingVehicle = (playerVehicle == sourceElement) -- check whether it matches the one which received data

if (not matchingVehicle) then -- if it doesn't match
local failReason = "Can only set on player's own vehicle" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowForElements) then -- check if it's one of them
local elementType = getElementType(sourceElement) -- get type of element whose data changed
local matchingElementType = allowForElements[elementType] -- verify whether it's allowed

if (not matchingElementType) then -- this isn't matching
local failReason = "Invalid element type" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedDataTypes) then -- if there's allowed data types
local valueType = type(newValue) -- get data type of value
local matchingType = allowedDataTypes[valueType] -- check if it's one of allowed

if (not matchingType) then -- if it's not then
local failReason = "Invalid data type" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end

local allowedStringLength = protectedKey.allowedStringLength -- if key has specified string length check
local dataString = (valueType == "string") -- make sure it's a string

if (allowedStringLength and dataString) then -- if we should check string length
local minLength = allowedStringLength[1] -- retrieve min length
local maxLength = allowedStringLength[2] -- retrieve max length
local stringLength = utf8.len(newValue) -- get length of data string
local matchingLength = (stringLength >= minLength) and (stringLength <= maxLength) -- compare whether value fits in between

if (not matchingLength) then -- if it doesn't
local failReason = "Invalid string length (must be between "..minLength.."-"..maxLength..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedTableLength = protectedKey.allowedTableLength -- if key has table length check
local dataTable = (valueType == "table") -- make sure it's a table

if (allowedTableLength and dataTable) then -- if we should check table length
local minLength = allowedTableLength[1] -- retrieve min length
local maxLength = allowedTableLength[2] -- retrieve max length
local minLengthAchieved = false -- variable which checks 'does minimum length was achieved'
local maxLengthExceeded = false -- variable which checks 'does length has exceeds more than allowed maximum'
local tableLength = 0 -- store initial table length

for _, _ in pairs(newValue) do -- loop through whole table
tableLength = (tableLength + 1) -- add + 1 on each table entry
minLengthAchieved = (tableLength >= minLength) -- is length bigger or at very minimum we require
maxLengthExceeded = (tableLength > maxLength) -- does table exceeded more than max length?

if (maxLengthExceeded) then -- it is bigger than it should be
break -- break the loop (due of condition above being worthy, it makes no point to count further and waste CPU, on a table which potentially could have huge amount of entries)
end
end

local matchingLength = (minLengthAchieved and not maxLengthExceeded) -- check if min length has been achieved, and make sure that it doesn't go beyond max length

if (not matchingLength) then -- this table doesn't match requirements
local failReason = "Invalid table length (must be between "..minLength.."-"..maxLength..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedNumberRange = protectedKey.allowedNumberRange -- if key has allowed number range check
local dataNumber = (valueType == "number") -- make sure it's a number

if (allowedNumberRange and dataNumber) then -- if we should check number range
local minRange = allowedNumberRange[1] -- retrieve min number range
local maxRange = allowedNumberRange[2] -- retrieve max number range
local matchingRange = (newValue >= minRange) and (newValue <= maxRange) -- compare whether value fits in between

if (not matchingRange) then -- if it doesn't
local failReason = "Invalid number range (must be between "..minRange.."-"..maxRange..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end
end

return true -- security checks passed, we are all clear with this data key
end

function onElementDataChangeAdvancedAC(dataKey, oldValue, newValue) -- this event makes use of handleDataChange, the code was split for better readability
if (not client) then -- check if data is coming from client
return false -- if it's not, do not continue
end

local approvedChange = handleDataChange(client, source, dataKey, oldValue, newValue) -- run our security checks

if (approvedChange) then -- it's all cool and good
return false -- we don't need further action
end

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(client, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(client, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onElementDataChange", root, onElementDataChangeAdvancedAC)
</syntaxhighlight>
</section>

==Securing triggerServerEvent==

* All parameters including '''source''' can be faked and should not be trusted.
* Global variable '''client''' can be trusted.
* '''Admin''' styled '''events''' should be verifying player (client) '''ACL rights''', either by [https://wiki.multitheftauto.com/wiki/IsObjectInACLGroup isObjectInACLGroup] or [https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo hasObjectPermissionTo].
* Do '''not''' use the same name for your custom event as MTA native server events (which aren't remotely triggerable by default), e.g: '''onPlayerLogin'''; doing so would open door for cheaters manipulations.
* Be aware to which players event is sent via [[triggerClientEvent]]. For both security & performance reasons, admin like events should be received by admins only (to prevent confidential data being accessed), in the same time you shouldn't send each event to everyone on server (e.g: login success event which hides login panel for certain player). [[triggerClientEvent]] allows you to specify the event receiver as first (optional) argument. It defaults to [[root]], meaning if you don't specify it, it will be sent to everyone connected to server - even those who are still downloading server cache (which results in ''Server triggered clientside event eventName, but event is not added clientside.''). You can either pass player element or table with receivers:
<syntaxhighlight lang="lua">
local playersToReceiveEvent = {player1, player2, player3} -- each playerX is player element

triggerClientEvent(playersToReceiveEvent, ...) -- do not forget to fill the latter part of arguments
</syntaxhighlight>

----------
<section name="Server" class="server" show="true">
Example of anti-cheat function designed for events, used for data validation for both normal, and admin events which are called from client-side.
<syntaxhighlight lang="lua">
--[[
For maximum security set punishPlayerOnDetect, punishmentBan to true (as per default configuration)

Anti-cheat (processServerEventData) table structure and it's options:

checkACLGroup = { -- check whether player who called event belongs to at least one group below, set to false/nil to not check this
"Admin",
},
checkPermissions = { -- check whether player who called event has permission to at least one thing below, set to false/nil to not check this
"function.kickPlayer",
},
checkEventData = {
{
debugData = "source", -- optional details for report shown in debug message
eventData = source, -- data we want to verify
equalTo = client, -- compare whether eventData == equalTo
allowedElements = { -- restrict eventData to be certain element type(s), set to false/nil or leave it empty to not check this (full list of element types: https://wiki.multitheftauto.com/wiki/GetElementsByType)
["player"] = true,
["ped"] = true,
["vehicle"] = true,
["object"] = true,
},
allowedDataTypes = { -- restrict eventData to be certain value type(s), set to false/nil or leave it empty to not check this
["string"] = true,
["number"] = true,
["table"] = true,
["boolean"] = true,
["nil"] = true,
},
allowedStringLength = {1, 32}, -- if eventData is a string, then it's length must be in between (min-max), set it to false/nil to not check string length - do note that allowedDataTypes must contain ["string"] = true
allowedTableLength = {1, 64}, -- if eventData is a table, then it's length must be in between (min-max), set it to false/nil to not check table length - do note that allowedDataTypes must contain ["table"] = true
allowedNumberRange = {1, 128}, -- if eventData is a number, then it must be in between (min-max), set it to false/nil to not check number range - do note that allowedDataTypes must contain ["number"] = true
},
},
]]

local punishPlayerOnDetect = true -- should player be punished upon detection (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Altering server event data" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugR = 255 -- debug message - red color
local debugG = 127 -- debug message - green color
local debugB = 0 -- debug message - blue color

function processServerEventData(clientElement, sourceElement, serverEvent, securityChecks) -- the heart of our anti-cheat, which does all the magic security measurements, returns true if there was no altering from client (based on data from securityChecks), false otherwise
if (not securityChecks) then -- if we haven't passed any security checks
return true -- nothing to check, let code go further
end

if (not clientElement) then -- if client variable isn't available for some reason (although it should never happen)
local failReason = "Client variable not present" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local checkACLGroup = securityChecks.checkACLGroup -- if there's any ACL groups to check
local checkPermissions = securityChecks.checkPermissions -- if there's any permissions to check
local checkEventData = securityChecks.checkEventData -- if there's any data checks

if (checkACLGroup) then -- let's check player ACL groups
local playerAccount = getPlayerAccount(clientElement) -- get current account of player
local guestAccount = isGuestAccount(playerAccount) -- if account is guest (meaning player is not logged in)

if (guestAccount) then -- it's the case
local failReason = "Can't retrieve player login - guest account" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local accountName = getAccountName(playerAccount) -- get name of player's current account
local aclString = "user."..accountName -- format it for further use in isObjectInACLGroup function

for groupID = 1, #checkACLGroup do -- iterate over table of given groups
local groupName = checkACLGroup[groupID] -- get each group name
local aclGroup = aclGetGroup(groupName) -- check if such group exists

if (not aclGroup) then -- it doesn't
local failReason = "ACL group '"..groupName.."' is missing" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local playerInACLGroup = isObjectInACLGroup(aclString, aclGroup) -- check if player belong to the group

if (playerInACLGroup) then -- yep, it's the case
return true -- so it's a success
end
end

local failReason = "Player doesn't belong to any given ACL group" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

if (checkPermissions) then -- check if player has at least one desired permission
local allowedByDefault = false -- does he have access by default

for permissionID = 1, #checkPermissions do -- iterate over all permissions
local permissionName = checkPermissions[permissionID] -- get permission name
local hasPermission = hasObjectPermissionTo(clientElement, permissionName, allowedByDefault) -- check whether player is allowed to perform certain action

if (hasPermission) then -- if player has access
return true -- one is available (and enough), server won't bother to check others (as return keywords also breaks loop)
end
end

local failReason = "Not enough permissions" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

if (checkEventData) then -- if there is some data to verify

for dataID = 1, #checkEventData do -- iterate over each of data
local dataToCheck = checkEventData[dataID] -- get each data set
local eventData = dataToCheck.eventData -- this is the one we'll be verifying
local equalTo = dataToCheck.equalTo -- we want to compare whether eventData == equalTo
local allowedElements = dataToCheck.allowedElements -- check whether is element, and whether belongs to certain element types
local allowedDataTypes = dataToCheck.allowedDataTypes -- do we restrict data to be certain type?
local debugData = dataToCheck.debugData -- additional helper data
local debugText = debugData and " ("..debugData..")" or "" -- if it's present, format it nicely

if (equalTo) then -- equal check exists
local matchingData = (eventData == equalTo) -- compare whether those two values are equal

if (not matchingData) then -- they aren't
local failReason = "Data isn't equal @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedElements) then -- we do check whether is an element, and belongs to at least one given in the list
local validElement = isElement(eventData) -- check if it's actual element

if (not validElement) then -- it's not
local failReason = "Data isn't element @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local elementType = getElementType(eventData) -- it's element, so we want to know it's type
local matchingElementType = allowedElements[elementType] -- verify whether it's allowed

if (not matchingElementType) then -- it's not allowed
local failReason = "Invalid element type @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedDataTypes) then -- let's check allowed data types
local dataType = type(eventData) -- get data type
local matchingType = allowedDataTypes[dataType] -- verify whether it's allowed

if (not matchingType) then -- it isn't
local failReason = "Invalid data type @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local allowedStringLength = dataToCheck.allowedStringLength -- if data has string length check
local dataString = (dataType == "string") -- make sure it's a string

if (allowedStringLength and dataString) then -- if we should check string length
local minLength = allowedStringLength[1] -- retrieve min length
local maxLength = allowedStringLength[2] -- retrieve max length
local stringLength = utf8.len(eventData) -- get length of data string
local matchingLength = (stringLength >= minLength) and (stringLength <= maxLength) -- compare whether value fits in between

if (not matchingLength) then -- if it doesn't
local failReason = "Invalid string length (must be between "..minLength.."-"..maxLength..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedTableLength = dataToCheck.allowedTableLength -- if data has table length check
local dataTable = (dataType == "table") -- make sure it's a table

if (allowedTableLength and dataTable) then -- if we should check table length
local minLength = allowedTableLength[1] -- retrieve min length
local maxLength = allowedTableLength[2] -- retrieve max length
local minLengthAchieved = false -- variable which checks 'does minimum length was achieved'
local maxLengthExceeded = false -- variable which checks 'does length has exceeds more than allowed maximum'
local tableLength = 0 -- store initial table length

for _, _ in pairs(eventData) do -- loop through whole table
tableLength = (tableLength + 1) -- add + 1 on each table entry
minLengthAchieved = (tableLength >= minLength) -- is length bigger or at very minimum we require
maxLengthExceeded = (tableLength > maxLength) -- does table exceeded more than max length?

if (maxLengthExceeded) then -- it is bigger than it should be
break -- break the loop (due of condition above being worthy, it makes no point to count further and waste CPU, on a table which potentially could have huge amount of entries)
end
end

local matchingLength = (minLengthAchieved and not maxLengthExceeded) -- check if min length has been achieved, and make sure that it doesn't go beyond max length

if (not matchingLength) then -- this table doesn't match requirements
local failReason = "Invalid table length (must be between "..minLength.."-"..maxLength..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedNumberRange = dataToCheck.allowedNumberRange -- if data has number range check
local dataNumber = (dataType == "number") -- make sure it's a number

if (allowedNumberRange and dataNumber) then -- if we should check number range
local minRange = allowedNumberRange[1] -- retrieve min number range
local maxRange = allowedNumberRange[2] -- retrieve max number range
local matchingRange = (eventData >= minRange) and (eventData <= maxRange) -- compare whether value fits in between

if (not matchingRange) then -- if it doesn't
local failReason = "Invalid number range (must be between "..minRange.."-"..maxRange..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end
end
end
end

return true -- security checks passed, we are all clear with this event call
end

function reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- helper function to log and handle accidents
local logClient = inspect(clientElement) -- in-depth view player which called event
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = inspect(sourceElement) -- in-depth view of source element
local logText = -- fill our report with data
"*\n"..
"Detected event abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Event: "..serverEvent.."\n"..
"Reason: "..failReason.."\n"..
"*"

outputDebugString(logText, debugLevel, debugR, debugG, debugB) -- print it to debug

if (not punishPlayerOnDetect or skipPunishment) then -- we don't want to punish player for some reason
return true -- stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(clientElement, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(clientElement, punishedBy, punishmentReason) -- simply kick player out of server
end

return true -- all done, report success
end

function onServerEvent(clientData)
--[[
Assume this server event (function) is called in such way:

local dataToPass = 10

triggerServerEvent("onServerEvent", localPlayer, dataToPass)
]]

local shouldProcessServerCode = processServerEventData(
client, -- client element - responsible for calling event
source, -- source element - passed in triggerServerEvent (as 2nd argument)
eventName, -- name of event - in this case 'onServerEvent'
{
checkEventData = { -- we want to verify everything what comes from client
{
eventData = source, -- first to check, source variable
equalTo = client, -- we want to check whether it matches player who called event
debugData = "source", -- helper details which would be shown in report
},
{
eventData = clientData, -- let's check the data which client sent to us
allowedDataTypes = {
["number"] = true, -- we want it to be only number
},
allowedNumberRange = {1, 100}, -- in range of 1 to 100
debugData = "clientData", -- if something goes wrong, let server know where (it will appear in debug report)
},
},
}
)

if (not shouldProcessServerCode) then -- something isn't right, no green light for processing code behind this scope
return false -- stop code execution
end

-- do code as usual
end
addEvent("onServerEvent", true)
addEventHandler("onServerEvent", root, onServerEvent)

function onServerAdminEvent(playerToBan)
--[[
Assume this server admin event (function) is called in such way:

local playerToBan = getPlayerFromName("playerToBan")

triggerServerEvent("onServerAdminEvent", localPlayer, playerToBan)
]]

local shouldProcessServerCode = processServerEventData(
client, -- client element - responsible for calling event
source, -- source element - passed in triggerServerEvent (as 2nd argument)
eventName, -- name of event - in this case 'onServerAdminEvent'
{
checkACLGroup = { -- we need to check whether player who called event belongs to ACL groups
"Admin", -- in this case admin group
},
checkEventData = { -- we want to verify everything what comes from client
{
eventData = source, -- first to check, source variable
equalTo = client, -- we want to check whether it matches player who called event
debugData = "source", -- helper details which would be shown in report
},
{
eventData = playerToBan, -- let's check the data which client sent to us
allowedDataTypes = {
["player"] = true, -- we want it to be player
},
debugData = "playerToBan", -- if something goes wrong, let server know where (it will appear in debug report)
},
},
}
)

if (not shouldProcessServerCode) then -- something isn't right, no green light for processing code behind this scope
return false -- stop code execution
end

-- do code as usual
end
addEvent("onServerAdminEvent", true)
addEventHandler("onServerAdminEvent", root, onServerAdminEvent)
</syntaxhighlight>
</section>

==Securing server-only events==
* It is very important to '''disable remote triggering''' ability in [https://wiki.multitheftauto.com/wiki/AddEvent addEvent], to prevent calling server-side only events from client-side.
* '''Admin''' styled '''events''' should be verifying player '''ACL rights''', either by [https://wiki.multitheftauto.com/wiki/IsObjectInACLGroup isObjectInACLGroup] or [https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo hasObjectPermissionTo].

----------
<section name="Server" class="server" show="true">
This example shows how you should make event server-side only.
<syntaxhighlight lang="lua">
function onServerSideOnlyEvent()
-- do some server-side stuff
end
addEvent("onServerSideOnlyEvent", false) -- set second argument (allowRemoteTriger) to false, so it can't be called from client
addEventHandler("onServerSideOnlyEvent", root, onServerSideOnlyEvent) -- associate our event with function onServerSideOnlyEvent
</syntaxhighlight>
</section>

==Securing projectiles & explosions==
This section (and '''code''' is '''work in progress''') - '''use at your own risk'''.

----------
<section name="Server" class="server" show="false">
Projectile ammo tracker:
<syntaxhighlight lang="lua">
local playerProjectileAmmo = {} -- store player-held weapons ammo here
local playerWeaponsToTrack = { -- keep track of ammo for certain player-held weapon types, basically those which create projectile; [weaponID] = weaponSlot
[16] = 8, -- grenade
[17] = 8, -- teargas
[18] = 8, -- molotov
[35] = 7, -- rocket launcher
[36] = 7, -- rocket launcher (heat-seeking)
[39] = 8, -- satchel charge
}

local function updateProjectileAmmoForPlayer(playerElement)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

for weaponID, weaponSlot in pairs(playerWeaponsToTrack) do
local weaponInSlot = getPedWeapon(playerElement, weaponSlot)
local weaponTotalAmmo = getPedTotalAmmo(playerElement, weaponSlot)
local weaponHasAmmo = (weaponTotalAmmo > 0)
local weaponMatching = (weaponInSlot == weaponID)
local updateWeaponAmmo = (weaponMatching and weaponHasAmmo)

if (updateWeaponAmmo) then
local storedProjectileAmmo = playerProjectileAmmo[playerElement]
local newWeaponAmmo = (updateWeaponAmmo and weaponTotalAmmo or nil)

if (not storedProjectileAmmo) then
playerProjectileAmmo[playerElement] = {}
storedProjectileAmmo = playerProjectileAmmo[playerElement]
end

storedProjectileAmmo[weaponID] = newWeaponAmmo
end
end

return true
end

function hasPlayerProjectileAmmo(playerElement, projectileWeapon)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

local projectileData = playerProjectileAmmo[playerElement]
local projectileAmmo = (projectileData and projectileData[projectileWeapon])

return projectileAmmo
end

function decreasePlayerProjectileAmmo(playerElement, projectileWeapon)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

local playerProjectileData = playerProjectileAmmo[playerElement]

if (not playerProjectileData) then
return false
end

local projectileWeaponAmmo = playerProjectileData[projectileWeapon]
local tempProjectileAmmo = (projectileWeaponAmmo - 1)
local newProjectileAmmo = (tempProjectileAmmo > 0 and tempProjectileAmmo or nil)

playerProjectileData[projectileWeapon] = newProjectileAmmo

return true
end

function onPlayerWeaponSwitchAntiCheat(previousWeaponID, currentWeaponID)
setTimer(updateProjectileAmmoForPlayer, 50, 1, source)
end
addEventHandler("onPlayerWeaponSwitch", root, onPlayerWeaponSwitchAntiCheat)

function onResourceStartAntiCheat()
local playersTable = getElementsByType("player")

for playerID = 1, #playersTable do
local playerElement = playersTable[playerID]

updateProjectileAmmoForPlayer(playerElement)
end
end
addEventHandler("onResourceStart", resourceRoot, onResourceStartAntiCheat)

function onPlayerWastedQuitAntiCheat()
playerProjectileAmmo[source] = nil
end
addEventHandler("onPlayerWasted", root, onPlayerWastedQuitAntiCheat)
addEventHandler("onPlayerQuit", root, onPlayerWastedQuitAntiCheat)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
Projectile handler:
<syntaxhighlight lang="lua">
local playerCreatedProjectiles = {} -- store count of legitimately created player projectiles; [playerElement] = {[projectileType] = activeProjectiles}
local projectileTypes = {
[16] = { -- Grenade
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[16] = true, -- grenade
},
},
[17] = { -- Teargas
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[17] = true, -- teargas
},
},
[18] = { -- Molotov
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[18] = true, -- molotov
},
},
[19] = { -- Rocket
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileMaxVelocity = 2,
projectileAllowedWeapons = {
[35] = true, -- rocket launcher
},
projectileAllowedVehicles = {
[425] = true, -- hunter
[520] = true, -- hydra
},
},
[20] = { -- Rocket (heat-seeking)
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileMaxVelocity = 2,
projectileAllowedWeapons = {
[36] = true, -- rocket launcher (heat-seeking)
},
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
[21] = { -- Airbomb
projectileAllowed = true,
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
[39] = { -- Satchel charge
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[39] = true, -- satchel charge
},
},
[58] = { -- Hydra flare
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
}

local reportAbnormality = true -- whether to report about abnormality in debug script - by default
local punishPlayerOnDetect = false -- should player be punished upon detection; true - yes, or false to not do anything (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Projectile/explosion anti-cheat" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugMsgLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugMsgR = 255 -- debug message - red color
local debugMsgG = 127 -- debug message - green color
local debugMsgB = 0 -- debug message - blue color

local function reportProjectileAbnormality(playerElement, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ, detectionCode)
local projectileSyncer = inspect(playerElement)
local projectilePosition = projectileX..", "..projectileY..", "..projectileZ
local projectileZoneName = getZoneName(projectileX, projectileY, projectileZ, false)
local projectileCityName = getZoneName(projectileX, projectileY, projectileZ, true)
local projectileLog =
"* Detected projectile abnormality - "..detectionCode.." *\n"..
"Projectile syncer: "..projectileSyncer.."\n"..
"Projectile type: "..projectileType.."\n"..
"Projectile position: "..projectilePosition.. " ("..projectileZoneName..", "..projectileCityName..")\n"

outputDebugString(projectileLog, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)

return true
end

local function processProjectileChecks(playerElement, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)
local projectileData = projectileTypes[projectileType]
local projectileAllowed = projectileData.projectileAllowed

if (not projectileAllowed) then
return false, "Projectile not allowed"
end

local projectileAllowedWeapons = projectileData.projectileAllowedWeapons

if (projectileAllowedWeapons) then
local playerWeapon = getPedWeapon(playerElement)
local allowedWeapon = projectileAllowedWeapons[playerWeapon]

if (not allowedWeapon) then
return false, "Player is not holding correct weapon"
end

local weaponAmmo = hasPlayerProjectileAmmo(playerElement, playerWeapon)
local playerHasAmmo = (weaponAmmo > 0)

if (not playerHasAmmo) then
return false, "Player doesn't have ammo for weapon"
end

decreasePlayerProjectileAmmo(playerElement, playerWeapon)
end

local playerVehicle = getPedOccupiedVehicle(playerElement)

if (playerVehicle) then
local projectileAllowedVehicles = projectileData.projectileAllowedVehicles

if (projectileAllowedVehicles) then
local vehicleModel = getElementModel(playerVehicle)
local allowedVehicle = projectileAllowedVehicles[vehicleModel]

if (not allowedVehicle) then
return false, "Player is not inside allowed vehicles"
end

local vehicleDriver = getVehicleController(playerVehicle)
local playerDriver = (playerElement == vehicleDriver)

if (not playerDriver) then
return false, "Player is not vehicle driver"
end

return true
end

return false, "Player in vehicle"
end

local projectileMaxDistanceFromCreator = projectileData.projectileMaxDistanceFromCreator

if (projectileMaxDistanceFromCreator) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToProjectile = getDistanceBetweenPoints3D(playerX, playerY, playerZ, projectileX, projectileY, projectileZ)
local matchingProjectileDistance = (distanceToProjectile <= projectileMaxDistanceFromCreator)

if (not matchingProjectileDistance) then
return false, "Projectile distance mismatch"
end
end

local projectileMaxVelocity = projectileData.projectileMaxVelocity

if (projectileMaxVelocity) then
local projectileVelocity = (projectileVX ^ 2 + projectileVY ^ 2 + projectileVZ ^ 2)
local projectileSpeed = math.sqrt(projectileVelocity)
local matchingProjectileVelocity = (projectileSpeed <= projectileMaxVelocity)

if (not matchingProjectileVelocity) then
return false, "Projectile velocity mismatch"
end
end

return true
end

local function trackPlayerProjectile(playerElement, projectileID)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerProjectiles = playerCreatedProjectiles[playerElement]

if (not playerProjectiles) then
playerCreatedProjectiles[playerElement] = {}
playerProjectiles = playerCreatedProjectiles[playerElement]
end

local projectilesByType = playerProjectiles[projectileID] or 0
local newProjectilesCount = (projectilesByType + 1)

playerProjectiles[projectileID] = newProjectilesCount

return true
end

local function getProjectileDetectionOverwrittenBehavior(projectileType)
local projectileData = projectileTypes[projectileType]

if (not projectileData) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local projectileBehaviour = projectileData.projectileOverwriteBehaviour

if (not projectileBehaviour) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local overwriteReport = projectileBehaviour.reportAbnormality
local overwritePunish = projectileBehaviour.punishPlayerOnDetect
local overwriteBan = projectileBehaviour.punishmentBan

return overwriteReport, overwritePunish, overwriteBan
end

function decreasePlayerProjectiles(playerElement, projectileID)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerProjectiles = playerCreatedProjectiles[playerElement]

if (not playerProjectiles) then
return false, true
end

local projectilesByType = playerProjectiles[projectileID]

if (not projectilesByType) then
return false, true
end

local tempProjectilesCount = (projectilesByType - 1)
local newProjectilesCount = (tempProjectilesCount > 0 and tempProjectilesCount or nil)

playerProjectiles[projectileID] = newProjectilesCount

return true
end

function onPlayerProjectileCreationAntiCheat(projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)
local approvedProjectile, detectionCode = processProjectileChecks(source, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)

if (approvedProjectile) then
trackPlayerProjectile(source, projectileType)

return true
end

local reportAbnormality, punishPlayerOnDetect, punishmentBan = getProjectileDetectionOverwrittenBehavior(projectileType)

if (reportAbnormality) then
reportProjectileAbnormality(source, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ, detectionCode)
end

cancelEvent()

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(source, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(source, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onPlayerProjectileCreation", root, onPlayerProjectileCreationAntiCheat)

function onPlayerQuitAntiCheat()
playerCreatedProjectiles[source] = nil
end
addEventHandler("onPlayerQuit", root, onPlayerQuitAntiCheat)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
Explosions handler:
<syntaxhighlight lang="lua">
local rocketInstantExplosionDistanceThreshold = 1.55 -- distance below which only explosion will be created (and not rocket projectile, hence not calling onPlayerProjectileCreation); do not change it
local explosionTypes = { -- more specific info on explosion, and whether it is allowed
[0] = { -- Grenade
explosionAllowed = true,
explosionAllowedProjectiles = {
[16] = true, -- grenade
},
},
[1] = { -- Molotov
explosionAllowed = true,
explosionAllowedProjectiles = {
[18] = true, -- molotov
},
},
[2] = { -- Rocket
explosionAllowed = true,
explosionAllowedWeapons = {
[35] = true, -- rocket launcher
[36] = true, -- rocket launcher (heat-seeking)
},
explosionAllowedProjectiles = {
[19] = true, -- rocket
[20] = true, -- rocket (heat-seeking)
},
},
[3] = { -- Rocket weak
explosionAllowed = true,
explosionAllowedProjectiles = {
[19] = true, -- rocket
[20] = true, -- rocket (heat-seeking)
},
},
[4] = { -- Car
explosionAllowed = true,
},
[5] = { -- Car quick
explosionAllowed = true,
},
[6] = { -- Boat
explosionAllowed = true,
},
[7] = { -- Heli
explosionAllowed = true,
},
[8] = { -- Mine
explosionAllowed = true,
},
[9] = { -- Object
explosionAllowed = true,
},
[10] = { -- Tank grenade
explosionAllowed = true,
explosionMaxDistanceFromCreator = 80,
explosionAllowedVehicles = {
[432] = true,
}
},
[11] = { -- Small
explosionAllowed = true,
},
[12] = { -- Tiny
explosionAllowed = true,
},
}

local reportAbnormality = true -- whether to report about abnormality in debug script - by default
local punishPlayerOnDetect = false -- should player be punished upon detection; true - yes, or false to not do anything (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Projectile/explosion anti-cheat" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugMsgLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugMsgR = 255 -- debug message - red color
local debugMsgG = 127 -- debug message - green color
local debugMsgB = 0 -- debug message - blue color

local function reportExplosionAbnormality(playerElement, explosionType, explosionX, explosionY, explosionZ, detectionCode)
local explosionSyncer = inspect(playerElement)
local explosionType = explosionType
local explosionPosition = explosionX..", "..explosionY..", "..explosionZ
local explosionZoneName = getZoneName(explosionX, explosionY, explosionZ, false)
local explosionCityName = getZoneName(explosionX, explosionY, explosionZ, true)
local explosionLog =
"* Detected explosion abnormality - "..detectionCode.." *\n"..
"Explosion syncer: "..explosionSyncer.."\n"..
"Explosion type: "..explosionType.."\n"..
"Explosion position: "..explosionPosition.. " ("..explosionZoneName..", "..explosionCityName..")\n"

outputDebugString(explosionLog, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)

return true
end

local function processExplosionChecks(playerElement, explosionType, explosionX, explosionY, explosionZ)
local explosionData = explosionTypes[explosionType]
local explosionAllowed = explosionData.explosionAllowed

if (not explosionAllowed) then
return false, "Explosion type not allowed"
end

local rocketExplosion = (explosionType == 2)

if (rocketExplosion) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToExplosion = getDistanceBetweenPoints3D(playerX, playerY, playerZ, explosionX, explosionY, explosionZ)
local instantExplosion = (distanceToExplosion < rocketInstantExplosionDistanceThreshold)

if (instantExplosion) then
local explosionAllowedWeapons = explosionData.explosionAllowedWeapons
local playerWeapon = getPedWeapon(playerElement)
local allowedWeapon = explosionAllowedWeapons[playerWeapon]

if (not allowedWeapon) then
return false, "Player is not holding rocket launcher"
end

local weaponAmmo = hasPlayerProjectileAmmo(playerElement, playerWeapon)
local playerHasAmmo = (weaponAmmo > 0)

if (not playerHasAmmo) then
return false, "Player doesn't have ammo for rocket launcher"
end

decreasePlayerProjectileAmmo(playerElement, playerWeapon)

return true
end
end

local explosionAllowedProjectiles = explosionData.explosionAllowedProjectiles

if (explosionAllowedProjectiles) then

for projectileID, _ in pairs(explosionAllowedProjectiles) do
local atleastOneProjectile = decreasePlayerProjectiles(playerElement, projectileID)

if (atleastOneProjectile) then
return true
end
end

return false, "Explosion created without respective projectile"
end

local explosionAllowedVehicles = explosionData.explosionAllowedVehicles

if (explosionAllowedVehicles) then
local playerVehicle = getPedOccupiedVehicle(playerElement)

if (not playerVehicle) then
return false, "Player is not in vehicle"
end

local vehicleModel = getElementModel(playerVehicle)
local allowedVehicle = explosionAllowedVehicles[vehicleModel]

if (not allowedVehicle) then
return false, "Player is inside not allowed vehicles"
end

local vehicleDriver = getVehicleController(playerVehicle)
local playerDriver = (playerElement == vehicleDriver)

if (not playerDriver) then
return false, "Player is not vehicle driver"
end
end

local explosionMaxDistanceFromCreator = explosionData.explosionMaxDistanceFromCreator

if (explosionMaxDistanceFromCreator) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToExplosion = getDistanceBetweenPoints3D(playerX, playerY, playerZ, explosionX, explosionY, explosionZ)
local matchingExplosionDistance = (distanceToExplosion < explosionMaxDistanceFromCreator)

if (not matchingExplosionDistance) then
return false, "Explosion distance mismatch"
end
end

return true
end

local function getExplosionDetectionOverwrittenBehavior(explosionType)
local explosionData = explosionTypes[explosionType]

if (not explosionData) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local explosionBehaviour = explosionData.explosionOverwriteBehaviour

if (not explosionBehaviour) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local overwriteReport = explosionBehaviour.reportAbnormality
local overwritePunish = explosionBehaviour.punishPlayerOnDetect
local overwriteBan = explosionBehaviour.punishmentBan

return overwriteReport, overwritePunish, overwriteBan
end

function onExplosionAntiCheat(explosionX, explosionY, explosionZ, explosionType)
local serverSyncExplosion = (source == root)

if (serverSyncExplosion) then
return true
end

local approvedExplosion, detectionCode = processExplosionChecks(source, explosionType, explosionX, explosionY, explosionZ)

if (approvedExplosion) then
return true
end

local reportAbnormality, punishPlayerOnDetect, punishmentBan = getExplosionDetectionOverwrittenBehavior(explosionType)

if (reportAbnormality) then
reportExplosionAbnormality(source, explosionType, explosionX, explosionY, explosionZ, detectionCode)
end

cancelEvent()

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(source, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(source, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onExplosion", root, onExplosionAntiCheat)
</syntaxhighlight>
</section>

==Handling non-registered events==

See: [[onPlayerTriggerInvalidEvent]]

==Handling events spam==
See: [[onPlayerTriggerEventThreshold]]

User:DColeman/RU:Безопасность скриптов

2025-05-10T12:31:39Z

DColeman: Translation progress

==Информация по памяти клиента==

Начиная с самых основ:
* Вы должны понимать, что все, что вы храните на стороне клиента, включая .lua файлы, находится под риском. Любая конфиденциальная или критическая информация, которая как-либо оказывается на клиентской стороне (ПК игрока), может быть прочитана и/или изменена чит-клиентами.
* Чтобы сохранить конфиденциальную информацию и логику скрипта в секрете - используйте серверную сторону.
* Обратите внимание, что скрипты, отмеченные как общие ('''shared''') также действуют как '''клиентские''', что означает, что все вышеперечисленное также применяется и к ним. Например, объявление скрипта:

<syntaxhighlight lang="xml">
<script src="script.lua" type="shared"/> 
</syntaxhighlight>

То же самое, что и объявление:

<syntaxhighlight lang="xml">
<script src="script.lua" type="client"/> 
<script src="script.lua" type="server"/> 
</syntaxhighlight>

==Дополнительный слой защиты==

Чтобы незначительно ''усложнить жизнь*'' тем, у кого есть плохие намерения по отношению к вашему серверу, вы можете использовать аттрибут cache (и/или [https://luac.mtasa.com/ скомпилированные lua скрипты (также известные как Luac) с '''3''' уровнем дополнительной обфускации] - [https://wiki.multitheftauto.com/wiki/Lua_compilation_API API]), доступный в [https://wiki.multitheftauto.com/wiki/Meta.xml meta.xml], вместе с настройкой встроенного античита МТА с включением SD (специальными кодами обнаружения), для дополнительной информации смотрите [https://wiki.multitheftauto.com/wiki/Anti-cheat_guide гайд по античиту].

<syntaxhighlight lang="xml">
<script src="shared.lua" type="shared" cache="false"/> 
<script src="client.lua" type="client" cache="false"/> 
</syntaxhighlight>

* ''Усложнить жизнь'' '''не означает "сделать невозможным"''' получение вашего клиентского Lua кода, это означает, что '''большинство''' людей не смогут просмотреть ваши .lua файлы - тех, кто ищет логические ошибки (баги) или отсутствующие/некорректные проверки безопасности.
* Может использоваться на '''client''' и '''shared''' типах скриптов (не имеет эффекта на серверных скриптах).
* Это не удалит Lua файлы, которые были загружены ранее.

==Обнаружение и обезвреживание бэкдоров и читов==
'''Чтобы минимизировать (или исключить) урон, причиненный Lua скриптами:'''
* Всегда обновляйте ваш сервер до самой актуальной версии, вы можете [https://nightly.multitheftauto.com/ загрузить новейшие сборки сервера отсюда.] С информацией по определенным сборкам можно ознакомиться [https://buildinfo.multitheftauto.com/ здесь.]
* Всегда обновляйте ресурсы, установленные на сервере, до самой актуальной версии, вы можете [https://github.com/multitheftauto/mtasa-resources загрузить новейшие (стандартные) ресурсы из репозитория GitHub.] Они часто содержат обновления безопасности, которые влияют на устойчивость вашего сервера к атакам.
* Убедитесь, что [https://wiki.multitheftauto.com/wiki/Access%20Control%20List ACL (список контроля доступа)] правильно сконфигурирован - он поможет заблокировать ресурсам некоторые потенциально опасные функции.
* Никогда не выдавайте админ-права ресурсам (включая карты), полученным из неизвестных источников.
* Перед запуском недоверенного ресурса, изучите:
** Его [https://wiki.multitheftauto.com/wiki/Meta.xml meta.xml], на наличие возможных скрытых скриптов, которые скрываются под видом файлов с другими расширениями.
** Его исходный код, на наличие вредоносной логики.
* Не запускайте и не используйте скомпилированные ресурсы (скрипты), в легитимности которых вы не уверены.

'''Чтобы минимизировать урон, причиненный читером, зашедшим на сервер:'''
* При создании скриптов '''никогда не доверяйте данным, полученным со стороны клиента'''.
* При просмотре скриптов на наличие дыр безопасности, сверяйтесь с данными, поступающими от клиента, которому можно доверять.
* Отправлены могут быть любые данные, поэтому любые серверные скрипты, которые коммуницируют с клиентскими и получают информацию от игроков, '''должны проверять информацию на корректность''' перед дальнейшим использованием. Подделка данных чаще всего происходит с помощью [[setElementData]] и [[triggerServerEvent]].
* Вы не должны полагаться только на [https://wiki.multitheftauto.com/wiki/Serial серийный номер] игрока, когда они используются для критических действий (авто-входа/администраторских действий). '''Не гарантируется, что серийный номер игрока уникален и не подделан'''. Это причина, почему вы должны '''поместить его за''' системой аккаунтов, в качестве '''важного аутентификационного фактора'''.
* Серверная логика '''не может быть обойдена''' (если только сервер не взломан или в коде нет ошибки, но это совсем другой сценарий.) - '''используйте это в своих интересах'''. В большинстве случаев, вы можете реализовать проверки безопасности только на серверной стороне, не привлекая клиент.
* Следование аксиоме '''''“Все параметры, включая source могут быть подделаны и им нельзя доверять. Глобальной переменной client можно доверять.”''''' дает вам уверенность в том, что игрок, к которому вы обращаетесь (через переменную '''client''') '''именно тот, кто вызвал событие'''. Это защищает вас от тех ситуаций, когда читер может вызывать, например, админские события (например, кик/бан игрока), указывая реального администратора ('''второй''' аргумент '''[[triggerServerEvent]]'''), или вызывать события за других игроков (будто они вызвали их, но в реальности это делает читер) - всего лишь из-за использования некорректной переменной. Чтобы убедиться, что вы это поняли, обратимся к коду:

<syntaxhighlight lang="lua">
--[[
НИКОГДА НЕ ИСПОЛЬЗУЙТЕ ЭТОТ КОД - ОН АБСОЛЮТНО НЕВЕРНЫЙ И НЕБЕЗОПАСНЫЙ
ПРОБЛЕМА: ИСПОЛЬЗУЯ ПЕРЕМЕННУЮ 'source' В hasObjectPermissionTo ВЫ ОСТАВЛЯЕТЕ ДЫРУ ДЛЯ ЧИТЕРОВ
]]

function onServerWrongAdminEvent(playerToBan)
if (not client) then -- 'client' указывает на игрока, который вызвал событие, и должен использоваться в качестве проверки безопасности (для предотвращения подмены игрока)
return false -- если эта переменная не существует (по неизвестной причине), останавливаем выполнение кода
end

local defaultPermission = false -- по стандарту не разрешаем действие, сморите: https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo
local canAdminBanPlayer = hasObjectPermissionTo(source, "function.banPlayer", defaultPermission) -- эксплойт находится здесь...

if (not canAdminBanPlayer) then -- если у игрока нет прав
return false -- останавливаем выполнение кода
end

local validElement = isElement(playerToBan) -- проверяем, что аргумент, переданный игроком, является элементом
if (not validElement) then -- если нет...
return false -- останавливаем выполнение кода
end

local elementType = getElementType(playerToBan) -- это элемент, получаем его тип
local playerType = (elementType == "player") -- проверяем, что тип элемента - игрок

if (not playerType) then -- это не игрок
return false -- останавливаемся
end

-- banPlayer(...) -- делаем, что нужно
end
addEvent("onServerWrongAdminEvent", true)
addEventHandler("onServerWrongAdminEvent", root, onServerWrongAdminEvent)

--[[
onServerCorrectAdminEvent ПРЕКРАСНО ЗАЩИЩЕН, ТАК, КАК ДОЛЖНО БЫТЬ
ЗДЕСЬ НЕТ ПРОБЛЕМ: МЫ ИСПОЛЬЗУЕМ 'client' В hasObjectPermissionTo, ЧТО ЗАЩИЩАЕТ НАС ОТ ПОДМЕНЫ ИГРОКА, КОТОРЫЙ ВЫЗВАЛ СОБЫТИЕ
]]--

function onServerCorrectAdminEvent(playerToBan)
if (not client) then -- 'client' указывает на игрока, который вызвал событие, и должен использоваться в качестве проверки безопасности (для предотвращения подмены игрока)
return false -- если эта переменная не существует (по неизвестной причине), останавливаем выполнение кода
end

local defaultPermission = false -- по стандарту не разрешаем действие, сморите: https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo
local canAdminBanPlayer = hasObjectPermissionTo(client, "function.banPlayer", defaultPermission) -- если игрок имеет права

if (not canAdminBanPlayer) then -- если у игрока нет прав
return false -- останавливаем выполнение кода
end

local validElement = isElement(playerToBan) -- проверяем, что аргумент, переданный игроком, является элементом
if (not validElement) then -- если нет...
return false -- останавливаем выполнение кода
end

local elementType = getElementType(playerToBan) -- это элемент, получаем его тип
local playerType = (elementType == "player") -- проверяем, что тип элемента - игрок

if (not playerType) then -- это не игрок
return false -- останавливаемся
end

-- banPlayer(...) -- делаем, что нужно
end
addEvent("onServerCorrectAdminEvent", true)
addEventHandler("onServerCorrectAdminEvent", root, onServerCorrectAdminEvent)
</syntaxhighlight>

==Securing setElementData==

* You should refrain from using [[element data]] everywhere, it should be only used when really necessary. It is advised to replace it with [[triggerClientEvent]] instead.
* If you still insist on using it, it is recommended to set '''4th''' argument in [[setElementData]] to '''false''' (disabling sync for this, certain data) and use subscriber mode - [[addElementDataSubscriber]], for both security & performance reasons described in [https://wiki.multitheftauto.com/wiki/Script_security#Securing_triggerServerEvent event section.]
{{Important Note|Disabling sync however, doesn't fully protect data key. It would be still vulnerable by default, but in this case you are not leaving it in plain sight. Using [[getAllElementData]] or digging in RAM wouldn't expose it, since it won't be synced to client in first place. Therefore, it needs to be added to anti-cheat as well.}}
* All parameters including '''source''' can be faked and should not be trusted.
* Global variable '''client''' can be trusted.

----------
<section name="Server" class="server" show="true">
Example of basic element data anti-cheat.
<syntaxhighlight lang="lua">
local function reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue) -- helper function to log and revert changes
local logClient = inspect(clientElement) -- in-depth view of player which forced element data sync
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = tostring(sourceElement) -- element which received data
local logOldValue = tostring(oldValue) -- old value
local logNewValue = tostring(newValue) -- new value
local logText = -- fill our report with data
"=======================================\n"..
"Detected element data abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Data key: "..dataKey.."\n"..
"Old data value: "..logOldValue.."\n"..
"New data value: "..logNewValue.."\n"..
"======================================="

local logVisibleTo = root -- specify who will see this log in console, in this case each player connected to server
local hadData = (oldValue ~= nil) -- check if element had such data before

if (hadData) then -- if element had such data before
setElementData(sourceElement, dataKey, oldValue, true) -- revert changes, it will call onElementDataChange event, but will fail (stop) on first condition - because server (not client) forced change
else
removeElementData(sourceElement, dataKey) -- remove it completely
end

outputConsole(logText, logVisibleTo) -- print it to console

return true -- all success
end

function onElementDataChangeBasicAC(dataKey, oldValue, newValue) -- the heart of our anti-cheat, which does all the magic security measurements
if (not client) then -- check if data is coming from client
return false -- if it's not, do not go further
end

local checkSpecialThing = (dataKey == "special_thing") -- compare whether dataKey matches "special_thing"
local checkFlagWaving = (dataKey == "flag_waving") -- compare whether dataKey matches "flag_waving"

if (checkSpecialThing) then -- if it does, do our security checks
local invalidElement = (client ~= source) -- verify whether source element is different from player which changed data

if (invalidElement) then -- if it's so
reportAndRevertDataChange(client, source, dataKey, oldValue, newValue) -- revert data change, because "special_thing" can only be set for player himself
end
end

if (checkFlagWaving) then -- if it does, do our security checks
local playerVehicle = getPedOccupiedVehicle(client) -- get player's current vehicle
local invalidVehicle = (playerVehicle ~= source) -- verify whether source element is different from player's vehicle

if (invalidVehicle) then -- if it's so
reportAndRevertDataChange(client, source, dataKey, oldValue, newValue) -- revert data change, because "flag_waving" can only be set for player's own vehicle
end
end
end
addEventHandler("onElementDataChange", root, onElementDataChangeBasicAC)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
Example of advanced element data anti-cheat.
<syntaxhighlight lang="lua">
--[[
For maximum security set punishPlayerOnDetect, punishmentBan, allowOnlyProtectedKeys to true (as per default configuration)
If allowOnlyProtectedKeys is enabled, do not forget to add every client-side element data key to protectedKeys table - otherwise you will face false-positives

Anti-cheat (handleDataChange) table structure and it's options:

["keyName"] = { -- name of key which would be protected
onlyForPlayerHimself = true, -- enabling this (true) will make sure that this element data key can only be set on player who synced it (ignores onlyForOwnPlayerVeh and allowForElements), use false/nil to disable this
onlyForOwnPlayerVeh = false, -- enabling this (true) will make sure that this element data key can only be set on player's current vehicle who synced it (ignores allowForElements), use false/nil to disable this
allowForElements = { -- restrict this key for certain element type(s), set to false/nil or leave it empty to not check this (full list of element types: https://wiki.multitheftauto.com/wiki/GetElementsByType)
["player"] = true,
["ped"] = true,
["vehicle"] = true,
["object"] = true,
},
allowedDataTypes = { -- restrict this key for certain value type(s), set to false/nil or leave it empty to not check this
["string"] = true,
["number"] = true,
["table"] = true,
["boolean"] = true,
["nil"] = true,
},
allowedStringLength = {1, 32}, -- if value is a string, then it's length must be in between (min-max), set it to false/nil to not check string length - do note that allowedDataTypes must contain ["string"] = true
allowedTableLength = {1, 64}, -- if value is a table, then it's length must be in between (min-max), set it to false/nil to not check table length - do note that allowedDataTypes must contain ["table"] = true
allowedNumberRange = {1, 128}, -- if value is a number, then it must be in between (min-max), set it to false/nil to not check number range - do note that allowedDataTypes must contain ["number"] = true
}
]]

local punishPlayerOnDetect = true -- should player be punished upon detection (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Altering element data" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local allowOnlyProtectedKeys = true -- disallow (remove by using removeElementData) every element data besides those given in protectedKeys table; in case someone wanted to flood server with garbage keys, which would be kept in memory until server restart or manual remove - setElementData(source, key, nil) won't remove it; it has to be removeElementData
local debugLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugR = 255 -- debug message - red color
local debugG = 127 -- debug message - green color
local debugB = 0 -- debug message - blue color
local protectedKeys = {
["vehicleNumber"] = { -- we want vehicleNumber to be set only on vehicles, with stricte numbers in range of 1-100
allowForElements = {
["vehicle"] = true,
},
allowedDataTypes = {
["number"] = true,
},
allowedNumberRange = {1, 100},
},
["personalVehData"] = { -- we want be able to set personalVehData only on current vehicle, also it should be a string with length between 1-24
onlyForOwnPlayerVeh = true,
allowedDataTypes = {
["string"] = true,
},
allowedStringLength = {1, 24},
},
-- perform security checks on keys stored in this table, in a convenient way
}

local function reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- helper function to log and revert changes
local logClient = inspect(clientElement) -- in-depth view of player which forced element data sync
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = inspect(sourceElement) -- in-depth view of element which received data
local logOldValue = inspect(oldValue) -- in-depth view of old value
local logNewValue = inspect(newValue) -- in-depth view of new value
local logText = -- fill our report with data
"*\n"..
"Detected element data abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Data key: "..dataKey.."\n"..
"Old data value: "..logOldValue.."\n"..
"New data value: "..logNewValue.."\n"..
"Fail reason: "..failReason.."\n"..
"*"

outputDebugString(logText, debugLevel, debugR, debugG, debugB) -- print it to debug

if (forceRemove) then -- we don't want this element data key to exist at all
removeElementData(sourceElement, dataKey) -- remove it

return true -- return success and stop here, we don't need further checks
end

setElementData(sourceElement, dataKey, oldValue, true) -- revert changes, it will call onElementDataChange event, but will fail (stop) on first condition - because server (not client) forced change

return true -- return success
end

local function handleDataChange(clientElement, sourceElement, dataKey, oldValue, newValue) -- the heart of our anti-cheat, which does all the magic security measurements, returns true if there was no altering from client (based on data from protectedKeys), false otherwise
local protectedKey = protectedKeys[dataKey] -- look up whether key changed is stored in protectedKeys table

if (not protectedKey) then -- if it's not

if (allowOnlyProtectedKeys) then -- if we don't want garbage keys
local failReason = "Key isn't present in protectedKeys" -- reason shown in report
local forceRemove = true -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end

return true -- this key isn't protected, let it through
end

local onlyForPlayerHimself = protectedKey.onlyForPlayerHimself -- if key has "self-set" lock
local onlyForOwnPlayerVeh = protectedKey.onlyForOwnPlayerVeh -- if key has "self-vehicle" lock
local allowForElements = protectedKey.allowForElements -- if key has element type check
local allowedDataTypes = protectedKey.allowedDataTypes -- if key has allowed data type check

if (onlyForPlayerHimself) then -- if "self-set" lock is active
local matchingElement = (clientElement == sourceElement) -- verify whether player who set data is equal to element which received data

if (not matchingElement) then -- if it's not matching
local failReason = "Can only set on player himself" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (onlyForOwnPlayerVeh) then -- if "self-vehicle" lock is active
local playerVehicle = getPedOccupiedVehicle(clientElement) -- get current vehicle of player which set data
local matchingVehicle = (playerVehicle == sourceElement) -- check whether it matches the one which received data

if (not matchingVehicle) then -- if it doesn't match
local failReason = "Can only set on player's own vehicle" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowForElements) then -- check if it's one of them
local elementType = getElementType(sourceElement) -- get type of element whose data changed
local matchingElementType = allowForElements[elementType] -- verify whether it's allowed

if (not matchingElementType) then -- this isn't matching
local failReason = "Invalid element type" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedDataTypes) then -- if there's allowed data types
local valueType = type(newValue) -- get data type of value
local matchingType = allowedDataTypes[valueType] -- check if it's one of allowed

if (not matchingType) then -- if it's not then
local failReason = "Invalid data type" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end

local allowedStringLength = protectedKey.allowedStringLength -- if key has specified string length check
local dataString = (valueType == "string") -- make sure it's a string

if (allowedStringLength and dataString) then -- if we should check string length
local minLength = allowedStringLength[1] -- retrieve min length
local maxLength = allowedStringLength[2] -- retrieve max length
local stringLength = utf8.len(newValue) -- get length of data string
local matchingLength = (stringLength >= minLength) and (stringLength <= maxLength) -- compare whether value fits in between

if (not matchingLength) then -- if it doesn't
local failReason = "Invalid string length (must be between "..minLength.."-"..maxLength..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedTableLength = protectedKey.allowedTableLength -- if key has table length check
local dataTable = (valueType == "table") -- make sure it's a table

if (allowedTableLength and dataTable) then -- if we should check table length
local minLength = allowedTableLength[1] -- retrieve min length
local maxLength = allowedTableLength[2] -- retrieve max length
local minLengthAchieved = false -- variable which checks 'does minimum length was achieved'
local maxLengthExceeded = false -- variable which checks 'does length has exceeds more than allowed maximum'
local tableLength = 0 -- store initial table length

for _, _ in pairs(newValue) do -- loop through whole table
tableLength = (tableLength + 1) -- add + 1 on each table entry
minLengthAchieved = (tableLength >= minLength) -- is length bigger or at very minimum we require
maxLengthExceeded = (tableLength > maxLength) -- does table exceeded more than max length?

if (maxLengthExceeded) then -- it is bigger than it should be
break -- break the loop (due of condition above being worthy, it makes no point to count further and waste CPU, on a table which potentially could have huge amount of entries)
end
end

local matchingLength = (minLengthAchieved and not maxLengthExceeded) -- check if min length has been achieved, and make sure that it doesn't go beyond max length

if (not matchingLength) then -- this table doesn't match requirements
local failReason = "Invalid table length (must be between "..minLength.."-"..maxLength..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedNumberRange = protectedKey.allowedNumberRange -- if key has allowed number range check
local dataNumber = (valueType == "number") -- make sure it's a number

if (allowedNumberRange and dataNumber) then -- if we should check number range
local minRange = allowedNumberRange[1] -- retrieve min number range
local maxRange = allowedNumberRange[2] -- retrieve max number range
local matchingRange = (newValue >= minRange) and (newValue <= maxRange) -- compare whether value fits in between

if (not matchingRange) then -- if it doesn't
local failReason = "Invalid number range (must be between "..minRange.."-"..maxRange..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end
end

return true -- security checks passed, we are all clear with this data key
end

function onElementDataChangeAdvancedAC(dataKey, oldValue, newValue) -- this event makes use of handleDataChange, the code was split for better readability
if (not client) then -- check if data is coming from client
return false -- if it's not, do not continue
end

local approvedChange = handleDataChange(client, source, dataKey, oldValue, newValue) -- run our security checks

if (approvedChange) then -- it's all cool and good
return false -- we don't need further action
end

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(client, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(client, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onElementDataChange", root, onElementDataChangeAdvancedAC)
</syntaxhighlight>
</section>

==Securing triggerServerEvent==

* All parameters including '''source''' can be faked and should not be trusted.
* Global variable '''client''' can be trusted.
* '''Admin''' styled '''events''' should be verifying player (client) '''ACL rights''', either by [https://wiki.multitheftauto.com/wiki/IsObjectInACLGroup isObjectInACLGroup] or [https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo hasObjectPermissionTo].
* Do '''not''' use the same name for your custom event as MTA native server events (which aren't remotely triggerable by default), e.g: '''onPlayerLogin'''; doing so would open door for cheaters manipulations.
* Be aware to which players event is sent via [[triggerClientEvent]]. For both security & performance reasons, admin like events should be received by admins only (to prevent confidential data being accessed), in the same time you shouldn't send each event to everyone on server (e.g: login success event which hides login panel for certain player). [[triggerClientEvent]] allows you to specify the event receiver as first (optional) argument. It defaults to [[root]], meaning if you don't specify it, it will be sent to everyone connected to server - even those who are still downloading server cache (which results in ''Server triggered clientside event eventName, but event is not added clientside.''). You can either pass player element or table with receivers:
<syntaxhighlight lang="lua">
local playersToReceiveEvent = {player1, player2, player3} -- each playerX is player element

triggerClientEvent(playersToReceiveEvent, ...) -- do not forget to fill the latter part of arguments
</syntaxhighlight>

----------
<section name="Server" class="server" show="true">
Example of anti-cheat function designed for events, used for data validation for both normal, and admin events which are called from client-side.
<syntaxhighlight lang="lua">
--[[
For maximum security set punishPlayerOnDetect, punishmentBan to true (as per default configuration)

Anti-cheat (processServerEventData) table structure and it's options:

checkACLGroup = { -- check whether player who called event belongs to at least one group below, set to false/nil to not check this
"Admin",
},
checkPermissions = { -- check whether player who called event has permission to at least one thing below, set to false/nil to not check this
"function.kickPlayer",
},
checkEventData = {
{
debugData = "source", -- optional details for report shown in debug message
eventData = source, -- data we want to verify
equalTo = client, -- compare whether eventData == equalTo
allowedElements = { -- restrict eventData to be certain element type(s), set to false/nil or leave it empty to not check this (full list of element types: https://wiki.multitheftauto.com/wiki/GetElementsByType)
["player"] = true,
["ped"] = true,
["vehicle"] = true,
["object"] = true,
},
allowedDataTypes = { -- restrict eventData to be certain value type(s), set to false/nil or leave it empty to not check this
["string"] = true,
["number"] = true,
["table"] = true,
["boolean"] = true,
["nil"] = true,
},
allowedStringLength = {1, 32}, -- if eventData is a string, then it's length must be in between (min-max), set it to false/nil to not check string length - do note that allowedDataTypes must contain ["string"] = true
allowedTableLength = {1, 64}, -- if eventData is a table, then it's length must be in between (min-max), set it to false/nil to not check table length - do note that allowedDataTypes must contain ["table"] = true
allowedNumberRange = {1, 128}, -- if eventData is a number, then it must be in between (min-max), set it to false/nil to not check number range - do note that allowedDataTypes must contain ["number"] = true
},
},
]]

local punishPlayerOnDetect = true -- should player be punished upon detection (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Altering server event data" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugR = 255 -- debug message - red color
local debugG = 127 -- debug message - green color
local debugB = 0 -- debug message - blue color

function processServerEventData(clientElement, sourceElement, serverEvent, securityChecks) -- the heart of our anti-cheat, which does all the magic security measurements, returns true if there was no altering from client (based on data from securityChecks), false otherwise
if (not securityChecks) then -- if we haven't passed any security checks
return true -- nothing to check, let code go further
end

if (not clientElement) then -- if client variable isn't available for some reason (although it should never happen)
local failReason = "Client variable not present" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local checkACLGroup = securityChecks.checkACLGroup -- if there's any ACL groups to check
local checkPermissions = securityChecks.checkPermissions -- if there's any permissions to check
local checkEventData = securityChecks.checkEventData -- if there's any data checks

if (checkACLGroup) then -- let's check player ACL groups
local playerAccount = getPlayerAccount(clientElement) -- get current account of player
local guestAccount = isGuestAccount(playerAccount) -- if account is guest (meaning player is not logged in)

if (guestAccount) then -- it's the case
local failReason = "Can't retrieve player login - guest account" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local accountName = getAccountName(playerAccount) -- get name of player's current account
local aclString = "user."..accountName -- format it for further use in isObjectInACLGroup function

for groupID = 1, #checkACLGroup do -- iterate over table of given groups
local groupName = checkACLGroup[groupID] -- get each group name
local aclGroup = aclGetGroup(groupName) -- check if such group exists

if (not aclGroup) then -- it doesn't
local failReason = "ACL group '"..groupName.."' is missing" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local playerInACLGroup = isObjectInACLGroup(aclString, aclGroup) -- check if player belong to the group

if (playerInACLGroup) then -- yep, it's the case
return true -- so it's a success
end
end

local failReason = "Player doesn't belong to any given ACL group" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

if (checkPermissions) then -- check if player has at least one desired permission
local allowedByDefault = false -- does he have access by default

for permissionID = 1, #checkPermissions do -- iterate over all permissions
local permissionName = checkPermissions[permissionID] -- get permission name
local hasPermission = hasObjectPermissionTo(clientElement, permissionName, allowedByDefault) -- check whether player is allowed to perform certain action

if (hasPermission) then -- if player has access
return true -- one is available (and enough), server won't bother to check others (as return keywords also breaks loop)
end
end

local failReason = "Not enough permissions" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

if (checkEventData) then -- if there is some data to verify

for dataID = 1, #checkEventData do -- iterate over each of data
local dataToCheck = checkEventData[dataID] -- get each data set
local eventData = dataToCheck.eventData -- this is the one we'll be verifying
local equalTo = dataToCheck.equalTo -- we want to compare whether eventData == equalTo
local allowedElements = dataToCheck.allowedElements -- check whether is element, and whether belongs to certain element types
local allowedDataTypes = dataToCheck.allowedDataTypes -- do we restrict data to be certain type?
local debugData = dataToCheck.debugData -- additional helper data
local debugText = debugData and " ("..debugData..")" or "" -- if it's present, format it nicely

if (equalTo) then -- equal check exists
local matchingData = (eventData == equalTo) -- compare whether those two values are equal

if (not matchingData) then -- they aren't
local failReason = "Data isn't equal @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedElements) then -- we do check whether is an element, and belongs to at least one given in the list
local validElement = isElement(eventData) -- check if it's actual element

if (not validElement) then -- it's not
local failReason = "Data isn't element @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local elementType = getElementType(eventData) -- it's element, so we want to know it's type
local matchingElementType = allowedElements[elementType] -- verify whether it's allowed

if (not matchingElementType) then -- it's not allowed
local failReason = "Invalid element type @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedDataTypes) then -- let's check allowed data types
local dataType = type(eventData) -- get data type
local matchingType = allowedDataTypes[dataType] -- verify whether it's allowed

if (not matchingType) then -- it isn't
local failReason = "Invalid data type @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local allowedStringLength = dataToCheck.allowedStringLength -- if data has string length check
local dataString = (dataType == "string") -- make sure it's a string

if (allowedStringLength and dataString) then -- if we should check string length
local minLength = allowedStringLength[1] -- retrieve min length
local maxLength = allowedStringLength[2] -- retrieve max length
local stringLength = utf8.len(eventData) -- get length of data string
local matchingLength = (stringLength >= minLength) and (stringLength <= maxLength) -- compare whether value fits in between

if (not matchingLength) then -- if it doesn't
local failReason = "Invalid string length (must be between "..minLength.."-"..maxLength..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedTableLength = dataToCheck.allowedTableLength -- if data has table length check
local dataTable = (dataType == "table") -- make sure it's a table

if (allowedTableLength and dataTable) then -- if we should check table length
local minLength = allowedTableLength[1] -- retrieve min length
local maxLength = allowedTableLength[2] -- retrieve max length
local minLengthAchieved = false -- variable which checks 'does minimum length was achieved'
local maxLengthExceeded = false -- variable which checks 'does length has exceeds more than allowed maximum'
local tableLength = 0 -- store initial table length

for _, _ in pairs(eventData) do -- loop through whole table
tableLength = (tableLength + 1) -- add + 1 on each table entry
minLengthAchieved = (tableLength >= minLength) -- is length bigger or at very minimum we require
maxLengthExceeded = (tableLength > maxLength) -- does table exceeded more than max length?

if (maxLengthExceeded) then -- it is bigger than it should be
break -- break the loop (due of condition above being worthy, it makes no point to count further and waste CPU, on a table which potentially could have huge amount of entries)
end
end

local matchingLength = (minLengthAchieved and not maxLengthExceeded) -- check if min length has been achieved, and make sure that it doesn't go beyond max length

if (not matchingLength) then -- this table doesn't match requirements
local failReason = "Invalid table length (must be between "..minLength.."-"..maxLength..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedNumberRange = dataToCheck.allowedNumberRange -- if data has number range check
local dataNumber = (dataType == "number") -- make sure it's a number

if (allowedNumberRange and dataNumber) then -- if we should check number range
local minRange = allowedNumberRange[1] -- retrieve min number range
local maxRange = allowedNumberRange[2] -- retrieve max number range
local matchingRange = (eventData >= minRange) and (eventData <= maxRange) -- compare whether value fits in between

if (not matchingRange) then -- if it doesn't
local failReason = "Invalid number range (must be between "..minRange.."-"..maxRange..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end
end
end
end

return true -- security checks passed, we are all clear with this event call
end

function reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- helper function to log and handle accidents
local logClient = inspect(clientElement) -- in-depth view player which called event
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = inspect(sourceElement) -- in-depth view of source element
local logText = -- fill our report with data
"*\n"..
"Detected event abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Event: "..serverEvent.."\n"..
"Reason: "..failReason.."\n"..
"*"

outputDebugString(logText, debugLevel, debugR, debugG, debugB) -- print it to debug

if (not punishPlayerOnDetect or skipPunishment) then -- we don't want to punish player for some reason
return true -- stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(clientElement, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(clientElement, punishedBy, punishmentReason) -- simply kick player out of server
end

return true -- all done, report success
end

function onServerEvent(clientData)
--[[
Assume this server event (function) is called in such way:

local dataToPass = 10

triggerServerEvent("onServerEvent", localPlayer, dataToPass)
]]

local shouldProcessServerCode = processServerEventData(
client, -- client element - responsible for calling event
source, -- source element - passed in triggerServerEvent (as 2nd argument)
eventName, -- name of event - in this case 'onServerEvent'
{
checkEventData = { -- we want to verify everything what comes from client
{
eventData = source, -- first to check, source variable
equalTo = client, -- we want to check whether it matches player who called event
debugData = "source", -- helper details which would be shown in report
},
{
eventData = clientData, -- let's check the data which client sent to us
allowedDataTypes = {
["number"] = true, -- we want it to be only number
},
allowedNumberRange = {1, 100}, -- in range of 1 to 100
debugData = "clientData", -- if something goes wrong, let server know where (it will appear in debug report)
},
},
}
)

if (not shouldProcessServerCode) then -- something isn't right, no green light for processing code behind this scope
return false -- stop code execution
end

-- do code as usual
end
addEvent("onServerEvent", true)
addEventHandler("onServerEvent", root, onServerEvent)

function onServerAdminEvent(playerToBan)
--[[
Assume this server admin event (function) is called in such way:

local playerToBan = getPlayerFromName("playerToBan")

triggerServerEvent("onServerAdminEvent", localPlayer, playerToBan)
]]

local shouldProcessServerCode = processServerEventData(
client, -- client element - responsible for calling event
source, -- source element - passed in triggerServerEvent (as 2nd argument)
eventName, -- name of event - in this case 'onServerAdminEvent'
{
checkACLGroup = { -- we need to check whether player who called event belongs to ACL groups
"Admin", -- in this case admin group
},
checkEventData = { -- we want to verify everything what comes from client
{
eventData = source, -- first to check, source variable
equalTo = client, -- we want to check whether it matches player who called event
debugData = "source", -- helper details which would be shown in report
},
{
eventData = playerToBan, -- let's check the data which client sent to us
allowedDataTypes = {
["player"] = true, -- we want it to be player
},
debugData = "playerToBan", -- if something goes wrong, let server know where (it will appear in debug report)
},
},
}
)

if (not shouldProcessServerCode) then -- something isn't right, no green light for processing code behind this scope
return false -- stop code execution
end

-- do code as usual
end
addEvent("onServerAdminEvent", true)
addEventHandler("onServerAdminEvent", root, onServerAdminEvent)
</syntaxhighlight>
</section>

==Securing server-only events==
* It is very important to '''disable remote triggering''' ability in [https://wiki.multitheftauto.com/wiki/AddEvent addEvent], to prevent calling server-side only events from client-side.
* '''Admin''' styled '''events''' should be verifying player '''ACL rights''', either by [https://wiki.multitheftauto.com/wiki/IsObjectInACLGroup isObjectInACLGroup] or [https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo hasObjectPermissionTo].

----------
<section name="Server" class="server" show="true">
This example shows how you should make event server-side only.
<syntaxhighlight lang="lua">
function onServerSideOnlyEvent()
-- do some server-side stuff
end
addEvent("onServerSideOnlyEvent", false) -- set second argument (allowRemoteTriger) to false, so it can't be called from client
addEventHandler("onServerSideOnlyEvent", root, onServerSideOnlyEvent) -- associate our event with function onServerSideOnlyEvent
</syntaxhighlight>
</section>

==Securing projectiles & explosions==
This section (and '''code''' is '''work in progress''') - '''use at your own risk'''.

----------
<section name="Server" class="server" show="false">
Projectile ammo tracker:
<syntaxhighlight lang="lua">
local playerProjectileAmmo = {} -- store player-held weapons ammo here
local playerWeaponsToTrack = { -- keep track of ammo for certain player-held weapon types, basically those which create projectile; [weaponID] = weaponSlot
[16] = 8, -- grenade
[17] = 8, -- teargas
[18] = 8, -- molotov
[35] = 7, -- rocket launcher
[36] = 7, -- rocket launcher (heat-seeking)
[39] = 8, -- satchel charge
}

local function updateProjectileAmmoForPlayer(playerElement)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

for weaponID, weaponSlot in pairs(playerWeaponsToTrack) do
local weaponInSlot = getPedWeapon(playerElement, weaponSlot)
local weaponTotalAmmo = getPedTotalAmmo(playerElement, weaponSlot)
local weaponHasAmmo = (weaponTotalAmmo > 0)
local weaponMatching = (weaponInSlot == weaponID)
local updateWeaponAmmo = (weaponMatching and weaponHasAmmo)

if (updateWeaponAmmo) then
local storedProjectileAmmo = playerProjectileAmmo[playerElement]
local newWeaponAmmo = (updateWeaponAmmo and weaponTotalAmmo or nil)

if (not storedProjectileAmmo) then
playerProjectileAmmo[playerElement] = {}
storedProjectileAmmo = playerProjectileAmmo[playerElement]
end

storedProjectileAmmo[weaponID] = newWeaponAmmo
end
end

return true
end

function hasPlayerProjectileAmmo(playerElement, projectileWeapon)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

local projectileData = playerProjectileAmmo[playerElement]
local projectileAmmo = (projectileData and projectileData[projectileWeapon])

return projectileAmmo
end

function decreasePlayerProjectileAmmo(playerElement, projectileWeapon)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

local playerProjectileData = playerProjectileAmmo[playerElement]

if (not playerProjectileData) then
return false
end

local projectileWeaponAmmo = playerProjectileData[projectileWeapon]
local tempProjectileAmmo = (projectileWeaponAmmo - 1)
local newProjectileAmmo = (tempProjectileAmmo > 0 and tempProjectileAmmo or nil)

playerProjectileData[projectileWeapon] = newProjectileAmmo

return true
end

function onPlayerWeaponSwitchAntiCheat(previousWeaponID, currentWeaponID)
setTimer(updateProjectileAmmoForPlayer, 50, 1, source)
end
addEventHandler("onPlayerWeaponSwitch", root, onPlayerWeaponSwitchAntiCheat)

function onResourceStartAntiCheat()
local playersTable = getElementsByType("player")

for playerID = 1, #playersTable do
local playerElement = playersTable[playerID]

updateProjectileAmmoForPlayer(playerElement)
end
end
addEventHandler("onResourceStart", resourceRoot, onResourceStartAntiCheat)

function onPlayerWastedQuitAntiCheat()
playerProjectileAmmo[source] = nil
end
addEventHandler("onPlayerWasted", root, onPlayerWastedQuitAntiCheat)
addEventHandler("onPlayerQuit", root, onPlayerWastedQuitAntiCheat)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
Projectile handler:
<syntaxhighlight lang="lua">
local playerCreatedProjectiles = {} -- store count of legitimately created player projectiles; [playerElement] = {[projectileType] = activeProjectiles}
local projectileTypes = {
[16] = { -- Grenade
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[16] = true, -- grenade
},
},
[17] = { -- Teargas
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[17] = true, -- teargas
},
},
[18] = { -- Molotov
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[18] = true, -- molotov
},
},
[19] = { -- Rocket
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileMaxVelocity = 2,
projectileAllowedWeapons = {
[35] = true, -- rocket launcher
},
projectileAllowedVehicles = {
[425] = true, -- hunter
[520] = true, -- hydra
},
},
[20] = { -- Rocket (heat-seeking)
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileMaxVelocity = 2,
projectileAllowedWeapons = {
[36] = true, -- rocket launcher (heat-seeking)
},
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
[21] = { -- Airbomb
projectileAllowed = true,
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
[39] = { -- Satchel charge
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[39] = true, -- satchel charge
},
},
[58] = { -- Hydra flare
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
}

local reportAbnormality = true -- whether to report about abnormality in debug script - by default
local punishPlayerOnDetect = false -- should player be punished upon detection; true - yes, or false to not do anything (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Projectile/explosion anti-cheat" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugMsgLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugMsgR = 255 -- debug message - red color
local debugMsgG = 127 -- debug message - green color
local debugMsgB = 0 -- debug message - blue color

local function reportProjectileAbnormality(playerElement, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ, detectionCode)
local projectileSyncer = inspect(playerElement)
local projectilePosition = projectileX..", "..projectileY..", "..projectileZ
local projectileZoneName = getZoneName(projectileX, projectileY, projectileZ, false)
local projectileCityName = getZoneName(projectileX, projectileY, projectileZ, true)
local projectileLog =
"* Detected projectile abnormality - "..detectionCode.." *\n"..
"Projectile syncer: "..projectileSyncer.."\n"..
"Projectile type: "..projectileType.."\n"..
"Projectile position: "..projectilePosition.. " ("..projectileZoneName..", "..projectileCityName..")\n"

outputDebugString(projectileLog, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)

return true
end

local function processProjectileChecks(playerElement, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)
local projectileData = projectileTypes[projectileType]
local projectileAllowed = projectileData.projectileAllowed

if (not projectileAllowed) then
return false, "Projectile not allowed"
end

local projectileAllowedWeapons = projectileData.projectileAllowedWeapons

if (projectileAllowedWeapons) then
local playerWeapon = getPedWeapon(playerElement)
local allowedWeapon = projectileAllowedWeapons[playerWeapon]

if (not allowedWeapon) then
return false, "Player is not holding correct weapon"
end

local weaponAmmo = hasPlayerProjectileAmmo(playerElement, playerWeapon)
local playerHasAmmo = (weaponAmmo > 0)

if (not playerHasAmmo) then
return false, "Player doesn't have ammo for weapon"
end

decreasePlayerProjectileAmmo(playerElement, playerWeapon)
end

local playerVehicle = getPedOccupiedVehicle(playerElement)

if (playerVehicle) then
local projectileAllowedVehicles = projectileData.projectileAllowedVehicles

if (projectileAllowedVehicles) then
local vehicleModel = getElementModel(playerVehicle)
local allowedVehicle = projectileAllowedVehicles[vehicleModel]

if (not allowedVehicle) then
return false, "Player is not inside allowed vehicles"
end

local vehicleDriver = getVehicleController(playerVehicle)
local playerDriver = (playerElement == vehicleDriver)

if (not playerDriver) then
return false, "Player is not vehicle driver"
end

return true
end

return false, "Player in vehicle"
end

local projectileMaxDistanceFromCreator = projectileData.projectileMaxDistanceFromCreator

if (projectileMaxDistanceFromCreator) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToProjectile = getDistanceBetweenPoints3D(playerX, playerY, playerZ, projectileX, projectileY, projectileZ)
local matchingProjectileDistance = (distanceToProjectile <= projectileMaxDistanceFromCreator)

if (not matchingProjectileDistance) then
return false, "Projectile distance mismatch"
end
end

local projectileMaxVelocity = projectileData.projectileMaxVelocity

if (projectileMaxVelocity) then
local projectileVelocity = (projectileVX ^ 2 + projectileVY ^ 2 + projectileVZ ^ 2)
local projectileSpeed = math.sqrt(projectileVelocity)
local matchingProjectileVelocity = (projectileSpeed <= projectileMaxVelocity)

if (not matchingProjectileVelocity) then
return false, "Projectile velocity mismatch"
end
end

return true
end

local function trackPlayerProjectile(playerElement, projectileID)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerProjectiles = playerCreatedProjectiles[playerElement]

if (not playerProjectiles) then
playerCreatedProjectiles[playerElement] = {}
playerProjectiles = playerCreatedProjectiles[playerElement]
end

local projectilesByType = playerProjectiles[projectileID] or 0
local newProjectilesCount = (projectilesByType + 1)

playerProjectiles[projectileID] = newProjectilesCount

return true
end

local function getProjectileDetectionOverwrittenBehavior(projectileType)
local projectileData = projectileTypes[projectileType]

if (not projectileData) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local projectileBehaviour = projectileData.projectileOverwriteBehaviour

if (not projectileBehaviour) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local overwriteReport = projectileBehaviour.reportAbnormality
local overwritePunish = projectileBehaviour.punishPlayerOnDetect
local overwriteBan = projectileBehaviour.punishmentBan

return overwriteReport, overwritePunish, overwriteBan
end

function decreasePlayerProjectiles(playerElement, projectileID)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerProjectiles = playerCreatedProjectiles[playerElement]

if (not playerProjectiles) then
return false, true
end

local projectilesByType = playerProjectiles[projectileID]

if (not projectilesByType) then
return false, true
end

local tempProjectilesCount = (projectilesByType - 1)
local newProjectilesCount = (tempProjectilesCount > 0 and tempProjectilesCount or nil)

playerProjectiles[projectileID] = newProjectilesCount

return true
end

function onPlayerProjectileCreationAntiCheat(projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)
local approvedProjectile, detectionCode = processProjectileChecks(source, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)

if (approvedProjectile) then
trackPlayerProjectile(source, projectileType)

return true
end

local reportAbnormality, punishPlayerOnDetect, punishmentBan = getProjectileDetectionOverwrittenBehavior(projectileType)

if (reportAbnormality) then
reportProjectileAbnormality(source, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ, detectionCode)
end

cancelEvent()

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(source, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(source, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onPlayerProjectileCreation", root, onPlayerProjectileCreationAntiCheat)

function onPlayerQuitAntiCheat()
playerCreatedProjectiles[source] = nil
end
addEventHandler("onPlayerQuit", root, onPlayerQuitAntiCheat)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
Explosions handler:
<syntaxhighlight lang="lua">
local rocketInstantExplosionDistanceThreshold = 1.55 -- distance below which only explosion will be created (and not rocket projectile, hence not calling onPlayerProjectileCreation); do not change it
local explosionTypes = { -- more specific info on explosion, and whether it is allowed
[0] = { -- Grenade
explosionAllowed = true,
explosionAllowedProjectiles = {
[16] = true, -- grenade
},
},
[1] = { -- Molotov
explosionAllowed = true,
explosionAllowedProjectiles = {
[18] = true, -- molotov
},
},
[2] = { -- Rocket
explosionAllowed = true,
explosionAllowedWeapons = {
[35] = true, -- rocket launcher
[36] = true, -- rocket launcher (heat-seeking)
},
explosionAllowedProjectiles = {
[19] = true, -- rocket
[20] = true, -- rocket (heat-seeking)
},
},
[3] = { -- Rocket weak
explosionAllowed = true,
explosionAllowedProjectiles = {
[19] = true, -- rocket
[20] = true, -- rocket (heat-seeking)
},
},
[4] = { -- Car
explosionAllowed = true,
},
[5] = { -- Car quick
explosionAllowed = true,
},
[6] = { -- Boat
explosionAllowed = true,
},
[7] = { -- Heli
explosionAllowed = true,
},
[8] = { -- Mine
explosionAllowed = true,
},
[9] = { -- Object
explosionAllowed = true,
},
[10] = { -- Tank grenade
explosionAllowed = true,
explosionMaxDistanceFromCreator = 80,
explosionAllowedVehicles = {
[432] = true,
}
},
[11] = { -- Small
explosionAllowed = true,
},
[12] = { -- Tiny
explosionAllowed = true,
},
}

local reportAbnormality = true -- whether to report about abnormality in debug script - by default
local punishPlayerOnDetect = false -- should player be punished upon detection; true - yes, or false to not do anything (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Projectile/explosion anti-cheat" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugMsgLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugMsgR = 255 -- debug message - red color
local debugMsgG = 127 -- debug message - green color
local debugMsgB = 0 -- debug message - blue color

local function reportExplosionAbnormality(playerElement, explosionType, explosionX, explosionY, explosionZ, detectionCode)
local explosionSyncer = inspect(playerElement)
local explosionType = explosionType
local explosionPosition = explosionX..", "..explosionY..", "..explosionZ
local explosionZoneName = getZoneName(explosionX, explosionY, explosionZ, false)
local explosionCityName = getZoneName(explosionX, explosionY, explosionZ, true)
local explosionLog =
"* Detected explosion abnormality - "..detectionCode.." *\n"..
"Explosion syncer: "..explosionSyncer.."\n"..
"Explosion type: "..explosionType.."\n"..
"Explosion position: "..explosionPosition.. " ("..explosionZoneName..", "..explosionCityName..")\n"

outputDebugString(explosionLog, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)

return true
end

local function processExplosionChecks(playerElement, explosionType, explosionX, explosionY, explosionZ)
local explosionData = explosionTypes[explosionType]
local explosionAllowed = explosionData.explosionAllowed

if (not explosionAllowed) then
return false, "Explosion type not allowed"
end

local rocketExplosion = (explosionType == 2)

if (rocketExplosion) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToExplosion = getDistanceBetweenPoints3D(playerX, playerY, playerZ, explosionX, explosionY, explosionZ)
local instantExplosion = (distanceToExplosion < rocketInstantExplosionDistanceThreshold)

if (instantExplosion) then
local explosionAllowedWeapons = explosionData.explosionAllowedWeapons
local playerWeapon = getPedWeapon(playerElement)
local allowedWeapon = explosionAllowedWeapons[playerWeapon]

if (not allowedWeapon) then
return false, "Player is not holding rocket launcher"
end

local weaponAmmo = hasPlayerProjectileAmmo(playerElement, playerWeapon)
local playerHasAmmo = (weaponAmmo > 0)

if (not playerHasAmmo) then
return false, "Player doesn't have ammo for rocket launcher"
end

decreasePlayerProjectileAmmo(playerElement, playerWeapon)

return true
end
end

local explosionAllowedProjectiles = explosionData.explosionAllowedProjectiles

if (explosionAllowedProjectiles) then

for projectileID, _ in pairs(explosionAllowedProjectiles) do
local atleastOneProjectile = decreasePlayerProjectiles(playerElement, projectileID)

if (atleastOneProjectile) then
return true
end
end

return false, "Explosion created without respective projectile"
end

local explosionAllowedVehicles = explosionData.explosionAllowedVehicles

if (explosionAllowedVehicles) then
local playerVehicle = getPedOccupiedVehicle(playerElement)

if (not playerVehicle) then
return false, "Player is not in vehicle"
end

local vehicleModel = getElementModel(playerVehicle)
local allowedVehicle = explosionAllowedVehicles[vehicleModel]

if (not allowedVehicle) then
return false, "Player is inside not allowed vehicles"
end

local vehicleDriver = getVehicleController(playerVehicle)
local playerDriver = (playerElement == vehicleDriver)

if (not playerDriver) then
return false, "Player is not vehicle driver"
end
end

local explosionMaxDistanceFromCreator = explosionData.explosionMaxDistanceFromCreator

if (explosionMaxDistanceFromCreator) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToExplosion = getDistanceBetweenPoints3D(playerX, playerY, playerZ, explosionX, explosionY, explosionZ)
local matchingExplosionDistance = (distanceToExplosion < explosionMaxDistanceFromCreator)

if (not matchingExplosionDistance) then
return false, "Explosion distance mismatch"
end
end

return true
end

local function getExplosionDetectionOverwrittenBehavior(explosionType)
local explosionData = explosionTypes[explosionType]

if (not explosionData) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local explosionBehaviour = explosionData.explosionOverwriteBehaviour

if (not explosionBehaviour) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local overwriteReport = explosionBehaviour.reportAbnormality
local overwritePunish = explosionBehaviour.punishPlayerOnDetect
local overwriteBan = explosionBehaviour.punishmentBan

return overwriteReport, overwritePunish, overwriteBan
end

function onExplosionAntiCheat(explosionX, explosionY, explosionZ, explosionType)
local serverSyncExplosion = (source == root)

if (serverSyncExplosion) then
return true
end

local approvedExplosion, detectionCode = processExplosionChecks(source, explosionType, explosionX, explosionY, explosionZ)

if (approvedExplosion) then
return true
end

local reportAbnormality, punishPlayerOnDetect, punishmentBan = getExplosionDetectionOverwrittenBehavior(explosionType)

if (reportAbnormality) then
reportExplosionAbnormality(source, explosionType, explosionX, explosionY, explosionZ, detectionCode)
end

cancelEvent()

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(source, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(source, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onExplosion", root, onExplosionAntiCheat)
</syntaxhighlight>
</section>

==Handling non-registered events==

See: [[onPlayerTriggerInvalidEvent]]

==Handling events spam==
See: [[onPlayerTriggerEventThreshold]]

User:DColeman/RU:Безопасность скриптов

2025-05-10T11:53:10Z

DColeman: /* Additional protection layer */ translation progress

==Информация по памяти клиента==

Начиная с самых основ:
* Вы должны понимать, что все, что вы храните на стороне клиента, включая .lua файлы, находится под риском. Любая конфиденциальная или критическая информация, которая как-либо оказывается на клиентской стороне (ПК игрока), может быть прочитана и/или изменена чит-клиентами.
* Чтобы сохранить конфиденциальную информацию и логику скрипта в секрете - используйте серверную сторону.
* Обратите внимание, что скрипты, отмеченные как общие ('''shared''') также действуют как '''клиентские''', что означает, что все вышеперечисленное также применяется и к ним. Например, объявление скрипта:

<syntaxhighlight lang="xml">
<script src="script.lua" type="shared"/> 
</syntaxhighlight>

То же самое, что и объявление:

<syntaxhighlight lang="xml">
<script src="script.lua" type="client"/> 
<script src="script.lua" type="server"/> 
</syntaxhighlight>

==Дополнительный слой защиты==

Чтобы незначительно ''усложнить жизнь*'' тем, у кого есть плохие намерения по отношению к вашему серверу, вы можете использовать аттрибут cache (и/или [https://luac.mtasa.com/ скомпилированные lua скрипты (также известные как Luac) с '''3''' уровнем дополнительной обфускации] - [https://wiki.multitheftauto.com/wiki/Lua_compilation_API API]), доступный в [https://wiki.multitheftauto.com/wiki/Meta.xml meta.xml], вместе с настройкой встроенного античита МТА с включением SD (специальными кодами обнаружения), для дополнительной информации смотрите [https://wiki.multitheftauto.com/wiki/Anti-cheat_guide гайд по античиту].

<syntaxhighlight lang="xml">
<script src="shared.lua" type="shared" cache="false"/> 
<script src="client.lua" type="client" cache="false"/> 
</syntaxhighlight>

* ''Усложнить жизнь'' '''не означает "сделать невозможным"''' получение вашего клиентского Lua кода, это означает, что '''большинство''' людей не смогут просмотреть ваши .lua файлы - тех, кто ищет логические ошибки (баги) или отсутствующие/некорректные проверки безопасности.
* Может использоваться на '''client''' и '''shared''' типах скриптов (не имеет эффекта на серверных скриптах).
* Это не удалит Lua файлы, которые были загружены ранее.

==Detecting and dealing with backdoors and cheats==
'''To ensure minimum (or no) damage resulting from Lua scripts:'''
* Keep your server up-to-date, you can [https://nightly.multitheftauto.com/ download latest server builds from MTA:SA nightly site.] Information on specific builds can be [https://buildinfo.multitheftauto.com/ found here.]
* Keep your resources up-to-date, you can [https://github.com/multitheftauto/mtasa-resources download latest (default) resources from GitHub repository.] Those often contain latest security fixes, which could mean difference between having your server resist from attack or not.
* Make sure to properly configure [https://wiki.multitheftauto.com/wiki/Access%20Control%20List ACL (Access Control List)] - which will block resources from using certain, potentially dangerous functions.
* Zero-trust with giving away admin rights for resources (including maps) coming from unknown sources.
* Before running any resource you don't trust, analyze:
** [https://wiki.multitheftauto.com/wiki/Meta.xml meta.xml] of it, for possible hidden scripts lurking beneath other file extensions.
** It's source code, for malicious logic.
* Do not run/keep using compiled resources (scripts) of which legitimacy you aren't sure.

'''To ensure minimum damage when a cheater connects to your server:'''
* When making scripts, remember to never trust data coming from a client.
* While reviewing scripts for possible security holes. Look at any data coming from the client that is being trusted.
* Any kind of data could be sent, hence server scripts which communicate with client by receiving data sent by players should validate it, before further use in latter parts of code. Mostly, it will be done either by [[setElementData]] or [[triggerServerEvent]].
* You shouldn't rely only on player [https://wiki.multitheftauto.com/wiki/Serial serial], when it comes to processing crucial operations (auto-login/admin actions). '''Serials aren't guaranted to be unique or non-fakable'''. This is why you should '''put it behind''' account system, as '''important authentication factor''' (e.g: '''login & password''').
* Server-side logic '''can not be bypassed''' or '''tampered''' with (unless server is breached or when there is a bug in code, but that's whole different scenario) - '''use it to your advantage'''. In majority of cases, you will be able to perform security validations with no participation of client-side.
* Using concept of '''''“All parameters including source can be faked and should not be trusted. Global variable client can be trusted.”''''' - gives you reliable assurance that player to which you refer (via '''client''') '''is''' in fact, '''the one which really called event'''. This approach will protect you from situations where cheater can call & process for instance: admin events (e.g kick/ban player) by passing the actual admin ('''2nd''' argument in '''[[triggerServerEvent]]'''), or trigger events for other players (as if they were the ones who called them, but in reality it was forcefully done by cheater) - as a consequence of using wrong variable. To make sure you fully understood it, take a look at examples below:

<syntaxhighlight lang="lua">
--[[
DON'T EVER DO THAT - THAT IS COMPLETELY WRONG AND INSECURE
THE ISSUE: BY USING 'source' IN hasObjectPermissionTo YOU ARE LEAVING DOOR STRAIGHT OPEN FOR CHEATERS
]]

function onServerWrongAdminEvent(playerToBan)
if (not client) then -- 'client' points to the player who triggered the event, and should be used as security measure (in order to prevent player faking)
return false -- if this variable doesn't exists at the moment (for unknown reason, or it was the server who triggered this event), stop code execution
end

local defaultPermission = false -- do not allow action by default, see (defaultPermission): https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo
local canAdminBanPlayer = hasObjectPermissionTo(source, "function.banPlayer", defaultPermission) -- the vulnerability lies here...

if (not canAdminBanPlayer) then -- if player doesn't have permissions
return false -- don't do it
end

local validElement = isElement(playerToBan) -- check whether argument passed from client is an element

if (not validElement) then -- it is not
return false -- stop code processing
end

local elementType = getElementType(playerToBan) -- it's an element, so get it's type
local playerType = (elementType == "player") -- make sure that it's a player

if (not playerType) then -- it's not a player
return false -- stop here
end

-- banPlayer(...) -- do what needs to be done
end
addEvent("onServerWrongAdminEvent", true)
addEventHandler("onServerWrongAdminEvent", root, onServerWrongAdminEvent)

--[[
onServerCorrectAdminEvent IS PERFECTLY SECURED, AS IT SHOULD BE
NO ISSUE HERE: WE'VE USED 'client' IN hasObjectPermissionTo WHICH MAKES IT SAFE FROM FAKING PLAYER WHO CALLED EVENT
]]

function onServerCorrectAdminEvent(playerToBan)
if (not client) then -- 'client' points to the player who triggered the event, and should be used as security measure (in order to prevent player faking)
return false -- if this variable doesn't exists at the moment (for unknown reason, or it was the server who triggered this event), stop code execution
end

local defaultPermission = false -- do not allow action by default, see (defaultPermission): https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo
local canAdminBanPlayer = hasObjectPermissionTo(client, "function.banPlayer", defaultPermission) -- is player allowed to do that?

if (not canAdminBanPlayer) then -- if player doesn't have permissions
return false -- don't do it
end

local validElement = isElement(playerToBan) -- check whether argument passed from client is an element

if (not validElement) then -- it is not
return false -- stop code processing
end

local elementType = getElementType(playerToBan) -- it's an element, so get it's type
local playerType = (elementType == "player") -- make sure that it's a player

if (not playerType) then -- it's not a player
return false -- stop here
end

-- banPlayer(...) -- do what needs to be done
end
addEvent("onServerCorrectAdminEvent", true)
addEventHandler("onServerCorrectAdminEvent", root, onServerCorrectAdminEvent)
</syntaxhighlight>

==Securing setElementData==

* You should refrain from using [[element data]] everywhere, it should be only used when really necessary. It is advised to replace it with [[triggerClientEvent]] instead.
* If you still insist on using it, it is recommended to set '''4th''' argument in [[setElementData]] to '''false''' (disabling sync for this, certain data) and use subscriber mode - [[addElementDataSubscriber]], for both security & performance reasons described in [https://wiki.multitheftauto.com/wiki/Script_security#Securing_triggerServerEvent event section.]
{{Important Note|Disabling sync however, doesn't fully protect data key. It would be still vulnerable by default, but in this case you are not leaving it in plain sight. Using [[getAllElementData]] or digging in RAM wouldn't expose it, since it won't be synced to client in first place. Therefore, it needs to be added to anti-cheat as well.}}
* All parameters including '''source''' can be faked and should not be trusted.
* Global variable '''client''' can be trusted.

----------
<section name="Server" class="server" show="true">
Example of basic element data anti-cheat.
<syntaxhighlight lang="lua">
local function reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue) -- helper function to log and revert changes
local logClient = inspect(clientElement) -- in-depth view of player which forced element data sync
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = tostring(sourceElement) -- element which received data
local logOldValue = tostring(oldValue) -- old value
local logNewValue = tostring(newValue) -- new value
local logText = -- fill our report with data
"=======================================\n"..
"Detected element data abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Data key: "..dataKey.."\n"..
"Old data value: "..logOldValue.."\n"..
"New data value: "..logNewValue.."\n"..
"======================================="

local logVisibleTo = root -- specify who will see this log in console, in this case each player connected to server
local hadData = (oldValue ~= nil) -- check if element had such data before

if (hadData) then -- if element had such data before
setElementData(sourceElement, dataKey, oldValue, true) -- revert changes, it will call onElementDataChange event, but will fail (stop) on first condition - because server (not client) forced change
else
removeElementData(sourceElement, dataKey) -- remove it completely
end

outputConsole(logText, logVisibleTo) -- print it to console

return true -- all success
end

function onElementDataChangeBasicAC(dataKey, oldValue, newValue) -- the heart of our anti-cheat, which does all the magic security measurements
if (not client) then -- check if data is coming from client
return false -- if it's not, do not go further
end

local checkSpecialThing = (dataKey == "special_thing") -- compare whether dataKey matches "special_thing"
local checkFlagWaving = (dataKey == "flag_waving") -- compare whether dataKey matches "flag_waving"

if (checkSpecialThing) then -- if it does, do our security checks
local invalidElement = (client ~= source) -- verify whether source element is different from player which changed data

if (invalidElement) then -- if it's so
reportAndRevertDataChange(client, source, dataKey, oldValue, newValue) -- revert data change, because "special_thing" can only be set for player himself
end
end

if (checkFlagWaving) then -- if it does, do our security checks
local playerVehicle = getPedOccupiedVehicle(client) -- get player's current vehicle
local invalidVehicle = (playerVehicle ~= source) -- verify whether source element is different from player's vehicle

if (invalidVehicle) then -- if it's so
reportAndRevertDataChange(client, source, dataKey, oldValue, newValue) -- revert data change, because "flag_waving" can only be set for player's own vehicle
end
end
end
addEventHandler("onElementDataChange", root, onElementDataChangeBasicAC)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
Example of advanced element data anti-cheat.
<syntaxhighlight lang="lua">
--[[
For maximum security set punishPlayerOnDetect, punishmentBan, allowOnlyProtectedKeys to true (as per default configuration)
If allowOnlyProtectedKeys is enabled, do not forget to add every client-side element data key to protectedKeys table - otherwise you will face false-positives

Anti-cheat (handleDataChange) table structure and it's options:

["keyName"] = { -- name of key which would be protected
onlyForPlayerHimself = true, -- enabling this (true) will make sure that this element data key can only be set on player who synced it (ignores onlyForOwnPlayerVeh and allowForElements), use false/nil to disable this
onlyForOwnPlayerVeh = false, -- enabling this (true) will make sure that this element data key can only be set on player's current vehicle who synced it (ignores allowForElements), use false/nil to disable this
allowForElements = { -- restrict this key for certain element type(s), set to false/nil or leave it empty to not check this (full list of element types: https://wiki.multitheftauto.com/wiki/GetElementsByType)
["player"] = true,
["ped"] = true,
["vehicle"] = true,
["object"] = true,
},
allowedDataTypes = { -- restrict this key for certain value type(s), set to false/nil or leave it empty to not check this
["string"] = true,
["number"] = true,
["table"] = true,
["boolean"] = true,
["nil"] = true,
},
allowedStringLength = {1, 32}, -- if value is a string, then it's length must be in between (min-max), set it to false/nil to not check string length - do note that allowedDataTypes must contain ["string"] = true
allowedTableLength = {1, 64}, -- if value is a table, then it's length must be in between (min-max), set it to false/nil to not check table length - do note that allowedDataTypes must contain ["table"] = true
allowedNumberRange = {1, 128}, -- if value is a number, then it must be in between (min-max), set it to false/nil to not check number range - do note that allowedDataTypes must contain ["number"] = true
}
]]

local punishPlayerOnDetect = true -- should player be punished upon detection (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Altering element data" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local allowOnlyProtectedKeys = true -- disallow (remove by using removeElementData) every element data besides those given in protectedKeys table; in case someone wanted to flood server with garbage keys, which would be kept in memory until server restart or manual remove - setElementData(source, key, nil) won't remove it; it has to be removeElementData
local debugLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugR = 255 -- debug message - red color
local debugG = 127 -- debug message - green color
local debugB = 0 -- debug message - blue color
local protectedKeys = {
["vehicleNumber"] = { -- we want vehicleNumber to be set only on vehicles, with stricte numbers in range of 1-100
allowForElements = {
["vehicle"] = true,
},
allowedDataTypes = {
["number"] = true,
},
allowedNumberRange = {1, 100},
},
["personalVehData"] = { -- we want be able to set personalVehData only on current vehicle, also it should be a string with length between 1-24
onlyForOwnPlayerVeh = true,
allowedDataTypes = {
["string"] = true,
},
allowedStringLength = {1, 24},
},
-- perform security checks on keys stored in this table, in a convenient way
}

local function reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- helper function to log and revert changes
local logClient = inspect(clientElement) -- in-depth view of player which forced element data sync
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = inspect(sourceElement) -- in-depth view of element which received data
local logOldValue = inspect(oldValue) -- in-depth view of old value
local logNewValue = inspect(newValue) -- in-depth view of new value
local logText = -- fill our report with data
"*\n"..
"Detected element data abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Data key: "..dataKey.."\n"..
"Old data value: "..logOldValue.."\n"..
"New data value: "..logNewValue.."\n"..
"Fail reason: "..failReason.."\n"..
"*"

outputDebugString(logText, debugLevel, debugR, debugG, debugB) -- print it to debug

if (forceRemove) then -- we don't want this element data key to exist at all
removeElementData(sourceElement, dataKey) -- remove it

return true -- return success and stop here, we don't need further checks
end

setElementData(sourceElement, dataKey, oldValue, true) -- revert changes, it will call onElementDataChange event, but will fail (stop) on first condition - because server (not client) forced change

return true -- return success
end

local function handleDataChange(clientElement, sourceElement, dataKey, oldValue, newValue) -- the heart of our anti-cheat, which does all the magic security measurements, returns true if there was no altering from client (based on data from protectedKeys), false otherwise
local protectedKey = protectedKeys[dataKey] -- look up whether key changed is stored in protectedKeys table

if (not protectedKey) then -- if it's not

if (allowOnlyProtectedKeys) then -- if we don't want garbage keys
local failReason = "Key isn't present in protectedKeys" -- reason shown in report
local forceRemove = true -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end

return true -- this key isn't protected, let it through
end

local onlyForPlayerHimself = protectedKey.onlyForPlayerHimself -- if key has "self-set" lock
local onlyForOwnPlayerVeh = protectedKey.onlyForOwnPlayerVeh -- if key has "self-vehicle" lock
local allowForElements = protectedKey.allowForElements -- if key has element type check
local allowedDataTypes = protectedKey.allowedDataTypes -- if key has allowed data type check

if (onlyForPlayerHimself) then -- if "self-set" lock is active
local matchingElement = (clientElement == sourceElement) -- verify whether player who set data is equal to element which received data

if (not matchingElement) then -- if it's not matching
local failReason = "Can only set on player himself" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (onlyForOwnPlayerVeh) then -- if "self-vehicle" lock is active
local playerVehicle = getPedOccupiedVehicle(clientElement) -- get current vehicle of player which set data
local matchingVehicle = (playerVehicle == sourceElement) -- check whether it matches the one which received data

if (not matchingVehicle) then -- if it doesn't match
local failReason = "Can only set on player's own vehicle" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowForElements) then -- check if it's one of them
local elementType = getElementType(sourceElement) -- get type of element whose data changed
local matchingElementType = allowForElements[elementType] -- verify whether it's allowed

if (not matchingElementType) then -- this isn't matching
local failReason = "Invalid element type" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedDataTypes) then -- if there's allowed data types
local valueType = type(newValue) -- get data type of value
local matchingType = allowedDataTypes[valueType] -- check if it's one of allowed

if (not matchingType) then -- if it's not then
local failReason = "Invalid data type" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end

local allowedStringLength = protectedKey.allowedStringLength -- if key has specified string length check
local dataString = (valueType == "string") -- make sure it's a string

if (allowedStringLength and dataString) then -- if we should check string length
local minLength = allowedStringLength[1] -- retrieve min length
local maxLength = allowedStringLength[2] -- retrieve max length
local stringLength = utf8.len(newValue) -- get length of data string
local matchingLength = (stringLength >= minLength) and (stringLength <= maxLength) -- compare whether value fits in between

if (not matchingLength) then -- if it doesn't
local failReason = "Invalid string length (must be between "..minLength.."-"..maxLength..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedTableLength = protectedKey.allowedTableLength -- if key has table length check
local dataTable = (valueType == "table") -- make sure it's a table

if (allowedTableLength and dataTable) then -- if we should check table length
local minLength = allowedTableLength[1] -- retrieve min length
local maxLength = allowedTableLength[2] -- retrieve max length
local minLengthAchieved = false -- variable which checks 'does minimum length was achieved'
local maxLengthExceeded = false -- variable which checks 'does length has exceeds more than allowed maximum'
local tableLength = 0 -- store initial table length

for _, _ in pairs(newValue) do -- loop through whole table
tableLength = (tableLength + 1) -- add + 1 on each table entry
minLengthAchieved = (tableLength >= minLength) -- is length bigger or at very minimum we require
maxLengthExceeded = (tableLength > maxLength) -- does table exceeded more than max length?

if (maxLengthExceeded) then -- it is bigger than it should be
break -- break the loop (due of condition above being worthy, it makes no point to count further and waste CPU, on a table which potentially could have huge amount of entries)
end
end

local matchingLength = (minLengthAchieved and not maxLengthExceeded) -- check if min length has been achieved, and make sure that it doesn't go beyond max length

if (not matchingLength) then -- this table doesn't match requirements
local failReason = "Invalid table length (must be between "..minLength.."-"..maxLength..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedNumberRange = protectedKey.allowedNumberRange -- if key has allowed number range check
local dataNumber = (valueType == "number") -- make sure it's a number

if (allowedNumberRange and dataNumber) then -- if we should check number range
local minRange = allowedNumberRange[1] -- retrieve min number range
local maxRange = allowedNumberRange[2] -- retrieve max number range
local matchingRange = (newValue >= minRange) and (newValue <= maxRange) -- compare whether value fits in between

if (not matchingRange) then -- if it doesn't
local failReason = "Invalid number range (must be between "..minRange.."-"..maxRange..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end
end

return true -- security checks passed, we are all clear with this data key
end

function onElementDataChangeAdvancedAC(dataKey, oldValue, newValue) -- this event makes use of handleDataChange, the code was split for better readability
if (not client) then -- check if data is coming from client
return false -- if it's not, do not continue
end

local approvedChange = handleDataChange(client, source, dataKey, oldValue, newValue) -- run our security checks

if (approvedChange) then -- it's all cool and good
return false -- we don't need further action
end

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(client, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(client, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onElementDataChange", root, onElementDataChangeAdvancedAC)
</syntaxhighlight>
</section>

==Securing triggerServerEvent==

* All parameters including '''source''' can be faked and should not be trusted.
* Global variable '''client''' can be trusted.
* '''Admin''' styled '''events''' should be verifying player (client) '''ACL rights''', either by [https://wiki.multitheftauto.com/wiki/IsObjectInACLGroup isObjectInACLGroup] or [https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo hasObjectPermissionTo].
* Do '''not''' use the same name for your custom event as MTA native server events (which aren't remotely triggerable by default), e.g: '''onPlayerLogin'''; doing so would open door for cheaters manipulations.
* Be aware to which players event is sent via [[triggerClientEvent]]. For both security & performance reasons, admin like events should be received by admins only (to prevent confidential data being accessed), in the same time you shouldn't send each event to everyone on server (e.g: login success event which hides login panel for certain player). [[triggerClientEvent]] allows you to specify the event receiver as first (optional) argument. It defaults to [[root]], meaning if you don't specify it, it will be sent to everyone connected to server - even those who are still downloading server cache (which results in ''Server triggered clientside event eventName, but event is not added clientside.''). You can either pass player element or table with receivers:
<syntaxhighlight lang="lua">
local playersToReceiveEvent = {player1, player2, player3} -- each playerX is player element

triggerClientEvent(playersToReceiveEvent, ...) -- do not forget to fill the latter part of arguments
</syntaxhighlight>

----------
<section name="Server" class="server" show="true">
Example of anti-cheat function designed for events, used for data validation for both normal, and admin events which are called from client-side.
<syntaxhighlight lang="lua">
--[[
For maximum security set punishPlayerOnDetect, punishmentBan to true (as per default configuration)

Anti-cheat (processServerEventData) table structure and it's options:

checkACLGroup = { -- check whether player who called event belongs to at least one group below, set to false/nil to not check this
"Admin",
},
checkPermissions = { -- check whether player who called event has permission to at least one thing below, set to false/nil to not check this
"function.kickPlayer",
},
checkEventData = {
{
debugData = "source", -- optional details for report shown in debug message
eventData = source, -- data we want to verify
equalTo = client, -- compare whether eventData == equalTo
allowedElements = { -- restrict eventData to be certain element type(s), set to false/nil or leave it empty to not check this (full list of element types: https://wiki.multitheftauto.com/wiki/GetElementsByType)
["player"] = true,
["ped"] = true,
["vehicle"] = true,
["object"] = true,
},
allowedDataTypes = { -- restrict eventData to be certain value type(s), set to false/nil or leave it empty to not check this
["string"] = true,
["number"] = true,
["table"] = true,
["boolean"] = true,
["nil"] = true,
},
allowedStringLength = {1, 32}, -- if eventData is a string, then it's length must be in between (min-max), set it to false/nil to not check string length - do note that allowedDataTypes must contain ["string"] = true
allowedTableLength = {1, 64}, -- if eventData is a table, then it's length must be in between (min-max), set it to false/nil to not check table length - do note that allowedDataTypes must contain ["table"] = true
allowedNumberRange = {1, 128}, -- if eventData is a number, then it must be in between (min-max), set it to false/nil to not check number range - do note that allowedDataTypes must contain ["number"] = true
},
},
]]

local punishPlayerOnDetect = true -- should player be punished upon detection (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Altering server event data" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugR = 255 -- debug message - red color
local debugG = 127 -- debug message - green color
local debugB = 0 -- debug message - blue color

function processServerEventData(clientElement, sourceElement, serverEvent, securityChecks) -- the heart of our anti-cheat, which does all the magic security measurements, returns true if there was no altering from client (based on data from securityChecks), false otherwise
if (not securityChecks) then -- if we haven't passed any security checks
return true -- nothing to check, let code go further
end

if (not clientElement) then -- if client variable isn't available for some reason (although it should never happen)
local failReason = "Client variable not present" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local checkACLGroup = securityChecks.checkACLGroup -- if there's any ACL groups to check
local checkPermissions = securityChecks.checkPermissions -- if there's any permissions to check
local checkEventData = securityChecks.checkEventData -- if there's any data checks

if (checkACLGroup) then -- let's check player ACL groups
local playerAccount = getPlayerAccount(clientElement) -- get current account of player
local guestAccount = isGuestAccount(playerAccount) -- if account is guest (meaning player is not logged in)

if (guestAccount) then -- it's the case
local failReason = "Can't retrieve player login - guest account" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local accountName = getAccountName(playerAccount) -- get name of player's current account
local aclString = "user."..accountName -- format it for further use in isObjectInACLGroup function

for groupID = 1, #checkACLGroup do -- iterate over table of given groups
local groupName = checkACLGroup[groupID] -- get each group name
local aclGroup = aclGetGroup(groupName) -- check if such group exists

if (not aclGroup) then -- it doesn't
local failReason = "ACL group '"..groupName.."' is missing" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local playerInACLGroup = isObjectInACLGroup(aclString, aclGroup) -- check if player belong to the group

if (playerInACLGroup) then -- yep, it's the case
return true -- so it's a success
end
end

local failReason = "Player doesn't belong to any given ACL group" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

if (checkPermissions) then -- check if player has at least one desired permission
local allowedByDefault = false -- does he have access by default

for permissionID = 1, #checkPermissions do -- iterate over all permissions
local permissionName = checkPermissions[permissionID] -- get permission name
local hasPermission = hasObjectPermissionTo(clientElement, permissionName, allowedByDefault) -- check whether player is allowed to perform certain action

if (hasPermission) then -- if player has access
return true -- one is available (and enough), server won't bother to check others (as return keywords also breaks loop)
end
end

local failReason = "Not enough permissions" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

if (checkEventData) then -- if there is some data to verify

for dataID = 1, #checkEventData do -- iterate over each of data
local dataToCheck = checkEventData[dataID] -- get each data set
local eventData = dataToCheck.eventData -- this is the one we'll be verifying
local equalTo = dataToCheck.equalTo -- we want to compare whether eventData == equalTo
local allowedElements = dataToCheck.allowedElements -- check whether is element, and whether belongs to certain element types
local allowedDataTypes = dataToCheck.allowedDataTypes -- do we restrict data to be certain type?
local debugData = dataToCheck.debugData -- additional helper data
local debugText = debugData and " ("..debugData..")" or "" -- if it's present, format it nicely

if (equalTo) then -- equal check exists
local matchingData = (eventData == equalTo) -- compare whether those two values are equal

if (not matchingData) then -- they aren't
local failReason = "Data isn't equal @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedElements) then -- we do check whether is an element, and belongs to at least one given in the list
local validElement = isElement(eventData) -- check if it's actual element

if (not validElement) then -- it's not
local failReason = "Data isn't element @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local elementType = getElementType(eventData) -- it's element, so we want to know it's type
local matchingElementType = allowedElements[elementType] -- verify whether it's allowed

if (not matchingElementType) then -- it's not allowed
local failReason = "Invalid element type @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedDataTypes) then -- let's check allowed data types
local dataType = type(eventData) -- get data type
local matchingType = allowedDataTypes[dataType] -- verify whether it's allowed

if (not matchingType) then -- it isn't
local failReason = "Invalid data type @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local allowedStringLength = dataToCheck.allowedStringLength -- if data has string length check
local dataString = (dataType == "string") -- make sure it's a string

if (allowedStringLength and dataString) then -- if we should check string length
local minLength = allowedStringLength[1] -- retrieve min length
local maxLength = allowedStringLength[2] -- retrieve max length
local stringLength = utf8.len(eventData) -- get length of data string
local matchingLength = (stringLength >= minLength) and (stringLength <= maxLength) -- compare whether value fits in between

if (not matchingLength) then -- if it doesn't
local failReason = "Invalid string length (must be between "..minLength.."-"..maxLength..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedTableLength = dataToCheck.allowedTableLength -- if data has table length check
local dataTable = (dataType == "table") -- make sure it's a table

if (allowedTableLength and dataTable) then -- if we should check table length
local minLength = allowedTableLength[1] -- retrieve min length
local maxLength = allowedTableLength[2] -- retrieve max length
local minLengthAchieved = false -- variable which checks 'does minimum length was achieved'
local maxLengthExceeded = false -- variable which checks 'does length has exceeds more than allowed maximum'
local tableLength = 0 -- store initial table length

for _, _ in pairs(eventData) do -- loop through whole table
tableLength = (tableLength + 1) -- add + 1 on each table entry
minLengthAchieved = (tableLength >= minLength) -- is length bigger or at very minimum we require
maxLengthExceeded = (tableLength > maxLength) -- does table exceeded more than max length?

if (maxLengthExceeded) then -- it is bigger than it should be
break -- break the loop (due of condition above being worthy, it makes no point to count further and waste CPU, on a table which potentially could have huge amount of entries)
end
end

local matchingLength = (minLengthAchieved and not maxLengthExceeded) -- check if min length has been achieved, and make sure that it doesn't go beyond max length

if (not matchingLength) then -- this table doesn't match requirements
local failReason = "Invalid table length (must be between "..minLength.."-"..maxLength..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedNumberRange = dataToCheck.allowedNumberRange -- if data has number range check
local dataNumber = (dataType == "number") -- make sure it's a number

if (allowedNumberRange and dataNumber) then -- if we should check number range
local minRange = allowedNumberRange[1] -- retrieve min number range
local maxRange = allowedNumberRange[2] -- retrieve max number range
local matchingRange = (eventData >= minRange) and (eventData <= maxRange) -- compare whether value fits in between

if (not matchingRange) then -- if it doesn't
local failReason = "Invalid number range (must be between "..minRange.."-"..maxRange..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end
end
end
end

return true -- security checks passed, we are all clear with this event call
end

function reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- helper function to log and handle accidents
local logClient = inspect(clientElement) -- in-depth view player which called event
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = inspect(sourceElement) -- in-depth view of source element
local logText = -- fill our report with data
"*\n"..
"Detected event abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Event: "..serverEvent.."\n"..
"Reason: "..failReason.."\n"..
"*"

outputDebugString(logText, debugLevel, debugR, debugG, debugB) -- print it to debug

if (not punishPlayerOnDetect or skipPunishment) then -- we don't want to punish player for some reason
return true -- stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(clientElement, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(clientElement, punishedBy, punishmentReason) -- simply kick player out of server
end

return true -- all done, report success
end

function onServerEvent(clientData)
--[[
Assume this server event (function) is called in such way:

local dataToPass = 10

triggerServerEvent("onServerEvent", localPlayer, dataToPass)
]]

local shouldProcessServerCode = processServerEventData(
client, -- client element - responsible for calling event
source, -- source element - passed in triggerServerEvent (as 2nd argument)
eventName, -- name of event - in this case 'onServerEvent'
{
checkEventData = { -- we want to verify everything what comes from client
{
eventData = source, -- first to check, source variable
equalTo = client, -- we want to check whether it matches player who called event
debugData = "source", -- helper details which would be shown in report
},
{
eventData = clientData, -- let's check the data which client sent to us
allowedDataTypes = {
["number"] = true, -- we want it to be only number
},
allowedNumberRange = {1, 100}, -- in range of 1 to 100
debugData = "clientData", -- if something goes wrong, let server know where (it will appear in debug report)
},
},
}
)

if (not shouldProcessServerCode) then -- something isn't right, no green light for processing code behind this scope
return false -- stop code execution
end

-- do code as usual
end
addEvent("onServerEvent", true)
addEventHandler("onServerEvent", root, onServerEvent)

function onServerAdminEvent(playerToBan)
--[[
Assume this server admin event (function) is called in such way:

local playerToBan = getPlayerFromName("playerToBan")

triggerServerEvent("onServerAdminEvent", localPlayer, playerToBan)
]]

local shouldProcessServerCode = processServerEventData(
client, -- client element - responsible for calling event
source, -- source element - passed in triggerServerEvent (as 2nd argument)
eventName, -- name of event - in this case 'onServerAdminEvent'
{
checkACLGroup = { -- we need to check whether player who called event belongs to ACL groups
"Admin", -- in this case admin group
},
checkEventData = { -- we want to verify everything what comes from client
{
eventData = source, -- first to check, source variable
equalTo = client, -- we want to check whether it matches player who called event
debugData = "source", -- helper details which would be shown in report
},
{
eventData = playerToBan, -- let's check the data which client sent to us
allowedDataTypes = {
["player"] = true, -- we want it to be player
},
debugData = "playerToBan", -- if something goes wrong, let server know where (it will appear in debug report)
},
},
}
)

if (not shouldProcessServerCode) then -- something isn't right, no green light for processing code behind this scope
return false -- stop code execution
end

-- do code as usual
end
addEvent("onServerAdminEvent", true)
addEventHandler("onServerAdminEvent", root, onServerAdminEvent)
</syntaxhighlight>
</section>

==Securing server-only events==
* It is very important to '''disable remote triggering''' ability in [https://wiki.multitheftauto.com/wiki/AddEvent addEvent], to prevent calling server-side only events from client-side.
* '''Admin''' styled '''events''' should be verifying player '''ACL rights''', either by [https://wiki.multitheftauto.com/wiki/IsObjectInACLGroup isObjectInACLGroup] or [https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo hasObjectPermissionTo].

----------
<section name="Server" class="server" show="true">
This example shows how you should make event server-side only.
<syntaxhighlight lang="lua">
function onServerSideOnlyEvent()
-- do some server-side stuff
end
addEvent("onServerSideOnlyEvent", false) -- set second argument (allowRemoteTriger) to false, so it can't be called from client
addEventHandler("onServerSideOnlyEvent", root, onServerSideOnlyEvent) -- associate our event with function onServerSideOnlyEvent
</syntaxhighlight>
</section>

==Securing projectiles & explosions==
This section (and '''code''' is '''work in progress''') - '''use at your own risk'''.

----------
<section name="Server" class="server" show="false">
Projectile ammo tracker:
<syntaxhighlight lang="lua">
local playerProjectileAmmo = {} -- store player-held weapons ammo here
local playerWeaponsToTrack = { -- keep track of ammo for certain player-held weapon types, basically those which create projectile; [weaponID] = weaponSlot
[16] = 8, -- grenade
[17] = 8, -- teargas
[18] = 8, -- molotov
[35] = 7, -- rocket launcher
[36] = 7, -- rocket launcher (heat-seeking)
[39] = 8, -- satchel charge
}

local function updateProjectileAmmoForPlayer(playerElement)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

for weaponID, weaponSlot in pairs(playerWeaponsToTrack) do
local weaponInSlot = getPedWeapon(playerElement, weaponSlot)
local weaponTotalAmmo = getPedTotalAmmo(playerElement, weaponSlot)
local weaponHasAmmo = (weaponTotalAmmo > 0)
local weaponMatching = (weaponInSlot == weaponID)
local updateWeaponAmmo = (weaponMatching and weaponHasAmmo)

if (updateWeaponAmmo) then
local storedProjectileAmmo = playerProjectileAmmo[playerElement]
local newWeaponAmmo = (updateWeaponAmmo and weaponTotalAmmo or nil)

if (not storedProjectileAmmo) then
playerProjectileAmmo[playerElement] = {}
storedProjectileAmmo = playerProjectileAmmo[playerElement]
end

storedProjectileAmmo[weaponID] = newWeaponAmmo
end
end

return true
end

function hasPlayerProjectileAmmo(playerElement, projectileWeapon)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

local projectileData = playerProjectileAmmo[playerElement]
local projectileAmmo = (projectileData and projectileData[projectileWeapon])

return projectileAmmo
end

function decreasePlayerProjectileAmmo(playerElement, projectileWeapon)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

local playerProjectileData = playerProjectileAmmo[playerElement]

if (not playerProjectileData) then
return false
end

local projectileWeaponAmmo = playerProjectileData[projectileWeapon]
local tempProjectileAmmo = (projectileWeaponAmmo - 1)
local newProjectileAmmo = (tempProjectileAmmo > 0 and tempProjectileAmmo or nil)

playerProjectileData[projectileWeapon] = newProjectileAmmo

return true
end

function onPlayerWeaponSwitchAntiCheat(previousWeaponID, currentWeaponID)
setTimer(updateProjectileAmmoForPlayer, 50, 1, source)
end
addEventHandler("onPlayerWeaponSwitch", root, onPlayerWeaponSwitchAntiCheat)

function onResourceStartAntiCheat()
local playersTable = getElementsByType("player")

for playerID = 1, #playersTable do
local playerElement = playersTable[playerID]

updateProjectileAmmoForPlayer(playerElement)
end
end
addEventHandler("onResourceStart", resourceRoot, onResourceStartAntiCheat)

function onPlayerWastedQuitAntiCheat()
playerProjectileAmmo[source] = nil
end
addEventHandler("onPlayerWasted", root, onPlayerWastedQuitAntiCheat)
addEventHandler("onPlayerQuit", root, onPlayerWastedQuitAntiCheat)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
Projectile handler:
<syntaxhighlight lang="lua">
local playerCreatedProjectiles = {} -- store count of legitimately created player projectiles; [playerElement] = {[projectileType] = activeProjectiles}
local projectileTypes = {
[16] = { -- Grenade
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[16] = true, -- grenade
},
},
[17] = { -- Teargas
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[17] = true, -- teargas
},
},
[18] = { -- Molotov
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[18] = true, -- molotov
},
},
[19] = { -- Rocket
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileMaxVelocity = 2,
projectileAllowedWeapons = {
[35] = true, -- rocket launcher
},
projectileAllowedVehicles = {
[425] = true, -- hunter
[520] = true, -- hydra
},
},
[20] = { -- Rocket (heat-seeking)
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileMaxVelocity = 2,
projectileAllowedWeapons = {
[36] = true, -- rocket launcher (heat-seeking)
},
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
[21] = { -- Airbomb
projectileAllowed = true,
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
[39] = { -- Satchel charge
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[39] = true, -- satchel charge
},
},
[58] = { -- Hydra flare
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
}

local reportAbnormality = true -- whether to report about abnormality in debug script - by default
local punishPlayerOnDetect = false -- should player be punished upon detection; true - yes, or false to not do anything (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Projectile/explosion anti-cheat" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugMsgLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugMsgR = 255 -- debug message - red color
local debugMsgG = 127 -- debug message - green color
local debugMsgB = 0 -- debug message - blue color

local function reportProjectileAbnormality(playerElement, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ, detectionCode)
local projectileSyncer = inspect(playerElement)
local projectilePosition = projectileX..", "..projectileY..", "..projectileZ
local projectileZoneName = getZoneName(projectileX, projectileY, projectileZ, false)
local projectileCityName = getZoneName(projectileX, projectileY, projectileZ, true)
local projectileLog =
"* Detected projectile abnormality - "..detectionCode.." *\n"..
"Projectile syncer: "..projectileSyncer.."\n"..
"Projectile type: "..projectileType.."\n"..
"Projectile position: "..projectilePosition.. " ("..projectileZoneName..", "..projectileCityName..")\n"

outputDebugString(projectileLog, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)

return true
end

local function processProjectileChecks(playerElement, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)
local projectileData = projectileTypes[projectileType]
local projectileAllowed = projectileData.projectileAllowed

if (not projectileAllowed) then
return false, "Projectile not allowed"
end

local projectileAllowedWeapons = projectileData.projectileAllowedWeapons

if (projectileAllowedWeapons) then
local playerWeapon = getPedWeapon(playerElement)
local allowedWeapon = projectileAllowedWeapons[playerWeapon]

if (not allowedWeapon) then
return false, "Player is not holding correct weapon"
end

local weaponAmmo = hasPlayerProjectileAmmo(playerElement, playerWeapon)
local playerHasAmmo = (weaponAmmo > 0)

if (not playerHasAmmo) then
return false, "Player doesn't have ammo for weapon"
end

decreasePlayerProjectileAmmo(playerElement, playerWeapon)
end

local playerVehicle = getPedOccupiedVehicle(playerElement)

if (playerVehicle) then
local projectileAllowedVehicles = projectileData.projectileAllowedVehicles

if (projectileAllowedVehicles) then
local vehicleModel = getElementModel(playerVehicle)
local allowedVehicle = projectileAllowedVehicles[vehicleModel]

if (not allowedVehicle) then
return false, "Player is not inside allowed vehicles"
end

local vehicleDriver = getVehicleController(playerVehicle)
local playerDriver = (playerElement == vehicleDriver)

if (not playerDriver) then
return false, "Player is not vehicle driver"
end

return true
end

return false, "Player in vehicle"
end

local projectileMaxDistanceFromCreator = projectileData.projectileMaxDistanceFromCreator

if (projectileMaxDistanceFromCreator) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToProjectile = getDistanceBetweenPoints3D(playerX, playerY, playerZ, projectileX, projectileY, projectileZ)
local matchingProjectileDistance = (distanceToProjectile <= projectileMaxDistanceFromCreator)

if (not matchingProjectileDistance) then
return false, "Projectile distance mismatch"
end
end

local projectileMaxVelocity = projectileData.projectileMaxVelocity

if (projectileMaxVelocity) then
local projectileVelocity = (projectileVX ^ 2 + projectileVY ^ 2 + projectileVZ ^ 2)
local projectileSpeed = math.sqrt(projectileVelocity)
local matchingProjectileVelocity = (projectileSpeed <= projectileMaxVelocity)

if (not matchingProjectileVelocity) then
return false, "Projectile velocity mismatch"
end
end

return true
end

local function trackPlayerProjectile(playerElement, projectileID)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerProjectiles = playerCreatedProjectiles[playerElement]

if (not playerProjectiles) then
playerCreatedProjectiles[playerElement] = {}
playerProjectiles = playerCreatedProjectiles[playerElement]
end

local projectilesByType = playerProjectiles[projectileID] or 0
local newProjectilesCount = (projectilesByType + 1)

playerProjectiles[projectileID] = newProjectilesCount

return true
end

local function getProjectileDetectionOverwrittenBehavior(projectileType)
local projectileData = projectileTypes[projectileType]

if (not projectileData) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local projectileBehaviour = projectileData.projectileOverwriteBehaviour

if (not projectileBehaviour) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local overwriteReport = projectileBehaviour.reportAbnormality
local overwritePunish = projectileBehaviour.punishPlayerOnDetect
local overwriteBan = projectileBehaviour.punishmentBan

return overwriteReport, overwritePunish, overwriteBan
end

function decreasePlayerProjectiles(playerElement, projectileID)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerProjectiles = playerCreatedProjectiles[playerElement]

if (not playerProjectiles) then
return false, true
end

local projectilesByType = playerProjectiles[projectileID]

if (not projectilesByType) then
return false, true
end

local tempProjectilesCount = (projectilesByType - 1)
local newProjectilesCount = (tempProjectilesCount > 0 and tempProjectilesCount or nil)

playerProjectiles[projectileID] = newProjectilesCount

return true
end

function onPlayerProjectileCreationAntiCheat(projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)
local approvedProjectile, detectionCode = processProjectileChecks(source, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)

if (approvedProjectile) then
trackPlayerProjectile(source, projectileType)

return true
end

local reportAbnormality, punishPlayerOnDetect, punishmentBan = getProjectileDetectionOverwrittenBehavior(projectileType)

if (reportAbnormality) then
reportProjectileAbnormality(source, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ, detectionCode)
end

cancelEvent()

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(source, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(source, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onPlayerProjectileCreation", root, onPlayerProjectileCreationAntiCheat)

function onPlayerQuitAntiCheat()
playerCreatedProjectiles[source] = nil
end
addEventHandler("onPlayerQuit", root, onPlayerQuitAntiCheat)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
Explosions handler:
<syntaxhighlight lang="lua">
local rocketInstantExplosionDistanceThreshold = 1.55 -- distance below which only explosion will be created (and not rocket projectile, hence not calling onPlayerProjectileCreation); do not change it
local explosionTypes = { -- more specific info on explosion, and whether it is allowed
[0] = { -- Grenade
explosionAllowed = true,
explosionAllowedProjectiles = {
[16] = true, -- grenade
},
},
[1] = { -- Molotov
explosionAllowed = true,
explosionAllowedProjectiles = {
[18] = true, -- molotov
},
},
[2] = { -- Rocket
explosionAllowed = true,
explosionAllowedWeapons = {
[35] = true, -- rocket launcher
[36] = true, -- rocket launcher (heat-seeking)
},
explosionAllowedProjectiles = {
[19] = true, -- rocket
[20] = true, -- rocket (heat-seeking)
},
},
[3] = { -- Rocket weak
explosionAllowed = true,
explosionAllowedProjectiles = {
[19] = true, -- rocket
[20] = true, -- rocket (heat-seeking)
},
},
[4] = { -- Car
explosionAllowed = true,
},
[5] = { -- Car quick
explosionAllowed = true,
},
[6] = { -- Boat
explosionAllowed = true,
},
[7] = { -- Heli
explosionAllowed = true,
},
[8] = { -- Mine
explosionAllowed = true,
},
[9] = { -- Object
explosionAllowed = true,
},
[10] = { -- Tank grenade
explosionAllowed = true,
explosionMaxDistanceFromCreator = 80,
explosionAllowedVehicles = {
[432] = true,
}
},
[11] = { -- Small
explosionAllowed = true,
},
[12] = { -- Tiny
explosionAllowed = true,
},
}

local reportAbnormality = true -- whether to report about abnormality in debug script - by default
local punishPlayerOnDetect = false -- should player be punished upon detection; true - yes, or false to not do anything (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Projectile/explosion anti-cheat" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugMsgLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugMsgR = 255 -- debug message - red color
local debugMsgG = 127 -- debug message - green color
local debugMsgB = 0 -- debug message - blue color

local function reportExplosionAbnormality(playerElement, explosionType, explosionX, explosionY, explosionZ, detectionCode)
local explosionSyncer = inspect(playerElement)
local explosionType = explosionType
local explosionPosition = explosionX..", "..explosionY..", "..explosionZ
local explosionZoneName = getZoneName(explosionX, explosionY, explosionZ, false)
local explosionCityName = getZoneName(explosionX, explosionY, explosionZ, true)
local explosionLog =
"* Detected explosion abnormality - "..detectionCode.." *\n"..
"Explosion syncer: "..explosionSyncer.."\n"..
"Explosion type: "..explosionType.."\n"..
"Explosion position: "..explosionPosition.. " ("..explosionZoneName..", "..explosionCityName..")\n"

outputDebugString(explosionLog, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)

return true
end

local function processExplosionChecks(playerElement, explosionType, explosionX, explosionY, explosionZ)
local explosionData = explosionTypes[explosionType]
local explosionAllowed = explosionData.explosionAllowed

if (not explosionAllowed) then
return false, "Explosion type not allowed"
end

local rocketExplosion = (explosionType == 2)

if (rocketExplosion) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToExplosion = getDistanceBetweenPoints3D(playerX, playerY, playerZ, explosionX, explosionY, explosionZ)
local instantExplosion = (distanceToExplosion < rocketInstantExplosionDistanceThreshold)

if (instantExplosion) then
local explosionAllowedWeapons = explosionData.explosionAllowedWeapons
local playerWeapon = getPedWeapon(playerElement)
local allowedWeapon = explosionAllowedWeapons[playerWeapon]

if (not allowedWeapon) then
return false, "Player is not holding rocket launcher"
end

local weaponAmmo = hasPlayerProjectileAmmo(playerElement, playerWeapon)
local playerHasAmmo = (weaponAmmo > 0)

if (not playerHasAmmo) then
return false, "Player doesn't have ammo for rocket launcher"
end

decreasePlayerProjectileAmmo(playerElement, playerWeapon)

return true
end
end

local explosionAllowedProjectiles = explosionData.explosionAllowedProjectiles

if (explosionAllowedProjectiles) then

for projectileID, _ in pairs(explosionAllowedProjectiles) do
local atleastOneProjectile = decreasePlayerProjectiles(playerElement, projectileID)

if (atleastOneProjectile) then
return true
end
end

return false, "Explosion created without respective projectile"
end

local explosionAllowedVehicles = explosionData.explosionAllowedVehicles

if (explosionAllowedVehicles) then
local playerVehicle = getPedOccupiedVehicle(playerElement)

if (not playerVehicle) then
return false, "Player is not in vehicle"
end

local vehicleModel = getElementModel(playerVehicle)
local allowedVehicle = explosionAllowedVehicles[vehicleModel]

if (not allowedVehicle) then
return false, "Player is inside not allowed vehicles"
end

local vehicleDriver = getVehicleController(playerVehicle)
local playerDriver = (playerElement == vehicleDriver)

if (not playerDriver) then
return false, "Player is not vehicle driver"
end
end

local explosionMaxDistanceFromCreator = explosionData.explosionMaxDistanceFromCreator

if (explosionMaxDistanceFromCreator) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToExplosion = getDistanceBetweenPoints3D(playerX, playerY, playerZ, explosionX, explosionY, explosionZ)
local matchingExplosionDistance = (distanceToExplosion < explosionMaxDistanceFromCreator)

if (not matchingExplosionDistance) then
return false, "Explosion distance mismatch"
end
end

return true
end

local function getExplosionDetectionOverwrittenBehavior(explosionType)
local explosionData = explosionTypes[explosionType]

if (not explosionData) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local explosionBehaviour = explosionData.explosionOverwriteBehaviour

if (not explosionBehaviour) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local overwriteReport = explosionBehaviour.reportAbnormality
local overwritePunish = explosionBehaviour.punishPlayerOnDetect
local overwriteBan = explosionBehaviour.punishmentBan

return overwriteReport, overwritePunish, overwriteBan
end

function onExplosionAntiCheat(explosionX, explosionY, explosionZ, explosionType)
local serverSyncExplosion = (source == root)

if (serverSyncExplosion) then
return true
end

local approvedExplosion, detectionCode = processExplosionChecks(source, explosionType, explosionX, explosionY, explosionZ)

if (approvedExplosion) then
return true
end

local reportAbnormality, punishPlayerOnDetect, punishmentBan = getExplosionDetectionOverwrittenBehavior(explosionType)

if (reportAbnormality) then
reportExplosionAbnormality(source, explosionType, explosionX, explosionY, explosionZ, detectionCode)
end

cancelEvent()

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(source, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(source, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onExplosion", root, onExplosionAntiCheat)
</syntaxhighlight>
</section>

==Handling non-registered events==

See: [[onPlayerTriggerInvalidEvent]]

==Handling events spam==
See: [[onPlayerTriggerEventThreshold]]

User:DColeman/RU:Безопасность скриптов

2025-05-10T11:33:33Z

DColeman: Init

==Информация по памяти клиента==

Начиная с самых основ:
* Вы должны понимать, что все, что вы храните на стороне клиента, включая .lua файлы, находится под риском. Любая конфиденциальная или критическая информация, которая как-либо оказывается на клиентской стороне (ПК игрока), может быть прочитана и/или изменена чит-клиентами.
* Чтобы сохранить конфиденциальную информацию и логику скрипта в секрете - используйте серверную сторону.
* Обратите внимание, что скрипты, отмеченные как общие ('''shared''') также действуют как '''клиентские''', что означает, что все вышеперечисленное также применяется и к ним. Например, объявление скрипта:

<syntaxhighlight lang="xml">
<script src="script.lua" type="shared"/> 
</syntaxhighlight>

То же самое, что и объявление:

<syntaxhighlight lang="xml">
<script src="script.lua" type="client"/> 
<script src="script.lua" type="server"/> 
</syntaxhighlight>

==Additional protection layer==

In order to make things ''slightly harder*'' for those having bad intentions towards your server, you can make use of cache attribute (and/or [https://luac.mtasa.com/ Lua compile (also known as Luac) with extra obfuscation set to level '''3'''] - [https://wiki.multitheftauto.com/wiki/Lua_compilation_API API]) available in [https://wiki.multitheftauto.com/wiki/Meta.xml meta.xml], along with configuring MTA's built-in AC by toggling SD (Special detections), see: [https://wiki.multitheftauto.com/wiki/Anti-cheat_guide Anti-cheat guide].

<syntaxhighlight lang="xml">
<script src="shared.lua" type="shared" cache="false"/> 
<script src="client.lua" type="client" cache="false"/> 
</syntaxhighlight>

* ''Slightly harder'' '''but not impossible''' for some to obtain client code, yet does good job at keeping '''most''' people away from inspecting your .lua files - those looking for possible logic flaws (bugs) or missing/incorrect security based checks.
* Can be used on both '''client''' and '''shared''' script type (has no effect on server-sided Lua).
* It doesn't remove Lua files which were previously downloaded.

==Detecting and dealing with backdoors and cheats==
'''To ensure minimum (or no) damage resulting from Lua scripts:'''
* Keep your server up-to-date, you can [https://nightly.multitheftauto.com/ download latest server builds from MTA:SA nightly site.] Information on specific builds can be [https://buildinfo.multitheftauto.com/ found here.]
* Keep your resources up-to-date, you can [https://github.com/multitheftauto/mtasa-resources download latest (default) resources from GitHub repository.] Those often contain latest security fixes, which could mean difference between having your server resist from attack or not.
* Make sure to properly configure [https://wiki.multitheftauto.com/wiki/Access%20Control%20List ACL (Access Control List)] - which will block resources from using certain, potentially dangerous functions.
* Zero-trust with giving away admin rights for resources (including maps) coming from unknown sources.
* Before running any resource you don't trust, analyze:
** [https://wiki.multitheftauto.com/wiki/Meta.xml meta.xml] of it, for possible hidden scripts lurking beneath other file extensions.
** It's source code, for malicious logic.
* Do not run/keep using compiled resources (scripts) of which legitimacy you aren't sure.

'''To ensure minimum damage when a cheater connects to your server:'''
* When making scripts, remember to never trust data coming from a client.
* While reviewing scripts for possible security holes. Look at any data coming from the client that is being trusted.
* Any kind of data could be sent, hence server scripts which communicate with client by receiving data sent by players should validate it, before further use in latter parts of code. Mostly, it will be done either by [[setElementData]] or [[triggerServerEvent]].
* You shouldn't rely only on player [https://wiki.multitheftauto.com/wiki/Serial serial], when it comes to processing crucial operations (auto-login/admin actions). '''Serials aren't guaranted to be unique or non-fakable'''. This is why you should '''put it behind''' account system, as '''important authentication factor''' (e.g: '''login & password''').
* Server-side logic '''can not be bypassed''' or '''tampered''' with (unless server is breached or when there is a bug in code, but that's whole different scenario) - '''use it to your advantage'''. In majority of cases, you will be able to perform security validations with no participation of client-side.
* Using concept of '''''“All parameters including source can be faked and should not be trusted. Global variable client can be trusted.”''''' - gives you reliable assurance that player to which you refer (via '''client''') '''is''' in fact, '''the one which really called event'''. This approach will protect you from situations where cheater can call & process for instance: admin events (e.g kick/ban player) by passing the actual admin ('''2nd''' argument in '''[[triggerServerEvent]]'''), or trigger events for other players (as if they were the ones who called them, but in reality it was forcefully done by cheater) - as a consequence of using wrong variable. To make sure you fully understood it, take a look at examples below:

<syntaxhighlight lang="lua">
--[[
DON'T EVER DO THAT - THAT IS COMPLETELY WRONG AND INSECURE
THE ISSUE: BY USING 'source' IN hasObjectPermissionTo YOU ARE LEAVING DOOR STRAIGHT OPEN FOR CHEATERS
]]

function onServerWrongAdminEvent(playerToBan)
if (not client) then -- 'client' points to the player who triggered the event, and should be used as security measure (in order to prevent player faking)
return false -- if this variable doesn't exists at the moment (for unknown reason, or it was the server who triggered this event), stop code execution
end

local defaultPermission = false -- do not allow action by default, see (defaultPermission): https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo
local canAdminBanPlayer = hasObjectPermissionTo(source, "function.banPlayer", defaultPermission) -- the vulnerability lies here...

if (not canAdminBanPlayer) then -- if player doesn't have permissions
return false -- don't do it
end

local validElement = isElement(playerToBan) -- check whether argument passed from client is an element

if (not validElement) then -- it is not
return false -- stop code processing
end

local elementType = getElementType(playerToBan) -- it's an element, so get it's type
local playerType = (elementType == "player") -- make sure that it's a player

if (not playerType) then -- it's not a player
return false -- stop here
end

-- banPlayer(...) -- do what needs to be done
end
addEvent("onServerWrongAdminEvent", true)
addEventHandler("onServerWrongAdminEvent", root, onServerWrongAdminEvent)

--[[
onServerCorrectAdminEvent IS PERFECTLY SECURED, AS IT SHOULD BE
NO ISSUE HERE: WE'VE USED 'client' IN hasObjectPermissionTo WHICH MAKES IT SAFE FROM FAKING PLAYER WHO CALLED EVENT
]]

function onServerCorrectAdminEvent(playerToBan)
if (not client) then -- 'client' points to the player who triggered the event, and should be used as security measure (in order to prevent player faking)
return false -- if this variable doesn't exists at the moment (for unknown reason, or it was the server who triggered this event), stop code execution
end

local defaultPermission = false -- do not allow action by default, see (defaultPermission): https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo
local canAdminBanPlayer = hasObjectPermissionTo(client, "function.banPlayer", defaultPermission) -- is player allowed to do that?

if (not canAdminBanPlayer) then -- if player doesn't have permissions
return false -- don't do it
end

local validElement = isElement(playerToBan) -- check whether argument passed from client is an element

if (not validElement) then -- it is not
return false -- stop code processing
end

local elementType = getElementType(playerToBan) -- it's an element, so get it's type
local playerType = (elementType == "player") -- make sure that it's a player

if (not playerType) then -- it's not a player
return false -- stop here
end

-- banPlayer(...) -- do what needs to be done
end
addEvent("onServerCorrectAdminEvent", true)
addEventHandler("onServerCorrectAdminEvent", root, onServerCorrectAdminEvent)
</syntaxhighlight>

==Securing setElementData==

* You should refrain from using [[element data]] everywhere, it should be only used when really necessary. It is advised to replace it with [[triggerClientEvent]] instead.
* If you still insist on using it, it is recommended to set '''4th''' argument in [[setElementData]] to '''false''' (disabling sync for this, certain data) and use subscriber mode - [[addElementDataSubscriber]], for both security & performance reasons described in [https://wiki.multitheftauto.com/wiki/Script_security#Securing_triggerServerEvent event section.]
{{Important Note|Disabling sync however, doesn't fully protect data key. It would be still vulnerable by default, but in this case you are not leaving it in plain sight. Using [[getAllElementData]] or digging in RAM wouldn't expose it, since it won't be synced to client in first place. Therefore, it needs to be added to anti-cheat as well.}}
* All parameters including '''source''' can be faked and should not be trusted.
* Global variable '''client''' can be trusted.

----------
<section name="Server" class="server" show="true">
Example of basic element data anti-cheat.
<syntaxhighlight lang="lua">
local function reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue) -- helper function to log and revert changes
local logClient = inspect(clientElement) -- in-depth view of player which forced element data sync
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = tostring(sourceElement) -- element which received data
local logOldValue = tostring(oldValue) -- old value
local logNewValue = tostring(newValue) -- new value
local logText = -- fill our report with data
"=======================================\n"..
"Detected element data abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Data key: "..dataKey.."\n"..
"Old data value: "..logOldValue.."\n"..
"New data value: "..logNewValue.."\n"..
"======================================="

local logVisibleTo = root -- specify who will see this log in console, in this case each player connected to server
local hadData = (oldValue ~= nil) -- check if element had such data before

if (hadData) then -- if element had such data before
setElementData(sourceElement, dataKey, oldValue, true) -- revert changes, it will call onElementDataChange event, but will fail (stop) on first condition - because server (not client) forced change
else
removeElementData(sourceElement, dataKey) -- remove it completely
end

outputConsole(logText, logVisibleTo) -- print it to console

return true -- all success
end

function onElementDataChangeBasicAC(dataKey, oldValue, newValue) -- the heart of our anti-cheat, which does all the magic security measurements
if (not client) then -- check if data is coming from client
return false -- if it's not, do not go further
end

local checkSpecialThing = (dataKey == "special_thing") -- compare whether dataKey matches "special_thing"
local checkFlagWaving = (dataKey == "flag_waving") -- compare whether dataKey matches "flag_waving"

if (checkSpecialThing) then -- if it does, do our security checks
local invalidElement = (client ~= source) -- verify whether source element is different from player which changed data

if (invalidElement) then -- if it's so
reportAndRevertDataChange(client, source, dataKey, oldValue, newValue) -- revert data change, because "special_thing" can only be set for player himself
end
end

if (checkFlagWaving) then -- if it does, do our security checks
local playerVehicle = getPedOccupiedVehicle(client) -- get player's current vehicle
local invalidVehicle = (playerVehicle ~= source) -- verify whether source element is different from player's vehicle

if (invalidVehicle) then -- if it's so
reportAndRevertDataChange(client, source, dataKey, oldValue, newValue) -- revert data change, because "flag_waving" can only be set for player's own vehicle
end
end
end
addEventHandler("onElementDataChange", root, onElementDataChangeBasicAC)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
Example of advanced element data anti-cheat.
<syntaxhighlight lang="lua">
--[[
For maximum security set punishPlayerOnDetect, punishmentBan, allowOnlyProtectedKeys to true (as per default configuration)
If allowOnlyProtectedKeys is enabled, do not forget to add every client-side element data key to protectedKeys table - otherwise you will face false-positives

Anti-cheat (handleDataChange) table structure and it's options:

["keyName"] = { -- name of key which would be protected
onlyForPlayerHimself = true, -- enabling this (true) will make sure that this element data key can only be set on player who synced it (ignores onlyForOwnPlayerVeh and allowForElements), use false/nil to disable this
onlyForOwnPlayerVeh = false, -- enabling this (true) will make sure that this element data key can only be set on player's current vehicle who synced it (ignores allowForElements), use false/nil to disable this
allowForElements = { -- restrict this key for certain element type(s), set to false/nil or leave it empty to not check this (full list of element types: https://wiki.multitheftauto.com/wiki/GetElementsByType)
["player"] = true,
["ped"] = true,
["vehicle"] = true,
["object"] = true,
},
allowedDataTypes = { -- restrict this key for certain value type(s), set to false/nil or leave it empty to not check this
["string"] = true,
["number"] = true,
["table"] = true,
["boolean"] = true,
["nil"] = true,
},
allowedStringLength = {1, 32}, -- if value is a string, then it's length must be in between (min-max), set it to false/nil to not check string length - do note that allowedDataTypes must contain ["string"] = true
allowedTableLength = {1, 64}, -- if value is a table, then it's length must be in between (min-max), set it to false/nil to not check table length - do note that allowedDataTypes must contain ["table"] = true
allowedNumberRange = {1, 128}, -- if value is a number, then it must be in between (min-max), set it to false/nil to not check number range - do note that allowedDataTypes must contain ["number"] = true
}
]]

local punishPlayerOnDetect = true -- should player be punished upon detection (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Altering element data" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local allowOnlyProtectedKeys = true -- disallow (remove by using removeElementData) every element data besides those given in protectedKeys table; in case someone wanted to flood server with garbage keys, which would be kept in memory until server restart or manual remove - setElementData(source, key, nil) won't remove it; it has to be removeElementData
local debugLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugR = 255 -- debug message - red color
local debugG = 127 -- debug message - green color
local debugB = 0 -- debug message - blue color
local protectedKeys = {
["vehicleNumber"] = { -- we want vehicleNumber to be set only on vehicles, with stricte numbers in range of 1-100
allowForElements = {
["vehicle"] = true,
},
allowedDataTypes = {
["number"] = true,
},
allowedNumberRange = {1, 100},
},
["personalVehData"] = { -- we want be able to set personalVehData only on current vehicle, also it should be a string with length between 1-24
onlyForOwnPlayerVeh = true,
allowedDataTypes = {
["string"] = true,
},
allowedStringLength = {1, 24},
},
-- perform security checks on keys stored in this table, in a convenient way
}

local function reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- helper function to log and revert changes
local logClient = inspect(clientElement) -- in-depth view of player which forced element data sync
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = inspect(sourceElement) -- in-depth view of element which received data
local logOldValue = inspect(oldValue) -- in-depth view of old value
local logNewValue = inspect(newValue) -- in-depth view of new value
local logText = -- fill our report with data
"*\n"..
"Detected element data abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Data key: "..dataKey.."\n"..
"Old data value: "..logOldValue.."\n"..
"New data value: "..logNewValue.."\n"..
"Fail reason: "..failReason.."\n"..
"*"

outputDebugString(logText, debugLevel, debugR, debugG, debugB) -- print it to debug

if (forceRemove) then -- we don't want this element data key to exist at all
removeElementData(sourceElement, dataKey) -- remove it

return true -- return success and stop here, we don't need further checks
end

setElementData(sourceElement, dataKey, oldValue, true) -- revert changes, it will call onElementDataChange event, but will fail (stop) on first condition - because server (not client) forced change

return true -- return success
end

local function handleDataChange(clientElement, sourceElement, dataKey, oldValue, newValue) -- the heart of our anti-cheat, which does all the magic security measurements, returns true if there was no altering from client (based on data from protectedKeys), false otherwise
local protectedKey = protectedKeys[dataKey] -- look up whether key changed is stored in protectedKeys table

if (not protectedKey) then -- if it's not

if (allowOnlyProtectedKeys) then -- if we don't want garbage keys
local failReason = "Key isn't present in protectedKeys" -- reason shown in report
local forceRemove = true -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end

return true -- this key isn't protected, let it through
end

local onlyForPlayerHimself = protectedKey.onlyForPlayerHimself -- if key has "self-set" lock
local onlyForOwnPlayerVeh = protectedKey.onlyForOwnPlayerVeh -- if key has "self-vehicle" lock
local allowForElements = protectedKey.allowForElements -- if key has element type check
local allowedDataTypes = protectedKey.allowedDataTypes -- if key has allowed data type check

if (onlyForPlayerHimself) then -- if "self-set" lock is active
local matchingElement = (clientElement == sourceElement) -- verify whether player who set data is equal to element which received data

if (not matchingElement) then -- if it's not matching
local failReason = "Can only set on player himself" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (onlyForOwnPlayerVeh) then -- if "self-vehicle" lock is active
local playerVehicle = getPedOccupiedVehicle(clientElement) -- get current vehicle of player which set data
local matchingVehicle = (playerVehicle == sourceElement) -- check whether it matches the one which received data

if (not matchingVehicle) then -- if it doesn't match
local failReason = "Can only set on player's own vehicle" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowForElements) then -- check if it's one of them
local elementType = getElementType(sourceElement) -- get type of element whose data changed
local matchingElementType = allowForElements[elementType] -- verify whether it's allowed

if (not matchingElementType) then -- this isn't matching
local failReason = "Invalid element type" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedDataTypes) then -- if there's allowed data types
local valueType = type(newValue) -- get data type of value
local matchingType = allowedDataTypes[valueType] -- check if it's one of allowed

if (not matchingType) then -- if it's not then
local failReason = "Invalid data type" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end

local allowedStringLength = protectedKey.allowedStringLength -- if key has specified string length check
local dataString = (valueType == "string") -- make sure it's a string

if (allowedStringLength and dataString) then -- if we should check string length
local minLength = allowedStringLength[1] -- retrieve min length
local maxLength = allowedStringLength[2] -- retrieve max length
local stringLength = utf8.len(newValue) -- get length of data string
local matchingLength = (stringLength >= minLength) and (stringLength <= maxLength) -- compare whether value fits in between

if (not matchingLength) then -- if it doesn't
local failReason = "Invalid string length (must be between "..minLength.."-"..maxLength..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedTableLength = protectedKey.allowedTableLength -- if key has table length check
local dataTable = (valueType == "table") -- make sure it's a table

if (allowedTableLength and dataTable) then -- if we should check table length
local minLength = allowedTableLength[1] -- retrieve min length
local maxLength = allowedTableLength[2] -- retrieve max length
local minLengthAchieved = false -- variable which checks 'does minimum length was achieved'
local maxLengthExceeded = false -- variable which checks 'does length has exceeds more than allowed maximum'
local tableLength = 0 -- store initial table length

for _, _ in pairs(newValue) do -- loop through whole table
tableLength = (tableLength + 1) -- add + 1 on each table entry
minLengthAchieved = (tableLength >= minLength) -- is length bigger or at very minimum we require
maxLengthExceeded = (tableLength > maxLength) -- does table exceeded more than max length?

if (maxLengthExceeded) then -- it is bigger than it should be
break -- break the loop (due of condition above being worthy, it makes no point to count further and waste CPU, on a table which potentially could have huge amount of entries)
end
end

local matchingLength = (minLengthAchieved and not maxLengthExceeded) -- check if min length has been achieved, and make sure that it doesn't go beyond max length

if (not matchingLength) then -- this table doesn't match requirements
local failReason = "Invalid table length (must be between "..minLength.."-"..maxLength..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedNumberRange = protectedKey.allowedNumberRange -- if key has allowed number range check
local dataNumber = (valueType == "number") -- make sure it's a number

if (allowedNumberRange and dataNumber) then -- if we should check number range
local minRange = allowedNumberRange[1] -- retrieve min number range
local maxRange = allowedNumberRange[2] -- retrieve max number range
local matchingRange = (newValue >= minRange) and (newValue <= maxRange) -- compare whether value fits in between

if (not matchingRange) then -- if it doesn't
local failReason = "Invalid number range (must be between "..minRange.."-"..maxRange..")" -- reason shown in report
local forceRemove = false -- should key be completely removed

reportAndRevertDataChange(clientElement, sourceElement, dataKey, oldValue, newValue, failReason, forceRemove) -- report accident, and handle (or not) this player

return false -- return failure
end
end
end

return true -- security checks passed, we are all clear with this data key
end

function onElementDataChangeAdvancedAC(dataKey, oldValue, newValue) -- this event makes use of handleDataChange, the code was split for better readability
if (not client) then -- check if data is coming from client
return false -- if it's not, do not continue
end

local approvedChange = handleDataChange(client, source, dataKey, oldValue, newValue) -- run our security checks

if (approvedChange) then -- it's all cool and good
return false -- we don't need further action
end

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(client, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(client, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onElementDataChange", root, onElementDataChangeAdvancedAC)
</syntaxhighlight>
</section>

==Securing triggerServerEvent==

* All parameters including '''source''' can be faked and should not be trusted.
* Global variable '''client''' can be trusted.
* '''Admin''' styled '''events''' should be verifying player (client) '''ACL rights''', either by [https://wiki.multitheftauto.com/wiki/IsObjectInACLGroup isObjectInACLGroup] or [https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo hasObjectPermissionTo].
* Do '''not''' use the same name for your custom event as MTA native server events (which aren't remotely triggerable by default), e.g: '''onPlayerLogin'''; doing so would open door for cheaters manipulations.
* Be aware to which players event is sent via [[triggerClientEvent]]. For both security & performance reasons, admin like events should be received by admins only (to prevent confidential data being accessed), in the same time you shouldn't send each event to everyone on server (e.g: login success event which hides login panel for certain player). [[triggerClientEvent]] allows you to specify the event receiver as first (optional) argument. It defaults to [[root]], meaning if you don't specify it, it will be sent to everyone connected to server - even those who are still downloading server cache (which results in ''Server triggered clientside event eventName, but event is not added clientside.''). You can either pass player element or table with receivers:
<syntaxhighlight lang="lua">
local playersToReceiveEvent = {player1, player2, player3} -- each playerX is player element

triggerClientEvent(playersToReceiveEvent, ...) -- do not forget to fill the latter part of arguments
</syntaxhighlight>

----------
<section name="Server" class="server" show="true">
Example of anti-cheat function designed for events, used for data validation for both normal, and admin events which are called from client-side.
<syntaxhighlight lang="lua">
--[[
For maximum security set punishPlayerOnDetect, punishmentBan to true (as per default configuration)

Anti-cheat (processServerEventData) table structure and it's options:

checkACLGroup = { -- check whether player who called event belongs to at least one group below, set to false/nil to not check this
"Admin",
},
checkPermissions = { -- check whether player who called event has permission to at least one thing below, set to false/nil to not check this
"function.kickPlayer",
},
checkEventData = {
{
debugData = "source", -- optional details for report shown in debug message
eventData = source, -- data we want to verify
equalTo = client, -- compare whether eventData == equalTo
allowedElements = { -- restrict eventData to be certain element type(s), set to false/nil or leave it empty to not check this (full list of element types: https://wiki.multitheftauto.com/wiki/GetElementsByType)
["player"] = true,
["ped"] = true,
["vehicle"] = true,
["object"] = true,
},
allowedDataTypes = { -- restrict eventData to be certain value type(s), set to false/nil or leave it empty to not check this
["string"] = true,
["number"] = true,
["table"] = true,
["boolean"] = true,
["nil"] = true,
},
allowedStringLength = {1, 32}, -- if eventData is a string, then it's length must be in between (min-max), set it to false/nil to not check string length - do note that allowedDataTypes must contain ["string"] = true
allowedTableLength = {1, 64}, -- if eventData is a table, then it's length must be in between (min-max), set it to false/nil to not check table length - do note that allowedDataTypes must contain ["table"] = true
allowedNumberRange = {1, 128}, -- if eventData is a number, then it must be in between (min-max), set it to false/nil to not check number range - do note that allowedDataTypes must contain ["number"] = true
},
},
]]

local punishPlayerOnDetect = true -- should player be punished upon detection (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Altering server event data" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugR = 255 -- debug message - red color
local debugG = 127 -- debug message - green color
local debugB = 0 -- debug message - blue color

function processServerEventData(clientElement, sourceElement, serverEvent, securityChecks) -- the heart of our anti-cheat, which does all the magic security measurements, returns true if there was no altering from client (based on data from securityChecks), false otherwise
if (not securityChecks) then -- if we haven't passed any security checks
return true -- nothing to check, let code go further
end

if (not clientElement) then -- if client variable isn't available for some reason (although it should never happen)
local failReason = "Client variable not present" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local checkACLGroup = securityChecks.checkACLGroup -- if there's any ACL groups to check
local checkPermissions = securityChecks.checkPermissions -- if there's any permissions to check
local checkEventData = securityChecks.checkEventData -- if there's any data checks

if (checkACLGroup) then -- let's check player ACL groups
local playerAccount = getPlayerAccount(clientElement) -- get current account of player
local guestAccount = isGuestAccount(playerAccount) -- if account is guest (meaning player is not logged in)

if (guestAccount) then -- it's the case
local failReason = "Can't retrieve player login - guest account" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local accountName = getAccountName(playerAccount) -- get name of player's current account
local aclString = "user."..accountName -- format it for further use in isObjectInACLGroup function

for groupID = 1, #checkACLGroup do -- iterate over table of given groups
local groupName = checkACLGroup[groupID] -- get each group name
local aclGroup = aclGetGroup(groupName) -- check if such group exists

if (not aclGroup) then -- it doesn't
local failReason = "ACL group '"..groupName.."' is missing" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local playerInACLGroup = isObjectInACLGroup(aclString, aclGroup) -- check if player belong to the group

if (playerInACLGroup) then -- yep, it's the case
return true -- so it's a success
end
end

local failReason = "Player doesn't belong to any given ACL group" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

if (checkPermissions) then -- check if player has at least one desired permission
local allowedByDefault = false -- does he have access by default

for permissionID = 1, #checkPermissions do -- iterate over all permissions
local permissionName = checkPermissions[permissionID] -- get permission name
local hasPermission = hasObjectPermissionTo(clientElement, permissionName, allowedByDefault) -- check whether player is allowed to perform certain action

if (hasPermission) then -- if player has access
return true -- one is available (and enough), server won't bother to check others (as return keywords also breaks loop)
end
end

local failReason = "Not enough permissions" -- reason shown in report
local skipPunishment = true -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

if (checkEventData) then -- if there is some data to verify

for dataID = 1, #checkEventData do -- iterate over each of data
local dataToCheck = checkEventData[dataID] -- get each data set
local eventData = dataToCheck.eventData -- this is the one we'll be verifying
local equalTo = dataToCheck.equalTo -- we want to compare whether eventData == equalTo
local allowedElements = dataToCheck.allowedElements -- check whether is element, and whether belongs to certain element types
local allowedDataTypes = dataToCheck.allowedDataTypes -- do we restrict data to be certain type?
local debugData = dataToCheck.debugData -- additional helper data
local debugText = debugData and " ("..debugData..")" or "" -- if it's present, format it nicely

if (equalTo) then -- equal check exists
local matchingData = (eventData == equalTo) -- compare whether those two values are equal

if (not matchingData) then -- they aren't
local failReason = "Data isn't equal @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedElements) then -- we do check whether is an element, and belongs to at least one given in the list
local validElement = isElement(eventData) -- check if it's actual element

if (not validElement) then -- it's not
local failReason = "Data isn't element @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local elementType = getElementType(eventData) -- it's element, so we want to know it's type
local matchingElementType = allowedElements[elementType] -- verify whether it's allowed

if (not matchingElementType) then -- it's not allowed
local failReason = "Invalid element type @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

if (allowedDataTypes) then -- let's check allowed data types
local dataType = type(eventData) -- get data type
local matchingType = allowedDataTypes[dataType] -- verify whether it's allowed

if (not matchingType) then -- it isn't
local failReason = "Invalid data type @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end

local allowedStringLength = dataToCheck.allowedStringLength -- if data has string length check
local dataString = (dataType == "string") -- make sure it's a string

if (allowedStringLength and dataString) then -- if we should check string length
local minLength = allowedStringLength[1] -- retrieve min length
local maxLength = allowedStringLength[2] -- retrieve max length
local stringLength = utf8.len(eventData) -- get length of data string
local matchingLength = (stringLength >= minLength) and (stringLength <= maxLength) -- compare whether value fits in between

if (not matchingLength) then -- if it doesn't
local failReason = "Invalid string length (must be between "..minLength.."-"..maxLength..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedTableLength = dataToCheck.allowedTableLength -- if data has table length check
local dataTable = (dataType == "table") -- make sure it's a table

if (allowedTableLength and dataTable) then -- if we should check table length
local minLength = allowedTableLength[1] -- retrieve min length
local maxLength = allowedTableLength[2] -- retrieve max length
local minLengthAchieved = false -- variable which checks 'does minimum length was achieved'
local maxLengthExceeded = false -- variable which checks 'does length has exceeds more than allowed maximum'
local tableLength = 0 -- store initial table length

for _, _ in pairs(eventData) do -- loop through whole table
tableLength = (tableLength + 1) -- add + 1 on each table entry
minLengthAchieved = (tableLength >= minLength) -- is length bigger or at very minimum we require
maxLengthExceeded = (tableLength > maxLength) -- does table exceeded more than max length?

if (maxLengthExceeded) then -- it is bigger than it should be
break -- break the loop (due of condition above being worthy, it makes no point to count further and waste CPU, on a table which potentially could have huge amount of entries)
end
end

local matchingLength = (minLengthAchieved and not maxLengthExceeded) -- check if min length has been achieved, and make sure that it doesn't go beyond max length

if (not matchingLength) then -- this table doesn't match requirements
local failReason = "Invalid table length (must be between "..minLength.."-"..maxLength..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end

local allowedNumberRange = dataToCheck.allowedNumberRange -- if data has number range check
local dataNumber = (dataType == "number") -- make sure it's a number

if (allowedNumberRange and dataNumber) then -- if we should check number range
local minRange = allowedNumberRange[1] -- retrieve min number range
local maxRange = allowedNumberRange[2] -- retrieve max number range
local matchingRange = (eventData >= minRange) and (eventData <= maxRange) -- compare whether value fits in between

if (not matchingRange) then -- if it doesn't
local failReason = "Invalid number range (must be between "..minRange.."-"..maxRange..") @ argument "..dataID..debugText -- reason shown in report
local skipPunishment = false -- should server skip punishment

reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- report accident, and handle (or not) this player

return false -- return failure
end
end
end
end
end

return true -- security checks passed, we are all clear with this event call
end

function reportAndHandleEventAbnormality(clientElement, sourceElement, serverEvent, failReason, skipPunishment) -- helper function to log and handle accidents
local logClient = inspect(clientElement) -- in-depth view player which called event
local logSerial = getPlayerSerial(clientElement) or "N/A" -- client serial, or "N/A" if not possible, for some reason
local logSource = inspect(sourceElement) -- in-depth view of source element
local logText = -- fill our report with data
"*\n"..
"Detected event abnormality:\n"..
"Client: "..logClient.."\n"..
"Client serial: "..logSerial.."\n"..
"Source: "..logSource.."\n"..
"Event: "..serverEvent.."\n"..
"Reason: "..failReason.."\n"..
"*"

outputDebugString(logText, debugLevel, debugR, debugG, debugB) -- print it to debug

if (not punishPlayerOnDetect or skipPunishment) then -- we don't want to punish player for some reason
return true -- stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(clientElement, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(clientElement, punishedBy, punishmentReason) -- simply kick player out of server
end

return true -- all done, report success
end

function onServerEvent(clientData)
--[[
Assume this server event (function) is called in such way:

local dataToPass = 10

triggerServerEvent("onServerEvent", localPlayer, dataToPass)
]]

local shouldProcessServerCode = processServerEventData(
client, -- client element - responsible for calling event
source, -- source element - passed in triggerServerEvent (as 2nd argument)
eventName, -- name of event - in this case 'onServerEvent'
{
checkEventData = { -- we want to verify everything what comes from client
{
eventData = source, -- first to check, source variable
equalTo = client, -- we want to check whether it matches player who called event
debugData = "source", -- helper details which would be shown in report
},
{
eventData = clientData, -- let's check the data which client sent to us
allowedDataTypes = {
["number"] = true, -- we want it to be only number
},
allowedNumberRange = {1, 100}, -- in range of 1 to 100
debugData = "clientData", -- if something goes wrong, let server know where (it will appear in debug report)
},
},
}
)

if (not shouldProcessServerCode) then -- something isn't right, no green light for processing code behind this scope
return false -- stop code execution
end

-- do code as usual
end
addEvent("onServerEvent", true)
addEventHandler("onServerEvent", root, onServerEvent)

function onServerAdminEvent(playerToBan)
--[[
Assume this server admin event (function) is called in such way:

local playerToBan = getPlayerFromName("playerToBan")

triggerServerEvent("onServerAdminEvent", localPlayer, playerToBan)
]]

local shouldProcessServerCode = processServerEventData(
client, -- client element - responsible for calling event
source, -- source element - passed in triggerServerEvent (as 2nd argument)
eventName, -- name of event - in this case 'onServerAdminEvent'
{
checkACLGroup = { -- we need to check whether player who called event belongs to ACL groups
"Admin", -- in this case admin group
},
checkEventData = { -- we want to verify everything what comes from client
{
eventData = source, -- first to check, source variable
equalTo = client, -- we want to check whether it matches player who called event
debugData = "source", -- helper details which would be shown in report
},
{
eventData = playerToBan, -- let's check the data which client sent to us
allowedDataTypes = {
["player"] = true, -- we want it to be player
},
debugData = "playerToBan", -- if something goes wrong, let server know where (it will appear in debug report)
},
},
}
)

if (not shouldProcessServerCode) then -- something isn't right, no green light for processing code behind this scope
return false -- stop code execution
end

-- do code as usual
end
addEvent("onServerAdminEvent", true)
addEventHandler("onServerAdminEvent", root, onServerAdminEvent)
</syntaxhighlight>
</section>

==Securing server-only events==
* It is very important to '''disable remote triggering''' ability in [https://wiki.multitheftauto.com/wiki/AddEvent addEvent], to prevent calling server-side only events from client-side.
* '''Admin''' styled '''events''' should be verifying player '''ACL rights''', either by [https://wiki.multitheftauto.com/wiki/IsObjectInACLGroup isObjectInACLGroup] or [https://wiki.multitheftauto.com/wiki/HasObjectPermissionTo hasObjectPermissionTo].

----------
<section name="Server" class="server" show="true">
This example shows how you should make event server-side only.
<syntaxhighlight lang="lua">
function onServerSideOnlyEvent()
-- do some server-side stuff
end
addEvent("onServerSideOnlyEvent", false) -- set second argument (allowRemoteTriger) to false, so it can't be called from client
addEventHandler("onServerSideOnlyEvent", root, onServerSideOnlyEvent) -- associate our event with function onServerSideOnlyEvent
</syntaxhighlight>
</section>

==Securing projectiles & explosions==
This section (and '''code''' is '''work in progress''') - '''use at your own risk'''.

----------
<section name="Server" class="server" show="false">
Projectile ammo tracker:
<syntaxhighlight lang="lua">
local playerProjectileAmmo = {} -- store player-held weapons ammo here
local playerWeaponsToTrack = { -- keep track of ammo for certain player-held weapon types, basically those which create projectile; [weaponID] = weaponSlot
[16] = 8, -- grenade
[17] = 8, -- teargas
[18] = 8, -- molotov
[35] = 7, -- rocket launcher
[36] = 7, -- rocket launcher (heat-seeking)
[39] = 8, -- satchel charge
}

local function updateProjectileAmmoForPlayer(playerElement)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

for weaponID, weaponSlot in pairs(playerWeaponsToTrack) do
local weaponInSlot = getPedWeapon(playerElement, weaponSlot)
local weaponTotalAmmo = getPedTotalAmmo(playerElement, weaponSlot)
local weaponHasAmmo = (weaponTotalAmmo > 0)
local weaponMatching = (weaponInSlot == weaponID)
local updateWeaponAmmo = (weaponMatching and weaponHasAmmo)

if (updateWeaponAmmo) then
local storedProjectileAmmo = playerProjectileAmmo[playerElement]
local newWeaponAmmo = (updateWeaponAmmo and weaponTotalAmmo or nil)

if (not storedProjectileAmmo) then
playerProjectileAmmo[playerElement] = {}
storedProjectileAmmo = playerProjectileAmmo[playerElement]
end

storedProjectileAmmo[weaponID] = newWeaponAmmo
end
end

return true
end

function hasPlayerProjectileAmmo(playerElement, projectileWeapon)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

local projectileData = playerProjectileAmmo[playerElement]
local projectileAmmo = (projectileData and projectileData[projectileWeapon])

return projectileAmmo
end

function decreasePlayerProjectileAmmo(playerElement, projectileWeapon)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerDead = isPedDead(playerElement)

if (playerDead) then
return false
end

local playerProjectileData = playerProjectileAmmo[playerElement]

if (not playerProjectileData) then
return false
end

local projectileWeaponAmmo = playerProjectileData[projectileWeapon]
local tempProjectileAmmo = (projectileWeaponAmmo - 1)
local newProjectileAmmo = (tempProjectileAmmo > 0 and tempProjectileAmmo or nil)

playerProjectileData[projectileWeapon] = newProjectileAmmo

return true
end

function onPlayerWeaponSwitchAntiCheat(previousWeaponID, currentWeaponID)
setTimer(updateProjectileAmmoForPlayer, 50, 1, source)
end
addEventHandler("onPlayerWeaponSwitch", root, onPlayerWeaponSwitchAntiCheat)

function onResourceStartAntiCheat()
local playersTable = getElementsByType("player")

for playerID = 1, #playersTable do
local playerElement = playersTable[playerID]

updateProjectileAmmoForPlayer(playerElement)
end
end
addEventHandler("onResourceStart", resourceRoot, onResourceStartAntiCheat)

function onPlayerWastedQuitAntiCheat()
playerProjectileAmmo[source] = nil
end
addEventHandler("onPlayerWasted", root, onPlayerWastedQuitAntiCheat)
addEventHandler("onPlayerQuit", root, onPlayerWastedQuitAntiCheat)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
Projectile handler:
<syntaxhighlight lang="lua">
local playerCreatedProjectiles = {} -- store count of legitimately created player projectiles; [playerElement] = {[projectileType] = activeProjectiles}
local projectileTypes = {
[16] = { -- Grenade
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[16] = true, -- grenade
},
},
[17] = { -- Teargas
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[17] = true, -- teargas
},
},
[18] = { -- Molotov
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[18] = true, -- molotov
},
},
[19] = { -- Rocket
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileMaxVelocity = 2,
projectileAllowedWeapons = {
[35] = true, -- rocket launcher
},
projectileAllowedVehicles = {
[425] = true, -- hunter
[520] = true, -- hydra
},
},
[20] = { -- Rocket (heat-seeking)
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileMaxVelocity = 2,
projectileAllowedWeapons = {
[36] = true, -- rocket launcher (heat-seeking)
},
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
[21] = { -- Airbomb
projectileAllowed = true,
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
[39] = { -- Satchel charge
projectileAllowed = true,
projectileMaxDistanceFromCreator = 2,
projectileAllowedWeapons = {
[39] = true, -- satchel charge
},
},
[58] = { -- Hydra flare
projectileAllowed = true,
projectileMaxDistanceFromCreator = 5,
projectileAllowedVehicles = {
[520] = true, -- hydra
},
},
}

local reportAbnormality = true -- whether to report about abnormality in debug script - by default
local punishPlayerOnDetect = false -- should player be punished upon detection; true - yes, or false to not do anything (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Projectile/explosion anti-cheat" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugMsgLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugMsgR = 255 -- debug message - red color
local debugMsgG = 127 -- debug message - green color
local debugMsgB = 0 -- debug message - blue color

local function reportProjectileAbnormality(playerElement, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ, detectionCode)
local projectileSyncer = inspect(playerElement)
local projectilePosition = projectileX..", "..projectileY..", "..projectileZ
local projectileZoneName = getZoneName(projectileX, projectileY, projectileZ, false)
local projectileCityName = getZoneName(projectileX, projectileY, projectileZ, true)
local projectileLog =
"* Detected projectile abnormality - "..detectionCode.." *\n"..
"Projectile syncer: "..projectileSyncer.."\n"..
"Projectile type: "..projectileType.."\n"..
"Projectile position: "..projectilePosition.. " ("..projectileZoneName..", "..projectileCityName..")\n"

outputDebugString(projectileLog, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)

return true
end

local function processProjectileChecks(playerElement, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)
local projectileData = projectileTypes[projectileType]
local projectileAllowed = projectileData.projectileAllowed

if (not projectileAllowed) then
return false, "Projectile not allowed"
end

local projectileAllowedWeapons = projectileData.projectileAllowedWeapons

if (projectileAllowedWeapons) then
local playerWeapon = getPedWeapon(playerElement)
local allowedWeapon = projectileAllowedWeapons[playerWeapon]

if (not allowedWeapon) then
return false, "Player is not holding correct weapon"
end

local weaponAmmo = hasPlayerProjectileAmmo(playerElement, playerWeapon)
local playerHasAmmo = (weaponAmmo > 0)

if (not playerHasAmmo) then
return false, "Player doesn't have ammo for weapon"
end

decreasePlayerProjectileAmmo(playerElement, playerWeapon)
end

local playerVehicle = getPedOccupiedVehicle(playerElement)

if (playerVehicle) then
local projectileAllowedVehicles = projectileData.projectileAllowedVehicles

if (projectileAllowedVehicles) then
local vehicleModel = getElementModel(playerVehicle)
local allowedVehicle = projectileAllowedVehicles[vehicleModel]

if (not allowedVehicle) then
return false, "Player is not inside allowed vehicles"
end

local vehicleDriver = getVehicleController(playerVehicle)
local playerDriver = (playerElement == vehicleDriver)

if (not playerDriver) then
return false, "Player is not vehicle driver"
end

return true
end

return false, "Player in vehicle"
end

local projectileMaxDistanceFromCreator = projectileData.projectileMaxDistanceFromCreator

if (projectileMaxDistanceFromCreator) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToProjectile = getDistanceBetweenPoints3D(playerX, playerY, playerZ, projectileX, projectileY, projectileZ)
local matchingProjectileDistance = (distanceToProjectile <= projectileMaxDistanceFromCreator)

if (not matchingProjectileDistance) then
return false, "Projectile distance mismatch"
end
end

local projectileMaxVelocity = projectileData.projectileMaxVelocity

if (projectileMaxVelocity) then
local projectileVelocity = (projectileVX ^ 2 + projectileVY ^ 2 + projectileVZ ^ 2)
local projectileSpeed = math.sqrt(projectileVelocity)
local matchingProjectileVelocity = (projectileSpeed <= projectileMaxVelocity)

if (not matchingProjectileVelocity) then
return false, "Projectile velocity mismatch"
end
end

return true
end

local function trackPlayerProjectile(playerElement, projectileID)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerProjectiles = playerCreatedProjectiles[playerElement]

if (not playerProjectiles) then
playerCreatedProjectiles[playerElement] = {}
playerProjectiles = playerCreatedProjectiles[playerElement]
end

local projectilesByType = playerProjectiles[projectileID] or 0
local newProjectilesCount = (projectilesByType + 1)

playerProjectiles[projectileID] = newProjectilesCount

return true
end

local function getProjectileDetectionOverwrittenBehavior(projectileType)
local projectileData = projectileTypes[projectileType]

if (not projectileData) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local projectileBehaviour = projectileData.projectileOverwriteBehaviour

if (not projectileBehaviour) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local overwriteReport = projectileBehaviour.reportAbnormality
local overwritePunish = projectileBehaviour.punishPlayerOnDetect
local overwriteBan = projectileBehaviour.punishmentBan

return overwriteReport, overwritePunish, overwriteBan
end

function decreasePlayerProjectiles(playerElement, projectileID)
local validElement = isElement(playerElement)

if (not validElement) then
return false
end

local playerProjectiles = playerCreatedProjectiles[playerElement]

if (not playerProjectiles) then
return false, true
end

local projectilesByType = playerProjectiles[projectileID]

if (not projectilesByType) then
return false, true
end

local tempProjectilesCount = (projectilesByType - 1)
local newProjectilesCount = (tempProjectilesCount > 0 and tempProjectilesCount or nil)

playerProjectiles[projectileID] = newProjectilesCount

return true
end

function onPlayerProjectileCreationAntiCheat(projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)
local approvedProjectile, detectionCode = processProjectileChecks(source, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ)

if (approvedProjectile) then
trackPlayerProjectile(source, projectileType)

return true
end

local reportAbnormality, punishPlayerOnDetect, punishmentBan = getProjectileDetectionOverwrittenBehavior(projectileType)

if (reportAbnormality) then
reportProjectileAbnormality(source, projectileType, projectileX, projectileY, projectileZ, projectileForce, projectileTarget, projectileRX, projectileRY, projectileRZ, projectileVX, projectileVY, projectileVZ, detectionCode)
end

cancelEvent()

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(source, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(source, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onPlayerProjectileCreation", root, onPlayerProjectileCreationAntiCheat)

function onPlayerQuitAntiCheat()
playerCreatedProjectiles[source] = nil
end
addEventHandler("onPlayerQuit", root, onPlayerQuitAntiCheat)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
Explosions handler:
<syntaxhighlight lang="lua">
local rocketInstantExplosionDistanceThreshold = 1.55 -- distance below which only explosion will be created (and not rocket projectile, hence not calling onPlayerProjectileCreation); do not change it
local explosionTypes = { -- more specific info on explosion, and whether it is allowed
[0] = { -- Grenade
explosionAllowed = true,
explosionAllowedProjectiles = {
[16] = true, -- grenade
},
},
[1] = { -- Molotov
explosionAllowed = true,
explosionAllowedProjectiles = {
[18] = true, -- molotov
},
},
[2] = { -- Rocket
explosionAllowed = true,
explosionAllowedWeapons = {
[35] = true, -- rocket launcher
[36] = true, -- rocket launcher (heat-seeking)
},
explosionAllowedProjectiles = {
[19] = true, -- rocket
[20] = true, -- rocket (heat-seeking)
},
},
[3] = { -- Rocket weak
explosionAllowed = true,
explosionAllowedProjectiles = {
[19] = true, -- rocket
[20] = true, -- rocket (heat-seeking)
},
},
[4] = { -- Car
explosionAllowed = true,
},
[5] = { -- Car quick
explosionAllowed = true,
},
[6] = { -- Boat
explosionAllowed = true,
},
[7] = { -- Heli
explosionAllowed = true,
},
[8] = { -- Mine
explosionAllowed = true,
},
[9] = { -- Object
explosionAllowed = true,
},
[10] = { -- Tank grenade
explosionAllowed = true,
explosionMaxDistanceFromCreator = 80,
explosionAllowedVehicles = {
[432] = true,
}
},
[11] = { -- Small
explosionAllowed = true,
},
[12] = { -- Tiny
explosionAllowed = true,
},
}

local reportAbnormality = true -- whether to report about abnormality in debug script - by default
local punishPlayerOnDetect = false -- should player be punished upon detection; true - yes, or false to not do anything (make sure that resource which runs this code has admin rights)
local punishmentBan = true -- only relevant if punishPlayerOnDetect is set to true; use true for ban or false for kick
local punishmentReason = "Projectile/explosion anti-cheat" -- only relevant if punishPlayerOnDetect is set to true; reason which would be shown to punished player
local punishedBy = "Console" -- only relevant if punishPlayerOnDetect is set to true; who was responsible for punishing, as well shown to punished player
local banByIP = false -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; banning by IP nowadays is not recommended (...)
local banByUsername = false -- community username - legacy thing, hence is set to false and should stay like that
local banBySerial = true -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; (...) if there is a player serial to use instead
local banTime = 0 -- only relevant if punishPlayerOnDetect and punishmentBan is set to true; time in seconds, 0 for permanent
local debugMsgLevel = 4 -- this debug level allows to hide INFO: prefix, and use custom colors
local debugMsgR = 255 -- debug message - red color
local debugMsgG = 127 -- debug message - green color
local debugMsgB = 0 -- debug message - blue color

local function reportExplosionAbnormality(playerElement, explosionType, explosionX, explosionY, explosionZ, detectionCode)
local explosionSyncer = inspect(playerElement)
local explosionType = explosionType
local explosionPosition = explosionX..", "..explosionY..", "..explosionZ
local explosionZoneName = getZoneName(explosionX, explosionY, explosionZ, false)
local explosionCityName = getZoneName(explosionX, explosionY, explosionZ, true)
local explosionLog =
"* Detected explosion abnormality - "..detectionCode.." *\n"..
"Explosion syncer: "..explosionSyncer.."\n"..
"Explosion type: "..explosionType.."\n"..
"Explosion position: "..explosionPosition.. " ("..explosionZoneName..", "..explosionCityName..")\n"

outputDebugString(explosionLog, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)

return true
end

local function processExplosionChecks(playerElement, explosionType, explosionX, explosionY, explosionZ)
local explosionData = explosionTypes[explosionType]
local explosionAllowed = explosionData.explosionAllowed

if (not explosionAllowed) then
return false, "Explosion type not allowed"
end

local rocketExplosion = (explosionType == 2)

if (rocketExplosion) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToExplosion = getDistanceBetweenPoints3D(playerX, playerY, playerZ, explosionX, explosionY, explosionZ)
local instantExplosion = (distanceToExplosion < rocketInstantExplosionDistanceThreshold)

if (instantExplosion) then
local explosionAllowedWeapons = explosionData.explosionAllowedWeapons
local playerWeapon = getPedWeapon(playerElement)
local allowedWeapon = explosionAllowedWeapons[playerWeapon]

if (not allowedWeapon) then
return false, "Player is not holding rocket launcher"
end

local weaponAmmo = hasPlayerProjectileAmmo(playerElement, playerWeapon)
local playerHasAmmo = (weaponAmmo > 0)

if (not playerHasAmmo) then
return false, "Player doesn't have ammo for rocket launcher"
end

decreasePlayerProjectileAmmo(playerElement, playerWeapon)

return true
end
end

local explosionAllowedProjectiles = explosionData.explosionAllowedProjectiles

if (explosionAllowedProjectiles) then

for projectileID, _ in pairs(explosionAllowedProjectiles) do
local atleastOneProjectile = decreasePlayerProjectiles(playerElement, projectileID)

if (atleastOneProjectile) then
return true
end
end

return false, "Explosion created without respective projectile"
end

local explosionAllowedVehicles = explosionData.explosionAllowedVehicles

if (explosionAllowedVehicles) then
local playerVehicle = getPedOccupiedVehicle(playerElement)

if (not playerVehicle) then
return false, "Player is not in vehicle"
end

local vehicleModel = getElementModel(playerVehicle)
local allowedVehicle = explosionAllowedVehicles[vehicleModel]

if (not allowedVehicle) then
return false, "Player is inside not allowed vehicles"
end

local vehicleDriver = getVehicleController(playerVehicle)
local playerDriver = (playerElement == vehicleDriver)

if (not playerDriver) then
return false, "Player is not vehicle driver"
end
end

local explosionMaxDistanceFromCreator = explosionData.explosionMaxDistanceFromCreator

if (explosionMaxDistanceFromCreator) then
local playerX, playerY, playerZ = getElementPosition(playerElement)
local distanceToExplosion = getDistanceBetweenPoints3D(playerX, playerY, playerZ, explosionX, explosionY, explosionZ)
local matchingExplosionDistance = (distanceToExplosion < explosionMaxDistanceFromCreator)

if (not matchingExplosionDistance) then
return false, "Explosion distance mismatch"
end
end

return true
end

local function getExplosionDetectionOverwrittenBehavior(explosionType)
local explosionData = explosionTypes[explosionType]

if (not explosionData) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local explosionBehaviour = explosionData.explosionOverwriteBehaviour

if (not explosionBehaviour) then
return reportAbnormality, punishPlayerOnDetect, punishmentBan
end

local overwriteReport = explosionBehaviour.reportAbnormality
local overwritePunish = explosionBehaviour.punishPlayerOnDetect
local overwriteBan = explosionBehaviour.punishmentBan

return overwriteReport, overwritePunish, overwriteBan
end

function onExplosionAntiCheat(explosionX, explosionY, explosionZ, explosionType)
local serverSyncExplosion = (source == root)

if (serverSyncExplosion) then
return true
end

local approvedExplosion, detectionCode = processExplosionChecks(source, explosionType, explosionX, explosionY, explosionZ)

if (approvedExplosion) then
return true
end

local reportAbnormality, punishPlayerOnDetect, punishmentBan = getExplosionDetectionOverwrittenBehavior(explosionType)

if (reportAbnormality) then
reportExplosionAbnormality(source, explosionType, explosionX, explosionY, explosionZ, detectionCode)
end

cancelEvent()

if (not punishPlayerOnDetect) then -- we don't want to punish player for some reason
return false -- so stop here
end

if (punishmentBan) then -- if it's ban
banPlayer(source, banByIP, banByUsername, banBySerial, punishedBy, punishmentReason, banTime) -- remove his presence from server
else -- otherwise
kickPlayer(source, punishedBy, punishmentReason) -- simply kick player out of server
end
end
addEventHandler("onExplosion", root, onExplosionAntiCheat)
</syntaxhighlight>
</section>

==Handling non-registered events==

See: [[onPlayerTriggerInvalidEvent]]

==Handling events spam==
See: [[onPlayerTriggerEventThreshold]]

Server Commands

2024-01-13T15:53:26Z

DColeman: Fix typo

This page lists all built in commands that the server can process. All these commands can be entered via the server console or the client console depending upon permissions unless otherwise stated.

==Resource commands==
====check====
:<ins>Server console only</ins>
:Usage: check [ ''all'' | ''<resource-name>'' ]<br>
:Checks which files would be changed with [[Server_Commands#upgrade|upgrade]] command. Does not modify anything.
====info====
:<ins>Server console only</ins>
:Usage: info ''<resource-name>''<br>
:Get info for a resource eg: info admin
====list====
:<ins>Server console only</ins>
:Shows a list of resources
====refresh====
:Refresh resource list to find new resources
====refreshall====
:Refresh resources and restart any changed resources
====restart====
:Usage: restart ''<resource-name>''<br>
:Restarts a running resource eg: restart admin

====start====
:Usage: start ''<resource-name>''<br>
:Start a loaded resource eg: start admin
====stop====
:Usage: stop ''<resource-name>''<br>
:Stop a resource eg: stop admin
====stopall====
:Stop all running resources
====upgrade====
:<ins>Server console only</ins>
:Usage: upgrade [ ''all'' | ''<resource-name>'' ]<br>
:Perform a basic upgrade of all resources. The [[Server_Commands#check|check]] command shows the list of changes this command will make.
====aclrequest====
:Usage: aclrequest [ ''list'' | ''allow'' | ''deny'' ] ''<resource-name>'' [ ''<right>'' | ''all'' ]<br>
:Manage ACL requests from resources implementing <aclrequest> in their [[meta.xml]]
{{New feature/item|3.0156|1.5.5|11851|
====reloadacl====
:Perform a simple ACL reload.}}

==Account commands==
====aexec====
:Usage: aexec ''<nick>'' ''<command>''<br>
:Force a player to execute a command eg: aexec playername say hello
====addaccount====
:Usage: addaccount ''<accountname>'' ''<password>''<br>
:Add an account eg: addaccount accountname password
====chgpass====
:Usage: chgpass ''<accountname>'' ''<password>''<br>
:Change an accounts password eg: chgpass account newpw
====delaccount====
:Usage: delaccount ''<accountname>''<br>
:Delete an account eg: delaccount accountname
====reloadbans====
:Reloads all the bans from ''banlist.xml''.
====authserial====
:Usage: authserial <account-name> [list|removelast|httppass]
:Manage serial authentication for an account.

==Server commands==
====ase====
:<ins>Server console only</ins>
:See the amount of master server list queries
====debugdb====
:Usage: debugdb ''<''0-2''>''<br>
:<ins>Server console only</ins>
:Set logging level for database functions. [0-Off  1-Errors only  2-All]
:By default, logging output is written to the file '''logs/db.log''' unless another file is declared in the [[Mtaserver.conf#dbfile|<dbfile> section of mtaserver.conf]]
====debugjoinflood====
:<ins>Server console only</ins>
:Shows debug information regarding the join flood mitigation feature.
====debuguptime====
:<ins>Server console only</ins>
:Shows how many days the server has been up and running.
====help====
:<ins>Server console only</ins>
:Displays these list of commands
====loadmodule====
:Usage: loadmodule ''<module-filename>''<br>
:Load a module eg: loadmodule ml_sockets.dll

====unloadmodule====
:<ins>Server console only</ins>
:Usage: unloadmodule ''<module-filename>''<br>
:Unload a module eg: unloadmodule ml_sockets.dll
====reloadmodule====
:<ins>Server console only</ins>
:Usage: reloadmodule ''<module-filename>''<br>
:Reload a module eg: reloadmodule ml_sockets.dll
====openports====
:<ins>Server console only</ins>
:Test if server ports are open
====sfakelag====
{{Main|Command fakelag}}
:Usage: sfakelag ''<packet loss>'' ''<extra ping>'' ''<ping variance>'' [''<KBPS limit>'']
:'''Only available if enabled in the [[mtaserver.conf]] file.'''
:Adds artificial packet loss, ping, jitter and bandwidth limits to the server-client connections.
====shutdown====
:Usage: shutdown ''<reason>''<br>
:Shutdown the server eg: shutdown put reason here
====sver====
:Get the server MTA version

==Other commands==
====say====
:Usage: say ''<text>''<br>
:Show a message to all players on the server eg: say hello
====whois====
:Usage: whois ''<nick>''<br>
:Get the IP of a player currently connected (use '''whowas''' for IP/serial/version)
{{Deprecated feature|3.0156|1.5.6|
====whowas====
:Usage: whowas ''<nick>''<br>
:Get IP/Serial/username of a player that was previously connected to the server
}}

====ver====
:Get the MTA version

==Client relevant only==
====chgmypass====
:<ins>Client only</ins>
:Usage: chgmypass ''<oldpass>'' ''<newpass>''<br>
:Change your password eg: chgmypass oldpw newpw
====debugscript====
:<ins>Client only</ins>
:Usage: debugscript ''<''0-3''>''<br>
:Remove (This does not work "Incorrect client type for this command")
====login====
:<ins>Client only</ins>
:Usage: login ''<accountname>'' ''<password>''<br>
:Login to an account eg: login accountname password

====logout====
:<ins>Client only</ins>
:Log out of the current account
====me====
:<ins>Client only</ins>
:Usage: me ''<text>''<br>
:Show a message to all players on the server, with your nick prepended
====msg====
:<ins>Client only</ins>
:Usage: msg ''<nick>'' ''<text>''<br>
:Send a message to a player eg: msg playername hello
====nick====
:<ins>Client only</ins>
:Usage: nick ''<old-nick>'' ''<new-nick>''<br>
:Change your ingame nickname
====teamsay====
:<ins>Client only</ins>
:Usage: teamsay ''<text>''<br>
:Send a message to all players on the same team

[[Category: Support]]

[[hu:Server Commands]]
[[ru:Server Commands]]

GetGuestPlayers

2023-10-05T16:55:31Z

DColeman: Spelling correction. This function cannot return false

{{Useful Function}}
__NOTOC__

==Syntax==
<syntaxhighlight lang="lua">table getGuestPlayers ( )</syntaxhighlight>

===Returns===
Returns all players who are not logged in or an empty table if there are no such players.

==Code==
<section name="Server" class="server" show="true"><syntaxhighlight lang="lua">
function getGuestPlayers ( )
local Guest = { } ;

for _ , players_ in ipairs ( getElementsByType ( "player" ) ) do
local playerAcc = getPlayerAccount ( players_ )

if isGuestAccount ( playerAcc ) then

table.insert ( Guest , players_ )

end
end
return Guest
end
</syntaxhighlight></section>

==Example 1==
This example gets players Guest Account and show msg login or register
<syntaxhighlight lang="lua">

</syntaxhighlight>

==Example 2==
This example gets players Guest Account and kill them
<syntaxhighlight lang="lua">
addCommandHandler ( "getGuestPlayers_" , function ( )

local GuestPlayers = getGuestPlayers ( )

if ( #GuestPlayers ~= 0 ) then

for _ , v in ipairs ( GuestPlayers ) do

outputChatBox ( getPlayerName ( v ) : gsub ( "#%x%x%x%x%x%x", "" ) .. "plz Login or Register" , v , 255 , 255 , 255 , true )

end
end
end
) ;

-- F8 Say : getGuestPlayers_
</syntaxhighlight>

==Example 3==
This example show number players not login or Guest Account
<syntaxhighlight lang="lua">
outputChatBox ( #getGuestPlayers ( ) )

</syntaxhighlight>

Author: Abdul_KariM

==See Also==
{{Useful_Functions}}