Multi Theft Auto: Wiki - User contributions [en]

EngineSetModelLODDistance

2025-02-03T19:23:22Z

Zangomangu: fixed distance

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

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

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

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

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

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

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

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

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

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

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

==Example==
<syntaxhighlight lang="lua">
-- Cause massive lag by maxing out draw distance of all objects

local objectsTable = getElementsByType("object")

for i = 1, #objectsTable do
local objectElement = objectsTable[i]
local objectModel = getElementModel(objectElement)

engineSetModelLODDistance(objectModel, 325) -- Set maximum draw distance
end
</syntaxhighlight>

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

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

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

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

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

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

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

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

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

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

setLowLODElement(building,lod)
end
</syntaxhighlight>

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

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

EngineSetModelLODDistance

2025-02-02T14:26:09Z

Zangomangu: Added notes on object/building lod difference

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

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

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

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

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

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

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

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

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

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

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

==Example==
<syntaxhighlight lang="lua">
-- Cause massive lag by maxing out draw distance of all objects

local objectsTable = getElementsByType("object")

for i = 1, #objectsTable do
local objectElement = objectsTable[i]
local objectModel = getElementModel(objectElement)

engineSetModelLODDistance(objectModel, 300) -- Set maximum draw distance
end
</syntaxhighlight>

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

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

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

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

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

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

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

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

Template:Projectiles

2023-11-14T22:50:13Z

Zangomangu: Moved note on hydra flare to createProjectile

{| class="wikitable" style="width: auto; text-align: center; table-layout: fixed;"
|-
!ID
!Name/Description
|-
|'''16'''
|Grenade
|-
|'''17'''
|Tear Gas Grenade
|-
|'''18'''
|Molotov
|-
|'''19'''
|Rocket (simple)
|-
|'''20'''
|Rocket (heat seeking)
|-
|'''21'''
|Air Bomb
|-
|'''39'''
|Satchel Charge
|-
|'''58'''
|Hydra flare
|-
|}

CreateProjectile

2023-11-14T22:50:00Z

Zangomangu: Moved note on hydra flare

__NOTOC__
{{Client function}}
This function creates a projectile of the specified type on the specified coordinates.

{{Note|
*'''Model''' argument is not synchronized between clients. Clients differs from local player see always standard projectile model.
*'''Target''' argument can only be defined as a player or another projectile.
}}

==Syntax==
<syntaxhighlight lang="lua">
projectile createProjectile ( element creator, int weaponType [, float posX, float posY, float posZ, float force = 1.0, element target = nil, float rotX, float rotY, float rotZ, float velX, float velY, float velZ, int model ] )
</syntaxhighlight>
{{OOP||[[Projectile]]}}

===Required Arguments===
*'''creator:''' The [[element]] representing creator of the projectile. In case you want the projectile to be synced for everybody creator must be the local player or his vehicle.
*'''weaponType:''' [[int]] representing the projectile weaponType (characteristics). Valid IDs are:
{{Projectiles}}

'''Note''': ID 58 doesn't work <ref>https://github.com/multitheftauto/mtasa-blue/issues/1927</ref>

===Optional Arguments===
{{OptionalArg}}
*'''posX''', '''posY''', '''posZ''': [[float]] starting coordinates for the projectile. They are coordinates of creator by default.
*'''force''': [[float]] representing the starting force for throwable projectiles.
*'''target''': [[element]] target used for heat seeking rockets.
*'''rotX''', '''rotY''', '''rotZ''': [[float]] starting rotation for the projectile.
*'''velX''', '''velY''', '''velZ''': [[float]] starting velocity for the projectile.
*'''model''': Integer representing the projectile's model, uses default model for weaponType if not specified.

==Returns==
Returns a ''[[projectile]]'' element if [[projectile]] creation was successful. Returns ''false'' if unable to create a [[projectile]] (wrong weapon ID or projectiles limit was reached).

==Example==
This example makes a rocket minigun (minigun shooting with rockets).
<syntaxhighlight lang="lua">
-- This function gets triggered everytime player shoots.
function onClientPlayerWeaponFireFunc(weapon,ammo,ammoInClip,hitX,hitY,hitZ,hitElement)
if weapon == 38 then -- if source is a local player and he uses minigun...
x,y,z = getElementPosition(localPlayer)
if not createProjectile(localPlayer,19,x,y,z,200) then -- then we either create a projectile...
outputChatBox ( "Rocket minigun overheated! Give it a rest pal!", source ) -- or if projectile limit is reached we output player a chat message
end
end
end

-- Don't forget to add the onClientPlayerWeaponFireFunc function as a handler for onClientPlayerWeaponFire.
addEventHandler("onClientPlayerWeaponFire", localPlayer, onClientPlayerWeaponFireFunc)
</syntaxhighlight>

This example code shoots a projectile from your occupied vehicle that travels in the direction your vehicle is facing when you press vehicle_fire (left mouse button with default controls)
<syntaxhighlight lang="lua">

function shootProjectile()
local vehicle = getPedOccupiedVehicle(localPlayer)
-- Only create projectile if we are inside a vehicle
if(vehicle)then
local x, y, z = getElementPosition(vehicle)
createProjectile(vehicle, 19, x, y, z)
end
end

bindKey("vehicle_fire", "down", shootProjectile)
</syntaxhighlight>

==Issues==
{{Issues|
{{Issue|584|createProjectile creates one projectile for every person in the vehicle}}
{{Issue|616|Projectile rotation is set exactly opposite for creator}}
}}

==See also==
{{Client projectile functions}}

[[it:createProjectile]]

Template:Player events

2023-11-14T22:47:32Z

Zangomangu: added two events

<ul>
<li>[[onPlayerACInfo]]</li>
<li>[[onPlayerBan]]</li>
<li>[[onPlayerChangeNick]]</li>
<li>[[onPlayerChat]]</li>
<li>[[onPlayerClick]]</li>
<li>[[onPlayerCommand]]</li>
<li>[[onPlayerConnect]]</li>
<li>[[onPlayerContact]]</li>
<li>[[onPlayerDamage]]</li>
{{Added feature/item|1.6.1|1.6.0|22293|
<li>[[onPlayerDetonateSatchels]]</li>
}}
<li>[[onPlayerJoin]]</li>
<li>[[onPlayerLogin]]</li>
<li>[[onPlayerLogout]]</li>
<li>[[onPlayerMarkerHit]]</li>
<li>[[onPlayerMarkerLeave]]</li>
<li>[[onPlayerModInfo]]</li>
<li>[[onPlayerMute]]</li>
<li>[[onPlayerNetworkStatus]]</li>
<li>[[onPlayerPickupHit]]</li>
{{New items|3.0156|1.5.5|
<li>[[onPlayerPickupLeave]]</li>
|11783}}
<li>[[onPlayerPickupUse]]</li>
<li>[[onPlayerPrivateMessage]]</li>
{{Added feature/item|1.6.1|1.6.0|22293|
<li>[[onPlayerProjectileCreation]]</li>
}}
<li>[[onPlayerQuit]]</li>
<li>[[onPlayerScreenShot]]</li>
<li>[[onPlayerSpawn]]</li>
<li>[[onPlayerStealthKill]]</li>
<li>[[onPlayerTarget]]</li>
<li>[[onPlayerUnmute]]</li>
<li>[[onPlayerVehicleEnter]]</li>
<li>[[onPlayerVehicleExit]]</li>
<li>[[onPlayerVoiceStart]]</li>
<li>[[onPlayerVoiceStop]]</li>
<li>[[onPlayerWasted]]</li>
<li>[[onPlayerWeaponFire]]</li>
<li>[[onPlayerWeaponSwitch]]</li>
</ul>

<noinclude>[[Category:Events templates]]</noinclude>

OnPlayerDetonateSatchels

2023-11-14T22:43:24Z

Zangomangu: Created page with "__NOTOC__ {{Server event}} {{Added feature/item|1.6.1|1.6.0|22293|This event is triggered every time satchels are detonated - either by a player or through detonateSatchels.}} ==Parameters== No parameters. ==Source== The source of this event is the player whose satchels are being detonated. ===Canceling=== If this event is canceled, the satchels will not detonate. ==Example== <syntaxhighlight lang="..."

__NOTOC__
{{Server event}}
{{Added feature/item|1.6.1|1.6.0|22293|This event is triggered every time satchels are detonated - either by a [[player]] or through [[detonateSatchels]].}}
==Parameters==
No parameters.

