Multi Theft Auto: Wiki - User contributions [en]

GetVehicleColor

2019-04-03T07:17:43Z

NanoBob: Consistency with other wiki pages

__NOTOC__
{{Server client function}}
This function returns the color of the specified vehicle. A vehicle can have up to four colors.

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

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

===Required Arguments===
*'''theVehicle:''' The [[vehicle]] that you wish to get the color of.
*'''bRGB :''' A boolean specifying whether to return RGB values. A setting of ''false'' will result in the function returning color ids instead.

===Returns===
*Returns 12 [[int|ints]] (if bRGB is ''true'') indicating the red, green and blue components of each of the 4 vehicle colors.
*Returns 4 [[int|ints]] (if bRGB is ''false'') indicating the color ids of each of the 4 vehicle colors.
*Returns ''false'' if the vehicle doesn't exist.

Valid color ids if bRGB is set to false:
{{Vehicle_colors}}
<br>

==Example==
<section name="Server" class="server" show="true">
This will output the 4 colors of any car that the player enters.
<syntaxhighlight lang="lua">
function playerEnterVehicle ( theVehicle, seat, jacked )
-- Get the colors of the car and store them to 4 seperate variables
local color1, color2, color3, color4 = getVehicleColor ( theVehicle )
-- Output the four retrieved car colors into the chatbox
outputChatBox ( "Car color 1: " .. color1 )
outputChatBox ( "Car color 2: " .. color2 )
outputChatBox ( "Car color 3: " .. color3 )
outputChatBox ( "Car color 4: " .. color4 )
end
addEventHandler ( "onPlayerVehicleEnter", getRootElement(), playerEnterVehicle )
</syntaxhighlight>
</section>

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

GetElementAngularVelocity

2019-04-03T07:16:42Z

NanoBob: Consistency with other wiki pages

__NOTOC__
{{Server client function}}
{{New feature/item|3.0156|1.5.5|14165|Gets the current angular velocity of a specified, supported element.}}

==Syntax==
<syntaxhighlight lang="lua">
float, float, float getElementAngularVelocity ( element theElement )
</syntaxhighlight>
{{OOP||[[element]]:getAngularVelocity|angularVelocity|setElementAngularVelocity}}
===Required Arguments===
*'''theElement:''' The [[element]] to retrieve the angular velocity from. Can be either a [[player]], [[ped]], [[object]], [[vehicle]] or a [[Element/Weapon|custom weapon]]. '''Server side supports only vehicles currently.'''

===Returns===
Returns three floats describing the x, y and z rotation

==Example==
<syntaxhighlight lang="lua">
addCommandHandler("getangularvelocity", function(player)
--retrieve angular velocity of the player
local avx, avy, avz = getElementAngularVelocity(player)
outputChatBox("Your current angular velocity is: X: "..avx.." Y: "..avy.." Z: "..avz, player, 0, 255, 0, false)
end)
</syntaxhighlight>

==Requirements==
{{Requirements|1.5.5-9.14060|1.5.5-9.14060|}}

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

GetVersion

2019-04-02T13:47:59Z

NanoBob: The point of this example was to implement a fallback to a method when running an older version. However someone (4 years ago) changed this which ended up with the example making no sense at all.

__NOTOC__
{{Server client function}}

This function gives you various version information about MTA and the operating system.

''Note:'' Clientside will return the version from the player, and the server-sided will return version from the server.

==Syntax==
<syntaxhighlight lang="lua">table getVersion ( )</syntaxhighlight>

===Returns===
Returns a table with version information. Specifically these keys are present in the table:
*'''number:''' the MTA server or client version (depending where the function was called) in pure numerical form, e.g. ''"256"''
*'''mta:''' the MTA server or client version (depending where the function was called) in textual form, e.g. ''"1.0"''
*'''name:''' the full MTA product name, either ''"MTA:SA Server"'' or ''"MTA:SA Client"''.
*'''netcode:''' the netcode version number.
*'''os:''' returns the operating system on which the server or client is running
*'''type:''' the type of build. can be:
**'''"Nightly rX"''' - A nightly development build. '''X''' represents the nightly build revision.
**'''"Custom"''' - A build compiled manually
**'''"Release"''' - A build that is publicly released (provisional).
*'''tag:''' the build tag (from 1.0.3 onwards). Contains infomation about the underlying version used. i.e. The final version of 1.0.3 has the build tag of "1.0.3 rc-9". (This can be confirmed by using the console command 'ver'.)
*'''sortable:''' a 15 character sortable version string (from 1.0.4 onwards). Format of the string is described in [[getPlayerVersion]].

==Example==
'''Example 1:''' This example will make a script compatible only with version 1.0:
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function setHoboSkin(playerSource)
local version = getVersion()
if version.number < 256 then -- MTA 1.0 version number is 0x0100
setPlayerSkin(playerSource, 137)
else
setElementModel(playerSource, 137)
end
end
addCommandHandler("hobo", setHoboSkin)
</syntaxhighlight>
</section>

'''Example 2:''' This client and server example will kick players that have anything earlier than the final released version of 1.0.3:
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function sendVersion()
-- Send local player version to the server
triggerServerEvent("onNotifyPlayerVersion", resourceRoot, getVersion())
end
addEventHandler("onClientResourceStart", resourceRoot, sendVersion)
</syntaxhighlight>
</section><section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function handlePlayerVersion(version)
if version.number > 256 + 3 then -- Allow anything above 1.0.3
return
end
if version.number == 256 + 3 then -- Check further if it is exactly 1.0.3
if version.type == "Release" then -- Check further if it is the "Release" type
local _, _, buildnumber = string.find(version.tag or "", "(%d)$") -- Extract the build number if there
buildnumber = tonumber(buildnumber) or 0
if buildnumber >= 9 then -- Allow 9 and above
return
end
end
end
outputConsole("Kicking player as below 1.0.3 Release build 9")
kickPlayer(client, "Upgrade your version at www.mtasa.com")
end
addEvent("onNotifyPlayerVersion", true)
addEventHandler("onNotifyPlayerVersion", resourceRoot, handlePlayerVersion)
</syntaxhighlight>
</section>

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

SetWeaponProperty

2019-03-08T15:36:02Z

NanoBob: Changed layout to be more consistent with the rest of the wiki

{{Server client function}}
__NOTOC__
<section name="Server" class="server" show="true">
This function sets the weapon property of the specified weapons specified weapon type. See lower down the page for documentation related to weapon creation.

==Syntax==
<syntaxhighlight lang="lua">bool setWeaponProperty ( int weaponID/string weaponName, string weaponSkill, string property, int/float theValue )</syntaxhighlight>

