Multi Theft Auto: Wiki - User contributions [en]

SetDynamicPedShadowsEnabled

2026-04-17T10:08:39Z

Arran Fortuna:

__NOTOC__
{{Client function}}
This function allows scripts to override the current dynamic ped shadow setting on the client.

When used, it temporarily overrides the player’s video setting for dynamic ped shadows. To restore the original value based on the player's settings, use [[resetDynamicPedShadows]].

==Syntax==
<syntaxhighlight lang="lua">
bool setDynamicPedShadowsEnabled ( bool enabled )
</syntaxhighlight>

===Required Arguments===
*'''enabled:''' a boolean value specifying whether dynamic ped shadows should be enabled (''true'') or disabled (''false'').

===Returns===
Returns ''true'' if the setting was successfully applied, ''false'' otherwise.

===Examples===
<syntaxhighlight lang="lua">
-- Disable dynamic ped shadows
setDynamicPedShadowsEnabled(false)
</syntaxhighlight>

===Example: Toggle shadows===
<syntaxhighlight lang="lua">
local current = isDynamicPedShadowsEnabled()
setDynamicPedShadowsEnabled(not current)
</syntaxhighlight>

===Example: Disable shadows on resource start and restore on stop===
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart", resourceRoot,
function()
setDynamicPedShadowsEnabled(false)
end
)

addEventHandler("onClientResourceStop", resourceRoot,
function()
resetDynamicPedShadows()
end
)
</syntaxhighlight>

==See Also==
{{Client world functions}}

SetDynamicPedShadowsEnabled

2026-04-17T10:04:13Z

Arran Fortuna:

IsDynamicPedShadowsEnabled

2026-04-17T10:04:00Z

Arran Fortuna:

__NOTOC__
{{Client function}}
This function checks whether dynamic shadows for peds are currently enabled on the client.

The returned value may reflect:
* The player's video settings.
* Any override applied using [[setDynamicPedShadowsEnabled]].

Use [[resetDynamicPedShadows]] to restore the setting back to the player’s original video configuration.

==Syntax==
<syntaxhighlight lang="lua">
bool isDynamicPedShadowsEnabled ( )
</syntaxhighlight>

===Required Arguments===
*None

===Returns===
Returns ''true'' if dynamic ped shadows are enabled, ''false'' otherwise.

===Examples===
<syntaxhighlight lang="lua">
if isDynamicPedShadowsEnabled() then
outputChatBox("Dynamic ped shadows are enabled.")
else
outputChatBox("Dynamic ped shadows are disabled.")
end
</syntaxhighlight>

===Example: Toggle shadows===
<syntaxhighlight lang="lua">
-- Toggle dynamic ped shadows
local current = isDynamicPedShadowsEnabled()
setDynamicPedShadowsEnabled(not current)
</syntaxhighlight>

==See Also==
{{World functions|client}}

ResetDynamicPedShadows

2026-04-17T10:03:46Z

Arran Fortuna:

__NOTOC__
{{Client function}}
This function restores the dynamic ped shadow setting back to the player's original video configuration.

If [[setDynamicPedShadowsEnabled]] was used to override the setting, calling this function will remove that override and reapply the value defined in the player's settings.

This is useful for ensuring that temporary changes made by a resource do not persist after it stops.

==Syntax==
<syntaxhighlight lang="lua">
bool resetDynamicPedShadows ( )
</syntaxhighlight>

===Required Arguments===
*None

===Returns===
Returns ''true'' if the reset was successful, ''false'' otherwise.

===Examples===
<syntaxhighlight lang="lua">
-- Reset dynamic ped shadows to player's settings
resetDynamicPedShadows()
</syntaxhighlight>

===Example: Safe usage in a resource===
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart", resourceRoot,
function()
setDynamicPedShadowsEnabled(false)
end
)

addEventHandler("onClientResourceStop", resourceRoot,
function()
resetDynamicPedShadows()
end
)
</syntaxhighlight>

==See Also==
{{World functions|client}}

SetDynamicPedShadowsEnabled

2026-04-17T10:02:21Z

Arran Fortuna:

ResetDynamicPedShadows

2026-04-17T09:55:33Z

Arran Fortuna: Created page with "__NOTOC__ {{Client function}} This function restores the dynamic ped shadow setting back to the player's original video configuration. If setDynamicPedShadowsEnabled was used to override the setting, calling this function will remove that override and reapply the value defined in the player's settings. This is useful for ensuring that temporary changes made by a resource do not persist after it stops. ==Syntax== <syntaxhighlight lang="lua"> bool resetDynamicPedSha..."

SetDynamicPedShadowsEnabled

2026-04-17T09:54:25Z

Arran Fortuna: Created page with "__NOTOC__ {{Client function}} This function allows scripts to override the current dynamic ped shadow setting on the client. When used, it temporarily overrides the player’s video setting for dynamic ped shadows. To restore the original value based on the player's settings, use resetDynamicPedShadows. ==Syntax== <syntaxhighlight lang="lua"> bool setDynamicPedShadowsEnabled ( bool enabled ) </syntaxhighlight> ===Required Arguments=== *'''enabled:''' a boolean val..."

IsDynamicPedShadowsEnabled

2026-04-17T09:53:02Z

Arran Fortuna: Created page with "__NOTOC__ {{Client function}} This function checks whether dynamic shadows for peds are currently enabled on the client. The returned value may reflect: * The player's video settings. * Any override applied using setDynamicPedShadowsEnabled. Use resetDynamicPedShadows to restore the setting back to the player’s original video configuration. ==Syntax== <syntaxhighlight lang="lua"> bool isDynamicPedShadowsEnabled ( ) </syntaxhighlight> ===Required Arguments==..."

EngineStreamingSetProperty

2026-04-13T16:16:30Z

Arran Fortuna:

{{MTA:Eir/Client_function}}

'''THIS IS NOT AN MTA FUNCTION!''' This should be deleted as it's part of an unfinished project.

__NOTOC__
This function changes the behavior of the GTA:SA streaming system. It is meant to optimize the performance of the game for your custom server. Changes in these properties affect the gameplay quality of the entire server.

==Syntax==
<syntaxhighlight lang="lua">
bool engineStreamingSetProperty ( string propertyName, var propValue )
</syntaxhighlight>

===Arguments===
*'''propertyName:''' the name of the streaming property you want to change
*'''propValue:''' value to pass to the property

===Valid Properties===
{{:MTA:Eir/functions/engineStreamingSetProperty/validProps}}

===Useful Media===
* https://dl.dropboxusercontent.com/u/55896914/eir_resources/streaming_opt.zip - streaming debugging resource
* https://dl.dropboxusercontent.com/u/55896914/eir_resources/streaming_test.zip - streaming mode example resource
* https://www.youtube.com/watch?v=sk8WsHwPgsU - showcase video

===Returns===
Returns ''true'' if valid arguments have been passed, ''false'' otherwise.

==Examples==
<section name="Client" class="client" show="true">
This snippet ultimatively fixes the world flickering.
<syntaxhighlight lang="lua">
engineStreamingSetProperty( "strictNodeDistrib", false );
engineStreamingSetProperty( "infiniteStreaming", true );
</syntaxhighlight>
</section>

<section name="Client" class="client" show="true">
This snippet sets the Streaming GC system to sparse mode. In this mode only the preallocated amount of Streaming GC nodes is allowed. Keeping a low amount of Streaming nodes is interesting for performance optimizations.
<syntaxhighlight lang="lua">
engineStreamingSetProperty( "gcOnDemand", true );
engineStreamingSetProperty( "infiniteStreaming", false );
engineStreamingSetProperty( "strictNodeDistrib", true );
</syntaxhighlight>
</section>

<section name="Client" class="client" show="true">
This snippet turns on fibered loading when the Streaming system is busy and leaves it that way for five seconds.
<syntaxhighlight lang="lua">
engineStreamingSetProperty( "isFibered", false );

local lastBusyTime = false;
local fiberedDuration = 5000;

addEventHandler( "onClientRender", root,
function()
local isBusy = engineGetStreamingInfo().isBusy;

if ( isBusy ) then
local now = getTickCount();

if not ( lastBusyTime ) then
lastBusyTime = now;

engineStreamingSetProperty( "isFibered", true );
end
elseif ( lastBusyTime ) then
if ( now - lastBusyTime > fiberedDuration ) then
engineStreamingSetProperty( "isFibered", false );
end
end
end
);
</syntaxhighlight>
</section>

<section name="Client" class="client" show="true">
This snippet makes the world load very slow. Lag spikes cannot occur due to Streaming loading anymore.
<syntaxhighlight lang="lua">
engineStreamingSetProperty( "isFibered", true );
engineStreamingSetProperty( "fiberedPerfMult", 0 );
</syntaxhighlight>
</section>

[[en:engineStreamingSetProperty]]

SetPedLookAt

2026-03-07T09:38:28Z

Arran Fortuna: Add example for remote player usage

__NOTOC__
{{Client function}}
{{Note|Avoid calling setPedLookAt every frame as this can cause bugs like being invincible to burning.}}
{{Important Note|For remote players, you have to use [https://wiki.multitheftauto.com/wiki/SetPedAimTarget setPedAimTarget] before setPedLookAt.}}
Makes a ped turn his head and look at a specific world position or element.
==Syntax==
<syntaxhighlight lang="lua">
bool setPedLookAt ( ped thePed, float x, float y, float z [, int time = 3000 [, int blend = 1000 ], element target = nil ] )
</syntaxhighlight>

===Required Arguments===
*'''thePed:''' the ped to change the lookat of.
*'''x:''' the x coordinate of the world position to look at.
*'''y:''' the y coordinate of the world position to look at.
*'''z:''' the z coordinate of the world position to look at.

===Optional Arguments===
*'''time:''' the time, in milliseconds, during which the ped will look at the target. Once this time has elapsed, he will look ahead again like before the function was applied. A time of 0 will immediately stop any lookat. A negative time will make the ped look at the target indefinitely.
*'''blend:''' the time, in milliseconds, during which the look will blend.
*'''target:''' if this argument is specified, the position arguments will be mean offsets relative to the target and the ped's gaze will follow the specified element instead. Can be a player, a vehicle, another ped etc.

==Example==
This example makes the local player look at where the camera points at. If you want to sync this effect with other players you can use [[triggerLatentServerEvent]] and [[triggerLatentClientEvent]] functions.
<syntaxhighlight lang="lua">
local screenSize_X, screenSize_Y = guiGetScreenSize()

function pedLookAt()
local x, y, z = getWorldFromScreenPosition(screenSize_X / 2, screenSize_Y / 2, 15)
setPedLookAt(localPlayer, x, y, z, -1, 0)
end
setTimer(pedLookAt, 120, 0)
</syntaxhighlight>

This example makes remote players heads move based on what direction their camera is facing.

<syntaxhighlight lang="lua">function remotePlayerHeadMoving()
local x, y, z = getElementPosition(localPlayer)
for i, player in pairs(getElementsWithinRange(x, y, z, 35, "player")) do
if (player ~= localPlayer and isElementOnScreen(player)) then
local rot = getPedCameraRotation(player)
local x, y, z = getElementPosition(player)
local vx = x + math.sin(math.rad(rot)) * 10
local vy = y + math.cos(math.rad(rot)) * 10
-- To fix remote player's head bug + check to avoid setPedAimTarget movement lag while aiming with gun
if (getPedTask(player, "secondary", 0) ~= "TASK_SIMPLE_USE_GUN") then
if (player ~= localPlayer) then
setPedAimTarget(player, vx, vy, z) -- head bug fix
end
setPedLookAt(player, vx, vy, z, -1, 0)
end
end
end
end
setTimer(remotePlayerHeadMoving, 100, 0)
</syntaxhighlight>

== Issues ==
{{Issues|
{{Issue|509|setPedLookAt does not work for remote players}}
{{Issue|626|setPedLookAt cancels damage done by any sort of fire}}
}}
==See Also==
{{Client ped functions}}

OnElementDataChange

2025-10-07T19:30:34Z

Arran Fortuna: Added info about being able to cancel the event.

{{Server event}}
__NOTOC__
This event is triggered ''after'' an element's [[element data|data]] entry is changed. Such changes can be made on the client or the server using [[setElementData]].

{{Note|These predefined variables are special in this event:
*'''client''': The [[event system#Event client|client]] global variable is set to the client that called [[setElementData]], or '''nil''' if it was called on the server.
*'''sourceResource''': The [[resource]] which changed the element data - '''nil''', if client synced data, '''resource''' element otherwise.}}

==Parameters==
<syntaxhighlight lang="lua">
string theKey, var oldValue, var newValue
</syntaxhighlight>

*'''theKey''': The name of the element data entry that has changed.
*'''oldValue''': The old value of this entry before it changed. See [[element data]] for a list of possible datatypes.
*'''newValue''': the new value of this entry after it changed. This will be equivalent to [[getElementData]](source, theKey).

==Cancelling==
This event cannot be cancelled using [[cancelEvent]]. To reverse the effect, use [[setElementData]] with the old value. See Example.

{{New items|3.0170|1.7.0|
This event can be cancelled using [[cancelEvent]]. If a client sent the cancelled change to the server, the server will send the client the server's version of the element data.
|25731}}

==Source==
The source of this event is the [[element]] whose element data changed.

==Example==
<section name="Server" class="server" show="true">
This example outputs a message to players when any of their element data values is changed.
<syntaxhighlight lang="lua">
function outputChange(theKey, oldValue, newValue)
if (getElementType(source) == "player") then -- check if the element is a player
outputChatBox("Your element data '" .. tostring(theKey) .. "' has changed from '" .. tostring(oldValue) .. "' to '" .. tostring(newValue) .. "'", source) -- output the change for the affected player
end
end
addEventHandler("onElementDataChange", root, outputChange)
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
This example checks and possibly reverses an element's data change.
<syntaxhighlight lang="lua">
function checkChange(theKey, oldValue)
-- The client can only set 'special_thing' on its own player
if (theKey== "special_thing") and (client ~= source) then
outputChatBox("Illegal setting of " .. tostring(theKey) .. "' by '" .. tostring(getPlayerName(client)))
setElementData(source, theKey, oldValue) -- Set back the original value
end
end
addEventHandler("onElementDataChange", root, checkChange)
</syntaxhighlight>
This example blocks all element data changes from clients. In MTA 1.7+ only.
<syntaxhighlight lang="lua">
function checkChange(theKey, oldValue, newValue)
if (client) then -- if there's a client variable, it means it came from a player.
cancelEvent()
end
end
addEventHandler("onElementDataChange", root, checkChange)
</syntaxhighlight>
</section>

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

Server mtaserver.conf

2025-09-13T15:33:12Z

Arran Fortuna: /* bandwidth_reduction */

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]]
:Bandwidth reduction causes de-sync when players are on mapped objects [https://github.com/multitheftauto/mtasa-blue/issues/4460 See GitHub issue]

====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. To allow a client to change a key, use setElementData(element, name, nil, true, "allow") first.
: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-09-10T08:43:57Z

Arran Fortuna:

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. To allow a client to change a key, use setElementData(element, name, nil, true, "allow") first.
: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-09-09T19:07:53Z

Arran Fortuna: Clarify how to use elementdata_whitelisted

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. To allow a client to change a key, use setElementData(element, name, nil, false, "allow") first.
: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]]

HasObjectPermissionTo

2025-08-25T08:22:58Z

Arran Fortuna: Added note about defaultPermission defaulting to false in 1.7

__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 naïve 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|
'''In 1.7.0 defaultPermission will now default to false. May affect the normal operation of existing scripts.'''
}}
<syntaxhighlight lang="lua">
bool hasObjectPermissionTo ( string / element theObject, string theAction [, bool defaultPermission = true ] )
</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]]

SetElementData

2025-08-19T18:10:10Z

Arran Fortuna:

{{Server client function}}
__NOTOC__
This function stores [[element data]] under a certain key, attached to an element. Element data set using this is then synced with all clients and the server. The data can contain server-created elements, but you should avoid passing data that is not able to be synced such as xmlnodes, acls, aclgroups etc.

As element data is synced to all clients, it can generate a lot of network traffic and be heavy on performance. Events are much more efficient for sending data from a client to the server only, or from the server to a specific client. 
Usage of element data should be discouraged where your goal can be achieved with events like above, and [[table|tables]] for storing and retrieving data.
{{Tip|A simple and efficient way to make a variable known to the server and clients is to use setElementData on the [[root]] element.}}
{{Note|See [[Script security]] for tips on preventing cheaters when using events and element data.}}
{{Note|For performance reasons, never use setElementData in events that fire often (like [[onClientRender]]) without further optimization or conditions. In fact, using element data in general, can take such a toll on performance that not using it unless strictly necessary (e.g use alternatives such as storing data in tables) is recommended.}}

{{New items|3.0158|1.5.7|A subscription mode has been introduced for [[setElementData]] serverside. When setting data in subscription mode, only clients that are added through [[addElementDataSubscriber]] will receive the data, which is good for performance.
Note this mode only works when setting element data serverside. Setting data clientside still sends the update to all clients if 'synchronize' is set to true.
|20477}}

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool setElementData ( element theElement, string key, var value [, string syncMode = "broadcast", string clientChangesPolicy = "default" ] )
</syntaxhighlight>
{{OOP||[[element]]:setData||getElementData}}

===Required Arguments===
*'''theElement:''' The [[element]] you wish to attach the data to.
*'''key:''' The key you wish to store the data under. (Maximum 128 characters.)
*'''value:''' The value you wish to store. See [[element data]] for a list of acceptable datatypes.

