Multi Theft Auto: Wiki - User contributions [en]

GetAnalogControlState

2020-01-16T12:45:16Z

MrTasty: Function arguments updated as pull #1165 was merged

__NOTOC__
{{Client function}}
This retrieves the analog control state of a control. This is useful for detecting sensitive controls, such as those used on a joypad.

To get the analog control state for a [[ped]], please use [[getPedAnalogControlState]].

==Syntax==
<syntaxhighlight lang="lua">float getAnalogControlState ( string control [, bool rawValue ] )</syntaxhighlight>

===Required Arguments===
*'''control:''' The control that you want to get the state of. See [[control names]] for a list of possible controls.

===Optional Arguments===
{{New feature/item|3.0157|1.5.7|20383|
*'''rawValue:''' A bool indicating whether to poll for raw controller state, which ignores keyboard input and any overrides from [[setAnalogControlState]] and others. When set to true, and a controller is not used, the function will always return 0.
}}

===Returns===
Returns a [[float]] between 0 and 1 indicating the amount the control is pressed.

==Example==
This creates an ''/forwards'' command, which toggles your ''forwards'' control state between 0 and 1.
<syntaxhighlight lang="lua">
addCommandHandler( "forwards",
function( )
if ( getAnalogControlState( "forwards" ) == 0 ) then
setAnalogControlState( "forwards", 1 )
else
setAnalogControlState( "forwards", 0 )
end
end
)
</syntaxhighlight>

==See Also==
{{Client input functions}}

GetPedAnalogControlState

2020-01-16T12:45:14Z

MrTasty: Function arguments updated as pull #1165 was merged

__NOTOC__
{{Client function}}
{{Needs_Example}}
This function retrieves the analog control state of a ped, as set by [[setPedAnalogControlState]].

==Syntax==
<syntaxhighlight lang="lua">float getPedAnalogControlState ( ped thePed, string controlName [, bool rawValue ] )</syntaxhighlight>

===Required Arguments===
*'''thePed:''' The ped you wish to retrieve the control state of.
*'''controlName:''' The control. See [[control names]] for a list of possible controls.

===Optional Arguments===
{{New feature/item|3.0157|1.5.7|20383|
*'''rawValue:''' A bool indicating whether to poll for raw controller state, which ignores keyboard input and any overrides from [[setPedAnalogControlState]] and others. When set to true, and a controller is not used, the function will always return 0.
}}

===Returns===
Returns a float between 0 ( full release ) and 1 ( full push ) indicating the amount the control is pushed.

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

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

==See Also==
{{Ped functions}}

[[hu:getPedAnalogControlState]]

Compatibility FAQ

2018-11-06T17:58:57Z

MrTasty: /* Compatibility Comparison */ Windows 10 version 1703 end of service date was October 9th.