==Required Arguments==
*'''weaponID:''' The ID or name of the [[Weapons|weapon]] you want to set a property of. Names can be:
{{Some Weapon Types}}
*'''weaponSkill:''' Either: "pro", "std" or "poor". The player must have this skill level set to have the effect.
*'''property:''' The property you want to set the value of:
{{Weapon Properties Writable}}
*'''theValue:''' The value to set the property to.

==Returns==
On success:

'''bool:''' Returns true if the weapon property was successfully set

On failure:

'''bool:''' Returns false if the weapon property was unable to be set
</section>

<section name="Client" class="client" show="true">
<p>The client side function only applies to custom weapons created client sided</p>
==Syntax==
<syntaxhighlight lang="lua">bool setWeaponProperty ( weapon theWeapon, string strProperty, value theValue )</syntaxhighlight>
{{OOP||[[Element/Weapon|weapon]]:setProperty||getWeaponProperty}}

==Required Arguments==

* '''theWeapon:''' the weapon to change the property of.
* '''strProperty:''' the property to edit:
{{Custom Weapon Properties Writable}}
* '''theValue:''' The value to set the property to.

==Returns==
Returns ''true'' if the property was set.
</section>

==Example==

<section name="Server" class="server" show="true">
This example sets the weapon range of the M4 at poor skill level to 75
<syntaxhighlight lang="lua">
local rangeSet = setWeaponProperty(31, "poor", "weapon_range", 75)
if (rangeSet) then
outputChatBox("M4 range at poor skill is set now 75!")
end
</syntaxhighlight>

This example makes the silenced pistol dual wielded at pro skill level
<syntaxhighlight lang="lua">
setWeaponProperty(23, "pro", "flags", 0x000800) -- Warning - Depends on the current flag setting
setWeaponProperty(23, "pro", "flags", 0x000002) -- Warning - Depends on the current flag setting
setWeaponProperty(23, "pro", "maximum_clip_ammo", 34)
</syntaxhighlight>

This examples doubles the range of the colt 45 hand gun
<syntaxhighlight lang="lua">
setWeaponProperty(22, "poor", "weapon_range", 70)
setWeaponProperty(22, "std", "weapon_range", 70)
setWeaponProperty(22, "pro", "weapon_range", 70)
</syntaxhighlight>

This example makes the minigun able to fire all its ammo without the short reload time
<syntaxhighlight lang="lua">
setWeaponProperty("minigun", "pro", "maximum_clip_ammo", 1000)
</syntaxhighlight>

This example turns off auto aim for all weapons
<syntaxhighlight lang="lua">
function setAutoAimForAllWeapons( bEnable )
weaponList = { "colt 45", "silenced", "deagle", "shotgun", "sawed-off", "combat shotgun", "uzi", "mp5", "ak-47", "m4", "tec-9", "rifle", "sniper", "minigun" }
for _,weapon in ipairs( weaponList ) do
for _,skill in ipairs( { "poor", "std", "pro" } ) do
setWeaponPropertyFlag( weapon, skill, 0x0001, not bEnable )
end
end
end

-- Set or clear an individual weapon flag bit
function setWeaponPropertyFlag( weapon, skill, flagBit, bSet )
local bIsSet = bitAnd( getWeaponProperty(weapon, skill, "flags"), flagBit ) ~= 0
if bIsSet ~= bSet then
setWeaponProperty(weapon, skill, "flags", flagBit)
end
end

-- Turn off auto aim
setAutoAimForAllWeapons( false )
</syntaxhighlight>

</section>

==Requirements==
{{Requirements|1.3|1.3.0-9.04555|}}

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.4.0-9.06339|Added 'fire_rotation' property}}

==See also==
{{Weapon functions}}

CreateMarker

2019-03-08T09:48:49Z

NanoBob: Missing argument type

__NOTOC__
{{Server client function}}

[[Image:Mtasa_markers.png|thumb|337px|This image shows all the different marker types available using this function.]]

This function creates a marker. A marker is a 3D model in the world that can highlight a particular point or area, often used to instruct players where to go to perform actions such as entering buildings.

There are various limits that govern the maximum number of each type that can be visible at once. These are:
* Coronas: 32
* Checkpoints, Rings, Cylinders and Arrows combined: 32

You are able to create as many markers as you wish (memory and element limit permitting), but the player will only be able to see the nearest ones up to the limit.

<br><br><br><br>

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
marker createMarker ( float x, float y, float z [, string theType = "checkpoint", float size = 4.0, int r = 0, int g = 0, int b = 255, int a = 255, bool visibleTo = getRootElement( ) ] )
</syntaxhighlight>
{{OOP||Marker}}
===Required Arguments===
* '''x''': A floating point number representing the X coordinate on the map.
* '''y''': A floating point number representing the Y coordinate on the map.
* '''z''': A floating point number representing the Z coordinate on the map.

===Optional arguments===
{{OptionalArg}}
* '''theType''': The visual type of the marker to be created. Possible values:
{{Marker_types}}
* '''size''': The diameter of the marker to be created, in meters.
* '''r''': An integer number representing the amount of red to use in the colouring of the marker (0 - 255).
* '''g''': An integer number representing the amount of green to use in the colouring of the marker (0 - 255).
* '''b''': An integer number representing the amount of blue to use in the colouring of the marker (0 - 255).
* '''a''': An integer number representing the amount of alpha to use in the colouring of the marker (0 - 255 where 0 is transparent and 255 is opaque).
* '''visibleTo''': This defines which elements can see the marker. Defaults to visible to everyone. See [[visibility]].
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
marker createMarker ( float x, float y, float z [, string theType = "checkpoint", float size = 4.0, int r = 0, int g = 0, int b = 255, int a = 255 ] )
</syntaxhighlight>
{{OOP||Marker}}
===Required Arguments===
* '''x''': A floating point number representing the X coordinate on the map.
* '''y''': A floating point number representing the Y coordinate on the map.
* '''z''': A floating point number representing the Z coordinate on the map.

===Optional arguments===
{{OptionalArg}}
* '''theType''': The visual type of the marker to be created. Possible values:
{{Marker_types}}
* '''size''': The diameter of the marker to be created, in meters.
* '''r''': An integer number representing the amount of red to use in the colouring of the marker (0 - 255).
* '''g''': An integer number representing the amount of green to use in the colouring of the marker (0 - 255).
* '''b''': An integer number representing the amount of blue to use in the colouring of the marker (0 - 255).
* '''a''': An integer number representing the amount of alpha to use in the colouring of the marker (0 - 255 where 0 is transparent and 255 is opaque).
</section>

===Returns===
Returns the [[marker]] element that was created, or ''false'' if the arguments are incorrect.