===Optional Arguments===
{{New items|3.0158|1.5.7|
*'''syncMode:''' Synchronization mode.
**''"broadcast"'' - Synchronize to all clients (default behavior). You can also parse ''true'' for this option.
**''"local"'' - Don't synchronize. You can also parse ''false'' for this option.
**''"subscribe"'' - Only synchronize to specific clients. See [[addElementDataSubscriber]] and [[removeElementDataSubscriber]].
|20477}}
{{New items|3.0161|1.6.0|
*'''clientChangesPolicy:''' Client changes policy.
**''"default"'' - Use '''elementdata_whitelisted''' setting from [https://wiki.multitheftauto.com/wiki/Server_mtaserver.conf#elementdata_whitelisted mtaserver.conf]
**''"allow"'' - Trust changes from clients.
**''"deny"'' - Deny client changes. The server will trigger the [[onPlayerChangesProtectedData]] event when the client attempts to change the value.
{{Note|Linux server users [https://github.com/multitheftauto/mtasa-blue/issues/4109 have reported crashes] when using the clientChangesPolicy argument.}}
|22815}}
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool setElementData ( element theElement, string key, var value [, bool synchronize = true ] )
</syntaxhighlight>
{{OOP||[[element]]:setData||getElementData}}

===Required Arguments===
*'''theElement:''' The [[element]] you wish to attach the data to.
*'''key:''' The key you wish to store the data under. (Maximum 128 characters.)
*'''value:''' The value you wish to store. See [[element data]] for a list of acceptable datatypes.

===Optional Arguments===
*'''synchronize:''' Determines whether or not the data will be synchronized with the server.
</section>

===Returns===
Returns ''true'' if the data was set successfully, ''false'' otherwise.

==Example==
Example 1
<section name="Server" class="server" show="true">
This example allows a player to add a custom tag onto their nickname, and also reverts it back to normal if they wish.
<syntaxhighlight lang="lua">
function addPlayerCustomTag ( thePlayer, command, newTag )
--Let's make sure the newTag param has been entered...
if ( newTag ) then
--Grab their current playername for saving.
local sPlayerNickname = getPlayerName ( thePlayer )
--Create their new nickname with their tag
local sNewPlayerNickname = newTag .. " " .. sPlayerNickname

--Let's first load the element data, see if it's there already
--The reason for this is that if a player were to do /addtag twice,
--the tag would be prepended a second time
local sOldNick = getElementData( thePlayer, "tempdata.originalnick" )
if ( sOldNick == false ) then
--Save their orignal nickname in their element data
setElementData ( thePlayer, "tempdata.originalnick", sPlayerNickname )
end

--Set their new nickname globally
setPlayerName ( thePlayer, sNewPlayerNickname )

--Tell them it's done
outputChatBox ( "Your new nickname has been set, to put it back to its original state you can use /deltag", thePlayer )
else
--The newTag param was not entered, give an error message
outputChatBox ( "/addtag - Incorrect syntax, Correct: /addtag <newtag>", thePlayer )
end
end
addCommandHandler ( "addtag", addPlayerCustomTag )

function removePlayerCustomTag ( thePlayer, command )
--We first need to check that they have already used /addtag, let's do that now
local sOldNick = getElementData( thePlayer, "tempdata.originalnick" )
if ( sOldNick ) then
--Great, they have a tag added, let's reset them

--First we will want to reset the element data back to its default (that being false)
setElementData ( thePlayer, "tempdata.originalnick", false )

--Now set the client name back
setPlayerName( thePlayer, sOldNick )

--Notify them
outputChatBox ( "Your old nickname has been set", thePlayer )
end
end
addCommandHandler ( "deltag", removePlayerCustomTag )
</syntaxhighlight>
</section>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.6.0-9.22815|Added clientChangesPolicy argument}}

==See Also==
{{Element_functions}}

[[pt-br:SetElementData]]
[[tr:setElementData]]

OnPlayerWeaponFire

2025-08-19T14:29:15Z

Arran Fortuna:

{{Server event}}
__NOTOC__
{{New feature/item|3.0153|1.5.3|9921|
This event is called when a player fires a weapon. This does not trigger for projectiles, melee weapons, or camera.
}}
{{Note|
*This event works only with weapons which have enabled bullet sync. See [[Weapons]] for more information.
*Start and end coordinates will be near the center of the map if a player fires a single handed weapon while looking behind them (when the gun is pointed at the sky)
}}
==Parameters==
<syntaxhighlight lang="lua">
int weaponID, float endX, float endY, float endZ, element hitElement, float startX, float startY, float startZ
</syntaxhighlight>
*'''weaponID''': an [[int]] representing [[weapons|weapon]] used for making a shot.
*'''endX''': [[float]] world X coordinate representing the end point.
*'''endY''': [[float]] world Y coordinate representing the end point.
*'''endZ''': [[float]] world Z coordinate representing the end point.
*'''hitElement''': an [[element]] which was hit by a shot. Currently this can be only another [[player]]. '''Note: hitElement could be incorrect and should not be relied upon.'''
*'''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 [[player]] who fired the weapon.

==Example==
This code creates explosions when the source players shoots.
<syntaxhighlight lang="lua">
addEventHandler ("onPlayerWeaponFire", root,
function (weapon, endX, endY, endZ, hitElement, startX, startY, startZ)
createExplosion(endX, endY, endZ, 2, source);
end
)
</syntaxhighlight>

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

DbQuery

2025-08-10T20:38:19Z

Arran Fortuna: /* Optional Arguments */

__NOTOC__
{{Server function}}
This function starts a database query using the supplied connection. Use the returned query handle with [[dbPoll]] to get the result, or [[dbFree]] if you don't want the result.
{{Tip|The server command [[Server_Commands#debugdb|debugdb 2]] will output verbose information on each query to a logging file (usually '''logs/db.log''')}}
{{Important Note|It is strongly recommended to use this function asynchronously, as presented in "This example starts a select query and processes the result in an inline callback function with custom arguments:"}}
==Syntax==
<syntaxhighlight lang="lua">
handle dbQuery ( [ function callbackFunction, [ table callbackArguments, ] ] element databaseConnection, string query [, var param1 [, var param2 ...]] )
</syntaxhighlight>
{{OOP||[[connection]]:query}}
===Required Arguments===
*'''databaseConnection:''' A database connection element previously returned from [[dbConnect]]
*'''query:''' An SQL query. Positions where parameter values will be inserted are marked with a '''?'''

===Optional Arguments===
*'''callbackFunction:''' An optional function to be called when a result is ready. The function will only be called if the result has not already been read with [[dbPoll]]. The function is called with the query handle as the first argument.
*'''callbackArguments:''' An optional table containing extra arguments (excluding functions) to be sent to the callback function.
*'''paramX:''' A variable number of parameters. These must be strings or numbers - it is important to make sure they are of the correct type. Also, the number of parameters passed must be equal to the number of '''?''' characters in the query string.
String parameters are automatically quoted and escaped as required. (If you do not want a string quoted, use '''??''')

===Returns===
Returns a query handle unless the connection is incorrect, in which case it return ''false''.

==Example==
This example starts an INSERT query and frees the result:
<syntaxhighlight lang="lua">
local qh = dbQuery( connection, "INSERT INTO table_name VALUES (?,?,?)", "aaa", "bbb", 10 )
dbFree( qh )
</syntaxhighlight>

This example starts a select query and waits for the result: (server freeze included)
<syntaxhighlight lang="lua">
local qh = dbQuery( connection, "SELECT * FROM table_name" )
local result = dbPoll( qh, -1 )
</syntaxhighlight>

This example starts a select query and processes the result in a callback function:
<syntaxhighlight lang="lua">
function aaa()
dbQuery( myCallback, connection, "SELECT * FROM table_name" )
end

function myCallback(qh)
local result = dbPoll( qh, 0 ) -- Timeout doesn't matter here because the result will always be ready
end
</syntaxhighlight>

This example starts a select query and processes the result in an inline callback function with custom arguments:
<syntaxhighlight lang="lua">
dbQuery( function(qh, tag, score)
local result = dbPoll( qh, 0 ) -- Timeout doesn't matter here because the result will always be ready
outputDebugString( tag ) -- Prints "hello"
outputDebugString( score ) -- Prints 2000
end
,{"hello",2000}, connection, "SELECT * FROM table_name" )
</syntaxhighlight>

'''''Note''': It is usually good practice to surround table and column names with backticks (`) in case they contain spaces or SQL keywords (and therefore cause syntax errors). This is especially true when using variables for table and column names, as potential problems may not be apparent when the script is first written.'' 

This example shows how to use backticks and '''??''' for parts of the query that are not column values:
<syntaxhighlight lang="lua">
dbExec( connection, "UPDATE `??` SET `??`=?", tableName, columnName, columnValue )
</syntaxhighlight>

==See Also==
{{SQL_functions}}

GetElementResourceName

2025-07-21T09:27:58Z

Arran Fortuna: Created page with "__NOTOC__ {{Useful Function}} This function returns the name of the resource that created an element. ==Syntax== <syntaxhighlight lang="lua"> string getElementResourceName ( element theElement ) </syntaxhighlight> ===Required arguments=== * '''theElement''': the element you want to get the resource name of. ==Returns== This function always returns a ''string'' containing the element's creator or a string containing information on how it failed to do so. ==Cod..."

__NOTOC__
{{Useful Function}}
This function returns the name of the resource that created an element.

==Syntax==
<syntaxhighlight lang="lua">
string getElementResourceName ( element theElement )
</syntaxhighlight>

===Required arguments===
* '''theElement''': the [[element]] you want to get the resource name of.

==Returns==
This function always returns a ''string'' containing the [[element]]'s creator or a string containing information on how it failed to do so.

==Code==
<section name="Function source" class="both" show="true">
<syntaxhighlight lang="lua">
function getElementResourceName(element)
if not isElement(element) then
return "Invalid element"
end

local maxHops = 50
local path = getElementType(element)
local chain = { element }

-- Build parent chain
local current = element
while current and maxHops > 0 do
current = getElementParent(current)
if current then
table.insert(chain, current)
path = path .. " -> " .. getElementType(current)
end
maxHops = maxHops - 1
end

-- Try to match one of the parents to a resource root
for _, res in ipairs(getResources()) do
local resRoot = getResourceRootElement(res)
for _, ancestor in ipairs(chain) do
if ancestor == resRoot then
return getResourceName(res)
end
end
end

return "No matching resource found (path: " .. path .. ")"
end

</syntaxhighlight>
</section>

==See also==
{{Useful_Functions}}

Template:Useful Functions

2025-07-21T09:25:10Z

Arran Fortuna: /* Element functions */

__NOTOC__
=== Table functions ===
*[[addTableChangeHandler]] » This function monitors the changes of a table.
*[[pairsByKeys]] » This function sort pairs table.
*[[rangeToTable]] » This function converts a string range to a table containing number values.
*[[setTableProtected]] » This function protects a table and makes it read-only.
*[[setTableToSql]] » This function is used to save the table in the database (sql).
*[[Sort_Functions]] » These functions are able to sort your tables by a key.
*[[getKeyFromValueInTable]] » This function returns the key of the specified value in a table.
*[[getTableFromSql]] » This functionality is used to obtain saved tables using the function ([https://wiki.multitheftauto.com/wiki/SetTableToSql SetTableToSql ]).
*[[isValueInTable]] » This function returns true if the value exists in the table, false if the value does not exist in the table.
*[[table.compare]] » This function checks whether two given tables are equal.
*[[table.copy]] » This function copies a whole table and all the tables in that table.
*[[table.deepmerge]] » This function deep merges two tables. Every nested table will be correspondingly merged.
*[[table.element]] » This function returns a new table with only userdata content.
*[[table.flip]] » This function returns the table from the last value to the first value, such as reflection.
*[[table.getRandomRows]] » This function returns random rows from table.
*[[table.map]] » This function goes through a table and replaces every field with the return of the passed function, where the field's value is passed as first argument and optionally more arguments.
*[[table.merge]] » This function merges two or more tables together.
*[[table.random]] » This function retrieves a random value from a table.
*[[table.removeValue]] » This function removes a specified value from a table.
*[[table.size]] » This function returns the absolute size of a table.

=== ACL functions ===
*[[aclGroupClone]] » This function clone a group to another group with/without ACLs and/or objects.
*[[renameAclGroup]] » This function gives an existing ACL group a new name.
*[[getPlayersInACLGroup]] » This function returns all players in an ACL group.
*[[isPlayerInACL]] » This function checks if a player element is in an ACL group.

=== Account functions ===
*[[getPlayerFromAccountName]] » This function is used to obtain a player by the name of his account.
*[[isPlayerAccount]] » This function checks if the account is a valid player account (account exists and is not a guest account)

=== Camera functions ===
*[[smoothMoveCamera]] » This function allows you to create a cinematic camera flight.
*[[sCamera]] » The function creates a speed camera in-game, fines speeding vehicles, and notifies the driver and take money from player based on vehicle speed.

=== Colshape functions ===
*[[createGarageColShape]] » This function creates a collision shape from the specified garage.

=== Cursor functions ===
*[[getCursorMovedOn]] » This function checks in which way the cursor is currently moving.
*[[setCursorCenteredOnRectangle]] » This functions will center the cursor inside a rectangle.

=== Drawing functions ===
*[[dxDrawAnimWindow]] » This function draws an animated 2D window on the screen.
*[[dxDrawBorderedRectangle]] » This is a function that will create a bordered rectangle.
*[[dxDrawBorderedText]] » This is a function that will create a bordered text.
*[[dxDrawDashedLine]] » This function draws a line with dashes.
*[[dxDrawEditbox]] » This function draws a edit box across the screen - rendered for one frame. This should be used in conjunction with '''onClientRender''' in order to display continuously.
*[[dxDrawGifImage]] » This function simulates the effect of a GIF image by using image sprites in 2D.
*[[dxDrawImage3D]] » This function draws a 3D image in GTA world.
*[[dxDrawImageOnElement]] » This function draws an image on any element.
*[[dxDrawLinedRectangle]] » This is a function that will create a rectangle outline with dx lines.
*[[dxDrawLoading]] » This function draws a loading bar on the screen.
*[[dxDrawOctagon3D]] » This function creates a 3D Octagon
*[[dxDrawPolygon]] » This function draws a custom polygon on the screen.
*[[dxDrawProgressBar]] » This function simulates a progress bar drawed using DirectDraw.
*[[dxDrawRectangle3D]] » This function draws a 3D rectangle in GTA world.
*[[dxDrawRectangleOnPlayer]] » This function draws a 3D rectangle above the player.
*[[dxDrawRing]] » This function draws a ring with dx lines.
*[[dxDrawRombo]] » This function creates a Rhombus.
*[[dxDrawSprite]] » This function draw a sprite in the 3D world.
*[[dxDrawTextOnElement]] » This function draws a text on any element.
*[[dxDrawTextOnRectangle]] » Esta funcion crea un rectangle con un texto dentro.
*[[dxDrawTriangle]] » This is a function that will create a triangle with dx lines.
*[[dxDrawBordered3DLine]] »This function creates a bordered area with 3D dx lines.
*[[dxFade]] » This function fade-in or fade-out any dxDraw by gradually changing its alpha value.
*[[dxGetFontSizeFromHeight]] » This function calculates the font size from given height.
*[[dxGetRealFontHeight]] » This function calculates the height of a font.
*[[wordWrap]] » This function breaks a long string into a table of separate lines limited to a specific length in pixels, for drawing separately.
*[[CreateRectangle3D]] » This is a function that will create a 3d rectangle on the player screen.
*[[getScreenStartPositionFromBox]] » This function helps with getting the correct position for your dx-effects.

=== Effects functions ===
*[[attachEffect]] » This function allows you attach an effect to an element.
*[[setScreenFlash]] » This function will make the screen flash(like a screenshot).

=== Element functions ===
*[[autoAttach]] » This function attaches one element into another at the same position and rotation they are.
*[[attachElementToBone]] » This function allows you to attach an element to ped bone accurately using new bone functions.
*[[getElementDirectionCardialPoint]] » This function returns the direction of the element according to the ''wind rose''.
*[[getElementSpeed]] » This function returns the specified element's speed in m/s, km/h or mph.
*[[getElementUsingData]] » This function returns table elements that contains the elements data with the given key and value.
*[[getElementZoneFullName]] » This function allows you to retrieve the zone full name of a element.
*[[getElementsInDimension]] » This function returns a table of elements that are in the specified dimension.
*[[getElementsWithinMarker]] » This function returns a table of elements that are within a marker's collision shape.
*[[getNearestElement]] » This function returns the nearest element (of a specific type) to a player.
*[[getPositionInFrontOfElement]] » This function returns position in provided distance away from element, including element's rotation.
*[[isElementInAir]] » This function checks if an element is in air or not.
*[[isElementInPhotograph]] » This function checks if an element is in the player's camera picture area.
*[[isElementInRange]] » This function allows you to check if an element's range to a main point is within the maximum range.
*[[isElementMoving]] » This function checks if an element is moving.
*[[isElementPlayer]] » This function checks whether the element is a player or not.
*[[isElementWithinAColShape]] » This function checks if an element is within a collision shape element.
*[[multi_check]] » This function checks one element to many, handy and clean.
*[[setElementSpeed]] » This function allows you to set the speed of an element in kph or mph units.
*[[getElementResourceName]] » This function returns the name of the resource that created an element.

=== Events ===
*[[onClientPlayerTimeChange]] » This code implements an event that is triggered when the player's real time change.
*[[onPlayerZoneChange]] » This code implements an event that is triggered when the player enters a new area on the map.
*[[onVehicleWeaponFire]] » This code implements an event that is triggered when a player in a vehicle fires a vehicle's weapon.

=== Input functions ===
*[[bindControlKeys]] » This function allows you to bind each key bound to a control individually. Doing this bypasses a little MTA restriction.
*[[unbindControlKeys]] » This function allows you to unbind each key bound to a control individually. Use this function with [[bindControlKeys]].
*[[getBoundControls]] » This function returns a table of control names that are bound to the specified key.
*[[isCommandHandlerAdded]] » This function allows you to check if a command is added or not in the respective resource.

=== Data functions ===
*[[levenshtein]] » This function can be used to calculate the Levenshtein distance between two strings.
*[[gregorianToJalali]] » This function converts gregorian date to jalali/shamsi date.
*[[byte2human]] » This function converts an integer (number of bytes) into a human-readable unit.
*[[capitalize]] » This function capitalizes a given string.
*[[convertDate]] » This function converts date to another look.
*[[convertServerTickToTimeStamp]] » This function converts server ticks to a unix timestamp.
*[[convertTextToSpeech]] » This function converts the provided text to a speech in the provided language which players can hear.
*[[findRotation3D]] » This function takes two sets of XYZ coordinates. It returns the 3D direction from point A to point B.
*[[findRotation]] » This function takes two points and returns the direction from point A to point B.
*[[formatDate]] » This function formats a date on the basis of a format string and returns it.
*[[formatNumber]] » This function formats large numbers by adding commas.
*[[generateRandomASCIIString]] » This function returns a random string which uses ASCII characters. 
*[[generateString]] » This function generates a random string with any characters.
*[[getAge]] » This function calculates the age of a given birthday.
*[[getDistanceBetweenElements]] » Returns the distance between two elements.
*[[getDistanceBetweenPointAndSegment2D]] » This function takes point coordinates and line (a segment) starting and ending coordinates. It returns the shortest distance between the point and the line.
*[[getEasterDate]] » This function returns easter date monthday and month for a given year.
*[[getElementRelatedAngle]] » This function returns the related angle between one element to another. This is useful to check which side an element is to another.
*[[getFreeDimension]] » This function get free dimension.
*[[getOffsetFromXYZ]] » This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.
*[[getPointFromDistanceRotation]] » This function finds a point based on a starting point, direction and distance.
*[[getRealMonth]] » This function returns the current month name
*[[getRGColorFromPercentage]] »This function returns two integers representing red and green colors according to the specified percentage.
*[[getScreenRotationFromWorldPosition]] » This function returns a screen relative rotation to a world position.
*[[getTimestamp]] » This function returns the UNIX timestamp of a specified date and time.
*[[gradientString]] » This function transforms a string in a new coloured gradient string.
*[[hex2rgb]] » This function convert hex to rgb.
*[[hexColorToRGB]] » This function convert hex string/number to RGBA values.
*[[isLeapYear]] » This function returns a boolean representing if a given year is a leap year.
*[[isValidMail]] » This function checks whether a provided e-mail string is valid.
*[[removeHex]] » This function is used to remove hexadecimal numbers (colors, for example) from strings.
*[[RGBToHex]] » This function returns a string representing the color in hexadecimal.
*[[RGBToHSV]] » This function convert RGB to HSV color space.
*[[RGBToDecimal]] » This function convert RGB to Decimal color.
*[[secondsToTimeDesc]] » This function converts a plain seconds-integer into a user-friendly time description.
*[[string.count]] » This function counts the amount of occurences of a string in a string.
*[[string.explode]] » This function splits a string at a given separator pattern and returns a table with the pieces.
*[[string.insert]] » This function inserts a string within another string at a given position.
*[[splitMultiple]] » This function improves the split function so that multiple characters can be used as the split at character.
*[[switch]] » This function allows the value of a variable or expression to control the flow of program execution via a multiway branch.
*[[tocolor2rgba]] » This function convert tocolor to rgba.
*[[toHex]] » This function converts a decimal number to a hexadecimal number, as a fix to be used client-side.
*[[var dump]] » This function outputs information about one or more variables using outputConsole.
*[[wavelengthToRGBA]] » This function converts a physical wavelength of light to a RGBA color.
*[[fixPersianString]] » This function returns a fixed sorted bilingual RTL for strings consisting of Farsi/Arabic and English.

=== GUI functions ===
*[[centerWindow]] » This function centers a CEGUI window element responsively in any resolution.
*[[isMouseOnGUICloseButton]] » This function allows you to check whether the mouse cursor/pointer is within a gui-window's native close button.
*[[isMouseOnGuiElement]] » This function allows you to check whether or not your mouse is over a specific gui element, this is especially useful if the gui element has a parent. 
*[[guiMoveElement]] » This function moves guiElement by/like using moveObject.
*[[guiSetStaticImageMovable]] » This function allows you to move a static image like a gui window.
=====Comboboxes=====
*[[guiComboBoxAdjustHeight]] » This function adjusts a CEGUI combobox element to have the correct height.

=====Gridlists=====
*[[convertGridListToText]] » This function converts grid list contents to text.
*[[getGridListRowIndexFromText]] » This function returns the GridList row index from the specified text.
*[[guiGridListAddPlayers]] » This function add all online players to a grid list.
*[[isTextInGridList]] » This function checks if some text exist or not in the GridList.
*[[guiGridListGetColumnIDFromTitle]] » This function gets a gridlist's column ID from the column title.
*[[guiGridListGetSelectedText]] » This function returns a string containing the inner text of a selected gridlist item.
*[[guiGridListSetColumnNonSortable]] » This function makes a gridlist column become non-sortable.

=====Labels=====
*[[guiLabelAddEffect]] » This function add an effects to the gui-label like (shadow, outline).

=== Marker functions ===
*[[createMarkerAttachedTo]] » This function creates a marker that is attached to an element.

=== Math functions ===
*[[reMap]] » Re-maps a number from one range to another.
*[[math.clamp]] » This function returns the number between range of numbers or it's minimum or maximum.
*[[math.getBezierPoint]] » Get N-th order bezier point.
*[[math.hypot]] » This function returns the Hypotenuse of the triangle given by sides x and y.
*[[math.isPointInPolygon]] » Check if point is inside polygon or not.
*[[math.lerp]] » Get val between two integer.
*[[math.percent]] » This function returns a percentage from two number values.
*[[math.polygonArea]] » Compute area of any polygon.
*[[math.randomDiff]] » Generates a pseudo-random integer that's always different from the last random number generated.
*[[math.rotVecToEulerAngle]] » Rotation Vector To Euler Angle
*[[math.round]] » Rounds a number whereas the number of decimals to keep and the method may be set.
*[[mathNumber]] » This function is a workaround for the client-side floating-point precision of 24-bits.
*[[Math.percentProgress|math.percentProgress]] » Returns a percentage progress from two specific values.
*[[math.average]] » This function returns the simple arithmetic mean of multiple numbers.
*[[math.absin]] » This function returns a formula representing the just positive half of a sine wave.

=== Map functions ===
*[[assignLod]] » This function lets you conveniently generate and apply a LOD model to a mapping object.
*[[getWorldPositionFromMapPosition]] » This function converts an F11 map position to world position.

=== Ped functions ===
*[[getAlivePlayersInTeam]] » This function returns a table of the alive players in a team.
*[[getGuestPlayers]] » This function gets a players not login or players Guest .
*[[getOnlineAdmins]] » This function returns a table of all logged-in administrators.
*[[getPedEyesPosition]] » This function allows you to get peds eyes position.
*[[getPedGender]] » This function allows you to get peds their gender.
*[[getPedMaxHealth]] » This function returns a pedestrians's maximum health by converting it from their maximum health stat.
*[[getPedMaxOxygenLevel]] » This function returns a ped's maximum oxygen level by converting it from their maximum underwater stamina stat.
*[[getPedWeaponSkill]] » This function returns a ped's corresponding weapon skill level name.
*[[getPedHitBone]] » This function gets the approximate number of the bone where the ped is hit.
*[[getPlayerFromNamePart]] » This function returns a player from partial name.
*[[getPlayerFromSerial]] » This function returns a player from their serial.
*[[getPlayersByData]] » This function returns a table of players that have the specified data name.
*[[getPlayersInPhotograph]] » This function returns a table of all players in photograph.
*[[getPlayersInVehicles]] » This function returns a table of the players insides vehicles from a specified dimension.
*[[getPlayerNameFromID]] » This function will get the player name from the ID element data.
*[[isPedAiming]]» This function checks if a pedestrian is aiming their weapon.
*[[isPedAimingNearPed]] » This is similar to isPedAiming but uses a colshape to be more precise.
*[[isPedDiving]] » This feature checks that pedestrian is diving in the water.
*[[isPedDrivingVehicle]] » This function checks if a specified pedestrian is driving a vehicle.
*[[isPedNearbyWall]] » This function checks if player/ped is nearby a objects like buildings or walls.
*[[isPlayerInTeam]] » This function checks if a player is in a specified team.
*[[setPedAttack]] » This function will make a ped attack a specified target.
*[[setPedFollow]] » This function will make a ped follow a specified target.
*[[isPedFalling]] » This function checks if the player/ped is falling from a high place.

=== Player functions ===
*[[countPlayersInRange]] » This function returns the number of players that are within a certain range of the specified coordinates.
*[[getPlayerPreviousAndNextWeapon]] » This function returns the player previous and next weapon.
*[[getPlayersInRange]] » This function make a table of players within certain range.
*[[isPlayerActuallyInVehicle]] » This function checks if a player is actually in a vehicle instead of just in the process of entering.
*[[isPlayerHitByVehicle]] » This function cancels event when a element is hit by a vehicle.

=== Resource functions ===
*[[getResourceScripts]] » This function returns a table of the resource scripts.
*[[getResourceSettings]] » This function returns a table of the resource settings.
*[[getResourceSize]] » This function returns the size of a specified resource in kB(kilobyte)
*[[refreshResource]] » This function refreshes your resource if you changed any of the files
*[[setResourcePriority]] » This function set resource download priority group.

=== Sound functions ===
*[[isSoundFinished]] » This function checks if a sound element has finished.
*[[stopSoundSlowly]] » This function stop your sound element slowly.

=== Browser functions ===
*[[playVideo]] » This function plays a video on the screen.

=== Team functions ===
*[[getTeamFromColor]] » This function returns a team element by the specified color.
*[[getTeamWithFewestPlayers]] » This function returns a team element with least players of all the specified teams.

=== Vehicle functions ===
*[[findEmptyCarSeat]] » This function finds you the first empty seat in a vehicle.
*[[getNearestVehicle]] » This function gets the nearest vehicle to the specified player in a specified distance.
*[[getRandomVehicle]] » This function gets a random vehicle.
*[[getValidVehicleModels]] » This function returns a table of all valid vehicle models.
*[[getVehiclesCountByType]] » This function returns the amount of vehicles by the given type as an integer value.
*[[getVehicleTurnVelocityCenterOfMass]]» This function gets a vehicle's turn velocity relative to the vehicle's center or mass.
*[[isVehicleDoubleExhaust]] » This function checks is exhaust vehicle double.
*[[isVehicleEmpty]] » This function checks whether a vehicle is empty.
*[[isVehicleOccupied]] » This function checks if a specified vehicle is occupied.
*[[isVehicleOnRoof]] » This function checks whether vehicle is on roof.
*[[isVehicleOnFire]] » This function checks if the vehicle is on fire or not.
*[[isVehicleReversing]] » This function checks if a specified vehicle is moving backwards.
*[[isVehicleUpgraded]] » This function checks is vehicle upgraded by upgrade ID.
*[[setVehicleGravityPoint]] » This function sets a vehicle's gravity in the direction of a 3 dimensional coordinate with the strength specified.
*[[setVehicleTurnVelocityCenterOfMass]] » This function sets a vehicle's turn velocity relative to the vehicle's center or mass.
*[[setVehicleHandlingFromText]] » This function sets a vehicle's handling from text.
*[[setVehicleWheelModel]] » This function changes the wheel model of the informed vehicle.

=== Weapon functions ===
*[[getJetpackWeaponsEnabled]] » This function returns a table of enabled weapons usable on a jetpack.

=== Object functions ===
*[[getDynamicDoorObjectOpenRatio]] » This function tells you how open a dynamic door is in a range from 0 to 1.
*[[isElementObject]] » This function tells you if an element is an object or no.

=== XML functions ===
*[[getXMLNodes]] » This function returns all children of a XML node.

=== Engine functions ===
*[[engineGetCOLsFromLibrary]] » This function gets the collision data from the col library.
*[[engineLoadIMGContainer]] » This function loads the IMG container.

=== Utility ===
*[[animate]] » This function allows you to use interpolateBetween without render event and easily used.
*[[callClientFunction]] » This function allows you to call any client-side function from the server's side.
*[[callServerFunction]] » This function allows you to call any server-side function from the client's side.
*[[check]] » This function checks if its arguments are of the right type and calls the error-function if one is not.
*[[checkPassiveTimer]] » This function allows you to use passive timers in your conditions. For example you want to prevent players repeatedly using a command.
*[[coroutine.resume]] » This function applies a fix for hidden coroutine error messages.
*[[compact]] » This function create table containing variables and their values.
*[[createDirectory]] » This function creates a directory in the resource's file system.
*[[getBanBySerial]] » This function returns the ban if the serial is banned.
*[[getBanFromName]] » This functions returns the ban of the given playername.
*[[getCurrentFPS]] » This function returns the frames per second at which GTA: SA is running.
*[[getSkinNameFromID]] » This function returns the name of the skin from the given id.
*[[IfElse]] » This function returns one of two values based on a boolean expression.
*[[isLastExecuteInTimer]] » This function check if the execute is the last execute in the timer.
*[[isMouseInCircle]] » This function checks if a cursor position is in circular area or not.
*[[isMouseInPosition]] » This function allows you to check whether the mouse cursor/pointer is within a rectangular position.
*[[iterElements]] » This function returns ''a time-saving'' iterator for your for-loops.
*[[PlotTrajectoryAtTime]] » Calculate projectile/water trajectory.
*[[preprocessor]] » This function allow you to use gcc macros.
*[[vector3:compare]] » This method checks whether two vectors match, with optional precision.
*[[svgCreateRoundedRectangle]] » This function creates a rectangle with rounded edges.
*[[debounce]] » This function is removing unwanted input noise.
*[[listAllFiles]] » This function lists all files and subdirectories within a given directory and its subdirectories.
*[[dumpdelete]] » This function recursively deletes elements inside a table, destroying elements like vehicles, peds, or killing timers.

===String functions===
*[[string.endsWith]] » This function checks if a string ends with other string.
*[[string.startsWith]] » This function checks if a string starts with other string.
*[[string.repetition]] » This function repeats a substring n times.
<noinclude>[[Category:Useful Functions]]</noinclude>

OnClientMinimize

2025-05-19T09:20:38Z

Arran Fortuna:

{{Client event}}
__NOTOC__
This event is triggered when the local player minimizes the game screen.
{{Note | This event only triggers from fullscreen minimize. [[onClientRestore]] can trigger even if this event didn't. [[isMTAWindowFocused]] is a more reliable way to see if a player is minimized.}}

==Parameters==
No parameters.

==Example==
This example kills any player who minimizes the game.
<syntaxhighlight lang="lua">
function handleMinimize()
setElementHealth( localPlayer, 0 )
end
addEventHandler( "onClientMinimize", root, handleMinimize )
</syntaxhighlight>

==See Also==
===Other client events===
{{Client_other_events}}
===Client event functions===
{{Client_event_functions}}

OnClientMinimize

2025-05-19T09:05:48Z

Arran Fortuna:

{{Client event}}
__NOTOC__
This event is triggered when the local player minimizes the game screen.
{{Note | This event only triggers from fullscreen minimize. [[onClientRestore]] can trigger even if this event didn't. Doesn't trigger if using borderless window. [[isMTAWindowFocused]] is a more reliable way to see if a player is minimized.}}

==Parameters==
No parameters.

==Example==
This example kills any player who minimizes the game.
<syntaxhighlight lang="lua">
function handleMinimize()
setElementHealth( localPlayer, 0 )
end
addEventHandler( "onClientMinimize", root, handleMinimize )
</syntaxhighlight>

==See Also==
===Other client events===
{{Client_other_events}}
===Client event functions===
{{Client_event_functions}}

OnClientMinimize

2025-05-19T09:01:15Z

Arran Fortuna:

{{Client event}}
__NOTOC__
This event is triggered when the local player minimizes the game screen.
{{Note | This event only triggers from fullscreen minimize. [[onClientRestore]] can trigger even if this event didn't. Doesn't trigger if using borderless window.}}

==Parameters==
No parameters.

==Example==
This example kills any player who minimizes the game.
<syntaxhighlight lang="lua">
function handleMinimize()
setElementHealth( localPlayer, 0 )
end
addEventHandler( "onClientMinimize", root, handleMinimize )
</syntaxhighlight>

==See Also==
===Other client events===
{{Client_other_events}}
===Client event functions===
{{Client_event_functions}}

Scripting Tips

2025-04-26T08:03:01Z

Arran Fortuna: /* Server Performance */

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.
* It's much more efficient to [[SetElementHealth]] [[setElementRotation]] [[setPedArmor]] on a player client side (doing it server side sends an RPC to all players) consider a client event all your server scripts can call to set a players stat on their client and their client will then update the server via puresync and that change is then relayed to clients via the next puresync or lightsync packet. Note that doing this for position client isn't advised as the refresh rate for lightsync is low so would take a few seconds for remote players in another part of the map to see the player's new position.

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

Scripting Tips

2025-04-26T07:59:21Z

Arran Fortuna: Re-added something Srslyyyy removed as it is not "misleading information"

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.
* It's much more efficient to [[SetElementHealth]] and [[setElementRotation]] on a player client side (doing it server side sends an RPC to all players) consider a client event all your server scripts can call to set a players health on their client and their client will then update the server via puresync and that change is then relayed to clients via the next puresync or lightsync packet.

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

GetElementsByType

2024-05-30T16:16:49Z

Arran Fortuna: Added gui-window

{{Server_client_function}}
__NOTOC__
This function is used to retrieve a list of all elements of the specified type. This can be useful, as it disregards ''where'' in the element tree it is. It can be used with either the built in types (listed below) or with any custom type used in a .map file. For example, if there is an element of type "flag" (e.g. <flag />) in the .map file, the using "flag" as the type argument would find it.

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
table getElementsByType ( string theType, [ element startat=getRootElement() ] )
</syntaxhighlight>
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
table getElementsByType ( string theType, [ element startat=getRootElement(), bool streamedIn=false ] )
</syntaxhighlight>
</section>

{{OOP|This function is a static function underneath the Element class.|[[Element]].getAllByType||}}

===Required Arguments===
*'''theType:''' The type of element you want a list of. This is the same as the tag name in the .map file, so this can be used with a custom element type if desired. Built in types can be found here: [[Element]]
**'''"player":''' A player connected to the server
**'''"ped":''' A ped
**'''"water":''' A water polygon
**'''"sound":''' A playing sound
**'''"vehicle":''' A vehicle
**'''"object":''' An object
**'''"pickup":''' A pickup
**'''"marker":''' A marker
**'''"colshape":''' A collision shape
**'''"blip":''' A blip
**'''"radararea":''' A radar area
**'''"team":''' A team
**'''"spawnpoint":''' A spawnpoint
**'''"console":''' The server Console
**'''"projectile":''' A clientside projectile
**'''"effect":''' A clientside effect
**'''"light":''' A clientside light
**'''"searchlight":''' A clientside searchlight
**'''"shader":''' A shader
**'''"texture":''' A texture
**'''"gui-window":''' A GUI window (there's others like this for other GUI types)

==Optional Arguments==
{{OptionalArg}}
*'''startat:''' The [[element]] the search should start at. Children of this element are searched, siblings or parents will not be found. By default, this is the root element which should suit most uses.

<section name="Client" class="client" show="true">
*'''streamedIn:''' If true, function will only return elements that are streamed in.
</section>

===Returns===
Returns a ''table'' containing all the elements of the specified type. Returns an empty ''table'' if there are no elements of the specified type. Returns ''false'' if the string specified is invalid (or not a string).

==Example==
'''Example 1:''' This example retrieves a table of the players in the server, and checks whether or not each one is in a vehicle:
<syntaxhighlight lang="lua">
local players = getElementsByType ( "player" ) -- get a table of all the players in the server
for theKey,thePlayer in ipairs(players) do -- use a generic for loop to step through each player
if ( isPlayerInVehicle ( thePlayer ) ) then -- if the player is in a vehicle, announce it
outputChatBox ( getPlayerName ( thePlayer ) .. " is in a vehicle" )
else -- if the player isn't in a vehicle, announce that he/she is on foot
outputChatBox ( getPlayerName ( thePlayer ) .. " is on foot" )
end
end
</syntaxhighlight>

'''Example 2:''' This example retrieves a table of the teams in the server, and display them in chat:
<syntaxhighlight lang="lua">
local teams = getElementsByType("team")
for i,team in ipairs(teams) do
local teamName = getTeamName(team) -- get the team name
outputChatBox(teamName) -- display the team name in chat
end
</syntaxhighlight>

'''Example 3:''' This shows how you could create a new element to describe a gas station:
<syntaxhighlight lang="lua">
function createGasStations(below)
local gasstations = getElementsByType ( "gasstation", below ) -- get a table of all the gas station elements in the element tree
for theKey,theGasStation in ipairs(gasstations) do
local x = getElementData(theGasStation, "posX") -- get the position of the element
local y = getElementData(theGasStation, "posY")
local z = getElementData(theGasStation, "posZ")
setElementParent(createColSphere(x, y, z, 10), theGasStation) -- create a colshape for the gas station at the gas station's position
addEventHandler("onColShapeHit", theGasStation, giveGas) -- when the player hits
end
end

function mapLoad()
createGasStations(source) -- create gas stations for the map that's just loaded
end
addEventHandler("onResourceStart", resourceRoot, mapLoad)

function giveGas(hittingElement)
local theGasStation = source
if getElementType(hittingElement) == "vehicle" then
local gas_left = getElementData(theGasStation, "amount")
local gas_speed = getElementData(theGasStation, "speed")
if gas_left > 0 then

local gas_to_remove = gas_speed
if gas_left < gas_speed then
gas_to_remove = gas_left

local current_vehicle_gas = getElementData(hittingElement, "gas")
current_vehicle_gas = current_vehicle_gas + gas_to_remove
gas_left = gas_left - gas_to_remove

setElementData(hittingElement, "gas", current_vehicle_gas)
setElementData(theGasStation, "amount", gas_left)
else
outputChatBox("Pump is out of gas!")
end
end
end
</syntaxhighlight>

'''Example 4:''' This example loops trough all connected players and redirects them to another server host:
<syntaxhighlight lang="lua">
local serverIP = "99.88.77.66" -- Change to your server IP to redirect everyone
local serverPort = 22005 -- The destination server's port

function redirectAllPlayers()
for _,p in ipairs (getElementsByType("player")) do
if p then
redirectPlayer (p, serverIP, serverPort)
end
end
end
addEventHandler ("onResourceStart", resourceRoot, redirectAllPlayers)
</syntaxhighlight>

==See Also==
{{Element_functions}}

OnPlayerScreenShot

2024-01-04T22:23:06Z

Arran Fortuna:

__NOTOC__
{{Server event}}
This event is triggered when the screen capture requested by [[takePlayerScreenShot]] has completed.

==Parameters==
<syntaxhighlight lang="lua">
resource theResource, string status, string imageData, int timestamp, string tag
</syntaxhighlight>

*'''theResource''': the [[resource]] which called [[takePlayerScreenShot]].
*'''status''': a [[string]] containing the status of the event which can be one of these values:
**''"ok"'' - the image capture was successful and imageData will contain a JPEG image.
**''"disabled"'' - the image capture failed because the player has disabled screen uploads.
**''"minimized"'' - the image capture failed because the player has minimized the screen (i.e. alt-tabbed).
**''"error"'' - the image capture failed because of an unspecified error.
*'''imageData''': a [[string]] which contains the JPEG image data. This can be saved with the [[Server_Scripting_Functions#File_functions|file functions]], or sent to players with [[triggerClientEvent]] or even uploaded to a web site.
*'''timestamp''': an [[int]] representing the server tick count when the capture was taken.
*'''tag''': a [[string]] passed to [[takePlayerScreenShot]].

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

==Example==
This example captures the screen of a random player every 2 seconds and shows it to everyone:

<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
--------------------------------------------------
-- Take screen shot every 2 seconds
function doTakeScreenShot()
takePlayerScreenShot( getRandomPlayer(), 320, 200 )
end
setTimer(doTakeScreenShot, 2000, 0)

--------------------------------------------------
-- Receive screen shot result
addEventHandler( "onPlayerScreenShot", root,
function ( theResource, status, pixels, timestamp, tag )
triggerClientEvent( root, "onMyClientScreenShot", resourceRoot, pixels ) -- Relay to all players
end
)
</syntaxhighlight>
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
--------------------------------------------------
-- Turn image data into a texture at the client
addEvent("onMyClientScreenShot",true)
addEventHandler( "onMyClientScreenShot", resourceRoot,
function( pixels )
if image then
destroyElement(image)
end
image = dxCreateTexture( pixels )
end
)

--------------------------------------------------
-- Show image
addEventHandler( "onClientRender", root,
function()
if image then
dxDrawImage( 100, 250, 320, 200, image )
end
end
)
</syntaxhighlight>
</section>

==Requirements==
{{Requirements|1.3|n/a|}}

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

Split

2023-11-15T16:59:40Z

Arran Fortuna: Added splitMultiple info to split

__NOTOC__
{{Server client function}}
This function splits a string into substrings. You specify a character that will act as a separating character; this will determine where to split the sub-strings. For example, it can split the string "Hello World" into two strings containing the two words, by spliting using a space as a separator.

'''Note:''' You can use the function [[gettok]] to retrieve a single token from the string at a specific index. This may be faster for one-off lookups, but considerably slower if you are going to check each token in a long string.

==Syntax==
<syntaxhighlight lang="lua">table split ( string stringToSplit, string / int separatingChar )</syntaxhighlight>

===Required Arguments===
* '''stringToSplit''' The string you wish to split into parts.
* '''separatingChar''' A string of the character you want to split, or the [[ASCII|ASCII number]] representing the character you want to use to split. If you want to split a string at multiple characters see [[splitMultiple]]

===Returns===
Returns a ''table'' of substrings split from the original string if successful, ''false'' otherwise.

{{note|Unicode characters work but when combined with others do not. E.g: #split("a€cb†", "€") returns 3 but #split("a€cb", "€") returns 2.
}}

{{note|You can't use same char twice as a separator. Eg.: ||, ||| are the same as |.
}}

==Example==
<section name="Server" class="server" show="true">
This example gives the specified weapons to the given player, while the weapons are a string in the form: 'weaponId,ammo;weaponId2,ammo2;weaponId3,ammo3;..'. This is especially for data read from a .map file attribute.
<syntaxhighlight lang="lua">
function giveWeapons(player, weaponsString)
local weaponsTable = split(weaponsString, ';') --split the string by the semi colon
for k,v in ipairs(weaponsTable) do --for all the split values do
weaponId = gettok(v, 1, string.byte(',')) --get the weapon ID using gettok, retrieve the first token
weaponAmmo = gettok(v, 2, ",") --get the ammo using gettok, retrieve the second token
if (weaponId and weaponAmmo) then --if neither of them is invalid
giveWeapon(player, weaponId, weaponAmmo) --give the player the weapons
end
end
end
</syntaxhighlight>
</section>

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

Template:Useful Functions

2023-11-15T16:58:09Z

Arran Fortuna: Added splitMultiple

__NOTOC__
=== Table functions ===
*[[addTableChangeHandler]] » This function monitors the changes of a table.
*[[getTableFromSql]] » This functionality is used to obtain saved tables using the function ([https://wiki.multitheftauto.com/wiki/SetTableToSql SetTableToSql ]).
*[[isValueInTable]] » This function returns true if the value exists in the table, false if the value does not exist in the table.
*[[pairsByKeys]] » This function sort pairs table.
*[[rangeToTable]] » This function converts a string range to a table containing number values.
*[[setTableProtected]] » This function protects a table and makes it read-only.
*[[setTableToSql]] » This function is used to save the table in the database (sql).
*[[Sort_Functions]] » These functions are able to sort your tables by a key.
*[[table.compare]] » This function checks whether two given tables are equal.
*[[table.copy]] » This function copies a whole table and all the tables in that table.
*[[table.deepmerge]] » This function deep merges two tables. Every nested table will be correspondingly merged.
*[[table.element]] » This function returns a new table with only userdata content.
*[[table.flip]] » This function returns the table from the last value to the first value, such as reflection.
*[[table.fromString]] » This function converts string to a table.
*[[table.getRandomRows]] » This function returns random rows from table.
*[[table.map]] » This function goes through a table and replaces every field with the return of the passed function, where the field's value is passed as first argument and optionally more arguments.
*[[table.merge]] » This function merges two or more tables together.
*[[table.random]] » This function retrieves a random value from a table.
*[[table.removeValue]] » This function removes a specified value from a table.
*[[table.size]] » This function returns the absolute size of a table.

=== ACL functions ===
*[[aclGroupClone]] » This function clone a group to another group with/without ACLs and/or objects.
*[[getPlayerAcls]] » This function returns a table of all ACL groups on a player.
*[[getPlayersInACLGroup]] » This function returns all players in an ACL group.
*[[isPlayerInACL]] » This function checks if a player element is in an ACL group.
*[[renameAclGroup]] » This function gives an existing ACL group a new name.

=== Account functions ===
*[[getPlayerFromAccountName]] » This function is used to obtain a player by the name of his account.

=== Camera functions ===
*[[smoothMoveCamera]] » This function allows you to create a cinematic camera flight.

=== Colshape functions ===
*[[createGarageColShape]] » This function creates a collision shape from the specified garage.

=== Cursor functions ===
*[[getCursorMovedOn]] » This function checks in which way the cursor is currently moving.
*[[setCursorCenteredOnRectangle]] » This functions will center the cursor inside a rectangle.

=== Drawing functions ===
*[[dxDrawAnimWindow]] » This function draws an animated 2D window on the screen.
*[[dxDrawBorderedRectangle]] » This is a function that will create a bordered rectangle.
*[[dxDrawBorderedText]] » This is a function that will create a bordered text.
*[[dxDrawDashedLine]] » This function draws a line with dashes.
*[[dxDrawEditbox]] » This function draws a edit box across the screen - rendered for one frame. This should be used in conjunction with '''onClientRender''' in order to display continuously.
*[[dxDrawGifImage]] » This function simulates the effect of a GIF image by using image sprites in 2D.
*[[dxDrawImage3D]] » This function draws a 3D image in GTA world.
*[[dxDrawImageOnElement]] » This function draws an image on any element.
*[[dxDrawLinedRectangle]] » This is a function that will create a rectangle outline with dx lines.
*[[dxDrawLoading]] » This function draws a loading bar on the screen.
*[[dxDrawOctagon3D]] » This function creates a 3D Octagon
*[[dxDrawPolygon]] » This function draws a custom polygon on the screen.
*[[dxDrawProgressBar]] » This function simulates a progress bar drawed using DirectDraw.
*[[dxDrawRectangle3D]] » This function draws a 3D rectangle in GTA world.
*[[dxDrawRectangleOnPlayer]] » This function draws a 3D rectangle above the player.
*[[dxDrawRing]] » This function draws a ring with dx lines.
*[[dxDrawRombo]] » This function creates a Rhombus.
*[[dxDrawSprite]] » This function draw a sprite in the 3D world.
*[[dxDrawTextOnElement]] » This function draws a text on any element.
*[[dxDrawTextOnRectangle]] » Esta funcion crea un rectangle con un texto dentro.
*[[dxDrawTriangle]] » This is a function that will create a triangle with dx lines.
*[[dxFade]] » This function fade-in or fade-out any dxDraw by gradually changing its alpha value.
*[[dxGetFontSizeFromHeight]] » This function calculates the font size from given height.
*[[dxGetRealFontHeight]] » This function calculates the height of a font.
*[[getScreenStartPositionFromBox]] » This function helps with getting the correct position for your dx-effects.
*[[wordWrap]] » This function breaks a long string into a table of separate lines limited to a specific length in pixels, for drawing separately.
*[[CreateRectangle3D]] » This is a function that will create a 3d rectangle on the player screen.
*[[DxDrawBordered3DLine]] »This function creates a bordered area with 3D dx lines.

=== Effects functions ===
*[[attachEffect]] » This function allows you attach an effect to an element.
*[[setScreenFlash]] » This function will make the screen flash(like a screenshot).

=== Element functions ===
*[[autoAttach]] » This function attaches one element into another at the same position and rotation they are.
*[[attachElementToBone]] » This function allows you to attach an element to ped bone accurately using new bone functions.
*[[getElementDirectionCardialPoint]] » This function returns the direction of the element according to the ''wind rose''.
*[[getElementSpeed]] » This function returns the specified element's speed in m/s, km/h or mph.
*[[getElementUsingData]] » This function returns table elements that contains the elements data with the given key and value.
*[[getElementZoneFullName]] » This function allows you to retrieve the zone full name of a element.
*[[getElementsInDimension]] » This function returns a table of elements that are in the specified dimension.
*[[getElementsWithinMarker]] » This function returns a table of elements that are within a marker's collision shape.
*[[getNearestElement]] » This function returns the nearest element (of a specific type) to a player.
*[[isElementInAir]] » This function checks if an element is in air or not.
*[[isElementInPhotograph]] » This function checks if an element is in the player's camera picture area.
*[[isElementInRange]] » This function allows you to check if an element's range to a main point is within the maximum range.
*[[isElementMoving]] » This function checks if an element is moving.
*[[isElementPlayer]] » This function checks whether the element is a player or not.
*[[isElementWithinAColShape]] » This function checks if an element is within a collision shape element.
*[[multi_check]] » This function checks one element to many, handy and clean.
*[[setElementSpeed]] » This function allows you to set the speed of an element in kph or mph units.
*[[getPositionInFrontOfElement]] » This function returns position in provided distance away from element, including element's rotation.

=== Events ===
*[[onClientPlayerTimeChange]] » This code implements an event that is triggered when the player's real time change.
*[[onPlayerZoneChange]] » This code implements an event that is triggered when the player enters a new area on the map.
*[[onVehicleWeaponFire]] » This code implements an event that is triggered when a player in a vehicle fires a vehicle's weapon.

=== Input functions ===
*[[bindControlKeys]] » This function allows you to bind each key bound to a control individually. Doing this bypasses a little MTA restriction.
*[[getBoundControls]] » This function returns a table of control names that are bound to the specified key.
*[[unbindControlKeys]] » This function allows you to unbind each key bound to a control individually. Use this function with [[bindControlKeys]].
*[[isCommandHandlerAdded]] » This function allows you to check if a command is added or not in the respective resource.

=== Data functions ===
*[[byte2human]] » This function converts an integer (number of bytes) into a human-readable unit.
*[[capitalize]] » This function capitalizes a given string.
*[[convertDate]] » This function converts date to another look.
*[[convertServerTickToTimeStamp]] » This function converts server ticks to a unix timestamp.
*[[convertTextToSpeech]] » This function converts the provided text to a speech in the provided language which players can hear.
*[[findRotation3D]] » This function takes two sets of XYZ coordinates. It returns the 3D direction from point A to point B.
*[[findRotation]] » This function takes two points and returns the direction from point A to point B.
*[[formatDate]] » This function formats a date on the basis of a format string and returns it.
*[[formatNumber]] » This function formats large numbers by adding commas.
*[[generateRandomASCIIString]] » This function returns a random string which uses ASCII characters. 
*[[generateString]] » This function generates a random string with any characters.
*[[getAge]] » This function calculates the age of a given birthday.
*[[getDistanceBetweenElements]] » Returns the distance between two elements.
*[[getDistanceBetweenPointAndSegment2D]] » This function takes point coordinates and line (a segment) starting and ending coordinates. It returns the shortest distance between the point and the line.
*[[getEasterDate]] » This function returns easter date monthday and month for a given year.
*[[getElementRelatedAngle]] » This function returns the related angle between one element to another. This is useful to check which side an element is to another.
*[[getFreeDimension]] » This function get free dimension.
*[[getKeyFromValueInTable]] » This function returns the key of the specified value in a table.
*[[getOffsetFromXYZ]] » This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.
*[[getPointFromDistanceRotation]] » This function finds a point based on a starting point, direction and distance.
*[[getRealMonth]] » This function returns the current month name
*[[getRGColorFromPercentage]] »This function returns two integers representing red and green colors according to the specified percentage.
*[[getScreenRotationFromWorldPosition]] » This function returns a screen relative rotation to a world position.
*[[getTimestamp]] » This function returns the UNIX timestamp of a specified date and time.
*[[gradientString]] » This function transforms a string in a new coloured gradient string.
*[[hex2rgb]] » This function convert hex to rgb.
*[[hexColorToRGB]] » This function convert hex string/number to RGBA values.
*[[isLeapYear]] » This function returns a boolean representing if a given year is a leap year.
*[[isValidMail]] » This function checks whether a provided e-mail string is valid.
*[[removeHex]] » This function is used to remove hexadecimal numbers (colors, for example) from strings.
*[[RGBToHex]] » This function returns a string representing the color in hexadecimal.
*[[RGBToHSV]] » This function convert RGB to HSV color space.
*[[RGBToDecimal]] » This function convert RGB to Decimal color.
*[[secondsToTimeDesc]] » This function converts a plain seconds-integer into a user-friendly time description.
*[[string.count]] » This function counts the amount of occurences of a string in a string.
*[[string.explode]] » This function splits a string at a given separator pattern and returns a table with the pieces.
*[[string.insert]] » This function inserts a string within another string at a given position.
*[[splitMultiple]] » This function improves the split function so that multiple characters can be used as the split at character.
*[[switch]] » This function allows the value of a variable or expression to control the flow of program execution via a multiway branch.
*[[tocolor2rgba]] » This function convert tocolor to rgba.
*[[toHex]] » This function converts a decimal number to a hexadecimal number, as a fix to be used client-side.
*[[var dump]] » This function outputs information about one or more variables using outputConsole.
*[[wavelengthToRGBA]] » This function converts a physical wavelength of light to a RGBA color.

=== GUI functions ===
*[[centerWindow]] » This function centers a CEGUI window element responsively in any resolution.
*[[guiMoveElement]] » This function moves guiElement by/like using moveObject.
*[[guiSetStaticImageMovable]] » This function allows you to move a static image like a gui window.
*[[isMouseOnGUICloseButton]] » This function allows you to check whether the mouse cursor/pointer is within a gui-window's native close button.
*[[isMouseOnGuiElement]] » This function allows you to check whether or not your mouse is over a specific gui element, this is especially useful if the gui element has a parent. 
=====Comboboxes=====
*[[guiComboBoxAdjustHeight]] » This function adjusts a CEGUI combobox element to have the correct height.

=====Gridlists=====
*[[convertGridListToText]] » This function converts grid list contents to text.
*[[getGridListRowIndexFromText]] » This function returns the GridList row index from the specified text.
*[[guiGridListAddPlayers]] » This function add all online players to a grid list.
*[[guiGridListGetColumnIDFromTitle]] » This function gets a gridlist's column ID from the column title.
*[[guiGridListGetSelectedText]] » This function returns a string containing the inner text of a selected gridlist item.
*[[guiGridListSetColumnNonSortable]] » This function makes a gridlist column become non-sortable.
*[[isTextInGridList]] » This function checks if some text exist or not in the GridList.

=====Labels=====
*[[guiLabelAddEffect]] » This function add an effects to the gui-label like (shadow, outline).

=== Marker functions ===
*[[createMarkerAttachedTo]] » This function creates a marker that is attached to an element.

=== Math functions ===
*[[math.clamp]] » This function returns the number between range of numbers or it's minimum or maximum.
*[[math.getBezierPoint]] » Get N-th order bezier point.
*[[math.hypot]] » This function returns the Hypotenuse of the triangle given by sides x and y.
*[[math.isPointInPolygon]] » Check if point is inside polygon or not.
*[[math.lerp]] » Get val between two integer.
*[[math.percent]] » This function returns a percentage from two number values.
*[[math.polygonArea]] » Compute area of any polygon.
*[[math.randomDiff]] » Generates a pseudo-random integer that's always different from the last random number generated.
*[[math.rotVecToEulerAngle]] » Rotation Vector To Euler Angle
*[[math.round]] » Rounds a number whereas the number of decimals to keep and the method may be set.
*[[mathNumber]] » This function is a workaround for the client-side floating-point precision of 24-bits.
*[[reMap]] » Re-maps a number from one range to another.
*[[Math.percentProgress|math.percentProgress]] » Returns a percentage progress from two specific values.
*[[math.average]] » This function returns the simple arithmetic mean of multiple numbers.

=== Map functions ===
*[[assignLod]] » This function lets you conveniently generate and apply a LOD model to a mapping object.
*[[getWorldPositionFromMapPosition]] » This function converts an F11 map position to world position.

=== Ped functions ===
*[[getAlivePlayersInTeam]] » This function returns a table of the alive players in a team.
*[[getGuestPlayers]] » This function gets a players not login or players Guest .
*[[getOnlineAdmins]] » This function returns a table of all logged-in administrators.
*[[getPedEyesPosition]] » This function allows you to get peds eyes position.
*[[getPedGender]] » This function allows you to get peds their gender.
*[[getPedMaxHealth]] » This function returns a pedestrians's maximum health by converting it from their maximum health stat.
*[[getPedMaxOxygenLevel]] » This function returns a ped's maximum oxygen level by converting it from their maximum underwater stamina stat.
*[[getPedWeaponSkill]] » This function returns a ped's corresponding weapon skill level name.
*[[getPedHitBone]] » This function gets the approximate number of the bone where the ped is hit.
*[[getPlayerFromNamePart]] » This function returns a player from partial name.
*[[getPlayerFromSerial]] » This function returns a player from their serial.
*[[getPlayersByData]] » This function returns a table of players that have the specified data name.
*[[getPlayersInPhotograph]] » This function returns a table of all players in photograph.
*[[getPlayersInVehicles]] » This function returns a table of the players insides vehicles from a specified dimension.
*[[isPedAiming]]» This function checks if a pedestrian is aiming their weapon.
*[[isPedAimingNearPed]] » This is similar to isPedAiming but uses a colshape to be more precise.
*[[isPedDiving]] » This feature checks that pedestrian is diving in the water.
*[[isPedDrivingVehicle]] » This function checks if a specified pedestrian is driving a vehicle.
*[[isPedNearbyWall]] » This function checks if player/ped is nearby a objects like buildings or walls.
*[[isPlayerInTeam]] » This function checks if a player is in a specified team.
*[[setPedAttack]] » This function will make a ped attack a specified target.
*[[setPedFollow]] » This function will make a ped follow a specified target.
*[[getPlayerNameFromID]] » This function will get the player name from the ID element data.

=== Player functions ===
*[[countPlayersInRange]] » This function returns the number of players that are within a certain range of the specified coordinates.
*[[getPlayerPreviousAndNextWeapon]] » This function returns the player previous and next weapon.
*[[getPlayersInRange]] » This function make a table of players within certain range.
*[[isPlayerActuallyInVehicle]] » This function checks if a player is actually in a vehicle instead of just in the process of entering.
*[[isPlayerHitByVehicle]] » This function cancels event when a element is hit by a vehicle.

=== Resource functions ===
*[[getFilesInResourceFolder]] » This function gets a list of files that are inside a folder of a resource.
*[[getResourceScripts]] » This function returns a table of the resource scripts.
*[[getResourceSettings]] » This function returns a table of the resource settings.
*[[getResourceSize]] » This function returns the size of a specified resource in kB(kilobyte)
*[[refreshResource]] » This function refreshes your resource if you changed any of the files
*[[setResourcePriority]] » This function set resource download priority group.

=== Sound functions ===
*[[isSoundFinished]] » This function checks if a sound element has finished.
*[[isSoundPlaying]] » This function checks if a sound element is playing or not.
*[[stopSoundSlowly]] » This function stop your sound element slowly.

=== Browser functions ===
*[[playVideo]] » This function plays a video on the screen.

=== Team functions ===
*[[getTeamFromColor]] » This function returns a team element by the specified color.
*[[getTeamWithFewestPlayers]] » This function returns a team element with least players of all the specified teams.

=== Vehicle functions ===
*[[findEmptyCarSeat]] » This function finds you the first empty seat in a vehicle.
*[[getNearestVehicle]] » This function gets the nearest vehicle to the specified player in a specified distance.
*[[getRandomVehicle]] » This function gets a random vehicle.
*[[getValidVehicleModels]] » This function returns a table of all valid vehicle models.
*[[getVehiclesCountByType]] » This function returns the amount of vehicles by the given type as an integer value.
*[[getVehicleTurnVelocityCenterOfMass]]» This function gets a vehicle's turn velocity relative to the vehicle's center or mass.
*[[isVehicleDoubleExhaust]] » This function checks is exhaust vehicle double.
*[[isVehicleEmpty]] » This function checks whether a vehicle is empty.
*[[isVehicleOccupied]] » This function checks if a specified vehicle is occupied.
*[[isVehicleOnRoof]] » This function checks whether vehicle is on roof.
*[[isVehicleOnFire]] » This function checks if the vehicle is on fire or not.
*[[isVehicleReversing]] » This function checks if a specified vehicle is moving backwards.
*[[isVehicleUpgraded]] » This function checks is vehicle upgraded by upgrade ID.
*[[setVehicleGravityPoint]] » This function sets a vehicle's gravity in the direction of a 3 dimensional coordinate with the strength specified.
*[[setVehicleTurnVelocityCenterOfMass]] » This function sets a vehicle's turn velocity relative to the vehicle's center or mass.
*[[setVehicleHandlingFromText]] » This function sets a vehicle's handling from text.
*[[setVehicleWheelModel]] » This function changes the wheel model of the informed vehicle.

=== Weapon functions ===
*[[getJetpackWeaponsEnabled]] » This function returns a table of enabled weapons usable on a jetpack.

=== Object functions ===
*[[getDynamicDoorObjectOpenRatio]] » This function tells you how open a dynamic door is in a range from 0 to 1.
*[[isElementObject]] » This function tells you if an element is an object or no.

=== XML functions ===
*[[getXMLNodes]] » This function returns all children of a XML node.

=== Engine functions ===
*[[engineGetCOLsFromLibrary]] » This function gets the collision data from the col library.
*[[engineLoadIMGContainer]] » This function loads the IMG container.

=== Utility ===
*[[animate]] » This function allows you to use interpolateBetween without render event and easily used.
*[[callClientFunction]] » This function allows you to call any client-side function from the server's side.
*[[callServerFunction]] » This function allows you to call any server-side function from the client's side.
*[[check]] » This function checks if its arguments are of the right type and calls the error-function if one is not.
*[[checkPassiveTimer]] » This function allows you to use passive timers in your conditions. For example you want to prevent players repeatedly using a command.
*[[coroutine.resume]] » This function applies a fix for hidden coroutine error messages.
*[[compact]] » This function create table containing variables and their values.
*[[getBanFromName]] » This functions returns the ban of the given playername.
*[[getCurrentFPS]] » This function returns the frames per second at which GTA: SA is running.
*[[getSkinNameFromID]] » This function returns the name of the skin from the given id.
*[[IfElse]] » This function returns one of two values based on a boolean expression.
*[[isCharInString]] » This shared function allows you to check if a char specified is in a string value.
*[[isLastExecuteInTimer]] » This function check if the execute is the last execute in the timer.
*[[isMouseInCircle]] » This function checks if a cursor position is in circular area or not.
*[[isMouseInPosition]] » This function allows you to check whether the mouse cursor/pointer is within a rectangular position.
*[[iterElements]] » This function returns ''a time-saving'' iterator for your for-loops.
*[[PlotTrajectoryAtTime]] » Calculate projectile/water trajectory.
*[[preprocessor]] » This function allow you to use gcc macros.
*[[vector3:compare]] » This method checks whether two vectors match, with optional precision.
*[[svgCreateRoundedRectangle]] » This function creates a rectangle with rounded edges.
*[[debounce]] » This function is removing unwanted input noise.

<noinclude>[[Category:Useful Functions]]</noinclude>

SplitMultiple

2023-11-15T16:55:29Z

Arran Fortuna:

{{Useful Function}}
<lowercasetitle></lowercasetitle>
__NOTOC__
This function splits a string into a table when the specified character(s) are detected. 

==Syntax==
<syntaxhighlight lang="lua">table splitMultiple( string str, string chars )</syntaxhighlight>

===Required Arguments===
* '''str''': The string to split.
* '''chars''': The characters to detect and split the string at.

===Returns===
Returns a table containing the pieces of the split string.

==Code==
<section name="Server- and/or clientside Script" class="both" show="true">
<syntaxhighlight lang="lua">
function splitMultiple(str, word)
local result = {}
local pattern = "(.-)" .. word

for match in string.gmatch(str, pattern) do
table.insert(result, match)
end

-- Add the remaining part of the string, if any
local lastPart = string.match(str, word .. "(.*)")
if lastPart then
table.insert(result, lastPart)
end

return result
end

</syntaxhighlight>
</section>

==Example==
<section name="Server" class="server" show="true">
<syntaxhighlight>
local text = "This is an example string with some words to split."
local word = "word"
local parts = splitStringByWord(text, word)

for i, part in ipairs(parts) do
print("Part " .. i .. ": " .. part)
end
</syntaxhighlight>
</section>

Author: ChatGPT-4

==See Also==
{{Useful_Functions}}

SplitMultiple

2023-11-15T16:55:10Z

Arran Fortuna: Created page with "{{Useful Function}} <lowercasetitle></lowercasetitle> __NOTOC__ This function splits a string into a table when the specified character(s) are detected. ==Syntax== <syntaxhighlight lang="lua">table splitMultiple( string str )</syntaxhighlight> ===Required Arguments=== * '''str''': The string to split. * '''chars''': The characters to detect and split the string at. ===Returns=== Returns a table containing the pieces of the split string. ==Code== <section name="S..."

{{Useful Function}}
<lowercasetitle></lowercasetitle>
__NOTOC__
This function splits a string into a table when the specified character(s) are detected. 

==Syntax==
<syntaxhighlight lang="lua">table splitMultiple( string str )</syntaxhighlight>

===Required Arguments===
* '''str''': The string to split.
* '''chars''': The characters to detect and split the string at.

===Returns===
Returns a table containing the pieces of the split string.

==Code==
<section name="Server- and/or clientside Script" class="both" show="true">
<syntaxhighlight lang="lua">
function splitMultiple(str, word)
local result = {}
local pattern = "(.-)" .. word

for match in string.gmatch(str, pattern) do
table.insert(result, match)
end

-- Add the remaining part of the string, if any
local lastPart = string.match(str, word .. "(.*)")
if lastPart then
table.insert(result, lastPart)
end

return result
end

</syntaxhighlight>
</section>

==Example==
<section name="Server" class="server" show="true">
<syntaxhighlight>
local text = "This is an example string with some words to split."
local word = "word"
local parts = splitStringByWord(text, word)

for i, part in ipairs(parts) do
print("Part " .. i .. ": " .. part)
end
</syntaxhighlight>
</section>

Author: ChatGPT-4

==See Also==
{{Useful_Functions}}

Math.clamp

2023-08-02T17:43:49Z

Arran Fortuna:

{{Useful_Function}}
This function returns the number between range of numbers or it's minimum or maximum. Alternatively if you can remember "min max min max" do math.min(math.max(x, min), max)

==Syntax==
<syntaxhighlight lang="lua">float math.clamp( float number, float min, float max )</syntaxhighlight>

===Required arguments===
* '''number''': Number that will be compared with range.
* '''min''': Minimum of range.
* '''max''': Maximum of range.

==Code==
<syntaxhighlight lang="lua">
function math.clamp(number, min, max)
if number < min then
return min
elseif number > max then
return max
end
return number
end
</syntaxhighlight>
'''Author''': Olez14

==Example==
<syntaxhighlight lang="lua">
local num = math.clamp(50, 1, 100)
print(num)
-- This prints 50.0

local num = math.clamp(-10, 1, 100)
print(num)
-- This prints 1.0

local num = math.clamp(225, 1, 100)
print(num)
-- This prints 100.0
</syntaxhighlight>

==See also==
{{Useful_Functions}}

Scripting Tips

2023-08-02T17:30:14Z

Arran Fortuna: /* General Lua */

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>
And the result will be the same, because Lua executes every instruction in every script file of a resource when it starts.
* 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 resourceRoot in event handlers for events from clients 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?
* It's much more efficient to [[SetElementHealth]] and [[setElementRotation]] on a player client side, consider a client event all your server scripts can call to set a players health.
* 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 so often. 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.
* 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>

GetLocalization

2023-07-27T18:00:07Z

Arran Fortuna:

{{Client function}}
__NOTOC__
{{New items|3.0140|1.4|
This function gets the player's localization setting as set in the MTA client.
}}
==Syntax==
<syntaxhighlight lang="lua">
table getLocalization ( )
</syntaxhighlight>

===Returns===
Returns a [[table]] with the following entries:
*'''code :''' The language code ''(eg. "en_US" for "English (United States)" or "ar" for "Arabic")''.
*'''name :''' The name of the language ''(eg. "English (United States)" or "Arabic")''.

==Example==
This example outputs simple ''Welcome'' message at the resource start (also when player joins the game if the resource is already running).
<syntaxhighlight lang="lua">
local msg = {cs = "Vítejte", fr = "Accueil", de = "Willkommen", pl = "Powitanie", hu = "Üdv"}

addEventHandler("onClientResourceStart", resourceRoot,
function ()
local languageCode = getLocalization()["code"]
if msg[languageCode] then --Check if the message is avaible in client's language
outputChatBox(msg[languageCode] .. "!") --Output it
else
outputChatBox("Welcome!") --Output English for any other language
end
end)
</syntaxhighlight>
This is a list of all the language codes used in MTA in a table with the full name of the language.
<syntaxhighlight lang="lua">
langTable = {
["ar_SA"] = "Arabic",
["az_AZ"] = "Azerbaijani",
["bg_BG"] = "Bulgarian",
["bs_BA"] = "Bosnian",
["cs_CZ"] = "Czech",
["da_DK"] = "Danish",
["de_DE"] = "German",
["en_US"] = "English",
["el_GR"] = "Greek",
["es_ES"] = "Spanish",
["et_EE"] = "Estonian",
["fa_IR"] = "Persian",
["fi_FI"] = "Finnish",
["fil_PH"] = "Filipino",
["fr_FR"] = "French",
["he_IL"] = "Hebrew",
["hi_IN"] = "Hindi",
["hr_HR"] = "Croatian",
["hu_HU"] = "Hungarian",
["id_ID"] = "Indonesian",
["it_IT"] = "Italian",
["ja_JP"] = "Japanese",
["ka_GE"] = "Georgian",
["ko_KR"] = "Korean",
["lt_LT"] = "Lithuanian",
["lv_LV"] = "Latvian",
["mk_MK"] = "Macedonian",
["nb_NO"] = "Norwegian",
["nl_NL"] = "Dutch",
["pt_BR"] = "Portuguese, Brazilian",
["pt_PT"] = "Portuguese",
["pl_PL"] = "Polish",
["ru_RU"] = "Russian",
["ro_RO"] = "Romanian",
["sl_SL"] = "Slovenian",
["sv_SE"] = "Swedish",
["sk_SK"] = "Slovak",
["srp"] = "Serbian",
["tr_TR"] = "Turkish",
["uk_UA"] = "Ukrainian",
["vi_VN"] = "Vietnamese",
["zh_CN"] = "Chinese Simplified",
["zh_TW"] = "Chinese Traditional",

}
</syntaxhighlight>

This function is useful for fixing any scripts that were made before MTA 1.6 as some of the language codes were changed.
<syntaxhighlight lang="lua">

function getLanguageCode(c)
if (c == "fr_FR") then
return "fr"
elseif (c == "ru_RU") then
return "ru"
elseif (c == "pt_PT") then
return "pt_BR"
elseif (c == "pl_PL") then
return "pl"
elseif (c == "tr_TR") then
return "tr"
elseif (c == "es_ES") then
return "es"
elseif (c == "de_DE") then
return "de"
elseif (c == "vi_VN") then
return "vi"
elseif (c == "ar_SA") then
return "ar"
elseif (c == "bg_BG") then
return "bg"
elseif (c == "hu_HU") then
return "hu"
elseif (c == "ro_RO") then
return "ro"
elseif (c == "sv_SE") then
return "sv"
elseif (c == "hr_HR") then
return "hr"
elseif (c == "uk_UA") then
return "uk"
elseif (c == "sl_SL") then
return "sl"
elseif (c == "id_ID") then
return "id"
elseif (c == "nl_NL") then
return "nl"
elseif (c == "it_IT") then
return "it"
elseif (c == "nb_NO") then
return "nb"
elseif (c == "el_GR") then
return "el"
elseif (c == "lt_LT") then
return "lt"
elseif (c == "da_DK") then
return "da"
end
return c
end

code = getLanguageCode(getLocalization().code)
</syntaxhighlight>

==See Also==
{{Client_utility_functions}}
[[ru:GetLocalization]]

GetLocalization

2023-07-27T17:51:51Z

Arran Fortuna:

{{Client function}}
__NOTOC__
{{New items|3.0140|1.4|
This function gets the player's localization setting as set in the MTA client.
}}
==Syntax==
<syntaxhighlight lang="lua">
table getLocalization ( )
</syntaxhighlight>

===Returns===
Returns a [[table]] with the following entries:
*'''code :''' The language code ''(eg. "en_US" for "English (United States)" or "ar" for "Arabic")''.
*'''name :''' The name of the language ''(eg. "English (United States)" or "Arabic")''.

==Example==
This example outputs simple ''Welcome'' message at the resource start (also when player joins the game if the resource is already running).
<syntaxhighlight lang="lua">
local msg = {cs = "Vítejte", fr = "Accueil", de = "Willkommen", pl = "Powitanie", hu = "Üdv"}

addEventHandler("onClientResourceStart", resourceRoot,
function ()
local languageCode = getLocalization()["code"]
if msg[languageCode] then --Check if the message is avaible in client's language
outputChatBox(msg[languageCode] .. "!") --Output it
else
outputChatBox("Welcome!") --Output English for any other language
end
end)
</syntaxhighlight>
This is a list of all the language codes used in MTA in a table with the full name of the language.
<syntaxhighlight lang="lua">
langTable = {
["ar_SA"] = "Arabic",
["az_AZ"] = "Azerbaijani",
["bg_BG"] = "Bulgarian",
["bs_BA"] = "Bosnian",
["cs_CZ"] = "Czech",
["da_DK"] = "Danish",
["de_DE"] = "German",
["en_US"] = "English",
["el_GR"] = "Greek",
["es_ES"] = "Spanish",
["et_EE"] = "Estonian",
["fa_IR"] = "Persian",
["fi_FI"] = "Finnish",
["fil_PH"] = "Filipino",
["fr_FR"] = "French",
["he_IL"] = "Hebrew",
["hi_IN"] = "Hindi",
["hr_HR"] = "Croatian",
["hu_HU"] = "Hungarian",
["id_ID"] = "Indonesian",
["it_IT"] = "Italian",
["ja_JP"] = "Japanese",
["ka_GE"] = "Georgian",
["ko_KR"] = "Korean",
["lt_LT"] = "Lithuanian",
["lv_LV"] = "Latvian",
["mk_MK"] = "Macedonian",
["nb_NO"] = "Norwegian",
["nl_NL"] = "Dutch",
["pt_BR"] = "Portuguese, Brazilian",
["pt_PT"] = "Portuguese",
["pl_PL"] = "Polish",
["ru_RU"] = "Russian",
["ro_RO"] = "Romanian",
["sl_SL"] = "Slovenian",
["sv_SE"] = "Swedish",
["sk_SK"] = "Slovak",
["srp"] = "Serbian",
["tr_TR"] = "Turkish",
["uk_UA"] = "Ukrainian",
["vi_VN"] = "Vietnamese",
["zh_CN"] = "Chinese Simplified",
["zh_TW"] = "Chinese Traditional",

}
</syntaxhighlight>

This function is useful for fixing any scripts that were made before MTA 1.6 as some of the language codes were changed.
<syntaxhighlight lang="lua">

function getLanguageCode(c)
if (c == "fr_FR") then
return "fr"
elseif (c == "ru_RU") then
return "ru"
elseif (c == "pt_PT") then
return "pt_BR"
elseif (c == "pl_PL") then
return "pl"
elseif (c == "tr_TR") then
return "tr"
elseif (c == "es_ES") then
return "es"
elseif (c == "de_DE") then
return "de"
elseif (c == "vi_VN") then
return "vi"
elseif (c == "ar_SA") then
return "ar"
elseif (c == "bg_BG") then
return "bg"
elseif (c == "hu_HU") then
return "hu"
elseif (c == "ro_RO") then
return "ro"
elseif (c == "sv_SE") then
return "sv"
elseif (c == "hr_HR") then
return "hr"
elseif (c == "uk_UA") then
return "uk"
elseif (c == "sl_SL") then
return "sl"
end
return c
end

code = getLanguageCode(getLocalization().code)
</syntaxhighlight>

==See Also==
{{Client_utility_functions}}
[[ru:GetLocalization]]

GetLocalization

2023-07-03T12:51:43Z

Arran Fortuna: /* Example */

{{Client function}}
__NOTOC__
{{New items|3.0140|1.4|
This function gets the player's localization setting as set in the MTA client.
}}
==Syntax==
<syntaxhighlight lang="lua">
table getLocalization ( )
</syntaxhighlight>

===Returns===
Returns a [[table]] with the following entries:
*'''code :''' The language code ''(eg. "en_US" for "English (United States)" or "ar" for "Arabic")''.
*'''name :''' The name of the language ''(eg. "English (United States)" or "Arabic")''.

==Example==
This example outputs simple ''Welcome'' message at the resource start (also when player joins the game if the resource is already running).
<syntaxhighlight lang="lua">
local msg = {cs = "Vítejte", fr = "Accueil", de = "Willkommen", pl = "Powitanie", hu = "Üdv"}

addEventHandler("onClientResourceStart", resourceRoot,
function ()
local languageCode = getLocalization()["code"]
if msg[languageCode] then --Check if the message is avaible in client's language
outputChatBox(msg[languageCode] .. "!") --Output it
else
outputChatBox("Welcome!") --Output English for any other language
end
end)
</syntaxhighlight>
This is a list of all the language codes used in MTA in a table with the full name of the language.
<syntaxhighlight lang="lua">
langTable = {
["ar_SA"] = "Arabic",
["az_AZ"] = "Azerbaijani",
["bg_BG"] = "Bulgarian",
["bs_BA"] = "Bosnian",
["cs_CZ"] = "Czech",
["da_DK"] = "Danish",
["de_DE"] = "German",
["en_US"] = "English",
["el_GR"] = "Greek",
["es_ES"] = "Spanish",
["et_EE"] = "Estonian",
["fa_IR"] = "Persian",
["fi_FI"] = "Finnish",
["fil_PH"] = "Filipino",
["fr_FR"] = "French",
["he_IL"] = "Hebrew",
["hi_IN"] = "Hindi",
["hr_HR"] = "Croatian",
["hu_HU"] = "Hungarian",
["id_ID"] = "Indonesian",
["it_IT"] = "Italian",
["ja_JP"] = "Japanese",
["ka_GE"] = "Georgian",
["ko_KR"] = "Korean",
["lt_LT"] = "Lithuanian",
["lv_LV"] = "Latvian",
["mk_MK"] = "Macedonian",
["nb_NO"] = "Norwegian",
["nl_NL"] = "Dutch",
["pt_BR"] = "Portuguese, Brazilian",
["pt_PT"] = "Portuguese",
["pl_PL"] = "Polish",
["ru_RU"] = "Russian",
["ro_RO"] = "Romanian",
["sl_SL"] = "Slovenian",
["sv_SE"] = "Swedish",
["sk_SK"] = "Slovak",
["srp"] = "Serbian",
["tr_TR"] = "Turkish",
["uk_UA"] = "Ukrainian",
["vi_VN"] = "Vietnamese",
["zh_CN"] = "Chinese Simplified",
["zh_TW"] = "Chinese Traditional",

}
</syntaxhighlight>

This function is useful for fixing any scripts that were made before MTA 1.6 as some of the language codes were changed.
<syntaxhighlight lang="lua">

function getLanguageCode(c)
if (c == "fr_FR") then
return "fr"
elseif (c == "ru_RU") then
return "ru"
elseif (c == "pt_PT") then
return "pt_BR"
elseif (c == "pl_PL") then
return "pl"
elseif (c == "tr_TR") then
return "tr"
elseif (c == "es_ES") then
return "es"
elseif (c == "de_DE") then
return "de"
elseif (c == "vi_VN") then
return "vi"
elseif (c == "ar_SA") then
return "ar"
elseif (c == "bg_BG") then
return "bg"
elseif (c == "hu_HU") then
return "hu"
elseif (c == "ro_RO") then
return "ro"
elseif (c == "sv_SE") then
return "sv"
elseif (c == "hr_HR") then
return "hr"
elseif (c == "uk_UA") then
return "uk"
end
return c
end

code = getLanguageCode(getLocalization().code)
</syntaxhighlight>

==See Also==
{{Client_utility_functions}}
[[ru:GetLocalization]]

GetLocalization

2023-07-03T12:51:16Z

Arran Fortuna:

{{Client function}}
__NOTOC__
{{New items|3.0140|1.4|
This function gets the player's localization setting as set in the MTA client.
}}
==Syntax==
<syntaxhighlight lang="lua">
table getLocalization ( )
</syntaxhighlight>

===Returns===
Returns a [[table]] with the following entries:
*'''code :''' The language code ''(eg. "en_US" for "English (United States)" or "ar" for "Arabic")''.
*'''name :''' The name of the language ''(eg. "English (United States)" or "Arabic")''.

==Example==
This example outputs simple ''Welcome'' message at the resource start (also when player joins the game if the resource is already running).
<syntaxhighlight lang="lua">
local msg = {cs = "Vítejte", fr = "Accueil", de = "Willkommen", pl = "Powitanie", hu = "Üdv"}

addEventHandler("onClientResourceStart", resourceRoot,
function ()
local languageCode = getLocalization()["code"]
if msg[languageCode] then --Check if the message is avaible in client's language
outputChatBox(msg[languageCode] .. "!") --Output it
else
outputChatBox("Welcome!") --Output English for any other language
end
end)
</syntaxhighlight>
This is a list of all the language codes used in MTA in a table with the full name of the language.
<syntaxhighlight lang="lua">
langTable = {
["ar_SA"] = "Arabic",
["az_AZ"] = "Azerbaijani",
["bg_BG"] = "Bulgarian",
["bs_BA"] = "Bosnian",
["cs_CZ= "Czech",
["da_DK"] = "Danish",
["de_DE"] = "German",
["en_US"] = "English",
["el_GR"] = "Greek",
["es_ES"] = "Spanish",
["et_EE"] = "Estonian",
["fa_IR"] = "Persian",
["fi_FI"] = "Finnish",
["fil_PH"] = "Filipino",
["fr_FR"] = "French",
["he_IL"] = "Hebrew",
["hi_IN"] = "Hindi",
["hr_HR"] = "Croatian",
["hu_HU"] = "Hungarian",
["id_ID"] = "Indonesian",
["it_IT"] = "Italian",
["ja_JP"] = "Japanese",
["ka_GE"] = "Georgian",
["ko_KR"] = "Korean",
["lt_LT"] = "Lithuanian",
["lv_LV"] = "Latvian",
["mk_MK"] = "Macedonian",
["nb_NO"] = "Norwegian",
["nl_NL"] = "Dutch",
["pt_BR"] = "Portuguese, Brazilian",
["pt_PT"] = "Portuguese",
["pl_PL"] = "Polish",
["ru_RU"] = "Russian",
["ro_RO"] = "Romanian",
["sl_SL"] = "Slovenian",
["sv_SE"] = "Swedish",
["sk_SK"] = "Slovak",
["srp"] = "Serbian",
["tr_TR"] = "Turkish",
["uk_UA"] = "Ukrainian",
["vi_VN"] = "Vietnamese",
["zh_CN"] = "Chinese Simplified",
["zh_TW"] = "Chinese Traditional",

}
</syntaxhighlight>

This function is useful for fixing any scripts that were made before MTA 1.6 as some of the language codes were changed.
<syntaxhighlight lang="lua">

function getLanguageCode(c)
if (c == "fr_FR") then
return "fr"
elseif (c == "ru_RU") then
return "ru"
elseif (c == "pt_PT") then
return "pt_BR"
elseif (c == "pl_PL") then
return "pl"
elseif (c == "tr_TR") then
return "tr"
elseif (c == "es_ES") then
return "es"
elseif (c == "de_DE") then
return "de"
elseif (c == "vi_VN") then
return "vi"
elseif (c == "ar_SA") then
return "ar"
elseif (c == "bg_BG") then
return "bg"
elseif (c == "hu_HU") then
return "hu"
elseif (c == "ro_RO") then
return "ro"
elseif (c == "sv_SE") then
return "sv"
elseif (c == "hr_HR") then
return "hr"
elseif (c == "uk_UA") then
return "uk"
end
return c
end

code = getLanguageCode(getLocalization().code)
</syntaxhighlight>
==See Also==
{{Client_utility_functions}}
[[ru:GetLocalization]]

GetLocalization

2023-06-26T19:44:23Z

Arran Fortuna:

{{Client function}}
__NOTOC__
{{New items|3.0140|1.4|
This function gets the player's localization setting as set in the MTA client.
}}
==Syntax==
<syntaxhighlight lang="lua">
table getLocalization ( )
</syntaxhighlight>

===Returns===
Returns a [[table]] with the following entries:
*'''code :''' The language code ''(eg. "en_US" for "English (United States)" or "ar" for "Arabic")''.
*'''name :''' The name of the language ''(eg. "English (United States)" or "Arabic")''.

==Example==
This example outputs simple ''Welcome'' message at the resource start (also when player joins the game if the resource is already running).
<syntaxhighlight lang="lua">
local msg = {cs = "Vítejte", fr = "Accueil", de = "Willkommen", pl = "Powitanie", hu = "Üdv"}

addEventHandler("onClientResourceStart", resourceRoot,
function ()
local languageCode = getLocalization()["code"]
if msg[languageCode] then --Check if the message is avaible in client's language
outputChatBox(msg[languageCode] .. "!") --Output it
else
outputChatBox("Welcome!") --Output English for any other language
end
end)
</syntaxhighlight>
This is a list of all (probably all) the language codes used in MTA in a table with the full name of the language. Note that when MTA 1.6 was released some of these have changed.
<syntaxhighlight lang="lua">
langTable = {
["ar"] = "Arabic",
["bg"] = "Bulgarian",
["cs"] = "Czech",
["da"] = "Danish",
["de"] = "German",
["en_US"] = "English",
["el"] = "Greek",
["es"] = "Spanish",
["et"] = "Estonian",
["fr"] = "French",
["hr"] = "Croatian",
["hu"] = "Hungarian",
["id"] = "Indonesian",
["it"] = "Italian",
["ja"] = "Japanese",
["lt"] = "Lithuanian",
["lv"] = "Latvian",
["mk"] = "Macedonian",
["nb"] = "Norwegian",
["nl"] = "Dutch",
["pt_BR"] = "Brazilian",
["pl"] = "Polish",
["ru"] = "Russian",
["ro"] = "Romanian",
["sl"] = "Slovenian",
["sv"] = "Swedish",
["sk"] = "Slovak",
["tr"] = "Turkish",
["uk"] = "Ukrainian",
["vi"] = "Vietnamese",
["zh_CN"] = "Chinese",
["zh_TW"] = "Taiwanese",

}
</syntaxhighlight>
This function is useful for fixing any scripts that were made before MTA 1.6 as some of the language codes were changed.
<syntaxhighlight lang="lua">

function getLanguageCode(c)
if (c == "fr_FR") then
return "fr"
elseif (c == "ru_RU") then
return "ru"
elseif (c == "pt_PT") then
return "pt_BR"
elseif (c == "pl_PL") then
return "pl"
elseif (c == "tr_TR") then
return "tr"
elseif (c == "es_ES") then
return "es"
elseif (c == "de_DE") then
return "de"
elseif (c == "vi_VN") then
return "vi"
elseif (c == "ar_SA") then
return "ar"
elseif (c == "bg_BG") then
return "bg"
elseif (c == "hu_HU") then
return "hu"
elseif (c == "ro_RO") then
return "ro"
elseif (c == "sv_SE") then
return "sv"
elseif (c == "hr_HR") then
return "hr"
elseif (c == "uk_UA") then
return "uk"
end
return c
end

code = getLanguageCode(getLocalization().code)
</syntaxhighlight>

==See Also==
{{Client_utility_functions}}
[[ru:GetLocalization]]

GetLocalization

2023-06-26T19:26:25Z

Arran Fortuna:

Scripting Tips

2022-10-31T17:22:08Z

Arran Fortuna:

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

== 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>
And the result will be the same, because Lua executes every instruction in every script file of a resource when it starts.
* 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 resourceRoot in event handlers for events from clients 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?
* It's much more efficient to [[SetElementHealth]] and [[setElementRotation]] on a player client side, consider a client event all your server scripts can call to set a players health.
* 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 so often. 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.
* 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>

Compiling MTASA

2021-11-15T16:42:12Z

Arran Fortuna: Updated again, should be right now, will ask a dev about it.

In order to successfully build Multi Theft Auto from source, it is necessary to perform a number of steps, which we will explain below.

Please read the instructions carefully and do not skip parts of it, if you have no experience.

== Prerequisites ==

Compiling the Multi Theft Auto client is only supported on Windows 10.

Make sure you have the following software and SDKs installed:

=== Visual Studio 2019 ===
[[File:Visual_Studio_Community.PNG|right|150px|link=https://www.visualstudio.com/vs/]]
# '''[https://visualstudio.microsoft.com/vs/ Download Microsoft Visual Studio 2019]''' - make sure you get the Community Edition, that one is free.
# On the installation checklist, [[:File:VsFoundationClasses.png|make sure you tick these 3 items]]:
## ''Desktop development with C++''
## ''MSVC v142 - VS 2019 C++ x64/x86 build tools''
## In the 'Individual Components' tab search 'MFC v142' and select 'C++ v14.29 (16.11) MFC for v142 build tools (x86 & x64)'

If you don't enable MFC, you will get the following error: <code>cannot open include file 'afxres.h'</code>.

If you've made a mistake, you can run the ''Visual Studio Installer'' app to modify your current installation. There is no need to uninstall and reinstall.

=== Microsoft DirectX SDK ===
[[File:DirectX_SDK.jpg|right|150px|link=http://web.archive.org/web/20200804044856/https://www.microsoft.com/en-us/download/details.aspx?id=23549]]
'''Download Microsoft DirectX SDK (August 2009) (DXSDK_Aug09.exe):'''
* [https://archive.org/download/dxsdk_aug09/DXSDK_Aug09.exe Mirror 1]
* [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe Mirror 2]

{| class="wikitable" style="margin-top: 0px; width: 70%; word-break: break-all;"
|+ File verification
|- style="vertical-align:bottom;"
! colspan="2" | Algorithm and variant
! Hash
! Hash file
|- style="text-align:center;vertical-align:center;"
| rowspan="6" | '''{{nowrap|SHA-3}}''' || ''SHA3-224'' || 8bfcdc03518d7edd34689534fd4d21291469ff2f2eb10437ad648c58 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-224 DXSDK_Aug09.exe.sha3-224]
|- style="text-align:center;vertical-align:center;"
| ''SHA3-256'' || 45bf3e08da3b3636ddb4f4a74243430f8d65759c074c0d79756ef810c4701c5a || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-256 DXSDK_Aug09.exe.sha3-256]
|- style="text-align:center;vertical-align:center;"
| ''SHA3-384'' || b358e529963d6f5fd7f8bd4b530fb18f6a2e6a442009a54e981b2f9967589ed48150af310f283640d56f9b60d41100c9 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-384 DXSDK_Aug09.exe.sha3-384]
|- style="text-align:center;vertical-align:center;"
| ''SHA3-512'' || 43522187053af744250059ef69c0f3083cecd1157fe56daac16b9497ebc6fb5b525875144e42898367c55f757cffd3526f37074d544470578602a5a944a45a75 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-512 DXSDK_Aug09.exe.sha3-512]
|- style="text-align:center;vertical-align:center;"
| ''SHAKE128'' || 2a7c81bde9e867cbb5ef00b72ad8de66a3ee64c1d59f16465fa712479b6a84d28a02cc5ed08afa1d51e72011657453dbd4656cc9340d32e18179c39d03982dfc35c8f0c2a5c99e11dc74d0e23ed21b1e55f19c809a5a152bde39a2d46fcd12421f373f2d691ade1b57faf6c2ab7aded5a7d174f1f1c77127c0d6a1523b4775c569c5e1b4efa2da4bf2f708a96707a709e245a7f507382e69a81777919c90e95a091c0b699ce7f517 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-128000 DXSDK_Aug09.exe.sha3-128000]
|- style="text-align:center;vertical-align:center;"
| ''SHAKE256'' || 9c100dac5245a61774f3a2752bf9e941bdcd5654b18035155161c63b20936dfc9bd7334feb9a6fe9a99a65491161083b39ac3bd578e2cf4f90cba3c786e9924fa0611f65a725331b77b63e7c8b552e1637bc77531ba0f2c9cac72115b28e523929ede4e5b246a0755e8d5c4089d94bf16627fb08672cfffa523bba3d976489a0eec60d3c6a96ca2b || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-256000 DXSDK_Aug09.exe.sha3-256000]
|- style="text-align:center;vertical-align:center;"
| rowspan="6" | '''{{nowrap|SHA-2}}''' || ''SHA-224'' || a3a74b89cccfe314b79418d5598aac5e94800221e5d945c74f15c004 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-224 DXSDK_Aug09.exe.sha2-224]
|- style="text-align:center;vertical-align:center;"
| ''SHA-256'' || 4ab1de69312f10f6b41310a5218d80c478bbd823bc0f86627318d690b128fb9f || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-256 DXSDK_Aug09.exe.sha2-256]
|- style="text-align:center;vertical-align:center;"
| ''SHA-384'' || 254ed29c6ad2cadc6f013d2d51c0ac78a6bbe236a2c94ca99610eba8b2c1200d1a62c445ca9ee51bb09354875d5eca8a || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-384 DXSDK_Aug09.exe.sha2-384]
|- style="text-align:center;vertical-align:center;"
| ''SHA-512'' || style="width: 60%;" | 736393c0dfa32221e229890f87eb330174d70dd2a02fa0cace303816d3e7a10a332a44129748de39665d1b339e627d6028c2080268f7afdd5240c447fec8ff0b || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-512 DXSDK_Aug09.exe.sha2-512]
|- style="text-align:center;vertical-align:center;"
| ''SHA-512/224'' || 7e23d9ba916000782a17e23abf48e25237f45590cfe767aed9d79f10 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-512224 DXSDK_Aug09.exe.sha2-512224]
|- style="text-align:center;vertical-align:center;"
| ''SHA-512/256'' || 0c833a56046fe7e4213fcb1862c730acf313d1b8f60b51eebf64dc3e79730c1c || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-512256 DXSDK_Aug09.exe.sha2-512256]
|- style="text-align:center;vertical-align:center;"
| colspan="2" | '''MD5''' || 66e5379ecf46b014688779621bcc677c || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.md5 DXSDK_Aug09.exe.md5]
|- style="text-align:center;vertical-align:center;"
| colspan="2" | '''{{nowrap|SHA-1}}''' || 5b9b969ed7b6cf5534bb7350e44c09b3573b0e71 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha1 DXSDK_Aug09.exe.sha1]
|}
CRC32 e9f5c61d ([https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sfv DXSDK_Aug09.exe.sfv]) 