== Compatibility Comparison ==
{{Warning|Using the legacy build is not without risk, there are known security issues in the Chrome Embedded Framework (CEF) that MTA:SA {{Current Version|full}} uses for Windows XP and Vista. It is recommended that you upgrade from XP or Vista to a supported Windows version.|true}}
{| class="wikitable"
|-
! Operating System
! Service Pack/Version
! Release Date
! Supported by Microsoft<ref>https://support.microsoft.com/en-us/help/13853/windows-lifecycle-fact-sheet</ref>
! Does MTA:SA {{Current Version|full}} work?
! Chrome Embedded Framework
Updates
! Future MTA:SA
releases/updates
|-
| Windows XP
| Service Pack 3
| August 2001
| {{No}}
| {{Partial|Yes, requires legacy build}}
| {{No}}
| {{Partial|Unknown}}
|-
| Windows Vista
| Service Pack 2
| November 2006
| {{No}}
| {{Partial|Yes, requires legacy build}}
| {{No}}
| {{Partial|Unknown}}
|-
| Windows 7
| Service Pack 1
| July 2009
| {{Yes|Yes, until January 2020}}
| {{Yes}}
| {{Yes}}
| {{Yes}}
|-
| Windows 8.0
| {{n/a}}
| August 2012
| {{No|No, upgrade to 8.1<ref>https://support.microsoft.com/en-us/help/15288/windows-8-update-to-windows-8-1</ref>}}
| {{n/a}}
| {{n/a}}
| {{n/a}}
|-
| Windows 8.1
| {{n/a}}
| August 2013
| {{Yes|Yes, until January 2023}}
| {{Yes}}
| {{Yes}}
| {{Yes}}
|-
|rowspan=7 | Windows 10<ref>([https://support.microsoft.com/en-us/help/13853/windows-lifecycle-fact-sheet])</ref>
| 1507
| July 2015
| {{No}}
| {{n/a}}
| {{n/a}}
| {{n/a}}
|-
| 1511
| November 2015
| {{No}}
| {{n/a}}
| {{n/a}}
| {{n/a}}
|-
| 1607
| August 2016
| {{No}}
| {{n/a}}
| {{n/a}}
| {{n/a}}
|-
| 1703
| April 2017
| {{No}}
| {{n/a}}
| {{n/a}}
| {{n/a}}
|-
| 1709
| October 2017
| {{Yes|Yes, until April 2019}}
| {{Yes}}
| {{Yes}}
| {{Yes}}
|-
| 1803
| April 2018
| {{Yes}}
| {{Yes}}
| {{Yes}}
| {{Yes}}
|-
| 1809
| September 2018
| {{n/a}}
| {{n/a}}
| {{n/a}}
| {{n/a}}
|}

* Please use a supported version of Windows 10 to run MTA.
* There are no guarantees that MTA will work on older not by Microsoft supported Windows 8 and 10 versions.

== FAQ - Frequently Asked Questions ==
=== Google is dropping XP/Vista support for Chrome browser? What does this even have to do with MTA:SA? ===
As you may know from our previous [https://forum.mtasa.com/topic/75559-mtasa-15-release-candidate-is-ready-for-testing/ news posts], MTA:SA uses CEF (Chrome Embedded Framework) components for providing some functionality for the mod since version 1.5. Being Chromium-based, CEF components are also being phased out for users of older Operating Systems and will simply not work on them.<ref>https://bitbucket.org/chromiumembedded/cef</ref>

=== Does MTA:SA 1.5.3 work fine on Windows XP and Windows Vista? ===
Yes, it works fine if you install it through the legacy build. We still can not really recommend using these systems anymore due to reasons listed below.

CEF compatibility issue aside, these Operating Systems (XP especially) are really old nowadays. You are putting yourself at risk if you use them as they are either no longer supported by Microsoft (XP) or the support will be discontinued soon (April 2017 - Vista).

=== What will happen if I try to use the regular build of 1.5.3 on Windows XP/Vista? ===
MTA:SA installer will display an error and will not let you install the mod on such systems. You will be asked to download the legacy build from our website.

=== And what will happen if I try to use the legacy build of 1.5.3 on Windows 7 and above? ===
Similarly, MTA:SA installer will display an error and will not let you install the mod on such systems. You will be asked to download the regular build from our website.

=== Why couldn't you just stick to the older version of CEF then so that XP/Vista would be still supported? / What about releasing two versions of the mod? A regular one with newest CEF and a legacy one with the older CEF build that still works on XP/Vista? ===
Hey, but we actually do provide a legacy build for MTA:SA 1.5.3 for XP/Vista users with an older version of CEF components.

The problem with sticking with either of these options is that we would have to continue providing a version that is vulnerable to any present and future security exploits that exist in Chromium and are already widely used. We do not want to put our users at risk because of that. CEF developers themselves do not want to provide a long-term security support for such a build either. <ref>http://www.magpcss.org/ceforum/viewtopic.php?f=6&t=14187</ref>

=== I am playing the mod on Windows 7/Windows 8/Windows 8.1/Windows 10 or newer. Am I affected by this? ===
No, you will not be affected at all. In fact, you will have a better experience with built-in web browser components than before due to security and performance fixes included in the newer CEF versions.

=== I am using Windows XP/Vista and I would still like to play future versions of MTA:SA. What can I do about it? ===
If you are using Windows XP or Windows Vista, you should upgrade your OS to a newer one. You will likely be required to do a clean install for that, so backup your stuff first. You should use these tools first to see if your PC is capable of upgrading to newer OS:

Windows 7: [https://www.microsoft.com/en-us/download/details.aspx?id=20 Windows 7 Upgrade Advisor]
Windows 8/10: [http://go.microsoft.com/fwlink?linkid=259439 Windows 8 Upgrade Assistant]

Is your PC toaster-tier which does not support Windows 8 or even 7? That means it is probably the right time to buy something more modern.

But fear not, if you are already using Windows 7 or newer, just install the newest build of MTA:SA 1.5.3 and you are set! And if you don't want to upgrade your OS or PC, well, we will keep offering the legacy build that works on XP/Vista for a while...

== Notes ==
<references />

== See also ==
* [https://forum.mtasa.com/topic/89685-mtasa-windows-xpvista-cef-components-and-you/ Topic about the compatibility changes]

WordWrap

2018-10-22T07:45:10Z

MrTasty:

__NOTOC__
{{Useful Function}}
{{Needs_Example}}
This function splits a long string into a table of lines no longer than ''maxwidth''.
{{Note|A line without any spaces in it will not break, meaning it may exceed ''maxwidth''.}}
{{Tip|This function may lag if used too often. Consider only calling this function when any of the arguments change (such as the text, maxwidth, it's scale or font, etc.) and caching the result, rather than calling it [[onClientRender]] or similarly frequent events.}}

==Syntax==
<syntaxhighlight lang="lua">
table wordWrap( string text, float maxwidth, [float scale=1, mixed font="default", bool bColorCoded=false] )
</syntaxhighlight>

===Required Arguments===
* '''text:''' The string to break into lines.
* '''maxwidth:''' The number of pixels of allowed length per line.

===Optional Arguments===
{{OptionalArg}}
* '''scale:''' The size of the text, as in [[dxGetTextWidth]]. Defaults to 1.
* '''font:''' Either a custom DX font element or the name of a built-in dx font, as in [[dxGetTextWidth]]. Defaults to "default".
* '''bColorCoded:''' Should color codes be excluded from the width? (false will include #rrggbb in the length calculations). Defaults to false.

==Code==
<section name="Clientside script" class="client" show="true">
<syntaxhighlight lang="lua">
function wordWrap(text, maxwidth, scale, font, colorcoded)
local lines = {}
local words = split(text, " ") -- this unfortunately will collapse 2+ spaces in a row into a single space
local line = 1 -- begin with 1st line
local word = 1 -- begin on 1st word
local endlinecolor
while (words[word]) do -- while there are still words to read
repeat
if colorcoded and (not lines[line]) and endlinecolor and (not string.find(words[word], "^#%x%x%x%x%x%x")) then -- if on a new line, and endline color is set and the upcoming word isn't beginning with a colorcode
lines[line] = endlinecolor -- define this line as beginning with the color code
end
lines[line] = lines[line] or "" -- define the line if it doesnt exist

if colorcoded then
local rw = string.reverse(words[word]) -- reverse the string
local x, y = string.find(rw, "%x%x%x%x%x%x#") -- and search for the first (last) occurance of a color code
if x and y then
endlinecolor = string.reverse(string.sub(rw, x, y)) -- stores it for the beginning of the next line
end
end

lines[line] = lines[line]..words[word] -- append a new word to the this line
lines[line] = lines[line] .. " " -- append space to the line

word = word + 1 -- moves onto the next word (in preparation for checking whether to start a new line (that is, if next word won't fit)
until ((not words[word]) or dxGetTextWidth(lines[line].." "..words[word], scale, font, colorcoded) > maxwidth) -- jumps back to 'repeat' as soon as the code is out of words, or with a new word, it would overflow the maxwidth

lines[line] = string.sub(lines[line], 1, -2) -- removes the final space from this line
if colorcoded then
lines[line] = string.gsub(lines[line], "#%x%x%x%x%x%x$", "") -- removes trailing colorcodes
end
line = line + 1 -- moves onto the next line
end -- jumps back to 'while' the a next word exists
return lines
end
</syntaxhighlight>
Author: Addlibs (aka MrTasty)
</section>

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

==See Also==
{{Useful_Functions}}

WordWrap

2018-10-22T07:41:38Z

MrTasty: Updated code to append colorcodes on every new line, preserving the color from the previous line (that is, if there are colorcodes present in the text)

__NOTOC__
{{Useful Function}}
{{Needs_Example}}
This function splits a long string into a table of lines no longer than ''maxwidth''.
{{Note|A line without any spaces in it will not break, meaning it may exceepd ''maxwidth''.}}
{{Tip|This function may lag if used too often. Consider only calling this function when any of the arguments change (such as the text, maxwidth, it's scale or font, etc.) and caching the result, rather than calling it [[onClientRender]] or similarly frequent events.}}

==Syntax==
<syntaxhighlight lang="lua">
table wordWrap( string text, float maxwidth, [float scale=1, mixed font="default", bool bColorCoded=false] )
</syntaxhighlight>

===Required Arguments===
* '''text:''' The string to break into lines.
* '''maxwidth:''' The number of pixels of allowed length per line.

===Optional Arguments===
{{OptionalArg}}
* '''scale:''' The size of the text, as in [[dxGetTextWidth]]. Defaults to 1.
* '''font:''' Either a custom DX font element or the name of a built-in dx font, as in [[dxGetTextWidth]]. Defaults to "default".
* '''bColorCoded:''' Should color codes be excluded from the width? (false will include #rrggbb in the length calculations). Defaults to false.

==Code==
<section name="Clientside script" class="client" show="true">
<syntaxhighlight lang="lua">
function wordWrap(text, maxwidth, scale, font, colorcoded)
local lines = {}
local words = split(text, " ") -- this unfortunately will collapse 2+ spaces in a row into a single space
local line = 1 -- begin with 1st line
local word = 1 -- begin on 1st word
local endlinecolor
while (words[word]) do -- while there are still words to read
repeat
if colorcoded and (not lines[line]) and endlinecolor and (not string.find(words[word], "^#%x%x%x%x%x%x")) then -- if on a new line, and endline color is set and the upcoming word isn't beginning with a colorcode
lines[line] = endlinecolor -- define this line as beginning with the color code
end
lines[line] = lines[line] or "" -- define the line if it doesnt exist

if colorcoded then
local rw = string.reverse(words[word]) -- reverse the string
local x, y = string.find(rw, "%x%x%x%x%x%x#") -- and search for the first (last) occurance of a color code
if x and y then
endlinecolor = string.reverse(string.sub(rw, x, y)) -- stores it for the beginning of the next line
end
end

lines[line] = lines[line]..words[word] -- append a new word to the this line
lines[line] = lines[line] .. " " -- append space to the line

word = word + 1 -- moves onto the next word (in preparation for checking whether to start a new line (that is, if next word won't fit)
until ((not words[word]) or dxGetTextWidth(lines[line].." "..words[word], scale, font, colorcoded) > maxwidth) -- jumps back to 'repeat' as soon as the code is out of words, or with a new word, it would overflow the maxwidth

lines[line] = string.sub(lines[line], 1, -2) -- removes the final space from this line
if colorcoded then
lines[line] = string.gsub(lines[line], "#%x%x%x%x%x%x$", "") -- removes trailing colorcodes
end
line = line + 1 -- moves onto the next line
end -- jumps back to 'while' the a next word exists
return lines
end
</syntaxhighlight>
Author: Addlibs (aka MrTasty)
</section>

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

==See Also==
{{Useful_Functions}}

WordWrap

2018-10-20T10:53:39Z

MrTasty: /* Optional Arguments */

__NOTOC__
{{Useful Function}}
{{Needs_Example}}
This function splits a long string into a table of lines no longer than ''maxwidth''.
{{Note|A line without any spaces in it will not break, meaning it may exceepd ''maxwidth''.}}
{{Tip|This function may lag if used too often. Consider only calling this function when any of the arguments change (such as the text, maxwidth, it's scale or font, etc.) and caching the result, rather than calling it [[onClientRender]] or similarly frequent events.}}

==Syntax==
<syntaxhighlight lang="lua">
table wordWrap( string text, float maxwidth, [float scale=1, mixed font="default", bool bColorCoded=false] )
</syntaxhighlight>

===Required Arguments===
* '''text:''' The string to break into lines.
* '''maxwidth:''' The number of pixels of allowed length per line.

===Optional Arguments===
{{OptionalArg}}
* '''scale:''' The size of the text, as in [[dxGetTextWidth]]. Defaults to 1.
* '''font:''' Either a custom DX font element or the name of a built-in dx font, as in [[dxGetTextWidth]]. Defaults to "default".
* '''bColorCoded:''' Should color codes be excluded from the width? (false will include #rrggbb in the length calculations). Defaults to false.

==Code==
<section name="Clientside script" class="client" show="true">
<syntaxhighlight lang="lua">
function wordWrap(text, maxwidth, scale, font, colorcoded)
local lines = {}
local words = split(text, " ") -- this unfortunately will collapse 2+ spaces in a row into a single space
local line = 1 -- begin with 1st line
local word = 1 -- begin on 1st word
while (words[word]) do -- while there are still words to read
repeat
lines[line] = lines[line] and (lines[line].." ") or "" -- appends space if line already exists, or defines it to an empty string
lines[line] = lines[line]..words[word] -- append a new word to the this line
word = word + 1 -- moves onto the next word (in preparation for checking whether to start a new line (that is, if next word won't fit)
until ((not words[word]) or dxGetTextWidth(lines[line].." "..words[word], scale, font, colorcoded) >= maxwidth) -- jumps back to 'repeat' as soon as the code is out of words, or with a new word, it would overflow the maxwidth

line = line + 1 -- moves onto the next line
end -- jumps back to 'while' the a next word exists
return lines
end
</syntaxhighlight>
Author: Addlibs (aka MrTasty)
</section>

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

==See Also==
{{Useful_Functions}}

Template:Useful Functions

2018-10-20T10:51:57Z

MrTasty: /* Drawing functions */ Added wordWrap

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

=== Account functions ===
*[[removeAccountData]] » This function is used to remove data from an account.

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

=== Cursor functions ===
*[[getCursorMovedOn]] » This function checks in which way the cursor is currently moving.

=== Drawing functions ===
*[[dxDrawAnimWindow]] » This function draws an animated 2D window on the screen.
*[[dxDrawBorderedRectangle]] » This is a function that will create a bordered rectangle.
*[[dxDrawDashedLine]] » This function draws a line with dashes.
*[[dxDrawTextOnRectangle]] » Esta funcion crea un rectangle con un texto dentro.
*[[dxDrawGifImage]] » This function simulates the effect of a GIF image by using image sprites in 2D.
*[[dxDrawImage3D]] » This function draws a 3D image in GTA world.
*[[dxDrawImageOnElement]] » This function draws an image on any element.
*[[dxDrawLinedRectangle]] » This is a function that will create a rectangle outline with dx lines.
*[[dxDrawLoading]] » This function draws a loading bar on the screen.
*[[dxDrawOctagon3D]] » This function creates a 3D Octagon
*[[dxDrawPolygon]] » This function draws a custom polygon on the screen.
*[[dxDrawRectangle3D]] » This function draws a 3D rectangle in GTA world.
*[[dxDrawProgressBar]] » This function simulates a progress bar drawed using DirectDraw.
*[[dxDrawTextOnElement]] » This function draws a text on any element.
*[[dxDrawTriangle]] » This is a function that will create a triangle with dx lines.
*[[dxGetFontSizeFromHeight]] » This function calculates the font size from given height.
*[[dxGetRealFontHeight]] » This function calculates the height of a font.
*[[wordWrap]] » This function breaks a long string into a table of separate lines limited to a specific length in pixels, for drawing separately.

=== Effects functions ===
*[[attachEffect]] » This function allows you attach an effect to an element.

=== Elements functions ===
*[[getElementSpeed]] » This function returns the specified element's speed in m/s, km/h or mph.
*[[getElementsInDimension]] » This function returns a table of elements that are in the specified dimension.
*[[getElementsWithinMarker]] » This function returns a table of elements that are within a marker's collision shape.
*[[isElementInPhotograph]] » This function checks if an element is in the player's camera picture area.
*[[isElementInRange]] » This function allows you to check if an element's range to a main point is within the maximum range.
*[[isElementMoving]]» This function checks if an element is moving.
*[[isElementWithinAColShape]]» This function checks if an element is within a collision shape element.
*[[multi_check]] » This function checks one element to many, handy and clean.
*[[setElementSpeed]] » This function allows you to set the speed of an element in kph or mph units.

=== Events ===
*[[onVehicleWeaponFire]] » This code implements an event that is triggered when a player in a vehicle fires a vehicle's weapon.

=== Input functions ===
*[[bindControlKeys]] » This function allows you to bind each key bound to a control individually. Doing this bypasses a little MTA restriction.
*[[getBoundControls]] » This function returns a table of control names that are bound to the specified key.
*[[unbindControlKeys]] » This function allows you to unbind each key bound to a control individually. Use this function with [[bindControlKeys]].
*[[getClipboard]] » This event returns the contents of the clipboard by pressing ctrl + v / ctrl + V. Event triggered ONLY if cursor is showing.

=== Data functions ===
*[[byte2human]] » This function converts an integer (number of bytes) into a human-readable unit.
*[[capitalize]] » This function capitalizes a given string.
*[[convertNumber]] » This function converts and formats large numbers.
*[[convertServerTickToTimeStamp]] » This function converts server ticks to a unix timestamp.
*[[convertTextToSpeech]] » This function converts the provided text to a speech in the provided language which players can hear.
*[[findRotation]] » This function takes two points and returns the direction from point A to point B.
*[[findRotation3D]] » This function takes two sets of XYZ coordinates. It returns the 3D direction from point A to point B.
*[[FormatDate]] » This function formats a date on the basis of a format string and returns it.
*[[generateString]] » This function generates a random string with any characters.
*[[generateRandomASCIIString]] » This function returns a random string which uses ASCII characters. 
*[[getAge]] » This function calculates the age of a given birthday.
*[[getDistanceBetweenPointAndSegment2D]] » This function takes point coordinates and line (a segment) starting and ending coordinates. It returns the shortest distance between the point and the line.
*[[getEasterDate]] » This function returns easter date monthday and month for a given year.
*[[getKeyFromValueInTable]] » This function returns the key of the specified value in a table.
*[[getOffsetFromXYZ]] » This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.
*[[getPointFromDistanceRotation]] » This function finds a point based on a starting point, direction and distance.
*[[getRealMonthH]] » This function convert english months to arabic months
*[[getRealMonthM]] » This function gives you the real months name
*[[getRGColorFromPercentage]] »This function returns two integers representing red and green colors according to the specified percentage.
*[[getScreenRotationFromWorldPosition]] » This function returns a screen relative rotation to a world position.
*[[getTimestamp]] » This function returns the UNIX timestamp of a specified date and time.
*[[isLeapYear]] » This function returns a boolean representing if a given year is a leap year.
*[[isValidMail]] » This function checks whether a provided e-mail string is valid.
*[[removeHex]] » This function is used to remove hexadecimal numbers (colors, for example) from strings.
*[[RGBToHex]] » This function returns a string representing the color in hexadecimal.
*[[secondsToTimeDesc]] » This function converts a plain seconds-integer into a user-friendly time description.
*[[string.count]] » This function counts the amount of occurences of a string in a string.
*[[string.explode]] » This function splits a string at a given separator pattern and returns a table with the pieces.
*[[switch]] » This function allows the value of a variable or expression to control the flow of program execution via a multiway branch.
*[[toHex]] » This function converts a decimal number to a hexadecimal number, as a fix to be used client-side.
*[[var dump]] » This function outputs information about one or more variables using outputConsole.
*[[wavelengthToRGBA]] » This function converts a physical wavelength of light to a RGBA color.
*[[getDistanceBetweenElements]] » Esta funcion sirve para obtener la distancia entre dos elementos.
*[[isLowerOrUpper]] »This function checks whether the letter is large or small.

=== GUI functions ===
*[[centerWindow]] » This function centers a CEGUI window element responsively in any resolution.
*[[guiMoveElement]] » This function moves guiElement by/like using moveObject.
=====Comboboxes=====
*[[guiComboBoxAdjustHeight]] » This function adjusts a CEGUI combobox element to have the correct height.
*[[guiComboBoxAddPlayersName]] » This function is add players name in combobox .

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

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

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

=== Math functions ===
*[[mathNumber]] » This function is a workaround for the client-side floating-point precision of 24-bits.
*[[math.hypot]] » This function returns the Hypotenuse of the triangle given by sides x and y.
*[[math.percent]] » This function returns a percentage from two number values.
*[[math.round]] » Rounds a number whereas the number of decimals to keep and the method may be set.
*[[reMap]] » Re-maps a number from one range to another.
*[[math.isPointInPolygon]] » Check if point is inside polygon or not.
*[[math.polygonArea]] » Compute area of any polygon.
*[[math.randomDiff]] » Generates a pseudo-random integer that's always different from the last random number generated.

=== Ped functions ===
*[[getAlivePlayers (Client)|getAlivePlayers]] » This function returns a table of the alive players client-side.
*[[getAlivePlayersInTeam]] » This function returns a table of the alive players in a team.
*[[getPlayersInVehicles]] » This function returns a table of the players insides vehicles from a specified dimension.
*[[getGuestPlayers]] » This function gets a players not login or players Guest .
*[[getOnlineAdmins]] » This function returns a table of all logged-in administrators.
*[[getPedEyesPosition]] » This function allows you to get peds eyes position.
*[[getPedMaxHealth]] » This function returns a pedestrians's maximum health by converting it from their maximum health stat.
*[[getPedMaxOxygenLevel]] » This function returns a ped's maximum oxygen level by converting it from their maximum underwater stamina stat.
*[[getPlayerFromNamePart]] » This function returns a player from partial name.
*[[getPlayerFromSerial]] » This function returns a player from their serial.
*[[getPlayersByData]] » This function returns a table of players that have the specified data name.
*[[getPlayersInGroup]] » This function returns all Players In Group .
*[[getPlayersInPhotograph]] » This function returns a table of all players in photograph.
*[[isPedAiming]]» This function checks if a pedestrian is aiming their weapon.
*[[isPedAimingNearPed]] » This is similar to isPedAiming but uses a colshape to be more precise.
*[[isPedDrivingVehicle]] » This function checks if a specified pedestrian is driving a vehicle.
*[[isPlayerInTeam]] » This function checks if a player is in a specified team.

=== Player functions ===
*[[countPlayersInRange]] » This function returns the number of players that are within a certain range of the specified coordinates.

=== Resource functions ===
*[[getResourceScripts]] » This function returns a table of the resource scripts.
*[[getResourceSettings]] » This function returns a table of the resource settings.
*[[refreshResource]] » This function refreshes your resource if you changed any of the files

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

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

=== Table functions ===
*[[rangeToTable]] » This function converts a string range to a table containing number values.
*[[setTableProtected]] » This function protects a table and makes it read-only.
*[[Sort_Functions]] » These functions are able to sort your tables by a key.
*[[table.compare]] » This function checks whether two given tables are equal.
*[[table.copy]] » This function copies a whole table and all the tables in that table.
*[[table.empty]] » This function checks whether a table is empty.
*[[table.map]] » This function goes through a table and replaces every field with the return of the passed function, where the field's value is passed as first argument and optionally more arguments.
*[[table.merge]] » This function merges two or more tables together.
*[[table.random]] » This function retrieves a random value from a table.
*[[table.removeValue]] » This function removes a specified value from a table.
*[[table.size]] » This function returns the absolute size of a table.

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

=== Vehicle funcions ===
*[[getNearestVehicle]] » This function gets the nearest vehicle to the specified player in a specified distance.
*[[getRandomVehicle]] » This function gets a random vehicle.
*[[getValidVehicleModels]] » This function returns a table of all valid vehicle models.
*[[getVehiclesCountByType]] » This function returns the amount of vehicles by the given type as an integer value.
*[[isVehicleEmpty]] » This function checks whether a vehicle is empty.
*[[isVehicleOccupied]] » This function checks if a specified vehicle is occupied.
*[[isVehicleOnRoof]] » This function checks whether vehicle is on roof.
*[[isVehicleReversing]] » This function checks if a specified vehicle is moving backwards.
*[[setVehicleGravityPoint]] » This function sets a vehicle's gravity in the direction of a 3 dimensional coordinate with the strength specified.
*[[getVehicleTurnVelocityCenterOfMass]]» This function gets a vehicle's turn velocity relative to the vehicle's center or mass.
*[[setVehicleTurnVelocityCenterOfMass]]» This function sets a vehicle's turn velocity relative to the vehicle's center or mass.

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

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

=== Utility ===
*[[animate]] » This function allows you to use interpolateBetween without render event and easily used.
*[[callClientFunction]] » This function allows you to call any client-side function from the server's side.
*[[callServerFunction]] » This function allows you to call any server-side function from the client's side.
*[[Check]] » This function checks if its arguments are of the right type and calls the error-function if one is not.
*[[coroutine.resume]] » This function applies a fix for hidden coroutine error messages.
*[[getBanFromName]] » This functions returns the ban of the given playername.
*[[getCurrentFPS]] » This function returns the frames per second at which GTA: SA is running.
*[[IfElse]] » This function returns one of two values based on a boolean expression.
*[[isCursorOnElement]] » This function checks whether the cursor is in a particular area.
*[[isMouseInCircle]] » This function checks if a cursor position is in circular area or not.
*[[isMouseInPosition]] » This function allows you to check whether the mouse cursor/pointer is within a rectangular position.
*[[iterElements]] » This function returns ''a time-saving'' iterator for your for-loops.
*[[thisCommandHandlersExist]] » This method checks a string if this exist as command Handlers
*[[vector3:compare]] » This method checks whether two vectors match, with optional precision.

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

WordWrap

2018-10-20T10:49:22Z

MrTasty: Created page with "__NOTOC__ {{Useful Function}} {{Needs_Example}} This function splits a long string into a table of lines no longer than ''maxwidth''. {{Note|A line without any spaces in it wi..."

__NOTOC__
{{Useful Function}}
{{Needs_Example}}
This function splits a long string into a table of lines no longer than ''maxwidth''.
{{Note|A line without any spaces in it will not break, meaning it may exceepd ''maxwidth''.}}
{{Tip|This function may lag if used too often. Consider only calling this function when any of the arguments change (such as the text, maxwidth, it's scale or font, etc.) and caching the result, rather than calling it [[onClientRender]] or similarly frequent events.}}

==Syntax==
<syntaxhighlight lang="lua">
table wordWrap( string text, float maxwidth, [float scale=1, mixed font="default", bool bColorCoded=false] )
</syntaxhighlight>

===Required Arguments===
* '''text:''' The string to break into lines.
* '''maxwidth:''' The number of pixels of allowed length per line.

===Optional Arguments===
{{OptionalArg}}
* '''scale:''' The size of the text, as in [[dxGetTextWidth]]. Defaults to 1.
* '''font:''' Either a custom DX font element or the name of a built-in dx font, as in [[dxGetTextWidth]]. Defaults to "default".
* '''bColorCoded:''' Should color codes be excluded from the width? (false will include #rrggbb in the length calculations) Defaults to false.

==Code==
<section name="Clientside script" class="client" show="true">
<syntaxhighlight lang="lua">
function wordWrap(text, maxwidth, scale, font, colorcoded)
local lines = {}
local words = split(text, " ") -- this unfortunately will collapse 2+ spaces in a row into a single space
local line = 1 -- begin with 1st line
local word = 1 -- begin on 1st word
while (words[word]) do -- while there are still words to read
repeat
lines[line] = lines[line] and (lines[line].." ") or "" -- appends space if line already exists, or defines it to an empty string
lines[line] = lines[line]..words[word] -- append a new word to the this line
word = word + 1 -- moves onto the next word (in preparation for checking whether to start a new line (that is, if next word won't fit)
until ((not words[word]) or dxGetTextWidth(lines[line].." "..words[word], scale, font, colorcoded) >= maxwidth) -- jumps back to 'repeat' as soon as the code is out of words, or with a new word, it would overflow the maxwidth

line = line + 1 -- moves onto the next line
end -- jumps back to 'while' the a next word exists
return lines
end
</syntaxhighlight>
Author: Addlibs (aka MrTasty)
</section>

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

==See Also==
{{Useful_Functions}}

Element data

2018-10-08T12:28:34Z

MrTasty:

Each [[element]] that is loaded is able to have [[element data]] values attached to it. These are values that can be accessed using a keyword string and directly correspond to the element's attributes in the map file, unless changed via scripting. Element data is a good way to store distributed information you want associated with an element, for example you could use it to associate a score with a player, or a team with a vehicle.

Element data is synchronized between the server and the client. Setting data from any of the two sides will force an update in the other, triggering the corresponding element data change events. This is very useful, as it provides a simple way to keep element properties synced without having to set special events to do it manually. This also means that excessive use of element data to store variables that are not required by both server and client becomes a waste of bandwidth.

Since not all datatypes can be packetized to be transferred, there are some restrictions. The types that cannot be stored as element data are ''non-element userdata'' (see [[MTA Classes]]), ''functions'' and ''threads''. Also, you may not send tables which contain one or more values of any of these types.

==Relevant functions==
* [[setElementData]]: sets an element data value.
* [[getElementData]]: retrieves an element data value.

==Relevant events==
* [[onElementDataChange]]: triggered on the server after element data is changed.
* [[onClientElementDataChange]]: triggered on the client after element data is changed.

OnElementDataChange

2018-10-08T12:28:32Z

MrTasty:

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

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

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

==Global parameters==
*'''source''': The [[event system#Event source|source]] of this event is the [[element]] whose [[element data]] changed.
*'''client''': The [[event system#Event client|client]] global variable is set to the client that called [[setElementData]], or nil if it was called on the server.
*'''sourceResource''': The [[resource]] which changed the element data. (Only works in versions above 1.3.4-5937)

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

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

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

OnClientElementDataChange

2018-10-08T12:28:28Z

MrTasty:

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

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

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

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

==Example==
This example tells the client whenever a player's "score" element data is changed.
<syntaxhighlight lang="lua">
function scoreChangeTracker(theKey, oldValue, newValue)
if (getElementType(source) == "player") and (theKey == "score") then
outputChatBox(getPlayerName(source).."'s new score is "..newValue.."!")
end
end
addEventHandler("onClientElementDataChange", root, scoreChangeTracker)
</syntaxhighlight>

[[pl:onClientElementDataChange]]

==See Also==
===Client element events===
{{Client_element_events}}
===Client event functions===
{{Client_event_functions}}

Debugging

2018-06-24T10:34:54Z

MrTasty: /* Useful functions */ added inspect and iprint

When scripting you will often come across problems that are not immediately apparent. This page tries to point out some basic strategies to locate the error.

==Debug console==
MTA features a built-in debug console that shows debug messages output from MTA functions or from scripts. Keeping it mind that you should have administrator access (unless you modify the ACL to change this), you can open the debug console by typing ''debugscript *x*'' in the console, where ''x'' is the debug level:
* '''1:''' only errors
* '''2:''' errors and warnings
* '''3:''' errors, warnings and info messages
By typing ''debugscript 3'' all messages are visible. Level 3 and level 2 are recommended for most occasions. You should have ''debugscript'' enabled whenever you are testing your scripts as it will help you easily detect and solve typos and other issues.

===Example===
This example code has two errors:
<syntaxhighlight lang="lua">
function SayHello(message, player)
if (getPlayerName(player) == "Fedor")
outputChatbox("Hello Fedor")
end
end
addEventHandler("onChatMessage", root, SayHello)
</syntaxhighlight>
When the script this piece of code is in is tried to be loaded, debugscript will output something similiar to this:
:{{Debug info|Loading script failed: myResource\script.lua:2: 'then' expected near ´outputChatbox'}}
This means the script could not be parsed because there was a syntax error. It shows the script path relative to the resource directory so you can identify to script where the error originated from. After the filename it shows a colon and a number, this number presents the line number - this is so you can find out where in your script the error is - it is very helpful for large scripts. After that is the error message, which varies depending on the error made. Looking at the error message, we can easily determine that the error originated from the resource '''myResource''' and line two of the script file '''script.lua'''. The error message is very clear, we forgot the "then"! We can easily fix that!
<syntaxhighlight lang="lua">
function SayHello(message, player)
if (getPlayerName(player) == "Fedor") then
outputChatbox("Hello Fedor")
end
end
addEventHandler("onChatMessage", root, SayHello)
</syntaxhighlight>
Now the script will load fine and won't output any errors until a player with the name 'Fedor' says something in the chat. At that moment, the debug console will output:
:{{Debug error|myResource\script.lua:2: attempt to call global 'outputChatbox' (a nil value)}}
This error means that the function '''outputChatbox''' is a nil value, that is - it doesn't exist! This is because the function is actually called [[outputChatBox]], not [[outputChatbox]] - take care of that capital B.:
<syntaxhighlight lang="lua">
function SayHello(message, player)
if (getPlayerName(player) == "Fedor") then
outputChatBox("Hello Fedor")
end
end
addEventHandler("onChatMessage", root, SayHello)
</syntaxhighlight>

Of course, this is just an example and I've only skimmed the surface of error messages. There are plenty of other messages and scenarios, but you should get the general idea.

==Server & client debug logging==
====Server====
Navigate to: ''(MTA root folder)>server>mods>deathmatch''

There are two nearly identical files:

*The local.conf is the settings for the "host game" menu item in the main menu of MTA. This is a quick and easy way of starting a temporary server from inside the client. When the client is turned off the server will also turn off.

*The mtaserver.conf is used when "MTA Server.exe" is executed from (MTA root folder)>server. This runs the server in its own console window which does not need the client to exist or to be run. This is can be useful if you're interested in hosting servers for a longer time period or if you want to experiment with a real world console.

Depending on which way you host, you will want to edit those files. The settings in question are:

<syntaxhighlight lang="xml">
<scriptdebuglogfile>logs/scripts.log</scriptdebuglogfile>


<scriptdebugloglevel>0</scriptdebugloglevel></syntaxhighlight>

You want to make sure you have a log name specified. Also you want to specify what level of errors will be logged. If it is 0 nothing will be logged. The levels were explained at the top of this article. If the logging level was changed to 3, then in this case all '''serverside''' script errors log to (MTA root folder)>server>mods>deathmatch>logs>scripts.log

====Client====
Navigate to: ''(MTA root folder)>server>clientscript.log''

This file logs all '''clientside''' script errors. This is set to log by default, no setup required.

==Debug strategies==
There are several strategies that support finding errors, apart from going through the code. Most of them include outputting debug messages, with have different information depending on the situtation.

===Useful functions===
There are some functions that may come in handy for debugging.
* [[outputDebugString]] or [[outputChatBox]] for outputting any information (use outputDebugString for technical output)
* [http://www.lua.org/manual/5.1/manual.html#pdf-tostring tostring()] on a variable to turn the value into a string. Useful if the value is not a number or string.
* [[inspect]] returns a useful human readable string notation of any datatype including tables, non-element userdatas such as ACL groups, accounts, etc, and elements.
* [[iprint]] similar to inspect, except it takes in as many arguments as desired and outputs them into debugscript.
* [[getElementType]] to check the type of the MTA element.
* [[isElement]] to check if the MTA element exists.

===Add debugmessages to check ''if'', ''when'' or ''how often'' a section of code is executed===
A typical example would be verify whether an ''if''-section is executed or not. To do that, just add any message you will recognize later within the ''if''-section.
<syntaxhighlight lang="lua">
if (variable1 == variable2) then
outputDebugString("variable1 is the same as variable2!")
-- do anything
end
</syntaxhighlight>

Another application would be to check when variable values are modified. First search for all occurences of the variable being edited and add a message just beside it.

===Add debugmessages to check the ''value'' of a variable===
Let's say you want to create a marker, but it doesn't appear at the position you expect it to be. The first thing you might want to do is check if the [[createMarker]] function is executed. But while doing this, you can also check the values being used in the [[createMarker]] function in one run.
<syntaxhighlight lang="lua">
outputChatBox("posX is: "..x.." posY is: "..y.." posZ is: "..z)
createMarker(x,y,z)
</syntaxhighlight>
This would output all three variables that are used as coordinates for the marker. Assuming you read those from a map file, you can now compare the debug output to the desired values. The [http://www.lua.org/manual/5.1/manual.html#pdf-tostring tostring()] will ensure that the values of the variables can be concatenated (put together) as a string, even if it's a boolean value.

==Example==
Imagine you created a [[Colshape|collision shape]] somewhere and you want an action to perform after the player stays for ten seconds inside it, you would do this:
<syntaxhighlight lang="lua">
function colShapeHit(player)
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit", root, colShapeHit)

function colShapeLeave(player)
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave", root, colShapeLeave)
</syntaxhighlight>
When a player enters the colshape, debugscript outputs the following message:
:{{Debug error|..[path]: attempt to index global 'colshapeTimer' (a nil value)}}
This means you tried to index a table that does not exist (because the table is a nil value, it doesn't exist). In the example above, this is done when storing the timer id in the table. We need to add a check if the table exists and if it does not exist we should create it.

<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit", root, colShapeHit)

function colShapeLeave(player)
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",root,colShapeLeave)
</syntaxhighlight>

Now we will still receive a warning when a player enters the colshape, waits for the message and leaves it again:

:{{Debug warning|[..]: Bad argument @ 'killTimer' Line: ..}}

Except for that (we will talk about that later) everything seems to work fine. A player enters the colshape, the timer is started, if he stays the message occurs, if he leaves the timer is killed.

===A more inconspicuous error===
But for some reason the message gets outputted twice when you stay in the colcircle while in a vehicle. Since it would appear some code is executed twice, we add debug messages to check this.

<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- add a debug message
outputDebugString("colShapeHit")
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- add a debug message
outputDebugString("colShapeLeave")
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",getRootElement(),colShapeLeave)
</syntaxhighlight>

Now we notice that both handler functions get executed twice when we are in a vehicle, but only once when we are on-foot. It would appear the vehicle triggers the colshape as well. To confirm this theory, we ensure that the ''player'' variable actually holds a reference to a player element.

<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- add a debug message, with the element type
outputDebugString("colShapeHit "..getElementType(player))
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- add a debug message, with the element type
outputDebugString("colShapeLeave "..getElementType(player))
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",getRootElement(),colShapeLeave)
</syntaxhighlight>

The debug messages tell us that one of the ''player'' variables is a player and that the other one is a vehicle element. Since we only want to react when a player enters the colshape, we add an ''if'' that will end the execution of the function if it's '''not''' an player element.

<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- add a check for the element type
if (getElementType(player) ~= "player") then return end
-- add a debug message, with the element type
outputDebugString("colShapeHit "..getElementType(player))
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- add a check for the element type
if (getElementType(player) ~= "player") then return end
-- add a debug message, with the element type
outputDebugString("colShapeLeave "..getElementType(player))
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",getRootElement(),colShapeLeave)
</syntaxhighlight>

Now the script should work as desired, but it will still output the warning mentioned above. This happens because the timer we try to kill when a player leaves the colshape will not exist anymore when it has reached the 10 seconds (and therefore executed after the 10th second has completed). There are different ways to get rid of that warning (since you know that the timer might not exist anymore and you only want to kill it if it exists). One way would be to check if the timer referenced in the table really exists. To do this, we need to use [[isTimer]], which we will use when we kill the timer:
<syntaxhighlight lang="lua">
if (isTimer(colshapeTimer[player])) then
killTimer(colshapeTimer[player])
end
</syntaxhighlight>

So the complete working code would be:
<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- add a check for the element type
if (getElementType(player) ~= "player") then return end
-- add a debug message, with the element type
outputDebugString("colShapeHit "..getElementType(player))
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- add a check for the element type
if (getElementType(player) ~= "player") then return end
-- add a debug message, with the element type
outputDebugString("colShapeLeave "..getElementType(player))
-- kill the timer when the player leaves the colshape
if (isTimer(colshapeTimer[player])) then
killTimer(colshapeTimer[player])
end
end
addEventHandler("onColShapeLeave",getRootElement(),colShapeLeave)
</syntaxhighlight>

==Debugging Performance Issues==

If your server is using up more resources than it should or you just want to make sure your scripts are efficient, you can find the source of the issue by using a great tool that comes with the default resource package called [[Resource:Performancebrowser|performancebrowser]]. You can start it with ''''start performancebrowser''''. If it doesn't exist then you can get the latest resources from the [https://github.com/multitheftauto/mtasa-resources GitHub repository]. This tool provides an incredible amount of information for performance debugging. Memory leaks, element leaks and CPU intensive scripts are all easily findable via performancebrowser. If you use the ''''d'''' option in Lua timing you can see which functions are using up the CPU.

To access performancebrowser you will need to go to your web browser and enter the address: http://serverIPHere:serverHTTPPortHere/performancebrowser/ Note that the / at the end is required. So for example: http://127.0.0.1:22005/performancebrowser/ You will then need to login with an in-game admin account or any account that has access to ''''resource.performancebrowser.http'''' and ''''resource.ajax.http''''. Most of the information you will need are in the categories Lua timing and Lua memory, look for values that are much higher than other values.

===Examples of scripts that could cause performance problems===

Adding data to a table but never removing it. This would take months/years before it causes a problem though.
<syntaxhighlight lang="lua">
local someData = {}

function storeData()
someData[source] = true
-- There is no handling for when a player quits, this is considered a memory leak
-- Using the Lua timing tab you can detect the RAM usage of each resource.
end
addEventHandler("onPlayerJoin", root, storeData)
</syntaxhighlight>

Element leaking is possible if you use temporary colshapes for whatever reason and may not destroy them. This would cause bandwidth, CPU and memory performance issues over time.
<syntaxhighlight lang="lua">
function useTemporaryCol()
local col = createColCircle(some code here)
if (normally this should happen) then
destroyElement(col)
end
-- But sometimes it didn't so the script ended but the collision area remained and over time
-- you may end up with hundreds to thousands of pointless collision areas.
-- The Lua timing tab allows you to see the amount of elements each script has created.
end
</syntaxhighlight>

High CPU usage resulting in the server FPS dropping so much that the server is unplayable. In under 24 hours this can create havoc on a very busy server. The amount of "refs" in the Lua timing detect this type of build up, surprisingly the Lua timing tab didn't help in this case but Lua memory did.
<syntaxhighlight lang="lua">
addEventHandler("onPlayerJoin", root, function()
-- Code for joiner
addEventHandler("onPlayerQuit", root, function()
-- Code for when they have quit
-- See the problem? It's bound to root which the event handler is being added again and again and again
end)
end)
</syntaxhighlight>

A function uses up a lot of your CPU because whatever it does takes a long time. This is just some function that takes a long time to complete. Without performancebrowser you'd have no idea its the cause but with performancebrowser you can see that a resource is using lots of CPU in the Lua timing tab. If you then enter: ''''d'''' into the options edit box it will even tell you what file name and first line of the function that is using up so much CPU.
<syntaxhighlight lang="lua">
function someDodgyCode()
for i=1, 100000 do
-- some code
end
end
</syntaxhighlight>

[[it:Guida al Debug]]
[[Category:Scripting Concepts]]
[[ru:Debugging]]
[[zh-cn:脚本调试教程]]
[[Category:Tutorials]]

SetVehicleLightState

2018-03-06T15:49:51Z

MrTasty: Added OOP syntax part

{{Server client function}}
__NOTOC__
This function sets the state of the light on the vehicle.

==Syntax==
<syntaxhighlight lang="lua">bool setVehicleLightState ( vehicle theVehicle, int light, int state )</syntaxhighlight>
{{OOP||[[vehicle]]:setLightState||getVehicleLightState}}

==Required Arguments==
*'''theVehicle:''' A handle to the [[vehicle]] that you wish to change the light state of.
*'''light:''' A whole number determining the individual light. (0 - 3)
*'''state:''' A whole number determining the new state of the light. ''0'' represents normal lights, and ''1'' represents broken lights.

===Returns===
Returns ''true'' if the light state was set successfully, ''false'' if invalid arguments were passed to the function.

==Example==
<syntaxhighlight lang="lua">
newcar = createVehicle ( 520, 1024, 1024, 1024 ) -- create a new vehicle
state = setVehicleLightState ( newcar, 0, 1 ) -- break the left front light
</syntaxhighlight>

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

FileOpen

2017-08-04T14:29:01Z

MrTasty: Added warning about function's limitations as of 1.5.4.

__NOTOC__
{{Server client function}}
Opens an existing file for reading and writing.
{{Note|To prevent memory leaks, ensure each successful call to [[fileOpen]] has a matching call to [[fileClose]].}}
{{Tip|The file functions should not be used to implement configuration files. It is encouraged to use the XML functions for this instead.}}
{{MessageBox|bordercolorhex=FFB2B2|bgcolorhex=FFE5E5|image=File:Dialog-warning.png|title=Warning:|message=As of 1.5.4 [https://buildinfo.mtasa.com/?Author=&Branch=&Revision=10413 r10413], this function will fail when trying to access a script file of another resource, even with ''general.ModifyOtherObjects'' rights granted, which uses a ''mysql'' connection through [[dbConnect]] when [[Server_mtaserver.conf#database_credentials_protection|''database_credentials_protection'']] is enabled in the server configuration. Additionally, meta.xml will be un-writable and will always open in read-only mode.}} 

==Syntax==
<syntaxhighlight lang="lua">
file fileOpen ( string filePath [, bool readOnly = false ])
</syntaxhighlight>
{{OOP||[[File]]}}

===Required Arguments===
*'''filePath:''' The [[filepath]] of the file in the following format: '''":resourceName/path"'''. 'resourceName' is the name of the resource the file is in, and 'path' is the path from the root directory of the resource to the file.
:For example, if there is a file named 'coolObjects.txt' in the resource 'objectSearch', it can be opened from another resource this way: ''fileOpen(":objectSearch/coolObjects.txt")''.
:If the file is in the current resource, only the file path is necessary, e.g. ''fileOpen("coolObjects.txt")''.

===Optional Arguments===
*'''readOnly:''' By default, the file is opened with reading and writing access. You can specify ''true'' for this parameter if you only need reading access.

===Returns===
If successful, returns a file handle for the file. Otherwise returns ''false'' (f.e. if the file doesn't exist).

==Example==
This example opens the file test.txt that is in the root of the current resource, and outputs its contents to the console.
<syntaxhighlight lang="lua">
local hFile = fileOpen("test.txt", true) -- attempt to open the file (read only)
if hFile then -- check if it was successfully opened
local buffer
while not fileIsEOF(hFile) do -- as long as we're not at the end of the file...
buffer = fileRead(hFile, 500) -- ... read the next 500 bytes...
outputConsole(buffer) -- ... and output them to the console
end
fileClose(hFile) -- close the file once we're done with it
else
outputConsole("Unable to open test.txt")
end
</syntaxhighlight>

This example show how to append data to an existing file:
<syntaxhighlight lang="lua">
local hFile = fileOpen("test.txt") -- attempt to open the file (read and write mode)
if hFile then -- check if it was successfully opened
fileSetPos( hFile, fileGetSize( hFile ) ) -- move position to the end of the file
fileWrite(hFile, "hello" ) -- append data
fileClose(hFile) -- close the file once we're done with it
else
outputConsole("Unable to open test.txt")
end
</syntaxhighlight>
==See Also==
{{File functions}}

RangeToTable

2015-10-14T18:07:16Z

MrTasty: /* Code */

{{Useful Function}}
{{Needs_Example}}
__NOTOC__
This function converts a string range to a table containing number values.

==Syntax==
<syntaxhighlight lang="lua">table rangeToTable ( string range )</syntaxhighlight>

===Required Arguments===
* '''range''': The range string (eg. "1,4,10-15,2").

===Returns===
Returns a table containing all ranged values.

==Code==
<syntaxhighlight lang="lua">
function rangeToTable( range )
assert(range, type(range)=="string", "Bad argument @ rangeToTable. Expected 'string', got '"..type(range).."'")
local numbers = split(range, ",")
local output = {}
for k, v in ipairs(numbers) do
if tonumber(v) then
table.insert(output, tonumber(v))
else
local st,en = tonumber(gettok(v, 1, "-")), tonumber(gettok(v, 2, "-"))
if st and en then
for i = st, en, (st<en and 1 or -1) do
table.insert(output, tonumber(i))
end
end
end
end
return output
end
</syntaxhighlight>
'''Author: MrTasty'''

==Example==
Needs example.
<syntaxhighlight lang="lua">
--TODO
</syntaxhighlight>

==See Also==
{{Useful_Functions}}

Writing Gamemodes

2015-08-24T06:49:36Z

MrTasty: /* Helpmanager */

This guide tries to outline the process of how to write a proper gamemode. If you just started with scripting for MTA, you may want to check the other scripting tutorials at the [[Main Page]] first.
==Introduction==
A gamemode is a resource that, once started, controls all of the gameplay. This may include telling the players what to do, spawning players, creating teams, defining what the players have to do to win or to get points and much more. Examples are Race and Deathmatch.

==What does "proper gamemode" mean?==
To put it simply, a proper gamemode is one that makes full use of MTA's .map file system. This means that the gamemode code does not have any map-specific data hardcoded in it, like positions of players or cars. Instead, the gamemode should be able to load .map files which define these data. This way the gamemode can have multiple maps; also, people can create .map files for the gamemode with MTA's map editor, which is much more convenient than writing code.

An obvious example of a "proper gamemode" is MTA:Race. It allows usermade maps with lots of possibilities within the .map file. To alter spawnpoints, objects etc., the user doesn't need to edit the gamemode itself.

===Map Files===
Map files are basically XML documents with a .map extension. They define an environment to play one or more specific gamemodes in. They are however not supposed to change the rules of the game - those are defined by the gamemode.

Each element in a map corresponds to a node in the .map file. There is standard syntax for common things like spawnpoints, objects and vehicles; however, for "special", gamemode specific information, you need to invent your own syntax.

====Example====
Let's take a Capture the Flag gamemode as an example. A map for this gamemode needs to mainly define spawnpoints and flag locations, and eventually objects and vehicles. A simplified map file could look like this:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Here you can see two MTA elements - a spawnpoint and a pickup. More importantly, this .map has a custom "flag" node which defines the position and color of the flag. The spawnpoint and pickup can be handled by existing external resources, custom elements have to be processed by the gamemode.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Example of getting the .map information====
As mentioned above, your gamemode needs de retrieve custom elements that are defined in a map file and process them. This is quite easy as demonstrated below.
<syntaxhighlight lang="lua">
-- retrieve a table with all flag elements
local flagElements = getElementsByType ( "flag" )
-- loop through them
for key, value in pairs(flagElements) do
-- get our info
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- create an object according to the flag position
createObject ( 1337, posX, posY, posZ )
-- output the team that we created a base for
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
The [[getElementsByType]] function retrieves a table of all the elements of a certain type (the type corresponds to the node name in the .map file). This works for both custom types and built-in MTA types (like "vehicle" or "player").
[[getElementData]] can be used to retrieve the xml attributes set in the .map file.
In this simple example, an object is created at the flag's location and a message is outputted in the chatbox. In reality, you will of course need to do more during map loading, like in this case setting up collision shapes to detect players taking the flag.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above
-- spawn players etc.
end
addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the [[Resource:Helpmanager|helpmanager help page]] for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the [[Resource:Dxscoreboard|scoreboard help page]] for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[it:Scrivere una gamemode]]
[[ru:Writing Gamemodes]]
[[de:Gamemodes schreiben]]
[[Category:Tutorials]]

Writing Gamemodes

2015-08-24T06:49:34Z

MrTasty: /* Scoreboard */

This guide tries to outline the process of how to write a proper gamemode. If you just started with scripting for MTA, you may want to check the other scripting tutorials at the [[Main Page]] first.
==Introduction==
A gamemode is a resource that, once started, controls all of the gameplay. This may include telling the players what to do, spawning players, creating teams, defining what the players have to do to win or to get points and much more. Examples are Race and Deathmatch.

==What does "proper gamemode" mean?==
To put it simply, a proper gamemode is one that makes full use of MTA's .map file system. This means that the gamemode code does not have any map-specific data hardcoded in it, like positions of players or cars. Instead, the gamemode should be able to load .map files which define these data. This way the gamemode can have multiple maps; also, people can create .map files for the gamemode with MTA's map editor, which is much more convenient than writing code.

An obvious example of a "proper gamemode" is MTA:Race. It allows usermade maps with lots of possibilities within the .map file. To alter spawnpoints, objects etc., the user doesn't need to edit the gamemode itself.

===Map Files===
Map files are basically XML documents with a .map extension. They define an environment to play one or more specific gamemodes in. They are however not supposed to change the rules of the game - those are defined by the gamemode.

Each element in a map corresponds to a node in the .map file. There is standard syntax for common things like spawnpoints, objects and vehicles; however, for "special", gamemode specific information, you need to invent your own syntax.

====Example====
Let's take a Capture the Flag gamemode as an example. A map for this gamemode needs to mainly define spawnpoints and flag locations, and eventually objects and vehicles. A simplified map file could look like this:
<syntaxhighlight lang="xml">
<map>
<spawnpoint id="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup id="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
...
</map>
</syntaxhighlight>

Here you can see two MTA elements - a spawnpoint and a pickup. More importantly, this .map has a custom "flag" node which defines the position and color of the flag. The spawnpoint and pickup can be handled by existing external resources, custom elements have to be processed by the gamemode.

To summarize - we want mass mapper input as we saw in MTA:Race. Users should NOT have to touch the gamemode script itself at all.

====Example of getting the .map information====
As mentioned above, your gamemode needs de retrieve custom elements that are defined in a map file and process them. This is quite easy as demonstrated below.
<syntaxhighlight lang="lua">
-- retrieve a table with all flag elements
local flagElements = getElementsByType ( "flag" )
-- loop through them
for key, value in pairs(flagElements) do
-- get our info
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
-- create an object according to the flag position
createObject ( 1337, posX, posY, posZ )
-- output the team that we created a base for
outputChatBox ( "Base for team " .. team .. " created" )
end
</syntaxhighlight>
The [[getElementsByType]] function retrieves a table of all the elements of a certain type (the type corresponds to the node name in the .map file). This works for both custom types and built-in MTA types (like "vehicle" or "player").
[[getElementData]] can be used to retrieve the xml attributes set in the .map file.
In this simple example, an object is created at the flag's location and a message is outputted in the chatbox. In reality, you will of course need to do more during map loading, like in this case setting up collision shapes to detect players taking the flag.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that always stays the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event ([[onGamemodeMapStart]]) to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. More specifically you'll be setting the "type" attribute of its <info> tag to "gamemode" inside meta.xml. Also, you can set the "name" attribute to a friendly name (like "Capture the flag") that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart
* onGamemodeMapStop (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within the handler function for these events you can extract all info you need from the resource's map files and configuration files.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
local mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above
-- spawn players etc.
end
addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well: the "type" attribute must be set to "map", and the "gamemodes" attribute must be a comma-separated list (no spaces) of gamemode resource names that the map works with.
<syntaxhighlight lang="xml">

<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in its own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that needs its own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the player's points gained through kills or captures. As usual, see the [[Resource:Dxscoreboard|scoreboard help page]] for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

[[it:Scrivere una gamemode]]
[[ru:Writing Gamemodes]]
[[de:Gamemodes schreiben]]
[[Category:Tutorials]]

OnClientVehicleEnter

2015-07-23T21:07:17Z

MrTasty: /* Example */ Typo fixed

{{Client event}}
__NOTOC__
This event gets fired when a player enters a vehicle.

==Parameters==
<syntaxhighlight lang="lua">
player thePlayer, int seat
</syntaxhighlight>
*'''thePlayer:''' the player that entered the vehicle
*'''seat:''' the number of the seat that the player is now sitting on. 0 = driver, higher numbers are passenger seats.

==Source==
The source of the event is the vehicle that the player entered.

==Example==
This code updates a GUI label with the name of the vehicle the local player is in.
<syntaxhighlight lang="lua">
lblVehicle = guiCreateLabel(10, 200, 150, 20, "Currently on foot", false)
addEventHandler("onClientVehicleEnter", getRootElement(),
function(thePlayer, seat)
if thePlayer == getLocalPlayer() then
guiSetText(lblVehicle, "Currently in a " .. getVehicleName(source))
end
end
)
addEventHandler("onClientVehicleExit", getRootElement(),
function(thePlayer, seat)
if thePlayer == getLocalPlayer() then
guiSetText(lblVehicle, "Currently on foot")
end
end
)
</syntaxhighlight>

==See Also==
===Client vehicle events===
{{Client_vehicle_events}}
===Client event functions===
{{Client_event_functions}}
[[es:onClientVehicleEnter]]

Scripting Tips

2015-05-29T08:59:39Z

MrTasty: /* General Lua */ Added another point

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

== General Lua ==
* The ''infinite loop / too long execution error'' which aborts execution can be disabled with ''debug.sethook(nil)''
* Be careful when looping a table where you intend to delete multiple rows, if 2 of them are in a row the 2nd one will get skipped! You must loop the table backwards (reverse ipairs). For example: ''for i = #table, 1, -1 do''
* Rather than having if checks inside if checks inside if checks, consider using ''return'' for example ''if (not ready) then return false end''
* Keep variable & function names short - longer names will make the file larger in size. In large files, this will increase download time.
* Remember that 'false' boolean has a value - If you want to delete a variable or element/account data, use 'nil' instead - this will reduce memory and disk usage (minuscule optimisation, only notable on larger servers)

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

local loadedFunction = loadstring(exampleFunction)</syntaxhighlight>

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

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

local admins = {}
local secretPasswordOnlyAdminsShouldKnow = "12345678"

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

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

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

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

== Server Performance ==
* Server lagging? Check [[Debugging#Debugging_Performance_Issues|this page of debugging performance issues]]
* Using resourceRoot in event handlers for events from clients is much more efficient than using root.
* Try to be efficient, but if what you're doing is too time consuming or complex, is it really efficient?
* It's much more efficient to set player health client side, consider a client event all your server scripts can call to set a players health.
* Unless you have hundreds of players, don't worry about making little optimizations, check ''performancebrowser'' or ''ipb'' (ingame performancebrowser) and make sure no resource is using significantly more than the others.

== Client Performance ==
* The biggest cause of client script CPU usage is anything done in onClient/Pre/Hud/Render because it is called so often. For example if you have a script which calls dxDrawLine3D 20 times, 60 times a second, if those lines are only in 1 part of the map, consider adding a [[getDistanceBetweenPoints3D]] check between the local player and the general area that those lines are in and if they're no where near the player, don't draw the lines.

GetCameraRotation

2015-05-04T21:07:52Z

MrTasty: Fixed a typo

__NOTOC__
{{Client function}}
{{Warning|'''This function no longer exists'''. However, below is a function that achieves a similar result.|true}}

<syntaxhighlight lang="lua">
local function getCameraRotation ()
local px, py, pz, lx, ly, lz = getCameraMatrix()
local rotz = 6.2831853071796 - math.atan2 ( ( lx - px ), ( ly - py ) ) % 6.2831853071796
local rotx = math.atan2 ( lz - pz, getDistanceBetweenPoints2D ( lx, ly, px, py ) )
--Convert to degrees
rotx = math.deg(rotx)
rotz = -math.deg(rotz)
return rotx, 180, rotz
end
</syntaxhighlight>

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

RangeToTable

2015-04-10T11:00:09Z

MrTasty:

{{Useful Function}}
{{Needs_Example}}
__NOTOC__
This function converts a string range to a table containing number values.

==Syntax==
<syntaxhighlight lang="lua">table rangeToTable ( string range )</syntaxhighlight>

===Required Arguments===
* '''range''': The range string (eg. "1,4,10-15,2").

===Returns===
Returns a table containing all ranged values.

==Code==
<syntaxhighlight lang="lua">
function rangeToTable( range )
assert(range, type(range)=="string", "Bad argument @ rangeToTable. Expected 'string', got '"..type(range).."'")
local numbers = split(range, ",")
local output = {}
for k, v in ipairs(numbers) do
if tonumber(v) then
table.insert(output, tonumber(v))
else
local st,en = gettok(v, 1, "-"), gettok(v, 2, "-")
for i = st, en, (st<en and 1 or -1) do
table.insert(output, tonumber(i))
end
end
end
return output
end
</syntaxhighlight>
'''Author: MrTasty'''

==Example==
Needs example.
<syntaxhighlight lang="lua">
--TODO
</syntaxhighlight>

==See Also==
{{Useful_Functions}}

Template:Useful Functions

2015-04-10T10:59:17Z

MrTasty: Added rangeToTable

*[[attachEffect]] » This function allows you attach an effect to an element.
*[[bindControlKeys]] » This function allows you to bind each key bound to a control individually. Doing this bypasses a little MTA restriction.
*[[callClientFunction]] » This function allows you to call any client-side function from the server's side.
*[[callServerFunction]] » This function allows you to call any server-side function from the client's side.
*[[capitalize]] » This function capitalizes a given string.
*[[centerWindow]] » This function centers a CEGUI window element responsively in any resolution.
*[[Check]] » This function checks if its arguments are of the right type and calls the error-function if one is not.
*[[convertNumber]] » This function converts and formats large numbers.
*[[convertServerTickToTimeStamp]] » This function converts server ticks to a unix timestamp.
*[[convertTextToSpeech]] » This function converts the provided text to a speech in the provided language which players can hear.
*[[coroutine.resume]] » This function applies a fix for hidden coroutine error messages.
*[[dxDrawAnimWindow]] » This function draws an animated 2D window on the screen.
*[[dxDrawCircle]] » This function draws a number of 2D lines in order to achieve a circle shape on the screen.
*[[dxDrawEmptyRec]] » This function draws an empty 2D rectangle on the screen.
*[[dxDrawGifImage]] » This function simulates the effect of a GIF image by using image sprites in 2D.
*[[dxDrawImage3D]] » This function draws a 3D image in GTA world.
*[[dxDrawRectangle3D]] » This function draws a 3D rectangle in GTA world.
*[[dxGetFontSizeFromHeight]] » This function calculates the font size from given height.
*[[dxGetRealFontHeight]] » This function calculates the height of a font.
*[[findRotation]] » This function takes two points and returns the direction from point A to point B.
*[[FormatDate]] » This function formats a date on the basis of a format string and returns it.
*[[GenerateString]] » This function generates a random string with any characters.
*[[generateRandomASCIIString]] » This function returns a random string which uses ASCII characters. 
*[[getAge]] » This function calculates the age of a given birthday.
*[[getAlivePlayers (Client)|getAlivePlayers]] » This function returns a table of the alive players client-side.
*[[getAlivePlayersInTeam]] » This function returns a table of the alive players in a team.
*[[getBanFromName]] » This functions returns the ban of the given playername.
*[[getBoundControls]] » This function returns a table of control names that are bound to the specified key.
*[[getCurrentFPS]] » This function returns the frames per second at which GTA: SA is running.
*[[getCursorMoveOn]] » This function checks in which way the cursor is currently moving.
*[[getDistanceBetweenPointAndSegment2D]] » This function takes point coordinates and line (a segment) starting and ending coordinates. It returns the shortest distance between the point and the line.
*[[getElementSpeed]] » This function returns the specified element's speed in m/s, km/h or mph.
*[[getElementsInDimension]] » This function returns a table of elements that are in the specified dimension.
*[[getElementsWithinMarker]] » This function returns a table of elements that are within a marker's collision shape.
*[[getJetpackWeaponsEnabled]] » This function returns a table of enabled weapons usable on a jetpack.
*[[getKeyFromValueInTable]] » This function returns the key of the specified value in a table.
*[[getOffsetFromXYZ]] » This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.
*[[getOnlineAdmins]] » This function returns a table of all logged-in administrators.
*[[getOnlineStaff]] » This function returns a string of all logged-in administrators separated by two whitespace characters.
*[[getPedMaxHealth]] » This function returns a pedestrians's maximum health by converting it from their maximum health stat.
*[[getPedMaxOxygenLevel]] » This function returns a ped's maximum oxygen level by converting it from their maximum underwater stamina stat.
*[[getPlayerFromNamePart]] » This function returns a player from partial name.
*[[getPlayerFromSerial]] » This function returns a player from their serial.
*[[getPlayerAcls]] » This function returns a table of all ACL groups on a player.
*[[getPlayersByData]] » This function returns a table of players that have the specified data name.
*[[getPlayersInPhotograph]] » This function returns a table of all players in photograph.
*[[getPlayerCity]] » This functions returns a string containing the player's city name
*[[getPointFromDistanceRotation]] » This function finds a point based on a starting point, direction and distance.
*[[getResourceSettings]] » This function returns a table of the resource settings.
*[[getResourceScripts]] » This function returns a table of the resource scripts.
*[[getRGColorFromPercentage]] »This function returns two integers representing red and green colors according to the specified percentage.
*[[getScreenRotationFromWorldPosition]] » This function returns a screen relative rotation to a world position.
*[[getTeamFromColor]] » This function returns a team element by the specified color.
*[[getTeamWithFewestPlayers]] » This function returns a team element with least players of all the specified teams.
*[[getTimestamp]] » This function returns the UNIX timestamp of a specified date and time.
*[[getValidVehicleModels]] » This function returns a table of all valid vehicle models.
*[[getVehicleRespawnPosition]] » This function allows you to get the respawn position of a vehicle.
*[[getXMLNodes]] » This function returns all children of a XML node.
*[[guiComboBoxAdjustHeight]] » This function adjusts a CEGUI combobox element to have the correct height.
*[[guiGridListGetSelectedText]] » This function returns a string containing the inner text of a selected gridlist item.
*[[IfElse]] » This function returns one of two values based on a boolean expression.
*[[isElementInPhotograph]] » This function checks if an element is in the player's camera picture area.
*[[isElementInRange]] » This function allows you to check if an element's range to a main point is within the maximum range.
*[[isElementMoving]]» This function checks if an element is moving.
*[[isElementWithinAColShape]]» This function checks if an element is within a collision shape element.
*[[isLeapYear]] » This function returns a boolean representing if a given year is a leap year.
*[[isMouseInPosition]] » This function allows you to check whether the mouse cursor/pointer is within a rectangular position.
*[[isPedAiming]]» This function checks if a pedestrian is aiming their weapon.
*[[isPedDrivingVehicle]] » This function checks if a specified pedestrian is driving a vehicle.
*[[isPlayerInACL]] » This function checks if a player element is in an ACL group.
*[[isPlayerInTeam]] » This function checks if a player is in a specified team.
*[[isSoundFinished]] » This function checks if a sound element has finished.
*[[isVehicleEmpty]] » This function checks whether a vehicle is empty.
*[[isVehicleOccupied]] » This function checks if a specified vehicle is occupied.
*[[isVehicleOnRoof]] » This function checks whether vehicle is on roof.
*[[iterElements]] » This function returns ''a time-saving'' iterator for your for-loops.
*[[mathNumber]] » This function is a workaround for the client-side floating-point precision of 24-bits.
*[[math.percent]] » This function returns a percentage from two number values.
*[[math.round]] » Rounds a number whereas the number of decimals to keep and the method may be set.
*[[multi_check]] » This function checks one element to many, handy and clean.
*[[onVehicleWeaponFire]] » This code implements an event that is triggered when a player in a vehicle fires a vehicle's weapon.
*[[rangeToTable]] » This function converts a string range to a table containing number values.
*[[renameAclGroup]] » This function gives an existing ACL group a new name.
*[[RGBToHex]] » This function returns a string representing the color in hexadecimal.
*[[secondsToTimeDesc]] » This function converts a plain seconds-integer into a user-friendly time description.
*[[setAccountName]] » This function is used to change an existing account's name.
*[[setElementSpeed]] » This function allows you to set the speed of an element in kph or mph units.
*[[setTableProtected]] » This function protects a table and makes it read-only.
*[[setVehicleGravityPoint]] » This function sets a vehicle's gravity in the direction of a 3 dimensional coordinate with the strength specified.
*[[smoothMoveCamera]] » This function allows you to create a cinematic camera flight.
*[[string.count]] » This function counts the amount of occurences of a string in a string.
*[[string.explode]] » This function splits a string at a given separator pattern and returns a table with the pieces.
*[[switch]] » This function allows the value of a variable or expression to control the flow of program execution via a multiway branch.
*[[table.copy]] » This function copies a whole table and all the tables in that table.
*[[table.compare]] » This function checks whether two given tables are equal.
*[[table.empty]] » This function checks whether a table is empty.
*[[table.map]] » This function goes through a table and replaces every field with the return of the passed function, where the field's value is passed as first argument and optionally more arguments.
*[[table.merge]] » This function merges two or more tables together.
*[[table.random]] » This function retrieves a random value from a table.
*[[table.size]] » This function returns the absolute size of a table.
*[[toHex]] » This function converts a decimal number to a hexadecimal number, as a fix to be used client-side.
*[[unbindControlKeys]] » This function allows you to unbind each key bound to a control individually. Use this function with [[bindControlKeys]].
*[[var dump]] » This function outputs information about one or more variables using outputConsole.
*[[wavelengthToRGBA]] » This function converts a physical wavelength of light to a RGBA color.
*[[isPedAimingNearPed]] » This is similar to isPedAiming but uses a colshape to be more precise.
[[Category:Useful Functions]]

RangeToTable

2015-04-10T10:58:16Z

MrTasty: Created page with "{{Useful Function}} {{Needs_Example}} __NOTOC__ This function converts a string range to a table containing number values ==Syntax== <syntaxhighlight lang="lua">table rangeToTable ( string ..."

{{Useful Function}}
{{Needs_Example}}
__NOTOC__
This function converts a string range to a table containing number values

==Syntax==
<syntaxhighlight lang="lua">table rangeToTable ( string range )</syntaxhighlight>

===Required Arguments===
* '''range''': The range string (eg. "1,4,10-15,2")

===Returns===
Returns a table containing all ranged values

==Code==
<syntaxhighlight lang="lua">
function rangeToTable( range )
assert(range, type(range)=="string", "Bad argument @ rangeToTable. Expected 'string', got '"..type(range).."'")
local numbers = split(range, ",")
local output = {}
for k, v in ipairs(numbers) do
if tonumber(v) then
table.insert(output, tonumber(v))
else
local st,en = gettok(v, 1, "-"), gettok(v, 2, "-")
for i = st, en, (st<en and 1 or -1) do
table.insert(output, tonumber(i))
end
end
end
return output
end
</syntaxhighlight>
'''Author: MrTasty'''

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

==See Also==
{{Useful_Functions}}

AclRemoveRight

2015-04-09T13:49:41Z

MrTasty: /* Example */

__NOTOC__
{{Server function}}

This function removes the given right (string) from the given ACL.

==Syntax==

<syntaxhighlight lang="lua">
bool aclRemoveRight ( acl theAcl, string rightName )
</syntaxhighlight>
{{OOP||[[acl]]:removeRight||}}
===Required Arguments===

*'''theAcl:''' The ACL to remove the right from
*'''rightName:''' The ACL name to remove from the right from

===Returns===

Returns ''true'' if the given right was successfully removed from the given ACL, ''false'' or ''nil'' if it could not be removed for some reason, ie. it didn't exist in the ACL.

==Example==
This example removes an acl right on resource start.
<syntaxhighlight lang="lua">
addEventHandler("onResourceStart",resourceRoot,function()
aclRemoveRight(aclGet("Admin"),"function.setServerPassword")
end)
</syntaxhighlight>

==See Also==

{{ACL_functions}}

Scripting Tips

2015-04-07T10:22:25Z

MrTasty:

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

== General Lua ==
* The ''infinite loop / too long execution error'' which aborts execution can be disabled with ''debug.sethook(nil)''
* Be careful when looping a table where you intend to delete multiple rows, if 2 of them are in a row the 2nd one will get skipped! You must loop the table backwards (reverse ipairs). For example: ''for i = #table, 1, -1 do''
* Rather than having if checks inside if checks inside if checks, consider using ''return'' for example ''if (not ready) then return false end''
* Keep variable & function names short - longer names will make the file larger in size. In large files, this will increase download time.
== MTA Scripting ==
* Remember that 99% of the time it's a bug in your script, not an MTA bug! Don't report something to the mantis until you're absolutely certain the bug can be reproduced with a small piece of script.
* As MTA already has so many functions and events virtually everything you want to do is already possible, as long as you're willing to do the work! You'll find better solutions to problems as there are many ways to achieve the same thing as long as you know all the functions and events.
* If a script is getting too complicated, try putting back-end stuff in another file so the main script calls the functions in the 2nd one. For example rather than having meaningless things like ''vehicleTable[vehicle][7]'' in the main file, put that in a function in the 2nd file and have the main file call a meaningfully named function so rather than seeing a useless ''7'' you'd see something like ''getFuel'' and although this might take longer to set-up you'll save time in the long run as you'll spend less time being confused when you come back to it in a weeks time to debug a problem.
* Your client side scripts can cause desync if you're not careful, try to keep the psychical world equal with every player. For example if your script creates a client side object make sure your script will create it for everyone nearby, else people will be wondering why a player appears to be constantly floating and falling.
* Instead of using ''onClientResourceStart'' or ''onResourceStart'' events attached to ''resourceRoot'' like this:
<syntaxhighlight lang="lua">function warnPeopleThatThisResourceStarted()
outputChatBox("The resource " .. getResourceName(resource) .. " has just started!", 0, 255, 0)
end
addEventHandler("onClientResourceStart", resourceRoot, warnPeopleThatThisResourceStarted)</syntaxhighlight>
You can also use this outside of any function:
<syntaxhighlight lang="lua">outputChatBox("The resource " .. getResourceName(resource) .. " has just started!", 0, 255, 0)</syntaxhighlight>
And the result will be the same, because Lua executes every instruction in every script file of a resource when it starts.
* string.dump produces unsigned compiled Lua code which is not allowed for security reasons. The only way to transport code now is by using the source code. e.g.:
<syntaxhighlight lang="lua">exampleFunction = [===[
return param
]===]

local loadedFunction = loadstring(exampleFunction)</syntaxhighlight>

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

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

local admins = {}
local secretPasswordOnlyAdminsShouldKnow = "12345678"

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

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

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

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

== Server Performance ==
* Server lagging? Check [[Debugging#Debugging_Performance_Issues|this page of debugging performance issues]]
* Using resourceRoot in event handlers for events from clients is much more efficient than using root.
* Try to be efficient, but if what you're doing is too time consuming or complex, is it really efficient?
* It's much more efficient to set player health client side, consider a client event all your server scripts can call to set a players health.
* Unless you have hundreds of players, don't worry about making little optimizations, check ''performancebrowser'' or ''ipb'' (ingame performancebrowser) and make sure no resource is using significantly more than the others.

== Client Performance ==
* The biggest cause of client script CPU usage is anything done in onClient/Pre/Hud/Render because it is called so often. For example if you have a script which calls dxDrawLine3D 20 times, 60 times a second, if those lines are only in 1 part of the map, consider adding a [[getDistanceBetweenPoints3D]] check between the local player and the general area that those lines are in and if they're no where near the player, don't draw the lines.

TriggerLatentServerEvent

2015-04-04T14:16:13Z

MrTasty:

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

==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==
<syntaxhighlight lang="lua">
--TODO
</syntaxhighlight>

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

==See Also==
{{Client_event_functions}}

Element/Shader

2015-02-26T13:50:40Z

MrTasty:

The shader class represents a Microsoft HLSL Effect File(.fx) loaded by the client, which can be used instead of a texture when calling [[dxDrawImage]]

The element type of this class is '''"shader"'''.

==How HLSL Effect Files file integrate into MTA:SA==

Note: This page assumes you know what an Effect File and HLSL is. If not, you better do some research first.

You can use this [[shadertest resource]] to try the examples below. Copy the effect source from the code boxes into '''shadertest/clientshader.fx''' and (re)start shadertest to see the output.

After you've done all that, (or maybe before if glancing below is making you panic), visit [[Shader examples|some more shader resource examples]].

===Techniques===
Effect Files usually contain several techniques, but for simplicity, MTA will only use the first technique that will run correctly on the clients hardware. So, for any given Effect File, put your high end techniques first, and the simplest ones last. That way, players with good hardware get the best technique applied, and players with older hardware get at least something.

===Simplest===
Here is the contents of an Effect File with one technique which should work on all hardware:
<syntaxhighlight lang="lua">
//-- Declare the textures. These are set using dxSetShaderValue( shader, "Tex0", texture )
texture Tex0;
texture Tex1;

//-- Very simple technique
technique simple
{
pass P0
{
//-- Set up texture stage 0
Texture[0] = Tex0;
ColorOp[0] = SelectArg1;
ColorArg1[0] = Texture;
AlphaOp[0] = SelectArg1;
AlphaArg1[0] = Texture;

//-- Disable texture stage 1
ColorOp[1] = Disable;
AlphaOp[1] = Disable;
}
}
</syntaxhighlight>
It doesn't use vertex or pixel shaders, only standard D3D render states.
Confusing reference of all the states you can set is here: http://msdn.microsoft.com/en-us/library/bb173347%28v=VS.85%29.aspx

===Not so simple===
Here is an Effect File containing a vertex and pixel shader:
<syntaxhighlight lang="lua">
//-- Declare the textures. These are set using dxSetShaderValue( shader, "Tex0", texture )
texture Tex0;
texture Tex1;

//-- Declare a user variable. This can be set using dxSetShaderValue( shader, "PositionOfCheese", 1, 2, 3 )
float3 PositionOfCheese;

//-- These variables are set automatically by MTA
float4x4 World;
float4x4 View;
float4x4 Projection;
float4x4 WorldViewProjection;
float Time;

//---------------------------------------------------------------------
//-- Sampler for the main texture (needed for pixel shaders)
//---------------------------------------------------------------------
sampler Sampler0 = sampler_state
{
Texture = (Tex0);
};

//---------------------------------------------------------------------
//-- Structure of data sent to the vertex shader
//---------------------------------------------------------------------
struct VSInput
{
float3 Position : POSITION;
float4 Diffuse : COLOR0;
float2 TexCoord : TEXCOORD0;
};

//---------------------------------------------------------------------
//-- Structure of data sent to the pixel shader ( from the vertex shader )
//---------------------------------------------------------------------
struct PSInput
{
float4 Position : POSITION0;
float4 Diffuse : COLOR0;
float2 TexCoord : TEXCOORD0;
};

//-----------------------------------------------------------------------------
//-- VertexShaderExample
//-- 1. Read from VS structure
//-- 2. Process
//-- 3. Write to PS structure
//-----------------------------------------------------------------------------
PSInput VertexShaderExample(VSInput VS)
{
PSInput PS = (PSInput)0;

//-- Transform vertex position (You nearly always have to do something like this)
PS.Position = mul(float4(VS.Position, 1), WorldViewProjection);

//-- Copy the color and texture coords so the pixel shader can use them
PS.Diffuse = VS.Diffuse;
PS.TexCoord = VS.TexCoord;

return PS;
}

//-----------------------------------------------------------------------------
//-- PixelShaderExample
//-- 1. Read from PS structure
//-- 2. Process
//-- 3. Return pixel color
//-----------------------------------------------------------------------------
float4 PixelShaderExample(PSInput PS) : COLOR0
{
//-- Modify the texture coord to make the image look all wobbly
PS.TexCoord.y += sin(PS.TexCoord.y * 100 + Time * 10) * 0.03;

//-- Grab the pixel from the texture
float4 finalColor = tex2D(Sampler0, PS.TexCoord);

//-- Apply color tint
finalColor = finalColor * PS.Diffuse;

return finalColor;
}

//-----------------------------------------------------------------------------
//-- Techniques
//-----------------------------------------------------------------------------

//--
//-- MTA will try this technique first:
//--
technique complercated
{
pass P0
{
VertexShader = compile vs_2_0 VertexShaderExample();
PixelShader = compile ps_2_0 PixelShaderExample();
}
}

//--
//-- And if the preceding technique will not validate on
//-- the players computer, MTA will try this one:
//--
technique simple
{
pass P0
{
//-- Set up texture stage 0
Texture[0] = Tex0;
ColorOp[0] = SelectArg1;
ColorArg1[0] = Texture;
AlphaOp[0] = SelectArg1;
AlphaArg1[0] = Texture;

//-- Disable texture stage 1
ColorOp[1] = Disable;
AlphaOp[1] = Disable;
}
}
</syntaxhighlight>

Technique 'complercated' will be used if the computer supports Shader Model 2, otherwise technique 'simple' will be used. Comments in the source explain what MTA does and where.

===Misc===
Points to remember when switching between editing lua and .fx files:
*HLSL statements often end with a ; (semi-colon)
*HLSL indices start from 0 (where as Lua usually starts from 1)
*HLSL compile errors can be viewed by typing 'debugscript 3' into the client console

==Shaders for world textures==
Here are a couple of examples of shaders to use when replacing world textures with [[engineApplyShaderToWorldTexture]]

===Simple===
This shader just replaces the texture and allows GTA to control all the render states.
<syntaxhighlight lang="lua">
//-- Declare the texture. These are set using dxSetShaderValue( shader, "Tex0", texture )
texture Tex0;

technique simple
{
pass P0
{
//-- Set up texture stage 0
Texture[0] = Tex0;

//-- Leave the rest of the states to the default settings
}
}
</syntaxhighlight> 
===Not so simple===
This shader can be used as a base for replacing a world texture if you intend to add some fancy effect.
It uses [[http://nightly.mtasa.com/files/shaders/mta-helper.fx mta-helper.fx]] to handle consistent naming of the preset shader settings (gWorld, gTexture0 etc.) 
'''''mta-helper.fx''''' also contains some helpful functions which calculate GTA lighting.
<syntaxhighlight lang="lua">
//-----------------------------------------------------------------------
//-- Settings
//-----------------------------------------------------------------------
texture Tex0; //-- Replacement texture

//---------------------------------------------------------------------
// Include some common stuff
//---------------------------------------------------------------------
#include "mta-helper.fx"

//-----------------------------------------------------------------------
//-- Sampler for the new texture
//-----------------------------------------------------------------------
sampler Sampler0 = sampler_state
{
Texture = (Tex0);
};

//-----------------------------------------------------------------------
//-- Structure of data sent to the vertex shader
//-----------------------------------------------------------------------
struct VSInput
{
float3 Position : POSITION0;
float3 Normal : NORMAL0;
float4 Diffuse : COLOR0;
float2 TexCoord : TEXCOORD0;
};

//-----------------------------------------------------------------------
//-- Structure of data sent to the pixel shader ( from the vertex shader )
//-----------------------------------------------------------------------
struct PSInput
{
float4 Position : POSITION0;
float4 Diffuse : COLOR0;
float2 TexCoord : TEXCOORD0;
};

//--------------------------------------------------------------------------------------------
//-- VertexShaderFunction
//-- 1. Read from VS structure
//-- 2. Process
//-- 3. Write to PS structure
//--------------------------------------------------------------------------------------------
PSInput VertexShaderFunction(VSInput VS)
{
PSInput PS = (PSInput)0;

//-- Calculate screen pos of vertex
PS.Position = mul(float4(VS.Position, 1), gWorldViewProjection);

//-- Pass through tex coord
PS.TexCoord = VS.TexCoord;

//-- Calculate GTA lighting for buildings
PS.Diffuse = MTACalcGTABuildingDiffuse( VS.Diffuse );
//--
//-- NOTE: The above line is for GTA buildings.
//-- If you are replacing a vehicle texture, do this instead:
//--
//-- // Calculate GTA lighting for vehicles
//-- float3 WorldNormal = MTACalcWorldNormal( VS.Normal );
//-- PS.Diffuse = MTACalcGTAVehicleDiffuse( WorldNormal, VS.Diffuse );

return PS;
}

//--------------------------------------------------------------------------------------------
//-- PixelShaderFunction
//-- 1. Read from PS structure
//-- 2. Process
//-- 3. Return pixel color
//--------------------------------------------------------------------------------------------
float4 PixelShaderFunction(PSInput PS) : COLOR0
{
//-- Get texture pixel
float4 texel = tex2D(Sampler0, PS.TexCoord);

//-- Apply diffuse lighting
float4 finalColor = texel * PS.Diffuse;

return finalColor;
}

//--------------------------------------------------------------------------------------------
//-- Techniques
//--------------------------------------------------------------------------------------------
technique tec
{
pass P0
{
VertexShader = compile vs_2_0 VertexShaderFunction();
PixelShader = compile ps_2_0 PixelShaderFunction();
}
}

//-- Fallback
technique fallback
{
pass P0
{
//-- Replace texture
Texture[0] = Tex0;

//-- Leave the rest of the states to the default settings
}
}
</syntaxhighlight>

The above code as it stands will calculate the correct lighting for GTA buildings. If you are replacing a vehicle, change:
<syntaxhighlight lang="lua">
//-- Calculate GTA lighting for buildings
PS.Diffuse = MTACalcGTABuildingDiffuse( VS.Diffuse );
</syntaxhighlight>
to:
<syntaxhighlight lang="lua">
//-- Calculate GTA lighting for vehicles
float3 WorldNormal = MTACalcWorldNormal( VS.Normal );
PS.Diffuse = MTACalcGTAVehicleDiffuse( WorldNormal, VS.Diffuse );
</syntaxhighlight> 
==Multiple pass shaders==
To do more than one pass, add '''pass''' blocks like this:
<syntaxhighlight lang="lua">
//-- Declare the texture. These are set using dxSetShaderValue( shader, "Tex0", texture )
texture Tex0;

technique simple
{
pass P0
{
// First pass
Texture[0] = Tex0;
}
pass P1
{
// Second pass
SrcBlend = Add;
DestBlend = One;
}
pass P2
{
// Third pass
SrcBlend = InvDestColor;
DestBlend = InvSrcColor;
}
}
</syntaxhighlight> 
==Related scripting functions==
===Client===
{{Drawing functions}}

[[Category:Element Types]]

Template:Useful Functions

2015-01-03T14:36:13Z

MrTasty:

*[[attachEffect]] » This function allows you attach an effect to an element.
*[[bindControlKeys]] » This function allows you to bind each key bound to a control individually. Doing this bypasses a little MTA restriction.
*[[callClientFunction]] » This function allows you to call any client-side function from the server's side.
*[[callServerFunction]] » This function allows you to call any server-side function from the client's side.
*[[centerWindow]] » This function centers a CEGUI window element responsively in any resolution.
*[[Check]] » This function checks if its arguments are of the right type and calls the error-function if one is not.
*[[convertNumber]] » This function converts and formats large numbers.
*[[convertServerTickToTimeStamp]] » This function converts server ticks to a unix timestamp.
*[[convertTextToSpeech]] » This function converts the provided text to a speech in the provided language which players can hear.
*[[coroutine.resume]] » This function applies a fix for hidden coroutine error messages.
*[[dxDrawAnimWindow]] » This function draws an animated 2D window on the screen.
*[[dxDrawCircle]] » This function draws a number of 2D lines in order to achieve a circle shape on the screen.
*[[dxDrawColorText]] » This function draws 2D text with hexadecimal support on the screen.
*[[dxDrawEmptyRec]] » This function draws an empty 2D rectangle on the screen.
*[[dxDrawGifImage]] » This function simulates the effect of a GIF image by using image sprites in 2D.
*[[dxDrawImage3D]] » This function draws a 3D image in GTA world.
*[[dxDrawRectangle3D]] » This function draws a 3D rectangle in GTA world.
*[[dxGetFontSizeFromHeight]] » This function calculates the font size from given height.
*[[dxGetRealFontHeight]] » This function calculates the height of a font.
*[[findRotation]] » This function takes two points and returns the direction from point A to point B.
*[[FormatDate]] » This function formats a date on the basis of a format string and returns it.
*[[GenerateString]] » This function generates a random string with any characters.
*[[generateRandomASCIIString]] » This function returns a random string which uses ASCII characters. 
*[[getAge]] » This function calculates the age of a given birthday.
*[[getAlivePlayers (Client)|getAlivePlayers]] » This function returns a table of the alive players client-side.
*[[getAlivePlayersInTeam]] » This function returns a table of the alive players in a team.
*[[getBanFromName]] » This functions returns the ban of the given playername.
*[[getBoundControls]] » This function returns a table of control names that are bound to the specified key.
*[[getCurrentFPS]] » This function returns the frames per second at which GTA: SA is running.
*[[getCursorMoveOn]] » This function checks in which way the cursor is currently moving.
*[[getDistanceBetweenPointAndSegment2D]] » This function takes point coordinates and line (a segment) starting and ending coordinates. It returns the shortest distance between the point and the line.
*[[getElementSpeed]] » This function returns the specified element's speed in m/s, km/h or mph.
*[[getElementsInDimension]] » This function returns a table of elements that are in the specified dimension.
*[[getElementsWithinMarker]] » This function returns a table of elements that are within a marker's collision shape.
*[[getJetpackWeaponsEnabled]] » This function returns a table of enabled weapons usable on a jetpack.
*[[getKeyFromValueInTable]] » This function returns the key of the specified value in a table.
*[[getOffsetFromXYZ]] » This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.
*[[getOnlineAdmins]] » This function returns a table of all logged-in administrators.
*[[getOnlineStaff]] » This function returns a string of all logged-in administrators separated by two whitespace characters.
*[[getPedMaxHealth]] » This function returns a pedestrians's maximum health by converting it from their maximum health stat.
*[[getPedMaxOxygenLevel]] » This function returns a ped's maximum oxygen level by converting it from their maximum underwater stamina stat.
*[[getPlayerFromNamePart]] » This function returns a player from partial name.
*[[getPlayerFromSerial]] » This function returns a player from their serial.
*[[getPlayerAcls]] » This function returns a table of all ACL groups on a player.
*[[getPlayersByData]] » This function returns a table of players that have the specified data name.
*[[getPlayersInPhotograph]] » This function returns a table of all players in photograph.
*[[getPlayerCity]] » This functions returns a string containing the player's city name
*[[getPointFromDistanceRotation]] » This function finds a point based on a starting point, direction and distance.
*[[getResourceSettings]] » This function returns a table of the resource settings.
*[[getResourceScripts]] » This function returns a table of the resource scripts.
*[[getRGColorFromPercentage]] »This function returns two integers representing red and green colors according to the specified percentage.
*[[getScreenRotationFromWorldPosition]] » This function returns a screen relative rotation to a world position.
*[[getTeamFromColor]] » This function returns a team element by the specified color.
*[[getTeamWithFewestPlayers]] » This function returns a team element with least players of all the specified teams.
*[[getTimestamp]] » This function returns the UNIX timestamp of a specified date and time.
*[[getValidVehicleModels]] » This function returns a table of all valid vehicle models.
*[[getVehicleRespawnPosition]] » This function allows you to get the respawn position of a vehicle.
*[[getXMLNodes]] » This function returns all children of a XML node.
*[[guiComboBoxAdjustHeight]] » This function adjusts a CEGUI combobox element to have the correct height.
*[[guiGridListGetSelectedText]] » This function returns a string containing the inner text of a selected gridlist item.
*[[IfElse]] » This function returns one of two values based on a boolean expression.
*[[isElementInPhotograph]] » This function checks if an element is in the player's camera picture area.
*[[isElementInRange]] » This function allows you to check if an element's range to a main point is within the maximum range.
*[[isElementMoving]]» This function checks if an element is moving.
*[[isElementWithinAColShape]]» This function checks if an element is within a collision shape element.
*[[isLeapYear]] » This function returns a boolean representing if a given year is a leap year.
*[[isMouseInPosition]] » This function allows you to check whether the mouse cursor/pointer is within a rectangular position.
*[[isPedAiming]]» This function checks if a pedestrian is aiming their weapon.
*[[isPedDrivingVehicle]] » This function checks if a specified pedestrian is driving a vehicle.
*[[isPlayerInACL]] » This function checks if a player element is in an ACL group.
*[[isPlayerInTeam]] » This function checks if a player is in a specified team.
*[[isSoundFinished]] » This function checks if a sound element has finished.
*[[isVehicleEmpty]] » This function checks whether a vehicle is empty.
*[[isVehicleOccupied]] » This function checks if a specified vehicle is occupied.
*[[isVehicleOnRoof]] » This function checks whether vehicle is on roof.
*[[iterElements]] » This function returns ''a time-saving'' iterator for your for-loops.
*[[mathNumber]] » This function is a workaround for the client-side floating-point precision of 24-bits.
*[[math.percent]] » This function returns a percentage from two number values.
*[[math.round]] » Rounds a number whereas the number of decimals to keep and the method may be set.
*[[multi_check]] » This function checks one element to many, handy and clean.
*[[onVehicleWeaponFire]] » This code implements an event that is triggered when a player in a vehicle fires a vehicle's weapon.
*[[renameAclGroup]] » This function gives an existing ACL group a new name.
*[[RGBToHex]] » This function returns a string representing the color in hexadecimal.
*[[secondsToTimeDesc]] » This function converts a plain seconds-integer into a user-friendly time description.
*[[setAccountName]] » This function is used to change an existing account's name.
*[[setElementSpeed]] » This function allows you to set the speed of an element in kph or mph units.
*[[setTableProtected]] » This function protects a table and makes it read-only.
*[[setVehicleGravityPoint]] » This function sets a vehicle's gravity in the direction of a 3 dimensional coordinate with the strength specified.
*[[smoothMoveCamera]] » This function allows you to create a cinematic camera flight.
*[[string.count]] » This function counts the amount of occurences of a string in a string.
*[[string.explode]] » This function splits a string at a given separator pattern and returns a table with the pieces.
*[[switch]] » This function allows the value of a variable or expression to control the flow of program execution via a multiway branch.
*[[table.copy]] » This function copies a whole table and all the tables in that table.
*[[table.compare]] » This function checks whether two given tables are equal.
*[[table.empty]] » This function checks whether a table is empty.
*[[table.map]] » This function goes through a table and replaces every field with the return of the passed function, where the field's value is passed as first argument and optionally more arguments.
*[[table.merge]] » This function merges two or more tables together.
*[[table.random]] » This function retrieves a random value from a table.
*[[table.size]] » This function returns the absolute size of a table.
*[[toHex]] » This function converts a decimal number to a hexadecimal number, as a fix to be used client-side.
*[[unbindControlKeys]] » This function allows you to unbind each key bound to a control individually. Use this function with [[bindControlKeys]].
*[[var dump]] » This function outputs information about one or more variables using outputConsole.
*[[wavelengthToRGBA]] » This function converts a physical wavelength of light to a RGBA color.
[[Category:Useful Functions]]

IsMouseInPosition

2015-01-03T14:34:41Z

MrTasty: Created page with "{{Useful Function}} {{Needs Example}} <lowercasetitle/> __NOTOC__ This function allows you to check whether the mouse cursor/pointer is within a rectangular position ==Syntax=..."

{{Useful Function}}
{{Needs Example}}
<lowercasetitle/>
__NOTOC__
This function allows you to check whether the mouse cursor/pointer is within a rectangular position
==Syntax==
<syntaxhighlight lang="lua">bool isMouseInPosition ( int x, int y, int width, int height )</syntaxhighlight>

===Required arguments===
* '''x''': Left-most X position for detection (absolute)
* '''y''': Top-most Y position for detection (absolute)
* '''width''': Width for detection (absolute)
* '''heigh''': Height for detection (absolute)

===Return===
Returns true/false depending on whether the mouse was within the specified position or not

==Code==
<syntaxhighlight lang="lua">
if ( not isCursorShowing ( ) ) then
return false
end
local sx, sy = guiGetScreenSize ( )
local cx, cy = getCursorPosition ( )
local cx, cy = ( cx * sx ), ( cy * sy )
if ( cx >= x and cx <= x + width ) and ( cy >= y and cy <= y + height ) then
return true
else
return false
end
end
</syntaxhighlight>
==Example==
Missing

==See Also==
{{Useful_Functions}}

SetTimer

2014-08-23T23:00:02Z

MrTasty:

__NOTOC__
{{Server client function}}
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 50ms.'''

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.create||}}
===Required Arguments===
*'''theFunction:''' The function you wish the timer to call. (Notice: Do not use a 'local' function, it must be global!)
{{New feature/item|3.0141|1.4.1|6773|
Added ''sourceTimer'' global variable to timer's callback function
}}
*'''timeInterval:''' The number of milliseconds that should elapse before the function is called. (the minimum is 50)(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 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" 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" 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>

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

IsElementWaitingForGroundToLoad

2014-08-07T18:45:26Z

MrTasty:

{{Needs_Checking|Example is wrong? --[[User:MrTasty|MrTasty]] ([[User talk:MrTasty|talk]]) 18:45, 7 August 2014 (UTC)}}
{{Server client function}}
__NOTOC__
{{New feature/item|3.0140|1.4.0|6715|This function checks if an [[element]] is frozen (unable to move without scripting) waiting until a [[client]] loads collisions of the area it is in. This allows MTA to automatically freeze vehicles when nobody is near them so they don't fall through the map, for example.}}
{{Note|When vehicles are frozen waiting for collisions to load they '''do not''' overwrite the frozen status set by [[setElementFrozen]].}}

==Syntax==
<syntaxhighlight lang="lua">
bool isElementWaitingForGroundToLoad ( element theElement )
</syntaxhighlight>

===Required arguments===
* '''theElement:''' the element to check its frozen waiting for collisions to load status. It can be a [[vehicle]], [[ped]] or [[player]].

===Returns===
Returns ''true'' if the specified [[element]] is frozen waiting for collisions of the area to load. Returns ''false'' if it's not or if the specified variable is invalid.

==Example==
<section name="Serverside example" class="server" show="true">
The next code snippet outputs a message when a vehicle respawns far away from players.

<syntaxhighlight lang="lua">
function notifyFarRespawn()
outputChatBox("* A " .. getVehicleName(source) .. " respawned far away! Find it quick!", root, 128, 255, 0)
end
addEventHandler("onVehicleRespawn", root, notifyFarRespawn)
</syntaxhighlight>
</section>

==See also==
{{Element functions}}

Matrix

2014-08-06T14:22:43Z

MrTasty:

Vector

2014-08-06T14:22:25Z

MrTasty: Redirected page to Vector3

#REDIRECT [[Vector3]]

Vector3

2014-08-06T14:22:23Z

MrTasty: I might have forgot some - please add the others if that's the case.

TeaDecode

2014-08-04T15:18:41Z

MrTasty:

__NOTOC__
{{Server_client function}}
{{New feature/item|9.06056|1.3.5|6056|
This function decrypts given [https://en.wikipedia.org/wiki/Base64 base64] representation of encrypted data using the [https://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm Tiny Encryption Algorithm].
}}

==Syntax==
<syntaxhighlight lang="lua">string teaDecode ( string data, string key )</syntaxhighlight>

===Required Arguments===
*'''data:''' The block of data you want to decrypt
*'''key:''' The key that should be used for decryption (Only first 16 characters are used)

===Returns===
Returns string containing the decrypted data if the decryption process was successfully completed, ''false'' otherwise.

==Example==
<section name="Example 1" class="client" show="true">
This example creates a /teadecrypt command, which reverts the TEA on a given string with the specified key, if any.
<syntaxhighlight lang="lua">
[lua]
function decrypt(cmd, theString, key)
if theString then
if not key then
key = string.rep(string.char(math.random(string.byte("a"), string.byte("Z"))), 10) -- Generate a random key of 10 characters
end
local decodedString = teaDecode(theString, key) -- Encode the string with the key
outputChatBox("The encoded string is: " .. encodedString .. " (used key: " .. key .. ")")
else
outputChatBox("Syntax: /" .. cmd .. " (string) [key].")
end
end
addCommandHandler("teadecrypt", decrypt)
</syntaxhighlight>
</section>

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

TeaDecode

2014-08-04T15:18:09Z

MrTasty:

__NOTOC__
{{Server_client function}}
{{Needs Example}}
{{New feature/item|9.06056|1.3.5|6056|
This function decrypts given [https://en.wikipedia.org/wiki/Base64 base64] representation of encrypted data using the [https://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm Tiny Encryption Algorithm].
}}

==Syntax==
<syntaxhighlight lang="lua">string teaDecode ( string data, string key )</syntaxhighlight>

===Required Arguments===
*'''data:''' The block of data you want to decrypt
*'''key:''' The key that should be used for decryption (Only first 16 characters are used)

===Returns===
Returns string containing the decrypted data if the decryption process was successfully completed, ''false'' otherwise.

==Example==
<section name="Example 1" class="client" show="true">
This example creates a /teadecrypt command, which reverts the TEA on a given string with the specified key, if any.
<syntaxhighlight lang="lua">
[lua]
function decrypt(cmd, theString, key)
if theString then
if not key then
key = string.rep(string.char(math.random(string.byte("a"), string.byte("Z"))), 10) -- Generate a random key of 10 characters
end
local decodedString = teaDecode(theString, key) -- Encode the string with the key
outputChatBox("The encoded string is: " .. encodedString .. " (used key: " .. key .. ")")
else
outputChatBox("Syntax: /" .. cmd .. " (string) [key].")
end
end
addCommandHandler("teadecrypt", decrypt)
</syntaxhighlight>
</section>

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

TeaEncode

2014-08-04T15:18:05Z

MrTasty:

__NOTOC__
{{Server_client function}}

{{New feature/item|9.06056|1.3.5|6056|
This functions performs the [https://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm Tiny Encryption Algorithm] on the given string and returns the [https://en.wikipedia.org/wiki/Base64 base64] representation of the encrypted block of data.
}}

==Syntax==
<syntaxhighlight lang="lua">string teaEncode ( string data, string key )</syntaxhighlight>

===Required Arguments===
*'''data:''' The block of data you want to encrypt
*'''key:''' The key that should be used for encryption (Only first 16 characters are used)

===Returns===
Returns the [https://en.wikipedia.org/wiki/Base64 base64] representation of the encrypted data if the encryption process was successfully completed, ''false'' otherwise.

==Example==
<section name="Client" class="client" show="true">
This example creates a /teaencrypt command, which performs the TEA on a given string with the specified key, if any.
<syntaxhighlight lang="lua">
[lua]
function encrypt(cmd, theString, key)
if theString then
if not key then
key = string.rep(string.char(math.random(string.byte("a"), string.byte("Z"))), 10) -- Generate a random key of 10 characters
end
local encodedString = teaEncode(theString, key) -- Encode the string with the key
outputChatBox("The encoded string is: " .. encodedString .. " (used key: " .. key .. ")")
else
outputChatBox("Syntax: /" .. cmd .. " (string) [key].")
end
end
addCommandHandler("teaencrypt", encrypt)
</syntaxhighlight>
</section>

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

TeaEncode

2014-08-04T15:16:59Z

MrTasty:

__NOTOC__
{{Server_client function}}

{{New feature/item|9.06056|1.3.5|6056|
This functions performs the [https://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm Tiny Encryption Algorithm] on the given string and returns the [https://en.wikipedia.org/wiki/Base64 base64] representation of the encrypted block of data.
}}

==Syntax==
<syntaxhighlight lang="lua">string teaEncode ( string data, string key )</syntaxhighlight>

===Required Arguments===
*'''data:''' The block of data you want to encrypt
*'''key:''' The key that should be used for encryption (Only first 16 characters are used)

===Returns===
Returns the [https://en.wikipedia.org/wiki/Base64 base64] representation of the encrypted data if the encryption process was successfully completed, ''false'' otherwise.

==Example==
<section name="Client" class="client" show="true">
This example creates a /teaencrypt command, which performs the TEA on a given string with the specified key, if any.
<syntaxhighlight lang="lua">
[lua]
function encrypt(cmd, theString, key)
if theString then
if not key then
key = string.rep(string.char(math.random(string.byte("a"), string.byte("Z"))), 10) -- Generate a random key of 10 characters
end
local encodedString = teaEncode(theString, key) -- Encode the string with the key
outputChatBox("The encoded string is: " .. encodedString .. " (used key: " .. key .. ")")
else
outputChatBox("Syntax: /" .. cmd .. " (string) [key].")
end
end
addCommandHandler("teaencrypt", encrypt)
[/lua]
</syntaxhighlight>
</section>

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

TeaDecode

2014-08-04T15:16:58Z

MrTasty:

__NOTOC__
{{Server_client function}}
{{Needs Example}}
{{New feature/item|9.06056|1.3.5|6056|
This function decrypts given [https://en.wikipedia.org/wiki/Base64 base64] representation of encrypted data using the [https://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm Tiny Encryption Algorithm].
}}

==Syntax==
<syntaxhighlight lang="lua">string teaDecode ( string data, string key )</syntaxhighlight>

===Required Arguments===
*'''data:''' The block of data you want to decrypt
*'''key:''' The key that should be used for decryption (Only first 16 characters are used)

===Returns===
Returns string containing the decrypted data if the decryption process was successfully completed, ''false'' otherwise.

==Example==
<section name="Example 1" class="client" show="true">
This example creates a /teadecrypt command, which reverts the TEA on a given string with the specified key, if any.
<syntaxhighlight lang="lua">
[lua]
function decrypt(cmd, theString, key)
if theString then
if not key then
key = string.rep(string.char(math.random(string.byte("a"), string.byte("Z"))), 10) -- Generate a random key of 10 characters
end
local decodedString = teaDecode(theString, key) -- Encode the string with the key
outputChatBox("The encoded string is: " .. encodedString .. " (used key: " .. key .. ")")
else
outputChatBox("Syntax: /" .. cmd .. " (string) [key].")
end
end
addCommandHandler("teadecrypt", decrypt)
[/lua]
</syntaxhighlight>
</section>

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

GetBoundControls

2014-08-04T15:00:05Z

MrTasty: /* Example 2 */

{{Useful Function}}
<lowercasetitle></lowercasetitle>
__NOTOC__
Returns a list of control names that are bound to the specified key.

==Syntax==
<syntaxhighlight lang="lua">
table getBoundControls ( string key )
</syntaxhighlight>

===Required Arguments===
*'''key:''' The name of the key. See [[Key names]].

===Returns===
If one or more controls are bound to the specified key, a table is returned containing the names of all the bound controls. If no controls are bound or an invalid name was passed, returns empty ''table''.

==Code==
<section name="Clientside script" class="client" show="true">
<syntaxhighlight lang="lua">
local controlTable = { "fire", "next_weapon", "previous_weapon", "forwards", "backwards", "left", "right", "zoom_in", "zoom_out",
"change_camera", "jump", "sprint", "look_behind", "crouch", "action", "walk", "aim_weapon", "conversation_yes", "conversation_no",
"group_control_forwards", "group_control_back", "enter_exit", "vehicle_fire", "vehicle_secondary_fire", "vehicle_left", "vehicle_right",
"steer_forward", "steer_back", "accelerate", "brake_reverse", "radio_next", "radio_previous", "radio_user_track_skip", "horn", "sub_mission",
"handbrake", "vehicle_look_left", "vehicle_look_right", "vehicle_look_behind", "vehicle_mouse_look", "special_control_left", "special_control_right",
"special_control_down", "special_control_up" }

function getBoundControls (key)
local controls = {}
for _,control in ipairs(controlTable) do
for k in pairs(getBoundKeys(control)) do
if (k == key) then
controls[control] = true
end
end
end
return controls
end
</syntaxhighlight>
Author: Lex128
</section>

==Example 1==
This code adds a special action when activated detonator and blocks its actual use in the game.
<syntaxhighlight lang="lua">
function detonatorAction (key, state)
if (getPedWeapon (localPlayer) ~= 40) then return end -- make sure that the detonator is in the hands of

outputChatBox ("Whohooo... BOOM!", 255, 0, 0) -- make necessary actions
for control in pairs (getBoundControls(key)) do
setControlState (control, false)
end
end

bindKey ("mouse1", "down", detonatorAction)
</syntaxhighlight>
==Example 2==
This code checks if someone has 'sprint' bound onto the mouse wheel (a well-known glitch which is now disabled by default) and kicks a player for having it bound
<section name="Clientside" class="client" show="true">
<syntaxhighlight lang="lua">
function onStart()
if ( (getBoundControls("mouse_wheel_up")["sprint"]) or (getBoundControls("mouse_wheel_down")["sprint"]) ) then
triggerServerEvent("kickPlayerForCheating", root, "supersprint binds")
end
end
addEventHandler("onClientResourceStart", resourceRoot, onStart)
</syntaxhighlight>
</section>
<section name="Serverside" class="server" show="true">
<syntaxhighlight lang="lua">
addEvent("kickPlayerForCheating", true)
addEventHandler("kickPlayerForCheating", root, function(cheat)
kickPlayer(client, "Anti Cheat", "Cheat detected: "..cheat)
end)
</syntaxhighlight>
</section>

==See Also==
{{Useful_Functions}}

GetBoundControls

2014-08-04T14:59:17Z

MrTasty:

{{Useful Function}}
<lowercasetitle></lowercasetitle>
__NOTOC__
Returns a list of control names that are bound to the specified key.

==Syntax==
<syntaxhighlight lang="lua">
table getBoundControls ( string key )
</syntaxhighlight>

===Required Arguments===
*'''key:''' The name of the key. See [[Key names]].

===Returns===
If one or more controls are bound to the specified key, a table is returned containing the names of all the bound controls. If no controls are bound or an invalid name was passed, returns empty ''table''.

==Code==
<section name="Clientside script" class="client" show="true">
<syntaxhighlight lang="lua">
local controlTable = { "fire", "next_weapon", "previous_weapon", "forwards", "backwards", "left", "right", "zoom_in", "zoom_out",
"change_camera", "jump", "sprint", "look_behind", "crouch", "action", "walk", "aim_weapon", "conversation_yes", "conversation_no",
"group_control_forwards", "group_control_back", "enter_exit", "vehicle_fire", "vehicle_secondary_fire", "vehicle_left", "vehicle_right",
"steer_forward", "steer_back", "accelerate", "brake_reverse", "radio_next", "radio_previous", "radio_user_track_skip", "horn", "sub_mission",
"handbrake", "vehicle_look_left", "vehicle_look_right", "vehicle_look_behind", "vehicle_mouse_look", "special_control_left", "special_control_right",
"special_control_down", "special_control_up" }

function getBoundControls (key)
local controls = {}
for _,control in ipairs(controlTable) do
for k in pairs(getBoundKeys(control)) do
if (k == key) then
controls[control] = true
end
end
end
return controls
end
</syntaxhighlight>
Author: Lex128
</section>

==Example 1==
This code adds a special action when activated detonator and blocks its actual use in the game.
<syntaxhighlight lang="lua">
function detonatorAction (key, state)
if (getPedWeapon (localPlayer) ~= 40) then return end -- make sure that the detonator is in the hands of

outputChatBox ("Whohooo... BOOM!", 255, 0, 0) -- make necessary actions
for control in pairs (getBoundControls(key)) do
setControlState (control, false)
end
end

bindKey ("mouse1", "down", detonatorAction)
</syntaxhighlight>
==Example 2==
This code checks if someone has 'sprint' bound onto the mouse wheel (a well-known glitch which is now disabled by default) and kicks a player for having it bound
<section name="Clientside" class="client" show="true">
<syntaxhighlight lang="lua">
function onStart()
if getBoundControls("mouse_wheel_up") or getBoundControls("mouse_wheel_down") then
triggerServerEvent("kickPlayerForCheating", root, "supersprint binds")
end
end
addEventHandler("onClientResourceStart", resourceRoot, onStart)
</syntaxhighlight>
</section>
<section name="Serverside" class="server" show="true">
<syntaxhighlight lang="lua">
addEvent("kickPlayerForCheating", true)
addEventHandler("kickPlayerForCheating", root, function(cheat)
kickPlayer(client, "Anti Cheat", "Cheat detected: "..cheat)
end)
</syntaxhighlight>
</section>

==See Also==
{{Useful_Functions}}

IsKeyBound

2014-08-04T14:48:08Z

MrTasty:

{{Server function}}
__NOTOC__
This function can be used to find out if a key has already been bound.

==Syntax==
<syntaxhighlight lang="lua">bool isKeyBound ( player thePlayer, string key, [ string keyState, function handler ] ) </syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The player you're checking.
*'''key:''' The key you're checking. See [[Key names]] for a list of valid key names.

===Optional Arguments===
*'''keyState:''' Is the state of the key when it calls the function, Can be either:
**'''"up":''' when the key is released
**'''"down":''' when the key is pressed
*'''handler:''' The function you're checking against
Note: If you do not specify a ''keyState'' or ''handler'', any instances of ''key'' being bound will cause ''isKeyBound'' to return ''true''.

==Example==
<syntaxhighlight lang="lua">
-- This function tells everyone in the server if someone has numpad 9 bound!
function onPlayerJoin ()
if (isKeyBound (source,"num_9")) then -- if num pad 9 is bound
outputChatBox (getPlayerName (source) .. " has bound numpad 9!",getRootElement(),255,0,0,false) -- let see everybody that he has binded it
end
end
addEventHandler ("onPlayerJoin",getRootElement(),onPlayerJoin) -- add event.
</syntaxhighlight>

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

GetChatboxLayout

2014-07-22T21:54:15Z

MrTasty: Fixed a typo

__NOTOC__
{{Client function}}
Returns information about how the chatbox looks.

These values come from the file called: [[Chatboxpresents.xml]] but it depends on what type of preset you currently have, which is chosen from your settings in the 'Interface' tab.

==Syntax==
<syntaxhighlight lang="lua">bool/int/table getChatboxLayout ( [ string CVar ] )</syntaxhighlight>

===Optional Arguments===
*'''CVar:''' the name of the property you want returned. Can be the following values:
**'''chat_font''' - Returns the chatbox font
**'''chat_lines''' - Returns how many lines the chatbox has
**'''chat_color''' - Returns the background color of the chatbox
**'''chat_text_color''' - Returns the chatbox text color
**'''chat_input_color''' - Returns the background color of the chatbox input
**'''chat_input_prefix_color''' - Returns the color of the input prefix text
**'''chat_input_text_color''' - Returns the color of the text in the chatbox input
**'''chat_scale''' - Returns the scale of the text in the chatbox
**'''chat_width''' - Returns the scale of the background width
**'''chat_css_style_text''' - Returns whether text fades out over time
**'''chat_css_style_background''' - Returns whether the background fades out over time
**'''chat_line_life''' - Returns how long it takes for text to start fading out
**'''chat_line_fade_out''' - Returns how long takes for text to fade out
**'''chat_use_cegui''' - Returns whether CEGUI is used to render the chatbox
**'''text_scale''' - Returns text scale

===Returns===
*4 numbers if the CVar contains "color"
*2 numbers if '''chat_scale''' was entered
*1 number if any other CVar was specified
*a table of all CVar values, if CVar was not specified
*''false'' if an invalid CVar was specified

==Example==
This code makes the chatbox empty when you type /clear
<syntaxhighlight lang="lua">
addCommandHandler("clear",
function ()
local lines = getChatboxLayout()["chat_lines"]
for i=1,lines do
outputChatBox("")
end
end
)
</syntaxhighlight>

==See Also==
{{GUI_functions}}

Vehicle IDs

2014-07-21T16:05:18Z

MrTasty: /* Trains and Railroad Cars */

==Introduction==
This is a list of GTA:SA's vehicle ID numbers, as listed in the vehicles.ide file. These vehicle ID numbers are used for several vehicle scripting functions.

Lua table of all the valid vehicle IDs listed on this page:
<syntaxhighlight lang="lua">vehicleIDS = { 602, 545, 496, 517, 401, 410, 518, 600, 527, 436, 589, 580, 419, 439, 533, 549, 526, 491, 474, 445, 467, 604, 426, 507, 547, 585,
405, 587, 409, 466, 550, 492, 566, 546, 540, 551, 421, 516, 529, 592, 553, 577, 488, 511, 497, 548, 563, 512, 476, 593, 447, 425, 519, 520, 460,
417, 469, 487, 513, 581, 510, 509, 522, 481, 461, 462, 448, 521, 468, 463, 586, 472, 473, 493, 595, 484, 430, 453, 452, 446, 454, 485, 552, 431,
438, 437, 574, 420, 525, 408, 416, 596, 433, 597, 427, 599, 490, 432, 528, 601, 407, 428, 544, 523, 470, 598, 499, 588, 609, 403, 498, 514, 524,
423, 532, 414, 578, 443, 486, 515, 406, 531, 573, 456, 455, 459, 543, 422, 583, 482, 478, 605, 554, 530, 418, 572, 582, 413, 440, 536, 575, 534,
567, 535, 576, 412, 402, 542, 603, 475, 449, 537, 538, 441, 464, 501, 465, 564, 568, 557, 424, 471, 504, 495, 457, 539, 483, 508, 571, 500,
444, 556, 429, 411, 541, 559, 415, 561, 480, 560, 562, 506, 565, 451, 434, 558, 494, 555, 502, 477, 503, 579, 400, 404, 489, 505, 479, 442, 458,
606, 607, 610, 590, 569, 611, 584, 608, 435, 450, 591, 594 }</syntaxhighlight>

Lua table of vehicles that are not lockable:
<syntaxhighlight lang="lua">notLockableVehicles = {594, 606, 607, 611, 584, 608, 435, 450, 591, 539, 441, 464, 501, 465, 564, 472, 473, 493, 595, 484, 430,
453, 452, 446, 454, 581, 509, 481, 462, 521, 463, 510, 522, 461, 448, 468, 586, 425, 520}</syntaxhighlight>
Lua table of vehicles without number plates:
<syntaxhighlight lang="lua">noNumberPlates = { 592, 553, 577, 488, 511, 497, 548, 563, 512, 476, 593, 447, 425, 519, 520, 460, 417, 469, 487, 513, 509, 481,
510, 472, 473, 493, 595, 484, 430, 453, 452, 446, 454 }</syntaxhighlight>

==2-Door and Compact cars==
<table border="1" class="unnamed1">
<tr><th>Name</th><th>ID</th><td></td><th>Name</th><th>ID</th></tr><tr><td>Alpha</td><td>602</td><td></td><td>Hustler</td><td>545</td></tr><tr><td>Blista Compact</td><td>496</td><td> </td><td>Majestic</td><td>517</td></tr><tr><td>Bravura</td><td>401</td><td> </td><td>Manana</td><td>410</td></tr><tr><td>Buccaneer</td><td>518</td><td> </td><td>Picador</td><td>600</td></tr><tr><td>Cadrona</td><td>527</td><td> </td><td>Previon</td><td>436</td></tr><tr><td>Club</td><td>589</td><td> </td><td>Stafford</td><td>580</td></tr><tr><td>Esperanto</td><td>419</td><td> </td><td>Stallion</td><td>439</td></tr><tr><td>Feltzer</td><td>533</td><td> </td><td>Tampa</td><td>549</td></tr><tr><td>Fortune</td><td>526</td><td> </td><td>Virgo</td><td>491</td></tr><tr><td>Hermes</td><td>474</td><td> </td><td> </td><td> </td></tr></table>

== 4-Door and Luxury cars==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th><td> </td><th>Name</th><th>ID</th></tr><tr><td>Admiral</td><td>445</td><td> </td><td>Oceanic</td><td>467</td></tr><tr><td>Damaged Glendale</td><td>604</td><td> </td><td>Premier</td><td>426</td></tr><tr><td>Elegant</td><td>507</td><td> </td><td>Primo</td><td>547</td></tr><tr><td>Emperor</td><td>585</td><td> </td><td>Sentinel</td><td>405</td></tr><tr><td>Euros</td><td>587</td><td> </td><td>Stretch</td><td>409</td></tr><tr><td>Glendale</td><td>466</td><td> </td><td>Sunrise</td><td>550</td></tr><tr><td>Greenwood</td><td>492</td><td> </td><td>Tahoma</td><td>566</td></tr><tr><td>Intruder</td><td>546</td><td> </td><td>Vincent</td><td>540</td></tr><tr><td>Merit</td><td>551</td><td> </td><td>Washington</td><td>421</td></tr><tr><td>Nebula</td><td>516</td><td> </td><td>Willard</td><td>529</td></tr></table>

==Aircraft==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th><td> </td><th>
Name</th><th>ID</th></tr><tr><td>Andromada</td><td>592</td><td> </td><td>
Nevada</td><td>553</td></tr><tr><td>AT-400</td><td>577</td><td> </td><td>

News Chopper</td><td>488</td></tr><tr><td>Beagle</td><td>511</td><td> </td><td>
Police Maverick</td><td>497</td></tr><tr><td>Cargobob</td><td>548</td><td> </td><td>
Raindance</td><td>563</td></tr><tr><td>Cropduster</td><td>512</td><td> </td><td>

Rustler</td><td>476</td></tr><tr><td>Dodo</td><td>593</td><td> </td><td>
Seasparrow</td><td>447</td></tr><tr><td>Hunter</td><td>425</td><td> </td><td>
Shamal</td><td>519</td></tr><tr><td>Hydra</td><td>520</td><td> </td><td>

Skimmer</td><td>460</td></tr><tr><td>Leviathan</td><td>417</td><td> </td><td>
Sparrow</td><td>469</td></tr><tr><td>Maverick</td><td>487</td><td> </td><td>
Stuntplane</td><td>513</td></tr></table>

==Bikes==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th><td> </td><th>Name</th><th>ID</th></tr><tr><td>BF-400</td><td>581</td><td> </td><td>Mountain Bike</td><td>510</td></tr><tr><td>Bike</td><td>509</td><td> </td><td>NRG-500</td><td>522</td> </tr><tr><td>BMX</td><td>481</td><td> </td><td>PCJ-600</td><td>461</td></tr><tr><td>Faggio</td><td>462</td><td> </td><td>Pizza Boy</td><td>448</td></tr><tr><td>FCR-900</td><td>521</td><td> </td><td>Sanchez</td><td> 468</td></tr><tr><td>Freeway</td><td>463</td><td> </td><td>Wayfarer</td><td>586</td></tr></table>

==Boats==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th></tr><tr><td>Coastguard</td><td>472</td></tr><tr><td>Dinghy</td><td>473</td></tr><tr><td>Jetmax</td><td>493</td></tr><tr><td>Launch</td><td>595</td></tr><tr><td>Marquis</td><td>484</td></tr><tr><td>Predator</td><td>430</td></tr><tr><td>Reefer</td><td>453</td></tr><tr><td>Speeder</td><td>452</td></tr><tr><td>Squalo</td><td>446</td></tr><tr><td>Tropic</td><td>454</td></tr></table>

==Civil Servant / Public Transportation (Road Vehicles)==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th></tr>
<tr><td>Baggage</td><td>485</td></tr>
<tr><td>Utility Van</td><td>552</td></tr>
<tr><td>Bus</td><td>431</td></tr>
<tr><td>Cabbie</td><td>438</td></tr>
<tr><td>Coach</td><td>437</td></tr>
<tr><td>Sweeper</td><td>574</td></tr>
<tr><td>Taxi</td><td>420</td></tr>
<tr><td>Towtruck</td><td>525</td></tr>
<tr><td>Trashmaster</td><td>408</td></tr></table>

==Government Vehicles==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th><td> </td><th>Name</th><th>ID</th></tr><tr><td>Ambulance</td><td>416</td><td> </td><td>Police Car (Los Santos)</td><td>596</td></tr><tr><td>Barracks</td><td>433</td><td> </td><td>Police Car (San Fierro)</td><td>597</td></tr><tr><td>Enforcer</td><td>427</td><td> </td><td>Police Ranger</td><td>599</td></tr><tr><td>FBI Rancher</td><td>490</td><td> </td><td>Rhino</td><td>432</td></tr><tr><td>FBI Truck</td><td>528</td><td> </td><td>S.W.A.T.</td><td>601</td></tr><tr><td>Fire Truck</td><td>407</td><td> </td><td>Securicar</td><td>428</td></tr><tr><td>Fire Truck (Ladder)</td><td>544</td><td> </td><td> </td><td> </td></tr><tr><td>HPV1000</td><td>523</td><td> </td><td> </td><td> </td></tr><tr><td>Patriot</td><td>470</td><td> </td><td> </td><td> </td></tr><tr><td>Police Car (Las Venturas)</td><td>598</td><td> </td><td> </td><td> </td></tr></table>

==Heavy and Utility Trucks==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th><td> </td><th>Name</th><th>ID</th></tr><tr><td>Benson</td><td>499</td><td> </td><td>Hotdog</td><td>588</td></tr><tr><td>Black Boxville</td><td>609</td><td> </td><td>Linerunner</td><td>403</td></tr><tr><td>Boxville</td><td>498</td><td> </td><td>Linerunner (From "Tanker Commando")</td><td>514</td></tr><tr><td>Cement Truck</td><td>524</td><td> </td><td>Mr. Whoopee</td><td>423</td></tr><tr><td>Combine Harvester</td><td>532</td><td> </td><td>Mule</td><td>414</td></tr><tr><td>DFT-30</td><td>578</td><td> </td><td>Packer</td><td>443</td></tr><tr><td>Dozer</td><td>486</td><td> </td><td>Roadtrain</td><td>515</td></tr><tr><td>Dumper</td><td>406</td><td> </td><td>Tractor</td><td>531</td></tr><tr><td>Dune</td><td>573</td><td> </td><td>Yankee</td><td>456</td></tr><tr><td>Flatbed</td><td>455</td><td> </td><td> </td><td> </td></tr></table>

==Light Trucks and Vans==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th><td> </td><th>Name</th><th>ID</th></tr><tr><td>Berkley's RC Van</td><td>459</td><td> </td><td>Sadler</td><td>543</td></tr><tr><td>Bobcat</td><td>422</td><td> </td><td>Tug</td><td>583</td></tr><tr><td>Burrito</td><td>482</td><td> </td><td>Walton</td><td>478</td></tr><tr><td>Damaged Sadler</td><td>605</td><td> </td><td>Yosemite</td><td>554</td></tr><tr><td>Forklift</td><td>530</td><td> </td><td> </td><td> </td></tr><tr><td>Moonbeam</td><td>418</td><td> </td><td> </td><td> </td></tr><tr><td>Mower</td><td>572</td><td> </td><td> </td><td> </td></tr><tr><td>News Van</td><td>582</td><td> </td><td> </td><td> </td></tr><tr><td>Pony</td><td>413</td><td> </td><td> </td><td> </td></tr><tr><td>Rumpo</td><td>440</td><td> </td><td> </td><td> </td></tr></table>

==Lowriders==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th></tr><tr><td>Blade</td><td>536</td></tr><tr><td>Broadway</td><td>575</td></tr><tr><td>Remington</td><td>534</td></tr><tr><td>Savanna</td><td>567</td></tr><tr><td>Slamvan</td><td>535</td></tr><tr><td>Tornado</td><td>576</td></tr><tr><td>Voodoo</td><td>412</td></tr></table>

==Muscle Cars==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th></tr><tr><td>Buffalo</td><td>402</td></tr><tr><td>Clover</td><td>542</td></tr><tr><td>Phoenix</td><td>603</td></tr><tr><td>Sabre</td><td>475</td></tr></table>

==Trains and Railroad Cars==

<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th><th>Notes</th></tr>
<tr><td>Tram</td><td>449</td><td></td></tr>
<tr><td>Freight</td><td>537</td><td></td></tr>
<tr><td>Brown Streak</td><td>538</td><td></td></tr>
<tr><td>Brown Streak Carriage</td><td>570</td><td>Removed in version [https://code.google.com/p/mtasa-blue/source/detail?r=2880 1.1-r2880], but available from [https://code.google.com/p/mtasa-blue/source/detail?r=5934 1.4-r5934] and forth.</tr>
<tr><td>Flat Freight</td><td>569</td><td></td></tr>
<tr><td>Box Freight</td><td>590</td><td></td></tr></table>

==RC Vehicles==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th></tr><tr><td>RC Bandit</td><td>441</td></tr><tr><td>RC Baron</td><td>464</td></tr><tr><td>RC Goblin</td><td>501</td></tr><tr><td>RC Raider</td><td>465</td></tr><tr><td>RC Tiger</td><td>564</td></tr></table>

==Recreational==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th><td> </td><th>Name</th><th>ID</th></tr><tr><td>Bandito</td><td>568</td><td> </td><td>Monster 3</td><td>557</td></tr><tr><td>BF Injection</td><td>424</td><td> </td><td>Quadbike</td><td>471</td></tr><tr><td>Bloodring Banger</td><td>504</td><td> </td><td>Sandking</td><td>495</td></tr><tr><td>Caddy</td><td>457</td><td> </td><td>Vortex</td><td>539</td></tr><tr><td>Camper</td><td>483</td><td> </td><td> </td><td> </td></tr><tr><td>Journey</td><td>508</td><td> </td><td> </td><td> </td></tr><tr><td>Kart</td><td>571</td><td> </td><td> </td><td> </td></tr><tr><td>Mesa</td><td>500</td><td> </td><td> </td><td> </td></tr><tr><td>Monster</td><td>444</td><td> </td><td> </td><td> </td></tr><tr><td>Monster 2</td><td>556</td><td> </td><td> </td><td> </td></tr></table>

==Street Racers==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th><td> </td><th>Name</th><th>ID</th></tr><tr><td>Banshee</td><td>429</td><td> </td><td>Infernus</td><td>411</td></tr><tr><td>Bullet</td><td>541</td><td> </td><td>Jester</td><td>559</td></tr><tr><td>Cheetah</td><td>415</td><td> </td><td>Stratum</td><td>561</td></tr><tr><td>Comet</td><td>480</td><td> </td><td>Sultan</td><td>560</td></tr><tr><td>Elegy</td><td>562</td><td> </td><td>Super GT</td><td>506</td></tr><tr><td>Flash</td><td>565</td><td> </td><td>Turismo</td><td>451</td></tr><tr><td>Hotknife</td><td>434</td><td> </td><td>Uranus</td><td>558</td></tr><tr><td>Hotring Racer</td><td>494</td><td> </td><td>Windsor</td><td>555</td></tr><tr><td>Hotring Racer 2</td><td>502</td><td> </td><td>ZR-350</td><td>477</td></tr><tr><td>Hotring Racer 3</td><td>503</td><td> </td><td> </td><td> </td></tr></table>

==SUVs and Wagons==
<table border="1" class="unnamed1"><tr><th>Name</th><th>ID</th></tr><tr><td>Huntley</td><td>579</td></tr><tr><td>Landstalker</td><td>400</td></tr><tr><td>Perennial</td><td>404</td></tr><tr><td>Rancher</td><td>489</td></tr><tr><td>Rancher (From "Lure")</td><td>505</td></tr><tr><td>Regina</td><td>479</td></tr><tr><td>Romero</td><td>442</td></tr><tr><td>Solair</td><td>458</td></tr></table>

==Trailers==
<table border="1" class="unnamed1"><tr><th width="218">Name</th><th width="24">ID</th></tr><tr><td>Baggage Trailer (covered)</td><td>606</td></tr><tr><td>Baggage Trailer (Uncovered)</td><td>607</td></tr><tr><td>Farm Trailer</td><td>610</td></tr><tr></tr><tr></tr><tr><td>"Street Clean" Trailer</td><td>611</td></tr><tr><td>Trailer (From "Tanker Commando")(*PRONE TO CRASHES*)</td><td>584</td></tr><tr><td>Trailer (Stairs)</td><td>608</td></tr><tr><td>Trailer 1</td><td>435</td></tr><tr><td>Trailer 2</td><td>450</td></tr><tr><td>Trailer 3</td><td>591</td></tr></table>

==Misc==
<table border="1" class="unnamed1"><tr><th width="218">Name</th><th width="24">ID</th></tr><tr><td>RC Cam (flower pot)</td><td>594</td></table>
 

==Vehicle Functions==
{{Vehicle functions}}

==See Also==
[[id|ID Lists]]
[[it:ID Veicoli]]
[[ru:Vehicle IDs]]
[[de:Fahrzeug IDs]]

[[Category:ID Lists]]

OnClientVehicleDamage

2014-06-14T20:53:47Z

MrTasty: /* Parameters */

__NOTOC__
{{Client event}}
{{New items|4.0140|1.3.5|
This event is triggered when a vehicle is damaged.
}}

==Parameters==
<syntaxhighlight lang="lua">
element theAttacker, int theWeapon, float loss, float damagePosX, float damagePosY, float damagePosZ, int tyreID
</syntaxhighlight>

*'''theAttacker''': An element if there was an attacker.
*'''theWeapon''': An integer specifying the weapon ID if a weapon was used.
*'''loss''': A float representing the amount of damage taken.
*'''damagePosX''': A float representing the X co-ordinate of where the damage took place.
*'''damagePosY''': A float representing the Y co-ordinate of where the damage took place.
*'''damagePosZ''': A float representing the Z co-ordinate of where the damage took place.
*'''tyreID''': A number representing the tyre which took damage, if there is one.

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

==Cancel effect==
If this event is [[Event system#Canceling|canceled]], the vehicle will not be damaged.

==Example==
This example makes every SWAT tank immune from all weapon attacks.
<syntaxhighlight lang="lua">
function handleVehicleDamage(attacker, weapon, loss, x, y, z, tyre)
if (weapon and getElementModel(source) == 601) then
-- A weapon was used and the vehicle model ID is that of the SWAT tank so cancel the damage.
cancelEvent()
end
end
addEventHandler("onClientVehicleDamage", root, handleVehicleDamage)
</syntaxhighlight>

This example allows the Rhino to take damage from bullets even though they're bullet proof, this example doesn't work with explosions though.
<syntaxhighlight lang="lua">
-- Only let these weapons damage a Rhino
local weaponsToDamageRhino = {
[38] = true, -- minigun
[33] = true, -- country rifle
[34] = true, -- sniper rifle
[30] = true, -- AK-47
[31] = true, -- M4
}

function handleRhinoDamage(attacker, weapon, loss, x, y, z, tyre)
if (weapon and getElementModel(source) == 432 and loss > 0) then
if (weaponsToDamageRhino[weapon]) then
setElementHealth(source, getElementHealth(source) - loss)
end
end
end
addEventHandler("onClientVehicleDamage", root, handleRhinoDamage)
</syntaxhighlight>

This example will prevent your vehicle from taking damage by being lit on fire.
<syntaxhighlight lang="lua">
function preventFireDamage_Handler(theAttacker, theWeapon)
if(theWeapon == 37) then
cancelEvent()
end
end
addEventHandler("onClientVehicleDamage", getRootElement(), preventFireDamage_Handler)
</syntaxhighlight>

==See Also==
===Client vehicle events===
{{Client_vehicle_events}}
===Client event functions===
{{Client_event_functions}}

DxDrawText

2014-02-12T23:29:15Z

MrTasty: Added rotation parameters

__NOTOC__
{{Client function}}

Draws a string of text on the screen for one frame. In order for the text to stay visible continuously, you need to call this function with the same parameters on each frame update (see [[onClientRender]]).

==Syntax==
<syntaxhighlight lang="lua">
bool dxDrawText ( string text, float left, float top [, float right=left, float bottom=top, int color=white,
float scale=1, mixed font="default", string alignX="left", string alignY="top",
bool clip=false, bool wordBreak=false, bool postGUI=false,
bool colorCoded=false, bool subPixelPositioning=false,
float fRotation=0, float fRotationCenterX=0, float fRotationCenterY=0 ] )
</syntaxhighlight>

===Required Arguments===
*'''text:''' the text to draw
*'''left:''' the absolute X coordinate of the top left corner of the text
*'''top:''' the absolute Y coordinate of the top left corner of the text

===Optional Arguments===
*'''right:''' the absolute X coordinate of the right side of the text bounding box. Used for text aligning, clipping and word breaking.
*'''bottom:''' the absolute Y coordinate of the bottom side of the text bounding box. Used for text aligning, clipping and word breaking.
*'''color:''' the color of the text, a value produced by [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
*'''scale:''' the size of the text.{{New feature|3.0110|1.1|'''scale:''' can (optionally) be specified as two floats. i.e. '''scaleX, scaleY'''}}
*'''font:''' Either a custom [[DX font]] element or the name of a built-in DX font:
{{DxFonts}}
*'''alignX:''' horizontal alignment of the text within the bounding box. Can be '''"left"''', '''"center"''' or '''"right"'''.
*'''alignY:''' vertical alignment of the text within the bounding box. Can be '''"top"''', '''"center"''' or '''"bottom"'''.
*'''clip:''' if set to ''true'', the parts of the text that don't fit within the bounding box will be cut off.
*'''wordBreak:''' if set to ''true'', the text will wrap to a new line whenever it reaches the right side of the bounding box. If ''false'', the text will always be completely on one line.
* '''postGUI:''' A bool representing whether the text should be drawn on top of or behind any ingame GUI (rendered by CEGUI).
{{New feature/item|3.0135|1.3.0|0|
'''Note: These parameters only work from version 1.3.0-9.03986 onwards:'''
*'''colorCoded:''' Set to true to enable embedded #FFFFFF color codes. '''Note: clip and wordBreak are forced false if this is set.'''
*'''subPixelPositioning:''' A bool representing whether the text can be positioned sub-pixel-ly. Looks nicer for moving/scaling animations.
}}
{{New feature/item|3.0135|1.3.5|0|
*'''fRotation:''' Rotation'''
*'''fRotationCenterX:''' Rotation Origin X'''
*'''fRotationCenterY:''' Rotation Origin Y'''
}}

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

==Example==
This example code will add the current zone name in the lower left corner of the players' screens.
<syntaxhighlight lang="lua">
local screenWidth, screenHeight = guiGetScreenSize ( ) -- Get the screen resolution (width and height)

function createText ( )
local playerX, playerY, playerZ = getElementPosition ( localPlayer ) -- Get our player's coordinates.
local playerZoneName = getZoneName ( playerX, playerY, playerZ ) -- Get name of the zone the player is in.

-- Draw zone name text's shadow.
dxDrawText ( playerZoneName, 44, screenHeight - 41, screenWidth, screenHeight, tocolor ( 0, 0, 0, 255 ), 1.02, "pricedown" )
-- Draw zone name text.
dxDrawText ( playerZoneName, 44, screenHeight - 43, screenWidth, screenHeight, tocolor ( 255, 255, 255, 255 ), 1, "pricedown" )
end

function HandleTheRendering ( )
addEventHandler ( "onClientRender", root, createText ) -- keep the text visible with onClientRender.
end

addEventHandler ( "onClientResourceStart", resourceRoot, HandleTheRendering )
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.03986|Added colorCoded and subPixelPositioning arguments}}
{{ChangelogItem|1.3.5|Added fRotation, fRotationCenterX and fRotationCenterY arguments}}

==See Also==
{{Drawing_functions}}

GetChatboxLayout

2014-01-22T20:33:08Z

MrTasty: /* Syntax */

__NOTOC__
{{Client function}}
Returns information about how the chatbox looks.

These values comes from the file called: [[Chatboxpresents.xml]] but it depends on what type of preset you currently have, which is chosen from your settings in the 'Interface' tab.

==Syntax==
<syntaxhighlight lang="lua">bool/int/table getChatboxLayout ( [ string CVar ] )</syntaxhighlight>

===Optional Arguments===
*'''CVar:''' the name of the property you want returned. Can be the following values:
**'''chat_font''' - Returns the chatbox font
**'''chat_lines''' - Returns how many lines the chatbox has
**'''chat_color''' - Returns the background color of the chatbox
**'''chat_text_color''' - Returns the chatbox text color
**'''chat_input_color''' - Returns the background color of the chatbox input
**'''chat_input_prefix_color''' - Returns the color of the input prefix text
**'''chat_input_text_color''' - Returns the color of the text in the chatbox input
**'''chat_scale''' - Returns the scale of the text in the chatbox
**'''chat_width''' - Returns the scale of the background width
**'''chat_css_style_text''' - Returns whether text fades out over time
**'''chat_css_style_background''' - Returns whether the background fades out over time
**'''chat_line_life''' - Returns how long it takes for text to start fading out
**'''chat_line_fade_out''' - Returns how long takes for text to fade out
**'''chat_use_cegui''' - Returns whether CEGUI is used to render the chatbox
**'''text_scale''' - Returns text scale

===Returns===
*4 numbers if the CVar contains "color"
*2 numbers if '''chat_scale''' was entered
*1 number if any other CVar was specified
*a table of all CVar values, if CVar was not specified
*''false'' if an invalid CVar was specified

==Example==
This code makes the chatbox empty when you type /clear
<syntaxhighlight lang="lua">
addCommandHandler("clear",
function ()
local lines = getChatboxLayout()["chat_lines"]
for i=1,lines do
outputChatBox("")
end
end
)
</syntaxhighlight>

==See Also==
{{GUI_functions}}

GetChatboxLayout

2014-01-22T20:31:07Z

MrTasty: Added 'table of all CVar values' to returns if CVar was not specified

__NOTOC__
{{Client function}}
Returns information about how the chatbox looks.

These values comes from the file called: [[Chatboxpresents.xml]] but it depends on what type of preset you currently have, which is chosen from your settings in the 'Interface' tab.

==Syntax==
<syntaxhighlight lang="lua">bool / int getChatboxLayout ( [ string CVar ] )</syntaxhighlight>

===Optional Arguments===
*'''CVar:''' the name of the property you want returned. Can be the following values:
**'''chat_font''' - Returns the chatbox font
**'''chat_lines''' - Returns how many lines the chatbox has
**'''chat_color''' - Returns the background color of the chatbox
**'''chat_text_color''' - Returns the chatbox text color
**'''chat_input_color''' - Returns the background color of the chatbox input
**'''chat_input_prefix_color''' - Returns the color of the input prefix text
**'''chat_input_text_color''' - Returns the color of the text in the chatbox input
**'''chat_scale''' - Returns the scale of the text in the chatbox
**'''chat_width''' - Returns the scale of the background width
**'''chat_css_style_text''' - Returns whether text fades out over time
**'''chat_css_style_background''' - Returns whether the background fades out over time
**'''chat_line_life''' - Returns how long it takes for text to start fading out
**'''chat_line_fade_out''' - Returns how long takes for text to fade out
**'''chat_use_cegui''' - Returns whether CEGUI is used to render the chatbox
**'''text_scale''' - Returns text scale

===Returns===
*4 numbers if the CVar contains "color"
*2 numbers if '''chat_scale''' was entered
*1 number if any other CVar was specified
*a table of all CVar values, if CVar was not specified
*''false'' if an invalid CVar was specified

==Example==
This code makes the chatbox empty when you type /clear
<syntaxhighlight lang="lua">
addCommandHandler("clear",
function ()
local lines = getChatboxLayout()["chat_lines"]
for i=1,lines do
outputChatBox("")
end
end
)
</syntaxhighlight>

==See Also==
{{GUI_functions}}

Template:Useful Functions

2014-01-19T11:24:01Z

MrTasty: Added 'getKeyFromValueInTable' and 'secondsToTimeDesc'

*[[callClientFunction]] » This function allows you to call any clientside function from the server's side.
*[[callServerFunction]] » This function allows you to call any server-side function from the client's side.
*[[centerWindow]] » This function center the window in any resolution.
*[[Check]] » This function checks if it's arguments are of the right types and calls the error-function if one isn't.
*[[convertNumber]] » This function converts large numbers and adds commas to it. (Example: 100000 -> 100,000)
*[[coroutine.resume]] » Fix for hidden coroutine error messages
*[[dxDrawAnimWindow]] » Create Animated Dx Window
*[[dxDrawCircle]] » This function draws a 2D line in a circle shape on the screen.
*[[dxDrawColorText]] » This function draws a dx text with #RRGGBB color codes support.
*[[dxDrawGifImage]] » This function simulates the effect of a GIF image by using image sprites.
*[[dxDrawImage3D]] » This function draws a 3D image.
*[[dxDrawPartialCircle]] » This function draws a 2D line in a partial circle shape on the screen.
*[[dxDrawRectangle3D]] » This function draws a 3D rectangle.
*[[dxGetFontSizeFromHeight]] » This function calculate a font size from given height for dxDraw.
*[[dxGetRealFontHeight]] » Accurately measures the pixel height of a font.
*[[FewPlayersOnTeams]] » This function gets a team from it's few Players.
*[[findRotation]] » Takes two points and returns the direction from point A to point B.
*[[FormatDate]] » Formats a date on the basis of a format string and returns it.
*[[GenerateString]] » With this function you can generate a random string with any characters.
*[[getAge]] » This function calculates the age of a birthday.
*[[getAlivePlayers (Client)|getAlivePlayers]] » This function returns all the alive players by a client side, so you can store them into a Gridlist or something like that, faster.
*[[getAlivePlayersInTeam]] » This function returns a table of the alive players in a team.
*[[getBoundControls]] » This function returns a list of control names that are bound to the specified key.
*[[getCursorMoveOn]] » This function checks in which way the cursor is currently moving.
*[[getDistanceBetweenPointAndSegment2D]] » Takes point coordinates and line (a segment) starting and ending coordinates. It returns the shortest distance between the point and the line.
*[[getElementSpeed]] » This function allows you to get element speed in kph or mph units.
*[[getElementsInDimension]] » This function gets the elements that are in the specified dimension.
*[[getElementsWithinMarker]] » This function gets the elements that are in a markers colshape.
*[[getJetpackWeaponsEnabled]] » This function returns a table of enabled weapons usable on a jetpack.
*[[getKeyFromValueInTable]] » This function returns the key of the specified value in a table.
*[[getOffsetFromXYZ]] » This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.
*[[getOnlineAdmins]] » This function will give the online admins.
*[[getOnlineStaff]] » Returns all online staff, names separated by two spaces.
*[[getPlayersByData]] » This function gets players who have data name you passed to it.
*[[getPlayerFromNamePart]] » This function allows you to get player From his Name part.
*[[getPlayersInPhotograph]] » This function gets all the players in a photograph.
*[[getPlayerFromSerial]] » This function gets an online player from their serial.
*[[getPointFromDistanceRotation]] » Finds a point based on a starting point, direction and distance.
*[[getResourceSettings]] » This function returns a table of the resource settings.
*[[getResourceScripts]] » This function returns a table of the resource scripts.
*[[getRGColorFromPercentage]] »This function returns two integers representing Red and Green colors according to the percentage requested.
*[[getTeamFromColor]] » This function gets a team from it's color. (Related to: [[getTeamFromName]])
*[[getTimestamp]] » With this function you can get the UNIX timestamp.
*[[getValidVehicleModels]] » This function returns a table containing valid MTA Vehicle models.
*[[getXMLNodes]] » Returns all children of a node
*[[getVehicleRespawnPosition]] » This function allows you to get the spawn position of a vehicle.
*[[guiComboBoxAdjustHeight]] » Adjusts the combobox to have a correct height.
*[[IfElse]] » Returns one of two values based on a boolean expression.
*[[isElementInPhotograph]] » This function checks if an element was in the player's camera picture.
*[[isElementInRange]] » This function allows you to check is the element's range to the main point is smaller than (or as big as) the maximum range.
*[[isElementMoving]]» This function checks if an element is moving.
*[[isElementTeam]]» This function checks if element is team.
*[[isElementWithinAColShape]]» This function checks if the [[element]] is in a [[colshape]].
*[[isPedAiming]]» This function checks if a ped is aiming.
*[[isPlayerInACL]] » This function will check to see if a player element is in an ACL group.
*[[isPlayerInTeam]] » This function check if the player in the team.
*[[isLeapYear]] » Checks if the given year is a leap year.
*[[isVehicleOnRoof]] » This function checks whether vehicle is on roof.
*[[isVehicleEmpty]] » This function checks whether a vehicle is empty.
*[[isSoundFinished]] » This function checks sound finished or not.
*[[iterElements]] » Returns an iterator for your for loops saving time typing ipairs( getElementsByType( type ) ), instead you type: iterElements( type ).
*[[mathNumber]] » This function is a workaround for the clientside floating-point precision of 24-bits
*[[math.round]] » Rounds a number whereas the number of decimals to keep and the method may be set.
*[[multi_check]] » This function checks one element to many, handy and clean.
*[[onVehicleWeaponFire]] » This code implements an event that is triggered when a player in a vehicle fires a vehicles weapon.
*[[RGBToHex]] » This function returns a string representing the color in hexadecimal.
*[[secondsToTimeDesc]] » This function converts a plain seconds-integer into a user-friendly time description.
*[[setElementSpeed]] » This function allows you to set moving element speed in kph or mph units.
*[[setTableProtected]] » Protects a table and makes it read-only.
*[[setVehicleGravityPoint]] » This clientside function sets a vehicle's gravity in the direction of a 3 dimensional coordinate with the strength specified.
*[[smoothMoveCamera]] » This clientside function allows you to create a cinematic camera flight.
*[[string.count]] » This function counts a text from a text.
*[[string.explode]] » This function splits a string at a given separator pattern and returns a table with the pieces.
*[[switch]] » This function allow the value of a variable or expression to control the flow of program execution via a multiway branch.
*[[table.copy]] » This function copies a whole table and all the tables in that table.
*[[table.compare]] » This function check if both tables is equal. 
*[[table.empty]] » This function check is empty table or not.
*[[table.map]] » This function goes through a table and replaces every field with the return of the passed function, where the field's value is passed as first argument and optionally more arguments.
*[[table.merge]] » Merges two or more tables in the first.
*[[table.random]] » This function retrieves a random variable from a table.
*[[table.size]] » Finds the absolute size of a table.
*[[toHex]] » This function converts a decimal number to a hexadecimal number, as a fix to be used clientside.
*[[var dump]] » This function outputs information about one or more variables using outputConsole()
*[[wavelengthToRGBA]] » This function converts a phisical wavelength of light to a RGBA color.
[[Category:Useful Functions]]

GetKeyFromValueInTable

2014-01-19T11:20:27Z

MrTasty:

{{Useful Function}}
__NOTOC__
This function can be used to find the key of a specified value in a specified table.

==Syntax==
<syntaxhighlight lang="lua">element/int/float/string getKeyFromValueInTable(table theTable, mixed searchFor )</syntaxhighlight>

===Required Arguments===
* '''theTable''': The table where to look for the specified value.
* '''searchFor''': The string/number/element to find the key of.

===Returns===
Returns the key of the searched value, or ''false'' if not found.

==Code==
<section name="Function source" class="both" show="true">
<syntaxhighlight lang="lua">
function getKeyFromValueInTable(a, b)
for k,v in ipairs(a) do
if v == b then
return k
end
end
return false
end
</syntaxhighlight>
</section>
Author: MrTasty

==Example==
This example output the cost of the item specified by the player who entered the command.

'''NOTE:''' This is not the most efficient way, as it won't allow you to have more than 1 item of the same cost.
<syntaxhighlight lang="lua">
shopItems = {
--[PRICE] = "ITEM NAME",
[10] = "Sprunk Soda",
[12] = "eCola",
[17] = "Pisswasser",
}

addCommandHandler("getcostof", function(player, command, item)
if item then
local cost = getKeyFromValueInTable(shopItems, item) --Find the key (the price in this case) of entered item name
if cost then
outputChatBox(item.." costs $"..cost, player, 255, 0, 0) --If the cost was found, output it to the command executor
else
outputChatBox(item.." is not available in our shop.", player, 255, 0, 0) --If it wasn't, tell the command executor that the item does not have a cost (ie: not in the shop)
end
else
outputChatBox("Syntax error. Valid syntax is: /"..command.." <item name>", player, 255, 0, 0) --Output valid syntax in case the executor did not specify the item name to search for
end
end)
</syntaxhighlight>

==See Also==
{{Useful_Functions}}