==Example==
<section name="Example 1" class="server" show="true">
This example creates a marker next to the player when they type 'createmarker':
<syntaxhighlight lang="lua">
-- this function is called whenever someone types 'createmarker' in the console:
function consoleCreateMarker ( thePlayer, commandName )
if ( thePlayer ) then
local x, y, z = getElementPosition ( thePlayer ) -- get the player's position
-- create a cylindrical marker next to the player:
local theMarker = createMarker ( x + 2, y + 2, z, "cylinder", 1.5, 255, 255, 0, 170 )
if ( theMarker ) then -- check if the marker was created successfully
outputConsole ( "Marker created successfully", thePlayer )
else
outputConsole ( "Failed to create marker", thePlayer )
end
end
end
addCommandHandler ( "createmarker", consoleCreateMarker )
</syntaxhighlight>
</section>

==See Also==
{{Marker functions}}
[[ru:createMarker]]
[[ar:createMarker]]
[[pl:createMarker]]

GetElementData

2019-03-08T09:21:10Z

NanoBob: Missing argument type

__NOTOC__
{{Server client function}}
This function retrieves [[element data]] attached to an element under a certain key.

==Syntax==
<syntaxhighlight lang="lua">var getElementData ( element theElement, string key [, bool inherit = true] )</syntaxhighlight>
{{OOP||[[element]]:getData||setElementData}}

===Required Arguments===
*'''theElement:''' This is the element with data you want to retrieve.
*'''key:''' The name of the element data entry you want to retrieve. (Maximum 31 characters.)

===Optional Arguments===
*'''inherit:''' - toggles whether or not the function should go up the hierarchy to find the requested key in case the specified element doesn't have it.

===Returns===
This function returns a ''variable'' containing the requested element data, or ''false'' if the element or the element data does not exist. When getting data corresponding to a XML attribute, this is always a ''string''.

==Example==
This example stores the tick count when a player joins and then allows players to see how long they are connected using a console function 'joinTime'.
<section show="true" name="Server" class="server">
<syntaxhighlight lang="lua">
function joinTime ( )
setElementData ( source, "joinTime", getTickCount() ) -- Store the current tick count in the player's data with the key 'joinTime'
end
-- Make our 'joinTime' function be called when a player joins
addEventHandler ( "onPlayerJoin", root, joinTime )

function showJoinTime ( source, commandName, playerName )
if ( playerName ) then -- see if a player was specified
thePlayer = getPlayerFromName ( playerName ) -- get the player element for the specified player
if ( thePlayer ) then -- if one was found...
local timeOnline = (getTickCount() - getElementData ( thePlayer, "joinTime" )) / 1000 -- calculates the time since join
outputChatBox ( getPlayerName ( thePlayer ).." joined "..timeOnline.." seconds ago", source ) -- output the player's join time
else
outputChatBox ( "Couldn't find '" .. playerName .. "'", source ) -- display an error
end
else
-- display when the player who used the function joined and inform how to see other people's join time
local timeOnline = (getTickCount() - getElementData ( source, "joinTime" )) / 1000 -- calculate the time since join
outputChatBox ( "You joined " ..timeOnline.." seconds ago", source )
outputChatBox ( "Use 'join_time <player name>' to see other people's join time", source )
end
end
-- Add a console command joinTime, that takes an optional parameter of a player's name
addCommandHandler ( "joinTime", showJoinTime )
</syntaxhighlight>
</section>

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

CreateBlipAttachedTo

2019-03-08T09:20:13Z

NanoBob: Missing argument type

__NOTOC__
{{Server client function}}
This function creates a [[blip]] that is attached to an [[element]]. This blip is displayed as an icon on the client's radar and will 'follow' the element that it is attached to around.

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
blip createBlipAttachedTo ( element elementToAttachTo [, int icon = 0, int size = 2, int r = 255, int g = 0, int b = 0, int a = 255, int ordering = 0, float visibleDistance = 16383.0, element visibleTo = getRootElement( ) ] )
</syntaxhighlight>
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
blip createBlipAttachedTo ( element elementToAttachTo [, int icon = 0, int size = 2, int r = 255, int g = 0, int b = 0, int a = 255, int ordering = 0, float visibleDistance = 16383.0 ] )
</syntaxhighlight>
</section>

{{OOP||[[Blip]].createAttachedTo||}}

===Required Arguments===
*'''elementToAttachTo:''' The [[element]] to attach the marker to.

===Optional Arguments===
{{OptionalArg}}
*'''icon:''' The icon that the radar blips should be. Valid values can be seen at [[Radar Blips]]
*'''size:''' The size of the radar blip. Only applicable to the ''Marker'' icon. Default value is 2. Maximum is 25.
*'''r:''' The amount of red in the blip's color (0 - 255). Only applicable to the ''Marker'' icon. Default is 255.
*'''g:''' The amount of green in the blip's color (0 - 255). Only applicable to the ''Marker'' icon. Default is 0.
*'''b:''' The amount of blue in the blip's color (0 - 255). Only applicable to the ''Marker'' icon. Default is 0.
*'''a:''' The amount of alpha in the blip's color (0 - 255). Only applicable to the ''Marker'' icon. Default is 255.
{{New feature/item|3|1.0||
*'''ordering:''' This defines the blip's Z-level ordering (-32768 - 32767). Default is 0.
*'''visibleDistance:''' The maximum distance from the camera at which the blip is still visible (0-65535)
}}
<section name="Server" class="server" show="true">
*'''visibleTo:''' What elements can see the blip. Defaults to visible to everyone. See [[visibility]].
</section>

===Returns===
Returns a [[blip]] if the blip was created succesfully, or ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
This example creates a radar blip attached to a random player, visible to everyone. The blip will follow the player around as they move. This could be used for manhunt, to emphasise a random player.
<syntaxhighlight lang="lua">
-- Pick a random player
function setupRandomRobber ()
local myPlayer = getRandomPlayer ()
-- Create a radar blip at the player's position, with a 'cash' icon and only visible to everyone (no 'visibleTo' parameter)
local myBlip = createBlipAttachedTo ( myPlayer, 52 )
end
</syntaxhighlight>
</section>

==See Also==
{{Blip_functions}}

[[hu:createBlipAttachedTo]]
[[RU:createBlipAttachedTo]]

CreateBlip

2019-03-08T09:19:30Z

NanoBob: Missing return type