'''NOTE:''' Restart your computer after installing ''Microsoft DirectX SDK'', because otherwise the environment variable '''DXSDK_DIR''' won't be available yet. After restarting it re-run '''create-projects.bat'''

'''Cant find d3dx9.h''' 
Add the '''$(DXSDK_DIR)Include;''' to the VC++ Directories in DirectX9GuiRenderer, GUI and Client Core projects.
You can find the VC++ Directories list by selecting a project, then pressing the shortcut ALT + ENTER (without the +), then under the 'Configuration properties' you can find 'VC++ Directories', and in there you can find the 'Include Directories' field, click on it and add ''';$(DXSDK_DIR)Include;''' at the end of it.
'''Note: You need to do the same thing in Release mode as well'''

'''Cant find d3dx9.lib''' 
Do do same as in the error above, but instead of ''';$(DXSDK_DIR)Include;''' you must add ''';$(DXSDK_DIR)Lib/x86;''' to the '''Library directories''' field
'''Note: You need to do the same thing in Release mode as well'''

'''S1023 Error''' 
[https://support.microsoft.com/en-us/kb/2728613 "S1023" error when you install the DirectX SDK (June 2010)] 

=== Git Client ===
[[File:Git_logo.png|left|32px|link=https://git-scm.com/]]

If you would like to contribute to MTA, you should install Git. This will allow you to collaborate with us by creating branches and pushing to your own fork. If you are not comfortable with the command line, we recommend you to download and install [https://desktop.github.com/ GitHub Desktop].

If you only want to compile the source code and are not interested in contributing to MTA, you can download the source directly (see below).

== Getting the latest source code ==

To get the latest code, you will have to download the latest copy of our Git repository. 
We recommend cloning the repository in your Git client because you can pull any updates from there easily.

* '''Repository:''' [https://github.com/multitheftauto/mtasa-blue multitheftauto/mtasa-blue]
* '''.zip:''' [https://github.com/multitheftauto/mtasa-blue/archive/master.zip master.zip]
* '''.tar.gz:''' [https://github.com/multitheftauto/mtasa-blue/archive/master.tar.gz master.tar.gz]

== Compiling the code ==
# Execute the script '''win-create-projects.bat'''
# Open the solution file '''MTASA.sln''' in the '''Build''' directory
# If you are asked to upgrade the project, click '''Cancel'''
# Compile in Visual Studio with '''Debug''' configuration (may take some minutes)
# Execute the script '''win-install-data.bat'''

= Running the software =

== Running the client ==

You can start your client in the '''Bin''' directory. You might find there a ''Multi Theft Auto.exe'' and/or ''Multi Theft Auto_d.exe'' executable. The ''_d'' suffix indicates a debug build of the software. 
Furthermore, you can also run your client inside the debugger from Visual Studio if you want to investigate a stack trace or set breakpoints in interesting code regions (read more in the section Debugging below).

== Running the dedicated server ==

If you already have run step 5 (''Install resources'') in ''Compiling the code'' to install resources then you can go to ''Starting the server''.

=== Installing the latest resources ===
If you want to run the Multi Theft Auto dedicated server, you will have to install the required resources. These are required because they implement the most basic functionality (e.g. spawning players) in order to play.

Our official resources repository is [https://github.com/multitheftauto/mtasa-resources hosted on GitHub]. You can download the latest resources from there or [http://mirror.mtasa.com/mtasa/resources/ download a zipped version]. Make sure that you have the latest resources package.

=== Starting the server ===
To run the server, open the ''MTA Server.exe'' executable in the '''Bin/server''' directory. The ''_d'' suffix indicates a debug build of the software. 
You can also run the debug build ''MTA Server_d.exe'' with the Visual Studio Debugger (as of writing, you can do that by right-clicking on the Server's Launcher project and selecting ''Start a local instance'' in the ''Debugger'' menu), but you can also attach to a running debug build MTA server (see more in the section Debugging below).

== Debugging ==
If you already compiled the code in the '''Debug''' configuration then continue reading, if not, then go up to ''Compiling the code'' and follow the steps for a ''Debug'' build. 
You can either launch MTA yourself and attach any debugger you want to use (also applies to the Visual Studio debugger) or you start a local debugging session in Visual Studio. 
[[File:Local_Windows_Debugger.PNG]]

=== How to enable breakpoints ===
If you choose to run MTA with Visual Studio then you should also attach the debugger to the executable '''gta_sa.exe''' (press ''CTRL + ALT + P'' in Visual Studio) - otherwise, your
breakpoints will not work for anything besides the MTA Launcher project. 
[[File:Attach_to_Process.png|600px]]

=== Extending timeout duration ===
When you use breakpoints during debugging, you may get kicked by the server due to timeout, because the client is frozen. To prevent this, create the '''timeout.longtime''' file in your ''Bin/server/'' directory.
The content of the file is the new timeout duration in seconds, so make sure you type a huge number in there. If you keep the file empty, the timeout will be set to 120 seconds.

=== ReAttach for Visual Studio ===
You can use [https://marketplace.visualstudio.com/items?itemName=ErlandR.ReAttach ReAttach] to re-attach the debugger to the '''gta_sa.exe''' executable whenever you start your local debugger in Visual Studio. 
[[File:ReAttach_to_GTASA.PNG]]

= Getting involved =
Please see our [[Coding guidelines]] for information on the coding practice.

= Additional information =
If you need more information, try our [http://bugs.mtasa.com/ bug tracker] or [irc://irc.multitheftauto.com IRC channel].

= Errors =
== CL38 error. [netc_d.dll not found] ==
Solution: Delete '''Multi Theft Auto_d.exe''' and hit compile again.

== After cloning the repository, it doesn't compile the project ==
Solution: Execute '''win-create-projects.bat''' in main directory.

== CL17 Load field. Please ensure that the latest data files have been installed correctly ==
Solution: Execute '''win-install-data.bat''' in main directory.

== ERROR: Loading network library (net_d.dll) failed! ==
Solution: Execute '''win-install-data.bat''' in main directory.

[[en:Compiling MTASA]]
[[hu:Compiling MTASA]]
[[pt-br:Compilando o MTASA]]
[[ru:Compiling MTASA]]
[[Category: Development]]

Compiling MTASA

2021-11-15T16:00:10Z

Arran Fortuna: Added an error solution

In order to successfully build Multi Theft Auto from source, it is necessary to perform a number of steps, which we will explain below.

Please read the instructions carefully and do not skip parts of it, if you have no experience.

== Prerequisites ==

Compiling the Multi Theft Auto client is only supported on Windows 10.

Make sure you have the following software and SDKs installed:

=== Visual Studio 2019 ===
[[File:Visual_Studio_Community.PNG|right|150px|link=https://www.visualstudio.com/vs/]]
# '''[https://visualstudio.microsoft.com/vs/ Download Microsoft Visual Studio 2019]''' - make sure you get the Community Edition, that one is free.
# On the installation checklist, [[:File:VsFoundationClasses.png|make sure you tick these two items]]:
## ''Desktop development with C++''
## ''C++ MFC for latest v143 build tools (x86 & x64)''
## ''MSVC v142 - VS 2019 C++ x64/x86 build tools''

If you don't enable MFC, you will get the following error: <code>cannot open include file 'afxres.h'</code>.

If you've made a mistake, you can run the ''Visual Studio Installer'' app to modify your current installation. There is no need to uninstall and reinstall.

=== Microsoft DirectX SDK ===
[[File:DirectX_SDK.jpg|right|150px|link=http://web.archive.org/web/20200804044856/https://www.microsoft.com/en-us/download/details.aspx?id=23549]]
'''Download Microsoft DirectX SDK (August 2009) (DXSDK_Aug09.exe):'''
* [https://archive.org/download/dxsdk_aug09/DXSDK_Aug09.exe Mirror 1]
* [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe Mirror 2]

{| class="wikitable" style="margin-top: 0px; width: 70%; word-break: break-all;"
|+ File verification
|- style="vertical-align:bottom;"
! colspan="2" | Algorithm and variant
! Hash
! Hash file
|- style="text-align:center;vertical-align:center;"
| rowspan="6" | '''{{nowrap|SHA-3}}''' || ''SHA3-224'' || 8bfcdc03518d7edd34689534fd4d21291469ff2f2eb10437ad648c58 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-224 DXSDK_Aug09.exe.sha3-224]
|- style="text-align:center;vertical-align:center;"
| ''SHA3-256'' || 45bf3e08da3b3636ddb4f4a74243430f8d65759c074c0d79756ef810c4701c5a || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-256 DXSDK_Aug09.exe.sha3-256]
|- style="text-align:center;vertical-align:center;"
| ''SHA3-384'' || b358e529963d6f5fd7f8bd4b530fb18f6a2e6a442009a54e981b2f9967589ed48150af310f283640d56f9b60d41100c9 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-384 DXSDK_Aug09.exe.sha3-384]
|- style="text-align:center;vertical-align:center;"
| ''SHA3-512'' || 43522187053af744250059ef69c0f3083cecd1157fe56daac16b9497ebc6fb5b525875144e42898367c55f757cffd3526f37074d544470578602a5a944a45a75 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-512 DXSDK_Aug09.exe.sha3-512]
|- style="text-align:center;vertical-align:center;"
| ''SHAKE128'' || 2a7c81bde9e867cbb5ef00b72ad8de66a3ee64c1d59f16465fa712479b6a84d28a02cc5ed08afa1d51e72011657453dbd4656cc9340d32e18179c39d03982dfc35c8f0c2a5c99e11dc74d0e23ed21b1e55f19c809a5a152bde39a2d46fcd12421f373f2d691ade1b57faf6c2ab7aded5a7d174f1f1c77127c0d6a1523b4775c569c5e1b4efa2da4bf2f708a96707a709e245a7f507382e69a81777919c90e95a091c0b699ce7f517 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-128000 DXSDK_Aug09.exe.sha3-128000]
|- style="text-align:center;vertical-align:center;"
| ''SHAKE256'' || 9c100dac5245a61774f3a2752bf9e941bdcd5654b18035155161c63b20936dfc9bd7334feb9a6fe9a99a65491161083b39ac3bd578e2cf4f90cba3c786e9924fa0611f65a725331b77b63e7c8b552e1637bc77531ba0f2c9cac72115b28e523929ede4e5b246a0755e8d5c4089d94bf16627fb08672cfffa523bba3d976489a0eec60d3c6a96ca2b || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-256000 DXSDK_Aug09.exe.sha3-256000]
|- style="text-align:center;vertical-align:center;"
| rowspan="6" | '''{{nowrap|SHA-2}}''' || ''SHA-224'' || a3a74b89cccfe314b79418d5598aac5e94800221e5d945c74f15c004 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-224 DXSDK_Aug09.exe.sha2-224]
|- style="text-align:center;vertical-align:center;"
| ''SHA-256'' || 4ab1de69312f10f6b41310a5218d80c478bbd823bc0f86627318d690b128fb9f || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-256 DXSDK_Aug09.exe.sha2-256]
|- style="text-align:center;vertical-align:center;"
| ''SHA-384'' || 254ed29c6ad2cadc6f013d2d51c0ac78a6bbe236a2c94ca99610eba8b2c1200d1a62c445ca9ee51bb09354875d5eca8a || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-384 DXSDK_Aug09.exe.sha2-384]
|- style="text-align:center;vertical-align:center;"
| ''SHA-512'' || style="width: 60%;" | 736393c0dfa32221e229890f87eb330174d70dd2a02fa0cace303816d3e7a10a332a44129748de39665d1b339e627d6028c2080268f7afdd5240c447fec8ff0b || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-512 DXSDK_Aug09.exe.sha2-512]
|- style="text-align:center;vertical-align:center;"
| ''SHA-512/224'' || 7e23d9ba916000782a17e23abf48e25237f45590cfe767aed9d79f10 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-512224 DXSDK_Aug09.exe.sha2-512224]
|- style="text-align:center;vertical-align:center;"
| ''SHA-512/256'' || 0c833a56046fe7e4213fcb1862c730acf313d1b8f60b51eebf64dc3e79730c1c || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-512256 DXSDK_Aug09.exe.sha2-512256]
|- style="text-align:center;vertical-align:center;"
| colspan="2" | '''MD5''' || 66e5379ecf46b014688779621bcc677c || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.md5 DXSDK_Aug09.exe.md5]
|- style="text-align:center;vertical-align:center;"
| colspan="2" | '''{{nowrap|SHA-1}}''' || 5b9b969ed7b6cf5534bb7350e44c09b3573b0e71 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha1 DXSDK_Aug09.exe.sha1]
|}
CRC32 e9f5c61d ([https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sfv DXSDK_Aug09.exe.sfv]) 

