Multi Theft Auto: Wiki - User contributions [en]

HasObjectPermissionTo

2025-08-25T11:54:19Z

Srslyyyy:

__NOTOC__
{{Server function}}
This function returns whether or not the given object has access to perform the given action.
{{Note|Only certain action names work. This function seems to return ''nil'' and output a bad argument error when checking if an object has rights for an action which doesn't start with ''function.'', ''command.'' or ''resource.'' keywords.}}

Scripts frequently wish to limit access to features to particular users. The naive way to do this would be to check if the player who is attempting to perform an action is in a particular group (usually the Admin group). The main issue with doing this is that the Admin group is not guaranteed to exist. It also doesn't give the server admin any flexibility. He might want to allow his 'moderators' access to the function you're limiting access to, or he may want it disabled entirely.

This is where using the ACL properly comes in, and luckily this is very easy. It all comes down to using this function. This, somewhat confusingly named function lets you check if an ACL object (a player or a resource) has a particular ACL right. In this case, we just care about players.

So, first of all, think of a name for your 'right'. Let's say we want a private area only certain people can go in, we'll call our right accessPrivateArea. Then, all you need to do is add one 'if' statement to your code:
<syntaxhighlight lang="lua">if hasObjectPermissionTo ( player, "resource.YourResourceName.accessPrivateArea", false ) then
-- Whatever you want to happen if they're allowed in
else
-- Whatever you want to happen if they aren't
end
</syntaxhighlight>

Notice that we've named the ''right'' using ''resource.YourResourceName.accessPrivateArea'' - this is just for neatness, so that the admin knows what resource the right belongs to. It's strongly advised you follow this convention. The ''false'' argument specifies the 'defaultPermission', false indicating that if the user hasn't had the right allowed or dissallowed (i.e. the admin hasn't added it to the config), that it should default to being not allowed.

The only downside of using this method is that the admin has to modify his config. The upsides are that the admin has much more control and your script will work for any server, however the admin has configured it.

==Syntax==
{{New feature/item|3.0162|1.7.0|25445|
'''defaultPermission''' argument now defaults to '''false'''. If third argument is '''nil'''/'''false''' (or not specified), then action (unless explicitly allowed in '''ACL''') won't be processed due to missing rights. May affect the normal operation of existing scripts.
}}
<syntaxhighlight lang="lua">
bool hasObjectPermissionTo ( string / element theObject, string theAction [, bool defaultPermission = true/false ] )
</syntaxhighlight>

{{OOP|This function is also a static function underneath the ACL class.|[[ACL]].hasObjectPermissionTo||}}
===Required Arguments===
*'''theObject:''' The object to test if has permission to. This can be a client element (ie. a player), a resource or a string in the form "user.<name>" or "resource.<name>".
*'''theAction:''' The action to test if the given object has access to. Ie. "function.kickPlayer".

===Optional Arguments===
{{OptionalArg}}
*'''defaultPermission:''' The default permission if none is specified in either of the groups the given object is a member of. If this is left to true, the given object will have permissions to perform the action unless the opposite is explicitly specified in the [[ACL]]. If false, the action will be denied by default unless explicitly approved by the [[Access Control List]].

===Returns===
Returns ''true'' if the given object has permission to perform the given action, ''false'' otherwise. Returns ''nil'' if the function failed because of bad arguments.

==Example==
This example kicks a player if the user using it has access to the kickPlayer function.
<syntaxhighlight lang="lua">
-- Kick command
function onKickCommandHandler ( playerSource, commandName, playerToKick, stringReason )
-- Does the calling user have permission to kick the player? Default
-- to false for safety reasons. We do this so any user can't use us to
-- kick players.
if ( hasObjectPermissionTo ( playerSource, "function.kickPlayer", false ) ) then

-- Do we have permission to kick the player? We do this so we can fail
-- nicely if this resource doesn't have access to call that function.
if ( hasObjectPermissionTo ( resource, "function.kickPlayer", true ) ) then
-- Kick him
kickPlayer ( playerToKick, playerSource, stringReason )
else
-- Resource doesn't have any permissions, sorry
outputChatBox ( "kick: The admin resource is not able to kick players. Please give this resource access to 'function.kickPlayer' in the ACL to use this function.", playerSource )
end
else
-- User doesn't have any permissions
outputChatBox ( "kick: You don't have permissions to use this command.", playerSource )
end
end
addCommandHandler ( "kick", onKickCommandHandler )
</syntaxhighlight>

==See Also==

{{ACL_functions}}
[[zh-cn:hasObjectPermissionTo]]
[[pt-br:hasObjectPermissionTo]]
[[ru:hasObjectPermissionTo]]

Template:Ped move states

2025-08-10T01:55:47Z

Srslyyyy: Adjust to PR #4350 (https://github.com/multitheftauto/mtasa-blue/pull/4350) by FileEX

<div style="border:3px solid red;margin-bottom:3px;padding-left:5px;"><div style="float:right;padding-right:5px;font-weight:bold;"></div>
* '''stand''': The ped is standing still.
* '''walk''': The ped is walking.
* '''powerwalk''': The ped is walking quickly.
* '''jog''': The ped is jogging.
* '''sprint''': The ped is sprinting.
* '''crouch''': The ped is crouching still.
* '''crawl''': The ped is crawling (moving and ducked).
* '''jump''': The ped is jumping into the air.
* '''fall''': The ped is falling to the ground.
* '''climb''': The ped is climbing onto an object.
{{New feature/item|3.0171|1.7.0|25351|'''swim:''' The ped is swimming.}}
{{New feature/item|3.0171|1.7.0|25351|'''walk_to_point:''' The ped is walking to a vehicle door.}}
{{New feature/item|3.0171|1.7.0|25351|'''ascent_jetpack:''' The ped is ascending with jetpack.}}
{{New feature/item|3.0171|1.7.0|25351|'''descent_jetpack:''' The ped is descending with jetpack.}}
{{New feature/item|3.0171|1.7.0|25351|'''jetpack_flying:''' The ped is flying with jetpack.}}
{{New feature/item|3.0171|1.7.0|25351|'''roll:''' The ped is rolling.}}
{{New feature/item|3.0171|1.7.0|25371|'''hanging:''' The ped is hanging onto a wall.}}
</div>

Template:Ped move states

2025-08-10T01:51:59Z

Srslyyyy: Adjust to PR #4316 (https://github.com/multitheftauto/mtasa-blue/pull/4316) by FileEX

SetCameraFieldOfView

2025-07-25T18:27:59Z

Srslyyyy: /* Example */

__NOTOC__
{{client function}}
{{New feature/item|3.0151|1.5.1|7397|This function sets the field of view of the ''dynamic camera'' - this is the field of view of the ''non-fixed camera'' - yes, the camera that the user can control whilst on foot or in a vehicle. The higher the field of view angle, the more you will be able to see to your sides.}}
{{Note|This function omits (but doesn't override) the user game option in '''''Settings -> Video -> FOV'''''}}
{{Note|It doesn't affect the FOV for the following camera modes: 1) Player aiming 2) Vehicle front bumper camera 3) Fixed camera}}
==Syntax==
<syntaxhighlight lang="lua">
bool setCameraFieldOfView ( string cameraMode, float fieldOfView [, bool instant = false ] )
</syntaxhighlight>
{{OOP||Camera.setFieldOfView||getCameraFieldOfView}}

===Required Arguments===
'''Note:''' after 100, some unexpected things may happen to the camera, particularly in vehicles, use carefully!
*'''cameraMode:''' the camera mode to set the field of view of:
** "player": whilst walking/running
** "vehicle": whilst in vehicle
** "vehicle_max": the max the field of view can go to when the vehicle is moving at a high speed (must be higher than "vehicle")
*'''fieldOfView:''' The field of view angle, 0 to 179.

===Optional arguments===
{{OptionalArg}}
{{New feature/item|3.0161|1.6.0|23300|
*'''instant''': If set to ''true'', the value is applied immediately, without delay (does not work with "vehicle_max").
}}

===Returns===
Returns ''true'' if the arguments are valid, ''false'' otherwise.

==Example==
In this example, the field of view for 'player walking/running' camera is set to 20, once resource fully starts.

<syntaxhighlight lang="lua">
local function changeCameraFovOnClientResourceStart()
setCameraFieldOfView("player", 20)
end
addEventHandler("onClientResourceStart", resourceRoot, changeCameraFovOnClientResourceStart)</syntaxhighlight>

==See Also==
{{Client camera functions}}

[[hu:setCameraFieldOfView]]
[[RO:setCameraFieldOfView]]

CreateEffect

2025-07-21T19:58:52Z

Srslyyyy: /* Example */

__NOTOC__
{{Client function}}
{{New items|3.0140|1.4|
Creates an [[Element/Effect|effect]] on specified position.
}}
{{Note|Not all effects support rotation (e.g. the "fire" - effect doesn't).}}
{{Note|All effects have their own duration.}}
==Syntax==
<syntaxhighlight lang="lua">effect createEffect ( string name, float x, float y, float z [, float rX, float rY, float rZ, float drawDistance = 0, bool soundEnable = false ] )</syntaxhighlight>
{{OOP||[[Effect]]}}

===Required Arguments===
*'''name:''' A string contains [[Element/Effect#Effects_list|effect name]].
*'''x:''' A floating point number representing the X coordinate on the map.
*'''y:''' A floating point number representing the Y coordinate on the map.
*'''z:''' A floating point number representing the Z coordinate on the map.

===Optional Arguments===
{{OptionalArg}}
*'''rX:''' A floating point number representing the rotation about the X axis in degrees.
*'''rY:''' A floating point number representing the rotation about the Y axis in degrees.
*'''rZ:''' A floating point number representing the rotation about the Z axis in degrees.
*'''drawDistance:''' A floating point number between 1 and 8191 which represents the draw distance of the effect, or 0 to use the default draw distance.
{{New feature/item|3.0155|1.5.5||
*'''soundEnable:''' to enable the sound of the effect.
}}

=== Returns ===
Returns the [[Element/Effect|effect]] element if creation was successful, ''false'' otherwise.

==Example==
This example allows you to create effect by using 'B' key (use mouse scroll up/down to switch effect).
<syntaxhighlight lang="lua">
local effectSwitchUpKey = "mouse_wheel_up"
local effectSwitchDownKey = "mouse_wheel_down"
local effectCreateKey = "b"

local effectNames = {
"blood_heli", "boat_prop", "camflash", "carwashspray", "cement", "cloudfast", "coke_puff", "coke_trail", "cigarette_smoke",
"explosion_barrel", "explosion_crate", "explosion_door", "exhale", "explosion_fuel_car", "explosion_large", "explosion_medium",
"explosion_molotov", "explosion_small", "explosion_tiny", "extinguisher", "flame", "fire", "fire_med", "fire_large", "flamethrower",
"fire_bike", "fire_car", "gunflash", "gunsmoke", "insects", "heli_dust", "jetpack", "jetthrust", "nitro", "molotov_flame",
"overheat_car", "overheat_car_electric", "prt_blood", "prt_boatsplash", "prt_bubble", "prt_cardebris", "prt_collisionsmoke",
"prt_glass", "prt_gunshell", "prt_sand", "prt_sand2", "prt_smokeII_3_expand", "prt_smoke_huge", "prt_spark", "prt_spark_2",
"prt_splash", "prt_wake", "prt_watersplash", "prt_wheeldirt", "petrolcan", "puke", "riot_smoke", "spraycan", "smoke30lit", "smoke30m",
"smoke50lit", "shootlight", "smoke_flare", "tank_fire", "teargas", "teargasAD", "tree_hit_fir", "tree_hit_palm", "vent", "vent2",
"water_hydrant", "water_ripples", "water_speed", "water_splash", "water_splash_big", "water_splsh_sml", "water_swim", "waterfall_end",
"water_fnt_tme", "water_fountain", "wallbust", "WS_factorysmoke"
}

local effectID = 1
local effectName = effectNames[effectID]
local effectCount = (#effectNames) -- there are 82 effects

outputChatBox("Effect set to: #ffa500"..effectName.."#ffffff (ID: #ffa500"..effectID.."#ffffff)", 255, 255, 255, true)

local function createEffectManually()
local playerX, playerY, playerZ = getElementPosition(localPlayer)
local effectX, effectY, effectZ = playerX, playerY, (playerZ + 2)
local effectRX, effectRY, effectRZ = 0, 0, 0
local effectDrawDistance = 300
local effectSoundEnable = false

outputChatBox("Created effect: #ffa500"..effectName.."#ffffff (ID: #ffa500"..effectID.."#ffffff)", 255, 255, 255, true)
createEffect(effectName, effectX, effectY, effectZ, effectRX, effectRY, effectRZ, effectDrawDistance, effectSoundEnable)
end
bindKey(effectCreateKey, "down", createEffectManually)

local function switchEffect(keyName)
local effectSwitchUp = (keyName == effectSwitchUpKey)
local effectSwitchFactor = (effectSwitchUp and 1 or -1)
local effectSwitchTempID = (effectID + effectSwitchFactor)
local effectSwitchID = (effectSwitchTempID > effectCount and 1 or effectSwitchTempID < 1 and effectCount or effectSwitchTempID)

effectID = effectSwitchID
effectName = effectNames[effectID]

outputChatBox("Effect set to: #ffa500"..effectName.."#ffffff (ID: #ffa500"..effectID.."#ffffff)", 255, 255, 255, true)
end
bindKey(effectSwitchDownKey, "down", switchEffect)
bindKey(effectSwitchUpKey, "down", switchEffect)
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.4.0-9.06892|Added drawDistance argument}}
{{ChangelogItem|1.5.4-9.11631|Added soundEnable argument}}

== See Also ==
{{Client_Effects_functions}}
[[ru:createEffect]]

CreateEffect

2025-07-21T19:57:43Z

Srslyyyy: /* Example */

__NOTOC__
{{Client function}}
{{New items|3.0140|1.4|
Creates an [[Element/Effect|effect]] on specified position.
}}
{{Note|Not all effects support rotation (e.g. the "fire" - effect doesn't).}}
{{Note|All effects have their own duration.}}
==Syntax==
<syntaxhighlight lang="lua">effect createEffect ( string name, float x, float y, float z [, float rX, float rY, float rZ, float drawDistance = 0, bool soundEnable = false ] )</syntaxhighlight>
{{OOP||[[Effect]]}}

===Required Arguments===
*'''name:''' A string contains [[Element/Effect#Effects_list|effect name]].
*'''x:''' A floating point number representing the X coordinate on the map.
*'''y:''' A floating point number representing the Y coordinate on the map.
*'''z:''' A floating point number representing the Z coordinate on the map.

===Optional Arguments===
{{OptionalArg}}
*'''rX:''' A floating point number representing the rotation about the X axis in degrees.
*'''rY:''' A floating point number representing the rotation about the Y axis in degrees.
*'''rZ:''' A floating point number representing the rotation about the Z axis in degrees.
*'''drawDistance:''' A floating point number between 1 and 8191 which represents the draw distance of the effect, or 0 to use the default draw distance.
{{New feature/item|3.0155|1.5.5||
*'''soundEnable:''' to enable the sound of the effect.
}}

=== Returns ===
Returns the [[Element/Effect|effect]] element if creation was successful, ''false'' otherwise.

==Example==
This example allows you to create effect by 'B' key (use mouse scroll up/down to switch effect).
<syntaxhighlight lang="lua">
local effectSwitchUpKey = "mouse_wheel_up"
local effectSwitchDownKey = "mouse_wheel_down"
local effectCreateKey = "b"

local effectNames = {
"blood_heli", "boat_prop", "camflash", "carwashspray", "cement", "cloudfast", "coke_puff", "coke_trail", "cigarette_smoke",
"explosion_barrel", "explosion_crate", "explosion_door", "exhale", "explosion_fuel_car", "explosion_large", "explosion_medium",
"explosion_molotov", "explosion_small", "explosion_tiny", "extinguisher", "flame", "fire", "fire_med", "fire_large", "flamethrower",
"fire_bike", "fire_car", "gunflash", "gunsmoke", "insects", "heli_dust", "jetpack", "jetthrust", "nitro", "molotov_flame",
"overheat_car", "overheat_car_electric", "prt_blood", "prt_boatsplash", "prt_bubble", "prt_cardebris", "prt_collisionsmoke",
"prt_glass", "prt_gunshell", "prt_sand", "prt_sand2", "prt_smokeII_3_expand", "prt_smoke_huge", "prt_spark", "prt_spark_2",
"prt_splash", "prt_wake", "prt_watersplash", "prt_wheeldirt", "petrolcan", "puke", "riot_smoke", "spraycan", "smoke30lit", "smoke30m",
"smoke50lit", "shootlight", "smoke_flare", "tank_fire", "teargas", "teargasAD", "tree_hit_fir", "tree_hit_palm", "vent", "vent2",
"water_hydrant", "water_ripples", "water_speed", "water_splash", "water_splash_big", "water_splsh_sml", "water_swim", "waterfall_end",
"water_fnt_tme", "water_fountain", "wallbust", "WS_factorysmoke"
}

local effectID = 1
local effectName = effectNames[effectID]
local effectCount = (#effectNames) -- there are 82 effects

outputChatBox("Effect set to: #ffa500"..effectName.."#ffffff (ID: #ffa500"..effectID.."#ffffff)", 255, 255, 255, true)

local function createEffectManually()
local playerX, playerY, playerZ = getElementPosition(localPlayer)
local effectX, effectY, effectZ = playerX, playerY, (playerZ + 2)
local effectRX, effectRY, effectRZ = 0, 0, 0
local effectDrawDistance = 300
local effectSoundEnable = false

outputChatBox("Created effect: #ffa500"..effectName.."#ffffff (ID: #ffa500"..effectID.."#ffffff)", 255, 255, 255, true)
createEffect(effectName, effectX, effectY, effectZ, effectRX, effectRY, effectRZ, effectDrawDistance, effectSoundEnable)
end
bindKey(effectCreateKey, "down", createEffectManually)

local function switchEffect(keyName)
local effectSwitchUp = (keyName == effectSwitchUpKey)
local effectSwitchFactor = (effectSwitchUp and 1 or -1)
local effectSwitchTempID = (effectID + effectSwitchFactor)
local effectSwitchID = (effectSwitchTempID > effectCount and 1 or effectSwitchTempID < 1 and effectCount or effectSwitchTempID)

effectID = effectSwitchID
effectName = effectNames[effectID]

outputChatBox("Effect set to: #ffa500"..effectName.."#ffffff (ID: #ffa500"..effectID.."#ffffff)", 255, 255, 255, true)
end
bindKey(effectSwitchDownKey, "down", switchEffect)
bindKey(effectSwitchUpKey, "down", switchEffect)
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.4.0-9.06892|Added drawDistance argument}}
{{ChangelogItem|1.5.4-9.11631|Added soundEnable argument}}

== See Also ==
{{Client_Effects_functions}}
[[ru:createEffect]]

CreateEffect

2025-07-21T19:55:47Z

Srslyyyy: Better example to preview effects

__NOTOC__
{{Client function}}
{{New items|3.0140|1.4|
Creates an [[Element/Effect|effect]] on specified position.
}}
{{Note|Not all effects support rotation (e.g. the "fire" - effect doesn't).}}
{{Note|All effects have their own duration.}}
==Syntax==
<syntaxhighlight lang="lua">effect createEffect ( string name, float x, float y, float z [, float rX, float rY, float rZ, float drawDistance = 0, bool soundEnable = false ] )</syntaxhighlight>
{{OOP||[[Effect]]}}

===Required Arguments===
*'''name:''' A string contains [[Element/Effect#Effects_list|effect name]].
*'''x:''' A floating point number representing the X coordinate on the map.
*'''y:''' A floating point number representing the Y coordinate on the map.
*'''z:''' A floating point number representing the Z coordinate on the map.

===Optional Arguments===
{{OptionalArg}}
*'''rX:''' A floating point number representing the rotation about the X axis in degrees.
*'''rY:''' A floating point number representing the rotation about the Y axis in degrees.
*'''rZ:''' A floating point number representing the rotation about the Z axis in degrees.
*'''drawDistance:''' A floating point number between 1 and 8191 which represents the draw distance of the effect, or 0 to use the default draw distance.
{{New feature/item|3.0155|1.5.5||
*'''soundEnable:''' to enable the sound of the effect.
}}

=== Returns ===
Returns the [[Element/Effect|effect]] element if creation was successful, ''false'' otherwise.

==Example==
This example allows you to create effect by 'B' key (use mouse scroll up/down to switch effect).
<syntaxhighlight lang="lua">
local effectSwitchUpKey = "mouse_wheel_up"
local effectSwitchDownKey = "mouse_wheel_down"
local effectCreateKey = "b"

local effectNames = {
"blood_heli", "boat_prop", "camflash", "carwashspray", "cement", "cloudfast", "coke_puff", "coke_trail", "cigarette_smoke",
"explosion_barrel", "explosion_crate", "explosion_door", "exhale", "explosion_fuel_car", "explosion_large", "explosion_medium",
"explosion_molotov", "explosion_small", "explosion_tiny", "extinguisher", "flame", "fire", "fire_med", "fire_large", "flamethrower",
"fire_bike", "fire_car", "gunflash", "gunsmoke", "insects", "heli_dust", "jetpack", "jetthrust", "nitro", "molotov_flame",
"overheat_car", "overheat_car_electric", "prt_blood", "prt_boatsplash", "prt_bubble", "prt_cardebris", "prt_collisionsmoke",
"prt_glass", "prt_gunshell", "prt_sand", "prt_sand2", "prt_smokeII_3_expand", "prt_smoke_huge", "prt_spark", "prt_spark_2",
"prt_splash", "prt_wake", "prt_watersplash", "prt_wheeldirt", "petrolcan", "puke", "riot_smoke", "spraycan", "smoke30lit", "smoke30m",
"smoke50lit", "shootlight", "smoke_flare", "tank_fire", "teargas", "teargasAD", "tree_hit_fir", "tree_hit_palm", "vent", "vent2",
"water_hydrant", "water_ripples", "water_speed", "water_splash", "water_splash_big", "water_splsh_sml", "water_swim", "waterfall_end",
"water_fnt_tme", "water_fountain", "wallbust", "WS_factorysmoke"
}

local effectID = 1
local effectName = effectNames[effectID]
local effectCount = (#effectNames) -- there are 82 effects

outputChatBox("Effect set to: #ffa500"..effectName.."#ffffff (ID: #ffa500"..effectID.."#ffffff)", 255, 255, 255, true)

local function createEffectManually()
local effectX, effectY, effectZ = getElementPosition(localPlayer)
local effectRX, effectRY, effectRZ = 0, 0, 0
local effectDrawDistance = 300
local effectSoundEnable = false

outputChatBox("Created effect: #ffa500"..effectName.."#ffffff (ID: #ffa500"..effectID.."#ffffff)", 255, 255, 255, true)
createEffect(effectName, effectX, effectY, effectZ, effectRX, effectRY, effectRZ, effectDrawDistance, effectSoundEnable)
end
bindKey(effectCreateKey, "down", createEffectManually)

local function switchEffect(keyName)
local effectSwitchUp = (keyName == effectSwitchUpKey)
local effectSwitchFactor = (effectSwitchUp and 1 or -1)
local effectSwitchTempID = (effectID + effectSwitchFactor)
local effectSwitchID = (effectSwitchTempID > effectCount and 1 or effectSwitchTempID < 1 and effectCount or effectSwitchTempID)

effectID = effectSwitchID
effectName = effectNames[effectID]

outputChatBox("Effect set to: #ffa500"..effectName.."#ffffff (ID: #ffa500"..effectID.."#ffffff)", 255, 255, 255, true)
end
bindKey(effectSwitchDownKey, "down", switchEffect)
bindKey(effectSwitchUpKey, "down", switchEffect)
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.4.0-9.06892|Added drawDistance argument}}
{{ChangelogItem|1.5.4-9.11631|Added soundEnable argument}}

== See Also ==
{{Client_Effects_functions}}
[[ru:createEffect]]

EngineSetModelLODDistance

2025-07-20T19:37:51Z

Srslyyyy: Replace to predefined variable

{{Client function}}
__NOTOC__
This function sets a custom LOD distance for any object / model ID. This is the distance at which objects of that model ID are switched to their LOD model, or (if there is no LOD model) become invisible.

'''Notes:'''
The actual draw distance used is modified by the draw distance slider in the settings 'Video' tab of the MTA client.

*When the 'Video' tab draw distance slider is 0%, the engineSetModelLODDistance setting approximately matches the draw distance used.
:''e.g. engineSetModelLODDistance(1337,100) will mean model 1337 will be visible up to a distance of '''100''' units.''

*When the 'Video' tab draw distance slider is 100%, the engineSetModelLODDistance setting is approximately doubled before use.
:''e.g. engineSetModelLODDistance(1337,100) will mean model 1337 will be visible up to a distance of '''200''' units.''

However, there is a general draw distance limit of 325 units. So engineSetModelLODDistance(1337,400) will mean model 1337 will be visible up to a distance of 325 units no matter what the 'Video' tab says.

Therefore, unless it's really important, engineSetModelLODDistance should not be set to anything greater than 170.<br>
170 will still give the maximum draw distance (of 325 units) on clients that have a 'Video' tab draw distance setting of 100%, and it will help reduce lag for players who chose a lower draw distance in their settings.

'''Note for low LOD [[object]]s''':
*The limit is 325 units, but the actual draw distance used is 5 times the setting value. Also, they ignore the 'Video' tab draw distance slider. So a setting of 200 will mean a low LOD element will always have a draw distance of '''1000''' units.

'''Note for low LOD [[building]]s''':
*The distance must be set greater than 300 for a low LOD building in order to work correctly. Otherwise, the low LOD will always be visible. The actual draw distance is NOT 5 times the setting value.

==Syntax==
<syntaxhighlight lang="lua">
bool engineSetModelLODDistance ( int model, float distance [, bool extendedLod = false ] )
</syntaxhighlight>
{{OOP||Engine.setModelLODDistance}}
===Required Arguments===
*'''model:''' The model / object ID number you want to change the LOD distance of.
*'''distance:''' New LOD distance value in San Andreas units.

===Optional Arguments===
{{OptionalArg}}
{{New feature/item|3.0161|1.6.0|22676|
*'''extendedLod:''' Allows to set a greater distance than the current 325 units.
}}

===Returns===
Returns ''true'' if the function executed succesfully, ''false'' otherwise.

==Example==
This example will set the LOD distance of all objects.
<syntaxhighlight lang="lua">
-- Client-side
-- WARNING: Can cause significant lag.

-- Adjusts LOD for all objects.
function setAllObjectsLOD()

-- Get all current objects.
local objects = getElementsByType("object", root, false)

for _, theObject in ipairs(objects) do

local modelID = getElementModel(theObject)
local lodLevel = 325 -- Distance value

-- Set LOD for this model ID.
-- The 'true' enables extended range.
engineSetModelLODDistance(modelID, lodLevel, true)

end
end

-- Command to run the function.
addCommandHandler("setAllObjectsLOD", setAllObjectsLOD)
</syntaxhighlight>

This example will, besides replacing with custom map objects, also set the LOD distance accordingly, a necessary step (otherwise the object could seem to fail loading and only show up 1 feet away).
<syntaxhighlight lang="lua">
function replaceObjects()

local col1 = engineLoadCOL("map1.col")
local col2 = engineLoadCOL("map2.col")

local txd = engineLoadTXD("map.txd")
engineImportTXD(txd, 2357)
engineImportTXD(txd, 2290)

local dff1 = engineLoadDFF("map1.dff")
local dff2 = engineLoadDFF("map2.dff")

engineReplaceCOL(col1, 2357)
engineReplaceCOL(col2, 2290)
engineReplaceModel(dff1, 2357)
engineReplaceModel(dff2, 2290)

engineSetModelLODDistance(2357, 325)
engineSetModelLODDistance(2290, 325)
end
</syntaxhighlight>

This example shows how to use LOD's with buildings.
<syntaxhighlight lang="lua">
function createMyPyramid()
local pos = Vector3(0, 0, 3)
local rot = Vector3(0, 0, 0)

local modelHi = 8395 -- This model has a lot of polygons
local modelLow = 8701 -- This model is optimized for drawing at a long distance

-- Always call this function if you don't like default draw distance
-- or you allocated the model with using engineRequestModel
engineSetModelLODDistance(modelHi, 100, true)
engineSetModelLODDistance(modelLow, 500, true)

local lod = createBuilding(modelLow, pos, rot)
local building = createBuilding(modelHi, pos, rot)

setLowLODElement(building,lod)
end
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.6.0-9.22676|Added extendedLod argument}}

==See Also==
* [[getVehiclesLODDistance]]
* [[resetVehiclesLODDistance]]
* [[setVehiclesLODDistance]]
{{Engine_functions}}

GetPedTask

2025-07-19T16:30:09Z

Srslyyyy: /* Example */

{{Client function}}
__NOTOC__
This function is used to get any simple or complex [[task]] of a certain type for a ped.

It can provide feedback on all tasks relating to a ped. For example, while jumping, [[getPedSimplestTask]] will return TASK_SIMPLE_IN_AIR. If you wanted to know specifically if the player has jumped, you would use this function. If you did you will discover that while jumping Primary task 3 is TASK_COMPLEX_JUMP.

==Syntax==
<syntaxhighlight lang="lua">
string, string, string, string getPedTask ( ped thePed, string priority, int taskType )
</syntaxhighlight>
{{OOP||[[ped]]:getTask}}
===Required Arguments===
*'''thePed''': The [[ped]] whose task you want to retrieve.
*'''priority''': A string determining which set of tasks you want to retrieve it from. This must be either "primary" or "secondary".
*'''taskType''': An integer value representing the task type (or slot) you want to get the task from. Types can be:
**'''PRIMARY TASKS'''
***'''0:''' TASK_PHYSICAL_RESPONSE
***'''1:''' TASK_EVENT_RESPONSE_TEMP
***'''2:''' TASK_EVENT_RESPONSE_NONTEMP
***'''3:''' TASK_PRIMARY
***'''4:''' TASK_DEFAULT
**'''SECONDARY TASKS'''
***'''0:''' TASK_SECONDARY_ATTACK
***'''1:''' TASK_SECONDARY_DUCK
***'''2:''' TASK_SECONDARY_SAY
***'''3:''' TASK_SECONDARY_FACIAL_COMPLEX
***'''4:''' TASK_SECONDARY_PARTIAL_ANIM
***'''5:''' TASK_SECONDARY_IK

===Returns===
Returns the name of the most complex task. See [[list of player tasks]] for valid strings. Returns ''false'' if invalid arguments are specified or if there is no task of the type specified.
<br>
{{New feature|3.0110|1.1|
Returns between 1 and 4 strings. The first string contains the name of the most complex task, with simpler sub-tasks being named in the following strings. See [[list of player tasks]] for valid strings. Returns ''false'' if invalid arguments are specified or if there is no task of the type specified.
}}

==Example==
This example draws the active primary and secondary tasks (including task hierarchy in 1.1) as your local player moves around the world.
<syntaxhighlight lang="lua">
local function renderPlayerTasks()
local textX, textY = 100, 200

for taskType = 0, 4 do
local a, b, c, d = getPedTask(localPlayer, "primary", taskType)

dxDrawText("Primary task #"..taskType.." is "..tostring(a).." -> "..tostring(b).." -> "..tostring(c).." -> "..tostring(d).." -> ", textX, textY)

textY = (textY + 15)
end

textY = (textY + 15)

for taskType = 0, 5 do
local a, b, c, d = getPedTask(localPlayer, "secondary", taskType)

dxDrawText("Secondary task #"..taskType.." is "..tostring(a).." -> "..tostring(b).." -> "..tostring(c).." -> "..tostring(d).." -> ", textX, textY)

textY = (textY + 15)
end
end
addEventHandler("onClientRender", root, renderPlayerTasks)
</syntaxhighlight>

==See Also==
{{Client_ped_functions}}

SetWorldSpecialPropertyEnabled

2025-07-15T07:30:24Z

Srslyyyy: /* Example */

__NOTOC__
{{Shared function}}

{{New feature/item|3.0161|1.6.0|22195|Added also as a server-side function. Previously only available as a client-side function.}}

Enables or disables a special world property.

{{Note|
It's recommended to use server-side function with appropriate [[mtaserver.conf#minclientversion|minclientversion]] for properties like "'''underworldwarp'''", "'''burnflippedcars'''", "'''extendedwatercannons'''", "'''flyingcomponents'''", "'''vehicle_engine_autostart'''" to avoid possible data desynchronization.
}}

==Syntax==
<syntaxhighlight lang="lua">bool setWorldSpecialPropertyEnabled ( string propname, bool enable )</syntaxhighlight>
{{OOP||||isWorldSpecialPropertyEnabled}}
[[File:Randomfoliage.jpeg|frame|right|A photo demonstrating ''randomfoliage'' enabled and disabled.]]
[[File:Roadsignstext.png|frame|right|A photo demonstrating ''roadsignstext'' enabled and disabled.]]
[[File:Extendedwatercannons.png|frame|right|A photo demonstrating ''extendedwatercannons'' enabled and disabled.]]
===Required Arguments===
*'''propname:''' the name of the property to set. Possible values are:
**'''hovercars''' - equivalent of the JBGVNB cheat, and allows cars to drive on water. (default: false)
**'''aircars''' - equivalent of the RIPAZHA cheat, and allows cars to fly. (default: false)
**'''extrabunny''' - equivalent of the CJPHONEHOME or JHJOECW cheat, and allows you to bunny hop on bicycles much higher. (default: false)
**'''extrajump''' - equivalent of the KANGAROO cheat, and allows you to jump on foot much higher. (default: false)
**'''randomfoliage''' - toggle randomly generated foliage on the GTA:SA map (default: true)
**'''snipermoon''' - toggle the GTA:SA easter egg, which increases the size of the moon every time you shoot it with a sniper rifle (default: false)
**'''extraairresistance''' - toggle the vehicle speed limit on cross-country roads (default: true)
**{{New feature/item|3.0156|1.5.5|12286|'''underworldwarp''' - toggle warp of peds and vehicles when fall under map (default: true)}}
**{{New feature/item|3.0160|1.5.9|21125|'''vehiclesunglare''' - toggle the vehicle sun glare effect (default: false) }}
**{{New feature/item|3.0160|1.5.9|21313| '''coronaztest''' - disable big sun lensflare effect (default: true) }}
**{{New feature/item|3.0161|1.6.0|21919| '''watercreatures''' - toggle randomly generated underwater creatures (default: true) }}
**{{New feature/item|3.0161|1.6.0|22195| '''burnflippedcars''' - toggle the vehicle to burn when upside down (default: true) }}
**{{New feature/item|3.0161|1.6.0|22199| '''fireballdestruct''' - toggle the aircraft model destruction on explosion ([[Media:FireballDestruct.jpg|preview]]) (default: true) }}
**{{New feature/item|3.0161|1.6.0|22430| '''roadsignstext''' - toggle the drawing of text on road signs. (default: true)}}
**{{New feature/item|3.0161|1.6.0|22485| '''extendedwatercannons''' - Increases the default limit of water cannons used at the same time from 3 to 30. (default: true)}}
**{{New feature/item|3.0161|1.6.0|22596| '''tunnelweatherblend''' - toggle the weather blending effect when the player is in the tunnel. (default: true)}}
**{{New feature/item|3.0161|1.6.0|22815| '''ignorefirestate''' - Allows aiming when the player is on fire and entering burning vehicles. (default: false)}}
**{{New feature/item|3.0161|1.6.0|22909| '''flyingcomponents''' - This property determines whether the detached components such as doors, bumpers, etc., should respawn after a vehicle is recreated (change model or variant) or streamed in. (default: true)}}
**{{New feature/item|3.0161|1.6.0|23223| '''vehicleburnexplosions''' - This property toggles creation of additional explosions ([[Explosion_types|type 2 - rocket]]) when plane or helicopter is burning. (default: true)}}
**{{New feature/item|3.0161|1.6.0|23237| '''vehicle_engine_autostart''' - This property toggles automatic vehicle engine state behavior. (default: true)<br>If you set it to ''false'' then vehicle engine will not start on driver enter and will not stop on driver exit. To control the engine you need to use [[SetVehicleEngineState|setVehicleEngineState]]. Helicopter rotors will spin only if the engine is on (with or without driver inside).}}
*'''enable:''' whether or not to enable the property.

===Returns===
Returns ''true'' if successful, ''false'' otherwise.

==Example==

This code allows you to enable/disable certain property using '''true''' or '''false'''.
<syntaxhighlight lang="lua">
local worldSpecialProperties = {
["hovercars"] = false,
["aircars"] = false,
["extrabunny"] = false,
["extrajump"] = false,
["randomfoliage"] = true,
["snipermoon"] = false,
["extraairresistance"] = true,
["underworldwarp"] = true,
["vehiclesunglare"] = false,
["coronaztest"] = true,
["watercreatures"] = true,
["burnflippedcars"] = true,
["fireballdestruct"] = true,
["roadsignstext"] = true,
["extendedwatercannons"] = true,
["tunnelweatherblend"] = true,
["ignorefirestate"] = false,
["flyingcomponents"] = true,
["vehicleburnexplosions"] = true,
["vehicle_engine_autostart"] = true,
}

local function toggleWorldSpecialProperties()
for propertyName, propertyState in pairs(worldSpecialProperties) do
setWorldSpecialPropertyEnabled(propertyName, propertyState)
end
end
addEventHandler("onClientResourceStart", resourceRoot, toggleWorldSpecialProperties)
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.5.5-3.12286|Added "underworldwarp" property}}
{{ChangelogItem|1.5.9-1.21125|Added "vehiclesunglare" property}}
{{ChangelogItem|1.5.9-9.21313|Added "coronaztest" property}}
{{ChangelogItem|1.6.0-9.21919|Added "watercreatures" property}}
{{ChangelogItem|1.6.0-9.22195|Added "burnflippedcars" property}}
{{ChangelogItem|1.6.0-9.22199|Added "fireballdestruct" property}}
{{ChangelogItem|1.6.0-9.22430|Added "roadsignstext" property}}
{{ChangelogItem|1.6.0-9.22485|Added "extenedwatercannons" property}}
{{ChangelogItem|1.6.0-9.22596|Added "tunnelweatherblend" property}}
{{ChangelogItem|1.6.0-9.22815|Added "ignorefirestate" property}}
{{ChangelogItem|1.6.0-9.22909|Added "flyingcomponents" property}}
{{ChangelogItem|1.6.0-9.23223|Added "vehicleburnexplosions" property}}
{{ChangelogItem|1.6.0-9.23237|Added "vehicle_engine_autostart" property}}

==See Also==
{{World functions}}

SetGlitchEnabled

2025-07-15T07:28:02Z

Srslyyyy: /* Example */

__NOTOC__
{{Server function}}
This function enables or disables glitches that are found in the original Single Player game that can be used to gain an advantage in multiplayer.
{{Note|By default all these glitches are disabled - use this function to '''enable''' them.}}

Users of the '''fastmove''' glitch may additionally want to install [https://community.mtasa.com/index.php?p=resources&s=details&id=13368 this resource to disable crouchsliding].

==Syntax==
<syntaxhighlight lang="lua">bool setGlitchEnabled ( string glitchName, bool enable )</syntaxhighlight>

===Required Arguments===
*'''glitchName:''' the name of the property to set. Possible values are:
{{Glitches}}
*'''enable:''' whether or not to enable the glitch.

===Returns===
Returns ''true'' if successful, ''false'' otherwise.

==Example==
This example allows you to toggle specific glitch using '''true''' or '''false'''.
<syntaxhighlight lang="lua">
local glitchesData = {
["quickreload"] = false,
["fastmove"] = false,
["fastfire"] = false,
["crouchbug"] = false,
["highcloserangedamage"] = false,
["hitanim"] = false,
["fastsprint"] = false,
["baddrivebyhitbox"] = false,
["quickstand"] = false,
["kickoutofvehicle_onmodelreplace"] = false,
["vehicle_rapid_stop"] = false,
}

local function toggleGlitches()
for glitchName, glitchState in pairs(glitchesData) do
setGlitchEnabled(glitchName, glitchState)
end
end
addEventHandler("onResourceStart", resourceRoot, toggleGlitches)
</syntaxhighlight>

==See Also==
{{Server functions}}

Template:Glitches

2025-07-15T07:22:49Z

Srslyyyy: Adjust to https://github.com/multitheftauto/mtasa-blue/pull/4243

<div style="border:3px solid red;margin-bottom:3px;padding-left:5px;"><div style="float:right;padding-right:5px;font-weight:bold;"></div>
*'''quickreload:''' This is the glitch where switching weapons auto-reloads your weapon, without actually performing the reload animation.
*'''fastmove:''' This is the glitch that can be achieved by a certain key combinations whilst standing up after crouching, which allows you to move quickly with slow weapons (e.g. deagle). Side effect: also enables the "crouchslide" bug - use [https://community.mtasa.com/index.php?p=resources&s=details&id=13368 the "NoCrouchSlide" resource] to remedy this.
*'''fastfire:''' This is the glitch that can be achieved by cancelling the full fire animation, allowing you to shoot with slow-fire weapons (e.g. deagle) much faster.
*'''crouchbug:''' This is the glitch where the post shooting animation can be aborted by using the crouch key.
*'''highcloserangedamage:''' Enabling this removes the extremely high damage guns inflict when fired at very close range.
*'''hitanim:''' Enabling this allows 'hit by bullet' animations to interrupt player aiming.
*'''fastsprint:''' Enabling fastsprint allows players to tap space with a macro to boost their speed beyond normal speeds of GTASA.
*'''baddrivebyhitbox:''' This glitch leaves players invulnerable to gun fire when performing certain driveby animations.
*'''quickstand:''' This glitch allows players to quickly stand up by pressing the crouch, sprint or jump controls just after releasing the aim weapon button while using one and being ducked.
*'''kickoutofvehicle_onmodelreplace:''' This glitch enables the old behavior where players get warped out of a vehicle when the model is replaced.
*{{New feature/item|3.0161|1.6.0|23281|'''vehicle_rapid_stop:''' This glitch enables the old behavior of vehicles (pre-high FPS fix, see PR: [https://github.com/multitheftauto/mtasa-blue/pull/4243 #4243] & [https://github.com/multitheftauto/mtasa-blue/pull/2784 #2784])}}
</div>

OnPlayerTriggerEventThreshold

2025-07-15T07:17:06Z

Srslyyyy: /* Parameters */

__NOTOC__
{{Server event}}
{{Added feature/item|1.6.1|1.6.0|22313|This event is triggered when a player exceeds the maximum threshold for events via [[triggerServerEvent]].}}

During each interval (''player_triggered_event_interval''), all usage of [[triggerServerEvent]] will be counted for each player. This includes registered events, non-registered events and non-remote events.

If the count exceeds ''max_player_triggered_events_per_interval'', this event will be fired. The count is reset each interval.

You can set these options via [[setServerConfigSetting]].

==Parameters==
{{New feature/item|3.0161|1.6.0|23281|'''eventName:''' the name of last called event.}}

==Source==
The [[event system#Event source|source]] of this event is the [[player]] who exceeded the threshold.

===Canceling===
Canceling this event has no effect.

==Example==
<syntaxhighlight lang="lua">
function processPlayerTriggerEventThreshold()
kickPlayer(source, "Event spam")
end
addEventHandler("onPlayerTriggerEventThreshold", root, processPlayerTriggerEventThreshold)

</syntaxhighlight>
{{See also/Server event|Player events}}

OnVehicleExplode

2025-07-15T06:55:30Z

Srslyyyy: Adjust to https://github.com/multitheftauto/mtasa-blue/pull/4295

__NOTOC__
{{Server event}}
This event is triggered when a vehicle explodes.

==Parameters==
<syntaxhighlight lang="lua">
bool withExplosion, player player
</syntaxhighlight>
*'''withExplosion:''' Determines whether the vehicle was blown with or without an explosion.
{{New feature/item|3.0161|1.6.0|22680|
*'''player:''' The player who sent the explosion packet.
}}

==Source==
The [[event system#Event source|source]] of this event is the [[vehicle]] that exploded.

==Cancel effect==
{{New feature/item|3.0161|1.6.0|23281|If this event is cancelled, the vehicle won't explode.}}

==Example==
'''Example 1'''
<syntaxhighlight lang="lua">
local vagosVehicle = nil

-- This will get called when the vagos vehicle explodes
function onVagosVehicleExplode ()
outputChatBox ( "VAGOS VEHICLE DESTROYED!" )
end

-- This is called when THIS resource starts
function onThisResourceStart ()

-- Create the vagos vehicle. A van.
vagosVehicle = createVehicle ( 522, 0, 0, 5 )

-- Add its explode handler. When this car explodes, onVagosVehicleExplode is called
addEventHandler ( "onVehicleExplode", vagosVehicle, onVagosVehicleExplode )
end

--Add the resource start event
addEventHandler ( "onResourceStart", resourceRoot, onThisResourceStart )
</syntaxhighlight>

'''Example 2:''' This will show the name of any vehicle that blew up:
<syntaxhighlight lang="lua">
function notifyAboutExplosion()
-- source is the element that triggered the event and can be used in other events as well
outputChatBox(getVehicleName(source) .. " just blew up")
end

-- by using root, it will work for any vehicle (even if it wasn't created via this resource)
addEventHandler("onVehicleExplode", root, notifyAboutExplosion)
</syntaxhighlight>

{{See also/Server event|Vehicle events}}

OnPlayerTriggerEventThreshold

2025-07-06T01:25:33Z

Srslyyyy: Adjust parameters to https://github.com/multitheftauto/mtasa-blue/pull/4271

__NOTOC__
{{Server event}}
{{Added feature/item|1.6.1|1.6.0|22313|This event is triggered when a player exceeds the maximum threshold for events via [[triggerServerEvent]].}}

During each interval (''player_triggered_event_interval''), all usage of [[triggerServerEvent]] will be counted for each player. This includes registered events, non-registered events and non-remote events.

If the count exceeds ''max_player_triggered_events_per_interval'', this event will be fired. The count is reset each interval.

You can set these options via [[setServerConfigSetting]].

==Parameters==
{{Added feature/item|1.6.1|1.6.0|23251|'''eventName:''' the name of last called event.}}

==Source==
The [[event system#Event source|source]] of this event is the [[player]] who exceeded the threshold.

===Canceling===
Canceling this event has no effect.

==Example==
<syntaxhighlight lang="lua">
function processPlayerTriggerEventThreshold()
kickPlayer(source, "Event spam")
end
addEventHandler("onPlayerTriggerEventThreshold", root, processPlayerTriggerEventThreshold)

</syntaxhighlight>
{{See also/Server event|Player events}}

GetCameraFieldOfView

2025-07-01T19:40:37Z

Srslyyyy:

__NOTOC__
{{client function}}
{{New feature/item|3.0151|1.5.1|7397|This function returns the field of view of the ''dynamic camera'' as set by [[setCameraFieldOfView]].}}
==Syntax==
<syntaxhighlight lang="lua">
float getCameraFieldOfView ( string cameraMode )
</syntaxhighlight>
{{OOP||Camera.getFieldOfView|fov|setCameraFieldOfView}}

===Required Arguments===
*'''cameraMode:''' the camera mode to get the field of view of:
** "player": whilst walking/running
** "vehicle": whilst in vehicle
** "vehicle_max": the max the field of view can go to when the vehicle is moving at a high speed (must be higher than "vehicle")

===Returns===
Returns one float - the field of view angle

==Example==
In this example, the field of view is output to the chat whenever the /getfov command is written

<syntaxhighlight lang="lua">
function getCamFOV()
outputChatBox("The camera field of view for 'player walking/running' is: " .. getCameraFieldOfView("player"))
end
addCommandHandler("getfov", getCamFOV)</syntaxhighlight>

==See Also==
{{Client camera functions}}

[[hu:getCameraFieldOfView]]
[[RO:getCameraFieldOfView]]

SetCameraFieldOfView

2025-07-01T19:40:27Z

Srslyyyy:

__NOTOC__
{{client function}}
{{New feature/item|3.0151|1.5.1|7397|This function sets the field of view of the ''dynamic camera'' - this is the field of view of the ''non-fixed camera'' - yes, the camera that the user can control whilst on foot or in a vehicle. The higher the field of view angle, the more you will be able to see to your sides.}}
{{Note|This function omits (but doesn't override) the user game option in '''''Settings -> Video -> FOV'''''}}
{{Note|It doesn't affect the FOV for the following camera modes: 1) Player aiming 2) Vehicle front bumper camera 3) Fixed camera}}
==Syntax==
<syntaxhighlight lang="lua">
bool setCameraFieldOfView ( string cameraMode, float fieldOfView )
</syntaxhighlight>
{{OOP||Camera.setFieldOfView||getCameraFieldOfView}}
===Required Arguments===
'''Note:''' after 100, some unexpected things may happen to the camera, particularly in vehicles, use carefully!
*'''cameraMode:''' the camera mode to set the field of view of:
** "player": whilst walking/running
** "vehicle": whilst in vehicle
** "vehicle_max": the max the field of view can go to when the vehicle is moving at a high speed (must be higher than "vehicle")
*'''fieldOfView:''' The field of view angle, 0 to 179.
===Returns===
Returns ''true'' if the arguments are valid, ''false'' otherwise.

==Example==
In this example, the field of view for 'player walking/running' is set to 20 when the player joins.

<syntaxhighlight lang="lua">
function setCameraFOVOnResStart()
setCameraFieldOfView("player",20)
end
addEventHandler("onClientResourceStart", resourceRoot, setCameraFOVOnResStart)</syntaxhighlight>

==See Also==
{{Client camera functions}}

[[hu:setCameraFieldOfView]]
[[RO:setCameraFieldOfView]]

SetCameraFieldOfView

2025-07-01T19:40:13Z

Srslyyyy:

__NOTOC__
{{client function}}
{{New feature/item|3.0151|1.5.1|7397|This function sets the field of view of the ''dynamic camera'' - this is the field of view of the ''non-fixed camera'' - yes, the camera that the user can control whilst on foot or in a vehicle. The higher the field of view angle, the more you will be able to see to your sides.}}
{{Note|This function omits (but doesn't override) the user game option in '''''Settings -> Video -> FOV'''''}}
{{Note|It doesn't affect the FOV for the following camera modes: 1) Player aiming 2) Vehicle front bumper camera 3) Fixed camera}}
==Syntax==
<syntaxhighlight lang="lua">
bool setCameraFieldOfView ( string cameraMode, float fieldOfView )
</syntaxhighlight>
{{OOP||Camera.setFieldOfView||getCameraFieldOfView}}
===Required Arguments===
'''Note:''' after 100, some unexpected things may happen to the camera, particularly in vehicles, use carefully!
*'''cameraMode:''' the camera mode to set the field of view of
** "player": whilst walking/running
** "vehicle": whilst in vehicle
** "vehicle_max": the max the field of view can go to when the vehicle is moving at a high speed (must be higher than "vehicle")
*'''fieldOfView:''' The field of view angle, 0 to 179.
===Returns===
Returns ''true'' if the arguments are valid, ''false'' otherwise.

==Example==
In this example, the field of view for 'player walking/running' is set to 20 when the player joins.

<syntaxhighlight lang="lua">
function setCameraFOVOnResStart()
setCameraFieldOfView("player",20)
end
addEventHandler("onClientResourceStart", resourceRoot, setCameraFOVOnResStart)</syntaxhighlight>

==See Also==
{{Client camera functions}}

[[hu:setCameraFieldOfView]]
[[RO:setCameraFieldOfView]]

SetCameraFieldOfView

2025-06-30T17:38:34Z

Srslyyyy:

__NOTOC__
{{client function}}
{{New feature/item|3.0151|1.5.1|7397|This function sets the field of view of the ''dynamic camera'' - this is the field of view of the ''non-fixed camera'' - yes, the camera that the user can control whilst on foot or in a vehicle. The higher the field of view angle, the more you will be able to see to your sides.}}
{{Note|This function omits (but doesn't override) the user game option in '''''Settings -> Video -> FOV'''''}}
{{Note|It doesn't affect the FOV for the following camera modes: 1) Player aiming 2) Vehicle front bumper camera 3) Fixed camera}}
==Syntax==
<syntaxhighlight lang="lua">
bool setCameraFieldOfView ( string cameraMode, float fieldOfView )
</syntaxhighlight>
{{OOP||Camera.setFieldOfView||getCameraFieldOfView}}
===Required Arguments===
'''Note:''' after 100, some unexpected things may happen to the camera, particularly in vehicles, use carefully!
*'''cameraMode:''' the camera mode to get the field of view of
** "player": whilst walking/running
** "vehicle": whilst in vehicle
** "vehicle_max": the max the field of view can go to when the vehicle is moving at a high speed (must be higher than "vehicle")
*'''fieldOfView:''' The field of view angle, 0 to 179.
===Returns===
Returns ''true'' if the arguments are valid, ''false'' otherwise.

==Example==
In this example, the field of view for 'player walking/running' is set to 20 when the player joins.

<syntaxhighlight lang="lua">
function setCameraFOVOnResStart()
setCameraFieldOfView("player",20)
end
addEventHandler("onClientResourceStart", resourceRoot, setCameraFOVOnResStart)</syntaxhighlight>

==See Also==
{{Client camera functions}}

[[hu:setCameraFieldOfView]]
[[RO:setCameraFieldOfView]]

SetCameraFieldOfView

2025-06-30T17:37:52Z

Srslyyyy:

__NOTOC__
{{client function}}
{{New feature/item|3.0151|1.5.1|7397|This function sets the field of view of the ''dynamic camera'' - this is the field of view of the ''non-fixed camera'' - yes, the camera that the user can control whilst on foot or in a vehicle. The higher the field of view angle, the more you will be able to see to your sides.}}
{{Note|This functions omits (but doesn't override) the user game option in '''''Settings -> Video -> FOV'''''}}
{{Note|It doesn't affect the FOV for the following camera modes: 1) Player aiming 2) Vehicle front bumper camera 3) Fixed camera}}
==Syntax==
<syntaxhighlight lang="lua">
bool setCameraFieldOfView ( string cameraMode, float fieldOfView )
</syntaxhighlight>
{{OOP||Camera.setFieldOfView||getCameraFieldOfView}}
===Required Arguments===
'''Note:''' after 100, some unexpected things may happen to the camera, particularly in vehicles, use carefully!
*'''cameraMode:''' the camera mode to get the field of view of
** "player": whilst walking/running
** "vehicle": whilst in vehicle
** "vehicle_max": the max the field of view can go to when the vehicle is moving at a high speed (must be higher than "vehicle")
*'''fieldOfView:''' The field of view angle, 0 to 179.
===Returns===
Returns ''true'' if the arguments are valid, ''false'' otherwise.

==Example==
In this example, the field of view for 'player walking/running' is set to 20 when the player joins.

<syntaxhighlight lang="lua">
function setCameraFOVOnResStart()
setCameraFieldOfView("player",20)
end
addEventHandler("onClientResourceStart", resourceRoot, setCameraFOVOnResStart)</syntaxhighlight>

==See Also==
{{Client camera functions}}

[[hu:setCameraFieldOfView]]
[[RO:setCameraFieldOfView]]

SetCameraFieldOfView

2025-06-30T17:35:51Z

Srslyyyy: Better phrasing for note

__NOTOC__
{{client function}}
{{New feature/item|3.0151|1.5.1|7397|This function sets the field of view of the ''dynamic camera'' - this is the field of view of the ''non-fixed camera'' - yes, the camera that the user can control whilst on foot or in a vehicle. The higher the field of view angle, the more you will be able to see to your sides.}}
{{Note|[[setCameraFieldOfView]] omits (but doesn't override) the user game option in '''''Settings->Video->FOV'''''}}
{{Note|[[setCameraFieldOfView]] does not affect the FOV for the following camera modes: 1) Player aiming 2) Vehicle front bumper camera 3) Fixed camera}}
==Syntax==
<syntaxhighlight lang="lua">
bool setCameraFieldOfView ( string cameraMode, float fieldOfView )
</syntaxhighlight>
{{OOP||Camera.setFieldOfView||getCameraFieldOfView}}
===Required Arguments===
'''Note:''' after 100, some unexpected things may happen to the camera, particularly in vehicles, use carefully!
*'''cameraMode:''' the camera mode to get the field of view of
** "player": whilst walking/running
** "vehicle": whilst in vehicle
** "vehicle_max": the max the field of view can go to when the vehicle is moving at a high speed (must be higher than "vehicle")
*'''fieldOfView:''' The field of view angle, 0 to 179.
===Returns===
Returns ''true'' if the arguments are valid, ''false'' otherwise.

==Example==
In this example, the field of view for 'player walking/running' is set to 20 when the player joins.

<syntaxhighlight lang="lua">
function setCameraFOVOnResStart()
setCameraFieldOfView("player",20)
end
addEventHandler("onClientResourceStart", resourceRoot, setCameraFOVOnResStart)</syntaxhighlight>

==See Also==
{{Client camera functions}}

[[hu:setCameraFieldOfView]]
[[RO:setCameraFieldOfView]]

SetCameraFieldOfView

2025-06-30T17:29:23Z

Srslyyyy: Remove misleading/incorrect information

__NOTOC__
{{client function}}
{{New feature/item|3.0151|1.5.1|7397|This function sets the field of view of the ''dynamic camera'' - this is the field of view of the ''non-fixed camera'' - yes, the camera that the user can control whilst on foot or in a vehicle. The higher the field of view angle, the more you will be able to see to your sides.}}
{{Note|[[setCameraFieldOfView]] does not affect the FOV for the following camera modes: 1) Player aiming 2) Vehicle front bumper camera 3) Fixed camera}}
==Syntax==
<syntaxhighlight lang="lua">
bool setCameraFieldOfView ( string cameraMode, float fieldOfView )
</syntaxhighlight>
{{OOP||Camera.setFieldOfView||getCameraFieldOfView}}
===Required Arguments===
'''Note:''' after 100, some unexpected things may happen to the camera, particularly in vehicles, use carefully!
*'''cameraMode:''' the camera mode to get the field of view of
** "player": whilst walking/running
** "vehicle": whilst in vehicle
** "vehicle_max": the max the field of view can go to when the vehicle is moving at a high speed (must be higher than "vehicle")
*'''fieldOfView:''' The field of view angle, 0 to 179.
===Returns===
Returns ''true'' if the arguments are valid, ''false'' otherwise.

==Example==
In this example, the field of view for 'player walking/running' is set to 20 when the player joins.

<syntaxhighlight lang="lua">
function setCameraFOVOnResStart()
setCameraFieldOfView("player",20)
end
addEventHandler("onClientResourceStart", resourceRoot, setCameraFOVOnResStart)</syntaxhighlight>

==See Also==
{{Client camera functions}}

[[hu:setCameraFieldOfView]]
[[RO:setCameraFieldOfView]]

Server mtaserver.conf

2025-06-05T17:53:14Z

Srslyyyy:

This page lists the settings that can be set in the settings file. ''Setting from the default '''mtaserver.conf''' settings file is in italics''.

==Settings==

====servername====
:''<servername>Default MTA Server</servername>''
:This parameter specifies the name the server will be visible as in the ingame server browser and on Game-Monitor. It is a required parameter.

====rule====
:''<rule name="NAME_HERE" value="VALUE_HERE"/>''
:The rule parameters are optional. There can be as many as you want in the config file. They contain information for the Server Browser/List. [[Server_Browser_Rules|Read this article for more information]].

====owner_email_address====
:''<owner_email_address></owner_email_address>''
:This parameter specifies the contact email addresses for the owner(s) of this server.
:The email addresses will not be publicly available, and only used by MTA administrators to contact the server owner.
:Note: Missing or incorrect owner_email_address can affect visibility in the master server list.
:Values: Comma separated list of email addresses

====serverip====
:''<serverip>auto</serverip>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING''' - it is generally only needed for complex network topologies and should be left at the default value otherwise.
: This parameter specifies the public IP address that the server will announce to the MTA servers, for the purposes of registering itself in the master server list and receiving some internal status updates. Usually, setting this parameter is only useful for some specialized scenarios, like servers that can be reached by multiple public addresses, or when a firewall is used for controlling incoming connections. If set to auto, the public IP address the requests originate from will be used as the server IP for communicating with MTA servers, which works fine in most cases.
:Values: auto or x.x.x.x ; default value: auto
:SERVERIP SHOULD BE LEFT SET TO auto UNLESS YOU ARE SURE OF WHAT YOU ARE DOING
:WARNING: SETTING serverip AND THEN ASKING FOR SUPPORT CAN CAUSE DEATH OR INJURY

====serverport====
:''<serverport>22003</serverport>
:This parameter specifies the UDP port on which the server will be accepting incoming player connections;
:default value: 22003. It is a required parameter.

====maxplayers====
:''<maxplayers>32</maxplayers>
:This parameter specifies the number of maximum player slots available on the server;
:default value: 32. It is a required parameter.

====httpserver====

:''<httpserver>1</httpserver>
:This parameter specifies whether the built-in http server will be used.
:Values: 0 - disabled , 1 - enabled ; default value: 1. Optional parameter.
:More information: [[Server_Manual#Using_the_web_interface|Using the web interface]]

====httpport====
:''<httpport>22005</httpport>
:This parameter specifies the TCP port on which the server will be accepting incoming http connections. It can be set to the same value as <serverport>. It is a required parameter if <httpserver> is set to 1.
:More information: [[Server_Manual#Using_the_web_interface|Using the web interface]]

====httpdownloadurl====
:''<httpdownloadurl></httpdownloadurl>
:If set, this parameter specifies the external URL from which clients will be able to download needed resources ingame. Otherwise they will download them directly from the server.
:More information: [[Server_Manual#Configuring_an_external_web_server|Configuring an external web server]]

====httpmaxconnectionsperclient====
:''<httpmaxconnectionsperclient>5</httpmaxconnectionsperclient>
:This parameter limits the number of http connections each client can make. Depending on the type of http server that is used, a lower figure may reduce download timeouts. Only relevant when using an external http server.
:Available range: 1 to 8.

====httpthreadcount====
:''<httpthreadcount>8</httpthreadcount>
:Number of HTTP server threads.
:Available range: 1 to 20. default value: 8

====httpdosthreshold====
:''<httpdosthreshold>20</httpdosthreshold>
:This parameter limits the number http connections that an IP can initiate over a short period of time.
:Available range: 1 to 100. default value: 20

====http_dos_exclude====
:''<http_dos_exclude></http_dos_exclude>
:This parameter lists the IP addresses that are to be excluded from http dos threshold limits.
:e.g. 88.11.22.33,101.2.3.4

====allow_gta3_img_mods====
:''<allow_gta3_img_mods>none</allow_gta3_img_mods>
:By default, the server will block the use of locally customized gta3.img player skins
:This setting can be used to allow such mods. Not recommended for competitive servers.
:Values: none, peds ; default value: none

====client_file====
:''<nowiki></nowiki>
:By default, the server will block the use of customized GTA:SA data files.
:To allow specific client files, add one or more of the above lines.
:More information: [[Anti-cheat_guide#.3Cclient_file_name.3D.22data.2Fcarmods.dat.22_verify.3D.220.22.2F.3E|Anti-cheat guide]]

====disableac====
:''<disableac></disableac>
:Comma separated list of disabled anti-cheats.
:e.g. To disable anti-cheat #2 and #3, use: 2,3
:More information: [[Anti-cheat_guide#.3Cdisableac.3E.3C.2Fdisableac.3E|Anti-cheat guide]]

====enablesd====
:''<enablesd>31,32</enablesd>
:Comma separated list of enabled special detections. A special detection is a type of anti-cheat for (usually) harmless game modifications.
:Competitive servers may wish to enable certain special detections, but most servers should leave this setting on its default.
:Values: special detection (SD) codes ; default value: 31,32 (e.g. enables special detections #31 and #32)
:More information: [[Anti-cheat_guide#.3Cenablesd.3E.3C.2Fenablesd.3E|Anti-cheat guide]]

====hideac====
:''<hideac>0</hideac>
:When this parameter is enabled client won't get any info about Anticheat settings when connecting to server.
:Values: 0 - disabled , 1 - enabled ; default value: 0. Optional parameter.

====minclientversion====
:''<minclientversion></minclientversion>
:Minimum client version. Clients with a lower version will not be allowed to connect. After disconnection, clients will be given an opportunity to download an update. If left blank, this setting is disabled and there are no restrictions on who can connect. Version numbers are described in [[getPlayerVersion]] and look like this: 1.6.0-9.22953.0
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:'''Note that this setting only determines if the client should be prompted to update. The actual build number they receive will be the [[https://nightly.mtasa.com/ver highest available]].'''

====minclientversion_auto_update====
:''<minclientversion_auto_update>1</minclientversion_auto_update>
:This parameter specifies if/when the <minclientversion> setting is automatically updated.
:Keeping <minclientversion> updated can help reduce cheating.
:Note: The instant setting (2) is only recommended for competitive servers.
:Values: 0 - disabled, 1 - enabled (delayed by a few days), 2 - enabled (instant) ; default value: 1.

====recommendedclientversion====
:''<recommendedclientversion></recommendedclientversion>
:Recommended client version. When connecting, if clients have a lower version, they will be given the option to download an update. If left blank, this setting is disabled.
:This parameter can changed and saved while the server is running with [[setServerConfigSetting]]
:'''Note that this setting only determines if the client should be prompted to update. The actual build number they receive will be the [[https://nightly.mtasa.com/ver highest available]].'''

====ase====
:''<ase>1</ase>
:This parameter can be used to make the server report to Game-Monitor master servers, allowing it to be visible in the in-game server browser. An additional UDP port needs to be available for this to work (value from <serverport> + 123 , so on a default <serverport> value 22003 the right port will be 22126 ).
:Available values: 0 - disabled , 1 - enabled. Optional parameter, defaults to 0.

====donotbroadcastlan====
:''<donotbroadcastlan>0</donotbroadcastlan>
:This parameter allows you to disable LAN broadcasting.

====password====
:''<password></password>
:If set, players will have to provide a password specified below, before they can connect to the server. If left blank, server doesn't require a password from them.
:This parameter can changed and saved while the server is running with [[setServerPassword]] or [[setServerConfigSetting]]

====net_auto_filter====
:''<net_auto_filter>1</net_auto_filter>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING'''
:Net auto filter.
:Values: 0 - disabled, 1 - enabled. default value: 1

====update_cycle_datagrams_limit====
:''<update_cycle_datagrams_limit>4</update_cycle_datagrams_limit>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING'''
:Send datagrams limit.
:Available range: 1 to 100. default value: 4

====update_cycle_messages_limit====
:''<update_cycle_messages_limit>50</update_cycle_messages_limit>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING'''
:Send messages limit.
:Available range: 10 to 1000. default value: 50

====bandwidth_reduction====
:''<bandwidth_reduction>medium</bandwidth_reduction>
:This parameter reduces the server's bandwidth usage by using various optimizations.
:Values: none, medium or maximum ; default value: medium
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====unoccupied_vehicle_syncer_distance====

:''<unoccupied_vehicle_syncer_distance>130</unoccupied_vehicle_syncer_distance>
:This parameter determines the distance limit for remote synced unoccupied vehicles
:Available range: 50 - 400; default value: 130
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====ped_syncer_distance====

:''<ped_syncer_distance>100</ped_syncer_distance>
:This parameter determines the distance limit for remote synced peds
:Available range: 50 - 400; default value: 100
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====player_sync_interval====
:''<player_sync_interval>100</player_sync_interval>
:This parameter determines the time in milliseconds between player sync packets.
:Available range: 50 - 4000; default value: 100
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====lightweight_sync_interval====
:''<lightweight_sync_interval>1500</lightweight_sync_interval>
:This parameter determines the time in milliseconds between lightweight (player) sync packets.
:Available range: 200 - 4000; default value: 1500
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====camera_sync_interval====
:''<camera_sync_interval>500</camera_sync_interval>
:This parameter determines the time in milliseconds between camera sync packets.
:Available range: 50 - 4000; default value: 500
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====ped_sync_interval====
:''<ped_sync_interval>500</ped_sync_interval>
:This parameter determines the time in milliseconds between ped sync packets when the ped is near the player.
:Available range: 50 - 4000; default value: 500
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====ped_far_sync_interval====
:''<ped_far_sync_interval>2000</ped_far_sync_interval>
:This parameter determines the time in milliseconds between ped sync packets when the ped is far away from the player.
:Available range: 50 - 4000; default value: 2000
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====unoccupied_vehicle_sync_interval====
:''<unoccupied_vehicle_sync_interval>400</unoccupied_vehicle_sync_interval>
:This parameter determines the time in milliseconds between unoccupied vehicle sync packets.
:Available range: 50 - 4000; default value: 400
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====keysync_mouse_sync_interval====
:''<keysync_mouse_sync_interval>100</keysync_mouse_sync_interval>
:This parameter determines the minimum time in milliseconds between key sync packets due to mouse movement.
:Available range: 50 - 4000; default value: 100
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====keysync_analog_sync_interval====
:''<keysync_analog_sync_interval>100</keysync_analog_sync_interval>
:This parameter determines the minimum time in milliseconds between key sync packets due to joystick movement.
:Available range: 50 - 4000; default value: 100
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====donkey_work_interval====
:''<donkey_work_interval>100</donkey_work_interval>
:Update near list interval in milliseconds.
:Available range: 50 to 4000. default value: 100

====bullet_sync====
:''<bullet_sync>1</bullet_sync>
:This parameter can improve the reliability of shots when using certain weapons. However, it uses more bandwidth.
:Note that bullet sync will be active regardless of this setting when certain [[setGlitchEnabled|glitches]] are enabled.
:Values: 0 - disabled , 1 - enabled ; default value: 1.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

{{Added feature/item|1.6.1|1.6.0|22430|
====vehicle_contact_sync_radius====
:''<vehicle_contact_sync_radius>30</vehicle_contact_sync_radius>
:This parameter specifies the radius in which any contact with a vehicle will turn the player into its syncer.
:Changing this setting to 0 will cause vehicles to not pick a new syncer based on which player is touching the vehicle.
:Available range: 0 to 130. Default - 30
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
}}

====vehext_percent====
:''<vehext_percent>0</vehext_percent>
:This parameter sets the amount of extrapolation that clients will apply to remote vehicles.
:This can reduce some of the latency induced location disparency by predicting where the remote vehicles will probably be.
:Depending on the gamemode, an incorrect prediction may have a negative effect.
:Therefore this setting should be considered experimental.
:Available range: 0 to 100. Default - 0

====vehext_ping_limit====
:''<vehext_ping_limit>150</vehext_ping_limit>
:This parameter places a limit on how much time (in milliseconds) the vehicle extrapolation will attempt to compensate for.
:Only relevant if <vehext_percent> is greater than zero.
:Available range: 50 to 500. Default - 150

====latency_reduction====
:''<latency_reduction>0</latency_reduction>
:This parameter can reduce the delay of player actions appearing on remote clients by 2 frames (approx 50ms).
:Due to the impact this may have on shot lag compensation, it should be considered experimental.
:Values: 0 - disabled , 1 - enabled ; default value: 0.
:Bugs caused by enabling latency_reduction: https://bugs.mtasa.com/view.php?id=8191 + https://bugs.mtasa.com/view.php?id=8226

====threadnet====

:''<threadnet>1</threadnet>
:This parameter specifies whether or not to run the network synchronization on another thread.
:Enabling will make the sync smoother, but may increase CPU usage slightly.
:Values: 0 - disabled , 1 - enabled ; default value: 1.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====idfile====
:''<idfile>server-id.keys</idfile>
:Specifies the location and file name of this servers unique private key. This is used to prevent private files saved on the client from being read by other servers.
:Keep a backup of this file in a safe place. Default value: server-id.keys
:More information about client private files: [[Filepath]]

====logfile====
:''<logfile>logs/server.log</logfile>
:Specifies the location and name of the main server log file. If left blank, server won't be saving this file.

====authfile====
:''<authfile>logs/server_auth.log</authfile>
:As well as the main log file, login successes and failures are logged here for easy reviewing of security issues. If left blank, this file is not used

====dbfile====
:''<dbfile>logs/db.log</dbfile>
:Specifies the location and name of the file used to log database queries. The server command [[Server_Commands#debugdb|debugdb]] sets the amount of logging.

====loadstringfile====
:''<nowiki></nowiki>
:Specifies the location and name of the file used to log loadstring function calls. If left blank or not set, no logging is done.

====acl====
:''<acl>acl.xml</acl>
:This parameter specifies the location and name of the Access Control List settings file. If left
:blank, server will use acl.xml file, located in the same folder as this configuration file.

====scriptdebuglogfile====
:''<scriptdebuglogfile>logs/scripts.log</scriptdebuglogfile>
:Specifies the location and name of the debugscript log file. If left blank, server won't be saving this file.

====scriptdebugloglevel====
:''<scriptdebugloglevel>0</scriptdebugloglevel>
:Specifies the level of the debugscript log file. Available values: 0, 1, 2, 3. When not set, defaults to 0.

====htmldebuglevel====
:''<htmldebuglevel>0</htmldebuglevel>
:Specifies the level of the html debug. Available values: 0, 1, 2, 3. When not set, defaults to 0.

====filter_duplicate_log_lines====
:''<filter_duplicate_log_lines>1</filter_duplicate_log_lines>
:Specifies whether or not duplicate log lines should be filtered. Available values: 0 or 1, defaults to 1.

====fpslimit====
:''<fpslimit>74</fpslimit>
:Specifies the frame rate limit that will be applied to connecting clients.
:Available range: 25 to 32767. Default: 74. You can also use 0 for uncapped fps.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====voice====
:''<voice>0</voice>
:This parameter specifies whether or not to enable player voice chat in-game
:Values: 0 - disabled , 1 - enabled

====voice_samplerate====
:''<voice_samplerate>1</voice_samplerate>
:This parameter specifies the sample rate for voice chat. 'voice' parameter must be set to 1 for this to be effective. Higher settings use more bandwidth and increase the sampling quality of voice chat
:Values: 0 - Narrowband (8kHz), 1 - Wideband (16kHz), 2 - Ultrawideband (32kHz). Default - 1

====voice_quality====
:''<voice_quality>4</voice_quality>
:This parameter specifies the voice quality for voice chat. 'voice' parameter must be set to 1 for this to be effective. Higher settings use more bandwidth and increase the the overall quality of voice chat
:Available range: 0 to 10. Default - 4

====voice_bitrate====
:''<nowiki></nowiki>
:Specifies the voice bitrate, in bps. This optional parameter overrides the previous two settings. If not set, MTA handles this automatically. Use with care.

====backup_path====
:''<backup_path>backups</backup_path>
:This parameter specifies the path to use for a basic backup of some server files. Note that basic backups are only made during server startup. Default value: backups

====backup_interval====
:''<backup_interval>3</backup_interval>
:This parameter specifies the number of days between each basic backup. Backups are only made during server startup, so the actual interval maybe much longer. Setting backup_interval to 0 will disable backups
:Available range: 0 to 30. Default - 3

====backup_copies====
:''<backup_copies>10</backup_copies>
:This parameter specifies the maximum number of backup copies to keep. Setting backup_copies to 0 will disable backups
:Available range: 0 to 100. Default - 10

====compact_internal_databases====
:''<compact_internal_databases>1</compact_internal_databases>
:This parameter specifies when the internal sqlite databases should be defragmented.
:For more info see: https://www.sqlite.org/lang_vacuum.html
:Values: 0 - Never, 1 - On server start only after basic backup, 2 - On server start always. Default - 1

====server_logic_fps_limit====
:''<server_logic_fps_limit>0</server_logic_fps_limit>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING'''
:Server logic FPS limit.
:Available range: 0 to 100. default value: 0

====crash_dump_upload====
:''<crash_dump_upload>1</crash_dump_upload>
:This parameter specifies whether server crash dump files should be sent to MTA HQ.
:Values: 0 - Off, 1 - On. Default - 1

====fakelag====

:''<fakelag>0</fakelag>
:This parameter specifies whether the [[Command fakelag|fakelag and sfakelag]] commands are enabled
:Values: 0 - Off, 1 - On. Default - 0

====auth_serial_groups====
:''<auth_serial_groups>Admin</auth_serial_groups>
:This parameter lists the ACL groups that are protected by serial authorization.
:Login attempts to a protected account from a second serial are blocked until the serial is manually authorized via the authserial command.
:For more info see: https://mtasa.com/authserial
:Note: This is security critical feature and disabling auth_serial_groups can affect visibility in the master server list.
:Values: Comma separated list of ACL groups. Default - Admin
:See [[Authorized Serial Account Protection]] for more information.

====auth_serial_http====
:''<auth_serial_http>1</auth_serial_http>
:This parameter specifies if the authorized serial login checks should also apply to the http interface.
:Protected account login attempts to the http interface will only succeed if the IP address matches one recently used by the account holder in-game.
:For more info see: https://mtasa.com/authserialhttp
:Note: This is security critical feature and disabling auth_serial_http can affect visibility in the master server list.
:Values: 0 - Off, 1 - Enabled. Default - 1

====auth_serial_http_ip_exceptions====
:''<auth_serial_http_ip_exceptions>127.0.0.1</auth_serial_http_ip_exceptions>
:This parameter specifies which IP addresses should always pass auth_serial_http checks.
:Values: Comma separated list of IP addresses

====database_credentials_protection====
:''<database_credentials_protection>1</database_credentials_protection>
:This parameter specifies if extra security measures are applied to resources which use [[dbConnect]] with MySQL.
:The extra measures are:
: - script files cannot be accessed with [[fileOpen]]
: - [[meta.xml]] is read-only
:'''NOTE:''' This only protects resources which use [[dbConnect]] with MySQL.
:Values: 0 - disabled, 1 - enabled; default - 1

{{New items|6.0160|1.6.0-22790|
====elementdata_whitelisted====
:''<elementdata_whitelisted>0</elementdata_whitelisted>
:Enables extra protection for [[SetElementData|element data]].
:When this option is enabled, the server ignores element data sync packets from the client, except for allowed keys.
:Values: 0 - disabled, 1 - enabled; default - 0
}}

{{New items|6.0160|1.6.0-22815|
====check_duplicate_serials====
:''<check_duplicate_serials>1</check_duplicate_serials>
:This parameter determines whether server will compare player serial on connection to any other serial present on server.
:When this option is enabled, the server will deny entry for player whose serial is already in use by other player on server. You might want to disable this when using VMs.
:Values: 0 - disabled, 1 - enabled; default - 1
}}

====player_triggered_event_interval====
:''<player_triggered_event_interval>1000</player_triggered_event_interval>
:Time interval for counting max (see below: max_player_triggered_events_per_interval) triggered events (via triggerServerEvent), exceeding this will call [[onPlayerTriggerEventThreshold]]
:Values: 50-5000; default: 1000 (in ms)

====max_player_triggered_events_per_interval====
:''<max_player_triggered_events_per_interval>100</max_player_triggered_events_per_interval>
:Max triggered amount of events (via triggerServerEvent) within interval above (player_triggered_event_interval), exceeding this will call [[onPlayerTriggerEventThreshold]]
:Values: 1-1000; default: 100

{{Added feature/item|1.6.1|1.6.0|22930|
====player_teleport_alert====
:''<player_teleport_alert>100</player_teleport_alert>
:Defines the maximum allowed unexpected position change (in units). If a player's position changes by more than this value without using [[setElementPosition]], the event [[onPlayerTeleport]] will be triggered.
:Values: 5-500; default: 100
}}

====module====
:''<nowiki></nowiki>
:''<nowiki></nowiki>
:Specifies the module(s) which are loaded with the server. To load several modules, add more <module> parameter(s). Optional parameter.

====resource_client_file_checks====

:''<resource_client_file_checks>1</resource_client_file_checks>
:If enabled, the server will perform checks on files in resources (listed in [[meta.xml]]) with PNG, TXD and DFF extensions, checking if they are corrupted. When the system finds a non-valid file of these types, it outputs a warning to the server console.
:You may want to disable thse checks when storing different/non-conforming data in files with these extensions (e.g. encrypted data).
:Values: 0 - Off, 1 - Enabled. Default - 1

====resource====
:''<resource src="admin" startup="1" protected="0" />
:''<resource src="defaultstats" startup="1" protected="0" />
:''<resource src="helpmanager" startup="1" protected="0" />
:''<resource src="joinquit" startup="1" protected="0" />
:''<resource src="mapcycler" startup="1" protected="0" />
:''<resource src="mapmanager" startup="1" protected="0" />
:''<resource src="parachute" startup="1" protected="0" />
:''<resource src="resourcebrowser" startup="1" protected="1" default="true" />
:''<resource src="resourcemanager" startup="1" protected="1" />
:''<resource src="scoreboard" startup="1" protected="0" />
:''<resource src="spawnmanager" startup="1" protected="0" />
:''<resource src="voice" startup="1" protected="0" />
:''<resource src="votemanager" startup="1" protected="0" />
:''<resource src="webadmin" startup="1" protected="0" />
:''<resource src="play" startup="1" protected="0" />
:''<resource src-"resources" startup"1" protected="0"
:Specifies persistent resources which are loaded when the server starts. Persistent resources are not stopped even if all the other resources that depend on them stop; that is, the only way to stop them is by explicitly using the ''stop'' server command or [[stopResource]] scripting function. To load several resources, add more <resource> parameters.

:In addition, there are several flags which control how the server deals with each resource:

:* '''src''': the resource name. This is the only mandatory flag.
:* '''startup''': controls whether the resource will be started with the server or not. If "1", "true" or "yes", the resource will be started. If not specified, defaults to not starting the resource.
:* '''protected''': if "1", "true" or "yes", the resource will not be able to be stopped when started. Otherwise, even if not specified, it will default to the normal behaviour.
:* '''default''': if given a "1", "true" or "yes" value, this resource will be the one who populates the built-in HTTP server main page, which is seen when no resource is given in the web address. It is not possible to have more than one default resource.

====busy_sleep_time====
:''<busy_sleep_time>-1</busy_sleep_time>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING''' - This parameter configures the server's sleep duration in milliseconds during busy processing, affecting CPU usage and responsiveness.
:Available range: -1 to 50; default value: -1
:-1 sets the server to automatically determine the optimal value based on workload.
:Setting it to 0 is recommended for achieving the best performance but may result in higher CPU usage.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]].

====idle_sleep_time====
:''<idle_sleep_time>-1</idle_sleep_time>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING''' - This parameter configures the server's sleep duration in milliseconds during idle periods, affecting CPU usage and responsiveness.
:Available range: -1 to 50; default value: -1
:-1 sets the server to automatically determine the optimal value based on workload.
:Setting it to 10 is recommended for achieving the best performance while balancing CPU usage.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]].

==Deprecated settings==

The following settings have been deprecated in the production version of MTA:SA and no longer work.

====networkencryption====

:''<networkencryption>1</networkencryption>
:This parameter specifies whether communications between the server and client is encrypted. Encryption can help prevent network data being viewed and modified.
:Values: 0 - disabled , 1 - enabled ; default value: 1. Optional parameter.
:This parameter can changed and saved while the server is running with [[setServerConfigSetting]]

====autologin====

:''<autologin>0</autologin>
:Specifies whether or not players should automatically be logged in based on their IP adresses.
:Values: 0 - disabled , 1 - enabled ; default value: 0.

====httpautoclientfiles====

:''<httpautoclientfiles>1</httpautoclientfiles>

[[Category: Support]]
[[ru:Server mtaserver.conf]]
[[pl:mtaserver.conf]]

Server mtaserver.conf

2025-06-05T07:06:28Z

Srslyyyy:

This page lists the settings that can be set in the settings file. ''Setting from the default '''mtaserver.conf''' settings file is in italics''.

==Settings==

====servername====
:''<servername>Default MTA Server</servername>''
:This parameter specifies the name the server will be visible as in the ingame server browser and on Game-Monitor. It is a required parameter.

====rule====
:''<rule name="NAME_HERE" value="VALUE_HERE"/>''
:The rule parameters are optional. There can be as many as you want in the config file. They contain information for the Server Browser/List. [[Server_Browser_Rules|Read this article for more information]].

====owner_email_address====
:''<owner_email_address></owner_email_address>''
:This parameter specifies the contact email addresses for the owner(s) of this server.
:The email addresses will not be publicly available, and only used by MTA administrators to contact the server owner.
:Note: Missing or incorrect owner_email_address can affect visibility in the master server list.
:Values: Comma separated list of email addresses

====serverip====
:''<serverip>auto</serverip>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING''' - it is generally only needed for complex network topologies and should be left at the default value otherwise.
: This parameter specifies the public IP address that the server will announce to the MTA servers, for the purposes of registering itself in the master server list and receiving some internal status updates. Usually, setting this parameter is only useful for some specialized scenarios, like servers that can be reached by multiple public addresses, or when a firewall is used for controlling incoming connections. If set to auto, the public IP address the requests originate from will be used as the server IP for communicating with MTA servers, which works fine in most cases.
:Values: auto or x.x.x.x ; default value: auto
:SERVERIP SHOULD BE LEFT SET TO auto UNLESS YOU ARE SURE OF WHAT YOU ARE DOING
:WARNING: SETTING serverip AND THEN ASKING FOR SUPPORT CAN CAUSE DEATH OR INJURY

====serverport====
:''<serverport>22003</serverport>
:This parameter specifies the UDP port on which the server will be accepting incoming player connections;
:default value: 22003. It is a required parameter.

====maxplayers====
:''<maxplayers>32</maxplayers>
:This parameter specifies the number of maximum player slots available on the server;
:default value: 32. It is a required parameter.

====httpserver====

:''<httpserver>1</httpserver>
:This parameter specifies whether the built-in http server will be used.
:Values: 0 - disabled , 1 - enabled ; default value: 1. Optional parameter.
:More information: [[Server_Manual#Using_the_web_interface|Using the web interface]]

====httpport====
:''<httpport>22005</httpport>
:This parameter specifies the TCP port on which the server will be accepting incoming http connections. It can be set to the same value as <serverport>. It is a required parameter if <httpserver> is set to 1.
:More information: [[Server_Manual#Using_the_web_interface|Using the web interface]]

====httpdownloadurl====
:''<httpdownloadurl></httpdownloadurl>
:If set, this parameter specifies the external URL from which clients will be able to download needed resources ingame. Otherwise they will download them directly from the server.
:More information: [[Server_Manual#Configuring_an_external_web_server|Configuring an external web server]]

====httpmaxconnectionsperclient====
:''<httpmaxconnectionsperclient>5</httpmaxconnectionsperclient>
:This parameter limits the number of http connections each client can make. Depending on the type of http server that is used, a lower figure may reduce download timeouts. Only relevant when using an external http server.
:Available range: 1 to 8.

====httpthreadcount====
:''<httpthreadcount>8</httpthreadcount>
:Number of HTTP server threads.
:Available range: 1 to 20. default value: 8

====httpdosthreshold====
:''<httpdosthreshold>20</httpdosthreshold>
:This parameter limits the number http connections that an IP can initiate over a short period of time.
:Available range: 1 to 100. default value: 20

====http_dos_exclude====
:''<http_dos_exclude></http_dos_exclude>
:This parameter lists the IP addresses that are to be excluded from http dos threshold limits.
:e.g. 88.11.22.33,101.2.3.4

====allow_gta3_img_mods====
:''<allow_gta3_img_mods>none</allow_gta3_img_mods>
:By default, the server will block the use of locally customized gta3.img player skins
:This setting can be used to allow such mods. Not recommended for competitive servers.
:Values: none, peds ; default value: none

====client_file====
:''<nowiki></nowiki>
:By default, the server will block the use of customized GTA:SA data files.
:To allow specific client files, add one or more of the above lines.
:More information: [[Anti-cheat_guide#.3Cclient_file_name.3D.22data.2Fcarmods.dat.22_verify.3D.220.22.2F.3E|Anti-cheat guide]]

====disableac====
:''<disableac></disableac>
:Comma separated list of disabled anti-cheats.
:e.g. To disable anti-cheat #2 and #3, use: 2,3
:More information: [[Anti-cheat_guide#.3Cdisableac.3E.3C.2Fdisableac.3E|Anti-cheat guide]]

====enablesd====
:''<enablesd>31,32</enablesd>
:Comma separated list of enabled special detections. A special detection is a type of anti-cheat for (usually) harmless game modifications.
:Competitive servers may wish to enable certain special detections, but most servers should leave this setting on its default.
:Values: special detection (SD) codes ; default value: 31,32 (e.g. enables special detections #31 and #32)
:More information: [[Anti-cheat_guide#.3Cenablesd.3E.3C.2Fenablesd.3E|Anti-cheat guide]]

====hideac====
:''<hideac>0</hideac>
:When this parameter is enabled client won't get any info about Anticheat settings when connecting to server.
:Values: 0 - disabled , 1 - enabled ; default value: 0. Optional parameter.

====minclientversion====
:''<minclientversion></minclientversion>
:Minimum client version. Clients with a lower version will not be allowed to connect. After disconnection, clients will be given an opportunity to download an update. If left blank, this setting is disabled and there are no restrictions on who can connect. Version numbers are described in [[getPlayerVersion]] and look like this: 1.6.0-9.22953.0
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:'''Note that this setting only determines if the client should be prompted to update. The actual build number they receive will be the [[https://nightly.mtasa.com/ver highest available]].'''

====minclientversion_auto_update====
:''<minclientversion_auto_update>1</minclientversion_auto_update>
:This parameter specifies if/when the <minclientversion> setting is automatically updated.
:Keeping <minclientversion> updated can help reduce cheating.
:Note: The instant setting (2) is only recommended for competitive servers.
:Values: 0 - disabled, 1 - enabled (delayed by a few days), 2 - enabled (instant) ; default value: 1.

====recommendedclientversion====
:''<recommendedclientversion></recommendedclientversion>
:Recommended client version. When connecting, if clients have a lower version, they will be given the option to download an update. If left blank, this setting is disabled.
:This parameter can changed and saved while the server is running with [[setServerConfigSetting]]
:'''Note that this setting only determines if the client should be prompted to update. The actual build number they receive will be the [[https://nightly.mtasa.com/ver highest available]].'''

====ase====
:''<ase>1</ase>
:This parameter can be used to make the server report to Game-Monitor master servers, allowing it to be visible in the in-game server browser. An additional UDP port needs to be available for this to work (value from <serverport> + 123 , so on a default <serverport> value 22003 the right port will be 22126 ).
:Available values: 0 - disabled , 1 - enabled. Optional parameter, defaults to 0.

====donotbroadcastlan====
:''<donotbroadcastlan>0</donotbroadcastlan>
:This parameter allows you to disable LAN broadcasting.

====password====
:''<password></password>
:If set, players will have to provide a password specified below, before they can connect to the server. If left blank, server doesn't require a password from them.
:This parameter can changed and saved while the server is running with [[setServerPassword]] or [[setServerConfigSetting]]

====net_auto_filter====
:''<net_auto_filter>1</net_auto_filter>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING'''
:Net auto filter.
:Values: 0 - disabled, 1 - enabled. default value: 1

====update_cycle_datagrams_limit====
:''<update_cycle_datagrams_limit>4</update_cycle_datagrams_limit>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING'''
:Send datagrams limit.
:Available range: 1 to 100. default value: 4

====update_cycle_messages_limit====
:''<update_cycle_messages_limit>50</update_cycle_messages_limit>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING'''
:Send messages limit.
:Available range: 10 to 1000. default value: 50

====bandwidth_reduction====
:''<bandwidth_reduction>medium</bandwidth_reduction>
:This parameter reduces the server's bandwidth usage by using various optimizations.
:Values: none, medium or maximum ; default value: medium
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====unoccupied_vehicle_syncer_distance====

:''<unoccupied_vehicle_syncer_distance>130</unoccupied_vehicle_syncer_distance>
:This parameter determines the distance limit for remote synced unoccupied vehicles
:Available range: 50 - 400; default value: 130
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====ped_syncer_distance====

:''<ped_syncer_distance>100</ped_syncer_distance>
:This parameter determines the distance limit for remote synced peds
:Available range: 50 - 400; default value: 100
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====player_sync_interval====
:''<player_sync_interval>100</player_sync_interval>
:This parameter determines the time in milliseconds between player sync packets.
:Available range: 50 - 4000; default value: 100
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====lightweight_sync_interval====
:''<lightweight_sync_interval>1500</lightweight_sync_interval>
:This parameter determines the time in milliseconds between lightweight (player) sync packets.
:Available range: 200 - 4000; default value: 1500
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====camera_sync_interval====
:''<camera_sync_interval>500</camera_sync_interval>
:This parameter determines the time in milliseconds between camera sync packets.
:Available range: 50 - 4000; default value: 500
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====ped_sync_interval====
:''<ped_sync_interval>500</ped_sync_interval>
:This parameter determines the time in milliseconds between ped sync packets when the ped is near the player.
:Available range: 50 - 4000; default value: 500
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====ped_far_sync_interval====
:''<ped_far_sync_interval>2000</ped_far_sync_interval>
:This parameter determines the time in milliseconds between ped sync packets when the ped is far away from the player.
:Available range: 50 - 4000; default value: 2000
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====unoccupied_vehicle_sync_interval====
:''<unoccupied_vehicle_sync_interval>400</unoccupied_vehicle_sync_interval>
:This parameter determines the time in milliseconds between unoccupied vehicle sync packets.
:Available range: 50 - 4000; default value: 400
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====keysync_mouse_sync_interval====
:''<keysync_mouse_sync_interval>100</keysync_mouse_sync_interval>
:This parameter determines the minimum time in milliseconds between key sync packets due to mouse movement.
:Available range: 50 - 4000; default value: 100
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====keysync_analog_sync_interval====
:''<keysync_analog_sync_interval>100</keysync_analog_sync_interval>
:This parameter determines the minimum time in milliseconds between key sync packets due to joystick movement.
:Available range: 50 - 4000; default value: 100
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====donkey_work_interval====
:''<donkey_work_interval>100</donkey_work_interval>
:Update near list interval in milliseconds.
:Available range: 50 to 4000. default value: 100

====bullet_sync====
:''<bullet_sync>1</bullet_sync>
:This parameter can improve the reliability of shots when using certain weapons. However, it uses more bandwidth.
:Note that bullet sync will be active regardless of this setting when certain [[setGlitchEnabled|glitches]] are enabled.
:Values: 0 - disabled , 1 - enabled ; default value: 1.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

{{Added feature/item|1.6.1|1.6.0|22430|
====vehicle_contact_sync_radius====
:''<vehicle_contact_sync_radius>30</vehicle_contact_sync_radius>
:This parameter specifies the radius in which any contact with a vehicle will turn the player into its syncer.
:Changing this setting to 0 will cause vehicles to not pick a new syncer based on which player is touching the vehicle.
:Available range: 0 to 130. Default - 30
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
}}

====vehext_percent====
:''<vehext_percent>0</vehext_percent>
:This parameter sets the amount of extrapolation that clients will apply to remote vehicles.
:This can reduce some of the latency induced location disparency by predicting where the remote vehicles will probably be.
:Depending on the gamemode, an incorrect prediction may have a negative effect.
:Therefore this setting should be considered experimental.
:Available range: 0 to 100. Default - 0

====vehext_ping_limit====
:''<vehext_ping_limit>150</vehext_ping_limit>
:This parameter places a limit on how much time (in milliseconds) the vehicle extrapolation will attempt to compensate for.
:Only relevant if <vehext_percent> is greater than zero.
:Available range: 50 to 500. Default - 150

====latency_reduction====
:''<latency_reduction>0</latency_reduction>
:This parameter can reduce the delay of player actions appearing on remote clients by 2 frames (approx 50ms).
:Due to the impact this may have on shot lag compensation, it should be considered experimental.
:Values: 0 - disabled , 1 - enabled ; default value: 0.
:Bugs caused by enabling latency_reduction: https://bugs.mtasa.com/view.php?id=8191 + https://bugs.mtasa.com/view.php?id=8226

====threadnet====

:''<threadnet>1</threadnet>
:This parameter specifies whether or not to run the network synchronization on another thread.
:Enabling will make the sync smoother, but may increase CPU usage slightly.
:Values: 0 - disabled , 1 - enabled ; default value: 1.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====idfile====
:''<idfile>server-id.keys</idfile>
:Specifies the location and file name of this servers unique private key. This is used to prevent private files saved on the client from being read by other servers.
:Keep a backup of this file in a safe place. Default value: server-id.keys
:More information about client private files: [[Filepath]]

====logfile====
:''<logfile>logs/server.log</logfile>
:Specifies the location and name of the main server log file. If left blank, server won't be saving this file.

====authfile====
:''<authfile>logs/server_auth.log</authfile>
:As well as the main log file, login successes and failures are logged here for easy reviewing of security issues. If left blank, this file is not used

====dbfile====
:''<dbfile>logs/db.log</dbfile>
:Specifies the location and name of the file used to log database queries. The server command [[Server_Commands#debugdb|debugdb]] sets the amount of logging.

====loadstringfile====
:''<nowiki></nowiki>
:Specifies the location and name of the file used to log loadstring function calls. If left blank or not set, no logging is done.

====acl====
:''<acl>acl.xml</acl>
:This parameter specifies the location and name of the Access Control List settings file. If left
:blank, server will use acl.xml file, located in the same folder as this configuration file.

====scriptdebuglogfile====
:''<scriptdebuglogfile>logs/scripts.log</scriptdebuglogfile>
:Specifies the location and name of the debugscript log file. If left blank, server won't be saving this file.

====scriptdebugloglevel====
:''<scriptdebugloglevel>0</scriptdebugloglevel>
:Specifies the level of the debugscript log file. Available values: 0, 1, 2, 3. When not set, defaults to 0.

====htmldebuglevel====
:''<htmldebuglevel>0</htmldebuglevel>
:Specifies the level of the html debug. Available values: 0, 1, 2, 3. When not set, defaults to 0.

====filter_duplicate_log_lines====
:''<filter_duplicate_log_lines>1</filter_duplicate_log_lines>
:Specifies whether or not duplicate log lines should be filtered. Available values: 0 or 1, defaults to 1.

====fpslimit====
:''<fpslimit>74</fpslimit>
:Specifies the frame rate limit that will be applied to connecting clients.
:Available range: 25 to 32767. Default: 74. You can also use 0 for uncapped fps.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====voice====
:''<voice>0</voice>
:This parameter specifies whether or not to enable player voice chat in-game
:Values: 0 - disabled , 1 - enabled

====voice_samplerate====
:''<voice_samplerate>1</voice_samplerate>
:This parameter specifies the sample rate for voice chat. 'voice' parameter must be set to 1 for this to be effective. Higher settings use more bandwidth and increase the sampling quality of voice chat
:Values: 0 - Narrowband (8kHz), 1 - Wideband (16kHz), 2 - Ultrawideband (32kHz). Default - 1

====voice_quality====
:''<voice_quality>4</voice_quality>
:This parameter specifies the voice quality for voice chat. 'voice' parameter must be set to 1 for this to be effective. Higher settings use more bandwidth and increase the the overall quality of voice chat
:Available range: 0 to 10. Default - 4

====voice_bitrate====
:''<nowiki></nowiki>
:Specifies the voice bitrate, in bps. This optional parameter overrides the previous two settings. If not set, MTA handles this automatically. Use with care.

====backup_path====
:''<backup_path>backups</backup_path>
:This parameter specifies the path to use for a basic backup of some server files. Note that basic backups are only made during server startup. Default value: backups

====backup_interval====
:''<backup_interval>3</backup_interval>
:This parameter specifies the number of days between each basic backup. Backups are only made during server startup, so the actual interval maybe much longer. Setting backup_interval to 0 will disable backups
:Available range: 0 to 30. Default - 3

====backup_copies====
:''<backup_copies>10</backup_copies>
:This parameter specifies the maximum number of backup copies to keep. Setting backup_copies to 0 will disable backups
:Available range: 0 to 100. Default - 10

====compact_internal_databases====
:''<compact_internal_databases>1</compact_internal_databases>
:This parameter specifies when the internal sqlite databases should be defragmented.
:For more info see: https://www.sqlite.org/lang_vacuum.html
:Values: 0 - Never, 1 - On server start only after basic backup, 2 - On server start always. Default - 1

====server_logic_fps_limit====
:''<server_logic_fps_limit>0</server_logic_fps_limit>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING'''
:Server logic FPS limit.
:Available range: 0 to 100. default value: 0

====crash_dump_upload====
:''<crash_dump_upload>1</crash_dump_upload>
:This parameter specifies whether server crash dump files should be sent to MTA HQ.
:Values: 0 - Off, 1 - On. Default - 1

====fakelag====

:''<fakelag>0</fakelag>
:This parameter specifies whether the [[Command fakelag|fakelag and sfakelag]] commands are enabled
:Values: 0 - Off, 1 - On. Default - 0

====auth_serial_groups====
:''<auth_serial_groups>Admin</auth_serial_groups>
:This parameter lists the ACL groups that are protected by serial authorization.
:Login attempts to a protected account from a second serial are blocked until the serial is manually authorized via the authserial command.
:For more info see: https://mtasa.com/authserial
:Note: This is security critical feature and disabling auth_serial_groups can affect visibility in the master server list.
:Values: Comma separated list of ACL groups. Default - Admin
:See [[Authorized Serial Account Protection]] for more information.

====auth_serial_http====
:''<auth_serial_http>1</auth_serial_http>
:This parameter specifies if the authorized serial login checks should also apply to the http interface.
:Protected account login attempts to the http interface will only succeed if the IP address matches one recently used by the account holder in-game.
:For more info see: https://mtasa.com/authserialhttp
:Note: This is security critical feature and disabling auth_serial_http can affect visibility in the master server list.
:Values: 0 - Off, 1 - Enabled. Default - 1

====auth_serial_http_ip_exceptions====
:''<auth_serial_http_ip_exceptions>127.0.0.1</auth_serial_http_ip_exceptions>
:This parameter specifies which IP addresses should always pass auth_serial_http checks.
:Values: Comma separated list of IP addresses

====database_credentials_protection====
:''<database_credentials_protection>1</database_credentials_protection>
:This parameter specifies if extra security measures are applied to resources which use [[dbConnect]] with MySQL.
:The extra measures are:
: - script files cannot be accessed with [[fileOpen]]
: - [[meta.xml]] is read-only
:'''NOTE:''' This only protects resources which use [[dbConnect]] with MySQL.
:Values: 0 - Off, 1 - Enabled. Default - 1

{{New items|6.0160|1.6.0-22790|
====elementdata_whitelisted====
:''<elementdata_whitelisted>0</elementdata_whitelisted>
:Enables extra protection for [[SetElementData|element data]].
:When this option is enabled, the server ignores element data sync packets from the client, except for allowed keys.
:Values: 0 - Off, 1 - Enabled. Default - 0
}}

{{New items|6.0160|1.6.0-22815|
====check_duplicate_serials====
:''<check_duplicate_serials>1</check_duplicate_serials>
:This parameter determines whether server will compare player serial on connection to any other serial present on server.
:When this option is enabled, the server will deny entry for player whose serial is already in use by other player on server. You might want to disable this when using VMs.
:Values: 0 - Off, 1 - Enabled. Default - 1
}}

====player_triggered_event_interval====
:''<player_triggered_event_interval>1000</player_triggered_event_interval>
:Time interval for counting max (see below: max_player_triggered_events_per_interval) triggered events (via triggerServerEvent), exceeding this will call [[onPlayerTriggerEventThreshold]]
:Values: 50-5000; default: 1000 (in ms)

====max_player_triggered_events_per_interval====
:''<max_player_triggered_events_per_interval>100</max_player_triggered_events_per_interval>
:Max triggered amount of events (via triggerServerEvent) within interval above (player_triggered_event_interval), exceeding this will call [[onPlayerTriggerEventThreshold]]
:Values: 1-1000; default: 100

{{Added feature/item|1.6.1|1.6.0|22930|
====player_teleport_alert====
:''<player_teleport_alert>100</player_teleport_alert>
:Defines the maximum allowed unexpected position change (in units). If a player's position changes by more than this value without using [[setElementPosition]], the event [[onPlayerTeleport]] will be triggered.
:Values: 5-500; default: 100
}}

====module====
:''<nowiki></nowiki>
:''<nowiki></nowiki>
:Specifies the module(s) which are loaded with the server. To load several modules, add more <module> parameter(s). Optional parameter.

====resource_client_file_checks====

:''<resource_client_file_checks>1</resource_client_file_checks>
:If enabled, the server will perform checks on files in resources (listed in [[meta.xml]]) with PNG, TXD and DFF extensions, checking if they are corrupted. When the system finds a non-valid file of these types, it outputs a warning to the server console.
:You may want to disable thse checks when storing different/non-conforming data in files with these extensions (e.g. encrypted data).
:Values: 0 - Off, 1 - Enabled. Default - 1

====resource====
:''<resource src="admin" startup="1" protected="0" />
:''<resource src="defaultstats" startup="1" protected="0" />
:''<resource src="helpmanager" startup="1" protected="0" />
:''<resource src="joinquit" startup="1" protected="0" />
:''<resource src="mapcycler" startup="1" protected="0" />
:''<resource src="mapmanager" startup="1" protected="0" />
:''<resource src="parachute" startup="1" protected="0" />
:''<resource src="resourcebrowser" startup="1" protected="1" default="true" />
:''<resource src="resourcemanager" startup="1" protected="1" />
:''<resource src="scoreboard" startup="1" protected="0" />
:''<resource src="spawnmanager" startup="1" protected="0" />
:''<resource src="voice" startup="1" protected="0" />
:''<resource src="votemanager" startup="1" protected="0" />
:''<resource src="webadmin" startup="1" protected="0" />
:''<resource src="play" startup="1" protected="0" />
:''<resource src-"resources" startup"1" protected="0"
:Specifies persistent resources which are loaded when the server starts. Persistent resources are not stopped even if all the other resources that depend on them stop; that is, the only way to stop them is by explicitly using the ''stop'' server command or [[stopResource]] scripting function. To load several resources, add more <resource> parameters.

:In addition, there are several flags which control how the server deals with each resource:

:* '''src''': the resource name. This is the only mandatory flag.
:* '''startup''': controls whether the resource will be started with the server or not. If "1", "true" or "yes", the resource will be started. If not specified, defaults to not starting the resource.
:* '''protected''': if "1", "true" or "yes", the resource will not be able to be stopped when started. Otherwise, even if not specified, it will default to the normal behaviour.
:* '''default''': if given a "1", "true" or "yes" value, this resource will be the one who populates the built-in HTTP server main page, which is seen when no resource is given in the web address. It is not possible to have more than one default resource.

====busy_sleep_time====
:''<busy_sleep_time>-1</busy_sleep_time>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING''' - This parameter configures the server's sleep duration in milliseconds during busy processing, affecting CPU usage and responsiveness.
:Available range: -1 to 50; default value: -1
:-1 sets the server to automatically determine the optimal value based on workload.
:Setting it to 0 is recommended for achieving the best performance but may result in higher CPU usage.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]].

====idle_sleep_time====
:''<idle_sleep_time>-1</idle_sleep_time>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING''' - This parameter configures the server's sleep duration in milliseconds during idle periods, affecting CPU usage and responsiveness.
:Available range: -1 to 50; default value: -1
:-1 sets the server to automatically determine the optimal value based on workload.
:Setting it to 10 is recommended for achieving the best performance while balancing CPU usage.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]].

==Deprecated settings==

The following settings have been deprecated in the production version of MTA:SA and no longer work.

====networkencryption====

:''<networkencryption>1</networkencryption>
:This parameter specifies whether communications between the server and client is encrypted. Encryption can help prevent network data being viewed and modified.
:Values: 0 - disabled , 1 - enabled ; default value: 1. Optional parameter.
:This parameter can changed and saved while the server is running with [[setServerConfigSetting]]

====autologin====

:''<autologin>0</autologin>
:Specifies whether or not players should automatically be logged in based on their IP adresses.
:Values: 0 - disabled , 1 - enabled ; default value: 0.

====httpautoclientfiles====

:''<httpautoclientfiles>1</httpautoclientfiles>

[[Category: Support]]
[[ru:Server mtaserver.conf]]
[[pl:mtaserver.conf]]

Server mtaserver.conf

2025-06-05T07:05:32Z

Srslyyyy: Add check_duplicate_serials by Nico (https://github.com/multitheftauto/mtasa-blue/pull/3854)

This page lists the settings that can be set in the settings file. ''Setting from the default '''mtaserver.conf''' settings file is in italics''.

==Settings==

====servername====
:''<servername>Default MTA Server</servername>''
:This parameter specifies the name the server will be visible as in the ingame server browser and on Game-Monitor. It is a required parameter.

====rule====
:''<rule name="NAME_HERE" value="VALUE_HERE"/>''
:The rule parameters are optional. There can be as many as you want in the config file. They contain information for the Server Browser/List. [[Server_Browser_Rules|Read this article for more information]].

====owner_email_address====
:''<owner_email_address></owner_email_address>''
:This parameter specifies the contact email addresses for the owner(s) of this server.
:The email addresses will not be publicly available, and only used by MTA administrators to contact the server owner.
:Note: Missing or incorrect owner_email_address can affect visibility in the master server list.
:Values: Comma separated list of email addresses

====serverip====
:''<serverip>auto</serverip>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING''' - it is generally only needed for complex network topologies and should be left at the default value otherwise.
: This parameter specifies the public IP address that the server will announce to the MTA servers, for the purposes of registering itself in the master server list and receiving some internal status updates. Usually, setting this parameter is only useful for some specialized scenarios, like servers that can be reached by multiple public addresses, or when a firewall is used for controlling incoming connections. If set to auto, the public IP address the requests originate from will be used as the server IP for communicating with MTA servers, which works fine in most cases.
:Values: auto or x.x.x.x ; default value: auto
:SERVERIP SHOULD BE LEFT SET TO auto UNLESS YOU ARE SURE OF WHAT YOU ARE DOING
:WARNING: SETTING serverip AND THEN ASKING FOR SUPPORT CAN CAUSE DEATH OR INJURY

====serverport====
:''<serverport>22003</serverport>
:This parameter specifies the UDP port on which the server will be accepting incoming player connections;
:default value: 22003. It is a required parameter.

====maxplayers====
:''<maxplayers>32</maxplayers>
:This parameter specifies the number of maximum player slots available on the server;
:default value: 32. It is a required parameter.

====httpserver====

:''<httpserver>1</httpserver>
:This parameter specifies whether the built-in http server will be used.
:Values: 0 - disabled , 1 - enabled ; default value: 1. Optional parameter.
:More information: [[Server_Manual#Using_the_web_interface|Using the web interface]]

====httpport====
:''<httpport>22005</httpport>
:This parameter specifies the TCP port on which the server will be accepting incoming http connections. It can be set to the same value as <serverport>. It is a required parameter if <httpserver> is set to 1.
:More information: [[Server_Manual#Using_the_web_interface|Using the web interface]]

====httpdownloadurl====
:''<httpdownloadurl></httpdownloadurl>
:If set, this parameter specifies the external URL from which clients will be able to download needed resources ingame. Otherwise they will download them directly from the server.
:More information: [[Server_Manual#Configuring_an_external_web_server|Configuring an external web server]]

====httpmaxconnectionsperclient====
:''<httpmaxconnectionsperclient>5</httpmaxconnectionsperclient>
:This parameter limits the number of http connections each client can make. Depending on the type of http server that is used, a lower figure may reduce download timeouts. Only relevant when using an external http server.
:Available range: 1 to 8.

====httpthreadcount====
:''<httpthreadcount>8</httpthreadcount>
:Number of HTTP server threads.
:Available range: 1 to 20. default value: 8

====httpdosthreshold====
:''<httpdosthreshold>20</httpdosthreshold>
:This parameter limits the number http connections that an IP can initiate over a short period of time.
:Available range: 1 to 100. default value: 20

====http_dos_exclude====
:''<http_dos_exclude></http_dos_exclude>
:This parameter lists the IP addresses that are to be excluded from http dos threshold limits.
:e.g. 88.11.22.33,101.2.3.4

====allow_gta3_img_mods====
:''<allow_gta3_img_mods>none</allow_gta3_img_mods>
:By default, the server will block the use of locally customized gta3.img player skins
:This setting can be used to allow such mods. Not recommended for competitive servers.
:Values: none, peds ; default value: none

====client_file====
:''<nowiki></nowiki>
:By default, the server will block the use of customized GTA:SA data files.
:To allow specific client files, add one or more of the above lines.
:More information: [[Anti-cheat_guide#.3Cclient_file_name.3D.22data.2Fcarmods.dat.22_verify.3D.220.22.2F.3E|Anti-cheat guide]]

====disableac====
:''<disableac></disableac>
:Comma separated list of disabled anti-cheats.
:e.g. To disable anti-cheat #2 and #3, use: 2,3
:More information: [[Anti-cheat_guide#.3Cdisableac.3E.3C.2Fdisableac.3E|Anti-cheat guide]]

====enablesd====
:''<enablesd>31,32</enablesd>
:Comma separated list of enabled special detections. A special detection is a type of anti-cheat for (usually) harmless game modifications.
:Competitive servers may wish to enable certain special detections, but most servers should leave this setting on its default.
:Values: special detection (SD) codes ; default value: 31,32 (e.g. enables special detections #31 and #32)
:More information: [[Anti-cheat_guide#.3Cenablesd.3E.3C.2Fenablesd.3E|Anti-cheat guide]]

====hideac====
:''<hideac>0</hideac>
:When this parameter is enabled client won't get any info about Anticheat settings when connecting to server.
:Values: 0 - disabled , 1 - enabled ; default value: 0. Optional parameter.

====minclientversion====
:''<minclientversion></minclientversion>
:Minimum client version. Clients with a lower version will not be allowed to connect. After disconnection, clients will be given an opportunity to download an update. If left blank, this setting is disabled and there are no restrictions on who can connect. Version numbers are described in [[getPlayerVersion]] and look like this: 1.6.0-9.22953.0
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:'''Note that this setting only determines if the client should be prompted to update. The actual build number they receive will be the [[https://nightly.mtasa.com/ver highest available]].'''

====minclientversion_auto_update====
:''<minclientversion_auto_update>1</minclientversion_auto_update>
:This parameter specifies if/when the <minclientversion> setting is automatically updated.
:Keeping <minclientversion> updated can help reduce cheating.
:Note: The instant setting (2) is only recommended for competitive servers.
:Values: 0 - disabled, 1 - enabled (delayed by a few days), 2 - enabled (instant) ; default value: 1.

====recommendedclientversion====
:''<recommendedclientversion></recommendedclientversion>
:Recommended client version. When connecting, if clients have a lower version, they will be given the option to download an update. If left blank, this setting is disabled.
:This parameter can changed and saved while the server is running with [[setServerConfigSetting]]
:'''Note that this setting only determines if the client should be prompted to update. The actual build number they receive will be the [[https://nightly.mtasa.com/ver highest available]].'''

====ase====
:''<ase>1</ase>
:This parameter can be used to make the server report to Game-Monitor master servers, allowing it to be visible in the in-game server browser. An additional UDP port needs to be available for this to work (value from <serverport> + 123 , so on a default <serverport> value 22003 the right port will be 22126 ).
:Available values: 0 - disabled , 1 - enabled. Optional parameter, defaults to 0.

====donotbroadcastlan====
:''<donotbroadcastlan>0</donotbroadcastlan>
:This parameter allows you to disable LAN broadcasting.

====password====
:''<password></password>
:If set, players will have to provide a password specified below, before they can connect to the server. If left blank, server doesn't require a password from them.
:This parameter can changed and saved while the server is running with [[setServerPassword]] or [[setServerConfigSetting]]

====net_auto_filter====
:''<net_auto_filter>1</net_auto_filter>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING'''
:Net auto filter.
:Values: 0 - disabled, 1 - enabled. default value: 1

====update_cycle_datagrams_limit====
:''<update_cycle_datagrams_limit>4</update_cycle_datagrams_limit>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING'''
:Send datagrams limit.
:Available range: 1 to 100. default value: 4

====update_cycle_messages_limit====
:''<update_cycle_messages_limit>50</update_cycle_messages_limit>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING'''
:Send messages limit.
:Available range: 10 to 1000. default value: 50

====bandwidth_reduction====
:''<bandwidth_reduction>medium</bandwidth_reduction>
:This parameter reduces the server's bandwidth usage by using various optimizations.
:Values: none, medium or maximum ; default value: medium
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====unoccupied_vehicle_syncer_distance====

:''<unoccupied_vehicle_syncer_distance>130</unoccupied_vehicle_syncer_distance>
:This parameter determines the distance limit for remote synced unoccupied vehicles
:Available range: 50 - 400; default value: 130
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====ped_syncer_distance====

:''<ped_syncer_distance>100</ped_syncer_distance>
:This parameter determines the distance limit for remote synced peds
:Available range: 50 - 400; default value: 100
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====player_sync_interval====
:''<player_sync_interval>100</player_sync_interval>
:This parameter determines the time in milliseconds between player sync packets.
:Available range: 50 - 4000; default value: 100
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====lightweight_sync_interval====
:''<lightweight_sync_interval>1500</lightweight_sync_interval>
:This parameter determines the time in milliseconds between lightweight (player) sync packets.
:Available range: 200 - 4000; default value: 1500
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====camera_sync_interval====
:''<camera_sync_interval>500</camera_sync_interval>
:This parameter determines the time in milliseconds between camera sync packets.
:Available range: 50 - 4000; default value: 500
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====ped_sync_interval====
:''<ped_sync_interval>500</ped_sync_interval>
:This parameter determines the time in milliseconds between ped sync packets when the ped is near the player.
:Available range: 50 - 4000; default value: 500
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====ped_far_sync_interval====
:''<ped_far_sync_interval>2000</ped_far_sync_interval>
:This parameter determines the time in milliseconds between ped sync packets when the ped is far away from the player.
:Available range: 50 - 4000; default value: 2000
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====unoccupied_vehicle_sync_interval====
:''<unoccupied_vehicle_sync_interval>400</unoccupied_vehicle_sync_interval>
:This parameter determines the time in milliseconds between unoccupied vehicle sync packets.
:Available range: 50 - 4000; default value: 400
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====keysync_mouse_sync_interval====
:''<keysync_mouse_sync_interval>100</keysync_mouse_sync_interval>
:This parameter determines the minimum time in milliseconds between key sync packets due to mouse movement.
:Available range: 50 - 4000; default value: 100
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====keysync_analog_sync_interval====
:''<keysync_analog_sync_interval>100</keysync_analog_sync_interval>
:This parameter determines the minimum time in milliseconds between key sync packets due to joystick movement.
:Available range: 50 - 4000; default value: 100
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
:Suggested values for this and the other sync_interval settings can be found here: [[Sync_interval_settings|Sync interval settings]]

====donkey_work_interval====
:''<donkey_work_interval>100</donkey_work_interval>
:Update near list interval in milliseconds.
:Available range: 50 to 4000. default value: 100

====bullet_sync====
:''<bullet_sync>1</bullet_sync>
:This parameter can improve the reliability of shots when using certain weapons. However, it uses more bandwidth.
:Note that bullet sync will be active regardless of this setting when certain [[setGlitchEnabled|glitches]] are enabled.
:Values: 0 - disabled , 1 - enabled ; default value: 1.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

{{Added feature/item|1.6.1|1.6.0|22430|
====vehicle_contact_sync_radius====
:''<vehicle_contact_sync_radius>30</vehicle_contact_sync_radius>
:This parameter specifies the radius in which any contact with a vehicle will turn the player into its syncer.
:Changing this setting to 0 will cause vehicles to not pick a new syncer based on which player is touching the vehicle.
:Available range: 0 to 130. Default - 30
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]
}}

====vehext_percent====
:''<vehext_percent>0</vehext_percent>
:This parameter sets the amount of extrapolation that clients will apply to remote vehicles.
:This can reduce some of the latency induced location disparency by predicting where the remote vehicles will probably be.
:Depending on the gamemode, an incorrect prediction may have a negative effect.
:Therefore this setting should be considered experimental.
:Available range: 0 to 100. Default - 0

====vehext_ping_limit====
:''<vehext_ping_limit>150</vehext_ping_limit>
:This parameter places a limit on how much time (in milliseconds) the vehicle extrapolation will attempt to compensate for.
:Only relevant if <vehext_percent> is greater than zero.
:Available range: 50 to 500. Default - 150

====latency_reduction====
:''<latency_reduction>0</latency_reduction>
:This parameter can reduce the delay of player actions appearing on remote clients by 2 frames (approx 50ms).
:Due to the impact this may have on shot lag compensation, it should be considered experimental.
:Values: 0 - disabled , 1 - enabled ; default value: 0.
:Bugs caused by enabling latency_reduction: https://bugs.mtasa.com/view.php?id=8191 + https://bugs.mtasa.com/view.php?id=8226

====threadnet====

:''<threadnet>1</threadnet>
:This parameter specifies whether or not to run the network synchronization on another thread.
:Enabling will make the sync smoother, but may increase CPU usage slightly.
:Values: 0 - disabled , 1 - enabled ; default value: 1.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====idfile====
:''<idfile>server-id.keys</idfile>
:Specifies the location and file name of this servers unique private key. This is used to prevent private files saved on the client from being read by other servers.
:Keep a backup of this file in a safe place. Default value: server-id.keys
:More information about client private files: [[Filepath]]

====logfile====
:''<logfile>logs/server.log</logfile>
:Specifies the location and name of the main server log file. If left blank, server won't be saving this file.

====authfile====
:''<authfile>logs/server_auth.log</authfile>
:As well as the main log file, login successes and failures are logged here for easy reviewing of security issues. If left blank, this file is not used

====dbfile====
:''<dbfile>logs/db.log</dbfile>
:Specifies the location and name of the file used to log database queries. The server command [[Server_Commands#debugdb|debugdb]] sets the amount of logging.

====loadstringfile====
:''<nowiki></nowiki>
:Specifies the location and name of the file used to log loadstring function calls. If left blank or not set, no logging is done.

====acl====
:''<acl>acl.xml</acl>
:This parameter specifies the location and name of the Access Control List settings file. If left
:blank, server will use acl.xml file, located in the same folder as this configuration file.

====scriptdebuglogfile====
:''<scriptdebuglogfile>logs/scripts.log</scriptdebuglogfile>
:Specifies the location and name of the debugscript log file. If left blank, server won't be saving this file.

====scriptdebugloglevel====
:''<scriptdebugloglevel>0</scriptdebugloglevel>
:Specifies the level of the debugscript log file. Available values: 0, 1, 2, 3. When not set, defaults to 0.

====htmldebuglevel====
:''<htmldebuglevel>0</htmldebuglevel>
:Specifies the level of the html debug. Available values: 0, 1, 2, 3. When not set, defaults to 0.

====filter_duplicate_log_lines====
:''<filter_duplicate_log_lines>1</filter_duplicate_log_lines>
:Specifies whether or not duplicate log lines should be filtered. Available values: 0 or 1, defaults to 1.

====fpslimit====
:''<fpslimit>74</fpslimit>
:Specifies the frame rate limit that will be applied to connecting clients.
:Available range: 25 to 32767. Default: 74. You can also use 0 for uncapped fps.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]]

====voice====
:''<voice>0</voice>
:This parameter specifies whether or not to enable player voice chat in-game
:Values: 0 - disabled , 1 - enabled

====voice_samplerate====
:''<voice_samplerate>1</voice_samplerate>
:This parameter specifies the sample rate for voice chat. 'voice' parameter must be set to 1 for this to be effective. Higher settings use more bandwidth and increase the sampling quality of voice chat
:Values: 0 - Narrowband (8kHz), 1 - Wideband (16kHz), 2 - Ultrawideband (32kHz). Default - 1

====voice_quality====
:''<voice_quality>4</voice_quality>
:This parameter specifies the voice quality for voice chat. 'voice' parameter must be set to 1 for this to be effective. Higher settings use more bandwidth and increase the the overall quality of voice chat
:Available range: 0 to 10. Default - 4

====voice_bitrate====
:''<nowiki></nowiki>
:Specifies the voice bitrate, in bps. This optional parameter overrides the previous two settings. If not set, MTA handles this automatically. Use with care.

====backup_path====
:''<backup_path>backups</backup_path>
:This parameter specifies the path to use for a basic backup of some server files. Note that basic backups are only made during server startup. Default value: backups

====backup_interval====
:''<backup_interval>3</backup_interval>
:This parameter specifies the number of days between each basic backup. Backups are only made during server startup, so the actual interval maybe much longer. Setting backup_interval to 0 will disable backups
:Available range: 0 to 30. Default - 3

====backup_copies====
:''<backup_copies>10</backup_copies>
:This parameter specifies the maximum number of backup copies to keep. Setting backup_copies to 0 will disable backups
:Available range: 0 to 100. Default - 10

====compact_internal_databases====
:''<compact_internal_databases>1</compact_internal_databases>
:This parameter specifies when the internal sqlite databases should be defragmented.
:For more info see: https://www.sqlite.org/lang_vacuum.html
:Values: 0 - Never, 1 - On server start only after basic backup, 2 - On server start always. Default - 1

====server_logic_fps_limit====
:''<server_logic_fps_limit>0</server_logic_fps_limit>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING'''
:Server logic FPS limit.
:Available range: 0 to 100. default value: 0

====crash_dump_upload====
:''<crash_dump_upload>1</crash_dump_upload>
:This parameter specifies whether server crash dump files should be sent to MTA HQ.
:Values: 0 - Off, 1 - On. Default - 1

====fakelag====

:''<fakelag>0</fakelag>
:This parameter specifies whether the [[Command fakelag|fakelag and sfakelag]] commands are enabled
:Values: 0 - Off, 1 - On. Default - 0

====auth_serial_groups====
:''<auth_serial_groups>Admin</auth_serial_groups>
:This parameter lists the ACL groups that are protected by serial authorization.
:Login attempts to a protected account from a second serial are blocked until the serial is manually authorized via the authserial command.
:For more info see: https://mtasa.com/authserial
:Note: This is security critical feature and disabling auth_serial_groups can affect visibility in the master server list.
:Values: Comma separated list of ACL groups. Default - Admin
:See [[Authorized Serial Account Protection]] for more information.

====auth_serial_http====
:''<auth_serial_http>1</auth_serial_http>
:This parameter specifies if the authorized serial login checks should also apply to the http interface.
:Protected account login attempts to the http interface will only succeed if the IP address matches one recently used by the account holder in-game.
:For more info see: https://mtasa.com/authserialhttp
:Note: This is security critical feature and disabling auth_serial_http can affect visibility in the master server list.
:Values: 0 - Off, 1 - Enabled. Default - 1

====auth_serial_http_ip_exceptions====
:''<auth_serial_http_ip_exceptions>127.0.0.1</auth_serial_http_ip_exceptions>
:This parameter specifies which IP addresses should always pass auth_serial_http checks.
:Values: Comma separated list of IP addresses

====database_credentials_protection====
:''<database_credentials_protection>1</database_credentials_protection>
:This parameter specifies if extra security measures are applied to resources which use [[dbConnect]] with MySQL.
:The extra measures are:
: - script files cannot be accessed with [[fileOpen]]
: - [[meta.xml]] is read-only
:'''NOTE:''' This only protects resources which use [[dbConnect]] with MySQL.
:Values: 0 - Off, 1 - Enabled. Default - 1

{{New items|6.0160|1.6.0-22790|
====elementdata_whitelisted====
:''<elementdata_whitelisted>0</elementdata_whitelisted>
:Enables extra protection for [[SetElementData|element data]].
:When this option is enabled, the server ignores element data sync packets from the client, except for allowed keys.
:Values: 0 - Off, 1 - Enabled. Default - 0
}}

{{New items|6.0160|1.6.0-22815|
====check_duplicate_serials====
:''<check_duplicate_serials>1</check_duplicate_serials>
:This parameter determines whether server will compare player serial on player connection to any other serial present on server.
:When this option is enabled, the server will deny entry for player whose serial is already in use by other player on server. You might want to disable this when using VMs.
:Values: 0 - Off, 1 - Enabled. Default - 1
}}

====player_triggered_event_interval====
:''<player_triggered_event_interval>1000</player_triggered_event_interval>
:Time interval for counting max (see below: max_player_triggered_events_per_interval) triggered events (via triggerServerEvent), exceeding this will call [[onPlayerTriggerEventThreshold]]
:Values: 50-5000; default: 1000 (in ms)

====max_player_triggered_events_per_interval====
:''<max_player_triggered_events_per_interval>100</max_player_triggered_events_per_interval>
:Max triggered amount of events (via triggerServerEvent) within interval above (player_triggered_event_interval), exceeding this will call [[onPlayerTriggerEventThreshold]]
:Values: 1-1000; default: 100

{{Added feature/item|1.6.1|1.6.0|22930|
====player_teleport_alert====
:''<player_teleport_alert>100</player_teleport_alert>
:Defines the maximum allowed unexpected position change (in units). If a player's position changes by more than this value without using [[setElementPosition]], the event [[onPlayerTeleport]] will be triggered.
:Values: 5-500; default: 100
}}

====module====
:''<nowiki></nowiki>
:''<nowiki></nowiki>
:Specifies the module(s) which are loaded with the server. To load several modules, add more <module> parameter(s). Optional parameter.

====resource_client_file_checks====

:''<resource_client_file_checks>1</resource_client_file_checks>
:If enabled, the server will perform checks on files in resources (listed in [[meta.xml]]) with PNG, TXD and DFF extensions, checking if they are corrupted. When the system finds a non-valid file of these types, it outputs a warning to the server console.
:You may want to disable thse checks when storing different/non-conforming data in files with these extensions (e.g. encrypted data).
:Values: 0 - Off, 1 - Enabled. Default - 1

====resource====
:''<resource src="admin" startup="1" protected="0" />
:''<resource src="defaultstats" startup="1" protected="0" />
:''<resource src="helpmanager" startup="1" protected="0" />
:''<resource src="joinquit" startup="1" protected="0" />
:''<resource src="mapcycler" startup="1" protected="0" />
:''<resource src="mapmanager" startup="1" protected="0" />
:''<resource src="parachute" startup="1" protected="0" />
:''<resource src="resourcebrowser" startup="1" protected="1" default="true" />
:''<resource src="resourcemanager" startup="1" protected="1" />
:''<resource src="scoreboard" startup="1" protected="0" />
:''<resource src="spawnmanager" startup="1" protected="0" />
:''<resource src="voice" startup="1" protected="0" />
:''<resource src="votemanager" startup="1" protected="0" />
:''<resource src="webadmin" startup="1" protected="0" />
:''<resource src="play" startup="1" protected="0" />
:''<resource src-"resources" startup"1" protected="0"
:Specifies persistent resources which are loaded when the server starts. Persistent resources are not stopped even if all the other resources that depend on them stop; that is, the only way to stop them is by explicitly using the ''stop'' server command or [[stopResource]] scripting function. To load several resources, add more <resource> parameters.

:In addition, there are several flags which control how the server deals with each resource:

:* '''src''': the resource name. This is the only mandatory flag.
:* '''startup''': controls whether the resource will be started with the server or not. If "1", "true" or "yes", the resource will be started. If not specified, defaults to not starting the resource.
:* '''protected''': if "1", "true" or "yes", the resource will not be able to be stopped when started. Otherwise, even if not specified, it will default to the normal behaviour.
:* '''default''': if given a "1", "true" or "yes" value, this resource will be the one who populates the built-in HTTP server main page, which is seen when no resource is given in the web address. It is not possible to have more than one default resource.

====busy_sleep_time====
:''<busy_sleep_time>-1</busy_sleep_time>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING''' - This parameter configures the server's sleep duration in milliseconds during busy processing, affecting CPU usage and responsiveness.
:Available range: -1 to 50; default value: -1
:-1 sets the server to automatically determine the optimal value based on workload.
:Setting it to 0 is recommended for achieving the best performance but may result in higher CPU usage.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]].

====idle_sleep_time====
:''<idle_sleep_time>-1</idle_sleep_time>
:'''ONLY USE THIS PARAMETER IF YOU ARE SURE OF WHAT YOU ARE DOING''' - This parameter configures the server's sleep duration in milliseconds during idle periods, affecting CPU usage and responsiveness.
:Available range: -1 to 50; default value: -1
:-1 sets the server to automatically determine the optimal value based on workload.
:Setting it to 10 is recommended for achieving the best performance while balancing CPU usage.
:This parameter can be changed and saved while the server is running with [[setServerConfigSetting]].

==Deprecated settings==

The following settings have been deprecated in the production version of MTA:SA and no longer work.

====networkencryption====

:''<networkencryption>1</networkencryption>
:This parameter specifies whether communications between the server and client is encrypted. Encryption can help prevent network data being viewed and modified.
:Values: 0 - disabled , 1 - enabled ; default value: 1. Optional parameter.
:This parameter can changed and saved while the server is running with [[setServerConfigSetting]]

====autologin====

:''<autologin>0</autologin>
:Specifies whether or not players should automatically be logged in based on their IP adresses.
:Values: 0 - disabled , 1 - enabled ; default value: 0.

====httpautoclientfiles====

:''<httpautoclientfiles>1</httpautoclientfiles>

[[Category: Support]]
[[ru:Server mtaserver.conf]]
[[pl:mtaserver.conf]]

OnClientPlayerWeaponFire

2025-06-05T05:19:34Z

Srslyyyy: /* Example */

{{Client event}}
__NOTOC__
This event is called when a player fires a weapon. This event does not trigger for melee weapons. Projectile weapons or the camera will only trigger the event if fired by the local player.
{{Note|This event is only triggered for players that are streamed in}}
{{Note|This does not trigger for any player's melee weapons or for remote player's projectile weapons or cameras}}
==Parameters==
<syntaxhighlight lang="lua">
int weapon, int ammo, int ammoInClip, float hitX, float hitY, float hitZ, element hitElement, float startX, float startY, float startZ
</syntaxhighlight>
*'''weapon''': an [[int]] representing [[weapons|weapon]] used for firing a shot.
*'''ammo''': an [[int]] amount of ammo left for this weapon type.
*'''ammoInClip''': an [[int]] amount of ammo left for this weapon type in clip.
*'''hitX''': [[float]] world X coordinate representing the hit point.
*'''hitY''': [[float]] world Y coordinate representing the hit point.
*'''hitZ''': [[float]] world Z coordinate representing the hit point.
*'''hitElement''': an [[element]] which was hit by a shot.
{{New feature/item|3.0131|1.3.1|4311|
*'''startX''': [[float]] world X coordinate representing the start of the bullet. Note: This is not the gun muzzle.
*'''startY''': [[float]] world Y coordinate representing the start of the bullet.
*'''startZ''': [[float]] world Z coordinate representing the start of the bullet.
}}

==Source==
The [[event system#Event source|source]] of this event is the streamed in [[player]] who fired the weapon.

==Example==
This example implements custom gunshot sounds.
<syntaxhighlight lang="lua">
local playerWeaponSounds = {
[22] = "sounds/weap/colt45.wav",
[23] = "sounds/weap/silenced.wav",
[24] = "sounds/weap/deagle.wav",
[25] = "sounds/weap/shotgun.wav",
[26] = "sounds/weap/sawed-off.wav",
[27] = "sounds/weap/combat shotgun.wav",
[28] = "sounds/weap/uzi.wav",
[30] = "sounds/weap/ak-47.wav",
[31] = "sounds/weap/m4.wav",
[32] = "sounds/weap/tec9.wav",
[34] = "sounds/weap/sniper.wav",
}

local function playCustomWeaponSound(weaponID)
local playerWeaponSoundPath = playerWeaponSounds[weaponID]

if (not playerWeaponSoundPath) then
return false
end

local playerMuzzleX, playerMuzzleY, playerMuzzleZ = getPedWeaponMuzzlePosition(source)
local playerWeaponSound = playSound3D(playerWeaponSoundPath, playerMuzzleX, playerMuzzleY, playerMuzzleZ)

if (not playerWeaponSound) then
return false
end

setSoundMaxDistance(playerWeaponSound, 90)
setSoundVolume(playerWeaponSound, 0.6)
end
addEventHandler("onClientPlayerWeaponFire", root, playCustomWeaponSound)
</syntaxhighlight>

This example sends a warning to the local player if they shoot another player with a minigun.
<syntaxhighlight lang="lua">
--First, we create a function for the event handler to use.
function onClientPlayerWeaponFireFunc(weapon, ammo, ammoInClip, hitX, hitY, hitZ, hitElement )
if weapon == 38 and getElementType(hitElement)=="player" then -- If the player shoots with a minigun, and hits another player...
outputChatBox ( "Don't kill people with minigun, it's lame!", 255, 0, 0 ) -- We output a warning to him.
end
end
-- Add this as a handler so that the function will be triggered every time the local player fires.
addEventHandler ( "onClientPlayerWeaponFire", localPlayer, onClientPlayerWeaponFireFunc )
</syntaxhighlight>

This example makes the Shotgun fire explosive rounds.
<syntaxhighlight lang="lua">
function onClientPlayerWeaponFireFunc(weapon, ammo, ammoInClip, hitX, hitY, hitZ, hitElement)
if (weapon == 25) then -- If the player shoots with a shotgun
createExplosion(hitX, hitY, hitZ, 12, true, 0, true) -- Creates a tiny explosion where the bullet hit.
end
end
-- Add this as a handler so that the function will be triggered every time a player fires.
addEventHandler("onClientPlayerWeaponFire", root, onClientPlayerWeaponFireFunc)
</syntaxhighlight>

==See Also==
===Client player events===
{{Client_player_events}}
===Client event functions===
{{Client_event_functions}}

OnClientPlayerWeaponFire

2025-06-05T05:19:05Z

Srslyyyy: /* Example */

{{Client event}}
__NOTOC__
This event is called when a player fires a weapon. This event does not trigger for melee weapons. Projectile weapons or the camera will only trigger the event if fired by the local player.
{{Note|This event is only triggered for players that are streamed in}}
{{Note|This does not trigger for any player's melee weapons or for remote player's projectile weapons or cameras}}
==Parameters==
<syntaxhighlight lang="lua">
int weapon, int ammo, int ammoInClip, float hitX, float hitY, float hitZ, element hitElement, float startX, float startY, float startZ
</syntaxhighlight>
*'''weapon''': an [[int]] representing [[weapons|weapon]] used for firing a shot.
*'''ammo''': an [[int]] amount of ammo left for this weapon type.
*'''ammoInClip''': an [[int]] amount of ammo left for this weapon type in clip.
*'''hitX''': [[float]] world X coordinate representing the hit point.
*'''hitY''': [[float]] world Y coordinate representing the hit point.
*'''hitZ''': [[float]] world Z coordinate representing the hit point.
*'''hitElement''': an [[element]] which was hit by a shot.
{{New feature/item|3.0131|1.3.1|4311|
*'''startX''': [[float]] world X coordinate representing the start of the bullet. Note: This is not the gun muzzle.
*'''startY''': [[float]] world Y coordinate representing the start of the bullet.
*'''startZ''': [[float]] world Z coordinate representing the start of the bullet.
}}

==Source==
The [[event system#Event source|source]] of this event is the streamed in [[player]] who fired the weapon.

==Example==
This example implements custom gunshot sounds.
<syntaxhighlight lang="lua">
local playerWeaponSounds = {
[22] = "sounds/weap/colt45.wav",
[23] = "sounds/weap/silenced.wav",
[24] = "sounds/weap/deagle.wav",
[25] = "sounds/weap/shotgun.wav",
[26] = "sounds/weap/sawed-off.wav",
[27] = "sounds/weap/combat shotgun.wav",
[28] = "sounds/weap/uzi.wav",
[30] = "sounds/weap/ak-47.wav",
[31] = "sounds/weap/m4.wav",
[32] = "sounds/weap/tec9.wav",
[34] = "sounds/weap/sniper.wav",
}

local function playCustomWeaponSound(weaponID)
local playerWeaponSoundPath = playerWeaponSounds[weaponID]

if (not playerWeaponSoundPath) then
return false
end

local playerMuzzleX, playerMuzzleY, playerMuzzleZ = getPedWeaponMuzzlePosition(source)
local playerWeaponSound = playSound3D(playerWeaponSoundPath, playerMuzzleX, playerMuzzleY, playerMuzzleZ)

if (not playerWeaponCustomSoundPath) then
return false
end

setSoundMaxDistance(playerWeaponSound, 90)
setSoundVolume(playerWeaponSound, 0.6)
end
addEventHandler("onClientPlayerWeaponFire", root, playCustomWeaponSound)
</syntaxhighlight>

This example sends a warning to the local player if they shoot another player with a minigun.
<syntaxhighlight lang="lua">
--First, we create a function for the event handler to use.
function onClientPlayerWeaponFireFunc(weapon, ammo, ammoInClip, hitX, hitY, hitZ, hitElement )
if weapon == 38 and getElementType(hitElement)=="player" then -- If the player shoots with a minigun, and hits another player...
outputChatBox ( "Don't kill people with minigun, it's lame!", 255, 0, 0 ) -- We output a warning to him.
end
end
-- Add this as a handler so that the function will be triggered every time the local player fires.
addEventHandler ( "onClientPlayerWeaponFire", localPlayer, onClientPlayerWeaponFireFunc )
</syntaxhighlight>

This example makes the Shotgun fire explosive rounds.
<syntaxhighlight lang="lua">
function onClientPlayerWeaponFireFunc(weapon, ammo, ammoInClip, hitX, hitY, hitZ, hitElement)
if (weapon == 25) then -- If the player shoots with a shotgun
createExplosion(hitX, hitY, hitZ, 12, true, 0, true) -- Creates a tiny explosion where the bullet hit.
end
end
-- Add this as a handler so that the function will be triggered every time a player fires.
addEventHandler("onClientPlayerWeaponFire", root, onClientPlayerWeaponFireFunc)
</syntaxhighlight>

==See Also==
===Client player events===
{{Client_player_events}}
===Client event functions===
{{Client_event_functions}}

ShowCursor

2025-05-22T06:35:31Z

Srslyyyy:

__NOTOC__
{{Server client function}}
This function is used to show or hide a [[player]]'s cursor.
{{Note|Regardless of the cursor state you set using this function, the cursor will always be visible while the menu, the chatbox input line or the console are active, or if another resource has called this function.}}
{{Note| Be aware of that if showCursor enbaled by a resource you can't disabled it from a different ressource showCursor(false) will not works, in order to make it works, disable it from the original resource that enabled it or use export }}

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool showCursor ( player thePlayer, bool show, [ bool toggleControls = true ] )
</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The [[player]] you want to show or hide the cursor of.
*'''show:''' A boolean value determining whether to show (''true'') or hide (''false'') the cursor.

===Optional Arguments===
{{OptionalArg}}
*'''toggleControls:''' A boolean value determining whether to disable controls whilst the cursor is showing. ''true'' implies controls are disabled, ''false'' implies controls remain enabled.
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool showCursor ( bool show, [ bool toggleControls = true ] )
</syntaxhighlight>

===Required Arguments===
*'''show:''' A boolean value determining whether to show (''true'') or hide (''false'') the cursor.

===Optional Arguments===
{{OptionalArg}}
*'''toggleControls:''' A boolean value determining whether to disable controls whilst the cursor is showing. ''true'' implies controls are disabled, ''false'' implies controls remain enabled.
</section>

===Returns===
Returns ''true'' if the player's cursor was shown or hidden successfully, ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
This example shows the cursor for a player named "Dave", then outputs a message if it was shown successfully.
<syntaxhighlight lang="lua">
local thePlayer = getPlayerFromName ( "Dave" ) -- get the player named Dave
if thePlayer then -- if we got him
showCursor ( thePlayer, true ) -- make his cursor show
if isCursorShowing ( thePlayer ) then -- did it show?
outputChatBox ( "Cursor is now showing for Dave." ) -- print a message to the chat box
end
end
</syntaxhighlight>
</section>

<section name="Client" class="client" show="true">
This example shows the cursor all the time
<syntaxhighlight lang="lua">
showCursor ( true ) -- Shows cursor
showCursor ( false ) -- Doesnt Show Cursor
</syntaxhighlight>
</section>

==See Also==
{{Cursor_functions}}

[[hu:showCursor]]

GetPedGender

2025-05-19T12:32:29Z

Srslyyyy: Code refactor & add missing skins

__NOTOC__
{{Useful Function}}

Get the gender of peds and players.

==Syntax==
<syntaxhighlight lang="lua">
string = getPedGender(element ped)
</syntaxhighlight>

===Required Arguments===
* '''ped:''' The ped/player you want the gender of.

===Returns===
Returns 1 value:
* '''gender:''' The gender of the ped/player. Possible values: "male", "female" (or "unknown"). Returns false if no player/ped element is provided.

==Code==
<section name="Server- and/or clientside Script" class="both" show="false">
<syntaxhighlight lang="lua">
local pedMaleSkins = {
0, 1, 2, 3, 4, 5, 7, 8, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23,
24, 25, 26, 27, 28, 29, 30, 32, 33, 34, 35, 36,
37, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 57,
58, 59, 60, 61, 62, 65, 66, 67, 68, 70, 71, 72, 73,
78, 79, 80, 81, 82, 83, 84, 94, 95, 96, 97, 98,
99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109,
110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121,
122, 123, 124, 125, 126, 127, 128, 132, 133, 134, 135,
136, 137, 142, 143, 144, 146, 147, 153, 154, 155, 156,
158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168,
170, 171, 173, 174, 175, 176, 177, 179, 180, 181, 182,
183, 184, 185, 186, 187, 188, 189, 200, 202, 203, 204,
206, 209, 210, 212, 213, 217, 220, 221, 222, 223, 227,
228, 229, 230, 234, 235, 236, 239, 240, 241, 242, 247,
248, 249, 250, 252, 253, 254, 255, 258, 259, 260, 261,
262, 264, 265, 266, 267, 268, 269, 270, 271, 272, 273, 274,
275, 276, 277, 278, 279, 280, 281, 282, 283, 284, 285,
286, 287, 288, 289, 290, 291, 292, 293, 294, 295, 296, 297,
299, 300, 301, 302, 303, 305, 306, 307, 308, 309, 310,
311, 312
}

local pedFemaleSkins = {
6, 9, 10, 11, 12, 13, 31, 38, 39, 40, 41, 53, 54,
55, 56, 63, 64, 69, 75, 76, 77, 85, 86, 87, 88, 89,
90, 91, 92, 93, 129, 130, 131, 138, 139, 140, 141,
145, 148, 150, 151, 152, 157, 169, 172, 178, 190, 191,
192, 193, 194, 195, 196, 197, 198, 199, 201, 205, 207,
211, 214, 215, 216, 218, 219, 224, 225, 226, 231, 232,
233, 237, 238, 243, 244, 245, 246, 251, 256, 257, 263,
298, 304
}

local pedElementTypes = {
["ped"] = true,
["player"] = true,
}

do
local maleSkinsTemp = {}
local femaleSkinsTemp = {}

for skinID = 1, #pedMaleSkins do
local pedModelID = pedMaleSkins[skinID]

maleSkinsTemp[pedModelID] = true
end

for skinID = 1, #pedFemaleSkins do
local pedModelID = pedFemaleSkins[skinID]

femaleSkinsTemp[pedModelID] = true
end

pedMaleSkins = maleSkinsTemp
pedFemaleSkins = femaleSkinsTemp
end

function getSkinGender(pedModel)
local skinMale = pedMaleSkins[pedModel] and "male"
local skinFemale = pedFemaleSkins[pedModel] and "female"
local skinGender = (skinMale or skinFemale or "unknown")

return skinGender
end

function getPedGender(pedElement)
local validElement = isElement(pedElement)

if (not validElement) then
return false
end

local elementType = getElementType(pedElement)
local pedType = pedElementTypes[elementType]

if (not pedType) then
return false
end

local pedModel = getElementModel(pedElement)
local pedGender = getSkinGender(pedModel)

return pedGender
end
</syntaxhighlight>
</section>

==Example==
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
--[[

The command /gender will display the gender of your player element.

]]
addCommandHandler("gender",
function ()
outputChatBox("My gender: " .. tostring(getPedGender(localPlayer)))
end)
</syntaxhighlight>
</section>

Author: IIYAMA.
Dataset by: Lexr128

==See Also==
{{Useful_Functions}}

SetFPSLimit

2025-05-19T05:27:23Z

Srslyyyy:

{{Server client function}}
__NOTOC__
This function sets the maximum [http://en.wikipedia.org/wiki/Frame_rate FPS (Frames per second)] that players on the server can run their game at.
{{Note|
* When set client side, the actual limit used is the lowest of both the server and client set values.
* Starting from version [[https://buildinfo.mtasa.com/?Revision=21313&Branch r21313]] and above '''fpsLimit''' range is '''25-32767'''. In older MTA releases it was '''25-100'''.
}}
==Syntax==
<syntaxhighlight lang="lua">
bool setFPSLimit ( int fpsLimit )
</syntaxhighlight>

===Required Arguments===
*'''fpsLimit:''' An integer value representing the maximum FPS. Refer to the note above for possible values. You can also pass '''0''' or '''false''', in which case the FPS limit will be the one set in the client settings (by default '''100 FPS''' and the client fps limit should also be manually changed via "'''fps_limit=0'''" in console or '''MTA San Andreas\MTA\config\coreconfig.xml''').

===Returns===
Returns ''true'' if successful, or ''false'' if it was not possible to set the limit or an invalid value was passed.

==Issues when increasing FPS==
Note: with "very high" FPS, any FPS limit over 74 is meant.
It is recommended to set a conservative FPS limit (between 40-60 and 74 highest) because high FPS can break some GTA internal calculations, causing various bugs. The higher the FPS the more of a problem these become:

74 FPS is the breaking point that opens the door to various more severe GTA bugs related to FPS and physics.

* Physics of vehicles is effected, both high and low FPSes may bring their own set of unfair advantages. Speaking about the consequences of high FPS in this context, up to 70 or 74 FPS is considered safe (as any differences in physics, if they do exist to begin with as they theoretically should, are so tiny that they are unmeasurable and thus wouldn't affect racing results in practise). Anything beyond 74 FPS may cause impactful discrepancies.

* Pressing the horn button to turn on and off sirens gets really hard at very high FPS. For instance, at 100 FPS, you are more likely to hit the regular horn 3 times (inconsistent) before eventually triggering the siren, besides taking a similar amount of tries to turn off the siren.
* At very high FPS, climbing over certain objects will result in instant death. Example at: 2520.108, -1681.407, 19.406, 266 - [https://wiki.multitheftauto.com/wiki/SetFPSLimit#Fix_for_climbing_over_certain_objects you can use this Lua code to fix it.]
* The higher your FPS, the more of a penalty in satchel throwing distance (up to ~10% at very high FPS) will apply.

For a full list of FPS-related GTA bugs (that are much less likely to impact gameplay in a meaningful way) and MTA developers' progress in tackling them, see the [https://github.com/multitheftauto/mtasa-blue/projects/14 Framerate issues tracker] github project.

==Example==
This example allows players to limit their own FPS using a command.
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
local minFPS = 25
local maxFPS = 100

function fpsFunction(commandName, fpsLimit)
local newFPS = tonumber(fpsLimit)
local displaySyntax = (not newFPS) or (newFPS < minFPS) or (newFPS > maxFPS)

if (displaySyntax) then
outputChatBox("Syntax: /"..commandName.." ["..minFPS.." ~ "..maxFPS.."] - limit your own FPS.")

return false
end

local currentLimit = getFPSLimit()
local setNewFPS = (newFPS ~= currentLimit)

if (setNewFPS) then
outputChatBox("Your FPS has been limited to: "..newFPS..".")
setFPSLimit(newFPS)
end
end
addCommandHandler("limitfps", fpsFunction)
addCommandHandler("fpslimit", fpsFunction)
</syntaxhighlight>
</section>

== Fix for climbing over certain objects==
You can use this small code to fix one of high FPS issues, specifically the one which would instantly kill player climbing over some objects.
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function onClientPlayerDamage(attackerElement, damageType, bodyPart)
local fallDamage = (damageType == 54)

if (not fallDamage) then
return false
end

local playerTask = getPedSimplestTask(localPlayer)
local playerClimbing = (playerTask == "TASK_SIMPLE_CLIMB")

if (playerClimbing) then
cancelEvent()
end
end
addEventHandler("onClientPlayerDamage", localPlayer, onClientPlayerDamage)
</syntaxhighlight>
</section>

==See Also==
{{Server functions}}

[[pl:setFPSLimit]]
[[ru:setFPSLimit]]

OnClientPedDamage

2025-05-11T20:43:21Z

Srslyyyy: /* Example */

__NOTOC__
{{Client event}}
This event is triggered whenever a [[ped]] is damaged.
{{Note|This event is only triggered for peds that are streamed in}}
==Parameters==
<syntaxhighlight lang="lua">
element attacker, int weapon, int bodypart [, float loss ]
</syntaxhighlight>

*'''attacker''': A [[player]] [[element]] representing the attacker or [[vehicle]] [[element]] (when a ped falls of a bike).
*'''weapon''': An integer representing the [[Weapons|weapon ID]] the attacker used
*'''bodypart''': An integer representing the bodypart the ped was damaged
{{BodyParts}}
*'''loss''': A float representing the percentage of health the ped lost.

==Source==
The [[event system#Event source|source]] of this event is the [[ped]] that got damaged

==Cancel effect==
If this event is [[Event system#Canceling|canceled]], then any damaging effects to the ped will cease.

==Example==
This example cancels any damage done to peds
<syntaxhighlight lang="lua">
function cancelPedDamage()
cancelEvent() -- cancel any damage done to peds
end
addEventHandler("onClientPedDamage", root, cancelPedDamage)
</syntaxhighlight>

==See Also==
===Client ped events===
{{Client_ped_events}}
===Client event functions===
{{Client_event_functions}}

Weapons

2025-05-11T19:51:12Z

Srslyyyy:

Scripting functions that ask for a weapon ID need an integer that refers to the GTASA weapon ID list. They are listed below.
{{Note|
*Clip size () denotes clip size when the weapon is dual wielded. Weapons without this specification are not dual wield weapons.
*GTASA [[Weapon_skill_levels|weapon stats]] will affect movement, accuracy, damage, and dual wield capability. See [[setPedStat]] to change these stats. The default MTA server package comes with a resource called "defaultStats" that sets GTASA weapon stats to 999. See the weapon stats link for more info.
*For death reasons, especially in event handlers for onPlayerWasted or similar, also have a look at the [[Damage Types]].
*'''Name''' is compatible with functions [[getWeaponNameFromID]], [[getWeaponIDFromName]].
*'''Bullet Sync''' refers to whether they are triggered by the [[OnPlayerWeaponFire]] event.
}}
{|class="wikitable sortable" style="text-align:center; margin: 1em auto 1em auto; border:1px solid black"
|-
! Slot || class="unsortable" | Type || class="unsortable" | Image || Name || ID || class="unsortable" | Model ID || class="unsortable" | Clip || class="unsortable" | Sharing slot ammo || class="unsortable" | Bullet Sync
|-
! rowspan="2" | 0
! rowspan="2" | Hand
| [[Image:Fist.png]] || align="left" | Fist || 0 || - || -
| rowspan="2" | -
| rowspan="2" | No
|-
| [[Image:Knuckle.png]] || align="left" | Brassknuckle || 1 || 331 || -
|-
! rowspan="8" | 1
! rowspan="8" | Melee
| [[Image:Golfclub.png]] || align="left" | Golfclub || 2 || 333 || -
| rowspan="8" | -
| rowspan="8" | No
|-
| [[Image:Nitestik.png]] || align="left" | Nightstick || 3 || 334 || -
|-
| [[Image:Knife.png]] || align="left" | Knife || 4 || 335 || -
|-
| [[Image:Bat.png]] || align="left" | Bat || 5 || 336 || -
|-
| [[Image:Shovel.png]] || align="left" | Shovel || 6 || 337 || -
|-
| [[Image:Poolcue.png]] || align="left" | Poolstick || 7 || 338 || -
|-
| [[Image:Katana.png]] || align="left" | Katana || 8 || 339 || -
|-
| [[Image:Saw.png]] || align="left" | Chainsaw || 9 || 341 || -
|-
! rowspan="3" | 2
! rowspan="3" | Handguns
| [[Image:Colt45.png]] || align="left" | Colt 45 || 22 || 346 || 17 (34)
| rowspan="3" | '''No'''<br/>''Replacing handgun resets slot 2 ammo''
| rowspan="3" | Yes
|-
| [[Image:Silenced.png]] || align="left" | Silenced || 23 || 347 || 17
|-
| [[Image:Deagle.png]] || align="left" | Deagle || 24 || 348 || 7
|-
! rowspan="3" | 3
! rowspan="3" | Shotguns
| [[Image:Shotgun.png]] || align="left" | Shotgun || 25 || 349 || 1
| rowspan="3" | Yes
| rowspan="3" | Yes
|-
| [[Image:Sawnoff.png]] || align="left" | Sawed-off || 26 || 350 || 2 (4)
|-
| [[Image:Spas12.png]] || align="left" | Combat Shotgun || 27 || 351 || 7
|-
! rowspan="3" | 4
! rowspan="3" | Sub-Machine Guns
| [[Image:Mac10.png]] || align="left" | Uzi || 28 || 352 || 50 (100)
| rowspan="3" | Yes
| rowspan="3" | Yes
|-
| [[Image:Mp5.png]] || align="left" | MP5 || 29 || 353 || 30
|-
| [[Image:Tec9.png]] || align="left" | Tec-9 || 32 || 372 || 50 (100)
|-
! rowspan="2" | 5
! rowspan="2" | Assault Rifles
| [[Image:Ak47.png]] || align="left" | AK-47 || 30 || 355 || 30
| rowspan="2" | Yes
| rowspan="2" | Yes
|-
| [[Image:M4.png]] || align="left" | M4 || 31 || 356 || 50
|-
! rowspan="2" | 6
! rowspan="2" | Rifles
| [[Image:Rifle.png]] || align="left" | Rifle || 33 || 357 || 1
| rowspan="2" | '''No'''<br/>''Replacing rifle resets slot 6 ammo''
| rowspan="2" | Yes
|-
| [[Image:Sniper.png]] || align="left" | Sniper || 34 || 358 || 1
|-
! rowspan="4" | 7
! rowspan="4" | Heavy Weapons
| [[Image:Rocketla.png]] || align="left" | Rocket Launcher || 35 || 359 || 1
| rowspan="4" | '''No'''<br/>''Replacing heavy weapon resets slot 7 ammo''
| rowspan="4" | No
|-
| [[Image:Heatseek.png]] || align="left" | Rocket Launcher HS || 36 || 360 || 1
|-
| [[Image:Flame.png]] || align="left" | Flamethrower || 37 || 361 || 50
|-
| [[Image:Minigun.png]] || align="left" | Minigun || 38 || 362 || 500
|-
! rowspan="4" | 8
! rowspan="4" | Projectiles
| [[Image:Grenade.png]] || align="left" | Grenade || 16 || 342 || 1
| rowspan="4" | '''No'''<br/>''Replacing projectile resets slot 8 ammo''
| rowspan="4" | No
|-
| [[Image:Teargas.png]] || align="left" | Teargas || 17 || 343 || 1
|-
| [[Image:Molotov.png]] || align="left" | Molotov || 18 || 344 || 1
|-
| [[Image:Satchel.png]] || align="left" | Satchel || 39 || 363 || 1
|-
! rowspan="3" | 9
! rowspan="3" | Special 1
| [[Image:Spraycan.png]] || align="left" | Spraycan || 41 || 365 || 500
| rowspan="3" | '''No'''<br/>''Replacing slot 9 weapon resets slot 9 ammo''
| rowspan="3" | No
|-
| [[Image:Fire_ex.png]] || align="left" | Fire Extinguisher || 42 || 366 || 500
|-
| [[Image:Camera.png]] || align="left" | Camera || 43 || 367 || 36
|-
! rowspan="5" | 10
! rowspan="5" | Gifts
| [[Image:Dildo1.png]] || align="left" | Dildo || 10 || 321 || -
| rowspan="5" | -
| rowspan="5" | No
|-
| [[Image:Dildo2.png]] || align="left" | Dildo || 11 || 322 || -
|-
| [[Image:Vibe1.png]] || align="left" | Vibrator || 12 || 323 || -
|-
| [[Image:Flowers.png]] || align="left" | Flower || 14 || 325 || -
|-
| [[Image:Cane.png]] || align="left" | Cane || 15 || 326 || -
|-
! rowspan="3" | 11
! rowspan="3" | Special 2
| [[Image:Irgoggle.png]] || align="left" | Nightvision || 44 || 368 || -
| rowspan="3" | -
| rowspan="3" | No
|-
| [[Image:Irgoggle.png]] || align="left" | Infrared || 45 || 369 || -
|-
| [[Image:Paracute.png]] || align="left" | Parachute || 46 || 371 || -
|-
! rowspan="1" | 12
! rowspan="1" | Satchel Detonator
| [[Image:Bomb.png]] || align="left" | Bomb || 40 || 364 || -
| rowspan="1" | -
| rowspan="1" | No
|}
Lua tables with weapons:
<syntaxhighlight lang="lua">
local weaponsID = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 22, 23, 24, 25, 26, 27, 28, 29, 32, 30, 31, 33, 34, 35, 36, 37, 38, 16, 17, 18, 39, 41, 42, 43, 10, 11, 12, 14, 15, 44, 45, 46, 40}
local weaponsBySlot = {
[0] = {0, 1}, -- hand
[1] = {2, 3, 4, 5, 6, 7, 8, 9}, -- melee
[2] = {22, 23, 24}, -- handguns
[3] = {25, 26, 27}, -- shotguns
[4] = {28, 29, 32}, -- sub-machine guns
[5] = {30, 31}, -- assault rifles
[6] = {33, 34}, -- rifles
[7] = {35, 36, 37, 38}, -- heavy weapons
[8] = {16, 17, 18, 39}, -- projectiles
[9] = {41, 42, 43}, -- special 1
[10] = {10, 11, 12, 14, 15}, -- gifts
[11] = {44, 45, 46}, -- special 2
[12] = {40}, -- satchel detonator
}
</syntaxhighlight>

==Functions==
{{Weapon functions|server}}== See Also ==
* [[Id|Ids]]

[[Category:ID Lists]]

[[hu:Weapons]]
[[it:Armi]]
[[ru:Weapons]]
[[de:Waffen]]
[[pl:Weapons]]

Script security

2025-05-03T16:34:46Z

Srslyyyy: /* Securing setElementData */

==Awareness of client memory==

Starting from very basics:
* You should be aware that everything you store on client-side is at risk, this includes .lua files as well. Any confidential (and/or) important data which is stored, or travels through client-side (player PC) could be accessed by malicious clients.
* To keep sensitive data (and/or) Lua logic safe - use server-side.
* Do note that scripts marked as '''shared''' act also as '''client code''', which means that everything above applies to them. For example defining:

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

Is same as doing:

<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]]

OnPlayerZoneChange

2025-05-01T15:05:14Z

Srslyyyy:

{{Useful Function}}
<lowercasetitle></lowercasetitle> __NOTOC__
This code implements an [[event]] that is triggered when the [[player]] enters a new area on the map.

==Parameters==
<syntaxhighlight lang="lua">
string oldZone, string newZone
</syntaxhighlight>
*'''oldZone:''' old zone of [[player]].
*'''newZone:''' new zone of [[player]].

==Source==
The [[event system#Event source|source]] of this event is the player whose zone was changed.

==Code==
<section name="Shared" class="both" show="true">
<syntaxhighlight lang="lua">
local playersZone = {}
local zoneEventName = (localPlayer and "onClientPlayerZoneChange" or "onPlayerZoneChange") -- client = "onClientPlayerZoneChange" — server = "onPlayerZoneChange"
local zoneCitiesOnly = false -- only major cities?

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

for playerID = 1, #playersTable do
local playerElement = playersTable[playerID]
local playerX, playerY, playerZ = getElementPosition(playerElement)
local playerZoneNow = getZoneName(playerX, playerY, playerZ, zoneCitiesOnly)
local playerZoneSaved = playersZone[playerElement]
local playerZoneNeedsUpdate = (playerZoneSaved and playerZoneSaved ~= playerZoneNow)

if (playerZoneNeedsUpdate) then
triggerEvent(zoneEventName, playerElement, playerZoneSaved, playerZoneNow)
end

playersZone[playerElement] = playerZoneNow
end
end
addEvent(zoneEventName, false) -- disable remote triggering so players couldn't trigger this event on server (& vice-versa)
setTimer(checkPlayersZone, 1000, 0)

local function clearPlayersZone()
playersZone[source] = nil
end
addEventHandler(localPlayer and "onClientPlayerQuit" or "onPlayerQuit", root, clearPlayersZone)
</syntaxhighlight>
</section>

'''Authors:''' [[User:IManGaaX|Youssef Maged (iManGaaX)]]

==Examples==
This example will make label with the full zone name of the player, '''onPlayerZoneChange''' is function is change the label text to new zone when the player enter a new zone.
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
local myCurrentZoneLabel

addEventHandler("onClientResourceStart", resourceRoot, function()
local firstZone = getElementZoneName(localPlayer)
myCurrentZoneLabel = guiCreateLabel(0, 0, 0.20, 0.02, firstZone, true)
end)

addEventHandler("onPlayerZoneChange", root, function(_, newZone)
if (source == localPlayer) then
guiSetText(myCurrentZoneLabel, newZone)
end
end)
</syntaxhighlight>
</section>
This example will out put in the chat the new zone full name when the player enter a new zone.
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
addEventHandler("onPlayerZoneChange", root, function(oldZone, newZone)
outputChatBox("Your Zone is Changed from "..(oldZone).." to "..(newZone)..".", source, 255, 255, 0)
end)
</syntaxhighlight>
</section>

==See Also==

{{Useful_Functions}}

EngineReplaceModel

2025-05-01T10:57:01Z

Srslyyyy:

__NOTOC__
{{Client function}}

This function replaces the given model ID with the model contained in a DFF file loaded by [[engineLoadDFF]]. This function supports [[vehicle|vehicles]], [[object|objects]], [[ped|peds]] and [[player|players]].

Since version [https://buildinfo.multitheftauto.com/?Revision=23124&Branch= r23124] and above replacing CJ clothing became possible - see: [[Clothing Component IDs]]. Body parts replacements aren't supported at the moment.

To replace weapon models you must use their object IDs, not weapon IDs. There is a weapon model list available at [[Weapons]].

{{Note|
* Follow loading order ('''COL''' -> '''TXD''' -> '''DFF''') which is used in the example - as other orders can cause collisions, textures or the DFF not to load due to technical limitations.
* Default GTA map objects behave inconsistently when using this function on them. If you want to replace models in the original GTA map, you need to call [[engineRestreamWorld]] after replacing models as well.
* A raw data DFF element can only be used once, because the underlying memory for the model is released after replacement.
* If the replacement model is broken and the original model is not loaded/streamed-in at the time of replacement, this function will succeed and you won't see any error message, neither when the model replacement fails once the original model starts to load/stream-in.}}

==Syntax==
<syntaxhighlight lang="lua">
bool engineReplaceModel ( dff theModel, int modelID [, bool alphaTransparency = false ] )
</syntaxhighlight>
{{OOP||[[DFF|dff]]:replace}}
===Required Arguments===
*'''theModel:''' The model to replace the given model ID with
*'''modelID:''' The model it to replace the model of

===Optional Arguments===
*'''alphaTransparency:''' Set to true if model uses semi-transparent textures, e.g. windows. This will ensure other objects behind the semi-transparent textures are rendered correctly. (Can slightly impact performance, so only set when required)

===Returns===
Returns ''true'' if the model was successfully replaced, ''false'' if it failed for some reason, ie. the DFF or the model ID is not valid.

==Example==
<section name="Client" class="client" show="true">
This example allows you to replace single or many models (with ability to toggle TXD filtering/DFF alpha transparency) - by using [[table]]. Do not forget to add those file paths to [[meta.xml]]
<syntaxhighlight lang="lua">
function onClientResourceStartReplaceModels()
local modelsToReplace = {
{ -- replace object (all object IDs here: https://dev.prineside.com/en/gtasa_samp_model_id/)
colFile = "object.col",
txdFile = "object.txd",
dffFile = "object.dff",
modelID = 1337,
alphaTransparency = false,
filteringEnabled = true,
},
{ -- replace vehicle (all vehicle IDs here: https://wiki.multitheftauto.com/wiki/Vehicle_IDs)
colFile = false, -- if file is not present set to false/nil
txdFile = "vehicle.txd",
dffFile = "vehicle.dff",
modelID = 434,
alphaTransparency = false,
filteringEnabled = true,
},
{ -- replace skin (all ped IDs here: https://wiki.multitheftauto.com/wiki/Character_Skins)
colFile = false, -- if file is not present set to false/nil
txdFile = "ped.txd",
dffFile = "ped.dff",
modelID = 16,
alphaTransparency = false,
filteringEnabled = true,
},
{ -- replace weapon (all weapon IDs here: https://wiki.multitheftauto.com/wiki/Weapons)
colFile = false, -- if file is not present set to false/nil
txdFile = "m4.txd",
dffFile = "m4.dff",
modelID = 356,
alphaTransparency = false,
filteringEnabled = true,
},
}

for assetID = 1, #modelsToReplace do
local modelData = modelsToReplace[assetID]
local modelCol = modelData.colFile
local modelTxd = modelData.txdFile
local modelDff = modelData.dffFile
local modelID = modelData.modelID

if (modelCol) then
local colData = engineLoadCOL(modelCol)

if (colData) then
engineReplaceCOL(colData, modelID)
end
end

if (modelTxd) then
local filteringEnabled = modelData.filteringEnabled
local txdData = engineLoadTXD(modelTxd, filteringEnabled)

if (txdData) then
engineImportTXD(txdData, modelID)
end
end

if (modelDff) then
local dffData = engineLoadDFF(modelDff)

if (dffData) then
local alphaTransparency = modelData.alphaTransparency

engineReplaceModel(dffData, modelID, alphaTransparency)
end
end
end
end
addEventHandler("onClientResourceStart", resourceRoot, onClientResourceStartReplaceModels)
</syntaxhighlight>
</section>

==See Also==
{{Engine_functions}}

EngineReplaceModel

2025-05-01T10:55:44Z

Srslyyyy:

__NOTOC__
{{Client function}}

This function replaces the given model ID with the model contained in a DFF file loaded by [[engineLoadDFF]]. This function supports [[vehicle|vehicles]], [[object|objects]], [[ped|peds]] and [[player|players]].
Since version [https://buildinfo.multitheftauto.com/?Revision=23124&Branch= r23124] and above replacing CJ clothing became possible - see: [[Clothing Component IDs]]. Body parts replacements aren't supported at the moment.
{{Deprecated feature|3.0111|1.1.1|This function does not support ped and weapon models.}}

To replace weapon models you must use their object IDs, not weapon IDs. There is a weapon model list available at [[weapons]].

{{Note|
* Follow loading order ('''COL''' -> '''TXD''' -> '''DFF''') which is used in the example - as other orders can cause collisions, textures or the DFF not to load due to technical limitations.
* Default GTA map objects behave inconsistently when using this function on them. If you want to replace models in the original GTA map, you need to call [[engineRestreamWorld]] after replacing models as well.
* A raw data DFF element can only be used once, because the underlying memory for the model is released after replacement.
* If the replacement model is broken and the original model is not loaded/streamed-in at the time of replacement, this function will succeed and you won't see any error message, neither when the model replacement fails once the original model starts to load/stream-in.}}

==Syntax==
<syntaxhighlight lang="lua">
bool engineReplaceModel ( dff theModel, int modelID [, bool alphaTransparency = false ] )
</syntaxhighlight>
{{OOP||[[DFF|dff]]:replace}}
===Required Arguments===
*'''theModel:''' The model to replace the given model ID with
*'''modelID:''' The model it to replace the model of

===Optional Arguments===
*'''alphaTransparency:''' Set to true if model uses semi-transparent textures, e.g. windows. This will ensure other objects behind the semi-transparent textures are rendered correctly. (Can slightly impact performance, so only set when required)

===Returns===
Returns ''true'' if the model was successfully replaced, ''false'' if it failed for some reason, ie. the DFF or the model ID is not valid.

==Example==
<section name="Client" class="client" show="true">
This example allows you to replace single or many models (with ability to toggle TXD filtering/DFF alpha transparency) - by using [[table]]. Do not forget to add those file paths to [[meta.xml]]
<syntaxhighlight lang="lua">
function onClientResourceStartReplaceModels()
local modelsToReplace = {
{ -- replace object (all object IDs here: https://dev.prineside.com/en/gtasa_samp_model_id/)
colFile = "object.col",
txdFile = "object.txd",
dffFile = "object.dff",
modelID = 1337,
alphaTransparency = false,
filteringEnabled = true,
},
{ -- replace vehicle (all vehicle IDs here: https://wiki.multitheftauto.com/wiki/Vehicle_IDs)
colFile = false, -- if file is not present set to false/nil
txdFile = "vehicle.txd",
dffFile = "vehicle.dff",
modelID = 434,
alphaTransparency = false,
filteringEnabled = true,
},
{ -- replace skin (all ped IDs here: https://wiki.multitheftauto.com/wiki/Character_Skins)
colFile = false, -- if file is not present set to false/nil
txdFile = "ped.txd",
dffFile = "ped.dff",
modelID = 16,
alphaTransparency = false,
filteringEnabled = true,
},
{ -- replace weapon (all weapon IDs here: https://wiki.multitheftauto.com/wiki/Weapons)
colFile = false, -- if file is not present set to false/nil
txdFile = "m4.txd",
dffFile = "m4.dff",
modelID = 356,
alphaTransparency = false,
filteringEnabled = true,
},
}

for assetID = 1, #modelsToReplace do
local modelData = modelsToReplace[assetID]
local modelCol = modelData.colFile
local modelTxd = modelData.txdFile
local modelDff = modelData.dffFile
local modelID = modelData.modelID

if (modelCol) then
local colData = engineLoadCOL(modelCol)

if (colData) then
engineReplaceCOL(colData, modelID)
end
end

if (modelTxd) then
local filteringEnabled = modelData.filteringEnabled
local txdData = engineLoadTXD(modelTxd, filteringEnabled)

if (txdData) then
engineImportTXD(txdData, modelID)
end
end

if (modelDff) then
local dffData = engineLoadDFF(modelDff)

if (dffData) then
local alphaTransparency = modelData.alphaTransparency

engineReplaceModel(dffData, modelID, alphaTransparency)
end
end
end
end
addEventHandler("onClientResourceStart", resourceRoot, onClientResourceStartReplaceModels)
</syntaxhighlight>
</section>

==See Also==
{{Engine_functions}}

PathListDir

2025-04-27T16:20:23Z

Srslyyyy:

__NOTOC__
{{Shared function}}

{{New feature/item|3.161|1.6.0|22470|
Reads a specified directory and returns all entries inside of it. These entries can be file or folder names.
}}
{{Note|
* Listing other resource directory can be done by passing '''":resourceName/."'''
* For listing current resource (the one where code is executed), you can pass either '''""''' or '''":currentResourceName/."''' (preferably use first approach, because the latter will require removing this part, once result is ready)
}}

==Syntax==
<syntaxhighlight lang="lua">
table pathListDir ( string path )
</syntaxhighlight>
{{OOP||[[path]]:listDir}}

===Required Arguments===
*'''path:''' A [[string]] containing a path you want to get entries from

===Returns===
Returns [[table]] with all entries in a specified directory.

==Example==
<section name="Client" class="client" show="true">
This example loads all models from a certain directory
<syntaxhighlight lang="lua">
-- from https://gist.github.com/kgriffs/124aae3ac80eefe57199451b823c24ec
local function stringEndsWith(str, ending)
return ending == "" or str:sub(-#ending) == ending
end

-- get all files from a models directory that exists in the resource root folder (resources/ResourceName)
-- and load them into the game
addEventHandler('onClientResourceStart', resourceRoot, function()
local entries = pathListDir('models') or {}
for _, fileOrFolder in ipairs(entries) do
if pathIsFile(fileOrFolder) then
local file = fileOrFolder
local modelName = tonumber(file:sub(1, -5))
if modelName then
-- the full path to the file
local filePath = 'models/'..file

if stringEndsWith(file, '.col') then
local colData = engineLoadCOL(filePath)
if colData then
engineReplaceCOL(colData, modelName)
end
end
if stringEndsWith(file, '.txd') then
local txdData = engineLoadTXD(filePath)
if txdData then
engineImportTXD(txdData, modelName)
end
end
if stringEndsWith(file, '.dff') then
local dffData = engineLoadDFF(filePath)
if dffData then
engineReplaceModel(dffData, modelName)
end
end
end
end
end
end, false)
</syntaxhighlight>
</section>

==See Also==
{{Shared_path_functions}}

OnPlayerZoneChange

2025-04-22T21:33:16Z

Srslyyyy: /* Parameters */

{{Useful Function}}
<lowercasetitle></lowercasetitle> __NOTOC__
This code implements an [[event]] that is triggered when the [[player]] enters a new area on the map.

==Parameters==
<syntaxhighlight lang="lua">
string oldZone, string newZone
</syntaxhighlight>
*'''oldZone:''' old zone of [[player]].
*'''newZone:''' new zone of [[player]].

==Source==
The [[event system#Event source|source]] of this event is the player whose zone was changed.

==Code==
<section name="Shared" class="both" show="true">
<syntaxhighlight lang="lua">
local playersZone = {}
local zoneEventName = (localPlayer and "onClientPlayerZoneChange" or "onPlayerZoneChange") -- client = "onClientPlayerZoneChange" — server = "onPlayerZoneChange"
local zoneCitiesOnly = false -- only major cities?

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

for playerID = 1, #playersTable do
local playerElement = playersTable[playerID]
local playerX, playerY, playerZ = getElementPosition(playerElement)
local playerZoneNow = getZoneName(playerX, playerY, playerZ, zoneCitiesOnly)
local playerZoneSaved = playersZone[playerElement]
local playerZoneNeedsUpdate = (playerZoneSaved and playerZoneSaved ~= playerZoneNow)

if (playerZoneNeedsUpdate) then
triggerEvent(zoneEventName, playerElement, playerZoneSaved, playerZoneNow)
end

playersZone[playerElement] = playerZoneNow
end
end
addEvent(zoneEventName, false) -- disable remote triggering so players couldn't trigger this event on server (& vice-versa)
setTimer(checkPlayersZone, 1000, 0)

local function clearPlayersZone()
playersZone[source] = nil
end
addEventHandler(localPlayer and "onClientPlayerQuit" or "onPlayerQuit", root, clearPlayersZone)

-- example for server:

function onPlayerZoneChange(oldZone, newZone)
iprint(source, oldZone, newZone)
end
addEventHandler("onPlayerZoneChange", root, onPlayerZoneChange)
</syntaxhighlight>
</section>

'''Author:''' [[User:IManGaaX|Youssef Maged (iManGaaX)]]

==Examples==
This example will make label with the full zone name of the player, '''onPlayerZoneChange''' is function is change the label text to new zone when the player enter a new zone.
{{RequiredFunctions|getElementZoneFullName}}
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
local myCurrentZoneLabel

addEventHandler("onClientResourceStart", resourceRoot, function()
local text = getElementZoneFullName(localPlayer)
myCurrentZoneLabel = guiCreateLabel(0, 0, 0.20, 0.02, text, true)
end)

addEventHandler("onPlayerZoneChange", root, function()
if (source == localPlayer) then
local newText = getElementZoneFullName(localPlayer)
guiSetText(myCurrentZoneLabel, newText)
end
end)
</syntaxhighlight>
</section>
This example will out put in the chat the new zone full name when the player enter a new zone.
{{RequiredFunctions|getElementZoneFullName}}
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
addEventHandler("onPlayerZoneChange", root, function()
local newZone = getElementZoneFullName(source)
outputChatBox("Your Zone is Changed to "..(newZone)..".", source, 255, 255, 0)
end)
</syntaxhighlight>
</section>

==See Also==

{{Useful_Functions}}

Scripting Tips

2025-04-22T21:21:49Z

Srslyyyy: Fix misleading information & add information about RT

This page contains a variety of things that knowing, make life easier for MTA scripters.

== General Lua ==
* The ''infinite loop / too long execution error'' which aborts execution can be disabled with ''debug.sethook(nil)''
* Be careful when looping a table where you intend to delete multiple rows, if 2 of them are in a row the 2nd one will get skipped! You must loop the table backwards (reverse ipairs). For example: ''for i = #table, 1, -1 do''
* Rather than having if checks inside if checks inside if checks, consider using ''return'' for example ''if (not ready) then return false end''
* A quick way to clamp a number between a lower and upper value: math.min(math.max(x, min), max) and easy to remember, just think: "min max min max"

== MTA Scripting ==
* Remember that 'false' boolean has a value - If you want to delete a variable or element/account data, use 'nil' instead - this will reduce memory and disk usage (minuscule optimization, only notable on larger servers)
* Remember that 99% of the time it's a bug in your script, not an MTA bug! Don't report something to GitHub Issues until you're absolutely certain the bug can be reproduced with a small piece of script.
* As MTA already has so many functions and events virtually everything you want to do is already possible, as long as you're willing to do the work! You'll find better solutions to problems as there are many ways to achieve the same thing as long as you know all the functions and events.
* If a script is getting too complicated, try putting back-end stuff in another file so the main script calls the functions in the 2nd one. For example rather than having meaningless things like ''vehicleTable[vehicle][7]'' in the main file, put that in a function in the 2nd file and have the main file call a meaningfully named function so rather than seeing a useless ''7'' you'd see something like ''getFuel'' and although this might take longer to set-up you'll save time in the long run as you'll spend less time being confused when you come back to it in a weeks time to debug a problem.
* Your client side scripts can cause desync if you're not careful, try to keep the psychical world equal with every player. For example if your script creates a client side object make sure your script will create it for everyone nearby, else people will be wondering why a player appears to be constantly floating and falling.
* Instead of using ''onClientResourceStart'' or ''onResourceStart'' events attached to ''resourceRoot'' like this:
<syntaxhighlight lang="lua">function warnPeopleThatThisResourceStarted()
outputChatBox("The resource " .. getResourceName(resource) .. " has just started!", 0, 255, 0)
end
addEventHandler("onClientResourceStart", resourceRoot, warnPeopleThatThisResourceStarted)</syntaxhighlight>
You can also use this outside of any function:
<syntaxhighlight lang="lua">outputChatBox("The resource " .. getResourceName(resource) .. " has just started!", 0, 255, 0)</syntaxhighlight>
However the result won't be exactly the same, as onClientResourceStart gets called only when all resource scripts are fully loaded, whilst code outside of it will be ran once '''this specific''' script is loaded. This is important, because load order of scripts exists, and you might want to call other script function (which gets loaded into memory afterwards), resulting in '''attempt to call global''' error. By using this specific event you have reliable time-frame to call it.
* string.dump produces unsigned compiled Lua code which is not allowed for security reasons. The only way to transport code now is by using the source code. e.g.:
<syntaxhighlight lang="lua">exampleFunction = [===[
return param
]===]

local loadedFunction = loadstring(exampleFunction)</syntaxhighlight>

== MTA Scripting - Element IDs Being Reused ==
* If your script is covered in [[isTimer]] and [[isElement]] checks to hide debug warnings from deleted elements not being dereferenced (making the variable nil) you will regret it when that element ID or timer pointer has to be re-used by MTA in a weeks time and your script starts acting strangely and you won't have a clue why. Dereference destroyed elements and disconnected players!
* Why would MTA reuse it in a weeks time? Everything has a userdata value whether it's a function or an element, there is a limited amount of these available meaning that eventually the server will be forced to use the same userdata value twice, as long as whatever that userdata value was for is no longer valid. This could happen within hours, weeks or even never depending on how many elements are being created and destroyed by your scripts.
* For example if you have a race server that has 100 objects in every map and the map was changing every 5 minutes your server would go through at least 1200 an hour, 28,800 a day, 201,600 a week in userdata values, it can't keep going up and up though eventually it will have to reuse the same userdata values and as long as you're dereferencing in your scripts, it won't be a problem.

The is an example of a script which fails to dereference, because when the player quits their userdata value remains in the table, but what if in a weeks time another player joins and they get assigned the same userdata value?
<syntaxhighlight lang="lua">

local admins = {}
local secretPasswordOnlyAdminsShouldKnow = "12345678"

function adminLogin()
if (hasObjectPermissionTo(source, "command.ban", false)) then
admins[source] = true
end
end
addEventHandler("onPlayerLogin", root, adminLogin)

function cmdGetSecretPassword(plr)
if (not admins[plr]) then
return false
end
outputChatBox("The secret password is "..secretPasswordOnlyAdminsShouldKnow, plr)
end
addCommandHandler("getsecretpass", cmdGetSecretPassword)
</syntaxhighlight>

Some random player who joins in a weeks time gets the same userdata value as an admin, that player can now use "getsecretpass". Solution? De-reference on destruction!
<syntaxhighlight lang="lua">

function onQuit()
admins[source] = nil
end
addEventHandler("onPlayerQuit", root, onQuit)
</syntaxhighlight>

== Server Performance ==
* Server lagging? Check [[Debugging#Debugging_Performance_Issues|this page of debugging performance issues]]
* Using '''localPlayer''' (or if not possible: '''resourceRoot''') in '''2nd''' argument of triggerServer(Client)Event for events is much more efficient than using root.
* Try to be efficient, but if what you're doing is too time consuming or complex, is it really efficient?
* Unless you have hundreds of players, don't worry about making little optimizations, check ''performancebrowser'' or ''ipb'' (ingame performancebrowser) and make sure no resource is using significantly more than the others.

== Client Performance ==
* The biggest cause of client script CPU usage is anything done in onClient/Pre/HUD/Render because it is called every frame. For example if you have a script which calls dxDrawLine3D 20 times, 60 times a second, if those lines are only in 1 part of the map, consider adding a [[getDistanceBetweenPoints3D]] check between the local player and the general area that those lines are in and if they're no where near the player, don't draw the lines.
* '''dxDraw*''' functions can be highly optimised by using [https://wiki.multitheftauto.com/wiki/DxCreateRenderTarget dxCreateRenderTarget], which will merge them into one single '''dxDrawImage''' resulting in much less calls. This can be applied to parts of interface which are static, or updated periodically.
* Another thing that gets called a lot and could therefore be quite consuming if not careful are events like [[onClientPlayerWeaponFire]] and [[onClientPlayerDamage]] so any scripts that use these should only be bound to the necessary elements (such as localPlayer instead of root) and run the simplest if statements for example if you wanted to handle a certain weapon being fired in a certain dimension it's better to check weapon first as that's a simple weaponID == x rather than getElementDimension(source) == y.

== Speed comparison between local and global variables ==

=== Slower ===

<syntaxhighlight lang="lua">

start = getTickCount()
a = 1
for i=1,10000000 do
a = 1
end
stop = getTickCount()
print("global", stop - start ) -- more than 500ms
</syntaxhighlight>
=== Faster ===
<syntaxhighlight lang="lua">
start = getTickCount()
local b = 1
for i=1,10000000 do
b = 1
end
stop = getTickCount()
print("local", stop - start ) -- less than 200ms
</syntaxhighlight>

== Speed comparison between structural and OOP scripting ==
=== Slower ===
<syntaxhighlight lang="lua">
start = getTickCount()
a = 1
for i=1,1000000 do
a = localPlayer.position
end
stop = getTickCount()
print("variable", stop - start ) -- more than 1500ms
</syntaxhighlight>
=== Faster ===
<syntaxhighlight lang="lua">
start = getTickCount()
b = nil
for i=1,1000000 do
b = getElementPosition(localPlayer)
end
stop = getTickCount()
print("structural", stop - start ) -- less than 200ms
</syntaxhighlight>

OnPlayerZoneChange

2025-04-22T01:05:24Z

Srslyyyy: Code improvements, including security fix

{{Useful Function}}
<lowercasetitle></lowercasetitle> __NOTOC__
This code implements an [[event]] that is triggered when the [[player]] enters a new area on the map.

==Parameters==
No parameters.

==Source==
The [[event system#Event source|source]] of this event is the player whose zone was changed.

==Code==
<section name="Shared" class="both" show="true">
<syntaxhighlight lang="lua">
local playersZone = {}
local zoneEventName = (localPlayer and "onClientPlayerZoneChange" or "onPlayerZoneChange") -- client = "onClientPlayerZoneChange" — server = "onPlayerZoneChange"
local zoneCitiesOnly = false -- only major cities?

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

for playerID = 1, #playersTable do
local playerElement = playersTable[playerID]
local playerX, playerY, playerZ = getElementPosition(playerElement)
local playerZoneNow = getZoneName(playerX, playerY, playerZ, zoneCitiesOnly)
local playerZoneSaved = playersZone[playerElement]
local playerZoneNeedsUpdate = (playerZoneSaved and playerZoneSaved ~= playerZoneNow)

if (playerZoneNeedsUpdate) then
triggerEvent(zoneEventName, playerElement, playerZoneSaved, playerZoneNow)
end

playersZone[playerElement] = playerZoneNow
end
end
addEvent(zoneEventName, false) -- disable remote triggering so players couldn't trigger this event on server (& vice-versa)
setTimer(checkPlayersZone, 1000, 0)

local function clearPlayersZone()
playersZone[source] = nil
end
addEventHandler(localPlayer and "onClientPlayerQuit" or "onPlayerQuit", root, clearPlayersZone)

-- example for server:

function onPlayerZoneChange(oldZone, newZone)
iprint(source, oldZone, newZone)
end
addEventHandler("onPlayerZoneChange", root, onPlayerZoneChange)
</syntaxhighlight>
</section>

'''Author:''' [[User:IManGaaX|Youssef Maged (iManGaaX)]]

==Examples==
This example will make label with the full zone name of the player, '''onPlayerZoneChange''' is function is change the label text to new zone when the player enter a new zone.
{{RequiredFunctions|getElementZoneFullName}}
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
local myCurrentZoneLabel

addEventHandler("onClientResourceStart", resourceRoot, function()
local text = getElementZoneFullName(localPlayer)
myCurrentZoneLabel = guiCreateLabel(0, 0, 0.20, 0.02, text, true)
end)

addEventHandler("onPlayerZoneChange", root, function()
if (source == localPlayer) then
local newText = getElementZoneFullName(localPlayer)
guiSetText(myCurrentZoneLabel, newText)
end
end)
</syntaxhighlight>
</section>
This example will out put in the chat the new zone full name when the player enter a new zone.
{{RequiredFunctions|getElementZoneFullName}}
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
addEventHandler("onPlayerZoneChange", root, function()
local newZone = getElementZoneFullName(source)
outputChatBox("Your Zone is Changed to "..(newZone)..".", source, 255, 255, 0)
end)
</syntaxhighlight>
</section>

==See Also==

{{Useful_Functions}}

PathListDir

2025-04-20T21:49:25Z

Srslyyyy:

__NOTOC__
{{Shared function}}

{{New feature/item|3.161|1.6.0|22470|
Reads a specified directory and returns all entries inside of it. These entries can be file or folder names.
}}
{{Note|
* Listing other resource directory can be done by passing '''":resourceName/."'''
* For listing current resource (the one where code is executed), you can pass either '''""''' or '''":currentResourceName/."'''
}}

==Syntax==
<syntaxhighlight lang="lua">
table pathListDir ( string path )
</syntaxhighlight>
{{OOP||[[path]]:listDir}}

===Required Arguments===
*'''path:''' A [[string]] containing a path you want to get entries from

===Returns===
Returns [[table]] with all entries in a specified directory.

==Example==
<section name="Client" class="client" show="true">
This example loads all models from a certain directory
<syntaxhighlight lang="lua">
-- from https://gist.github.com/kgriffs/124aae3ac80eefe57199451b823c24ec
local function stringEndsWith(str, ending)
return ending == "" or str:sub(-#ending) == ending
end

-- get all files from a models directory that exists in the resource root folder (resources/ResourceName)
-- and load them into the game
addEventHandler('onClientResourceStart', resourceRoot, function()
local entries = pathListDir('models') or {}
for _, fileOrFolder in ipairs(entries) do
if pathIsFile(fileOrFolder) then
local file = fileOrFolder
local modelName = tonumber(file:sub(1, -5))
if modelName then
-- the full path to the file
local filePath = 'models/'..file

if stringEndsWith(file, '.col') then
local colData = engineLoadCOL(filePath)
if colData then
engineReplaceCOL(colData, modelName)
end
end
if stringEndsWith(file, '.txd') then
local txdData = engineLoadTXD(filePath)
if txdData then
engineImportTXD(txdData, modelName)
end
end
if stringEndsWith(file, '.dff') then
local dffData = engineLoadDFF(filePath)
if dffData then
engineReplaceModel(dffData, modelName)
end
end
end
end
end
end, false)
</syntaxhighlight>
</section>

==See Also==
{{Shared_path_functions}}

PathListDir

2025-04-20T18:58:07Z

Srslyyyy: Add note about listing current & other resource directories

__NOTOC__
{{Shared function}}

{{New feature/item|3.161|1.6.0|22470|
Reads a specified directory and returns all entries inside of it. These entries can be file or folder names.
}}
{{Note|
* Listing other resource directory can be done by passing '''":resourceName/."'''
* For listing current resource (the one where code is executed), you can pass either '''""''' or '''":resourceName/."'''
}}

==Syntax==
<syntaxhighlight lang="lua">
table pathListDir ( string path )
</syntaxhighlight>
{{OOP||[[path]]:listDir}}

===Required Arguments===
*'''path:''' A [[string]] containing a path you want to get entries from

===Returns===
Returns [[table]] with all entries in a specified directory.

==Example==
<section name="Client" class="client" show="true">
This example loads all models from a certain directory
<syntaxhighlight lang="lua">
-- from https://gist.github.com/kgriffs/124aae3ac80eefe57199451b823c24ec
local function stringEndsWith(str, ending)
return ending == "" or str:sub(-#ending) == ending
end

-- get all files from a models directory that exists in the resource root folder (resources/ResourceName)
-- and load them into the game
addEventHandler('onClientResourceStart', resourceRoot, function()
local entries = pathListDir('models') or {}
for _, fileOrFolder in ipairs(entries) do
if pathIsFile(fileOrFolder) then
local file = fileOrFolder
local modelName = tonumber(file:sub(1, -5))
if modelName then
-- the full path to the file
local filePath = 'models/'..file

if stringEndsWith(file, '.col') then
local colData = engineLoadCOL(filePath)
if colData then
engineReplaceCOL(colData, modelName)
end
end
if stringEndsWith(file, '.txd') then
local txdData = engineLoadTXD(filePath)
if txdData then
engineImportTXD(txdData, modelName)
end
end
if stringEndsWith(file, '.dff') then
local dffData = engineLoadDFF(filePath)
if dffData then
engineReplaceModel(dffData, modelName)
end
end
end
end
end
end, false)
</syntaxhighlight>
</section>

==See Also==
{{Shared_path_functions}}

GetPositionInFrontOfElement

2025-04-20T01:31:06Z

Srslyyyy: No need for table here

{{Useful Function}}
This function returns position in provided distance away from element, including element's rotation<br>

==Syntax==
<syntaxhighlight lang="lua">float, float, float getPositionInFrontOfElement( element theElement, float distance )</syntaxhighlight>

===Required Arguments===
* '''theElement''': The element you want to get position in front of.
* '''distance''': Distance from an element you want to get position in.

===Returns===
Returns three ''floats'' indicating the position in front of the element, ''x'', ''y'' and ''z'' respectively.

==Code==
<section name="Shared" class="both" show="true">
<syntaxhighlight lang="lua">
function getPositionInFrontOfElement(theElement, distance)
assert((type(theElement) == "element" or type(theElement == "userdata")), "Bad argument @ 'getPositionInFrontOfElement' [Expected element at argument 1, got "..(type(theElement)).."]")

local x, y, z = getElementPosition(theElement)
local _, _, rz = getElementRotation(theElement)

local rotationRad = math.rad(rz)
local objX = x - distance * math.sin(rotationRad)
local objY = y + distance * math.cos(rotationRad)
local objZ = z

return objX, objY, objZ
end
</syntaxhighlight>
</section>

==Example==
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
addCommandHandler("createtreeonmyface", function(_, distance)
local x, y, z = getPositionInFrontOfElement(localPlayer, tonumber(distance))
if (x) then
createObject(660, x, y, z)
end
end)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
addCommandHandler("createtreeonmyface", function(player, _, distance)
local x, y, z = getPositionInFrontOfElement(player, tonumber(distance))
if (x) then
createObject(660, x, y, z)
end
end)
</syntaxhighlight>
</section>

'''Author:''' bover.

==See Also==
{{Useful_Functions}}

SetFPSLimit

2025-04-18T12:08:19Z

Srslyyyy: /* Required Arguments */

{{Server client function}}
__NOTOC__
This function sets the maximum [http://en.wikipedia.org/wiki/Frame_rate FPS (Frames per second)] that players on the server can run their game at.
{{Note|
* When set client side, the actual limit used is the lowest of both the server and client set values.
* Starting from version [[https://buildinfo.mtasa.com/?Revision=21313&Branch r21313]] and above '''fpsLimit''' range is '''25-32767'''. In older MTA releases it was '''25-100'''.
}}
==Syntax==
<syntaxhighlight lang="lua">
bool setFPSLimit ( int fpsLimit )
</syntaxhighlight>

===Required Arguments===
*'''fpsLimit:''' An integer value representing the maximum FPS. Refer to the note above for possible values. You can also pass '''0''' or '''false''', in which case the FPS limit will be the one set in the client settings (by default, '''100 FPS''' and the client fps limit should also be manually changed via "'''fps_limit=0'''" in console or '''MTA San Andreas\MTA\config\coreconfig.xml''').

===Returns===
Returns ''true'' if successful, or ''false'' if it was not possible to set the limit or an invalid value was passed.

==Issues when increasing FPS==
Note: with "very high" FPS, any FPS limit over 74 is meant.
It is recommended to set a conservative FPS limit (between 40-60 and 74 highest) because high FPS can break some GTA internal calculations, causing various bugs. The higher the FPS the more of a problem these become:

74 FPS is the breaking point that opens the door to various more severe GTA bugs related to FPS and physics.

* Physics of vehicles is effected, both high and low FPSes may bring their own set of unfair advantages. Speaking about the consequences of high FPS in this context, up to 70 or 74 FPS is considered safe (as any differences in physics, if they do exist to begin with as they theoretically should, are so tiny that they are unmeasurable and thus wouldn't affect racing results in practise). Anything beyond 74 FPS may cause impactful discrepancies.

* Pressing the horn button to turn on and off sirens gets really hard at very high FPS. For instance, at 100 FPS, you are more likely to hit the regular horn 3 times (inconsistent) before eventually triggering the siren, besides taking a similar amount of tries to turn off the siren.
* At very high FPS, climbing over certain objects will result in instant death. Example at: 2520.108, -1681.407, 19.406, 266 - [https://wiki.multitheftauto.com/wiki/SetFPSLimit#Fix_for_climbing_over_certain_objects you can use this Lua code to fix it.]
* The higher your FPS, the more of a penalty in satchel throwing distance (up to ~10% at very high FPS) will apply.

For a full list of FPS-related GTA bugs (that are much less likely to impact gameplay in a meaningful way) and MTA developers' progress in tackling them, see the [https://github.com/multitheftauto/mtasa-blue/projects/14 Framerate issues tracker] github project.

==Example==
This example allows players to limit their own FPS using a command.
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
local minFPS = 25
local maxFPS = 100

function fpsFunction(commandName, fpsLimit)
local newFPS = tonumber(fpsLimit)
local displaySyntax = (not newFPS) or (newFPS < minFPS) or (newFPS > maxFPS)

if (displaySyntax) then
outputChatBox("Syntax: /"..commandName.." ["..minFPS.." ~ "..maxFPS.."] - limit your own FPS.")

return false
end

local currentLimit = getFPSLimit()
local setNewFPS = (newFPS ~= currentLimit)

if (setNewFPS) then
outputChatBox("Your FPS has been limited to: "..newFPS..".")
setFPSLimit(newFPS)
end
end
addCommandHandler("limitfps", fpsFunction)
addCommandHandler("fpslimit", fpsFunction)
</syntaxhighlight>
</section>

== Fix for climbing over certain objects==
You can use this small code to fix one of high FPS issues, specifically the one which would instantly kill player climbing over some objects.
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function onClientPlayerDamage(attackerElement, damageType, bodyPart)
local fallDamage = (damageType == 54)

if (not fallDamage) then
return false
end

local playerTask = getPedSimplestTask(localPlayer)
local playerClimbing = (playerTask == "TASK_SIMPLE_CLIMB")

if (playerClimbing) then
cancelEvent()
end
end
addEventHandler("onClientPlayerDamage", localPlayer, onClientPlayerDamage)
</syntaxhighlight>
</section>

==See Also==
{{Server functions}}

[[pl:setFPSLimit]]
[[ru:setFPSLimit]]

SetFPSLimit

2025-04-18T12:07:54Z

Srslyyyy: /* Example */

{{Server client function}}
__NOTOC__
This function sets the maximum [http://en.wikipedia.org/wiki/Frame_rate FPS (Frames per second)] that players on the server can run their game at.
{{Note|
* When set client side, the actual limit used is the lowest of both the server and client set values.
* Starting from version [[https://buildinfo.mtasa.com/?Revision=21313&Branch r21313]] and above '''fpsLimit''' range is '''25-32767'''. In older MTA releases it was '''25-100'''.
}}
==Syntax==
<syntaxhighlight lang="lua">
bool setFPSLimit ( int fpsLimit )
</syntaxhighlight>

===Required Arguments===
*'''fpsLimit:''' An integer value representing the maximum FPS. Refer to the note above for possible values. You can also pass '''0''' or '''false''', in which case the FPS limit will be the one set in the client settings (by default, '''100 FPS''' and the client fps limit should also be manually changed via "'''fps_limit=0'''" in console or '''MTA San Andreas 1.5\MTA\config\coreconfig.xml''').

===Returns===
Returns ''true'' if successful, or ''false'' if it was not possible to set the limit or an invalid value was passed.

==Issues when increasing FPS==
Note: with "very high" FPS, any FPS limit over 74 is meant.
It is recommended to set a conservative FPS limit (between 40-60 and 74 highest) because high FPS can break some GTA internal calculations, causing various bugs. The higher the FPS the more of a problem these become:

74 FPS is the breaking point that opens the door to various more severe GTA bugs related to FPS and physics.

* Physics of vehicles is effected, both high and low FPSes may bring their own set of unfair advantages. Speaking about the consequences of high FPS in this context, up to 70 or 74 FPS is considered safe (as any differences in physics, if they do exist to begin with as they theoretically should, are so tiny that they are unmeasurable and thus wouldn't affect racing results in practise). Anything beyond 74 FPS may cause impactful discrepancies.

* Pressing the horn button to turn on and off sirens gets really hard at very high FPS. For instance, at 100 FPS, you are more likely to hit the regular horn 3 times (inconsistent) before eventually triggering the siren, besides taking a similar amount of tries to turn off the siren.
* At very high FPS, climbing over certain objects will result in instant death. Example at: 2520.108, -1681.407, 19.406, 266 - [https://wiki.multitheftauto.com/wiki/SetFPSLimit#Fix_for_climbing_over_certain_objects you can use this Lua code to fix it.]
* The higher your FPS, the more of a penalty in satchel throwing distance (up to ~10% at very high FPS) will apply.

For a full list of FPS-related GTA bugs (that are much less likely to impact gameplay in a meaningful way) and MTA developers' progress in tackling them, see the [https://github.com/multitheftauto/mtasa-blue/projects/14 Framerate issues tracker] github project.

==Example==
This example allows players to limit their own FPS using a command.
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
local minFPS = 25
local maxFPS = 100

function fpsFunction(commandName, fpsLimit)
local newFPS = tonumber(fpsLimit)
local displaySyntax = (not newFPS) or (newFPS < minFPS) or (newFPS > maxFPS)

if (displaySyntax) then
outputChatBox("Syntax: /"..commandName.." ["..minFPS.." ~ "..maxFPS.."] - limit your own FPS.")

return false
end

local currentLimit = getFPSLimit()
local setNewFPS = (newFPS ~= currentLimit)

if (setNewFPS) then
outputChatBox("Your FPS has been limited to: "..newFPS..".")
setFPSLimit(newFPS)
end
end
addCommandHandler("limitfps", fpsFunction)
addCommandHandler("fpslimit", fpsFunction)
</syntaxhighlight>
</section>

== Fix for climbing over certain objects==
You can use this small code to fix one of high FPS issues, specifically the one which would instantly kill player climbing over some objects.
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function onClientPlayerDamage(attackerElement, damageType, bodyPart)
local fallDamage = (damageType == 54)

if (not fallDamage) then
return false
end

local playerTask = getPedSimplestTask(localPlayer)
local playerClimbing = (playerTask == "TASK_SIMPLE_CLIMB")

if (playerClimbing) then
cancelEvent()
end
end
addEventHandler("onClientPlayerDamage", localPlayer, onClientPlayerDamage)
</syntaxhighlight>
</section>

==See Also==
{{Server functions}}

[[pl:setFPSLimit]]
[[ru:setFPSLimit]]

SetFPSLimit

2025-04-04T06:37:32Z

Srslyyyy: /* Fix for climbing over certain objects */

{{Server client function}}
__NOTOC__
This function sets the maximum [http://en.wikipedia.org/wiki/Frame_rate FPS (Frames per second)] that players on the server can run their game at.
{{Note|
* When set client side, the actual limit used is the lowest of both the server and client set values.
* Starting from version [[https://buildinfo.mtasa.com/?Revision=21313&Branch r21313]] and above '''fpsLimit''' range is '''25-32767'''. In older MTA releases it was '''25-100'''.
}}
==Syntax==
<syntaxhighlight lang="lua">
bool setFPSLimit ( int fpsLimit )
</syntaxhighlight>

===Required Arguments===
*'''fpsLimit:''' An integer value representing the maximum FPS. Refer to the note above for possible values. You can also pass '''0''' or '''false''', in which case the FPS limit will be the one set in the client settings (by default, '''100 FPS''' and the client fps limit should also be manually changed via "'''fps_limit=0'''" in console or '''MTA San Andreas 1.5\MTA\config\coreconfig.xml''').

===Returns===
Returns ''true'' if successful, or ''false'' if it was not possible to set the limit or an invalid value was passed.

==Issues when increasing FPS==
Note: with "very high" FPS, any FPS limit over 74 is meant.
It is recommended to set a conservative FPS limit (between 40-60 and 74 highest) because high FPS can break some GTA internal calculations, causing various bugs. The higher the FPS the more of a problem these become:

74 FPS is the breaking point that opens the door to various more severe GTA bugs related to FPS and physics.

* Physics of vehicles is effected, both high and low FPSes may bring their own set of unfair advantages. Speaking about the consequences of high FPS in this context, up to 70 or 74 FPS is considered safe (as any differences in physics, if they do exist to begin with as they theoretically should, are so tiny that they are unmeasurable and thus wouldn't affect racing results in practise). Anything beyond 74 FPS may cause impactful discrepancies.

* Pressing the horn button to turn on and off sirens gets really hard at very high FPS. For instance, at 100 FPS, you are more likely to hit the regular horn 3 times (inconsistent) before eventually triggering the siren, besides taking a similar amount of tries to turn off the siren.
* At very high FPS, climbing over certain objects will result in instant death. Example at: 2520.108, -1681.407, 19.406, 266 - [https://wiki.multitheftauto.com/wiki/SetFPSLimit#Fix_for_climbing_over_certain_objects you can use this Lua code to fix it.]
* The higher your FPS, the more of a penalty in satchel throwing distance (up to ~10% at very high FPS) will apply.

For a full list of FPS-related GTA bugs (that are much less likely to impact gameplay in a meaningful way) and MTA developers' progress in tackling them, see the [https://github.com/multitheftauto/mtasa-blue/projects/14 Framerate issues tracker] github project.

==Example==
This example allows players to limit their own FPS using a command.
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
local minFPS = 25
local maxFPS = 100

function fpsFunction(commandName, fpsLimit)
local newFPS = tonumber(fpsLimit)
local displaySyntax = (not newFPS) or (newFPS < minFPS) or (newFPS > maxFPS)

if displaySyntax then
outputChatBox("Syntax: /"..commandName.." ["..minFPS.." ~ "..maxFPS.."] - limit your own FPS.")

return false
end

local currentLimit = getFPSLimit()
local setNewFPS = (newFPS ~= currentLimit)

if setNewFPS then
outputChatBox("Your FPS has been limited to: "..newFPS..".")
setFPSLimit(newFPS)
end
end
addCommandHandler("limitfps", fpsFunction)
addCommandHandler("fpslimit", fpsFunction)
</syntaxhighlight>
</section>

== Fix for climbing over certain objects==
You can use this small code to fix one of high FPS issues, specifically the one which would instantly kill player climbing over some objects.
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function onClientPlayerDamage(attackerElement, damageType, bodyPart)
local fallDamage = (damageType == 54)

if (not fallDamage) then
return false
end

local playerTask = getPedSimplestTask(localPlayer)
local playerClimbing = (playerTask == "TASK_SIMPLE_CLIMB")

if (playerClimbing) then
cancelEvent()
end
end
addEventHandler("onClientPlayerDamage", localPlayer, onClientPlayerDamage)
</syntaxhighlight>
</section>

==See Also==
{{Server functions}}

[[pl:setFPSLimit]]
[[ru:setFPSLimit]]

Script security

2025-04-01T19:30:49Z

Srslyyyy: /* Securing projectiles & explosions */

==Awareness of client memory==

Starting from very basics:
* You should be aware that everything you store on client-side is at risk, this includes .lua files as well. Any confidential (and/or) important data which is stored, or travels through client-side (player PC) could be accessed by malicious clients.
* To keep sensitive data (and/or) Lua logic safe - use server-side.
* Do note that scripts marked as '''shared''' act also as '''client code''', which means that everything above applies to them. For example defining:

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

Is same as doing:

<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, if it didn't existed before) 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]]

Texture pixels

2025-04-01T19:15:44Z

Srslyyyy: /* Pixels more */

__NOTOC__====Pixels====
-----------------
'''*''' MTA refers to the raw information that a [[texture]] contains as 'pixels'.

'''*''' Pixels can be retrieved from any [[texture]] type including [[dxCreateRenderTarget|render targets]] and [[dxCreateScreenSource|screen sources]] by using the function [[dxGetTexturePixels]].

'''*''' Pixels are just a string to Lua, so they can be saved to a file or even sent over the 'internet'.

====Pixels properties====
-----------------
Pixels have two properties:
*'''dimensions''' (width and height) which is retrieved by using the function [[dxGetPixelsSize]]
*'''format''' (plain,jpeg,png,dds) which is retrieved by using the function [[dxGetPixelsFormat]]
**''plain'' - Fastest and simplest - It's default format of the pixels returned by [[dxGetTexturePixels]] and the only one that can be used with [[dxSetTexturePixels]], [[dxGetPixelColor]] and [[dxSetPixelColor]]. But it also uses a lot of bytes, so internet transfers will be longer. Also can't be read by Photoshop or browsers etc.
**''png'' - A few less bytes, still quite big for net transfers. Can be saved to a file and read by Photoshop and browsers etc.
**''jpeg'' - A lot less bytes, so best for net transfers. Can be saved to a file and read by Photoshop and browsers etc.
**''dds'' - DirectDraw Surface. Game's native texture format with various compressed and uncompressed options. Used to store standard, cube or volume textures. Compressed pixels in this format can be loaded nearly instantly by [[dxCreateTexture]].

To convert between the 3 different formats, use the function [[dxConvertPixels]]

====Pixels more====
-----------
Pixels can also be loaded from any png/jpeg file just like this:
<syntaxhighlight lang="lua">
local fileHandler = fileOpen("hello.jpg")

if (not fileHandler) then
return false
end

local fileSize = fileGetSize(fileHandler)
local filePixels = fileRead(fileHandler, fileSize)

fileClose(fileHandler)
</syntaxhighlight>

Pixels can be used to create textures just like this:
<syntaxhighlight lang="lua">
local newTexture = dxCreateTexture(pixelsData)
</syntaxhighlight>

Pixels can be used to save textures just like this:
<syntaxhighlight lang="lua">
local texturePixels = dxGetTexturePixels(myRenderTarget)
local texturePixelsConverted = dxConvertPixels(texturePixels, "jpeg")
local fileHandler = fileCreate("piccy.jpg")

if (not fileHandler) then
return false
end

fileWrite(fileHandler, texturePixelsConverted)
fileClose(fileHandler)
</syntaxhighlight>

====Pixels performance====
------------------
Getting/setting pixels from textures is not quick and not something you want to be doing every frame (in onClientRender for example).
Setting pixels to a render target is especially slow. Pixels are ideal however for transferring composite images built on a render target into a normal texture for later use. For example, making a custom radar map.

Texture pixels

2025-04-01T19:15:14Z

Srslyyyy: /* Pixels more */

__NOTOC__====Pixels====
-----------------
'''*''' MTA refers to the raw information that a [[texture]] contains as 'pixels'.

'''*''' Pixels can be retrieved from any [[texture]] type including [[dxCreateRenderTarget|render targets]] and [[dxCreateScreenSource|screen sources]] by using the function [[dxGetTexturePixels]].

'''*''' Pixels are just a string to Lua, so they can be saved to a file or even sent over the 'internet'.

====Pixels properties====
-----------------
Pixels have two properties:
*'''dimensions''' (width and height) which is retrieved by using the function [[dxGetPixelsSize]]
*'''format''' (plain,jpeg,png,dds) which is retrieved by using the function [[dxGetPixelsFormat]]
**''plain'' - Fastest and simplest - It's default format of the pixels returned by [[dxGetTexturePixels]] and the only one that can be used with [[dxSetTexturePixels]], [[dxGetPixelColor]] and [[dxSetPixelColor]]. But it also uses a lot of bytes, so internet transfers will be longer. Also can't be read by Photoshop or browsers etc.
**''png'' - A few less bytes, still quite big for net transfers. Can be saved to a file and read by Photoshop and browsers etc.
**''jpeg'' - A lot less bytes, so best for net transfers. Can be saved to a file and read by Photoshop and browsers etc.
**''dds'' - DirectDraw Surface. Game's native texture format with various compressed and uncompressed options. Used to store standard, cube or volume textures. Compressed pixels in this format can be loaded nearly instantly by [[dxCreateTexture]].

To convert between the 3 different formats, use the function [[dxConvertPixels]]

====Pixels more====
-----------
Pixels can also be loaded from any png/jpeg file just like this:
<syntaxhighlight lang="lua">
local fileHandler = fileOpen("hello.jpg")

if (not fileHandler) then
return false
end

local fileSize = fileGetSize(fileHandler)
local filePixels = fileRead(fileHandler, fileSize)

fileClose(fileHandler)
</syntaxhighlight>

Pixels can be used to create textures just like this:
<syntaxhighlight lang="lua">
local myNewTexture = dxCreateTexture(pixelsData)
</syntaxhighlight>

Pixels can be used to save textures just like this:
<syntaxhighlight lang="lua">
local texturePixels = dxGetTexturePixels(myRenderTarget)
local texturePixelsConverted = dxConvertPixels(texturePixels, "jpeg")
local fileHandler = fileCreate("piccy.jpg")

if (not fileHandler) then
return false
end

fileWrite(fileHandler, texturePixelsConverted)
fileClose(fileHandler)
</syntaxhighlight>

====Pixels performance====
------------------
Getting/setting pixels from textures is not quick and not something you want to be doing every frame (in onClientRender for example).
Setting pixels to a render target is especially slow. Pixels are ideal however for transferring composite images built on a render target into a normal texture for later use. For example, making a custom radar map.

Texture pixels

2025-04-01T19:13:33Z

Srslyyyy:

__NOTOC__====Pixels====
-----------------
'''*''' MTA refers to the raw information that a [[texture]] contains as 'pixels'.

'''*''' Pixels can be retrieved from any [[texture]] type including [[dxCreateRenderTarget|render targets]] and [[dxCreateScreenSource|screen sources]] by using the function [[dxGetTexturePixels]].

'''*''' Pixels are just a string to Lua, so they can be saved to a file or even sent over the 'internet'.

====Pixels properties====
-----------------
Pixels have two properties:
*'''dimensions''' (width and height) which is retrieved by using the function [[dxGetPixelsSize]]
*'''format''' (plain,jpeg,png,dds) which is retrieved by using the function [[dxGetPixelsFormat]]
**''plain'' - Fastest and simplest - It's default format of the pixels returned by [[dxGetTexturePixels]] and the only one that can be used with [[dxSetTexturePixels]], [[dxGetPixelColor]] and [[dxSetPixelColor]]. But it also uses a lot of bytes, so internet transfers will be longer. Also can't be read by Photoshop or browsers etc.
**''png'' - A few less bytes, still quite big for net transfers. Can be saved to a file and read by Photoshop and browsers etc.
**''jpeg'' - A lot less bytes, so best for net transfers. Can be saved to a file and read by Photoshop and browsers etc.
**''dds'' - DirectDraw Surface. Game's native texture format with various compressed and uncompressed options. Used to store standard, cube or volume textures. Compressed pixels in this format can be loaded nearly instantly by [[dxCreateTexture]].

To convert between the 3 different formats, use the function [[dxConvertPixels]]

====Pixels more====
-----------
Pixels can also be loaded from any png/jpeg file just like this:
<syntaxhighlight lang="lua">
local fileHandler = fileOpen("hello.jpg")

if (not fileHandler) then
return false
end

local fileSize = fileGetSize(fileHandler)
local filePixels = fileRead(fileHandler, fileSize)

fileClose(filePixels)
</syntaxhighlight>

Pixels can be used to create textures just like this:
<syntaxhighlight lang="lua">
local myNewTexture = dxCreateTexture(pixelsData)
</syntaxhighlight>

Pixels can be used to save textures just like this:
<syntaxhighlight lang="lua">
local texturePixels = dxGetTexturePixels(myRenderTarget)
local texturePixelsConverted = dxConvertPixels(texturePixels, "jpeg")
local fileHandler = fileCreate("piccy.jpg")

if (not fileHandler) then
return false
end

fileWrite(fileHandler, texturePixelsConverted)
fileClose(fileHandler)
</syntaxhighlight>

====Pixels performance====
------------------
Getting/setting pixels from textures is not quick and not something you want to be doing every frame (in onClientRender for example).
Setting pixels to a render target is especially slow. Pixels are ideal however for transferring composite images built on a render target into a normal texture for later use. For example, making a custom radar map.