__NOTOC__
{{Server client function}}
This function creates a [[blip]] [[element]], which is displayed as an icon on the client's radar.

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
blip createBlip ( float x, float y, float z [, int icon = 0, int size = 2, int r = 255, int g = 0, int b = 0, int a = 255, int ordering = 0, float visibleDistance = 16383.0, element visibleTo = getRootElement( ) ] )
</syntaxhighlight>
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
blip createBlip ( float x, float y, float z [, int icon = 0, int size = 2, int r = 255, int g = 0, int b = 0, int a = 255, int ordering = 0, float visibleDistance = 16383.0 ] )
</syntaxhighlight>
</section>
{{OOP||[[Blip]]}}
===Required Arguments===
*'''x:''' The x position of the blip, in world coordinates.
*'''y:''' The y position of the blip, in world coordinates.
*'''z:''' The z position of the blip, in world coordinates.

===Optional Arguments===
{{OptionalArg}}
*'''icon:''' The icon that the radar blips should be. Valid values can be seen at [[Radar Blips]]
*'''size:''' The size of the radar blip. Only applicable to the ''Marker'' icon. Default is 2. Maximum is 25.
*'''r:''' The amount of red in the blip's color (0–255). Only applicable to the ''Marker'' icon. Default is 255.
*'''g:''' The amount of green in the blip's color (0–255). Only applicable to the ''Marker'' icon. Default is 0.
*'''b:''' The amount of blue in the blip's color (0–255). Only applicable to the ''Marker'' icon. Default is 0.
*'''a:''' The amount of alpha in the blip's color (0–255). Only applicable to the ''Marker'' icon. Default is 255.
{{New feature/item|3|1.0||
*'''ordering:''' This defines the blip's Z-level ordering (-32768–32767). Default is 0.
*'''visibleDistance:''' The maximum distance from the camera at which the blip is still visible (0–65535).
}}
<section name="Server" class="server" show="true">
*'''visibleTo:''' This defines which elements can see the blip. Defaults to visible to everyone. See [[visibility]].
</section>

==Returns==
Returns an [[element]] of the [[blip]] if it was created successfully, ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
'''Example 1:''' This example creates a radar blip at a random player's position and makes it so that it is only visible to that player.
<syntaxhighlight lang="lua">
-- Pick a random player
local myPlayer = getRandomPlayer( )
-- Retrieve the player's position and store it in the variables x, y and z
local x, y, z = getElementPosition( myPlayer )
-- Create a radar blip at the player's position, with a 'cash' icon and only visible to the player
local myBlip = createBlip( x, y, z, 51, 0, 0, 0, 255, myPlayer )
</syntaxhighlight>

'''Example 2:''' This example attaches a blip to a player. You can attach a blip to an element by just setting the blip's parent to that element.
<syntaxhighlight lang="lua">
-- Pick a random player
local myPlayer = getRandomPlayer( )
-- Create a radar blip in the middle of the map
local myBlip = createBlip( 0, 0, 0 )
-- Make the player the parent of the blip, so that the blip follows the player around
setElementParent( myBlip, myPlayer )
</syntaxhighlight>
</section>

==See Also==
{{Blip_functions}}

[[HU:createBlip]]
[[AR:createBlip]]
[[es:createBlip]]
[[DE:createBlip]]
[[PL:createBlip]]

GetPlayerMoney

2019-03-08T09:00:36Z

NanoBob: The return value in the server block was inconsistent with almost any other page on the wiki (and even the client block on the same page)

__NOTOC__
{{Server client function}}
Returns the amount of money a player currently has.

'''Note:''' The amount may vary between the server and client, you shouldn't trust the client side value to always be accurate.

==Syntax==
<section show="true" name="Server" class="server">
<syntaxhighlight lang="lua">int getPlayerMoney ( player thePlayer )</syntaxhighlight>
{{OOP||[[player]]:getMoney|money|setPlayerMoney}}
===Required Arguments===
*'''thePlayer:''' The player you wish the retrieve the amount of money from.

===Returns===
Returns an integer with the amount of money the specified player has, ''false'' if the player is invalid.
</section>

<section show="true" name="Client" class="client">
<syntaxhighlight lang="lua">int getPlayerMoney ( )</syntaxhighlight>
{{OOP||[[Player]].getMoney||setPlayerMoney}}
===Returns===
Returns an integer with the amount of money the local player has.
</section>

==Example==
<section show="true" name="Server" class="server">
When a player types '/checkMoney' this example retrieves the player's money and outputs a message according to the value.
<syntaxhighlight lang="lua">
function checkMoney(thePlayer, command)
local money = getPlayerMoney(thePlayer) -- get the amount of money from the player who entered the command
if (money > 1000) then -- if money is more than 1000
outputChatBox("You are rich: " .. tostring(money), thePlayer) -- output this message together with the money
else
outputChatBox("Poor guy...", thePlayer) -- and else, output this message
end
end
addCommandHandler("checkMoney", checkMoney) -- add the console command
</syntaxhighlight>
</section>

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

[[pt-br:getPlayerMoney]]
[[ru:getPlayerMoney]]
[[tr:getPlayerMoney]]

GuiGridListSetSelectionMode

2019-03-06T12:48:44Z

NanoBob: For more consistency

__NOTOC__
{{Client function}}
This function sets the selection mode of a gui gridlist. For example, the MTA ''server browser'' selects a whole row, while the ''Controls'' dialog selects a single cell. To select multiple items you must be holding down 'ctrl'.

==Syntax==
<syntaxhighlight lang="lua">
bool guiGridListSetSelectionMode ( gui-Element gridlist, int mode )
</syntaxhighlight>
{{OOP||[[Element/GUI/Gridlist|GuiGridList]]:setSelectionMode|selectionMode}}

===Required Arguments===
*'''gridlist:''' The gridlist in which you wish to set the selection mode.
*'''mode:''' The mode of the selection. Can be the following values:
**'''0:''' Single row selection
**'''1:''' Multiple row selection
**'''2:''' Single cell selection
**'''3:''' Multiple cell selection
**'''4:''' Nominated(First) single column selection
**'''5:''' Nominated(First) multiple column selection
**'''6:''' Single column selection
**'''7:''' Multiple column selection
**'''8:''' Nominated(First) single row selection
**'''9:''' Nominated(First) multiple row selection

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