'''NOTE:''' Restart your computer after installing ''Microsoft DirectX SDK'', because otherwise the environment variable '''DXSDK_DIR''' won't be available yet. After restarting it re-run '''create-projects.bat'''

'''Cant find d3dx9.h''' 
Add the '''$(DXSDK_DIR)Include;''' to the VC++ Directories in DirectX9GuiRenderer, GUI and Client Core projects.
You can find the VC++ Directories list by selecting a project, then pressing the shortcut ALT + ENTER (without the +), then under the 'Configuration properties' you can find 'VC++ Directories', and in there you can find the 'Include Directories' field, click on it and add ''';$(DXSDK_DIR)Include;''' at the end of it.
'''Note: You need to do the same thing in Release mode as well'''

'''Cant find d3dx9.lib''' 
Do do same as in the error above, but instead of ''';$(DXSDK_DIR)Include;''' you must add ''';$(DXSDK_DIR)Lib/x86;''' to the '''Library directories''' field
'''Note: You need to do the same thing in Release mode as well'''

'''S1023 Error''' 
[https://support.microsoft.com/en-us/kb/2728613 "S1023" error when you install the DirectX SDK (June 2010)] 

=== Git Client ===
[[File:Git_logo.png|left|32px|link=https://git-scm.com/]]

If you would like to contribute to MTA, you should install Git. This will allow you to collaborate with us by creating branches and pushing to your own fork. If you are not comfortable with the command line, we recommend you to download and install [https://desktop.github.com/ GitHub Desktop].

If you only want to compile the source code and are not interested in contributing to MTA, you can download the source directly (see below).

== Getting the latest source code ==

To get the latest code, you will have to download the latest copy of our Git repository. 
We recommend cloning the repository in your Git client because you can pull any updates from there easily.

* '''Repository:''' [https://github.com/multitheftauto/mtasa-blue multitheftauto/mtasa-blue]
* '''.zip:''' [https://github.com/multitheftauto/mtasa-blue/archive/master.zip master.zip]
* '''.tar.gz:''' [https://github.com/multitheftauto/mtasa-blue/archive/master.tar.gz master.tar.gz]

== Compiling the code ==
# Execute the script '''win-create-projects.bat'''
# Open the solution file '''MTASA.sln''' in the '''Build''' directory
# If you are asked to upgrade the project, click '''Cancel'''
# Compile in Visual Studio with '''Debug''' configuration (may take some minutes)
# Execute the script '''win-install-data.bat'''

= Running the software =

== Running the client ==

You can start your client in the '''Bin''' directory. You might find there a ''Multi Theft Auto.exe'' and/or ''Multi Theft Auto_d.exe'' executable. The ''_d'' suffix indicates a debug build of the software. 
Furthermore, you can also run your client inside the debugger from Visual Studio if you want to investigate a stack trace or set breakpoints in interesting code regions (read more in the section Debugging below).

== Running the dedicated server ==

If you already have run step 5 (''Install resources'') in ''Compiling the code'' to install resources then you can go to ''Starting the server''.

=== Installing the latest resources ===
If you want to run the Multi Theft Auto dedicated server, you will have to install the required resources. These are required because they implement the most basic functionality (e.g. spawning players) in order to play.

Our official resources repository is [https://github.com/multitheftauto/mtasa-resources hosted on GitHub]. You can download the latest resources from there or [http://mirror.mtasa.com/mtasa/resources/ download a zipped version]. Make sure that you have the latest resources package.

=== Starting the server ===
To run the server, open the ''MTA Server.exe'' executable in the '''Bin/server''' directory. The ''_d'' suffix indicates a debug build of the software. 
You can also run the debug build ''MTA Server_d.exe'' with the Visual Studio Debugger (as of writing, you can do that by right-clicking on the Server's Launcher project and selecting ''Start a local instance'' in the ''Debugger'' menu), but you can also attach to a running debug build MTA server (see more in the section Debugging below).

== Debugging ==
If you already compiled the code in the '''Debug''' configuration then continue reading, if not, then go up to ''Compiling the code'' and follow the steps for a ''Debug'' build. 
You can either launch MTA yourself and attach any debugger you want to use (also applies to the Visual Studio debugger) or you start a local debugging session in Visual Studio. 
[[File:Local_Windows_Debugger.PNG]]

=== How to enable breakpoints ===
If you choose to run MTA with Visual Studio then you should also attach the debugger to the executable '''gta_sa.exe''' (press ''CTRL + ALT + P'' in Visual Studio) - otherwise, your
breakpoints will not work for anything besides the MTA Launcher project. 
[[File:Attach_to_Process.png|600px]]

=== Extending timeout duration ===
When you use breakpoints during debugging, you may get kicked by the server due to timeout, because the client is frozen. To prevent this, create the '''timeout.longtime''' file in your ''Bin/server/'' directory.
The content of the file is the new timeout duration in seconds, so make sure you type a huge number in there. If you keep the file empty, the timeout will be set to 120 seconds.

=== ReAttach for Visual Studio ===
You can use [https://marketplace.visualstudio.com/items?itemName=ErlandR.ReAttach ReAttach] to re-attach the debugger to the '''gta_sa.exe''' executable whenever you start your local debugger in Visual Studio. 
[[File:ReAttach_to_GTASA.PNG]]

= Getting involved =
Please see our [[Coding guidelines]] for information on the coding practice.

= Additional information =
If you need more information, try our [http://bugs.mtasa.com/ bug tracker] or [irc://irc.multitheftauto.com IRC channel].

= Errors =
== CL38 error. [netc_d.dll not found] ==
Solution: Delete '''Multi Theft Auto_d.exe''' and hit compile again.

== After cloning the repository, it doesn't compile the project ==
Solution: Execute '''win-create-projects.bat''' in main directory.

== CL17 Load field. Please ensure that the latest data files have been installed correctly ==
Solution: Execute '''win-install-data.bat''' in main directory.

== ERROR: Loading network library (net_d.dll) failed! ==
Solution: Execute '''win-install-data.bat''' in main directory.

[[en:Compiling MTASA]]
[[hu:Compiling MTASA]]
[[pt-br:Compilando o MTASA]]
[[ru:Compiling MTASA]]
[[Category: Development]]

Compiling MTASA

2021-11-15T15:45:49Z

Arran Fortuna: Update based on changes to visual studio installer

In order to successfully build Multi Theft Auto from source, it is necessary to perform a number of steps, which we will explain below.

Please read the instructions carefully and do not skip parts of it, if you have no experience.

== Prerequisites ==

Compiling the Multi Theft Auto client is only supported on Windows 10.

Make sure you have the following software and SDKs installed:

=== Visual Studio 2019 ===
[[File:Visual_Studio_Community.PNG|right|150px|link=https://www.visualstudio.com/vs/]]
# '''[https://visualstudio.microsoft.com/vs/ Download Microsoft Visual Studio 2019]''' - make sure you get the Community Edition, that one is free.
# On the installation checklist, [[:File:VsFoundationClasses.png|make sure you tick these two items]]:
## ''Desktop development with C++''
## ''C++ MFC for latest v143 build tools (x86 & x64)''
## ''MSVC v142 - VS 2019 C++ x64/x86 build tools''

If you don't enable MFC, you will get the following error: <code>cannot open include file 'afxres.h'</code>.

If you've made a mistake, you can run the ''Visual Studio Installer'' app to modify your current installation. There is no need to uninstall and reinstall.

=== Microsoft DirectX SDK ===
[[File:DirectX_SDK.jpg|right|150px|link=http://web.archive.org/web/20200804044856/https://www.microsoft.com/en-us/download/details.aspx?id=23549]]
'''Download Microsoft DirectX SDK (August 2009) (DXSDK_Aug09.exe):'''
* [https://archive.org/download/dxsdk_aug09/DXSDK_Aug09.exe Mirror 1]
* [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe Mirror 2]

{| class="wikitable" style="margin-top: 0px; width: 70%; word-break: break-all;"
|+ File verification
|- style="vertical-align:bottom;"
! colspan="2" | Algorithm and variant
! Hash
! Hash file
|- style="text-align:center;vertical-align:center;"
| rowspan="6" | '''{{nowrap|SHA-3}}''' || ''SHA3-224'' || 8bfcdc03518d7edd34689534fd4d21291469ff2f2eb10437ad648c58 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-224 DXSDK_Aug09.exe.sha3-224]
|- style="text-align:center;vertical-align:center;"
| ''SHA3-256'' || 45bf3e08da3b3636ddb4f4a74243430f8d65759c074c0d79756ef810c4701c5a || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-256 DXSDK_Aug09.exe.sha3-256]
|- style="text-align:center;vertical-align:center;"
| ''SHA3-384'' || b358e529963d6f5fd7f8bd4b530fb18f6a2e6a442009a54e981b2f9967589ed48150af310f283640d56f9b60d41100c9 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-384 DXSDK_Aug09.exe.sha3-384]
|- style="text-align:center;vertical-align:center;"
| ''SHA3-512'' || 43522187053af744250059ef69c0f3083cecd1157fe56daac16b9497ebc6fb5b525875144e42898367c55f757cffd3526f37074d544470578602a5a944a45a75 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-512 DXSDK_Aug09.exe.sha3-512]
|- style="text-align:center;vertical-align:center;"
| ''SHAKE128'' || 2a7c81bde9e867cbb5ef00b72ad8de66a3ee64c1d59f16465fa712479b6a84d28a02cc5ed08afa1d51e72011657453dbd4656cc9340d32e18179c39d03982dfc35c8f0c2a5c99e11dc74d0e23ed21b1e55f19c809a5a152bde39a2d46fcd12421f373f2d691ade1b57faf6c2ab7aded5a7d174f1f1c77127c0d6a1523b4775c569c5e1b4efa2da4bf2f708a96707a709e245a7f507382e69a81777919c90e95a091c0b699ce7f517 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-128000 DXSDK_Aug09.exe.sha3-128000]
|- style="text-align:center;vertical-align:center;"
| ''SHAKE256'' || 9c100dac5245a61774f3a2752bf9e941bdcd5654b18035155161c63b20936dfc9bd7334feb9a6fe9a99a65491161083b39ac3bd578e2cf4f90cba3c786e9924fa0611f65a725331b77b63e7c8b552e1637bc77531ba0f2c9cac72115b28e523929ede4e5b246a0755e8d5c4089d94bf16627fb08672cfffa523bba3d976489a0eec60d3c6a96ca2b || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-256000 DXSDK_Aug09.exe.sha3-256000]
|- style="text-align:center;vertical-align:center;"
| rowspan="6" | '''{{nowrap|SHA-2}}''' || ''SHA-224'' || a3a74b89cccfe314b79418d5598aac5e94800221e5d945c74f15c004 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-224 DXSDK_Aug09.exe.sha2-224]
|- style="text-align:center;vertical-align:center;"
| ''SHA-256'' || 4ab1de69312f10f6b41310a5218d80c478bbd823bc0f86627318d690b128fb9f || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-256 DXSDK_Aug09.exe.sha2-256]
|- style="text-align:center;vertical-align:center;"
| ''SHA-384'' || 254ed29c6ad2cadc6f013d2d51c0ac78a6bbe236a2c94ca99610eba8b2c1200d1a62c445ca9ee51bb09354875d5eca8a || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-384 DXSDK_Aug09.exe.sha2-384]
|- style="text-align:center;vertical-align:center;"
| ''SHA-512'' || style="width: 60%;" | 736393c0dfa32221e229890f87eb330174d70dd2a02fa0cace303816d3e7a10a332a44129748de39665d1b339e627d6028c2080268f7afdd5240c447fec8ff0b || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-512 DXSDK_Aug09.exe.sha2-512]
|- style="text-align:center;vertical-align:center;"
| ''SHA-512/224'' || 7e23d9ba916000782a17e23abf48e25237f45590cfe767aed9d79f10 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-512224 DXSDK_Aug09.exe.sha2-512224]
|- style="text-align:center;vertical-align:center;"
| ''SHA-512/256'' || 0c833a56046fe7e4213fcb1862c730acf313d1b8f60b51eebf64dc3e79730c1c || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-512256 DXSDK_Aug09.exe.sha2-512256]
|- style="text-align:center;vertical-align:center;"
| colspan="2" | '''MD5''' || 66e5379ecf46b014688779621bcc677c || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.md5 DXSDK_Aug09.exe.md5]
|- style="text-align:center;vertical-align:center;"
| colspan="2" | '''{{nowrap|SHA-1}}''' || 5b9b969ed7b6cf5534bb7350e44c09b3573b0e71 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha1 DXSDK_Aug09.exe.sha1]
|}
CRC32 e9f5c61d ([https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sfv DXSDK_Aug09.exe.sfv]) 