==Source==
The [[event system#Event source|source]] of this event is the [[player]] whose satchels are being detonated.

===Canceling===
If this event is [[Event system #Canceling|canceled]], the satchels will not detonate.

==Example==
<syntaxhighlight lang="lua">

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

OnPlayerProjectileCreation

2023-11-14T22:35:22Z

Zangomangu: Created page with "__NOTOC__ {{Server event}} {{Added feature/item|1.6.1|1.6.0|22293|This event is triggered every time a projectile is created by a player - either through a weapon, a vehicle weapon or createProjectile.}} ==Parameters== <syntaxhighlight lang="lua"> int weaponType, float x, float y, float z, float force, element target, float rotX, float rotY, float rotZ, float velX, float velY, float velZ </syntaxhighlight> *'''weaponType:''' ID, see below {{Projectiles}} *'''x:''..."

__NOTOC__
{{Server event}}
{{Added feature/item|1.6.1|1.6.0|22293|This event is triggered every time a projectile is created by a [[player]] - either through a weapon, a vehicle weapon or [[createProjectile]].}}
==Parameters==
<syntaxhighlight lang="lua">
int weaponType, float x, float y, float z, float force, element target, float rotX, float rotY, float rotZ, float velX, float velY, float velZ
</syntaxhighlight>
*'''weaponType:''' ID, see below
{{Projectiles}}
*'''x:''' X coordinate of where the projectile was created
*'''y:''' Y coordinate of where the projectile was created
*'''z:''' Z coordinate of where the projectile was created
*'''force:''' force of thrown projectile. Valid for ID 16, 17, 18, 39.
*'''target:''' [[element]] the projectile is targeting. Valid for ID 19, 20.
*'''rotX:''' X rotation. Valid for ID 19, 20.
*'''rotY:''' Y rotation. Valid for ID 19, 20.
*'''rotZ:''' Z rotation. Valid for ID 19, 20.
*'''velX:''' X axis velocity. Valid for ID 16, 17, 18, 19, 20, 39.
*'''velY:''' Y axis velocity. Valid for ID 16, 17, 18, 19, 20, 39.
*'''velZ:''' Z axis velocity. Valid for ID 16, 17, 18, 19, 20, 39.

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

===Canceling===
If this event is [[Event system #Canceling|canceled]], the projectile will not be created for other players on the server.

==Example==
<syntaxhighlight lang="lua">

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

SetWaterLevel

2023-10-22T23:09:09Z

Zangomangu: remove deprecated syntax

__NOTOC__
{{Server client function}}

Sets the height of some or all the water in the game world.
{{Note|When the water level is 0, the standard GTA rendering is performed so that water is visible when viewed through translucent surfaces, such as vehicle windows. However, some MTA custom objects placed underwater will appear in front of the water. Setting the water level to any non-zero value (i.e. setWaterLevel(0.001) ) forces alternative rendering and MTA custom objects placed underwater will be drawn correctly.}}
==Syntax==
<syntaxhighlight lang="lua">
bool setWaterLevel ( [ water theWater, ] float level )
</syntaxhighlight>

{{Added feature/item|1.5.9|1.5.8|20716|
<syntaxhighlight lang="lua">
bool setWaterLevel ( float level [, bool includeWaterFeatures = true, bool includeWaterElements = true, bool includeWorldSea = true, bool includeOutsideWorldSea = false ] )
</syntaxhighlight>
}}

{{OOP||[[water]]:setLevel|level|getWaterLevel}}

===Required Arguments===
*'''level:''' the new Z coordinate of the water surface. All water in the game world is set to this height.

===Optional Arguments===
*'''theWater:''' the water element to change.

''or:''
{{New feature/item|3.0120|1.2||
*'''includeWaterFeatures :''' a boolean indicating whether to also set the level of water features such as ponds and pools.
*'''includeWaterElements :''' a boolean indicating whether to also set the level of all water elements.
{{Added feature/item|1.5.9|1.5.8|20716|
*'''includeWorldSea :''' a boolean indicating whether to set the level of the sea water
*'''includeOutsideWorldSea:''' a boolean indicating whether to also set the level of sea water outside the world area, ie. outside -3000, 3000.
}}
}}

===Returns===
Returns ''true'' if successful, ''false'' in case of failure.

== Alternate client-only syntax ==
<section name="Client only" class="client" show="true">
<syntaxhighlight lang="lua">bool setWaterLevel ( [float x, float y, float z,] float level )</syntaxhighlight>
===Required Arguments===
*'''level:''' the new Z coordinate of the water surface
===Optional Arguments===
The area of water containing that point or corresponding to that water element is changed.

*'''x:''' the X coordinate of the point indicating the water area to change.
*'''y:''' the Y coordinate of the point indicating the water area to change.
*'''z:''' the Z coordinate of the point indicating the water area to change. This parameter is reserved and is currently ignored, set it to 0.

===Returns===
Returns ''true'' if successful, ''false'' in case of failure (there is no water at the specified coordinates).
</section>

==Example==
<section name="Client" class="client" show="true">
This example code will slowly drain away all rivers and seas.
<syntaxhighlight lang="lua">
local level = 0

function drainSomeWater()
level = level - 0.01
setWaterLevel ( level )
end
setTimer ( drainSomeWater, 100, 15000 )
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
This example code will slowly drain away all rivers and seas.
<syntaxhighlight lang="lua">
local level = 0

function drainSomeWater()
level = level - 0.01
setWaterLevel ( level )
end
setTimer ( drainSomeWater, 100, 15000 )
</syntaxhighlight>

This example code adds a command ''water'' which can be used to change the current water level.
<syntaxhighlight lang="lua">
addCommandHandler ( "water",
function ( thePlayer, command, level )
if level and tonumber ( level ) then -- if we have input something and if it is actually a number value
setWaterLevel ( tonumber( level ) ) -- change the water level
outputChatBox ( "Waterlevel is now: " .. level ) -- send a message to everyone to inform about the change
end
end
)
</syntaxhighlight>
</section>

==See Also==
{{Client water functions}}

Resource:Editor

2023-10-06T18:31:57Z

Zangomangu:

{{Resource page}}
The MTA:SA map editor allows you to create maps for gamemodes.

==Starting==
To start the editor, simply click the "Map editor" menu item in the main MTA menu.

==Menus==
Once the editor has started, you are presented with two menu bars: the main menu at the top, and the element menu in the lower left.

===Main menu===
These are the buttons in the main menu:
* [[Image:Editor_New.png]] Create a new map.
* [[Image:Editor_Open.png]] Open an existing map.
* [[Image:Editor_Save.png]] Save the map you're working on.
* [[Image:Editor_Save_as.png]] Save your map under a different name.
* [[Image:Editor_Options.png]] Alter general map editor settings.
* [[Image:Editor_Undo.png]] Undo the last action.
* [[Image:Editor_Redo.png]] Restore the last undone action.
* [[Image:Editor_Locations.png]] Stored game world locations. The editor comes with a great list of San Andreas Interior locations but you can also add your own interior and non-interior locations to the list.
* [[Image:Editor_Current_elements.png]] List all the elements the map contains (objects, vehicles, markers, pickups etc.)
* [[Image:Editor_Map_settings.png]] Map specific settings, like time of day, gravity etc. Here you can also specify what gamemodes the map is compatible with.
* [[Image:Editor_Definitions.png]] Load [[Resource:Editor/EDF|editor definition files (EDF)]] that you want to use.
* [[Image:Editor_Test.png]] Go into play mode to try out the map. This will load up the gamemode the map is made for.

===Element menu===
The element menu is used to add new elements to the map.
* [[Image:Editor_Vehicle.png]] Create a new vehicle.
* [[Image:Editor_Object.png]] Create a new object (buildings, roads and other scenery).
* [[Image:Editor_Pickup.png]] Create a new pickup (health, armor, weapons and custom).
* [[Image:Editor_Marker.png]] Create a new marker (checkpoint, ring, cylinder, arrow and corona).
* [[File:Crosshair.png‎]] Select world object.
* [[Image:Editor_WorldObjectRemover.png]] Delete world object.
Additionally, if you have [[Resource:Editor/EDF|editor definitions loaded]], you can roll the mousewheel in this menu to bring up custom elements.

==Using the editor==
This section explains how to create and modify maps.

===Moving around the map===
When you initially start the editor, you are in ''camera mode''. You are able to use the '''WASD''' keys to move the camera and the mouse to pan the camera. While moving around, you can hold '''ALT''' to move more slowly or '''SHIFT''' to go faster.

To access the editor's interface and control panel you need to switch to ''cursor mode''. You can toggle between cursor mode and camera mode with the '''F''' key. When in cursor mode, your view is fixed, and you can use the mouse cursor to manipulate elements and use the graphical interface.

Camera mode can be recognized by a crosshair in the center of the screen. You can use it to select and move elements just like in cursor mode.

[[Image:Editor_Crosshair.png|center]]

===Starting a new map===
* Start the editor, or if it is already started, click the ''New'' menu button.
* Click the ''Map settings'' button. In the ''Meta'' tab, fill in the Name and Author fields with the name of the map and your name respectively. Also open the ''Gamemodes'' tab and add the gamemodes your map is meant for (they will be moved to the ''Added gamemodes'' list). You can do this by selecting them and clicking ''Add'', or by double clicking them. Click OK when you're done.
[[Image:Editor_Mapsettings.png|center]]
* Click the ''Definitions'' window and add the resources of which you want to use the custom elements. These will consist of the gamemodes you selected in the ''Map settings'' window, plus eventual additional resources. For more information about editor definitions, see [[Resource:Editor/EDF|EDF]]. Click OK when you're done.

===Creating new elements===
Adding elements to your map, such as vehicles and objects, is very straightforward.
* If you are in camera mode, switch to cursor mode first by pressing '''F'''.
* Click the button in the element menu that represents what you want. E.g., click the button with a car on it to add a vehicle.
* A new element of the selected type will be created and attached to your cursor. Move it to the location where you want it and '''left click''' to drop it off.

[[Image:Editor_Addelem.png|center]]

To create custom elements that are specific to a resource, hover the cursor over the element menu and turn the scroll wheel until the desired resource comes up. Note that for this to work, you first have to add the [[Resource:Editor/EDF|EDF]] file of the resource in the ''Definitions'' window.

[[Image:Editor_Selectedf.png|center]]

===Selecting===
* '''Left click''' an element to select it in ''keyboard mode''.
* '''Right click''' it to select it in ''mouse mode''.
* Press the '''Spacebar''' or click in an empty area to deselect.

The selected element, if any, is denoted by a yellow cone marker. Elements (particularly objects) with poor collisions can be detected easier by enabling ''High sensitivity mode'', by pressing the '''E''' key. This increases detection at the expense of accuracy.

The ''Current elements'' dialog can also be used to select elements. Double-clicking an item within the list will select it in ''Keyboard mode''.

===Moving===
Moving elements can be done in several ways.

'''With the mouse'''
* Simply drag and drop with the '''left mouse button'''.
Or:
* Select the element in mouse mode ('''right click'''), move it to where you want it, and click to drop it off.

You can also adjust the ''Hold distance'' of an element toward and away from the camera by switching to camera mode, '''right clicking''' the element, and rolling the '''mouse wheel'''.

'''With the keyboard'''
* Select the element in keyboard mode ('''left click''').
* Use the '''arrow keys''' to move the element in the horizontal plane, and '''PgUp'''/'''PgDn''' to move it vertically. Hold '''ALT''' to decrease the movement speed, or '''SHIFT''' to increase it.

By default, elements move relative to the camera and are not locked to any axes. This can be disabled in the ''Options'' menu.

===Rotating===
'''With the mouse'''

You can rotate selected elements around the Z axis with the mouse wheel.
* Select the element in keyboard mode ('''left click''') and roll the mouse wheel while holding '''Left CTRL'''.
Or:
* Select the element in mouse mode ('''right click'''), hold '''CTRL''', and roll the mouse wheel.

'''With the keyboard'''
* Select the element in keyboard mode ('''left click''').
* While holding '''CTRL''' (the selection marker will turn green), use the '''arrow keys''' and '''PgUp'''/'''PgDn''' to rotate the element around the different axes.

With both methods you can additionally hold '''ALT''' to decrease the rotation speed or '''SHIFT''' to increase it.

[[Image:Editor_Rotateelem.png|center]]

===Changing model and other properties===
Most elements have a variety of options that can be altered to change their appearance and behaviour. Examples are the model, color and visual upgrades of a car.

* Open the properties window of an element by either double clicking it or by selecting it and pressing '''F3'''.
* Make any alterations that you want. For example, to change the model of a car or object, click the '''Browse''' button next to "model" to open the model browser.
* Click OK when you're done.

[[Image:Editor_Props.png|center]]

===Cloning===
You can clone an element by selecting it and pressing '''C'''.

* In mouse mode the cloned element will be attached to your cursor. '''Left click''' to place it in the map.
* In keyboard mode the cloned element will be cloned in the identical position.

If you hold '''CTRL''' while clicking, the element will be cloned again and will again be attached to the cursor. This way you can easily place large quantities of something.

Alternatively you can use the ''Pullout'' button located in the bottom-right corner of the properties box to clone an element.

===Deleting===
Simply select the element and press '''DEL''' ''(Delete)''.

Alternatively you can use the ''Pullout'' button located in the bottom-right corner of the properties box to delete an element.

==Creating maps for specific gamemodes==
To make a map for a specific gamemode, you have to do two things:
* Click the '''Map Settings''' button in the top menu, go to the '''Gamemodes''' tab and add any gamemodes that your map is to be used with.
* You will likely also need to add one or more [[Resource:Editor/EDF|Editor Definition Files]]. These will allow you to place gamemode specific elements in the map, like spawnpoints, race checkpoints, or CTF flags. You can add EDF's by clicking the '''Definitions''' menu button and adding the relevant gamemodes.

==Controls==
Here is a list of all default controls. To change them please go to the MTA Settings menu while the Editor is started.

===Camera===
{|
|-
| camera_move_forwards
| '''w'''
|-
| camera_move_backwards
| '''s'''
|-
| camera_move_left
| '''a'''
|-
| camera_move_right
| '''d'''
|-
| high_sensitivity_mode
| '''e'''
|}

===Cloning===
{|
|-
| clone_selected_element
| '''c'''
|-
| clone_drop_modifier
| '''lctrl''' || ''(Left CTRL)''
|}

===Element manipulation===
{|
|-
| element_move_forward
| '''arrow_u''' || ''(Arrow key Up)''
|-
| element_move_backward
| '''arrow_d''' || ''(Arrow key Down)''
|-
| element_move_left
| '''arrow_l''' || ''(Arrow key Left)''
|-
| element_move_right
| '''arrow_r''' || ''(Arrow key Right)''
|-
| element_move_downwards
| '''pgdn''' || ''(Page Down)''
|-
| element_move_upwards
| '''pgup''' || ''(Page Up)''
|-
| zoom_in
| '''mouse_wheel_down'''
|-
| zoom_out
| '''mouse_wheel_up'''
|-
| quick_rotate_increase
| '''mod_rotate''' + '''mouse_wheel_up''' || ''(Left CTRL + Mouse wheel Up)''
|-
| quick_rotate_decrease
| '''mod_rotate''' + '''mouse_wheel_down''' || ''(Left CTRL + Mouse wheel Down)''
|-
| mod_rotate
| '''lctrl''' || ''(Left CTRL)''
|-
| mod_slow_speed
| '''lalt''' || ''(Left ALT)''
|-
| mod_fast_speed
| '''lshift''' || ''(Left SHIFT)''
|-
| destroy_selected_element
| '''delete'''
|-
| drop_selected_element
| '''space'''
|-
| pickup_selected_element
| '''F2'''
|-
| reset_rotation
| '''mod_rotate''' + '''r''' || ''(Left CTRL + R)''
|}

===GUI===
{|
| toggle_gui_display
| '''F4'''
|-
| toggle_cursor
| '''f'''
|-
| select_target_keyboard
| '''mouse1''' || ''(Left Mouse button)''
|-
| select_target_mouse
| '''mouse2''' || ''(Right Mouse button)''
|-
| edf_next
| '''mouse_wheel_up'''
|-
| edf_prev
| '''mouse_wheel_down'''
|-
| undo
| '''Ctrl''' + '''z'''
|-
| redo
| '''Ctrl''' + '''y'''
|-
| properties_toggle
| '''F3'''
|-
| browser_up
| '''arrow_u''' || ''(Arrow key Up)''
|-
| browser_down
| '''arrow_d''' || ''(Arrow key Down)''
|-
| browser_zoom_in
| '''mouse_wheel_up'''
|-
| browser_zoom_out
| '''mouse_wheel_down'''
|-
| browser_confirm
| '''enter'''
|-
| currentelements_up
| '''num_8''' || ''(Numpad key 8)''
|-
| currentelements_down
| '''num_2''' || ''(Numpad key 2)''
|-
| toggle_test
| '''F5'''
|}

==Multiplayer==
The editor is built with both serverside and clientside components, and therefore supports multiplayer out of the box. To use the editor in multiplayer with other players, simply copy all of the editor's resources into your server, start the '''editor''' resource and allow other players to join.

Please note that currently the editor lacks any permissions system, so all users have access to every function.

==Plugins & External resources==
{{Main|Resource:Editor/Plugins}}

The editor allows basic importing of elements from external resources. This is useful for resources that may have to manipulate an element in a specific way that cannot be performed by the editor. For example, a map resource which uses custom models (and has a script to import these models) cannot be manipulated by default within the editor.

By using the '''import <resourceName>''' command in console the resource's elements can be imported within the editor.

==FAQ==
==== I get a black screen when launching the Map Editor ====

Usually this is caused due to incorrect installation of Map Editor resources. If you are using a stable MTASA client, please install it again and make sure that you use Client and Server install option.

If you are using a nightly build, to get it working right you need to download latest [https://github.com/multitheftauto/mtasa-resources resources (step 3)], unpack the archive and put its contents in:
''MTA San Andreas\server\mods\deathmatch\resources'' , where ''MTA San Andreas'' is a folder where you've installed MTA San Andreas (default location: C:\Program Files\MTA San Andreas).

Putting them in this path: MTA San Andreas\mods\deathmatch\resources '''is a common mistake''' - it won't work if you put them there. So make sure to put them in the ''italic'' path above.

If this issue still occurs, even when you've checked the note above and verified that you've installed it correctly, it might be because you've got an outdated '''acl.xml''' file. You can find the default one [https://github.com/multitheftauto/mtasa-blue/blob/master/Server/mods/deathmatch/acl.xml here]. It should be placed in '''server/mods/deathmatch/''' in your MTA: San Andreas installation directory.

==== I get an "Could not start the local server. See console for details" when using the "Map Editor" button ====
This is because you do not have a valid editor.conf installed. You can find the default one [https://github.com/multitheftauto/mtasa-blue/blob/master/Server/mods/deathmatch/editor.conf here]. It should be placed in '''server/mods/deathmatch/''' in your MTA: San Andreas installation directory.

==== I have saved a map but cannot find it in my server's resources directory, despite the Editor itself being able to see it ====
This is due to the fact that Vista/7 limits write-access for non-admin processes in Program Files directory. Files get written in the "VirtualStore" directory instead of real Program Files folder. You should be able to locate your map resource in a similar directory to:
C:\Users\<USERNAME>\AppData\Local\VirtualStore\Program Files\MTA San Andreas\server\mods\deathmatch\resources\

Running the Server/MTA San Andreas with Administrative rights will allow the map to be saved to the proper location.

==== I have some other problem with the map editor ====

Sometimes resetting the map editor will solve certain issues. The easiest way to do that is install MTA:SA to a brand new folder. Otherwise you can try the following steps:
::1. Go to the resources folder, '''server/mods/deathmatch/resources/''' and delete the '''editor_dump''' directory
::2. Go to the resources folder, '''server/mods/deathmatch/resources/''' and delete the '''editor_test''' directory

==== I have found a bug or have a suggestion/feedback for the map editor ====
Please use the official [https://github.com/multitheftauto/mtasa-resources/issues github issues] for reporting bugs. Feel free to also join us on [http://www.mtasa.com/discord Discord].

[[hu:Resource:Editor]]
[[ru:Resource:Editor]]
[[es:Resource:Editor]]
[[tr:Resource:Editor]]
[[pt-br:Resource:Editor]]

Template:Client world functions

2023-09-30T16:17:52Z

Zangomangu:

<ul>
<li>[[areTrafficLightsLocked]]</li>
<li>[[createSWATRope]]</li>
<li>[[getAircraftMaxHeight]]</li>
<li>[[getAircraftMaxVelocity]]</li>
<li>[[getBirdsEnabled]]</li>
{{New feature/item|3.0161|1.6.0|22188|
<li>[[getColorFilter]]</li>
}}
<li>[[getCloudsEnabled]]</li>
<li>[[getCoronaReflectionsEnabled]]</li>
<li>[[getFarClipDistance]]</li>
<li>[[getFogDistance]]</li>
<li>[[getGameSpeed]]</li>
<li>[[getGarageBoundingBox]]</li>
<li>[[getGaragePosition]]</li>
<li>[[getGarageSize]]</li>
<li>[[getGravity]]</li>
<li>[[getGroundPosition]]</li>
<li>[[getHeatHaze]]</li>
<li>[[getInteriorFurnitureEnabled]]</li>
<li>[[getInteriorSoundsEnabled]]</li>
<li>[[getJetpackMaxHeight]]</li>
<li>[[getMinuteDuration]]</li>
<li>[[getMoonSize]]</li>
<li>[[getNearClipDistance]]</li>
<li>[[getOcclusionsEnabled]]</li>
<li>[[getPedsLODDistance]]</li>
<li>[[getPlayerBlurLevel]]</li>
<li>[[getRainLevel]]</li>
{{Added feature/item|1.5.9|1.5.8|20675|
<li>[[getRoofPosition]]</li>
}}
<li>[[getScreenFromWorldPosition]]</li>
<li>[[getSunColor]]</li>
<li>[[getSunSize]]</li>
<li>[[getTime]]</li>
<li>[[getTrafficLightState]]</li>
<li>[[getVehiclesLODDistance]]</li>
<li>[[getWeather]]</li>
<li>[[getWindVelocity]]</li>
<li>[[getWorldFromScreenPosition]]</li>
<li>[[getZoneName]]</li>
<li>[[isAmbientSoundEnabled]]</li>
<li>[[isGarageOpen]]</li>
<li>[[isLineOfSightClear]]</li>
<li>[[isWorldSoundEnabled]]</li>
<li>[[isWorldSpecialPropertyEnabled]]</li>
{{New feature/item|3.0161|1.6.0|22219|
<li>[[processLineAgainstMesh]]</li>
}}
<li>[[processLineOfSight]]</li>
<li>[[removeWorldModel]]</li>
<li>[[resetAmbientSounds]]</li>
<li>[[resetBlurLevel]]</li>
<li>[[resetColorFilter]]</li>
<li>[[resetCoronaReflectionsEnabled]]</li>
<li>[[resetFarClipDistance]]</li>
<li>[[resetFogDistance]]</li>
<li>[[resetHeatHaze]]</li>
<li>[[resetMoonSize]]</li>
<li>[[resetNearClipDistance]]</li>
<li>[[resetPedsLODDistance]]</li>
<li>[[resetRainLevel]]</li>
<li>[[resetSkyGradient]]</li>
<li>[[resetSunColor]]</li>
<li>[[resetSunSize]]</li>
<li>[[resetVehiclesLODDistance]]</li>
<li>[[resetWindVelocity]]</li>
<li>[[resetWorldSounds]]</li>
<li>[[restoreAllWorldModels]]</li>
<li>[[restoreWorldModel]]</li>
<li>[[setAircraftMaxHeight]]</li>
<li>[[setAircraftMaxVelocity]]</li>
<li>[[setAmbientSoundEnabled]]</li>
<li>[[setBirdsEnabled]]</li>
<li>[[setCloudsEnabled]]</li>
<li>[[setColorFilter]]</li>
<li>[[setCoronaReflectionsEnabled]]</li>
<li>[[setFarClipDistance]]</li>
<li>[[setFogDistance]]</li>
<li>[[setGameSpeed]]</li>
<li>[[setGarageOpen]]</li>
<li>[[setGravity]]</li>
<li>[[setHeatHaze]]</li>
<li>[[setInteriorFurnitureEnabled]]</li>
<li>[[setInteriorSoundsEnabled]]</li>
<li>[[setJetpackMaxHeight]]</li>
<li>[[setMinuteDuration]]</li>
<li>[[setMoonSize]]</li>
<li>[[setNearClipDistance]]</li>
<li>[[setOcclusionsEnabled]]</li>
<li>[[setPedsLODDistance]]</li>
<li>[[setPlayerBlurLevel]]</li>
<li>[[setRainLevel]]</li>
<li>[[setSkyGradient]]</li>
<li>[[setSunColor]]</li>
<li>[[setSunSize]]</li>
<li>[[setTime]]</li>
<li>[[setTrafficLightsLocked]]</li>
<li>[[setTrafficLightState]]</li>
<li>[[setVehiclesLODDistance]]</li>
<li>[[setWeather]]</li>
<li>[[setWeatherBlended]]</li>
<li>[[setWindVelocity]]</li>
<li>[[setWorldSoundEnabled]]</li>
<li>[[setWorldSpecialPropertyEnabled]]</li>
{{New feature/item|3.0161|1.6.0|21902|
<li>[[setGrainLevel]]</li>
}}
{{New feature/item|3.0161|1.6.0|21902|
<li>[[setGrainMultiplier]]</li>
}}
<li>[[testLineAgainstWater]]</li>
</ul>

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

ProcessLineAgainstMesh

2023-09-30T16:08:41Z

Zangomangu: New feature tag

__NOTOC__
{{Client function}}
{{New feature/item|3.0161|1.6.0|22219|Does a raycast against an element's renderable mesh model directly}}
Does a raycast against an element's renderable mesh model [not the collision model!].
The same functionality is already present in [[processLineOfSight]], but the latter is a little buggy due to the fact that the collision model is always simplified, and not exactly the same as the mesh, which leads to situations where no hit is detected, even though the visible mesh is hittable [or vice versa].
Also, when one is interested in a specific element the overhead is a lot smaller [as we can skip all the collision detection done by the before-mentioned function].

==Syntax==
Return values labelled for ease of reference.
<syntaxhighlight lang="lua">
bool -- hit
float float -- texU, texV
string -- textureName
string -- frameName
float float float -- worldX, worldY, worldZ
processLineAgainstMesh(element toTest,
float startX, float startY, float startZ,
float endX, float endY, float endZ)
</syntaxhighlight>

===Required Arguments===
*'''toProcess:''' The element to process the line against
*'''startX, startY, startZ:''' The start [origin] of the line
*'''endX, endY, endZ:''' The end of the line

===Returns===
*'''hit:''' ''true'' if there is a collision with the given element's mesh, ''false'' otherwise [in which case all other values are nil]
*'''texU, texV:''' the U, V coordinates on the hit geometry's texture
*'''textureName:''' name of the hit geometry's texture
*'''frameName:''' hit frame's name
*'''worldX, worldY, worldZ:''' collision position in world space

==Requirements==
{{Requirements|n/a|1.6.0-9.22173|}}

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

SetPedControlState

2023-08-03T09:13:00Z

Zangomangu: Add a note on crouching

__NOTOC__
{{Client function}}
This function makes a [[ped]] or [[player]] press or release a certain [[control names|control]].
{{Note|You can't use enter_exit or enter_passenger on a ped. Please use [[setPedEnterVehicle]] and [[setPedExitVehicle]].}}
{{Note|To make a ped crouch, set the control to ''true'' and reset to ''false'' after one frame. Use [[setTimer]] with 0ms. Do the same to make the ped stand again.}}

==Syntax==
<syntaxhighlight lang="lua">
bool setPedControlState ( ped thePed, string control, bool state )
</syntaxhighlight>
{{OOP||[[Ped]]:setControlState}}

===Required Arguments===
*'''thePed:''' the ped you want to press or release a control.
*'''control:''' the name of the control of which to change the state. See [[control names]] for a list of valid names.
*'''state:''' the new control state. ''true'' means pressed, ''false'' is released.

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

==Remarks==
If you set the control state on the localPlayer element, then the control state is synchronized to every other client as if the input was made through the game input. But if you set any control states to server-side peds then the control state is not automatically synchronized. This behaviour is unaffected by being the syncer of the server-side ped or not. Let's assume that the syncer client calls setPedControlState on the ped. The other game clients - the ones where setPedControlState was not manually called by scripts - will see the ped teleport around. It will clearly look as if synchronization were broken.

==Example==
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function newPed()
local x, y, z = getElementPosition(localPlayer)
local ped = createPed(0, x + 1, y, z)
if ped then
setPedControlState(ped, "forwards", true)
end
end
addCommandHandler("ped", newPed)
</syntaxhighlight>
</section>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.5.5-3.11427|Works with the [[getLocalPlayer|local player]] as well. Deprecated [[setControlState]] and [[getControlState]].}}

==See Also==
{{Client ped functions}}

SetTimer

2023-08-03T09:07:39Z

Zangomangu: Remove irrelevant version info

__NOTOC__
{{Server client function}}{{Important Note|The speed at which a client side timer runs can be completely unreliable if a client is maliciously modifying their operating system speed, timers could run much faster or slower.}}
{{Important Note|Writing the following code can cause performance issues. Use [[onClientPreRender]] instead. <syntaxhighlight lang="lua">setTimer(theFunction, 0, 0)</syntaxhighlight>}}
This function allows you to trigger a function after a number of milliseconds have elapsed. You can call one of your own functions or a built-in function. For example, you could set a timer to spawn a player after a number of seconds have elapsed.

Once a timer has finished repeating, it no longer exists.

The minimum accepted interval is 0ms.

Multi Theft Auto guarantees that the timer will be triggered after ''at least'' the interval you specify. The resolution of the timer is tied to the frame rate (server side and client-side). All the overdue timers are triggered at a single point each frame. This means that if, for example, the player is running at 30 frames per second, then two timers specified to occur after 100ms and 110ms would more than likely occur during the same frame, as the difference in time between the two timers (10ms) is less than half the length of the frame (33ms). As with most timers provided by other languages, you shouldn't rely on the timer triggering at an exact point in the future.

==Syntax==
<syntaxhighlight lang="lua">
timer setTimer ( function theFunction, int timeInterval, int timesToExecute [, var arguments... ] )
</syntaxhighlight>
{{OOP||[[Timer]]}}
===Required Arguments===
*'''theFunction:''' The function you wish the timer to call.
{{Note|The hidden global variable '''sourceTimer''' contains the currently executing timer userdata}}
{{Note|The hidden global variable '''source''' becomes ''nil'' inside a timer function. You need to declare it on the function arguments if you need to use it.}}
*'''timeInterval:''' The number of milliseconds that should elapse before the function is called. The minimum is 0 ms; 1000 milliseconds = 1 second)
*'''timesToExecute:''' The number of times you want the timer to execute, or 0 for infinite repetitions.

===Optional Arguments===
{{OptionalArg}}
*'''arguments:''' Any arguments you wish to pass to the function can be listed after the ''timesToExecute'' argument. Note that any tables you want to pass will get cloned, whereas metatables and functions/function references in that passed table will get lost. Also changes you make in the original table before the function gets called won't get transferred.

===Returns===
Returns a [[timer]] pointer if the timer was set successfully, ''false'' if the arguments are invalid or the timer could not be set.

==Example==

<section name="Example 1" class="both" show="true">
This example will output some text after a small delay.

<syntaxhighlight lang="lua">
-- define function to be called
function delayedChat ( text )
outputChatBox ( "Delayed text: " .. text )
end

-- set a timer so the function is called after 1 second
setTimer ( delayedChat, 1000, 1, "Hello, World!" )
</syntaxhighlight>
1 second after the line above has been executed, the text ''Delayed text: Hello, World!'' will be displayed in the chat box.
</section>

<section name="Example 2" class="both" show="true">
This example will nest a whole function within a timer. This is nice for things like setting variables without having to call a function outside of your code block.

<syntaxhighlight lang="lua">
function mainFunction()
outputChatBox ("Instant text!")
setTimer ( function()
outputChatBox ( "5 second delay text!" )
end, 5000, 1 )
end

mainFunction() --call function
</syntaxhighlight>
</section>

<section name="Example 3" class="both" show="true">
This example outputs some random text to the chat every 300000 milliseconds (5 minutes).
<syntaxhighlight lang="lua">
setTimer(function()
outputChatBox("Text " .. math.random(1,4))
end, 300000, 0)
</syntaxhighlight>
</section>

<section name="Example 4" class="server" show="true">
This example should send a global message about the death of a player on a random time. I used [https://wiki.multitheftauto.com/wiki/Math.round math.round] in this example to give a nicer output.
<syntaxhighlight lang="lua">
function math.round(number, decimals, method) -- math.round, useful function taken from the wiki: https://wiki.multitheftauto.com/wiki/Math.round
decimals = decimals or 0
local factor = 10 ^ decimals
if (method == "ceil" or method == "floor") then return math[method](number * factor) / factor
else return tonumber(("%."..decimals.."f"):format(number)) end
end

function onWasted()
local delay = math.random(500, 5000) -- 0.5s to 5s of delay
setTimer(function(thePlayer) -- Starts the Timer
local whoDied = "Someone" -- In case the name can't be read, Someone will appear
if isElement(thePlayer) then -- This checks if thePlayer's element still exists (which means thePlayer hasnt disconnected yet)
whoDied = getPlayerName(thePlayer) -- Changes Someone to thePlayer's name
end
outputChatBox(whoDied.." #FFFFFFhas #FF0000died #FFFFFF"..math.round(delay/1000, 1).." seconds ago.", root, 255, 175, 0, true) -- This will output to everyone on the server that thePlayer (or Someone) died X seconds ago.
end
delay, 1, source) -- The source at the end is an argument for the function we made before, you can't use the source directly because it won't be readed
end
addEventHandler("onPlayerWasted", root, onWasted) -- Executed every time someone dies
</syntaxhighlight>
</section>

==See Also==
{{Utility functions}}
[[pt-br:SetTimer]]

ClearElementVisibleTo

2023-08-03T08:57:33Z

Zangomangu:

__NOTOC__
{{Server function}}
This function clears any settings added by [[setElementVisibleTo]] and restores an [[element]] to its default [[visibility]].

==Syntax==
<syntaxhighlight lang="lua">
bool clearElementVisibleTo ( element theElement )
</syntaxhighlight>
{{OOP||[[element]]:clearVisibility|||}}

===Required Arguments===
*'''theElement:''' The element in which you wish to restore to its default visibility

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

==Example==
This example clears any visibility settings after a player dies, so everyone can see his blip for a short period
<syntaxhighlight lang="lua">
-- specify the getBlipAttachedTo function
function getBlipAttachedTo( thePlayer )
local blips = getElementsByType( "blip" )
for k, theBlip in ipairs( blips ) do
if getElementAttachedTo( theBlip ) == thePlayer then
return theBlip
end
end
return false
end

function clearVisibilityWasted ( totalammo, killer, killerweapon, bodypart ) -- when a player dies
clearElementVisibleTo ( getBlipAttachedTo ( source ) ) -- clear any visiblity settings of his blip
end
addEventHandler ( "onPlayerWasted", root, clearVisibilityWasted ) --add an event handler for onPlayerWasted
</syntaxhighlight>

==See Also==
{{Element_functions}}

SetElementVisibleTo

2023-08-03T08:56:23Z

Zangomangu: Describe precisely which elements this function works with

__NOTOC__
{{Server function}}
{{Needs_Checking|Can an element only be visible to one element (and its children) at a time? If so, do we need clearElementVisibleTo? If not, surely we need to remove the root element before using this function?

Does the order of setElementVisibleTo calls really not matter? [[visibility|Visibility]] seems to ''imply'' that the order does matter.

Is this function particularly ''or only'' useful for changing the visibility of markers, radar blips and radar areas?|[[User:EAi|EAi]][[User:Iam2noob4u|Iam2noob4u]]
}}

This function can change an [[element]]'s [[visibility]].

This function only works with the following elements.
* [[Marker]]s
* [[Blip]]s
* [[Radararea]]s

Visibility settings of lower elements in the element tree override higher ones - if visibility for root is set to false and for a player is set to true, it will be visible to the player.

If you want to clear all visibility settings of an [[element]], try [[clearElementVisibleTo]]

==Syntax==
<syntaxhighlight lang="lua">
bool setElementVisibleTo ( element theElement, element visibleTo, bool visible )
</syntaxhighlight>
{{OOP||[[element]]:setVisibleTo||isElementVisibleTo}}

===Required Arguments===
*'''theElement:''' The element you want to control the visibility of.
*'''visibleTo:''' The element you wish the element to be visible or invisible to. Any child elements that are players will also be able to see the element. See [[visibility]].
*'''visible:''' Whether you are making it visible or invisible to the player.

===Returns===
Returns ''true'' if the element's visibility was changed successfully, ''false'' otherwise, for example if you are trying to change the visibility of a vehicle, player or object.

==Example==
This example creates a marker and makes it only visibile to the player called 'someguy'.
<syntaxhighlight lang="lua">
-- Find the player called someguy
local someguy = getPlayerFromName ( "someguy" )
-- If the player was found then
if ( someguy ) then
-- Get the player's position into the variables x, y and z
x, y, z = getElementPosition ( someguy )
-- Create a marker at the player's position
myMarker = createMarker ( x, y, z )

-- Then make the marker invisible to the whole dimension (root for the first)
setElementVisibleTo ( myMarker, root, false )
-- Set marker visibility to true for someguy
setElementVisibleTo ( myMarker, someguy, true )

-- The order in which you do the visibility changes does not matter, but ideally trues should be set before falses in order to prevent a momentary flicker.
end
</syntaxhighlight>

The following example shows how to make the marker visible to everyone except anotherguy
<syntaxhighlight lang="lua">
-- Find the player called someguy
local someguy = getPlayerFromName ( "someguy" )
local anotherguy = getPlayerFromName ( "anotherguy" )
-- If the player was found then
if ( someguy ) then
-- Get the player's position into the variables x, y and z
x, y, z = getElementPosition ( someguy )
-- Create a marker at the player's position
myMarker = createMarker ( x, y, z )
attachElements(myMarker, someguy)

-- First make sure everyone is able to see the marker, this line is unnecessary in this case as root visibility is set to true by default behaviour
setElementVisibleTo ( myMarker, root, true )

-- Then hide it from anotherguy
setElementVisibleTo ( myMarker, anotherguy, false )
end
</syntaxhighlight>

==See Also==
{{Element_functions}}

Sync interval settings

2023-06-18T08:42:24Z

Zangomangu: (1.6) added ped_far_sync_interval

==About player sync==
Player key sync is always done on demand. i.e. Player presses W, (or pushes forward on the joystick), and the sync for that is sent straight away to the server, and then to the other clients.
There is no setting to limit key sync as it is an essential component to minimize latency.
The 'player_sync_interval' below, is the interval between positional and rotational corrections to key sync. This is in case the movement interpreted by the key sync system on remote clients has introduced any errors.

==Default values==
{| class="wikitable"
|'''Name'''
|'''Default (ms)'''
|'''Valid range'''
|'''Description'''
|-
| player_sync_interval
| 100
| 50-4000
| Time between key sync correction updates for players. (Note: Player key sync is always done on demand and is not affected by any setting) (Note2: Don't set player_sync_interval interval too high, it will cause fake network troubles)
|-
| lightweight_sync_interval
| 1500
| 50-4000
| Time between updates for very far away players
|-
| camera_sync_interval
| 500
| 50-4000
| How often to tell the server of any client side changes to the local players camera position and target.
|-
| ped_sync_interval
| 400
| 50-4000
| Time between updates for non-player peds
|-
| ped_far_sync_interval
| 2000
| 50-4000
| Time between updates for non-player peds for clients which are far away from the ped.
|-
| unoccupied_vehicle_sync_interval
| 1000
| 50-4000
| Time between updates for unoccupied vehicles
|-
| keysync_mouse_sync_interval
| 100
| 50-4000
| Minimum gap between mouse movement updates being sent to the server
|-
| keysync_analog_sync_interval
| 100
| 50-4000
| Minimum gap between joystick partial axes movement updates being sent to the server. (Full axes movement is treated as key sync and is not limited by this setting)
|-
|}

==Suggested settings==
===Bandwith and CPU saver===
{| class="wikitable"
|-
| player_sync_interval
| 200
|-
| lightweight_sync_interval
| 3000
|-
|}

===Bandwith and CPU super saver===
{| class="wikitable"
|-
| player_sync_interval
| 300
|-
| lightweight_sync_interval
| 4000
|-
|}

===Less annoying unoccupied vehicles===
{| class="wikitable"
|-
| unoccupied_vehicle_sync_interval
| 500
|-
|}

===Uber sync (bandwidth and CPU intensive)===
{| class="wikitable"
|-
| player_sync_interval
| 50
|-
| keysync_mouse_sync_interval
| 50
|-
| keysync_analog_sync_interval
| 50
|-
|}

Server mtaserver.conf

2023-06-18T08:33:34Z

Zangomangu:

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

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

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

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

====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.1.0-9.03100.0
: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]].'''

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

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

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

====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>36</fpslimit>
:Specifies the frame rate limit that will be applied to connecting clients.
:Available range: 25 to 100. Default: 36.
:When running the map editor locally (i.e. from the client), the default FPS limit is 50.
: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

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

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

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

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

====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====
:''<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.

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

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

Server mtaserver.conf

2023-06-18T08:31:57Z

Zangomangu: (1.6) added ped_far_sync_interval

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

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

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

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

====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.1.0-9.03100.0
: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]].'''

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

====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 player is nearby.
: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]]

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

====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>36</fpslimit>
:Specifies the frame rate limit that will be applied to connecting clients.
:Available range: 25 to 100. Default: 36.
:When running the map editor locally (i.e. from the client), the default FPS limit is 50.
: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

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

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

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

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

====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====
:''<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.

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

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

GetScreenFromWorldPosition

2023-04-02T17:29:07Z

Zangomangu: Undo revision 76324 by Deihim007 (talk) it returns 3 values

__NOTOC__
{{Client function}}
This function gets the screen position of a point in the world. This is useful for attaching 2D gui elements to parts of the world (e.g. players) or detecting if a point is on the screen (though it does not check if it is actually visible, you should use [[processLineOfSight]] for that).

==Syntax==
<syntaxhighlight lang="lua">
float, float, float getScreenFromWorldPosition ( float x, float y, float z [, float edgeTolerance = 0.0, bool relative = true ] )
</syntaxhighlight>

===Required Arguments===
*'''x:''' A float value indicating the x position in the world.
*'''y:''' A float value indicating the y position in the world.
*'''z:''' A float value indicating the z position in the world.

===Optional Arguments===
{{OptionalArg}}
{{New feature/item|3|1.0||
*'''edgeTolerance:''' A [[float]] value indicating the distance the position can be off screen before the function returns false. Note: it's clamped down on both axies to the size of screen at the given axis*10
*'''relative:''' A [[boolean]] value that indicates if edgeTolerance is in pixels [false], or relative to the screen size [true].
}}

===Returns===
Returns two ''x'', ''y'' [[float]]s indicating the screen position and [[float]] distance between screen and given position if successful, ''false'' otherwise.

===Example===
<section class="client" name="Client-side Script" show="true">
This example add a '3d' text at coordinates 0, 0, 0 (center of map).
<syntaxhighlight lang="lua">
addEventHandler ( "onClientRender", root,
function ( )
if ( getDistanceBetweenPoints3D ( 0, 0, 3, getElementPosition ( localPlayer ) ) ) < 50 then
local coords = { getScreenFromWorldPosition ( 0, 0, 3 ) }
if coords[1] and coords[2] then
dxDrawText ( "Hello !", coords[1], coords[2], coords[1], coords[2], tocolor(255,255,255), 1, "default-bold" )
end
end
end )
</syntaxhighlight>
</section>

==See Also==
{{Client_world_functions}}

GetScreenFromWorldPosition

2023-03-31T21:37:37Z

Zangomangu: Undo revision 76318 by LordHenry (talk)

SetElementBoneMatrix

2023-01-15T15:06:48Z

Zangomangu: Reverted edits by Synthetic (talk) to last revision by Lvrent

{{Client function}}
__NOTOC__
{{Added feature/item|1.5.9|1.5.8|20704|This function sets the transformation matrix of a specific bone. Currently the [[Element/Player|Player]] and [[Element/Ped|Ped]] element types are accepted.}}
{{Tip|If you want to attach an element to a bone, see [[attachElementToBone]].}}
{{Tip|For [[matrix]] manipulation which goes beyond the basic examples given on this page, see the [[Lua matrix library]]. Using the built-in [[matrix]] class is also recommended.}}

==Syntax==
<syntaxhighlight lang="lua">
bool setElementBoneMatrix ( element theElement, int boneId, matrix matrix )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' the [[element]] to set the bone matrix on.
*'''boneId:''' the ID of the bone. See [[Bone IDs]].
*'''matrix:''' the MTA [[matrix]] to set.

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

==Example==
{{Needs Example}}

==Requirements==
{{Requirements|n/a|1.5.8-9.20704|}}

==See Also==
{{Client_element_functions}}

SetElementBonePosition

2022-12-06T16:44:58Z

Zangomangu: Reverted edits by GustavoFreire (talk) to last revision by AncienT

__NOTOC__
{{Client function}}
{{Added feature/item|1.5.9|1.5.8|20704|This function sets the position of a bone to the specified coordinates. Currently the [[Element/Player|Player]] and [[Element/Ped|Ped]] element types are accepted.}}
{{Tip|If you want to attach an element to a bone, see [[attachElementToBone]].}}
{{Note|You need to use this function together with [[onClientPedsProcessed]].}}

==Syntax==
<syntaxhighlight lang="lua">
bool setElementBonePosition ( element theElement, int bone, float x, float y, float z )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' the [[Element|element]] to set the bone position on.
*'''bone:''' the ID of the bone to set the position of. See [[Bone IDs]].
*'''x:''' The X coordinate of the destination.
*'''y:''' The Y coordinate of the destination.
*'''z:''' The Z coordinate of the destination.

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

==Example==
[[File:CJ with long neck.png|thumb|alt=CJ with long neck|Example preview]]
This example shows a surprised CJ with a long neck
<syntaxhighlight lang="lua">
local bones = {
[4] = Vector3(0, 0, 0.15),
[5] = Vector3(0, 0, 0.15),
[6] = Vector3(0, 0, 0.13),
[7] = Vector3(0, 0, 0.13),
[8] = Vector3(0, 0, 0.1),
}
function updatePed()
for bone,v in pairs(bones) do
local pos = localPlayer:getBonePosition(bone)+v
setElementBonePosition(localPlayer, bone, pos)
end
end
addEventHandler("onClientPedsProcessed", root, updatePed)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.5.8-9.20704|}}

==See Also==
{{Client_element_functions}}

OnPlayerWasted

2022-11-14T21:46:47Z

Zangomangu: Killer element type

__NOTOC__
{{Server event}}
This event is triggered when a player is killed or dies.

==Parameters==
{{New feature/item|3|1.0||<syntaxhighlight lang="lua">
int totalAmmo, element killer, int killerWeapon, int bodypart, bool stealth
</syntaxhighlight>}}

{{Deprecated_feature|3|1.0|<syntaxhighlight lang="lua">
int totalAmmo, element killer, int killerWeapon, int bodypart
</syntaxhighlight>}}

*'''totalAmmo''': an [[int]] representing the total ammo the victim had when they died.
*'''killer''': an [[element]] representing the [[player]], [[ped]], [[vehicle]] or [[object]] who was the killer. Deaths resulting from fall damage provide the [[vehicle]] or [[object]] landed on as the killer. If there is no killer this is ''false''.
*'''killerWeapon''': an [[int]] representing the [[Weapons|killer weapon]] or the [[Damage Types|damage type]].
*'''bodypart''': an [[int]] representing the bodypart ID the victim was hit on when they died.
{{BodyParts}}
*'''stealth''': a [[boolean]] value representing whether or not this was a stealth kill.

==Source==
The [[event system#Event source|source]] of this event is the [[player]] that died or got killed.

==Example==
This example prints the killer and bodypart to the chat when a player dies.
<syntaxhighlight lang="lua">
-- register player_Wasted as a handler for onPlayerWasted
function player_Wasted ( ammo, attacker, weapon, bodypart )
-- if there was an attacker
if ( attacker ) then
-- we declare our variable outside the following checks
local tempString
-- if the element that killed him was a player,
if ( getElementType ( attacker ) == "player" ) then
-- put the attacker, victim and weapon info in the string
tempString = getPlayerName ( attacker ).." killed "..getPlayerName ( source ).." ("..getWeaponNameFromID ( weapon )..")"
-- else, if it was a vehicle,
elseif ( getElementType ( attacker ) == "vehicle" ) then
-- we'll get the name from the attacker vehicle's driver
tempString = getPlayerName ( getVehicleController ( attacker ) ).." killed "..getPlayerName ( source ).." ("..getWeaponNameFromID ( weapon )..")"
end
-- if the victim was shot in the head, append a special message
if ( bodypart == 9 ) then
tempString = tempString.." (HEADSHOT!)"
-- else, just append the bodypart name
else
tempString = tempString.." ("..getBodyPartName ( bodypart )..")"
end
-- display the message
outputChatBox ( tempString )
-- if there was no attacker,
else
-- output a death message without attacker info
outputChatBox ( getPlayerName ( source ).." died. ("..getWeaponNameFromID ( weapon )..") ("..getBodyPartName ( bodypart )..")" )
end
end
addEventHandler ( "onPlayerWasted", root, player_Wasted )
</syntaxhighlight>

And another example, this will spawn you in the middle of GTA SA world (x=0, y=0, z=3) after 2 seconds of your death
<syntaxhighlight lang="lua">
addEventHandler( "onPlayerWasted", root,
function()
setTimer( spawnPlayer, 2000, 1, source, 0, 0, 3 )
end
)
</syntaxhighlight>

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

[[ru:onPlayerWasted]]

OnPedWasted

2022-11-14T21:46:25Z

Zangomangu: Killer element type

__NOTOC__
{{Server event}}
This event is triggered when a ped is killed or dies. It is not triggered for players.

==Parameters==
<syntaxhighlight lang="lua">int totalAmmo, element killer, int killerWeapon, int bodypart, bool stealth
</syntaxhighlight>

*'''totalAmmo''': an [[int]] representing the total ammo the victim had when he died.
*'''killer''': an [[element]] representing the [[player]], [[ped]] or [[vehicle]] who was the killer. If there was no killer this is ''false''.
*'''killerWeapon''': an [[int]] representing the [[Weapons|killer weapon]] or the [[Damage Types|damage types]].
*'''bodypart''': an [[int]] representing the bodypart ID the victim was hit on when he died.
{{BodyParts}}
*'''stealth''': a [[boolean]] representing whether or not this was a stealth kill.

==Source==
The [[event system#Event source|source]] of this event is the [[ped]] that died or got killed.

==Example==
This example outputs to the console that the ped is now dead.
<syntaxhighlight lang="lua">
ped1 = createPed(112, 0, 0, 0) --Create our Ped
function died()
outputConsole("Your Ped is dead now!")
end
addEventHandler("onPedWasted", ped1, died) --Add the Event when ped1 dies
</syntaxhighlight>

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

OnClientPlayerWasted

2022-11-14T21:38:44Z

Zangomangu: Killer element type

__NOTOC__
{{Client event}}
This event is triggered whenever a player, including those remote, dies.

==Parameters==
<syntaxhighlight lang="lua">
element killer, int weapon, int bodypart, bool stealth
</syntaxhighlight>

*'''killer''': A [[player]], [[ped]] or [[vehicle]] [[element]] representing the killer.
*'''weapon''': An [[int|integer]] representing the [[Weapons|killer weapon]] or the [[Damage Types|damage types]].
*'''bodypart''': An [[int|integer]] representing the bodypart the player was damaged.
{{BodyParts}}
*'''stealth''': A [[boolean]] representing whether or not this was a stealth kill.

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

==Example==
This example outputs a mocking message when the local player dies.
<syntaxhighlight lang="lua">
messages = {
"Better luck next time",
"Don't think you're so cool now, do you?",
"Nice one, pal",
"Your opinion is void"
}

function wastedMessage ( killer, weapon, bodypart )
local randomID = math.random ( 1, #messages ) --get a random ID from the table
local randomMessage = messages[randomID] --use that to retrieve a message
outputChatBox ( randomMessage, 255, 0, 0 ) --output the message
end
addEventHandler ( "onClientPlayerWasted", getLocalPlayer(), wastedMessage ) --add an event for the local player only
</syntaxhighlight>

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

OnClientPedWasted

2022-11-14T21:38:03Z

Zangomangu: Killer element type

__NOTOC__
{{Client event}}

This event is triggered whenever a ped dies.

==Parameters==
<syntaxhighlight lang="lua">
element killer, int weapon, int bodypart, float loss / bool stealth
</syntaxhighlight>

*'''killer''': A [[player]], [[ped]] or [[vehicle]] [[element]] representing the killer.
*'''weapon''': An [[int|integer]] representing the [[Weapons|killer weapon]] or the [[Damage Types|damage types]].
*'''bodypart''': An [[int|integer]] representing the bodypart the player was damaged.
{{BodyParts}}
*'''loss''': A [[float]] representing the percentage of health the ped lost in the final "hit". ''Note: Only for client-side created peds.''
'''OR'''
*'''stealth''': A [[boolean]] representing whether or not this was a stealth kill.

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

==Example==
<section name="Client" class="client" show="true">
This example outputs a message every time a player kills another player.
<syntaxhighlight lang="lua">
-- define the event handler function
function onWasted(killer, weapon, bodypart)
if ( killer and getElementType(killer) == "player" and getElementType(source) == "player" ) then
outputChatBox(getPlayerName(killer).." has killed ".. getPlayerName(source) ..".") -- output the kill message to the chatbox.
end
end

-- add the event handler
addEventHandler("onClientPedWasted", getRootElement(), onWasted)
</syntaxhighlight>
</section>

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

Installing and Configuring Nginx as an External Web Server

2022-11-06T10:10:02Z

Zangomangu: Added note on 403

==Internal vs External==
The MTA:SA server comes with a built-in 'internal' HTTP server which clients use to automatically download resource files. It is only a basic HTTP server which does not support compression or multiple client connections.
By adding an external HTTP server such as '''nginx''' or '''lighttpd''', resource download speed can be increased and bandwidth usage (and player waiting time) decreased.
Note that the external HTTP server can be on the same machine as the MTA server.

==nginx vs Apache==
We recommend nginx or lighttpd as they are better suited to handle the hundreds of file requests that MTA:SA clients will generate. Apache can be used, but will require settings tweaking and the mtasever.conf setting <'''httpmaxconnectionsperclient'''> may have to be reduced to prevent timeouts.

The following guide is for installing and configuring nginx solely for MTA:SA. It assumes:
* You are not already using nginx for other web sites on your server.
* MTA:SA server is installed on the same server.
* You are using Debian 7 (but should work on other distributions in a similar way.)

==Installing nginx:==
Update system:
apt-get update
apt-get upgrade

Install nginx:
apt-get install nginx

Ensure nginx is not running:
/etc/init.d/nginx stop

==Configuring nginx:==

====Edit: /etc/nginx/sites-enabled/mta-server1====
In the directory '''/etc/nginx/sites-enabled/''' create a file called '''mta-server1''' with the following content:
server {
listen 20080;
root /PATH_TO_MTA_SERVER/mods/deathmatch/resource-cache/http-client-files;
server_name localhost;
access_log off;
autoindex off;
}
'''**Important**: Change PATH_TO_MTA_SERVER to the actual absolute path of your MTA:SA server install directory'''
====Edit: /etc/nginx/nginx.conf====
At the top of the file, add this line to increase the max number of files that can be opened:
worker_rlimit_nofile 5000;
Find the ''''worker_connections'''' line and change it to this:
worker_connections 5000;
Find the ''''gzip'''' settings and make sure gzip is on:
gzip on;
and ''''gzip_types'''' is set for any file type:
gzip_types *;

==Testing nginx:==
Start nginx:
/etc/init.d/nginx start

=====Test #1=====
Open your internet browser, and try this address: '''<nowiki>http://YOUR_SERVER_IP:20080/admin/client/admin_ACL.lua</nowiki>'''<br/>
If prompted to download a file - SUCCESS!

'''Note''': If you are getting a 403 Forbidden response, nginx cannot access the files. Usually this means the user (www-data) is lacking ''execute'' permission on the server, mods, deathmatch, resource-cache, http-client-files folders.

=====Test #2=====
To test the compression is working, go here: http://www.whatsmyip.org/http-compression-test/ and enter '''<nowiki>http://YOUR_SERVER_IP:20080/admin/client/admin_ACL.lua</nowiki>''' in the white box and press 'Test'.<br/>
If green tick - SUCCESS!

==Configure MTA:SA server:==
====Edit mtaserver.conf====
Set '''httpdownloadurl''' to be like this:
<httpdownloadurl>'''<nowiki>http://YOUR_SERVER_IP:20080</nowiki>'''</httpdownloadurl>

And start MTA:SA server.

TriggerLatentServerEvent

2022-08-17T21:11:46Z

Zangomangu: Added as note and link to issue

__NOTOC__
{{Client function}}
This function is the same as [[triggerServerEvent]] except the transmission rate of the data contained in the arguments can be limited and other network traffic is not blocked while the data is being transferred.

{{Note|Calling [[kickPlayer]] inside a function which was called from triggerLatentServerEvent causes server to crash. ([https://github.com/multitheftauto/mtasa-blue/issues/2386 #2386])}}

==Syntax==
<syntaxhighlight lang="lua">
bool triggerLatentServerEvent ( string event, [int bandwidth=5000, bool persist=false,] element theElement, [arguments...] )
</syntaxhighlight>

===Required Arguments===
*'''event:''' The name of the event to trigger server-side. You should register this event with [[addEvent]] and add at least one event handler using [[addEventHandler]].
*'''theElement:''' The element that is the [[Event system#Event handlers|source]] of the event. This could be another player, or if this isn't relevant, use the root element.

===Optional Arguments===
*'''bandwidth:''' The bytes per second rate to send the data contained in the arguments.
*'''persist:''' A bool indicating whether the transmission should be allowed to continue even after the resource that triggered it has since stopped.
*'''arguments...:''' A list of arguments to trigger with the event. You can pass any Lua data type (except functions). You can also pass [[element]]s. The total amount of data should not exceed 100MB.

===Returns===
Returns ''true'' if the event trigger has been sent, ''false'' if invalid arguments were specified.

==Example==
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
if fileExists("text.txt")
file = fileOpen("test.txt") --Open a file (you can create it yourself).
local data = fileRead(file,100*1024*1024) --Max 100 MB
fileClose(file) --Close File
triggerLatentServerEvent("onReadFile",5000,false,root,data) --trigger
end
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
addEvent("onReadFile",true)
addEventHandler("onReadFile",root,function(data)
local file = fileCreate("text.txt") --Save "data" into "text.txt"
fileWrite(file,data)
fileClose(file)
end)

</syntaxhighlight>
</section>

==Requirements==
{{Requirements|n/a|1.3.0-9.03772|}}

==See Also==
{{Client_event_functions}}

SetWorldSpecialPropertyEnabled

2022-04-10T17:31:37Z

Zangomangu: Typo

__NOTOC__
{{Client function}}

Enables or disables a special world property.

==Syntax==
<syntaxhighlight lang="lua">bool setWorldSpecialPropertyEnabled ( string propname, bool enable )</syntaxhighlight>
{{OOP||||isWorldSpecialPropertyEnabled}}
[[File:Randomfoliage.jpeg|frame|right|A photo demonstrating ''randomfoliage'' enabled and disabled.]]
===Required Arguments===
*'''propname:''' the name of the property to set. Possible values are:
**'''hovercars''' - equivalent of the JBGVNB cheat, and allows cars to drive on water.
**'''aircars''' - equivalent of the RIPAZHA cheat, and allows cars to fly.
**'''extrabunny''' - equivalent of the CJPHONEHOME or JHJOECW cheat, and allows you to bunny hop on bicycles much higher.
**'''extrajump''' - equivalent of the KANGAROO cheat, and allows you to jump on foot much higher.
**'''randomfoliage''' - toggle randomly generated foliage on the GTA:SA map (default: true)
**'''snipermoon''' - toggle the GTA:SA easter egg, which increases the size of the moon every time you shoot it with a sniper rifle (default: false)
**'''extraairresistance''' - toggle the vehicle speed limit on cross-country roads (default: true)
**{{New feature/item|3.0156|1.5.5|12286|'''underworldwarp''' - toggle warp of peds and vehicles when fall under map (default: true)}}
**{{New feature/item|1.5.9|1.5.9|21125|'''vehiclesunglare''' - toggle the vehicle sun glare effect (default: false) }}
*'''enable:''' whether or not to enable the property.

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

==Example==

'''Example 1:''' Allows cars to fly.
<syntaxhighlight lang="lua">
addEventHandler( "onClientResourceStart", resourceRoot,
function( )
setWorldSpecialPropertyEnabled( "aircars", true )
end
)
</syntaxhighlight>

'''Example 2:''' Allow cars to drive on water.
<syntaxhighlight lang="lua">
addEventHandler( "onClientResourceStart", resourceRoot,
function( )
setWorldSpecialPropertyEnabled( "hovercars", true )
end
)</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.5.5-3.12286|Added "underworldwarp" property}}
{{ChangelogItem|1.5.9-1.21125|Added "vehiclesunglare" property}}

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

IsVehicleOnGround

2022-01-31T21:15:01Z

Zangomangu: Added note regarding isVehicleWheelOnGround

{{Server client function}}
__NOTOC__
Checks to see if a vehicle has contact with the ground.

{{Note|This function has a few issues, see below. Consider using the clientside function [[isVehicleWheelOnGround]] instead.}}

==Syntax==
<syntaxhighlight lang="lua">
bool isVehicleOnGround ( vehicle theVehicle )
</syntaxhighlight>
{{OOP||[[vehicle]]:isOnGround|onGround}}
===Required Arguments===
*'''theVehicle:''' The vehicle you wish to check.

===Returns===
Returns ''true'' if vehicle is on the ground, ''false'' if it is not.

==Example==

This example tells you when you've jumped out of a vehicle.

<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function checkVState ( vehicle, seat, jacked )
vehName = getVehicleName ( vehicle )

if isVehicleOnGround ( vehicle ) == false then
outputChatBox ( "You jumped out of a "..vehName.."!", source, 255, 0, 0 )
end

end
addEventHandler ( "onPlayerVehicleExit", getRootElement(), checkVState )
</syntaxhighlight>
</section>

== Issues ==
{{Issues|
{{Issue|471|isVehicleOnGround sometimes returns false incorrectly}}
{{Issue|2093|isVehicleOnGround does not work after setVehicleHandling}}
}}

==See Also==
{{Vehicle functions}}

RU/onPlayerChangeNick

2022-01-30T19:04:39Z

Zangomangu: Removed fixed issues

{{RU/Server event}}
__NOTOC__
Это событие вызывается, когда игрок меняет свой ник.

==Параметры==
<syntaxhighlight lang="lua">
string oldNick, string newNick, bool changedByUser
</syntaxhighlight>
*'''oldNick'''. Ник, который игрок имел раньше.
*'''newNick'''. Новый ник игрока.
{{RU/New items|3.0154|1.5.3|
*'''changedByUser'''. Было ли имя изменено с помощью функции [[RU/setPlayerName|setPlayerName]] или пользователем.
|9765}}

==Источник==
[[RU/Event system|Источником]] этого события является [[RU/Element/Player|игрок]], который изменил свой ник.

==Отмена эффекта==
[[RU/Event system#Отмена событий|Отмена]] этого события зависит от того, как оно вызывается. Если оно вызывается скриптинговым событием, тогда оно не отменяется. Если оно вызывается командой ''/nick'', оно отменяется. Если это событие отменено и может быть отменено, имя не изменится.

==Примеры==
'''Пример 1'''. В этом примере отменяется событие, если ник уже существует.
<syntaxhighlight lang="lua">
function nickChangeHandler(oldNick, newNick)
if getAccount(newNick) then
outputChatBox("К сожалению, уже существует аккаунт с Вашим новым ником как имя пользователя.", source, 0, 255, 0)
outputChatBox("Пожалуйста, выберите другой.", source, 0, 255, 0)
cancelEvent()
end
end
addEventHandler("onPlayerChangeNick", getRootElement(), nickChangeHandler)
</syntaxhighlight>

{{RU/New items|3.0154|1.5.3|
'''Пример 2'''. В этом примере проверяется, был ли ник игрока изменён скриптом и, если это так, логируется.
<syntaxhighlight lang="lua">
function wasNickChangedByUser(oldNick, newNick, changedByUser)
if changedByUser == false then
outputServerLog("Имя игрока "..oldNick.." было изменено на "..newNick.." скриптом.")
end
end
addEventHandler("onPlayerChangeNick", getRootElement(), wasNickChangedByUser)
</syntaxhighlight>|9765}}

{{RU/See also/Server event|RU/Player events|События игрока}}

[[en:onPlayerChangeNick]]

WarpPedIntoVehicle

2022-01-30T19:02:49Z

Zangomangu:

__NOTOC__
{{Server client function}}
This function is used to warp or force a ped into a vehicle. There are no animations involved when this happens.

[[File:vehicle seat ids.png|200px|thumb|right|Vehicle seat ids]]

'''Available client side from 1.3.1''' (It will only work with client side vehicles and peds)
{{Important Note|If you used [[setElementPosition]] to spawn the [[ped]]/[[player]], this function will not work and returns '''false'''.}}

==Syntax==
<syntaxhighlight lang="lua">
bool warpPedIntoVehicle ( ped thePed, vehicle theVehicle, [ int seat=0 ] )
</syntaxhighlight>

{{OOP|Set the variable to nil to execute [[removePedFromVehicle]]|[[ped]]:warpIntoVehicle|vehicle|getPedOccupiedVehicle}}

===Required Arguments===
*'''thePed:''' The ped which you wish to force inside the vehicle
*'''theVehicle:''' The vehicle you wish to force the ped into

===Optional Arguments===
{{OptionalArg}}
*'''seat:''' An integer representing the seat ID.
** '''0:''' Front-left
** '''1:''' Front-right
** '''2:''' Rear-left
** '''3:''' Rear-right

===Returns===
Returns ''true'' if the operation is successful, ''false'' otherwise.

==Example==
This example creates a vehicle and warps a ped inside immediately.
<syntaxhighlight lang="lua">
function setupForRace ( )
local RacerPed = createPed ( 252, 0, 0, 3 )
local RaceVehicle = createVehicle ( 411, 4, 0, 3 ) -- create a vehicle.
warpPedIntoVehicle ( RacerPed, RaceVehicle ) -- warp the ped straight into the vehicle
end
addCommandHandler ( "startrace", setupForRace ) -- add a command to start race
</syntaxhighlight>

==Issues==
{{Issues|
{{Issue|475|Network trouble when calling warpPedIntoVehicle on resourceStart}}
}}

==See Also==
{{Ped functions}}
[[ru:warpPedIntoVehicle]]

SetVehicleDirtLevel

2022-01-30T19:02:03Z

Zangomangu: Remove issue from disabled function

__NOTOC__
{{Server client function}}
{{Disabled|This function doesn't work actually. See the bugtracker for updates and more information.}}
This function sets the dirt level on a vehicle.

==Syntax==
<syntaxhighlight lang="lua">
bool setVehicleDirtLevel ( vehicle theVehicle, int dirtLevel )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' The vehicle that you want to set the dirt level from
*'''dirtLevel:''' The dirt level

===Returns===
Returns ''true'' if the dirt level was set on the vehicle, ''false'' if the dirt level was not set or if invalid arguments are specified.

==Example==
<syntaxhighlight lang="lua">
--TODO
</syntaxhighlight>

==See Also==
{{Vehicle functions}}

SetVehicleColor

2022-01-30T19:01:48Z

Zangomangu: Removed fixed issue

__NOTOC__
{{Server client function}}
This function will set the color of a vehicle using either a RGB format, or the [[Vehicle Colors|standard San Andreas color IDs.]] Vehicles can have up to 4 colors, most of the vehicles have 2 colors only.

{{New feature|3.0110|1.1|
==Syntax==
<syntaxhighlight lang="lua">
bool setVehicleColor(vehicle veh, int r1, int g1, int b1, [int r2, int g2, int b2, int r3, int g3, int b3, int r4, int g4, int b4])
</syntaxhighlight>

<syntaxhighlight lang="lua">
bool setVehicleColor(vehicle veh, int p1, int p2, int p3, int p4)
</syntaxhighlight>

{{OOP||[[vehicle]]:setColor}}

===Required Arguments===
*'''theVehicle:''' The [[vehicle]] that you wish to set the color of.
* RGB format:
** '''r1, g1, b1:''' Three integers indicating the red, green and blue components of the first (main) color for the vehicle
* Palette format:
** '''p1, p2, p3, p4:''' Exactly four integers indicating the [[Vehicle Colors|vehicle color IDs]] from the palette. <br> If a vehicle has fewer than four colours, you must still provide four colours, otherwise the RGB format will be used.
===Optional Arguments (RGB format only)===
*'''r2, g2, b2:''' Three integers indicating the red, green and blue components of the second color for the vehicle
*'''r3, g3, b3:''' Three integers indicating the red, green and blue components of the third color for the vehicle
*'''r4, g4, b4:''' Three integers indicating the red, green and blue components of the fourth color for the vehicle
}}
===Returns===
Returns ''true'' if vehicle's color was set, ''false'' if an invalid vehicle or invalid colors were specified.

==Examples==
<section name="Example 1 - RGB format" class="server" show="true">
This example implements a serverside ''random_color'' console command.
<syntaxhighlight lang="lua">
addCommandHandler( 'random_color',
function( uPlayer )
if isPedInVehicle( uPlayer ) then
local uVehicle = getPedOccupiedVehicle( uPlayer )
if uVehicle then
local r, g, b = math.random( 255 ), math.random( 255 ), math.random( 255 )
setVehicleColor( uVehicle, r, g, b )
end
end
end
)
</syntaxhighlight>
</section>

<section name="Example 2 - palette format" class="server" show="true">
This example implements a serverside command for the player to spawn a red and white Banshee, using the palette colors.
<syntaxhighlight lang="lua">
addCommandHandler("banshee", function(player)
local x, y, z = getElementPosition(player)
local rx, ry, rz = getElementRotation(player)
local vehicle = createVehicle(429, x, y, z, 0.0, 0.0, rz, "PALETTE")
setVehicleColor(vehicle, 3, 1, 0, 0)-- A red and white Banshee!
addVehicleUpgrade(vehicle, 1010)
warpPedIntoVehicle(player, vehicle, 0)
outputChatBox("You have spawned a red and white Banshee! I also added NOS for you!", source, 50, 168, 82)
end)
</syntaxhighlight>
</section>

==See Also==
{{Vehicle_functions}}

SetResourceDefaultSetting

2022-01-30T19:01:23Z

Zangomangu: Remove issue from disabled function

__NOTOC__
{{Server function}}
{{Disabled|This function doesn't work actually. See [[#Issues|issues]] for more information.}}
This function is used to set a default setting for a specified [[resource]].


==Syntax==
<syntaxhighlight lang="lua">
bool setResourceDefaultSetting ( resource theResource, string settingName, string/int/float settingValue )
</syntaxhighlight>

===Required Arguments===
*'''theResource:''' the resource where the setting is located
*'''settingName:''' the name of the default setting
*'''settingValue:''' the new value of the setting

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

==Example==
This example checks to see if the server has the freeroam server then sets "spawnmaponstart" to "false".
<syntaxhighlight lang="lua">addEventHandler("onResourceStart",resourceRoot,function()
local freeroamRes = getResourceFromName("Freeroam")
if(freeroamRes)then
setResourceDefaultSetting(freeroamRes,"spawnmaponstart","false")
end
end)
</syntaxhighlight>

==See Also==
{{Resource_functions}}

SetRadioChannel

2022-01-30T19:00:49Z

Zangomangu: Updated issues

__NOTOC__
{{Client function}}
This function sets the heard radio channel, even while not in a vehicle.
{{Note|This function sometimes doesn't work when setting the radio channel to another different from the current one due to unknown reasons. If you experience this issue, simply add setRadioChannel(0) at the beginning of the script, outside any function.}}

==Syntax==
<syntaxhighlight lang="lua">
bool setRadioChannel ( int ID )
</syntaxhighlight>

===Required Arguments===
*'''ID:''' The ID of the radio station you want to play.

{{SoundID}}

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

==Example==
This example adds a command ''setradio'' which can be used to change the current radio station by ID.
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
addCommandHandler ( "setradio",
function ( command, stationID )
local result = setRadioChannel ( tonumber( stationID ) )
if result then -- if we had a valid ID
outputChatBox ( "Changed your radio station to " .. getRadioChannelName ( tonumber ( stationID ) ) .. "!" )
else
outputChatBox ( "Invalid radio station ID, valid ones are 0-12." )
end
end
)
</syntaxhighlight>
</section>

== Issues ==
{{Issues|
{{Issue|423|setRadioChannel doesn't work when outside a vehicle}}
}}

==See Also==

{{Client_audio_functions}}

[[hu:setRadioChannel]]
[[AR:setRadioChannel]]
[[RO:SetRadioChannel]]
[[PT-BR:setRadioChannel]]

SetPedLookAt

2022-01-30T18:59:54Z

Zangomangu: Updated issues

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

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

SetObjectBreakable

2022-01-30T18:58:49Z

Zangomangu: Removed fixed issue

__NOTOC__
{{Client function}}
This function sets an object to be breakable/unbreakable.

==Syntax==
<syntaxhighlight lang="lua">bool setObjectBreakable ( object theObject, bool breakable )</syntaxhighlight>
{{OOP||[[object]]:setBreakable|breakable|isObjectBreakable}}
===Required Arguments===
*'''object''' the [[object]] that's being set.
*'''breakable''' a boolean whether the object is breakable (true) or unbreakable (false).

===Returns===
* ''true'' if the object is now breakable.
* ''false'' if it can't or if invalid arguments are passed.

==Example==
This example creates an object when the resource starts and sets it to be breakable.
<syntaxhighlight lang="lua">function toggleObjectVulnerability()
local object = createObject(1337, 5540.6654, 1020.55122, 1240.545)
if isObjectBreakable(object) then
setObjectBreakable(object, false)
outputChatBox("The object is now not breakable.")
else
setObjectBreakable(object, true)
outputChatBox("The object is now breakable.")
end
end
addEventHandler("onClientResourceStart", resourceRoot, toggleObjectVulnerability)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.3.0-9.03783|}}
==See Also==
{{Client_object_functions}}

SetModelHandling

2022-01-30T18:58:28Z

Zangomangu: Updated issues

{{Server function}}
__NOTOC__
This function is used to change the handling data of all vehicles of a specified model.

==Syntax==
<syntaxhighlight lang="lua">
bool setModelHandling ( int modelId, string property, var value )
</syntaxhighlight>

===Required Arguments===
*'''modelId:''' The [[Vehicle_IDs|vehicle model]] you wish to set the handling of.
*'''property:''' The property you wish to set the handling of the vehicle to, or ''nil'' if you want to reset the all the handling properties.
*'''value:''' The value of the models's handling property you wish to set, or ''nil'' if you want to reset the handling property to its default value.

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

==Handling Properties==
See below a list of valid properties and their required values:
{{Handling Properties}}

==Example==
<section name="Server" class="server" show="true">
This example script changes the handling of all Bullet.
<syntaxhighlight lang="lua">
function handlingChange()
local modelId = 541
setModelHandling(modelId, "mass", 1890)
setModelHandling(modelId, "turnMass", 3780)
setModelHandling(modelId, "dragCoeff", 0.7)
setModelHandling(modelId, "centerOfMass", {0.0, 0.1, -0.2} )
setModelHandling(modelId, "percentSubmerged", 75)
setModelHandling(modelId, "tractionMultiplier", 0.70)
setModelHandling(modelId, "tractionLoss", 0.90)
setModelHandling(modelId, "tractionBias", 0.50)
setModelHandling(modelId, "numberOfGears", 5)
setModelHandling(modelId, "maxVelocity", 407)
setModelHandling(modelId, "engineAcceleration", 50)
setModelHandling(modelId, "engineInertia", 10)
setModelHandling(modelId, "driveType", "awd")
setModelHandling(modelId, "engineType", "petrol")
setModelHandling(modelId, "brakeDeceleration", 11)
setModelHandling(modelId, "brakeBias", 0.45)
setModelHandling(modelId, "ABS", false)
setModelHandling(modelId, "steeringLock", 30)
setModelHandling(modelId, "suspensionForceLevel", 0.80)
setModelHandling(modelId, "suspensionDamping", 0.20)
setModelHandling(modelId, "suspensionHighSpeedDamping", 0.0)
setModelHandling(modelId, "suspensionUpperLimit", 0.10)
setModelHandling(modelId, "suspensionLowerLimit", -0.09)
setModelHandling(modelId, "suspensionFrontRearBias", 0.5)
setModelHandling(modelId, "suspensionAntiDiveMultiplier", 0.6)
setModelHandling(modelId, "seatOffsetDistance", 0.3)
setModelHandling(modelId, "collisionDamageMultiplier", 0.50)
setModelHandling(modelId, "monetary", 1460000)
setModelHandling(modelId, "modelFlags", 0xC0222004)
setModelHandling(modelId, "handlingFlags", 0x1400000)
setModelHandling(modelId, "headLight", 1)
setModelHandling(modelId, "tailLight", 1)
setModelHandling(modelId, "animGroup", 0)
end
addEventHandler("onResourceStart", resourceRoot, handlingChange)
</syntaxhighlight>

This function will reset the handling of Bullet vehicles to its default state.
<syntaxhighlight lang="lua">
function resetHandling()
local modelId = 541
for k,_ in pairs(getModelHandling(modelId)) do
setModelHandling(modelId, k, nil)
end
end
addEventHandler("onResourceStop", resourceRoot, resetHandling)
</syntaxhighlight>
</section>

== Issues ==
{{Issues|
{{Issue|553|setModelHandling doesn't work with already created vehicles}}
{{Issue|1198|"setModelHandling" function doesn't affect vehicles that have been changed using "setElementModel"}}
}}

==See other vehicle functions==
{{Vehicle functions}}

SetJetpackWeaponEnabled

2022-01-30T18:56:39Z

Zangomangu: Updated issues

__NOTOC__
{{Server function}}
This function sets a weapon usable while using the Jetpack.
{{Note|colt 45, sawed-off, tec-9 and uzi are always enabled for the Jetpack and are not affected by this function}}
==Syntax==
<syntaxhighlight lang="lua">bool setJetpackWeaponEnabled(string weapon, bool enabled)</syntaxhighlight>

===Required Arguments===
*'''weapon''' The weapon that's being set usable on a Jetpack. Names can be: (Case is ignored)
{{All Weapon Types}}
*'''enabled''' A bool representing whether the weapon is enabled or disabled.

===Returns===
Returns true, else false if invalid arguments are passed.

==Example==
<syntaxhighlight lang="lua">addEventHandler("onResourceStart",resourceRoot,function()
if setJetpackWeaponEnabled("31",true) then
outputChatBox(getWeaponNameFromID(31).." is now enabled for jetpacks!")
end
end)</syntaxhighlight>

==Example==
<syntaxhighlight lang="lua">
local weapons = {
31,
34,
33,
}

addEventHandler("onResourceStart",resourceRoot,function()
for i,v in ipairs(weapons) do
if setJetpackWeaponEnabled(v,true) then
outputChatBox(getWeaponNameFromID(v).." is now enabled for jetpacks!")
end
end
end
)</syntaxhighlight>

== Issues ==
{{Issues|
{{Issue|508|Texture bug with setJetpackWeaponEnabled.}}
}}

==Requirements==
{{Requirements|1.3.1|n/a|}}
==See Also==
{{World_functions}}

SetElementPosition

2022-01-30T18:55:45Z

Zangomangu: Updated issues

__NOTOC__
{{Shared function}}
This function sets the position of an element to the specified coordinates.
{{Warning|Do not use this function to spawn a [[player]]. It will cause problems with other functions like [[warpPedIntoVehicle]]. Use [[spawnPlayer]] instead.}}

==Syntax==
<syntaxhighlight lang="lua">
bool setElementPosition ( element theElement, float x, float y, float z [, bool warp = true ] )
</syntaxhighlight>
{{OOP||[[element]]:setPosition|position|getElementPosition}}

===Required Arguments===
*'''theElement:''' A valid [[element]] to be moved.
*'''x:''' The x coordinate of the destination.
*'''y:''' The y coordinate of the destination.
*'''z:''' The z coordinate of the destination.

===Optional Arguments===
*'''warp:''' teleports players, resetting any animations they were doing. Setting this to ''false'' preserves the current animation.

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

==Example==
<section name="Server" class="server" show="true">
This example lets admins teleport 5 random players to themselves
<syntaxhighlight lang="lua">
function randomPlayersToLocation(p)
if not isPlayerStaff(p) then return end

local playersOnline = getElementsByType("player")
local amount = #playersOnline

if amount == 0 then return end

for index = 1,(amount > 5 and 5 or amount) do
local player = playersOnline[index]
setElementPosition(player, getElementPosition(p))
end
end
addCommandHandler("randomtp", randomPlayersToLocation)
addCommandHandler("playershere", randomPlayersToLocation)

-- Utility function
local staffACLs = {
aclGetGroup("Admin"),
aclGetGroup("Moderator")
}

function isPlayerStaff(p)
if isElement(p) and getElementType(p) == "player" and not isGuestAccount(getPlayerAccount(p)) then
local object = getAccountName(getPlayerAccount(p))

for _, group in ipairs(staffACLs) do
if isObjectInACLGroup("user." .. object, group) then
return true
end
end
end
return false
end
</syntaxhighlight>
</section>

If you want to put a vehicle or player out of the water or simulate the position-resetting behaviour if CJ goes below the ground too far, then you need to retrieve a recommended coordinate on ground to place the element at. Take a look at [https://forum.mtasa.com/topic/132891-important-helprespawn-vehicle/?do=findComment&comment=1003198 this MTA forums post] for steps in the right direction.

==Issues==
{{Issues|
{{Issue|539|Changing player position when he/she has a jetpack will remove the jetpack and bug when skin is changed}}
{{Issue|529|Player falls from his bike when its teleported by setElementPosition}}
}}

==See Also==
{{Element functions}}

[[hu:setElementPosition]]
[[ru:setElementPosition]]

SetElementHealth

2022-01-30T18:53:08Z

Zangomangu: Added more issues

{{Server client function}}
__NOTOC__
This function sets the health for the specified [[element]]. This can be a [[ped]], [[object]] or a [[vehicle]].
{{Note|In the case of the [[vehicle]] element, the following effects appear, depending on the health value:
*'''650:''' white steam 0%, black smoke 0%
*'''450:''' white steam 100%, black smoke 50%
*'''250:''' white steam 0%, black smoke 100%
*'''249:''' fire with big black smoke
}}

==Syntax==
<syntaxhighlight lang="lua">
bool setElementHealth ( element theElement, float newHealth )
</syntaxhighlight>
{{OOP||[[element]]:setHealth|health|getElementHealth}}

===Required Arguments===
*'''theElement:''' The [[ped]], [[vehicle]] or [[object]] whose health you want to set.
*'''newHealth:''' A float indicating the new health to set for the element.

===Returns===
Returns ''true'' if the new health was set successfully, or ''false'' if invalid arguments were passed.

==Example==
<section name="Server" class="server" show="true">
This example adds a 'hpslap' console command that lets players "slap" others (doing 20 damage).
<syntaxhighlight lang="lua">
function hpSlap ( sourcePlayer, command, targetPlayerName )
-- check if the user has access to it first
if not hasObjectPermissionTo(sourcePlayer, "command.slap", false) then
outputChatBox ( "You cannot use this command.", sourcePlayer )
return false
end
-- look up the player to be slapped
local targetPlayer = getPlayerFromName ( targetPlayerName )
-- if there's a player with such name,
if targetPlayer then
-- subtract 20 from his health
setElementHealth ( targetPlayer, getElementHealth(targetPlayer) - 20 )
else
-- otherwise, output an error message
outputChatBox ( "There is no player named " .. targetPlayerName .. "!", sourcePlayer )
end
end
-- add our function as a handler for "hpslap"
addCommandHandler ( "hpslap", hpSlap )
</syntaxhighlight>
</section>
<section name="Example 1" class="server" show="true">
This example setting health by a command.
<syntaxhighlight lang="lua">
function Health(player, command, amount)
setElementHealth(player, tonumber(amount))
end
addCommandHandler("set", Health)
</syntaxhighlight>
</section>

==Issues==
{{Issues|
{{Issue|414|Using setElementHealth on a dead ped makes it invincible}}
{{Issue|2223|setElementHealth in onClientPlayerDamage bug}}
{{Issue|472|setElementHealth in onClientPedDamage can cause crash}}
}}

==See Also==
{{Element functions}}

SetElementFrozen

2022-01-30T18:10:05Z

Zangomangu: Updated issues

__NOTOC__
{{Server client function}}
This function freezes an element (stops it in its position and disables movement) or unfreezes it.
{{Warning|This function cancels any animation set by setPedAnimation if you freeze the ped.}}

==Syntax==
<syntaxhighlight lang="lua">
bool setElementFrozen ( element theElement, bool freezeStatus )
</syntaxhighlight>
{{OOP||[[element]]:setFrozen|frozen|isElementFrozen}}

===Required Arguments===
*'''theElement:''' The [[element]] whose freeze status we want to change.
*'''freezeStatus:''' A boolean denoting whether we want to freeze (''true'') or unfreeze (''false'') it.

===Returns===
Returns ''true'' if the element was frozen, ''false'' if it wasn't or if invalid arguments are passed.

==Example==
<section name="Serverside example" class="server" show="true">
This example binds the "p" key to a function to freeze/unfreeze the player's current vehicle.
<syntaxhighlight lang="lua">
function toggleFreezeStatus(thePlayer) -- This function freezes the specified player's vehicle, if he's in one
local playerVehicle = getPedOccupiedVehicle(thePlayer) -- Check if player's in vehicle

if playerVehicle then -- if so
local isPlayerVehicleFrozen = isElementFrozen(playerVehicle) -- Check if vehicle is frozen

setElementFrozen(playerVehicle, not isPlayerVehicleFrozen) -- Set opposite state
end
end

local connectedPlayers = getElementsByType("player") -- Get all connected players
local playerElement = false -- Store reference to player

for playerID = 1, #connectedPlayers do -- Loop through each player
playerElement = connectedPlayers[playerID] -- Get player element by accessing it via playerID

bindKey(playerElement, "p", "down", toggleFreezeStatus, "Toggle freeze status") -- Bind function for player
end
</syntaxhighlight>
</section>

==Issues==
{{Issues|
{{Issue|1291|Ped rotation is always zero on client side if ped has been frozed after creating it}}
{{Issue|541|Frozen ped rotation goes wrong with latency reduction enabled}}
{{Issue|442|Client-side setElementFrozen should sync vehicle driven by local player}}
}}

[[ar:SetElementFrozen]]
[[en:SetElementFrozen]]
==See Also==
{{Element_functions}}

SetElementData

2022-01-30T10:46:39Z

Zangomangu: Removed fixed issue

{{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. <br/>
Usage of element data should be disencouraged 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 neccesary (e.g use alternatives such as storing data in tables) is recommended.}}.

{{New items|5.0157|1.5.7-9.20477|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.
}}

==Syntax==

<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 clients(server-side variation) or server(client-side variation)

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

{{New items|5.0157|1.5.7-9.20477|
==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool setElementData ( element theElement, string key, var value [, var syncMode="broadcast"] )
</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 31 characters.)
*'''value:''' The value you wish to store. See [[element data]] for a list of acceptable datatypes.

===Optional Arguments===
*'''syncMode:''' Synchronisation mode.
**''"broadcast"'' - Synchronise to all clients (default behavior). You can also parse ''true'' for this option.
**''"local"'' - Don't synchronise. You can also parse ''false'' for this option.
**''"subscribe"'' - Only synchronise to specific clients. See [[addElementDataSubscriber]] and [[removeElementDataSubscriber]].
</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 31 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 succesfully, ''false'' otherwise.
}}

==Example==
<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>
[[tr:setElementData]]

==See Also==
[[pt-br:SetElementData]]
{{Element_functions}}

SetCursorPosition

2022-01-30T10:43:14Z

Zangomangu: Removed fixed issue

{{Client function}}
__NOTOC__
This function sets the current position of the mouse cursor.

==Syntax==
<syntaxhighlight lang="lua">
bool setCursorPosition ( int cursorX, int cursorY )
</syntaxhighlight>

===Required Arguments===

*'''cursorX:''' Position over the X axis
*'''cursorY:''' Position over the Y axis

===Returns===

Returns ''true'' if the position has been successfully set, ''false'' otherwise.

==Example==
This example sets your cursor position to the center of your screen after using the command ''cursorpos''.
<syntaxhighlight lang="lua">
function centerCursorFunction()
local showing = isCursorShowing ()
if showing then -- if the cursor is showing
local screenX, screenY = guiGetScreenSize () --get the screen size in pixels
setCursorPosition (screenX/2, screenY/2) --set the cursor position to the center of the screen
else
outputChatBox( "Your cursor is not showing." )
end
end
addCommandHandler( "cursorpos", centerCursorFunction )
</syntaxhighlight>

==See Also==
{{Client_input_functions}}

[[hu:setCursorPosition]]

SetChatAlpha

2022-01-30T10:43:03Z

Zangomangu: Removed issues from disabled function

{{Disabled|This function doesn't exists. See issue 7698 on bugtracker.}}
{{Client function}}
This function sets the global alpha value of the in-game chat. The alpha value applies to text output, input line and background colors.
__NOTOC__
==Syntax==
<syntaxhighlight lang="lua">
bool setChatAlpha ( float alpha )
</syntaxhighlight>

===Required Arguments===
*'''alpha:''' the new global alpha value for the in-game chat (0-255)

===Returns===
Returns ''true'' if alpha is a number and resides in a valid range (0-255), ''false'' if alpha is not a number or resides in an invalid range (like 9001).

==Example==
This example makes everybodies chatbox flash in 1 second intervals.
<syntaxhighlight lang="lua">
local startTime = getTickCount()
local interval = 1000 -- time in milliseconds
local baseAlpha = 200 -- the alpha value the chat will at least have
-- valid: 0 - 255

addEventHandler( "onClientRender", root,
function()
local elapsedTime = getTickCount() - startTime
local modAlpha = ( 255 - baseAlpha ) / 2
local alpha = math.sin( elapsedTime / interval * math.pi * 2 ) * modAlpha
+ baseAlpha + modAlpha

setChatAlpha( alpha )
end
)
</syntaxhighlight>

==See Also==
{{GUI_functions}}

SetCameraTarget

2022-01-30T10:42:46Z

Zangomangu: Removed fixed issue

__NOTOC__
{{Server client function}}
This function allows you to set a player's camera to follow other elements instead. Currently supported element type is:
*[[Player]]s

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool setCameraTarget ( player thePlayer [, player target = nil ] )
</syntaxhighlight>
{{OOP||[[player]]:setCameraTarget|cameraTarget|getCameraTarget}}
===Required Arguments===
*'''thePlayer:''' The player whose camera you wish to modify.

===Optional Arguments===
*'''target:''' The player who you want the camera to follow. If none is specified, the camera will target the player.
</section>

<section name="Client 1" class="client" show="true">
<syntaxhighlight lang="lua">
bool setCameraTarget ( player target )
</syntaxhighlight>

===Required Arguments===
*'''target:''' The player who you want the local camera to follow.
</section>

{{New feature/item|3.0132|1.3.1|5212|
<section name="Client 2" class="client" show="true">
This syntax mantains the player targeted by the camera, but makes the camera look at the specified coordinates. It has no effect when the camera doesn't have a target.
<syntaxhighlight lang="lua">bool setCameraTarget ( float targetX, float targetY, float targetZ )</syntaxhighlight>

===Required Arguments===
*'''targetX, targetY, targetZ:''' The target position that you want the local camera to look at.
</section>}}

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

==Example==
This is an example of how one could implement a spectator function. Using the left and right arrow keys you can view other players. Note that this code isn't complete as it doesn't take into account joining or quitting players.
<section class="client" name="Client script" show="true">
<syntaxhighlight lang="lua">
g_Players = getElementsByType("player") -- get a list of all players in the server
for i,aPlayer in ipairs(g_Players) do -- find out what index the local player has in the list
if aPlayer == localPlayer then
g_CurrentSpectated = i
break
end
end

function spectatePrevious() -- decrement the spectate index and spectate the corresponding player
if g_CurrentSpectated == 1 then
g_CurrentSpectated = #g_Players
else
g_CurrentSpectated = g_CurrentSpectated - 1
end
setCameraTarget(g_Players[g_CurrentSpectated])
end

function spectateNext() -- increment the spectate index and spectate the corresponding player
if g_CurrentSpectated == #g_Players then
g_CurrentSpectated = 1
else
g_CurrentSpectated = g_CurrentSpectated + 1
end
setCameraTarget(g_Players[g_CurrentSpectated])
end

-- Bind above functions to arrow keys
bindKey("arrow_l", "down", spectatePrevious)
bindKey("arrow_r", "down", spectateNext)
</syntaxhighlight>
</section>

==See Also==
{{Camera functions}}

[[hu:setCameraTarget]]
[[RO:setCameraTarget]]

SetAccountData

2022-01-30T10:41:49Z

Zangomangu: Removed fixed issue

{{Server function}}
__NOTOC__{{Important Note|You '''MUST''' use the standard ''module.key'' naming for your keys, as shown in the example below. This prevents collisions between different scripts.}}
This function sets a string to be stored in an [[account]]. This can then be retrieved using [[getAccountData]]. Data stored as account data is persistent across user's sessions and maps, unless they are logged into a guest account. Even if logged into a guest account, account data can be useful as a way to store a reference to your own account system, though it's persistence is equivalent to that of using [[setElementData]] on the player's element.

==Syntax==
<syntaxhighlight lang="lua">
bool setAccountData ( account theAccount, string key, var value )
</syntaxhighlight>
{{OOP||[[account]]:setData||getAccountData}}
===Required Arguments===
*'''theAccount:''' The account you wish to retrieve the data from.
*'''key:''' The key under which you wish to store the data
*'''value:''' The value you wish to store. Set to false to remove the data. '''NOTE:''' you cannot store tables as values, but you can use [[toJSON]] strings.

===Returns===
Returns a ''true'' if the account data was set, ''false'' if an invalid argument was specified.

==Example==
For a pirate roleplaying gametype, the amount of money a player has is made persistent by storing it in his account. Note the code uses "piraterpg.money" as key instead of just "money", as the player may be participating in other gametypes that also save his money amount to his account. If both gametypes would use "money" as the account key, they'd overwrite each other's data.
<syntaxhighlight lang="lua">
function onPlayerQuit ( )
-- when a player leaves, store his current money amount in his account data
local playeraccount = getPlayerAccount ( source )
if ( playeraccount ) and not isGuestAccount ( playeraccount ) then -- if the player is logged in
local playermoney = getPlayerMoney ( source ) -- get the player money
setAccountData ( playeraccount, "piraterpg.money", playermoney ) -- save it in his account
end
end

function onPlayerLogin (_, playeraccount )
-- when a player logins, retrieve his money amount from his account data and set it
if ( playeraccount ) then
local playermoney = getAccountData ( playeraccount, "piraterpg.money" )
-- make sure there was actually a value saved under this key (check if playermoney is not false).
-- this will for example not be the case when a player plays the gametype for the first time
if ( playermoney ) then
setPlayerMoney ( source, playermoney )
end
end
end

addEventHandler ( "onPlayerQuit", root, onPlayerQuit )
addEventHandler ( "onPlayerLogin", root, onPlayerLogin )
</syntaxhighlight>

==See Also==
{{Account_functions}}

[[en:setAccountData]]
[[ru:setAccountData]]
[[ar:setAccountData]]
[[es:setAccountData]]

RemoveResourceDefaultSetting

2022-01-30T10:41:25Z

Zangomangu: Remove issue from deprecated function

__NOTOC__
{{Server function}}
{{Disabled|This function doesn't work actually. See [[#Issues|issues]] for more information.}}
This function is used to remove a default setting from specified [[resource]].


==Syntax==
<syntaxhighlight lang="lua">
bool removeResourceDefaultSetting ( resource theResource, string settingName )
</syntaxhighlight>

===Required Arguments===
*'''theResource:''' the resource which setting is to be removed
*'''settingName:''' name of the default setting which is to be removed

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

==Example==
This example would check if the server has the freeroam resource and removes the default settings called "spawnmaponstart".
<syntaxhighlight lang="lua">addEventHandler("onResourceStart",resourceRoot,function()
local freeroamRes = getResourceFromName("Freeroam")
if(freeroamRes)then
removeResourceDefaultSetting(freeroamRes,"spawnmaponstart")
end
end)
</syntaxhighlight>

==See Also==
{{Resource_functions}}

OnPlayerDamage

2022-01-30T10:41:07Z

Zangomangu: Removed fixed issues

__NOTOC__
{{Server event}}
This event is triggered when a player is damaged, in any way.

*This event is not triggered when attacked by a team member if friendly fire is enabled.
*Canceling this event has no effect. Cancel the client-side event [[onClientPlayerDamage]] instead.
*onPlayerDamage doesn't trigger if the damage kills the player, [[onPlayerWasted]] is called instead.

==Parameters==
<syntaxhighlight lang="lua">
player attacker, int damage_causing, int bodypart, float loss
</syntaxhighlight>

*'''attacker''': a [[player]] element representing the player who was the attacker. If there was no attacker this returns false.
*'''damage_causing''': an [[int]] representing the cause of damage, either a [[Weapons|attacker weapon]], or some other [[Damage Types|types of damage]].
*'''bodypart''': an [[int]] representing the bodypart ID the player was hit on when he got damaged.
{{BodyParts}}
*'''loss''': a [[float]] representing the percentage of health the player lost.

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

==Example==
This example causes an instant kill when a player is shot in the head, and announces it in the chatbox.
<syntaxhighlight lang="lua">
function playerDamage_text ( attacker, weapon, bodypart, loss ) --when a player is damaged
if ( bodypart == 9 and attacker and attacker ~= source ) then -- if the body part is 9 (head) and there is an attacker and it wasn't self damage
outputChatBox ( "Headshot!", attacker, 255, 170, 0 ) --output "Headshot" into the chatbox
killPed ( source, attacker, weapon, bodypart ) -- and kill the player
end
end
addEventHandler ( "onPlayerDamage", root, playerDamage_text ) --add an event handler for the onPlayerDamage event
</syntaxhighlight>

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