==Example==
This example creates a grid list with 3 columns and 3 rows, each with text describing its position in the grid list. Also, the cursor is turned on. The player can use the command 'setmode #' to change how the grid list can be selected.
<syntaxhighlight lang="lua">function clientsideResourceStart ()
--Create a gridlist
myGridList = guiCreateGridList ( 0.35, 0.35, 0.4, 0.1, true )
--Create a column for myGridList to add rows into
columnA = guiGridListAddColumn ( myGridList, "columnA Title", 0.3 )
columnB = guiGridListAddColumn ( myGridList, "columnA Title", 0.3 )
columnC = guiGridListAddColumn ( myGridList, "columnA Title", 0.3 )
--Create a row for columnA
rowA = guiGridListAddRow ( myGridList )
rowB = guiGridListAddRow ( myGridList )
rowC = guiGridListAddRow ( myGridList )
--Set the text of columnA, rowA to "Hello World!"
guiGridListSetItemText ( myGridList, rowA, columnA, "rowA ColumnA", false, false )
guiGridListSetItemText ( myGridList, rowB, columnA, "rowB ColumnA", false, false )
guiGridListSetItemText ( myGridList, rowC, columnA, "rowC ColumnA", false, false )
guiGridListSetItemText ( myGridList, rowA, columnB, "rowA ColumnB", false, false )
guiGridListSetItemText ( myGridList, rowB, columnB, "rowB ColumnB", false, false )
guiGridListSetItemText ( myGridList, rowC, columnB, "rowC ColumnB", false, false )
guiGridListSetItemText ( myGridList, rowA, columnC, "rowA ColumnC", false, false )
guiGridListSetItemText ( myGridList, rowB, columnC, "rowB ColumnC", false, false )
guiGridListSetItemText ( myGridList, rowC, columnC, "rowC ColumnC", false, false )
showCursor ( true )
end
addEventHandler ( "onClientResourceStart", resourceRoot, clientsideResourceStart )

--The player types 'setmode' to activate this function. Additionaly, the player needs
--to type a modeNumber. Ex: 'setmode 5', 5 would be stored as modeNumber
function setSelectionMode ( commandName, modeNumber )
--The player enters the command "setmode #". The modeNumber entry will be a string
--argument. Ex: "9" "nine". Attempt to change modeNumber into a number argument.
modeNumber = tonumber(modeNumber)
--If the selection mode was successfully changed, output a message saying which
--mode it changed to. Otherwise, list reasons why it did not work.
if ( guiGridListSetSelectionMode ( myGridList, modeNumber ) ) then
outputChatBox ( "Changed grid list selection mode to: "..modeNumber )
else
outputChatBox ( "modeNumber must be a number and be between 0 and 9" )
end
end
addCommandHandler ( "setmode", setSelectionMode )</syntaxhighlight>

==See Also==
{{GUI functions}}
{{GUI_events}}

CreateEffect

2019-03-06T12:19:40Z

NanoBob: /* Syntax */

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

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

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

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

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

--There are 82 effects

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

addCommandHandler("createEffect", function(_, effectIndex)
effectIndex = tonumber(effectIndex)
if effectIndex and type(effectIndex) == "number" then
if effectIndex > 0 and effectIndex <= #effectNames then
createEffect(effectNames[effectIndex], Vector3( getElementPosition( getLocalPlayer() ) ), 0, 0, 0)
end
end
end)

--Example Command: /createEffect 3

</syntaxhighlight>

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

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

DxGetPixelColor

2019-03-06T12:18:50Z

NanoBob: /* Returns */

{{Client function}}
__NOTOC__
This function gets the color of a single pixel from [[Texture_pixels|pixels]] contained in a string. It only works with ''''plain'''' format pixels.

==Syntax==
<syntaxhighlight lang="lua">
int, int, int, int dxGetPixelColor( string pixels, int x, int y )
</syntaxhighlight>

===Required Arguments===
*'''pixels :''' The pixels to use
*'''x:''' The X coordinate for the pixel
*'''y:''' The Y coordinate for the pixel

==Returns==
Returns 4 ''int''s representing the rgba color value of the pixel if succesful, or ''false'' if invalid arguments were passed to the function.

==Example==
<syntaxhighlight lang="lua">
local texture = dxCreateTexture(4,4) --Create a texture
local pixel = dxGetTexturePixels(texture) --Get pixel element
local sx,sy = dxGetPixelsSize(pixel) --Get pixel size
local tab = {} --Define a table
for i=0,sx-1 do --From 0th pixel to 3th pixel in width
tab[i+1] = {} --Define a table
for j=0,sy-1 do --From 0th pixel to 3th pixel in height
local r,g,b,a = dxGetPixelColor(pixel,i,j) --Get pixel color
tab[i+1][j+1] = {r,g,b,a} --Save the color in the table
end
end
</syntaxhighlight>

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

==See Also==
{{Drawing_functions}}

[[hu:dxGetPixelColor]]

DxGetPixelColor

2019-03-06T12:17:37Z

NanoBob: /* Syntax */

{{Client function}}
__NOTOC__
This function gets the color of a single pixel from [[Texture_pixels|pixels]] contained in a string. It only works with ''''plain'''' format pixels.

==Syntax==
<syntaxhighlight lang="lua">
int, int, int, int dxGetPixelColor( string pixels, int x, int y )
</syntaxhighlight>

===Required Arguments===
*'''pixels :''' The pixels to use
*'''x:''' The X coordinate for the pixel
*'''y:''' The Y coordinate for the pixel

==Returns==
Returns the color of pixel if successful, or ''false'' if invalid arguments were passed to the function.

==Example==
<syntaxhighlight lang="lua">
local texture = dxCreateTexture(4,4) --Create a texture
local pixel = dxGetTexturePixels(texture) --Get pixel element
local sx,sy = dxGetPixelsSize(pixel) --Get pixel size
local tab = {} --Define a table
for i=0,sx-1 do --From 0th pixel to 3th pixel in width
tab[i+1] = {} --Define a table
for j=0,sy-1 do --From 0th pixel to 3th pixel in height
local r,g,b,a = dxGetPixelColor(pixel,i,j) --Get pixel color
tab[i+1][j+1] = {r,g,b,a} --Save the color in the table
end
end
</syntaxhighlight>

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

==See Also==
{{Drawing_functions}}

[[hu:dxGetPixelColor]]

DxDrawCircle

2019-03-06T12:14:16Z

NanoBob: /* Syntax */

{{Client Function}}
<lowercasetitle/>
__NOTOC__
{{New feature/item|3.0156|1.5.5|13977|This function draws a circle shape on the screen - rendered for '''one''' frame. This should be used in conjunction with [[onClientRender]] in order to be display continuously.}}

==Syntax==
<syntaxhighlight lang="lua">bool dxDrawCircle ( float posX, float posY, float radius [, float startAngle = 0.0, float stopAngle = 360.0, color theColor = white,
color theCenterColor = theColor, int segments = 32, int ratio = 1, bool postGUI = false ] )</syntaxhighlight>

===Required Arguments===
[[Image:DxDrawCircle_Saml1er.png|thumb|An example of how dxDrawCircle function works in practice.]]