'''NOTE:''' Restart your computer after installing ''Microsoft DirectX SDK'', because otherwise the environment variable '''DXSDK_DIR''' won't be available yet. After restarting it re-run '''create-projects.bat'''

'''Cant find d3dx9.h''' 
Add the '''$(DXSDK_DIR)Include;''' to the VC++ Directories in DirectX9GuiRenderer, GUI and Client Core projects.
You can find the VC++ Directories list by selecting a project, then pressing the shortcut ALT + ENTER (without the +), then under the 'Configuration properties' you can find 'VC++ Directories', and in there you can find the 'Include Directories' field, click on it and add ''';$(DXSDK_DIR)Include;''' at the end of it.
'''Note: You need to do the same thing in Release mode as well'''

'''Cant find d3dx9.lib''' 
Do do same as in the error above, but instead of ''';$(DXSDK_DIR)Include;''' you must add ''';$(DXSDK_DIR)Lib/x86;''' to the '''Library directories''' field
'''Note: You need to do the same thing in Release mode as well'''

'''S1023 Error''' 
[https://support.microsoft.com/en-us/kb/2728613 "S1023" error when you install the DirectX SDK (June 2010)] 

=== Git Client ===
[[File:Git_logo.png|left|32px|link=https://git-scm.com/]]

If you would like to contribute to MTA, you should install Git. This will allow you to collaborate with us by creating branches and pushing to your own fork. If you are not comfortable with the command line, we recommend you to download and install [https://desktop.github.com/ GitHub Desktop].

If you only want to compile the source code and are not interested in contributing to MTA, you can download the source directly (see below).

== Getting the latest source code ==

To get the latest code, you will have to download the latest copy of our Git repository. 
We recommend cloning the repository in your Git client because you can pull any updates from there easily.

* '''Repository:''' [https://github.com/multitheftauto/mtasa-blue multitheftauto/mtasa-blue]
* '''.zip:''' [https://github.com/multitheftauto/mtasa-blue/archive/master.zip master.zip]
* '''.tar.gz:''' [https://github.com/multitheftauto/mtasa-blue/archive/master.tar.gz master.tar.gz]

== Compiling the code ==
# Execute the script '''win-create-projects.bat'''
# Open the solution file '''MTASA.sln''' in the '''Build''' directory
# If you are asked to upgrade the project, click '''Cancel'''
# Compile in Visual Studio with '''Debug''' configuration (may take some minutes)
# Execute the script '''win-install-data.bat'''

= Running the software =

== Running the client ==

You can start your client in the '''Bin''' directory. You might find there a ''Multi Theft Auto.exe'' and/or ''Multi Theft Auto_d.exe'' executable. The ''_d'' suffix indicates a debug build of the software. 
Furthermore, you can also run your client inside the debugger from Visual Studio if you want to investigate a stack trace or set breakpoints in interesting code regions (read more in the section Debugging below).

== Running the dedicated server ==

If you already have run step 5 (''Install resources'') in ''Compiling the code'' to install resources then you can go to ''Starting the server''.

=== Installing the latest resources ===
If you want to run the Multi Theft Auto dedicated server, you will have to install the required resources. These are required because they implement the most basic functionality (e.g. spawning players) in order to play.

Our official resources repository is [https://github.com/multitheftauto/mtasa-resources hosted on GitHub]. You can download the latest resources from there or [http://mirror.mtasa.com/mtasa/resources/ download a zipped version]. Make sure that you have the latest resources package.

=== Starting the server ===
To run the server, open the ''MTA Server.exe'' executable in the '''Bin/server''' directory. The ''_d'' suffix indicates a debug build of the software. 
You can also run the debug build ''MTA Server_d.exe'' with the Visual Studio Debugger (as of writing, you can do that by right-clicking on the Server's Launcher project and selecting ''Start a local instance'' in the ''Debugger'' menu), but you can also attach to a running debug build MTA server (see more in the section Debugging below).

== Debugging ==
If you already compiled the code in the '''Debug''' configuration then continue reading, if not, then go up to ''Compiling the code'' and follow the steps for a ''Debug'' build. 
You can either launch MTA yourself and attach any debugger you want to use (also applies to the Visual Studio debugger) or you start a local debugging session in Visual Studio. 
[[File:Local_Windows_Debugger.PNG]]

=== How to enable breakpoints ===
If you choose to run MTA with Visual Studio then you should also attach the debugger to the executable '''gta_sa.exe''' (press ''CTRL + ALT + P'' in Visual Studio) - otherwise, your
breakpoints will not work for anything besides the MTA Launcher project. 
[[File:Attach_to_Process.png|600px]]

=== Extending timeout duration ===
When you use breakpoints during debugging, you may get kicked by the server due to timeout, because the client is frozen. To prevent this, create the '''timeout.longtime''' file in your ''Bin/server/'' directory.
The content of the file is the new timeout duration in seconds, so make sure you type a huge number in there. If you keep the file empty, the timeout will be set to 120 seconds.

=== ReAttach for Visual Studio ===
You can use [https://marketplace.visualstudio.com/items?itemName=ErlandR.ReAttach ReAttach] to re-attach the debugger to the '''gta_sa.exe''' executable whenever you start your local debugger in Visual Studio. 
[[File:ReAttach_to_GTASA.PNG]]

= Getting involved =
Please see our [[Coding guidelines]] for information on the coding practice.

= Additional information =
If you need more information, try our [http://bugs.mtasa.com/ bug tracker] or [irc://irc.multitheftauto.com IRC channel].

= Errors =
== CL38 error. [netc_d.dll not found] ==
Solution: Delete '''Multi Theft Auto_d.exe''' and hit compile again.

== After cloning the repository, it doesn't compile the project ==
Solution: Execute '''win-create-projects.bat''' in main directory.

== CL17 Load field. Please ensure that the latest data files have been installed correctly ==
Solution: Execute '''win-install-data.bat''' in main directory.

[[en:Compiling MTASA]]
[[hu:Compiling MTASA]]
[[pt-br:Compilando o MTASA]]
[[ru:Compiling MTASA]]
[[Category: Development]]

GetPlayerPing

2021-09-15T13:31:48Z

Arran Fortuna: Added clarification that VPN usage won't give incorrect ping (tested)

__NOTOC__
{{Server client function}}
This function returns the ping of a specified [[player]]. The ping is the number of milliseconds that data takes to travel from the player's client to the server or vice versa. If a player is using a VPN their ping will still be returned correctly.

==Syntax==
<syntaxhighlight lang="lua">int getPlayerPing ( player thePlayer )</syntaxhighlight>
{{OOP||[[player]]:getPing|ping|}}
===Required Arguments===
*'''thePlayer''': The [[player]] whose ping you want to determine.

===Returns===
Returns the ping as an [[int]], or ''false'' if the player is invalid.

==Example==
<section name="Server" class="server" show="true">
This example checks every players ping every 5 seconds and if it's over 500 they get kicked.
<syntaxhighlight lang="lua">
function kickPing() -- Creates a function called kickPing
for i, player in ipairs(getElementsByType("player")) do -- Loop every player
if (getPlayerPing(player) >= 500) then -- If their ping is over 500
kickPlayer(player, "Ping over 500!") -- Kick them
end
end
end
setTimer(kickPing, 5000, 0) -- Every 5 seconds, the kickPing function is called.
</syntaxhighlight>
</section>

<section name="Client" class="client" show="true">
This example checks the ping of every player entering the 'ping' command and warns him if it's over 100.
<syntaxhighlight lang="lua">
function checkPing()
local ping = getPlayerPing(localPlayer) -- get the ping from the source element (the player who joined)
if (ping > 100) then -- if it's higher than 100...
outputChatBox("Your ping is pretty high! Please try to lower it if possible.") -- output a message to the player
end
end
addCommandHandler("ping", checkPing)
</syntaxhighlight>
</section>

==See Also==
{{Player functions}}

[[ru:getPlayerPing]]

UnbindKey

2021-07-29T17:42:47Z

Arran Fortuna: Added note about annoying bug that causes an hour lost debugging.

__NOTOC__
{{Server client function}}
Removes an existing key bind from the specified player.
{{Note|unbindKey will only work on binds that were added by the same resource}}
{{Note|unbindKey on the server may return ''true'' on failure}}
{{Note|If you call unbindKey twice, it will break other scripts: [https://github.com/multitheftauto/mtasa-blue/issues/497 Issue 497]}}
==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool unbindKey ( player thePlayer, string key, string keyState, string command )
</syntaxhighlight>
<syntaxhighlight lang="lua">
bool unbindKey ( player thePlayer, string key [, string keyState, function handler ] )
</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The player you wish to unbind the key of.
*'''key:''' The key you wish to unbind. See [[Key names]] for a list of valid key names.
*'''keyState:''' Can be either:
**'''"up":''' If the bound key triggered a function when the key was released
**'''"down":''' If the bound key triggered a function when the key was pressed
**'''"both":''' If the bound key triggered a function when the key was pressed and released
*'''command :''' (Syntax 1) The command you wish to unbind.

===Optional Arguments===
*'''keyState:''' is optional in Syntax 2.
*'''handler:''' (Syntax 2) The function you wish to unbind.
Note: If you do not specify ''handler'', any instances of ''key'' being bound will be unbound, whatever function they are bound to.

===Returns===
Returns '''true'' if the key was unbound, ''false'' if it was not previously bound or invalid arguments were passed to the function.
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool unbindKey ( string key, string keyState, string command )
</syntaxhighlight>
<syntaxhighlight lang="lua">
bool unbindKey ( string key [, string keyState, function handler ] )
</syntaxhighlight>