* '''posX''': An integer representing the '''absolute''' X position of the circle center, represented by pixels on the screen.
* '''posY''': An integer representing the '''absolute''' Y position of the circle center, represented by pixels on the screen.
* '''radius''': An integer representing the radius scale of the circle that is being drawn.

===Optional Arguments===
{{OptionalArg}}
* '''startAngle''': An integer representing the angle of the first point of the circle.
* '''stopAngle''': An integer representing the angle of the last point of the circle.
* '''theColor''': An integer of the hex color, produced using [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
* '''theCenterColor''': An integer of the hex color, produced using [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
* '''segments''': An integer ranging from 3-1024 representing how many triangles are used to form the circle, more segments = smoother circle. Note: using lots of segments may cause lag.
* '''ratio''': Ratio between width and height, e.g: 2 would mean that the width of the circle is 2 times the height.
* '''postGUI''': A bool representing whether the circle should be drawn on top of or behind any ingame GUI (rendered by CEGUI).

===Returns===
Returns ''true'' if the creation of the 2D circle was successful, ''false'' otherwise.

==Example==
This function draws a rectangle with rounded corners.
<syntaxhighlight lang="lua">
function dxDrawRoundedRectangle(x, y, rx, ry, color, radius)
rx = rx - radius * 2
ry = ry - radius * 2
x = x + radius
y = y + radius

if (rx >= 0) and (ry >= 0) then
dxDrawRectangle(x, y, rx, ry, color)
dxDrawRectangle(x, y - radius, rx, radius, color)
dxDrawRectangle(x, y + ry, rx, radius, color)
dxDrawRectangle(x - radius, y, radius, ry, color)
dxDrawRectangle(x + rx, y, radius, ry, color)

dxDrawCircle(x, y, radius, 180, 270, color, color, 7)
dxDrawCircle(x + rx, y, radius, 270, 360, color, color, 7)
dxDrawCircle(x + rx, y + ry, radius, 0, 90, color, color, 7)
dxDrawCircle(x, y + ry, radius, 90, 180, color, color, 7)
end
end
dxDrawRoundedRectangle(350, 50, 100, 100, tocolor(0, 255, 0, 255), 20)
</syntaxhighlight>

==See Also==
{{Drawing_functions}}

[[hu:dxDrawCircle]]

GetTimers

2019-03-06T11:26:06Z

NanoBob: /* Syntax */

__NOTOC__
{{Server client function}}
This function returns a table of all active timers that the resource that calls it has created. Alternatively, only the timers with a remaining time less than or equal to a certain value can be retrieved.

==Syntax==
<syntaxhighlight lang="lua">
table getTimers ( [ int theTime = nil ] )
</syntaxhighlight>

===Optional Arguments===
*'''theTime:''' The maximum time left (in milliseconds) on the timers you wish to retrieve.

===Returns===
Returns a table of all the active timers.

==Example==
This example kills timers with a remaining time of less than 1 minute.
<syntaxhighlight lang="lua">
-- Find and kill all the timers with less than 1 minute to go
timers = getTimers ( 60000 )
-- Loop through the timer list
for timerKey, timerValue in ipairs(timers) do
-- kill the timer
killTimer ( timerValue )
end
</syntaxhighlight>

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

Scripting Introduction

2018-06-14T08:21:38Z

NanoBob: Added VS code to suggested editors

Resources are a key part of MTA. A resource is essentially a folder or zip file that contains a collection of files, plus a meta file that describes to the server how the resource should be loaded and what files it does contain. A resource can be seen as being partly equivalent to a program running in an operating system - it can be started and stopped, and multiple resources can run at once.

Everything that has to do with scripting happens in resources, what a resource does defines if it is a gamemode, a map or anything else. MTA comes with resources that you can optionally use in your gamemodes, such as maplimits to keep playings within a playing area or deathpickups to create weapon pickups.
{{tip|Your first step to begin Lua scripting should be using an Lua editor. This makes scripting much easier. We recommend [https://code.visualstudio.com/ Visual Studio Code], [http://www.sublimetext.com/ Sublime Text], [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] or [http://luaedit.sourceforge.net/ LuaEdit]. There is also an unofficial [[MTASE|MTA Script Editor]] (in work-in-progress state) that you can test out.}}

==Creating a working script==
We will first learn how to make a basic script that lets the player walk around in the city, step by step.
===Where are all the scripts?===
Let's take a look at the script's file structure. Go to your MTA Server folder, and follow the path below:

server/mods/deathmatch/resources/

You will see a lot of .zip files, which are the packaged sample scripts shipped with MTA. Each file is a "resource", and they will all be unzipped and loaded by the server when it starts. To create your own resource, simply make a folder with your preferred name. We'll use "myserver" for this tutorial.

Now you should be under this directory:

server/mods/deathmatch/resources/myserver/

===Identifying your resource===
In order to let the server know what's in the resource, a ''meta.xml'' file must be created to list the resource's content. It must be located in the resource's root directory, which is the "myserver" folder in our case. So create a text file and name it "meta.xml", and open it with notepad.

Enter the following codes in the ''meta.xml'' file:
<syntaxhighlight lang="xml">
<meta>
<info author="YourName" type="gamemode" name="My Server" description="My first MTA server" />
<script src="script.lua" />
</meta>
</syntaxhighlight>
In the ''<info />'' tag, there's a "type" field which indicates that the resource is a ''gamemode'' instead of a regular include or a ''map'', which will be explained later. A gamemode is what you need to make a stand-alone server.

The ''<script />'' tag indicates the script files contained in the resource, which we will create next.
===Creating a simple script===
Note that in the ''<script />'' tag above, the .lua file is not under another directory. Therefore we'll create the file in the same folder as meta.xml. Now you can copy and paste the following code into script.lua:
<syntaxhighlight lang="lua">
local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10
function joinHandler()
spawnPlayer(source, spawnX, spawnY, spawnZ)
fadeCamera(source, true)
setCameraTarget(source, source)
outputChatBox("Welcome to My Server", source)
end
addEventHandler("onPlayerJoin", getRootElement(), joinHandler)
</syntaxhighlight>
The script will spawn you at the coordinate (x, y, z) specified above, when you join the game. Note that the ''fadeCamera'' function must be used or the screen will be black. Also, in releases after DP2, you need to set the camera target (otherwise all the player will see is blue sky).

The '''source''' variable indicates who triggered the event. Since a player has joined when the code is triggered, you use this variable to look which has joined. So it'll spawn that player instead of everyone or a random person.

If we have a closer look on [[addEventHandler]], you can see 3 things: 'onPlayerJoin', which indicates when it's triggered. getRootElement(), which shows by what/who it can be triggered. (getRootElement() is everything/everyone) And joinHandler, which indicates the function that has to be triggered after the event is triggered. Other details will be explained later in another example, now let's just run the server and try it out!

===Running the script===
To get the server started, simply run the executable under the server/ directory. A list of server stats will be shown first; note the port number, which you'll need when joining the game. Then the server loads all the resources under the mods/deathmatch/resources/ directory, and then "ready to accept connections!"

Before you connect to the server, you must run the gamemode. Type "start myserver" and press Enter. The server will start the gamemode you just created, and will also show any errors and warnings from this point on. Now you can start the MTA client, and "Quick Connect" using the IP address of your server and the port number you saw earlier. If all goes well, after a few seconds your character will be walking on the streets of Los Santos.

Next we'll add a command to your script that players can use to spawn a vehicle beside their position. You may skip it and check out more advanced scripting with the [[Map manager|Map Manager]], which continues this tutorial. Another branch from this tutorial is [[Introduction to Scripting GUI]], you may follow it to see how Graphical User Interface in MTA is drawn and scripted.

==Creating a simple command==
Let's go back to the content of the ''script.lua'' file. As mentioned above, we want to provide a command to create a vehicle beside your current position in the game. Firstly we need to create a function we want to call and a command handler that creates the command the player will be able to enter in the console.

<syntaxhighlight lang="lua">
-- create the function the command handler calls, with the arguments: thePlayer, command, vehicleModel
function createVehicleForPlayer(thePlayer, command, vehicleModel)
-- create a vehicle and stuff
end

-- create a command handler
addCommandHandler("createvehicle", createVehicleForPlayer)
</syntaxhighlight>
''Note: Function names are clickable in code examples on the wiki and linked to the functions' documentation.''

====About command handlers====
The first argument of [[addCommandHandler]] is the name of the command the player will be able to enter, the second argument is the function this will call, in this case ''createVehicleForPlayer''.

If you have already experience in scripting, you will know that you call a function like this:
<syntaxhighlight lang="lua">
functionName(argument1, argument2, argument3, ..)
</syntaxhighlight>
<syntaxhighlight lang="lua">
functionName(thePlayer, commandName, argument3, ..)
</syntaxhighlight>
If we have a closer look on the lower example above, we can see argument1 is thePlayer and argument2 the commandName. thePlayer is simply the one who typed the command, so whatever you call it, the variable will contain the player who activated the command. commandName is simply the command they typed. So if they typed "/greet", this argument will contain "greet". Argument 3 is something extra the player typed, you'll learn it a little bit further in the tutorial. Never forget that the first 2 arguments are standard arguments, but you can name them to anything you want.

We called the [[addCommandHandler]] function this way already and since ''createVehicleForPlayer'' is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.

For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:
<syntaxhighlight lang="lua">
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer is the player element of the player who entered the command
</syntaxhighlight>
As we can see, it provides several parameters: the player who called the command, the command he entered and whatever text he had after that, in this case "468" as vehicle id for the Sanchez. The first two parameters are the same with all command handlers, which you can read on the [[addEventHandler]] page. For this fact, you always have to define at least those two parameters to use any after that (for example to process text that was entered after the command, like in our example the vehicle model id).

''Note: You have to add the command handler AFTER you defined the handler function, else it can't find it. The order of execution matters.''

====Writing the function====
In order to fill the function we created, we need to think about what we have to do:
* Get the players position, so we know where to spawn the vehicle (we want it to appear right beside the player)
* Calculate the position we want to spawn the vehicle at (we don't want it to appear in the player)
* Spawn the vehicle
* Check if it has been spawned successfully, or output a message

In order to achieve our goals, we have to use several functions. To find function we need to use, we should visit the [[Scripting Functions|Server Functions List]]. First we need a function to get the players position. Since players are Elements, we first jump to the '''Element functions''' where we find the [[getElementPosition]] function. By clicking on the function name in the list, you get to the function description. There we can see the syntax, what it returns and usually an example. The syntax shows us what arguments we can or have to submit.

For [[getElementPosition]], the syntax is:
<syntaxhighlight lang="lua">
float, float, float getElementPosition ( element theElement )
</syntaxhighlight>

The three ''float'' in front of the function name are the return type. In this case it means the function returns three floating point numbers. (x, y and z) Within the parentheses, you can see what arguments you have to submit. In this case only the element whose position you want to get, which is the player in our example.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
-- get the position and put it in the x,y,z variables
-- (local means, the variables only exist in the current scope, in this case, the function)
local x,y,z = getElementPosition(thePlayer)
end
</syntaxhighlight>

Next we want to ensure that the vehicle won't spawn directly in the player, so we add a few units to the ''x'' variable, which will make it spawn east from the player.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
end
</syntaxhighlight>

Now we need another function, one to spawn a vehicle. We once again search for it on the [[Scripting Functions|Server Functions List]], this time - since we are talking about vehicles - in the '''Vehicle functions''' section, where we will choose [[createVehicle]]. In this function's syntax, we only have one return type (which is more common), a vehicle element that points to the vehicle we just created. Also, we see that some arguments are enclosed within [ ] which means that those are optional.

We already have all arguments we need for [[createVehicle]] in our function: The position we just calculated in the ''x,y,z'' variables and the model id that we provided through the command ("createvehicle 468") and can access in the function as ''vehicleModel'' variable.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
-- create the vehicle and store the returned vehicle element in the ''createdVehicle'' variable
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)
end
</syntaxhighlight>

Of course this code can be improved in many ways, but at least we want to add a check whether the vehicle was created successfully or not. As we can read on the [[createVehicle]] page under '''Returns''', the function returns ''false'' when it was unable to create the vehicle. Thus, we check the value of the ''createVehicle'' variable.

Now we have our complete script:
<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)
-- check if the return value was ''false''
if (createdVehicle == false) then
-- if so, output a message to the chatbox, but only to this player.
outputChatBox("Failed to create vehicle.",thePlayer)
end
end
addCommandHandler("createvehicle", createVehicleForPlayer)
</syntaxhighlight>

As you can see, we introduced another function with [[outputChatBox]]. By now, you should be able to explore the function's documentation page yourself. For more advanced scripting, please check out the [[Map manager|Map Manager]].

==What you need to know==
You already read some things about resources, command handlers and finding functions in the documentation in the first paragraph, but there is much more to learn. This section will give you a rather short overview over some of these things, while linking to related pages if possible.
===Clientside and Serverside scripts===
You may have already noticed these or similiar terms (Server/Client) somewhere on this wiki, mostly in conjunction with functions. MTA not only supports scripts that run on the server and provide commands (like the one we wrote above) or other features, but also scripts that run on the MTA client the players use to connect to the server. The reason for this is, that some features MTA provides have to be clientside (like a GUI - Graphical User Interface), others should be because they work better and still others are better off to be serverside or just don't work clientside.

Most scripts you will make (gamemodes, maps) will probably be serverside, like the one we wrote in the first section. If you run into something that can't be solved serverside, you will probably have to make it clientside. For a clientside script for example, you would create a ordinary script file (for example called ''client.lua'') and specify it in the meta.xml, like this:
<syntaxhighlight lang="xml">
<script src="client.lua" type="client" />
</syntaxhighlight>
The ''type'' attribute defaults to 'server', so you only need to specify it for clientside scripts. When you do this, the clientside script will be downloaded to the player's computer once he connects to the server. Read more about [[Client side scripts]].

===More complex resources===
The previous section showed briefly how to add clientside scripts to the resource, but there is also much more possible. As mentioned at the very top of this page, resources can be pretty much everything. Their purpose is defined by what they do. Let's have some theoretical resources, by looking at the files it contains, the ''meta.xml'' and what they might do:

====First example - A utility script====
<syntaxhighlight lang="xml">
/admin_commands
/meta.xml
/commands.lua
/client.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="admin commands" />
<script src="commands.lua" />
<script src="client.lua" type="client" />
</meta>
</syntaxhighlight>

* The ''commands.lua'' provides some admin commands, like banning a player, muting or something else that can be used to admin the server
* The ''client.lua'' provides a GUI to be able to perform the mentioned actions easily

This example might be running all the time (maybe even auto-started when the server starts) as it's useful during the whole gaming experience and also wont interfere with the gameplay, unless an admin decides to take some action of course.

====Second example - A gamemode====
<syntaxhighlight lang="xml">
/counterstrike
/meta.xml
/counterstrike.lua
/buymenu.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="Counterstrike remake" type="gamemode" />
<script src="counterstrike.lua" />
<script src="buymenu.lua" type="client" />
</meta>
</syntaxhighlight>

* The ''counterstrike.lua'' contains similiar to the following features:
** Let players choose their team and spawn them
** Provide them with weapons, targets and instructions (maybe read from a Map, see below)
** Define the game's rules, e.g. when does the round end, what happens when a player dies
** .. and maybe some more
* The ''buymenu.lua'' is a clientside script and creates a menu to buy weapons

This example can be called a gamemode, since it not only intereferes with the gameplay, but actually defines the rules of it. The ''type'' attribute indicates that this example works with the [[Map manager]], yet another resource that was written by the QA Team to manage gamemodes and map loading. It is highly recommended that you base your gamemodes on the techniques it provides.

This also means that the gamemode probably won't run without a map. Gamemodes should always be as generic as possible. An example for a map is stated in the next example.

====Third example - A Map====
<syntaxhighlight lang="xml">
/cs-airport
/meta.xml
/airport.map
/airport.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" />
<map src="airport.map" />
<script src="airport.lua" />
</meta>
</syntaxhighlight>

* The ''airport.map'' in a XML file that provides information about the map to the gamemode, these may include:
** Where the players should spawn, with what weapons, what teams there are
** What the targets are
** Weather, World Time, Timelimit
** Provide vehicles
* The ''airport.lua'' might contain map-specific features, that may include:
** Opening some door/make something explode when something specific happens
** Create or move some custom objects, or manipulate objects that are created through the .map file
** .. anything else map-specific you can think of

As you can see, the ''type'' attribute changed to 'map', telling the [[Map manager]] that this resource is a map, while the ''gamemodes'' attribute tells it for which gamemodes this map is valid, in this case the gamemode from the above example.
What may come as a surprise is that there is also a script in the Map resource. Of course this is not necessarily needed in a map, but opens a wide range of possibilities for map makers to create their own world within the rules of the gamemode they create it for.

The ''airport.map'' file might look similiar to this:
<syntaxhighlight lang="xml">
<map mode="deathmatch" version="1.0">
<terrorists>
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" />
</terrorists>
<counterterrorists>
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" />
</counterterrorists>

<bomb posX="23342.23" posY="" posZ="" />

<vehicle posX="" posY="" posZ="" model="602" />
<vehicle posX="" posY="" posZ="" model="603" />
</map>
</syntaxhighlight>

When a gamemode is started with a map, the map resources is automatically started by the mapmanager and the information it contains can be read by the gamemode resource. When the map changes, the current map resource is stopped and the next map resource is started. For a more in-depth explanation and examples of how map resources are utilized in the main script, please visit the [[Writing Gamemodes]] page.

===Events===
[[Event|Events]] are the way MTA tells scripts about things that happen. For example when a player dies, the [[onPlayerWasted]] event is triggered. In order to perform any actions when a player dies, you have to prepare yourself similiar to adding a command handler, as shown in [[#Writing_the_script|the first chapter]].

This example will output a message with the name of the player who died:
<syntaxhighlight lang="lua">
function playerDied(totalAmmo, killer, killerWeapon, bodypart)
outputChatBox(getPlayerName(source).." died!")
end
addEventHandler("onPlayerWasted",getRootElement(),playerDied)
</syntaxhighlight>

Instead of showing what arguments are needed, the documentation page for Events shows what parameters are passed to the handler function, similiar to the way a [[#About_command_handlers|command handler]] does, just that it is different from event to event. Another important point is the ''source'' variable, that exists in handler functions. It doesn't have to be added to the parameter list of the function, but it still exists. It has a different value from event to event, for player events (as in the example above) it is the player element. As another example, you can take a look at the basic spawning player script in the first section to get an idea how ''source'' is used.

==Where to go from here==
You should now be familiar with the most basic aspects of MTA scripting and also a bit with the documentation. The [[Main Page]] provides you with links to more information, Tutorials and References that allow a deeper look into the topics you desire to learn about.
{{note|From here we recommend reading the [[debugging]] tutorial. Good debugging skills are an absolute necessity when you are making scripts. We also recommend you to use the [[predefined variables list]] to help you with certain tasks and make scripting easier and faster.}}
'''See also:'''
* [[OOP_Introduction|OOP Scripting Introduction]]
* [[Advanced Topics]]
* [[Script_security|Script security]]
* [[Scripting Introduction Urdu]]
[[es:Introducción a la Programación]]
[[it:Introduzione allo scripting]]
[[nl:Scripting_introductie]]
[[pt-br:Introdução ao Scripting]]
[[ru:Scripting Introduction]]
[[hu:Scripting Intorduction]]
[[ar:مقدمه_في_البرمجه]]
[[zh-cn:脚本编写介绍]]
[[Category:Tutorials]]