===Required Arguments===
*'''key:''' The key you wish to unbind. See [[Key names]] for a list of valid key names.
*'''keyState:''' Can be either:
**'''"up":''' If the bound key triggered a function when the key was released
**'''"down":''' If the bound key triggered a function when the key was pressed
**'''"both":''' If the bound key triggered a function when the key was pressed and released
*'''command :''' (Syntax 1) The command you wish to unbind.

===Optional Arguments===
*'''keyState:''' is optional in Syntax 2.
*'''handler:''' (Syntax 2) The function you wish to unbind.
Note: If you do not specify ''handler'', any instances of ''key'' being bound will be unbound, whatever function they are bound to.

===Returns===
Returns '''true'' if the key was unbound, ''false'' if it was not previously bound or invalid arguments were passed to the function.
</section>

==Example==
<section name="Server" class="server" show="true">
This function binds the player's ''F1'' key to a function ''goMoo'' which outputs a chat message when pressed. The key is then unbound so that it can effectively only be used once per life.
<syntaxhighlight lang="lua">
-- define the function that will be called when F1 is pressed
function goMoo( player )
outputChatBox ( getPlayerName ( player ) .. " says Mooooooo!" )
unbindKey ( player, "F1", "down", goMoo ) -- this function will no longer be triggered by the player, after removing the bind.
end

function playerSpawn ( )
bindKey ( source, "F1", "down", goMoo ) -- bind the player's F1 key to the 'goMoo' function defined above
end
addEventHandler ( "onPlayerSpawn", root, playerSpawn ) -- make the playerSpawn function be called when a player spawns
</syntaxhighlight>
</section>

==See Also==
{{Input functions}}

[[pt-br:unbindKey]]

OnClientGUITabSwitched

2021-06-16T17:42:09Z

Arran Fortuna:

{{Client event}}
__NOTOC__
This event is triggered each time the user switch from GUI tab.

When adding the event handler on the tab panel, propagate must be true.

==Parameters==
<syntaxhighlight lang="lua">
element theElement
</syntaxhighlight>
* '''theElement''': the [[Element/GUI/Tab|tab]] which was selected.

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

==Example==
This example creates a window with a tabpanel with two tabs. Every time a user changes tabpage a notification will be shown.

First we'll create the window. Then add a tabpanel and couple tabs with some labels in them. Qoute: [[GuiCreateWindow#Example]]
<syntaxhighlight lang="lua">
local myWindow = guiCreateWindow ( 0, 0, 0.5, 0.4, "Information", true ) -- create a window which has "Information" in the title bar.
local tabPanel = guiCreateTabPanel ( 0, 0.1, 1, 1, true, myWindow ) -- create a tab panel which fills the whole window
local tabMap = guiCreateTab( "Map Information", tabPanel ) -- create a tab named "Map Information" on 'tabPanel'
local tabHelp = guiCreateTab( "Help", tabPanel ) -- create another tab named "Help" on 'tabPanel'

-- adds a label (text) to each tab
guiCreateLabel( 0.02, 0.04, 0.94, 0.2, "This is information about the current map", true, tabMap )
guiCreateLabel( 0.02, 0.04, 0.94, 0.92, "This is help text.", true, tabHelp )
</syntaxhighlight>

Now let's add the event handler.
<syntaxhighlight lang="lua">

function OnChange(selectedTab)
-- If there is a selected tab.
if selectedTab ~= nil then
outputChatBox( "You've changed your active tab." )
end
end

addEventHandler("onClientGUITabSwitched", root, OnChange)
</syntaxhighlight>

==See Also==
{{GUI_events}}
===Client event functions===
{{Client_event_functions}}

CreateColPolygon

2021-01-27T09:53:31Z

Arran Fortuna:

__NOTOC__
{{Server client function}}
{{Note|For this function to work correctly, get/set your bound points in an anti-clockwise fashion.}}
{{Note|Even though this is a 2D colshape, [[isElementWithinColShape]] returns false if an element is in the area but below 0 Z height.}}
This function creates a collision polygon. See [http://en.wikipedia.org/wiki/Polygon Wikipedia] for a definition of a polygon. The first set of X Y of this shape is not part of the colshape bounds, so can set anywhere in the game world, however for performance, place it as close to the centre of the polygon as you can. It should be noted this shape is '''2D'''. There should be at least 3 bound points set.
{{VisualizeColshape}}
==Syntax==
<syntaxhighlight lang="lua">
colshape createColPolygon ( float fCenterX, float fCenterY, float fX1, float fY1, float fX2, float fY2, float fX3, float fY3, ... )
</syntaxhighlight>
{{OOP| |ColShape.Polygon||}}
===Required Arguments===
*'''fCenterX:''' The X position of the collision polygon's position - the position that will be returned from [[getElementPosition]].
*'''fCenterY:''' The Y position of the collision polygon's position - the position that will be returned from [[getElementPosition]].
*'''fX1:''' The 1st X position of the collision polygon's bound point
*'''fY1:''' The 1st Y position of the collision polygon's bound point
*'''fX2:''' The 2nd X position of the collision polygon's bound point
*'''fY2:''' The 2nd Y position of the collision polygon's bound point
*'''fX3:''' The 3rd X position of the collision polygon's bound point
*'''fY3:''' The 3rd Y position of the collision polygon's bound point
*'''... :''' From the 3rd position you can have as many points as you require to create the colshape.

===Returns===
Returns a [[colshape]] element if successful, ''false'' if invalid arguments were passed to the function.

==Example==
<section name="Server" class="server" show="true">
This example displays a chat message when any element hits the colshape and allows the colshape to be created using a console function ''set_zone''.
<syntaxhighlight lang="lua">
local theZone = false

function shapeHit( element )
local descriptor = "undefined"

if getElementType( element ) == "player" then
-- Use the player's name
descriptor = getPlayerName( element )
elseif getElementType( element ) == "vehicle" then
-- Use the vehicle's model name
descriptor = getVehicleName( element ) or descriptor
end

-- Output a message in the chat box for everyone on the server
outputChatBox( descriptor .. " is in the zone!" )
end

function createZoneCommandHandler( playerSource, commandName, fX, fY, fX1, fY1, fX2, fY2, fX3, fY3, ... )
-- Verify the player has given us the minimum amount of bound points
if not ( fY and fX and fX1 and fY1 and fX2 and fX3 and fY3 ) then
return outputChatBox( "Syntax: set_zone <X> <Y> <X1> <Y1> <X2> <Y2> <X3> <Y3> [<Xn> <Yn> ...]", playerSource, 255, 100, 100 )
end

-- Create the collision shape with the numbers from the arguments
local tempCol = createColPolygon( fX, fY, fX1, fY1, fX2, fY2, fX3, fY3, ... )

if not tempCol then
return outputChatBox( "Error: Couldn't create collision polygon", playerSource, 255, 100, 100 )
end

-- Destroy the previous collision polygon shape in case we already have one
if isElement( theZone ) then
destroyElement( theZone )
end

-- Use a variable out-of-scope to keep track of the most recently created collision shape element
theZone = tempCol

-- Attach an event handler to the element to get notified whenever an element hits our collision shape
addEventHandler( "onColShapeHit", tempCol, shapeHit, false )

outputChatBox( "Success: Collision shape has been created!", playerSource, 100, 255, 100 )
end
addCommandHandler( "set_zone", createZoneCommandHandler )
</syntaxhighlight>
</section>
<section name="Server" class="server" show="hide">
This example displays a chat message when any element hits the colshape and allows the colshape to be created using a console function ''set_wall''.
<syntaxhighlight lang="lua">
local theWall = false

function shapeHit( element )
local descriptor = "undefined"

if getElementType( element ) == "player" then
-- Use the player's name
descriptor = getPlayerName( element )
elseif getElementType( element ) == "vehicle" then
-- Use the vehicle's model name
descriptor = getVehicleName( element ) or descriptor
end

-- Output a message in the chat box for everyone on the server
outputChatBox( descriptor .. " is in the zone!" )
end

function createWallCommandHandler( playerSource, commandName, fromX, fromY, toX, toY )
-- Verify the player has given us the minimum amount of bound points
if not ( fromX and fromY and toX and toY ) then
return outputChatBox( "Syntax: set_wall <fromX> <fromY> <toX> <toY>", playerSource, 255, 100, 100 )
end

-- Calculate the 90° angle for the line between the two coordinates from the arguments
local radian90DegreeAngle = math.atan2(toY - fromY, toX - fromX) + math.pi / 2

-- Depth/width of the wall
local depth = 1

-- Pre-calculate the cosinus/sinus distances
local cosinusDepth = math.cos(radian90DegreeAngle) * depth / 2
local sinusDepth = math.sin(radian90DegreeAngle) * depth / 2

-- Calculate the points in the game world
local x1, y1 = fromX - cosinusDepth, fromY - sinusDepth
local x2, y2 = toX - cosinusDepth, toY - sinusDepth
local x3, y3 = toX + cosinusDepth, toY + sinusDepth
local x4, y4 = fromX + cosinusDepth, fromY + sinusDepth

-- Create the collision shape with the calculated numbers
local tempCol = createColPolygon( fromX + (toX - fromX) / 2, fromY + (toY - fromY) / 2, x1, y1, x2, y2, x3, y3, x4, y4 )

if not tempCol then
return outputChatBox( "Error: Couldn't create collision polygon", playerSource, 255, 100, 100 )
end

-- Destroy the previous collision polygon shape in case we already have one
if isElement( theWall ) then
destroyElement( theWall )
end

-- Use a variable out-of-scope to keep track of the most recently created collision shape element
theWall = tempCol

-- Attach an event handler to the element to get notified whenever an element hits our collision shape
addEventHandler( "onColShapeHit", tempCol, shapeHit, false )

outputChatBox( "Success: Collision shape has been created!", playerSource, 100, 255, 100 )
end
addCommandHandler( "set_wall", createWallCommandHandler )
</syntaxhighlight>
</section>

==Issues==
{{Issues|
{{Issue|9742|[Fixed in 1.5.5-3.12343] Passing this function [[Vector2|Vector2s]] are not fully supported}}
}}

==See Also==
{{Collision shape functions}}

[[hu:createColPolygon]]

PlaySoundFrontEnd

2021-01-08T20:10:31Z

Arran Fortuna:

{{Server client function}}
__NOTOC__
This function plays a frontend sound for the specified player.
{{Note|These sounds can be disabled with [[setWorldSoundEnabled]] so if these sounds stop working you should check if you're disabling the sounds.}}
{{Note|These sounds don't work when [[fadeCamera]] has been used to make the screen black.}}

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool playSoundFrontEnd ( player thePlayer, int sound )
</syntaxhighlight>
{{New feature/item|3.0141|1.4.0|6987|{{OOP||[[player]]:playSoundFrontEnd}}}}

===Required Arguments===
*'''thePlayer:''' the [[player]] you want the sound to play for.
*'''sound:''' a whole [[int]] specifying the sound id to play. Valid values are:
{{Sounds}}
</section>
<section name="Client" class="client" show="false">
<syntaxhighlight lang="lua">
bool playSoundFrontEnd ( int sound )
</syntaxhighlight>
{{New feature/item|3.0141|1.4.0|6987|{{OOP||[[Sound]].playFrontEnd}}}}

===Required Arguments===
*'''sound:''' a whole [[int]] specifying the sound id to play. Valid values are:
{{Sounds}}
</section>

===Returns===
Returns ''true'' if the sound was successfully played, ''false'' otherwise.

==Example==
<section name="server" class="server" show="true">
This example plays a sound when a player spawns.
<syntaxhighlight lang="lua">
function onPlayerSpawn ( theSpawnpoint, theTeam )
playSoundFrontEnd ( source, 16 )
end
addEventHandler ( "onPlayerSpawn", root, onPlayerSpawn )
</syntaxhighlight>
</section>
<section name="client" class="client" show="true">
This example plays a sound when the player types the command '/sound'.
<syntaxhighlight lang="lua">
function onSoundEvent ( )
playSoundFrontEnd ( 16 )
end
addCommandHandler("sound", onSoundEvent)
</syntaxhighlight>
</section>

==See Also==
{{Client_audio_functions}}

[[hu:playSoundFrontEnd]]
[[de:playSoundFrontEnd]]
[[ar:playSoundFrontEnd]]

FileExists

2020-12-20T19:05:53Z

Arran Fortuna:

__NOTOC__
{{Server client function}}
This functions checks whether a specified file exists inside a resource.

==Syntax==
<syntaxhighlight lang="lua">
bool fileExists ( string filePath )
</syntaxhighlight>
{{OOP|This function is a static function underneath the File class.|[[File]].exists}}
===Required Arguments===
*'''filePath:''' The [[filepath]] of the file, whose existence is going to be checked, in the following format: '''":resourceName/path"'''. 'resourceName' is the name of the resource the file is checked to be in, and 'path' is the path from the root directory of the resource to the file.
:For example, if you want to check whether a file named 'myfile.txt' exists in the resource 'mapcreator', it can be done from another resource this way: ''fileExists(":mapcreator/myfile.txt")''.
:If the file, whose existence is going to be checked, is in the current resource, only the file path is necessary, e.g. ''fileExists("myfile.txt")''. Note that you must use forward slashes '/' for the folders, backslashes '\' will return false.

===Returns===
Returns ''true'' if the file exists, ''false'' otherwise.

==Example==
This example checks if a file exists in a resource directory
<syntaxhighlight lang="lua">
function checkExistingFile(player,cmd,filename,resourcename)
if not filename then -- if the player didn't include a filename
outputChatBox("ERROR: Syntax '/checkfile filename resourcename(optional)'.",player) -- display error
return false -- stop function
end
if not resourcename then -- if the player didn't specify the resource he wants to check, use current resource
resourcename = getResourceName(resource) --every resource has a predefined global variable called resource that contains the resource pointer for that resource, in other words, the value that getThisResource() function returns.
else
if not getResourceFromName(resourcename) then -- if a resource with that name doesn't exist, output error and stop function
outputChatBox("ERROR: Resource "..resourcename.." doesn't exist.",player) -- output error message
return false -- stop the function here
end
end
-- as it hasn't stopped anywhere, we have both correct resourcename and filename
local exists = fileExists((":%s/%s"):format(resourcename,filename)) -- using shorter format of string.format, see StringLibraryTutorial in lua wiki for that
if exists then
outputChatBox(("The file %q in resource %q exists"):format(filename,resourcename))
else
outputChatBox(("The file %q in resource %q doesn't exist"):format(filename,resourcename))
end
end
addCommandHandler("exists",checkExistingFile)
</syntaxhighlight>

==See Also==
{{File functions}}

OnClientPlayerVehicleEnter

2020-07-21T20:08:50Z

Arran Fortuna: Fixed example

{{Client event}}
__NOTOC__
This event is fired when a player or ped enters a vehicle.

==Parameters==
<syntaxhighlight lang="lua">
vehicle theVehicle, int seat
</syntaxhighlight>
*'''theVehicle:''' the [[vehicle]] that the player entered
*'''seat:''' the seat that the player now is on. Driver's seat = 0, higher numbers are passenger seats.

==Source==
The [[event system#Event source|source]] of this event is the [[player]] or [[ped]] that entered the vehicle.

==Example==
This example will tell you the name of the vehicle you enter.
<syntaxhighlight lang="lua">
function checkVehicles(theVehicle)
outputChatBox("You entered a "..getVehicleName(theVehicle).."!")
end
addEventHandler("onClientPlayerVehicleEnter", localPlayer, checkVehicles)
</syntaxhighlight>

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