Multi Theft Auto: Wiki - User contributions [en]

PlaySoundFrontEnd

2010-04-17T23:58:06Z

Norby89: /* Example */

{{Server client function}}
__NOTOC__
This function plays a frontend sound for the specified player.

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool playSoundFrontEnd ( player thePlayer, int sound )
</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The [[player]] you want the sound to play for.
*'''sound:''' A whole [[int]] specifying the sound id to play. Valid values are:
{{Sounds}}
</section>
<section name="Client" class="client" show="false">
<syntaxhighlight lang="lua">
bool playSoundFrontEnd ( int sound )
</syntaxhighlight>

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

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

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

==See Also==
{{Client_audio_functions}}

Var dump

2009-12-23T10:02:39Z

Norby89: minor typo

{{Useful Function}}
<lowercasetitle>var_dump</lowercasetitle>
__NOTOC__
This function outputs information about one or more variables using outputConsole().

==Syntax==
<syntaxhighlight lang="lua">string/table var_dump( ... )</syntaxhighlight>

===Arguments===
The function can have a variable number of arguments. Those arguments can be of three types:
* '''Modifiers:''' A ''string'' that begins with a "-" (minus) and that is followed by at least another parameter is a modifier. A modifier can change the behaviour of the function. Modifiers don't have to be the first argument, they always work on all arguments after it (see examples).
* '''Names:''' A ''string'' that is followed by at least another parameter and isn't preceeded by another ''string'' (that is not a modifier), is a name. A name is output before the variable output, to make it recognizable (basicially a description of the variable that is being output, e.g. the name).
* '''Values:''' Any value that is not one of the two above will generate an output with information about the variable:
** For ''strings'': string(''lengthOfString'') "''value''"
** For ''userdata'': userdata(''MTA element type'') "''value''"
** For ''tables'': table(''numerOfElements'') "''value''"
*** If the table contains any elements, they will also be output if the appropriate modifiers are set. This will always be in the form [''key''] => ''value'', while ''key'' and ''value'' are formatted by var_dump.

===Modifiers===
* '''v''' (verbose): Dumps more data than usual (for now it outputs whole tables including subtables)
* '''n''' (normal): Switches back into 'normal' non-verbose mode.
* '''s''' (silent): With this activated, it outputs nothing at all, however it still returns the output, so you can use it yourself (also used internally for recursion).
* '''u''' (unnamed): Don't use names. Every ''string'' that is not a modifier will be output as a value, not a decription.
* '''d[number]''' (depth): Output nested tables up to this depth (e.g. "d1" means output all values of the initial table, but not the values of the values, if they are also tables).

===Returns===
Returns a string with all the output in one line and a table with several lines of output.

==Code==
<section name="Server- and/or clientside Script" class="both" show="true">
<syntaxhighlight lang="lua" lang="lua">
-- modifiers: v - verbose (all subtables), n - normal, s - silent (no output), dx - up to depth x, u - unnamed
function var_dump(...)
-- default options
local verbose = false
local firstLevel = true
local outputDirectly = true
local noNames = false
local indentation = "\t\t\t\t\t\t"
local depth = nil

local name = nil
local output = {}
for k,v in ipairs(arg) do
-- check for modifiers
if type(v) == "string" and k < #arg and v:sub(1,1) == "-" then
local modifiers = v:sub(2)
if modifiers:find("v") ~= nil then
verbose = true
end
if modifiers:find("s") ~= nil then
outputDirectly = false
end
if modifiers:find("n") ~= nil then
verbose = false
end
if modifiers:find("u") ~= nil then
noNames = true
end
local s,e = modifiers:find("d%d+")
if s ~= nil then
depth = tonumber(string.sub(modifiers,s+1,e))
end
-- set name if appropriate
elseif type(v) == "string" and k < #arg and name == nil and not noNames then
name = v
else
if name ~= nil then
name = ""..name..": "
else
name = ""
end

local o = ""
if type(v) == "string" then
table.insert(output,name..type(v).."("..v:len()..") \""..v.."\"")
elseif type(v) == "userdata" then
local elementType = "no valid MTA element"
if isElement(v) then
elementType = getElementType(v)
end
table.insert(output,name..type(v).."("..elementType..") \""..tostring(v).."\"")
elseif type(v) == "table" then
local count = 0
for key,value in pairs(v) do
count = count + 1
end
table.insert(output,name..type(v).."("..count..") \""..tostring(v).."\"")
if verbose and count > 0 and (depth == nil or depth > 0) then
table.insert(output,"\t{")
for key,value in pairs(v) do
-- calls itself, so be careful when you change anything
local newModifiers = "-s"
if depth == nil then
newModifiers = "-sv"
elseif depth > 1 then
local newDepth = depth - 1
newModifiers = "-svd"..newDepth
end
local keyString, keyTable = var_dump(newModifiers,key)
local valueString, valueTable = var_dump(newModifiers,value)

if #keyTable == 1 and #valueTable == 1 then
table.insert(output,indentation.."["..keyString.."]\t=>\t"..valueString)
elseif #keyTable == 1 then
table.insert(output,indentation.."["..keyString.."]\t=>")
for k,v in ipairs(valueTable) do
table.insert(output,indentation..v)
end
elseif #valueTable == 1 then
for k,v in ipairs(keyTable) do
if k == 1 then
table.insert(output,indentation.."["..v)
elseif k == #keyTable then
table.insert(output,indentation..v.."]")
else
table.insert(output,indentation..v)
end
end
table.insert(output,indentation.."\t=>\t"..valueString)
else
for k,v in ipairs(keyTable) do
if k == 1 then
table.insert(output,indentation.."["..v)
elseif k == #keyTable then
table.insert(output,indentation..v.."]")
else
table.insert(output,indentation..v)
end
end
for k,v in ipairs(valueTable) do
if k == 1 then
table.insert(output,indentation.." => "..v)
else
table.insert(output,indentation..v)
end
end
end
end
table.insert(output,"\t}")
end
else
table.insert(output,name..type(v).." \""..tostring(v).."\"")
end
name = nil
end
end
local string = ""
for k,v in ipairs(output) do
if outputDirectly then
outputConsole(v)
end
string = string..v
end
return string, output
end
</syntaxhighlight>
</section>

==Example==
<section name="Serverside Example" class="server" show="true">
Get a table of all players on the server (if there are 4 players).
<syntaxhighlight lang="lua" lang="lua">
var_dump(getElementsByType("player"))
</syntaxhighlight>
Output:
<syntaxhighlight lang="lua">
table(4) "table: 02998058"
</syntaxhighlight>
With 'verbose' modifier.
<syntaxhighlight lang="lua">
var_dump("-v",getElementsByType("player"))
</syntaxhighlight>
<syntaxhighlight lang="lua">
table(1) "table: 043C6900"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
</syntaxhighlight>

Now another table we created before (please note that the table 'test2' is both key and value in this example):
<syntaxhighlight lang="lua">
test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v",getElementsByType("player"),test)
</syntaxhighlight>

<syntaxhighlight lang="lua">
table(1) "table: 020B7838"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
table(2) "table: 021770A0"
{
[string(5) "hello"] => string(4) "test"
[table(2) "table: 02313070"
{
[number "1"] => string(4) "haha"
[number "2"] => string(4) "naja"
}]
=> table(2) "table: 02313070"
{
[number "1"] => string(4) "haha"
[number "2"] => string(4) "naja"
}
}
</syntaxhighlight>

The same as before, but now with a modifier to output the second table 'normal':
<syntaxhighlight lang="lua">
test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v",getElementsByType("player"),"-n",test)
</syntaxhighlight>

<syntaxhighlight lang="lua">
table(1) "table: 01BB9030"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
table(2) "table: 0223B2D8"
</syntaxhighlight>

The same as before, but now with a modifier to output the second table only to depth 1 (the verbose is still active from the first argument):
<syntaxhighlight lang="lua">
test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v",getElementsByType("player"),"-d1",test)
</syntaxhighlight>

<syntaxhighlight lang="lua">
table(1) "table: 029BE6E8"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
table(2) "table: 01E2CDF8"
{
[string(5) "hello"] => string(4) "test"
[table(2) "table: 021C6378"] => table(2) "table: 021C6378"
}
</syntaxhighlight>

The same as before, but now with names to make clear which output belongs to which variable (of course in this small example, it's not really needed):
<syntaxhighlight lang="lua">
test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v","players",getElementsByType("player"),"-d1","test tables",test)
</syntaxhighlight>

<syntaxhighlight lang="lua">
players: table(1) "table: 0219F4D0"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
test tables: table(2) "table: 0219DB20"
{
[string(5) "hello"] => string(4) "test"
[table(2) "table: 01B68048"] => table(2) "table: 01B68048"
}
</syntaxhighlight>

The same as before, but now 'unnamed', meaning all values that are not modifiers will be output as values. However, the last two arguments were also removed, which leaves the last modifier as last argument, which will output the modifier as a normal value:
<syntaxhighlight lang="lua">
var_dump("-u","players",getElementsByType("player"),"-d1")
</syntaxhighlight>

<syntaxhighlight lang="lua">
string(7) "players"
table(1) "table: 028B8A10"
string(3) "-d1"
</syntaxhighlight>

</section>

==See Also==
{{Useful_Functions}}

Access Control List

2009-10-02T19:47:30Z

Norby89:

MTA includes a complete Access Control List (ACL) that allows you to secure and limit access to the server, its functions and resources in any number of ways.

The key concept of MTA's ACL (and ACLs in general) is that you're giving a specific object a set of rights. In MTA's case objects are one of two things - resources or users. There are numerous ''rights'' available in MTA - these mainly focus on server-side scripting functions.

What this essentially means is that the ACL allows you to choose exactly what functions a resource or user can perform. This can obviously be invaluable - for example preventing all your server's players from being able to ban each other, or preventing your new untested resources from doing the same.

Of course, ''with great power comes great responsibility'' and it is very easily possible to completely break resources - for example, disabling [[spawnPlayer]] for all resources would be a Bad Thing. Of course, there are situations when you might want to do this - if you want to force all your resources to use a spawn manager resource for example, but even this is somewhat draconian.

==How it works==
There are three ways you can modify the ACL - how you do it depends who you are.

===HTTP Interface===
You can use the [[Resource/webadmin|webadmin]] http interface to modify the ACL in your web browser. This is by far the easiest way to do so. Just make sure the ''webadmin'' resource is started on your server and visit ''<nowiki>http://ServerIP:HttpPort/</nowiki>''. You can then use the two sections - ACLs and Groups. ACLs allows you to create your Access Control Lists - lists of rights. Groups allow you to group together collections of users and assign ACLs to them. For example, the ACLs section allows you to specify that the Admin ACL has access to the ''start'' console command. You can the go to the Groups section and create an Admin ''group'' that has access to your Admin ''acl''. You can then add users to your Admin ''group''.

===XML file===
You can modify the ACL.xml file manually. This has a fairly straightforward syntax, but it can get a bit confusing at times. If you do it while the server is running, don't forget to call the scripting function [[aclReload]] ("start runcode", "run aclReload()") so the new ACL is loaded, or otherwise stop your server before modifying. This also prevents your changes from being accidentally overwritten by the server.

===Scripting functions===
You can use a large number of ACL scripting functions to modify the ACL on the fly. Of course, you can (and really should!) limit access to the ACL functions with the ACL.

{{ACL functions}}
[[Category:Scripting Concepts]]

SetWaterColor

2009-07-30T17:17:54Z

Norby89: /* Example */

__NOTOC__
{{Client function}}
This function changes the water color of the GTA world.

==Syntax==
<syntaxhighlight lang="lua">
bool setWaterColor ( int red, int green, int blue, [ int alpha = 200 ] )
</syntaxhighlight>

===Required Arguments===
*'''red:''' The ''red'' value of the water, from 0 to 255.
*'''green:''' The ''green'' value of the water, from 0 to 255.
*'''blue:''' The ''blue'' value of the water, from 0 to 255.

===Optional Arguments===
{{OptionalArg}}
*'''alpha:''' The ''alpha'' (visibility) value of the water, from 0 to 255. Defaults to 200 if not declared.

===Returns===
Returns ''true'' if water color was set correctly, ''false'' if invalid values were passed.

==Example==
This example adds a command ''watercolor'' with which a player can change the water colour.
<syntaxhighlight lang="lua">
function changeWaterColor ( commandName, red, green, blue, alpha )
-- if alpha is input, then include it too
alpha = tonumber ( alpha ) or 200
red = tonumber ( red )
green = tonumber ( green )
blue = tonumber ( blue )
-- check if the colour values for red, green and blue are valid
if red and green and blue then
setWaterColor ( red, green, blue, alpha )
else
outputChatBox ( "Failed to change the water colour!" )
end
end
addCommandHandler ( "watercolor", changeWaterColor )
</syntaxhighlight>

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

Resource:Race

2009-07-12T14:11:53Z

Norby89:

{{Resource page}}
__NOTOC__
The "race" gamemode organizes sprint or freeroam races for one or more players. It supports both maps from MTA:Race and maps in the MTA:SA DM map syntax that were created in the map editor.

==Ingame==
Playing race is quite straightforward. If there are checkpoints, drive from checkpoint to checkpoint and be the first to reach the finish line within the time. If there are no checkpoints, just drive around and have fun.

In races you may encounter three types of pickups which will have an effect on your vehicle:
*'''Repair pickups:''' this pickup looks like a wrench. If you drive over it, your vehicle will be restored to full health.
*'''Nitrous oxide pickups:''' a red NOS bottle. After you drive over one you can press the fire button (by default the left mouse button) to get a temporary speed boost.
*'''Vehicle change pickups:''' these display the name of a vehicle above them. As soon as you drive over a pickup your vehicle will be changed.

Lastly, if you get stuck during a race, you can enter the /kill command in the chatbox to kill yourself and respawn at the previous checkpoint.

==Installing maps==
===Installing maps in MTA:Race syntax===
Adding MTA:Race maps to your DM server is easy. All you have to do is place the file in a folder and add a meta.xml. No conversion is necessary.
*Go to the "resources" folder of your server installation (<SERVER>\mods\deathmatch\resources) and create a new folder. In order to keep with conventions, the folder name should be in the format "race-<mapname>", so if the map file is called "Dirtring.map" you might call the folder "race-dirtring".
*Copy the .map file into the new folder
*Create a meta.xml file in the new folder and paste the following text into it:
<div style="padding-left: 20px">
<syntaxhighlight lang="xml">
<meta>
<info type="map" gamemodes="race" name="" />
<race src=".map" />
</meta>
</syntaxhighlight>
</div>
*Enter the name of the map, for example "Dirtring", in the "name" attribute of the <info> node.
*Enter the name of the .map file in the "src" attribute of the <race> node, for example "Dirtring.map".
*Save the meta.xml.
*Add more maps if you wish. When you're done, /refresh your server resources.

===Installing maps in DM syntax===
If you created the map yourself in the MTA:SA DM map editor (not released at this point), everything will be in place and you only need to /refresh. If you downloaded the map, place it in your server "resources" folder and /refresh.

===Converting maps from Race syntax to DM syntax===
The MTA:SA DM map editor can only edit maps in the DM syntax. If you want to edit maps that are in MTA:Race syntax, you need to convert them.
*Make sure the map you want to convert is not in a zip file. If it is, create a folder with the same name as the zip file and extract the zip contents into it.
*Make sure race is started. Either have a race map running, or do /start race.
*Enter the command /convrace <map resource name>.
*The conversion process should be very quick. Once conversion is complete a message will appear.
The map file is overwritten with the converted version. If you want to keep the original file, make sure you have a backup.

==Map syntax==
===MTA:Race style syntax===
<syntaxhighlight lang="xml">
<map mod="race">
<meta>
<author>Author name</author>
<description>Map description</description>
<version>Map version number</version>
</meta>

<options>
<weather>Weather ID</weather>
<respawn>timelimit|none</respawn> 
<duration>Maximum race time in seconds. Default is 10 minutes</duration>
<time>hour:minute</time> 
<vehicleweapons>true|false</vehicleweapons> 
<ghostmode>true|false</ghostmode> 
<skins>cj|random|rangelist></skins> 

<respawntime>Time from death to respawn in seconds. Default is 10.</respawntime>
</options>


<spawnpoint>
<position>X Y Z</position>
<rotation>Angle in degrees. 0 = north, higher values go counter clockwise.</rotation>
<vehicle>Vehicle number</vehicle>

<paintjob>Paintjob ID, ranges from 0 to 3</paintjob>
<upgrades>Space separated list of vehicle upgrade numbers</upgrades>
</spawnpoint>


<checkpoint>
<position>X Y Z</position>
<size>Float. Higher values make the checkpoint marker bigger. Default is 1</size>
<color>R G B</color> 

<vehicle>Vehicle ID to change into when passing through this checkpoint</vehicle>
<paintjob>Paintjob ID, ranges from 0 to 3</paintjob>
<upgrades>Space separated list of vehicle upgrade numbers</upgrades>
</checkpoint>


<object>
<position>X Y Z</position>
<rotation>rotX rotY rotZ</rotation> 
<model>Model ID</model>
</object>


<pickup>
<position>X Y Z</position>
<type>repair|nitro|vehiclechange</type>

<vehicle>Vehicle ID to change into</vehicle>

<paintjob>paintjob ID</paintjob>
<upgrades>Space separated upgrade list</upgrades>
</pickup>
</map>
</syntaxhighlight>

The <skins> option can be "cj" (players are CJ in random clothes), "random" (players have random ped skins), or a range list. A range list is a space separated list of single numbers and ranges of numbers expressed as "start-end". For example:

<syntaxhighlight lang="lua">18 40-50 65-68 72 200</syntaxhighlight>

The skin of each player will be chosen at random from this list.

===MTA:SA DM style syntax===
====.map file====
<syntaxhighlight lang="xml">
<map mod="deathmatch">

<spawnpoint posX="X" posY="Y" posZ="Z" rotation="Rotation in degrees" vehicle="Vehicle ID" id="spawnpointID" [ paintjob="paintjob ID" upgrades="*comma*-separated list of upgrades" ] />


<checkpoint posX="X" posY="Y" posZ="Z" color="#FF0000" id="textual or numeric checkpoint ID" nextid="ID of checkpoint after this one" [ size="checkpoint size" vehicle="vehicle ID to change into" paintjob="paintjob ID" upgrades="comma-separated list of upgrades" ] />


<object posX="X" posY="Y" posZ="Z" rotX="in degrees" rotY="in degrees" rotZ="in degrees" model="model ID" id="objectID" />


<pickup posX="X" posY="Y" posZ="Z" type="repair|nitro|vehiclechange" id="pickupID" [ vehicle="vehicle ID" paintjob="paintjob ID" upgrades="comma-separated list of upgrades" ] />
</map>
</syntaxhighlight>

====meta.xml====
<syntaxhighlight lang="xml">
<meta>
<info type="map" gamemodes="race" name="Map name" author="Author name" description="Map description" version="Map version number"/>
<race src="Map file.map"/>
<settings>
<setting name="#optionName" value="optionValue"/>
...
</settings>
</meta>
</syntaxhighlight>
The <setting>s correspond to options in MTA:Race syntax. For example, <time>4:0</time> in MTA:Race syntax would correspond to <setting name="#time" value="4:0"/> in DM syntax.

==Adding your scripts to Race==
If you want to add new features to Race, you can either modify the original Race resource files, or more preferably, add the features as a separate resource and communicate with Race via events.
Not hacking the Race core and is probably a good idea if you want to apply official updates and fixes for Race in the future. Choosing to use separate resources for your customization also means you can continue use customizations from other people, and if you so wish, share your customization with others.

==Addons==
A Race 'addon' is no different from any other script resource, except that is has addon="race" in the <info> section of it's meta.xml file. This is simply to allow Race to identify it and put it in the /config menu for you. Addons communicate with Race via events. The current list of Race events and what they do are here:

==Events for version 0.8.3==

===Server===

'''onPlayerReachCheckpoint'''

'''onPlayerPickUpRacePickup'''

'''onMapStarting'''

'''onPlayerFinish'''

'''onPostFinish'''

'''onPollStarting'''

===Client===
'''onClientMapStarting'''

'''onClientPlayerFinish'''

'''onClientPlayerOutOfTime'''

'''onClientMapStopping'''

'''onClientScreenFadedOut'''

'''onClientScreenFadedIn'''

==Events for version 0.8.3 in detail==
===onPlayerReachCheckpoint===
====Parameters====
<syntaxhighlight lang="lua">int checkpoint</syntaxhighlight>
*'''checkpoint:''' the number of the checkpoint the player went through. The first checkpoint has number 1.

====Source====
The source is the player that reached the checkpoint.

===onPlayerPickUpRacePickup===
====Parameters====
<syntaxhighlight lang="lua">int/string pickupID</syntaxhighlight>
*'''pickupID:''' the number of the pickup in case of MTA:Race syntax (starting at 1), or the "id" attribute of the pickup in case of DM syntax.

====Source====
The source is the player that picked up the pickup.

==Element data==
These element data are set on each player:
*'''Race rank:''' the current position of the player in the race. 1 = first, 2 = second etc. Updated on a 1 second interval.
*'''race.checkpoint:''' the number of the checkpoint the player is ''heading for''. When the player spawns this number is 1, after he passed the first checkpoint it's 2, etc.
*'''race.finished:''' ''true'' if the player has finished, ''false'' if he's still racing.

Resource:Race

2009-07-10T15:38:18Z

Norby89: wrong default checkpoint size

{{Resource page}}
__NOTOC__
The "race" gamemode organizes sprint or freeroam races for one or more players. It supports both maps from MTA:Race and maps in the MTA:SA DM map syntax that were created in the map editor.

==Ingame==
Playing race is quite straightforward. If there are checkpoints, drive from checkpoint to checkpoint and be the first to reach the finish line within the time. If there are no checkpoints, just drive around and have fun.

In races you may encounter three types of pickups which will have an effect on your vehicle:
*'''Repair pickups:''' this pickup looks like a wrench. If you drive over it, your vehicle will be restored to full health.
*'''Nitrous oxide pickups:''' a red NOS bottle. After you drive over one you can press the fire button (by default the left mouse button) to get a temporary speed boost.
*'''Vehicle change pickups:''' these display the name of a vehicle above them. As soon as you drive over a pickup your vehicle will be changed.

Lastly, if you get stuck during a race, you can enter the /kill command in the chatbox to kill yourself and respawn at the previous checkpoint.

==Installing maps==
===Installing maps in MTA:Race syntax===
Adding MTA:Race maps to your DM server is easy. All you have to do is place the file in a folder and add a meta.xml. No conversion is necessary.
*Go to the "resources" folder of your server installation (<SERVER>\mods\deathmatch\resources) and create a new folder. In order to keep with conventions, the folder name should be in the format "race-<mapname>", so if the map file is called "Dirtring.map" you might call the folder "race-dirtring".
*Copy the .map file into the new folder
*Create a meta.xml file in the new folder and paste the following text into it:
<div style="padding-left: 20px">
<syntaxhighlight lang="xml">
<meta>
<info type="map" gamemodes="race" name="" />
<race src=".map" />
</meta>
</syntaxhighlight>
</div>
*Enter the name of the map, for example "Dirtring", in the "name" attribute of the <info> node.
*Enter the name of the .map file in the "src" attribute of the <race> node, for example "Dirtring.map".
*Save the meta.xml.
*Add more maps if you wish. When you're done, /refresh your server resources.

===Installing maps in DM syntax===
If you created the map yourself in the MTA:SA DM map editor (not released at this point), everything will be in place and you only need to /refresh. If you downloaded the map, place it in your server "resources" folder and /refresh.

===Converting maps from Race syntax to DM syntax===
The MTA:SA DM map editor can only edit maps in the DM syntax. If you want to edit maps that are in MTA:Race syntax, you need to convert them.
*Make sure the map you want to convert is not in a zip file. If it is, create a folder with the same name as the zip file and extract the zip contents into it.
*Make sure race is started. Either have a race map running, or do /start race.
*Enter the command /convrace <map resource name>.
*The conversion process should be very quick. Once conversion is complete a message will appear.
The map file is overwritten with the converted version. If you want to keep the original file, make sure you have a backup.

==Map syntax==
===MTA:Race style syntax===
<syntaxhighlight lang="xml">
<map mod="race">
<meta>
<author>Author name</author>
<description>Map description</description>
<version>Map version number</version>
</meta>

<options>
<weather>Weather ID</weather>
<respawn>timelimit|none</respawn> 
<duration>Maximum race time in seconds. Default is 10 minutes</duration>
<time>hour:minute</time> 
<vehicleweapons>true|false</vehicleweapons> 
<ghostmode>true|false</ghostmode> 
<skins>cj|random|rangelist></skins> 

<respawntime>Time from death to respawn in seconds. Default is 5.</respawntime>
</options>


<spawnpoint>
<position>X Y Z</position>
<rotation>Angle in degrees. 0 = north, higher values go counter clockwise.</rotation>
<vehicle>Vehicle number</vehicle>

<paintjob>Paintjob ID, ranges from 0 to 3</paintjob>
<upgrades>Space separated list of vehicle upgrade numbers</upgrades>
</spawnpoint>


<checkpoint>
<position>X Y Z</position>
<size>Float. Higher values make the checkpoint marker bigger. Default is 1</size>
<color>R G B</color> 

<vehicle>Vehicle ID to change into when passing through this checkpoint</vehicle>
<paintjob>Paintjob ID, ranges from 0 to 3</paintjob>
<upgrades>Space separated list of vehicle upgrade numbers</upgrades>
</checkpoint>


<object>
<position>X Y Z</position>
<rotation>rotX rotY rotZ</rotation> 
<model>Model ID</model>
</object>


<pickup>
<position>X Y Z</position>
<type>repair|nitro|vehiclechange</type>

<vehicle>Vehicle ID to change into</vehicle>

<paintjob>paintjob ID</paintjob>
<upgrades>Space separated upgrade list</upgrades>
</pickup>
</map>
</syntaxhighlight>

The <skins> option can be "cj" (players are CJ in random clothes), "random" (players have random ped skins), or a range list. A range list is a space separated list of single numbers and ranges of numbers expressed as "start-end". For example:

<syntaxhighlight lang="lua">18 40-50 65-68 72 200</syntaxhighlight>

The skin of each player will be chosen at random from this list.

===MTA:SA DM style syntax===
====.map file====
<syntaxhighlight lang="xml">
<map mod="deathmatch">

<spawnpoint posX="X" posY="Y" posZ="Z" rotation="Rotation in degrees" vehicle="Vehicle ID" id="spawnpointID" [ paintjob="paintjob ID" upgrades="*comma*-separated list of upgrades" ] />


<checkpoint posX="X" posY="Y" posZ="Z" color="#FF0000" id="textual or numeric checkpoint ID" nextid="ID of checkpoint after this one" [ size="checkpoint size" vehicle="vehicle ID to change into" paintjob="paintjob ID" upgrades="comma-separated list of upgrades" ] />


<object posX="X" posY="Y" posZ="Z" rotX="in degrees" rotY="in degrees" rotZ="in degrees" model="model ID" id="objectID" />


<pickup posX="X" posY="Y" posZ="Z" type="repair|nitro|vehiclechange" id="pickupID" [ vehicle="vehicle ID" paintjob="paintjob ID" upgrades="comma-separated list of upgrades" ] />
</map>
</syntaxhighlight>

====meta.xml====
<syntaxhighlight lang="xml">
<meta>
<info type="map" gamemodes="race" name="Map name" author="Author name" description="Map description" version="Map version number"/>
<race src="Map file.map"/>
<settings>
<setting name="#optionName" value="optionValue"/>
...
</settings>
</meta>
</syntaxhighlight>
The <setting>s correspond to options in MTA:Race syntax. For example, <time>4:0</time> in MTA:Race syntax would correspond to <setting name="#time" value="4:0"/> in DM syntax.

==Adding your scripts to Race==
If you want to add new features to Race, you can either modify the original Race resource files, or more preferably, add the features as a separate resource and communicate with Race via events.
Not hacking the Race core and is probably a good idea if you want to apply official updates and fixes for Race in the future. Choosing to use separate resources for your customization also means you can continue use customizations from other people, and if you so wish, share your customization with others.

==Addons==
A Race 'addon' is no different from any other script resource, except that is has addon="race" in the <info> section of it's meta.xml file. This is simply to allow Race to identify it and put it in the /config menu for you. Addons communicate with Race via events. The current list of Race events and what they do are here:

==Events for version 0.8.3==

==Server==

'''onPlayerReachCheckpoint'''

'''onPlayerPickUpRacePickup'''

'''onMapStarting'''

'''onPlayerFinish'''

'''onPostFinish'''

'''onPollStarting'''

==Client==
'''onClientMapStarting'''

'''onClientPlayerFinish'''

'''onClientPlayerOutOfTime'''

'''onClientMapStopping'''

'''onClientScreenFadedOut'''

'''onClientScreenFadedIn'''

==Events for version 0.8.3 in detail==
===onPlayerReachCheckpoint===
====Parameters====
<syntaxhighlight lang="lua">int checkpoint</syntaxhighlight>
*'''checkpoint:''' the number of the checkpoint the player went through. The first checkpoint has number 1.

====Source====
The source is the player that reached the checkpoint.

===onPlayerPickUpRacePickup===
====Parameters====
<syntaxhighlight lang="lua">int/string pickupID</syntaxhighlight>
*'''pickupID:''' the number of the pickup in case of MTA:Race syntax (starting at 1), or the "id" attribute of the pickup in case of DM syntax.

====Source====
The source is the player that picked up the pickup.

==Element data==
These element data are set on each player:
*'''Race rank:''' the current position of the player in the race. 1 = first, 2 = second etc. Updated on a 1 second interval.
*'''race.checkpoint:''' the number of the checkpoint the player is ''heading for''. When the player spawns this number is 1, after he passed the first checkpoint it's 2, etc.
*'''race.finished:''' ''true'' if the player has finished, ''false'' if he's still racing.

Resource:Race

2009-07-10T15:28:30Z

Norby89: wrong default values

{{Resource page}}
__NOTOC__
The "race" gamemode organizes sprint or freeroam races for one or more players. It supports both maps from MTA:Race and maps in the MTA:SA DM map syntax that were created in the map editor.

==Ingame==
Playing race is quite straightforward. If there are checkpoints, drive from checkpoint to checkpoint and be the first to reach the finish line within the time. If there are no checkpoints, just drive around and have fun.

In races you may encounter three types of pickups which will have an effect on your vehicle:
*'''Repair pickups:''' this pickup looks like a wrench. If you drive over it, your vehicle will be restored to full health.
*'''Nitrous oxide pickups:''' a red NOS bottle. After you drive over one you can press the fire button (by default the left mouse button) to get a temporary speed boost.
*'''Vehicle change pickups:''' these display the name of a vehicle above them. As soon as you drive over a pickup your vehicle will be changed.

Lastly, if you get stuck during a race, you can enter the /kill command in the chatbox to kill yourself and respawn at the previous checkpoint.

==Installing maps==
===Installing maps in MTA:Race syntax===
Adding MTA:Race maps to your DM server is easy. All you have to do is place the file in a folder and add a meta.xml. No conversion is necessary.
*Go to the "resources" folder of your server installation (<SERVER>\mods\deathmatch\resources) and create a new folder. In order to keep with conventions, the folder name should be in the format "race-<mapname>", so if the map file is called "Dirtring.map" you might call the folder "race-dirtring".
*Copy the .map file into the new folder
*Create a meta.xml file in the new folder and paste the following text into it:
<div style="padding-left: 20px">
<syntaxhighlight lang="xml">
<meta>
<info type="map" gamemodes="race" name="" />
<race src=".map" />
</meta>
</syntaxhighlight>
</div>
*Enter the name of the map, for example "Dirtring", in the "name" attribute of the <info> node.
*Enter the name of the .map file in the "src" attribute of the <race> node, for example "Dirtring.map".
*Save the meta.xml.
*Add more maps if you wish. When you're done, /refresh your server resources.

===Installing maps in DM syntax===
If you created the map yourself in the MTA:SA DM map editor (not released at this point), everything will be in place and you only need to /refresh. If you downloaded the map, place it in your server "resources" folder and /refresh.

===Converting maps from Race syntax to DM syntax===
The MTA:SA DM map editor can only edit maps in the DM syntax. If you want to edit maps that are in MTA:Race syntax, you need to convert them.
*Make sure the map you want to convert is not in a zip file. If it is, create a folder with the same name as the zip file and extract the zip contents into it.
*Make sure race is started. Either have a race map running, or do /start race.
*Enter the command /convrace <map resource name>.
*The conversion process should be very quick. Once conversion is complete a message will appear.
The map file is overwritten with the converted version. If you want to keep the original file, make sure you have a backup.

==Map syntax==
===MTA:Race style syntax===
<syntaxhighlight lang="xml">
<map mod="race">
<meta>
<author>Author name</author>
<description>Map description</description>
<version>Map version number</version>
</meta>

<options>
<weather>Weather ID</weather>
<respawn>timelimit|none</respawn> 
<duration>Maximum race time in seconds. Default is 10 minutes</duration>
<time>hour:minute</time> 
<vehicleweapons>true|false</vehicleweapons> 
<ghostmode>true|false</ghostmode> 
<skins>cj|random|rangelist></skins> 

<respawntime>Time from death to respawn in seconds. Default is 5.</respawntime>
</options>


<spawnpoint>
<position>X Y Z</position>
<rotation>Angle in degrees. 0 = north, higher values go counter clockwise.</rotation>
<vehicle>Vehicle number</vehicle>

<paintjob>Paintjob ID, ranges from 0 to 3</paintjob>
<upgrades>Space separated list of vehicle upgrade numbers</upgrades>
</spawnpoint>


<checkpoint>
<position>X Y Z</position>
<size>Float. Higher values make the checkpoint marker bigger. Default is 2.25</size>
<color>R G B</color> 

<vehicle>Vehicle ID to change into when passing through this checkpoint</vehicle>
<paintjob>Paintjob ID, ranges from 0 to 3</paintjob>
<upgrades>Space separated list of vehicle upgrade numbers</upgrades>
</checkpoint>


<object>
<position>X Y Z</position>
<rotation>rotX rotY rotZ</rotation> 
<model>Model ID</model>
</object>


<pickup>
<position>X Y Z</position>
<type>repair|nitro|vehiclechange</type>

<vehicle>Vehicle ID to change into</vehicle>

<paintjob>paintjob ID</paintjob>
<upgrades>Space separated upgrade list</upgrades>
</pickup>
</map>
</syntaxhighlight>

The <skins> option can be "cj" (players are CJ in random clothes), "random" (players have random ped skins), or a range list. A range list is a space separated list of single numbers and ranges of numbers expressed as "start-end". For example:

<syntaxhighlight lang="lua">18 40-50 65-68 72 200</syntaxhighlight>

The skin of each player will be chosen at random from this list.

===MTA:SA DM style syntax===
====.map file====
<syntaxhighlight lang="xml">
<map mod="deathmatch">

<spawnpoint posX="X" posY="Y" posZ="Z" rotation="Rotation in degrees" vehicle="Vehicle ID" id="spawnpointID" [ paintjob="paintjob ID" upgrades="*comma*-separated list of upgrades" ] />


<checkpoint posX="X" posY="Y" posZ="Z" color="#FF0000" id="textual or numeric checkpoint ID" nextid="ID of checkpoint after this one" [ size="checkpoint size" vehicle="vehicle ID to change into" paintjob="paintjob ID" upgrades="comma-separated list of upgrades" ] />


<object posX="X" posY="Y" posZ="Z" rotX="in degrees" rotY="in degrees" rotZ="in degrees" model="model ID" id="objectID" />


<pickup posX="X" posY="Y" posZ="Z" type="repair|nitro|vehiclechange" id="pickupID" [ vehicle="vehicle ID" paintjob="paintjob ID" upgrades="comma-separated list of upgrades" ] />
</map>
</syntaxhighlight>

====meta.xml====
<syntaxhighlight lang="xml">
<meta>
<info type="map" gamemodes="race" name="Map name" author="Author name" description="Map description" version="Map version number"/>
<race src="Map file.map"/>
<settings>
<setting name="#optionName" value="optionValue"/>
...
</settings>
</meta>
</syntaxhighlight>
The <setting>s correspond to options in MTA:Race syntax. For example, <time>4:0</time> in MTA:Race syntax would correspond to <setting name="#time" value="4:0"/> in DM syntax.

==Adding your scripts to Race==
If you want to add new features to Race, you can either modify the original Race resource files, or more preferably, add the features as a separate resource and communicate with Race via events.
Not hacking the Race core and is probably a good idea if you want to apply official updates and fixes for Race in the future. Choosing to use separate resources for your customization also means you can continue use customizations from other people, and if you so wish, share your customization with others.

==Addons==
A Race 'addon' is no different from any other script resource, except that is has addon="race" in the <info> section of it's meta.xml file. This is simply to allow Race to identify it and put it in the /config menu for you. Addons communicate with Race via events. The current list of Race events and what they do are here:

==Events for version 0.8.3==

==Server==

'''onPlayerReachCheckpoint'''

'''onPlayerPickUpRacePickup'''

'''onMapStarting'''

'''onPlayerFinish'''

'''onPostFinish'''

'''onPollStarting'''

==Client==
'''onClientMapStarting'''

'''onClientPlayerFinish'''

'''onClientPlayerOutOfTime'''

'''onClientMapStopping'''

'''onClientScreenFadedOut'''

'''onClientScreenFadedIn'''

==Events for version 0.8.3 in detail==
===onPlayerReachCheckpoint===
====Parameters====
<syntaxhighlight lang="lua">int checkpoint</syntaxhighlight>
*'''checkpoint:''' the number of the checkpoint the player went through. The first checkpoint has number 1.

====Source====
The source is the player that reached the checkpoint.

===onPlayerPickUpRacePickup===
====Parameters====
<syntaxhighlight lang="lua">int/string pickupID</syntaxhighlight>
*'''pickupID:''' the number of the pickup in case of MTA:Race syntax (starting at 1), or the "id" attribute of the pickup in case of DM syntax.

====Source====
The source is the player that picked up the pickup.

==Element data==
These element data are set on each player:
*'''Race rank:''' the current position of the player in the race. 1 = first, 2 = second etc. Updated on a 1 second interval.
*'''race.checkpoint:''' the number of the checkpoint the player is ''heading for''. When the player spawns this number is 1, after he passed the first checkpoint it's 2, etc.
*'''race.finished:''' ''true'' if the player has finished, ''false'' if he's still racing.

GetVehiclePanelState

2008-09-23T06:55:01Z

Norby89: /* Example */

__NOTOC__
{{Needs Checking|A list of panels would be nice and a more specific explanation on what the function returns --[[User:Norby89|Norby89]] 12:30, 26 August 2007 (CDT)}}
{{Server client function}}
This function returns the current state of a specifed panel on the vehicle. A vehicle can have up to 7 panels.

==Syntax==
<syntaxhighlight lang="lua">
int getVehiclePanelState ( vehicle thevehicle, int panel )
</syntaxhighlight>

==Required Arguments==
*'''theVehicle:''' The [[vehicle]] that you wish to know the panel state of.
*'''panel:''' An ''integer'' ranging from 0 to 6.

==Returns==
Returns an [[int]] indicating the state of the specified the panel. This value can be:

NEEDS UPDATING

==Example==
This function creates an admiral and outputs every panel's state in the chatbox.
<syntaxhighlight lang="lua">local admiral = createVehicle ( 445, 0, 0, 10 )

for i=0, 6 do
local panel = getVehiclePanelState ( admiral, i )
outputChatBox ( panel )
end
</syntaxhighlight>

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

IsGarageOpen

2008-09-19T12:37:21Z

Norby89: /* Example */

__NOTOC__
{{Server client function}}
This function checks whether or not a specific garage door is open.

==Syntax==
<syntaxhighlight lang="lua">
bool isGarageOpen ( int garageID )
</syntaxhighlight>

===Required Arguments===
*'''garageID:''' The [[Garage|garage ID]] that represents the garage door that is being checked.

===Returns===
Returns ''true'' if the garage is open, ''false'' if it is closed or an invalid garage ID was given.

==Example==
<section name="Server" class="server" show="true">
This example opens a garage door when a player enters a collision shape near it, and closes it when they leave:
<syntaxhighlight lang="lua">
GARAGE_ID = 25

-- create a collision shape and attach event handlers to it when the resource starts
addEventHandler("onResourceStart", getResourceRootElement(getThisResource()),
function (resource)
local garageCube = createColCube(1337, 194, 28, 6, 10, 4)
addEventHandler("onColShapeHit", garageCube, onGarageCubeHit)
addEventHandler("onColShapeLeave", garageCube, onGarageCubeLeave)
end)

-- open the door when someone enters the garage's collision shape
function onGarageCubeHit(hitElement, matchingDimension)
if (getElementType(hitElement) == "player") then
-- check to make sure the door is closed
if (not isGarageOpen(GARAGE_ID)) then
-- open the door
setGarageOpen(GARAGE_ID, true)
end
end
end

-- close the door when someone leaves the garage's collision shape
function onGarageCubeLeave(leaveElement, matchingDimension)
if (getElementType(leaveElement) == "player") then
-- check to make sure the door is open
if (isGarageOpen(GARAGE_ID)) then
-- close the door
setGarageOpen(GARAGE_ID, false)
end
end
end
</syntaxhighlight>
</section>

==See Also==
{{World functions}}
[[Category:Needs_More_Examples]]

SetGarageOpen

2008-09-19T12:37:04Z

Norby89: /* Example */

__NOTOC__
{{Server client function}}
This function opens or closes the specified garage door in the world.

==Syntax==
<syntaxhighlight lang="lua">
bool setGarageOpen ( int garageID, bool open )
</syntaxhighlight>

===Required Arguments===
*'''garageID:''' The [[Garage|garage ID]] that represents the garage door being opened or closed.
*'''isOpen:''' A boolean indicating whether or not to open the door.

===Returns===
Returns ''true'' if successful, ''false'' if an invalid garage id was given.

==Example==
<section name="Server" class="server" show="true">
This example opens a garage door when a player enters a collision shape near it, and closes it when they leave:
<syntaxhighlight lang="lua">
GARAGE_ID = 25

-- create a collision shape and attach event handlers to it when the resource starts
addEventHandler("onResourceStart", getResourceRootElement(getThisResource()),
function (resource)
local garageCube = createColCube(1337, 194, 28, 6, 10, 4)
addEventHandler("onColShapeHit", garageCube, onGarageCubeHit)
addEventHandler("onColShapeLeave", garageCube, onGarageCubeLeave)
end)

-- open the door when someone enters the garage's collision shape
function onGarageCubeHit(hitElement, matchingDimension)
if (getElementType(hitElement) == "player") then
-- check to make sure the door is closed
if (not isGarageOpen(GARAGE_ID)) then
-- open the door
setGarageOpen(GARAGE_ID, true)
end
end
end

-- close the door when someone leaves the garage's collision shape
function onGarageCubeLeave(leaveElement, matchingDimension)
if (getElementType(leaveElement) == "player") then
-- check to make sure the door is open
if (isGarageOpen(GARAGE_ID)) then
-- close the door
setGarageOpen(GARAGE_ID, false)
end
end
end
</syntaxhighlight>
</section>

==See Also==
{{World functions}}
[[Category:Needs_More_Examples]]

Template:Client XML functions

2008-04-06T11:18:01Z

Norby89:

*[[xmlCopyFile]]
*[[xmlCreateFile]]
*[[xmlCreateSubNode]]
*[[xmlDestroyNode]]
*[[xmlFindSubNode]]
*[[xmlLoadFile]]
*[[xmlNodeGetAttribute]]
*[[xmlNodeGetValue]]
*[[xmlNodeSetAttribute]]
*[[xmlNodeSetValue]]
*[[xmlSaveFile]]
*[[xmlUnloadFile]]
{{New feature|3|DP3|
*[[xmlNodeGetChildren ]]
*[[xmlNodeGetParent ]]
}}

Template:XML functions

2008-04-06T11:17:34Z

Norby89:

XmlNodeGetChildren

2008-04-06T11:17:09Z

Norby89:

__NOTOC__
{{Server client function}}
This function returns a single child or all the children of a particular XML node.

==Syntax==
<syntaxhighlight lang="lua">xmlnode/table xmlNodeGetChildren( xmlnode parent, [ int index ])</syntaxhighlight>

===Required Arguments===
* '''parent''': This is an [[xmlnode]] that you want to find the children under.

===Optional Arguments===
{{OptionalArg}}
* '''index''': This is the index of the node you wish to find. For example, to find the 5th subnode, you would use 4 as the index value. To find the first occurence, use 0. If this is not set, it will return a list of all children.

===Returns===
If index isn't specified, it returns a list of all children. Returns an [[xmlnode]] object if index was set and a node was found, otherwise it returns false.

==Example==
<section name="Server" class="server" show="true">
If you wanted to find the 'instructions' node in a map file like this:
<syntaxhighlight lang="xml">
<map version="2.0">
<options>
<instructions>Start at the begining and keep going until the end!</instructions>
</options>
</map>
</syntaxhighlight>

You could use the following code:
<syntaxhighlight lang="lua">
maproot = getLoadedMapXMLRoot ();
optionsnode = xmlNodeGetChildren( maproot, 0 ); -- In this case it would find the options sub node as the first under the 'map' node
</syntaxhighlight>

</section>

==See Also==
{{XML functions}}

XmlNodeGetSubNodes

2008-04-06T11:13:06Z

Norby89: XmlNodeGetSubNodes moved to XmlNodeGetChildren

#REDIRECT [[XmlNodeGetChildren]]

XmlNodeGetChildren

2008-04-06T11:13:06Z

Norby89: XmlNodeGetSubNodes moved to XmlNodeGetChildren

__NOTOC__
{{Server client function}}
This function returns a single sub node or a list of sub nodes of a particular XML node.

==Syntax==
<syntaxhighlight lang="lua">xmlnode/table xmlNodeGetChildren( xmlnode parent, [ int index ])</syntaxhighlight>

===Required Arguments===
* '''parent''': This is an [[xmlnode]] that you want to find the children under.

===Optional Arguments===
{{OptionalArg}}
* '''index''': This is the index of the node you wish to find. For example, to find the 5th subnode, you would use 4 as the index value. To find the first occurence, use 0. If this is not set, it will return a list of all children.

===Returns===
If index isn't specified, it returns a list of all children. Returns an [[xmlnode]] object if index was set and a node was found, otherwise it returns false.

==Example==
<section name="Server" class="server" show="true">
If you wanted to find the 'instructions' node in a map file like this:
<syntaxhighlight lang="xml">
<map version="2.0">
<options>
<instructions>Start at the begining and keep going until the end!</instructions>
</options>
</map>
</syntaxhighlight>

You could use the following code:
<syntaxhighlight lang="lua">
maproot = getLoadedMapXMLRoot ();
optionsnode = xmlNodeGetChildren( maproot, 0 ); -- In this case it would find the options sub node as the first under the 'map' node
</syntaxhighlight>

</section>

==See Also==
{{XML functions}}

XmlNodeGetChildren

2008-04-06T11:11:37Z

Norby89:

AddCommandHandler

2008-04-01T13:29:53Z

Norby89:

__NOTOC__
{{Server client function}}
{{Note_box|It is strongly advised that you do not use the same name for your handler function as the command name, as this can lead to confusion if multiple handler functions are used. Use a name that describes your handler's purpose more specifically.}}
This function will attach a scripting function (handler) to a console command, so that whenever a player or administrator uses the command the function is called.

Multiple command handlers can be attached to a single command, and they will be called in the order that the handlers were attached. Equally, multiple commands can be handled by a single function, and the ''commandName'' parameter used to decide the course of action.

For users, a command is in the format:

''commandName'' ''argument1'' ''argument2''

This can be triggered from the player's console or directly from the chat box by prefixing the message with a forward slash (''/''). For server side handlers, the server admin is also able to trigger these directly from the server's console in the same way as they are triggered from a player's console.

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction, [bool restricted = false] )
</syntaxhighlight>

===Required Arguments===
*'''commandName:''' This is the name of the command you wish to attach a handler to. This is what must be typed into the console to trigger the function.
*'''handlerFunction:''' This is the function that you want the command to trigger, which has to be defined before you add the handler. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command (see below). These are all optional.
===Optional Arguments===
{{OptionalArg}}
*'''restricted:''' Specify whether or not this command should be restricted by default. Use this on commands that should be inaccessible to everyone as default except special users specified in the ACL (Access Control List). This is to make sure admin commands such as ie. 'punish' won't be available to everyone if a server administrator forgets masking it in ACL. This argument defaults to false if nothing is specified.
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction )
</syntaxhighlight>

===Required Arguments===
*'''commandName:''' This is the name of the command you wish to attach a handler to. This is what must be typed into the console to trigger the function.
*'''handlerFunction:''' This is the function that you want the command to trigger, which has to be defined before you add the handler. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command (see below). These are all optional.
</section>

====Handler function parameters====
These are the parameters for the handler function that is called when the command is used.
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">player playerSource, string commandName, [string arg1, string arg2, ...] </syntaxhighlight>

* '''playerSource:''' The player who triggered the command. If not triggered by a player (e.g. by admin), this will be ''false''.
* '''commandName:''' The name of the command triggered. This is useful if multiple commands go through one function.
* '''arg1, arg2, ...:''' Each word after command name in the original command is passed here in a seperate variable. If there is no value for an argument, its variable will contain [[nil]]. You can deal with a variable number of arguments using the vararg expression, as shown in '''Example 3''' below.
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua"> string commandName, [string arg1, string arg2, ...] </syntaxhighlight>
* '''commandName:''' The name of the command triggered. This is useful if multiple commands go through one function.
* '''arg1, arg2, ...:''' Each word after command name in the original command is passed here in a seperate variable. If there is no value for an argument, its variable will contain [[nil]]. You can deal with a variable number of arguments using the vararg expression, as shown in '''Example 3''' below.
</section>

===Returns===
Returns ''true'' if the command handler was added successfully, ''false'' otherwise.

==Example==
<section name="Server" class="server">
'''Example 1:''' This example defines a command handler for the command ''createmarker''. This will create a red marker at the position of the player player who uses it.
<syntaxhighlight lang="lua">
-- Define our function that will handle this command
function consoleCreateMarker ( playerSource )
-- If a player triggered it (rather than the admin) then
if ( playerSource ) then
-- Get that player's position
local x, y, z = getElementPosition ( playerSource )
-- Create a size 2, red checkpoint marker at their position
createMarker ( x, y, z, "checkpoint", 2, 255, 0, 0, 255 )
-- Output it in his chat box
outputChatBox ( "You got a red marker", playerSource )
end
end
-- Attach the 'consoleCreateMarker' function to the "createmarker" command
addCommandHandler ( "createmarker", consoleCreateMarker )
</syntaxhighlight>

'''Example 2:''' A simple health setting command. If a player types ''/sethealth X'' in the chatbox his health will be set to X. Note that the function [[setElementHealth]] is used rather than something like "setPlayerHealth". This function is more generic and can also be used to set the health of vehicles.
<syntaxhighlight lang="lua">
function consoleSetHealth(playerSource, commandName, health)
setElementHealth(playerSource, tonumber(health))
end
addCommandHandler("sethealth", consoleSetHealth)
</syntaxhighlight>

'''Example 3:''' This example implements a ''set_vehicle_color'' command.
<syntaxhighlight lang="lua">
-- Define our function that will handle this command
function consoleSetVehicleColor ( playerSource, commandName, col1, col2, col3, col4 )
-- If a player triggered this in-game
if ( playerSource ) then
-- Get the player's vehicle
local playerVehicle = getPlayerOccupiedVehicle ( playerSource )
-- If the player is in a vehicle and we've got at least 1 parameter
if ( playerVehicle and col1 ) then
-- Get the vehicle's existing color and use it if fewer than 4 arguments were passed
local exCol1, exCol2, exCol3, exCol4 = getVehicleColor ( playerVehicle )

if not col2 then col2 = exCol2 end
if not col3 then col3 = exCol3 end
if not col4 then col4 = exCol4 end

-- Set the vehicle's color
setVehicleColor ( playerVehicle, col1, col2, col3, col4 )
else
-- If we didn't get at least 1 parameter or the player doesn't have a vehicle, display some help text
outputConsole ( "This function will set your current vehicle's colors. A vehicle can have up to 4 colors.", playerSource )
outputConsole ( "Syntax: set_vehicle_color color1 [ color2 color3 color4 ]", playerSource )
outputConsole ( "You must be in a vehicle to use this function.", playerSource )
end
end
end
-- Attach the 'consoleSetVehicleColor' function to the "set_vehicle_color" command
addCommandHandler ( "set_vehicle_color", consoleSetVehicleColor )
</syntaxhighlight>

'''Example 4:''' This example makes use of Lua's vararg expression to implement a ''check_parameters'' command to count the number of parameters passed, merge them all into a single string and output it. This is also shows you how you can use table.concat to merge all the passed arguments. This is particularly useful when you want to read in a sentence of text passed from the user.
<syntaxhighlight lang="lua">
-- Define our function that will handle this command (which can accept a variable number of arguments after commandName)
function consoleCheckParameters ( playerSource, commandName, ... )
-- If a player, not an admin, triggered it,
if playerSource then
-- Pack all extra arguments passed in a table
local parametersTable = {...}
-- Get the number of arguments in that table
local parameterCount = #parametersTable
-- Output it to the player's chatbox
outputChatBox ( "Number of parameters: " .. parameterCount, playerSource )
-- Join them together in a single comma-separated string
local stringWithAllParameters = table.concat( parametersTable, ", " )
-- Output this parameter list to the player's chatbox
outputChatBox ( "Parameters passed: " .. stringWithAllParameters, playerSource )
end
end
-- Attach the 'consoleCheckParameters' function to the "check_parameters" command
addCommandHandler ( "check_parameters", consoleCheckParameters )
</syntaxhighlight>
</section>
<section name="Client" class="client">
'''Example 1:''' This creates a GUI window and allows a player to change its alpha (transparency) value with a command. Note that, in a clientside script, the player using the command is not passed as a parameter to the handler function, since it is always the local player.

<syntaxhighlight lang="lua">--Create a window
myWindow = guiCreateWindow ( 0.30, 0.10, 0.5, 0.60, "GUI window title", true )

--Add a command handler to change the alpha of the GUI window. Usage example: 'alpha 0.15'
function changeAlpha ( commandName, alphaAmount )
-- All command parameters are strings, so we'll convert the value to a number first
alphaAmount = tonumber(alphaAmount)
guiSetAlpha ( myGridList, alphaAmount )
end
addCommandHandler ( "alpha", changeAlpha )
</syntaxhighlight>
</section>

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

TriggerServerEvent

2008-03-01T17:59:10Z

Norby89: /* See Also */

__NOTOC__
{{Client function}}
This function triggers an event previously registered on the server. This is the primary means of passing information between the client and the server. Servers have a similar [[triggerClientEvent]] function that can do the reverse. You can treat this function as if it was an asynchronous function call, using [[triggerClientEvent]] to pass back any returned information if necessary.

Almost any data types can be passed as expected, including [[element]]s and complex nested [[table]]s. Non-element MTA data types like xmlNodes or resource pointers will not be able to be passed as they do not necessarily have a valid representation on the client.

Events are sent reliably, so the server will receive them, but there may be (but shouldn't be) a significant delay before they are received. You should take this into account when using them.

Keep in mind the bandwidth issues when using events - don't pass a large list of arguments unless you really need to. It is marginally more efficient to pass one large event than two smaller ones.

==Syntax==
<syntaxhighlight lang="lua">
bool triggerServerEvent ( string event, 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 ''source'' of the event. This could be another player, or if this isn't relevant, use the root element.

===Optional Arguments===
*'''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.

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

==Example==
This example shows how you can pass a simple "Hello World" message from the client to the server using an event.

'''Server:'''
<syntaxhighlight lang="lua">
function greetingHandler ( message )
outputChatBox ( "The client says: " .. message )
end
addEvent("onGreeting", true)
addEventHandler("onGreeting", getRootElement(), greetingHandler)
</syntaxhighlight>

'''Client:'''
<syntaxhighlight lang="lua">
function greetingCommand ( source, commandName )
triggerServerEvent ( "onGreeting", getLocalPlayer(), "Hello World!" )
--getLocalPlayer instead of getRootElement makes the client player the 'source' on the server function, eliminating the need for an additional player argument to be transferred.
end
addCommandHandler ( "greet", greetingCommand )
</syntaxhighlight>

When the command "greet" is executed (by typing it in the server console or the player's console), the clients ''greetingCommand'' function is called. This triggers the server-side event ''onGreeting'' with the string ''"Hello World!"''. This event is then handled by the ''greetingHandler'' function server-side which then displays the message.

==See Also==
{{Client_event_functions}}

XmlNodeGetChildren

2008-02-28T15:23:32Z

Norby89:

__NOTOC__
{{Server client function}}
This function returns a single sub node or a list of sub nodes of a particular XML node.

==Syntax==
<syntaxhighlight lang="lua">xmlnode/table xmlNodeGetSubNodes( xmlnode parent, [ int index ])</syntaxhighlight>

===Required Arguments===
* '''parent''': This is an [[xmlnode]] that you want to find the sub nodes under.

===Optional Arguments===
{{OptionalArg}}
* '''index''': This is the index of the node you wish to find. For example, to find the 5th subnode, you would use 4 as the index value. To find the first occurence, use 0. If this is not set, it will return a list of all sub nodes.

===Returns===
If index isn't specified, it returns a list of all sub nodes. Returns an [[xmlnode]] object if index was set and a node was found, otherwise it returns false.

==Example==
<section name="Server" class="server" show="true">
If you wanted to find the 'instructions' node in a map file like this:
<syntaxhighlight lang="xml">
<map version="2.0">
<options>
<instructions>Start at the begining and keep going until the end!</instructions>
</options>
</map>
</syntaxhighlight>

You could use the following code:
<syntaxhighlight lang="lua">
maproot = getLoadedMapXMLRoot ();
optionsnode = xmlNodeGetSubNodes( maproot, 0 ); -- In this case it would find the options sub node as the first under the 'map' node
</syntaxhighlight>

</section>

==See Also==
{{XML functions}}

AttachElementToElement

2007-12-31T09:35:29Z

Norby89: /* Optional Arguments */ no radians

{{Needs Checking|What kinds of elements can be attached together? --[[User:Jbeta|jbeta]]}}
__NOTOC__
{{Server client function}}
This function attaches one element to another, so that the first one follows the second whenever it moves.

This is not compatible with all elements. The following elements are compatible:
* [[Marker|Markers]]
* [[Blip|Blips]]
* [[Object|Objects]]
* [[Player|Players]]
* [[Vehicle|Vehicles]]

==Syntax==
<syntaxhighlight lang="lua">
bool attachElementToElement ( element theElement, element theAttachToElement, [ float xPosOffset, float yPosOffset, float zPosOffset, float xRotOffset, float yRotOffset, float zRotOffset ] )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element to be attached.
*'''theAttachToElement:''' The element to attach the first to.

===Optional Arguments===
{{OptionalArg}}
*'''xPosOffset:''' The x offset, if you want the elements to be a certain distance from one another (default 0).
*'''yPosOffset:''' The y offset (default 0).
*'''zPosOffset:''' The z offset (default 0).
*'''xRotOffset:''' The x offset (default 0).
*'''yRotOffset:''' The y offset (default 0).
*'''zRotOffset:''' The z offset (default 0).

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

==Example==
<section name="Server" class="server" show="true">
'''Example 1:''' This example attaches a marker to the player who steals the Mr. Whoopee:
<syntaxhighlight lang="lua">
-- create the vehicle
local vehicleMrWhoopee = createVehicle ( 423, 237.472 -54.225 1.518, 0, 354.488, 0 )

function onMrWhoopeeEnter ( thePlayer, seat, jackedPlayer )
outputChatBox ( getClientName ( thePlayer ) .. " stole the Whoopee!", getRootElement (), 255, 0, 0 )
-- create the marker to attach
local arrowMarker = createMarker ( 0, 0, 0, "arrow", .75, 255, 0, 0, 170 )
-- attach the marker to the player with a vertical offset of 2 units
attachElementToElement ( arrowMarker, thePlayer, 0, 0, 2 )
end

-- attach it to an event
addEventHandler ( "onVehicleEnter", vehicleMrWhoopee, onMrWhoopeeEnter )
</syntaxhighlight>
'''Example 2:''' This function adds a tank on top of a player (for extra defense):
<syntaxhighlight lang="lua">
function tankHat( source, commandName )
local x, y, z = getElementPosition( source ) --Get the players position
local tank = createVehicle( 432, x, y, z + 5 ) --Create a tank
attachElementToElement( tank, source, 0, 0, 5 ) --Attach the tank to the player.
end
addCommandHandler( "hat", tankHat )
</syntaxhighlight>
</section>
<section name="Client" class="client" show="false">
'''Example 3:''' This function adds a tank on top of a player (for extra defense), clientside. This means it will be invisible to other players.
<syntaxhighlight lang="lua">
function tankHat( commandName )
local x, y, z = getElementPosition( source ) --Get the players position
local tank = createVehicle( 432, x, y, z + 5 ) --Create a tank
attachElementToElement( tank, source, 0, 0, 5 ) --Attach the tank to the player.
end
addCommandHandler( "hat", tankHat )
</syntaxhighlight>
</section>

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

Element/Object

2007-12-27T12:48:52Z

Norby89: /* Optional Attributes */ changed radians to degrees

__NOTOC__
The object class represents static, 3-D models in the GTA world. Objects can only represent models created by the server, they cannot represent models that are part of the GTA's default landscape. Examples of objects include building models, roads, and terrain.

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

==XML syntax==
<syntaxhighlight lang="xml">
<object model="" posX="" posY="" posZ="" rotX="" rotY="" rotZ=""/>
</syntaxhighlight>

===Required Attributes===
* '''model''': The ID of the object being created. Since GTA has thousands of objects, these are hard to document on the wiki. Instead, they can be found using the object browser in the map editor.
* '''posX''': A float representing the X position of the object.
* '''posY''': A float representing the Y position of the object.
* '''posZ''': A float representing the Z position of the object.

===Optional Attributes===
* '''rotX''': A float representing the X rotation of the object in degrees.
* '''rotY''': A float representing the Y rotation of the object in degrees.
* '''rotZ''': A float representing the Z rotation of the object in degrees.

==Related scripting functions==
{{Object functions}}

OnColShapeLeave

2007-12-24T11:42:58Z

Norby89: /* Variables */

__NOTOC__
This event is triggered when a player leaves a collision shape.

==Syntax==
<syntaxhighlight lang="lua">
onColShapeLeave ( element leaveElement, bool matchingDimension )
</syntaxhighlight>

==Variables==
* The source of this event refers to the col object in which an element has left
*'''leaveElement''': The [[element]] that who exited the col shape.
*'''matchingDimension''': a boolean referring to whether the collision shape was in the same dimension as the element.

==Example==
This example kills the player whenever they leave a certain collision shape:
<syntaxhighlight lang="lua">
jailZone = createColCircle ( 1024, 1024, 15, 50 ) -- create a collision shape

-- call 'jailZoneLeave' whenever a player leaves the collision shape:
addEventHandler ( "onColShapeLeave", jailZone, "jailZoneLeave" )
function jailZoneLeave ( thePlayer )
killPlayer ( thePlayer ) -- kill the player
outputChatBox ( "You are not allowed to leave the jail!", thePlayer )
end
</syntaxhighlight>

==See Also==
{{Event_functions}}

OnColShapeLeave

2007-12-24T11:42:12Z

Norby89: /* Variables */

__NOTOC__
This event is triggered when a player leaves a collision shape.

==Syntax==
<syntaxhighlight lang="lua">
onColShapeLeave ( element leaveElement, bool matchingDimension )
</syntaxhighlight>

==Variables==
* The source of this event refers to the col object in which an element has left
*'''leaveElement''': The [[element]] that who exited the col shape.

==Example==
This example kills the player whenever they leave a certain collision shape:
<syntaxhighlight lang="lua">
jailZone = createColCircle ( 1024, 1024, 15, 50 ) -- create a collision shape

-- call 'jailZoneLeave' whenever a player leaves the collision shape:
addEventHandler ( "onColShapeLeave", jailZone, "jailZoneLeave" )
function jailZoneLeave ( thePlayer )
killPlayer ( thePlayer ) -- kill the player
outputChatBox ( "You are not allowed to leave the jail!", thePlayer )
end
</syntaxhighlight>

==See Also==
{{Event_functions}}

OnColShapeHit

2007-12-24T11:40:20Z

Norby89: /* Parameters */

__NOTOC__
This event is triggered when the player hits a [[colshape]].

==Syntax==
<syntaxhighlight lang="lua">
void onColShapeHit ( element hitElement, bool matchingDimension )
</syntaxhighlight>

==Parameters==
*The '''source''' of this event refers to the [[colshape]] which was hit by the element.
*'''hitElement''': the [[element]] that entered the colshape.
*'''matchingDimension''': a boolean referring to whether the hit collision shape was in the same dimension as the element.

==Example==
This example creates a hill area for a ''King of the hill'' gamemode. When a player enters or leaves the area, it's announced in the chatbox.
<syntaxhighlight lang="lua">
-- create our hill area for our gamemode
local hillArea = createColSquare ( -2171.0678710938, 678.17950439453, 0, 15, 15 )

-- add hill_Enter as a handler for when a player enters the hill area
addEventHandler ( "onColShapeHit", hillArea, "hill_Enter" )
function hill_Enter ( thePlayer, matchingDimension )
--announce to everyone that the player entered the hill
outputChatBox( getClientName(thePlayer).." entered the zone!", getRootElement(),255, 255, 109, )
end

-- add hill_Enter as a handler for when a player leaves the hill area
addEventHandler ( "onColShapeLeave", hillArea, "hill_Exit" )
function hill_Exit ( thePlayer, matchingDimension )
--check if the player is not dead
if isPlayerDead ( thePlayer ) ~= true then
--if he was alive, announce to everyone that the player has left the hill
outputChatBox ( getClientName(thePlayer).." left the zone!", getRootElement(), 255, 255, 109 )
end
end
</syntaxhighlight>

==See Also==
{{Event_functions}}

OnColShapeHit

2007-12-24T11:39:53Z

Norby89: /* Parameters */

__NOTOC__
This event is triggered when the player hits a [[colshape]].

==Syntax==
<syntaxhighlight lang="lua">
void onColShapeHit ( element hitElement, bool matchingDimension )
</syntaxhighlight>

==Parameters==
*The '''source''' of this event refers to the [[colshape]] which was hit by the player.
*'''hitElement''': the [[element]] that entered the colshape.
*'''matchingDimension''': a boolean referring to whether the hit collision shape was in the same dimension as the player.

==Example==
This example creates a hill area for a ''King of the hill'' gamemode. When a player enters or leaves the area, it's announced in the chatbox.
<syntaxhighlight lang="lua">
-- create our hill area for our gamemode
local hillArea = createColSquare ( -2171.0678710938, 678.17950439453, 0, 15, 15 )

-- add hill_Enter as a handler for when a player enters the hill area
addEventHandler ( "onColShapeHit", hillArea, "hill_Enter" )
function hill_Enter ( thePlayer, matchingDimension )
--announce to everyone that the player entered the hill
outputChatBox( getClientName(thePlayer).." entered the zone!", getRootElement(),255, 255, 109, )
end

-- add hill_Enter as a handler for when a player leaves the hill area
addEventHandler ( "onColShapeLeave", hillArea, "hill_Exit" )
function hill_Exit ( thePlayer, matchingDimension )
--check if the player is not dead
if isPlayerDead ( thePlayer ) ~= true then
--if he was alive, announce to everyone that the player has left the hill
outputChatBox ( getClientName(thePlayer).." left the zone!", getRootElement(), 255, 255, 109 )
end
end
</syntaxhighlight>

==See Also==
{{Event_functions}}

GetAttachedElements

2007-12-15T10:11:29Z

Norby89: /* Example */

{{Server client function}}
__NOTOC__
This function returns a table of all the elements attached to the specified element

==Syntax==
<syntaxhighlight lang="lua">
table getAttachedElements ( element theElement )
</syntaxhighlight>

===Required Arguments===
*'''theElement''': The [[element]] which you require the information from.

===Returns===
Returns a table of all the elements attached to the specified element.

==Example==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
-- Print a list of all the players attached to the specified element
local Inf = getElementByID ( "infernus1" )
local attachedElements = getAttachedElements ( Inf )
if ( attachedElements ) then -- if we got the table
local attachedElementsList = "none"
-- Loop through the table
for ElementKey, ElementValue in ipairs ( attachedElements ) do
-- add their name to the list
if ( getElementType ( ElementValue ) == "player" ) then
if ( attachedElementsList == "none" ) then
attachedElementsList = getClientName ( ElementValue )
else
attachedElementsList = attachedElementsList .. ", " .. getClientName ( ElementValue )
end
end
end
outputConsole ( "Players attached to the infernus: " .. attachedElementsList )
end
</syntaxhighlight>
</section>

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

AttachElementToElement

2007-12-01T09:47:04Z

Norby89: /* Optional Arguments */

{{Needs Checking|What kinds of elements can be attached together? --[[User:Jbeta|jbeta]]}}
__NOTOC__
{{Server client function}}
This function attaches one element to another, so that the first one follows the second whenever it moves.

This is not compatible with all elements. The following elements are compatible:
* [[Marker|Markers]]
* [[Blip|Blips]]
* [[Object|Objects]]
* [[Player|Players]]
* [[Vehicle|Vehicles]]

==Syntax==
<syntaxhighlight lang="lua">
bool attachElementToElement ( element theElement, element theAttachToElement, [ float xPosOffset, float yPosOffset, float zPosOffset, float xRotOffset, float yRotOffset, float zRotOffset ] )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element to be attached.
*'''theAttachToElement:''' The element to attach the first to.

===Optional Arguments===
{{OptionalArg}}
*'''xPosOffset:''' The x offset, if you want the elements to be a certain distance from one another (default 0).
*'''yPosOffset:''' The y offset (default 0).
*'''zPosOffset:''' The z offset (default 0).
*'''xRotOffset:''' The x offset (default 0).
*'''yRotOffset:''' The y offset (default 0).
*'''zRotOffset:''' The z offset (default 0).
Rotations are in radians.

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

==Example==
<section name="Server" class="server" show="true">
'''Example 1:''' This example attaches a marker to the player who steals the Mr. Whoopee:
<syntaxhighlight lang="lua">
-- create the vehicle
local vehicleMrWhoopee = createVehicle ( 423, 237.472 -54.225 1.518, 0, 354.488, 0 )

function onMrWhoopeeEnter ( thePlayer, seat, jackedPlayer )
outputChatBox ( getClientName ( thePlayer ) .. " stole the Whoopee!", getRootElement (), 255, 0, 0 )
-- create the marker to attach
local arrowMarker = createMarker ( 0, 0, 0, "arrow", .75, 255, 0, 0, 170 )
-- attach the marker to the player with a vertical offset of 2 units
attachElementToElement ( arrowMarker, thePlayer, 0, 0, 2 )
end

-- attach it to an event
addEventHandler ( "onVehicleEnter", vehicleMrWhoopee, onMrWhoopeeEnter )
</syntaxhighlight>
'''Example 2:''' This function adds a tank on top of a player (for extra defense):
<syntaxhighlight lang="lua">
function tankHat( source, commandName )
local x, y, z = getElementPosition( source ) --Get the players position
local tank = createVehicle( 432, x, y, z + 5 ) --Create a tank
attachElementToElement( tank, source, 0, 0, 5 ) --Attach the tank to the player.
end
addCommandHandler( "hat", tankHat )
</syntaxhighlight>
</section>
<section name="Client" class="client" show="false">
'''Example 3:''' This function adds a tank on top of a player (for extra defense), clientside. This means it will be invisible to other players.
<syntaxhighlight lang="lua">
function tankHat( commandName )
local x, y, z = getElementPosition( source ) --Get the players position
local tank = createVehicle( 432, x, y, z + 5 ) --Create a tank
attachElementToElement( tank, source, 0, 0, 5 ) --Attach the tank to the player.
end
addCommandHandler( "hat", tankHat )
</syntaxhighlight>
</section>

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

CreateElement

2007-11-26T16:35:49Z

Norby89: /* Example */ minor fix

__NOTOC__
{{Server client function}}
This function is used to create a new dummy element in the [[element tree]] which do not necessarily represent an entity within the San Andreas world. A common use for this function is for creating custom elements, such as a Flag or a Base.

Elements created using this function are placed in the element tree with their parent as the 'dynamic' map element.

==Syntax==
<syntaxhighlight lang="lua">
element createElement ( string elementType, [ string elementID ] )
</syntaxhighlight>

===Required Arguments===
*'''elementType:''' The type of element being created.

===Optional Arguments===
*'''elementID:''' The ID of the element being created.

===Returns===
Returns the element if it was successfully created. Returns ''false'' if the arguments are wrong.

==Example==
This example creates a "flag" element, named "blue", which will be at the resource's dynamic map.

<syntaxhighlight lang="lua">
blueTeamFlag = createElement( "flag", "blue" )
</syntaxhighlight>

Except for it being placed in a different map root, that line will have the same effect as having this in a .map file:
<syntaxhighlight lang="xml">
<flag id="blue" />
</syntaxhighlight>

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

GetPlayerRotation

2007-10-02T16:03:52Z

Norby89:

__NOTOC__
{{Server client function}}
This function returns the current rotation (in degrees) of a player around the Z axis. It's used with on-foot players: use [[getVehicleRotation]] on the occupied [[vehicle]] if the player is in one.

==Syntax==
<syntaxhighlight lang="lua">
float getPlayerRotation ( player thePlayer )
</syntaxhighlight>

===Required Arguments===
*'''thePlayer''': the [[player]] whose rotation you want to retrieve.

===Returns===
Returns a ''float'' containing the player's rotation, or ''false'' if an invalid player (or one in a vehicle) was passed.

==Example==
This code adds a ''getrot'' command to get the player's current rotation.
<syntaxhighlight lang="lua">
function outputPlayerRotation ( sourcePlayer )
-- if the command was triggered by an ingame player
if ( sourcePlayer ) then
-- if he is in a vehicle
if isPlayerInVehicle ( sourcePlayer ) then
-- store the vehicle element
local playerVehicle = getPlayerOccupiedVehicle ( sourcePlayer )
-- and output its rotation
local x,y,z = getVehicleRotation ( playerVehicle )
outputChatBox ( "Your vehicle's rotation is: " .. z, sourcePlayer )
-- if he is on foot
else
-- output the player's rotation
outputChatBox ( "Your rotation is: " .. getPlayerRotation ( sourcePlayer ), sourcePlayer )
end
end
end

-- register outputPlayerRotation as a handler for the getrot command
addCommandHandler ( "getrot", outputPlayerRotation )
</syntaxhighlight>

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

GetPlayerTask

2007-09-05T14:43:19Z

Norby89: /* Required Arguments */

{{Client function}}
__NOTOC__
This function is used to get the name of the current task of a certain type for a player.

==Syntax==
<syntaxhighlight lang="lua">
string getPlayerTask ( player thePlayer, string priority, int taskType, [int index = 0] )
</syntaxhighlight>

===Required Arguments===
*'''thePlayer''': The [[player]] whose task you want to retrieve.
*'''priority''': A string determining which set of tasks you want to retrieve it from. This must be either "priority" or "secondary".
*'''taskType''': An integer value representing the task type (or slot) you want to get the task from. Types can be:
**'''PRIMARY TASKS'''
***'''0:''' TASK_PRIORITY_PHYSICAL_RESPONSE
***'''1:''' TASK_PRIORITY_EVENT_RESPONSE_TEMP
***'''2:''' TASK_PRIORITY_EVENT_RESPONSE_NONTEMP
***'''3:''' TASK_PRIORITY_PRIMARY
***'''4:''' TASK_PRIORITY_DEFAULT
**'''SECONDARY TASKS'''
***'''0:''' TASK_SECONDARY_ATTACK
***'''1:''' TASK_SECONDARY_DUCK
***'''2:''' TASK_SECONDARY_SAY
***'''3:''' TASK_SECONDARY_FACIAL_COMPLEX
***'''4:''' TASK_SECONDARY_PARTIAL_ANIM
***'''5:''' TASK_SECONDARY_IK

===Optional Arguments===
*'''index''': An integer value representing how many sub tasks to go through. -1 to get the simplest task, 0 to get the most complex task.

===Returns===
Returns a string containing the name of a task. See [[list of player tasks]] for valid strings. Returns ''false'' if invalid arguments are specified or if there is no task of the type or index specified.

==Example==
<section name="Client" class="client" show="true">
This example prints the name of a player's task to the chat when they use the "task" command in the console.
<syntaxhighlight lang="lua">
function myTask ( commandName, priority, taskType )
task = getPlayerTask ( source, priority, tonumber(taskType) )
taskName = "none"
if ( task ) then
taskName = task
end
outputChatBox ( getClientName ( source ) .. "'s " .. priority .. "(" .. taskType .. ") task is: " .. taskName )
end
addCommandHandler ( "task", myTask )
</syntaxhighlight>
</section>

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

GetPlayerTask

2007-09-05T14:41:54Z

Norby89: /* Required Arguments */

{{Client function}}
__NOTOC__
This function is used to get the name of the current task of a certain type for a player.

==Syntax==
<syntaxhighlight lang="lua">
string getPlayerTask ( player thePlayer, string priority, int taskType, [int index = 0] )
</syntaxhighlight>

===Required Arguments===
*'''thePlayer''': The [[player]] whose task you want to retrieve.
*'''priority''': A string determining which set of tasks you want to retrieve it from. This must be either "primary" or "secondary".
*'''taskType''': An integer value representing the task type (or slot) you want to get the task from. Types can be:
**'''PRIMARY TASKS'''
***'''0:''' TASK_PRIORITY_PHYSICAL_RESPONSE
***'''1:''' TASK_PRIORITY_EVENT_RESPONSE_TEMP
***'''2:''' TASK_PRIORITY_EVENT_RESPONSE_NONTEMP
***'''3:''' TASK_PRIORITY_PRIMARY
***'''4:''' TASK_PRIORITY_DEFAULT
**'''SECONDARY TASKS'''
***'''0:''' TASK_SECONDARY_ATTACK
***'''1:''' TASK_SECONDARY_DUCK
***'''2:''' TASK_SECONDARY_SAY
***'''3:''' TASK_SECONDARY_FACIAL_COMPLEX
***'''4:''' TASK_SECONDARY_PARTIAL_ANIM
***'''5:''' TASK_SECONDARY_IK

===Optional Arguments===
*'''index''': An integer value representing how many sub tasks to go through. -1 to get the simplest task, 0 to get the most complex task.

===Returns===
Returns a string containing the name of a task. See [[list of player tasks]] for valid strings. Returns ''false'' if invalid arguments are specified or if there is no task of the type or index specified.

==Example==
<section name="Client" class="client" show="true">
This example prints the name of a player's task to the chat when they use the "task" command in the console.
<syntaxhighlight lang="lua">
function myTask ( commandName, priority, taskType )
task = getPlayerTask ( source, priority, tonumber(taskType) )
taskName = "none"
if ( task ) then
taskName = task
end
outputChatBox ( getClientName ( source ) .. "'s " .. priority .. "(" .. taskType .. ") task is: " .. taskName )
end
addCommandHandler ( "task", myTask )
</syntaxhighlight>
</section>

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

SetVehicleTurnVelocity

2007-08-27T17:08:18Z

Norby89: /* Required Arguments */

{{Needs_Checking|We need a min-max values allowed or a recommended min-max/relevant range?
--[[User:Ransom|Ransom]] 02:46, 11 April 2007 (CDT)}}

[[Category:Incomplete]]

__NOTOC__
{{Server client function}}
Sets the angular velocity of a vehicle. Basically applies a spin to it.

==Syntax==
<syntaxhighlight lang="lua">
bool setVehicleTurnVelocity ( vehicle theVehicle, float rx, float ry, float rz )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' The [[vehicle]] to apply the spin to.
*'''rx:''' velocity around the X axis
*'''ry:''' velocity around the Y axis
*'''rz:''' velocity around the Z axis

===Returns===
Returns ''true'' if it was succesful, ''false'' otherwise.

==Example==
<syntaxhighlight lang="lua">
function onColShapeHit ( thePlayer, matchingDimension )
-- When a player hits the collision shape, check if he's in a vehicle
local playerVehicle = getPlayerOccupiedVehicle ( thePlayer )
if playerVehicle ~= false then
-- If so, give it a spin
setVehicleTurnVelocity ( playerVehicle, 0, 0, 20 )
end
end
addEventHandler ( "onColShapeHit", getRootElement ( ), onColShapeHit )
</syntaxhighlight>

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

SetVehicleTurnVelocity

2007-08-27T17:07:33Z

Norby89: /* Returns */

{{Needs_Checking|We need a min-max values allowed or a recommended min-max/relevant range?
--[[User:Ransom|Ransom]] 02:46, 11 April 2007 (CDT)}}

[[Category:Incomplete]]

__NOTOC__
{{Server client function}}
Sets the angular velocity of a vehicle. Basically applies a spin to it.

==Syntax==
<syntaxhighlight lang="lua">
bool setVehicleTurnVelocity ( vehicle theVehicle, float rx, float ry, float rz )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' vehicle to apply the spin to
*'''rx:''' velocity around the X axis
*'''ry:''' velocity around the Y axis
*'''rz:''' velocity around the Z axis

===Returns===
Returns ''true'' if it was succesful, ''false'' otherwise.

==Example==
<syntaxhighlight lang="lua">
function onColShapeHit ( thePlayer, matchingDimension )
-- When a player hits the collision shape, check if he's in a vehicle
local playerVehicle = getPlayerOccupiedVehicle ( thePlayer )
if playerVehicle ~= false then
-- If so, give it a spin
setVehicleTurnVelocity ( playerVehicle, 0, 0, 20 )
end
end
addEventHandler ( "onColShapeHit", getRootElement ( ), onColShapeHit )
</syntaxhighlight>

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

SetVehicleTurnVelocity

2007-08-27T17:06:50Z

Norby89: /* See Also */

{{Needs_Checking|We need a min-max values allowed or a recommended min-max/relevant range?
--[[User:Ransom|Ransom]] 02:46, 11 April 2007 (CDT)}}

[[Category:Incomplete]]

__NOTOC__
{{Server client function}}
Sets the angular velocity of a vehicle. Basically applies a spin to it.

==Syntax==
<syntaxhighlight lang="lua">
bool setVehicleTurnVelocity ( vehicle theVehicle, float rx, float ry, float rz )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' vehicle to apply the spin to
*'''rx:''' velocity around the X axis
*'''ry:''' velocity around the Y axis
*'''rz:''' velocity around the Z axis

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

==Example==
<syntaxhighlight lang="lua">
function onColShapeHit ( thePlayer, matchingDimension )
-- When a player hits the collision shape, check if he's in a vehicle
local playerVehicle = getPlayerOccupiedVehicle ( thePlayer )
if playerVehicle ~= false then
-- If so, give it a spin
setVehicleTurnVelocity ( playerVehicle, 0, 0, 20 )
end
end
addEventHandler ( "onColShapeHit", getRootElement ( ), onColShapeHit )
</syntaxhighlight>

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

GetVehicleTurnVelocity

2007-08-27T17:03:27Z

Norby89:

{{Server client function}}
{{Needs Checking|can somebody try this and see if it works properly? I always got random numbers even when the vehicle was completely still --[[User:Norby89|Norby89]] 12:03, 27 August 2007 (CDT)}}
__NOTOC__
This function is used to retrieve a vehicle's turning velocity for each axis.

==Syntax==
<syntaxhighlight lang="lua">
float float float getVehicleTurnVelocity ( vehicle theVehicle )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' The [[vehicle]] you wish to get the turning velocities of.

===Returns===
Returns 3 ''floats'' that represent the vehicle's turning velocity on the x, y and z axis or ''false'' if wrong arguments were passed.

==Example==

This page does not currently have an example
<syntaxhighlight lang="lua">
--enter an example here
</syntaxhighlight>

==See Also==

{{Vehicle functions}}
[[Category:Needs_Example]]

GetVehicleTurnVelocity

2007-08-27T16:54:22Z

Norby89:

{{Server client function}}
__NOTOC__
This function is used to retrieve a vehicle's turning velocity for each axis.

==Syntax==
<syntaxhighlight lang="lua">
float float float getVehicleTurnVelocity ( vehicle theVehicle )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' The [[vehicle]] you wish to get the turning velocities of.

===Returns===
Returns 3 ''floats'' that represent the vehicle's turning velocity on the x, y and z axis or ''false'' if wrong arguments were passed.

==Example==

This page does not currently have an example
<syntaxhighlight lang="lua">
--enter an example here
</syntaxhighlight>

==See Also==

{{Vehicle functions}}
[[Category:Needs_Example]]

GetVehicleTurnVelocity

2007-08-27T16:52:53Z

Norby89:

{{Server client function}}
__NOTOC__
This function is used to retrieve a vehicle's turning velocity for each axis.

==Syntax==
<syntaxhighlight lang="lua">
float float float getVehicleTurnVelocity ( vehicle theVehicle )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' The [[vehicle]] you wish to get the turning velocities of.

===Returns===
Returns 3 ''floats'' that represent the vehicle's turning velocity on the x, y and z axis.

==Example==

This page does not currently have an example
<syntaxhighlight lang="lua">
--enter an example here
</syntaxhighlight>

==See Also==

{{Vehicle Functions}}
[[Category:Needs_Example]]

GetVehiclePanelState

2007-08-27T11:15:43Z

Norby89: /* Required Arguments */

__NOTOC__
{{Needs Checking|A list of panels would be nice and a more specific explanation on what the function returns --[[User:Norby89|Norby89]] 12:30, 26 August 2007 (CDT)}}
{{Server client function}}
This function returns the current state of a specifed panel on the vehicle. A vehicle can have up to 7 panels.

==Syntax==
<syntaxhighlight lang="lua">
int getVehiclePanelState ( vehicle thevehicle, int panel )
</syntaxhighlight>

==Required Arguments==
*'''theVehicle:''' The [[vehicle]] that you wish to know the panel state of.
*'''panel:''' An ''integer'' ranging from 0 to 6.

==Returns==
Returns an [[int]] indicating the state of the specified the panel. This value can be:

NEEDS UPDATING

==Example==
This function creates an admiral and outputs every panel's state in the chatbox.
<syntaxhighlight lang="lua">local newcar = createVehicle ( 520, 1024, 1024, 1024 )
admiral = createVehicle ( 445, 0, 0, 10 )

...

for i=0, 6 do
local panel = getVehiclePanelState ( admiral, i )
outputChatBox ( panel )
end
</syntaxhighlight>

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

SetVehicleDoorState

2007-08-27T11:15:33Z

Norby89: /* Syntax */

__NOTOC__
{{Server client function}}
This function sets the damage state of a specified door on a vehicle.

==Syntax==
<section name="Server and Client" class="both" show="true">
<syntaxhighlight lang="lua">
setVehicleDoorState ( vehicle theVehicle, int door, int state )
</syntaxhighlight>

==Required Arguments==
*'''theVehicle:''' The [[vehicle]] that you wish to change the door state of.
*'''door:''' An integer between 0 and 5 specifying the door you want to change state of.
*'''state:''' An integer determining the new state of the door:
**'''0:''' intact
**'''1:''' swinging free
**'''2:''' bashed
**'''3:''' bashed and swinging free
**'''4:''' missing

==Returns==
Returns ''true'' if the door state was successfully set, ''false'' if invalid arguments, invalid door IDs or invalid state IDs are passed.
</section>

==Example==
<section name="Server and Client" class="both" show="true">
<syntaxhighlight lang="lua">
-- create a new vehicle
local newcar = createVehicle ( 520, 1024, 1024, 1024 )
-- break its front left door off
state = setVehicleDoorState ( newcar, 2, 4 )
</syntaxhighlight>
</section>

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

GetVehiclePanelState

2007-08-27T11:15:24Z

Norby89: /* Required Arguments */

__NOTOC__
{{Needs Checking|A list of panels would be nice and a more specific explanation on what the function returns --[[User:Norby89|Norby89]] 12:30, 26 August 2007 (CDT)}}
{{Server client function}}
This function returns the current state of a specifed panel on the vehicle. A vehicle can have up to 7 panels.

==Syntax==
<syntaxhighlight lang="lua">
int getVehiclePanelState ( vehicle thevehicle, int panel )
</syntaxhighlight>

==Required Arguments==
*'''theVehicle:''' The [[vehicle]] that you wish to know the panel state of.
*'''panel:''' An [[integer]] ranging from 0 to 6.

==Returns==
Returns an [[int]] indicating the state of the specified the panel. This value can be:

NEEDS UPDATING

==Example==
This function creates an admiral and outputs every panel's state in the chatbox.
<syntaxhighlight lang="lua">local newcar = createVehicle ( 520, 1024, 1024, 1024 )
admiral = createVehicle ( 445, 0, 0, 10 )

...

for i=0, 6 do
local panel = getVehiclePanelState ( admiral, i )
outputChatBox ( panel )
end
</syntaxhighlight>

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

GetVehiclePanelState

2007-08-27T11:13:03Z

Norby89: /* Required Arguments */

__NOTOC__
{{Needs Checking|A list of panels would be nice and a more specific explanation on what the function returns --[[User:Norby89|Norby89]] 12:30, 26 August 2007 (CDT)}}
{{Server client function}}
This function returns the current state of a specifed panel on the vehicle. A vehicle can have up to 7 panels.

==Syntax==
<syntaxhighlight lang="lua">
int getVehiclePanelState ( vehicle thevehicle, int panel )
</syntaxhighlight>

==Required Arguments==
*'''theVehicle:''' The [[vehicle]] that you wish to know the panel state of.
*'''panel:''' A whole number ranging from 0 to 6.

==Returns==
Returns an [[int]] indicating the state of the specified the panel. This value can be:

NEEDS UPDATING

==Example==
This function creates an admiral and outputs every panel's state in the chatbox.
<syntaxhighlight lang="lua">local newcar = createVehicle ( 520, 1024, 1024, 1024 )
admiral = createVehicle ( 445, 0, 0, 10 )

...

for i=0, 6 do
local panel = getVehiclePanelState ( admiral, i )
outputChatBox ( panel )
end
</syntaxhighlight>

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

GetVehiclePlateText

2007-08-27T10:36:00Z

Norby89:

{{Needs Checking|This function doesn't work, mantis #2457 --[[User:Norby89|Norby89]] 13:47, 26 August 2007 (CDT)}}
__NOTOC__
{{Server client function}}
This function is used to retrieve the text on the number plate of a specified vehicle.

==Syntax==
<syntaxhighlight lang="lua">
string getVehiclePlateText ( vehicle theVehicle )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' The [[vehicle]] that you wish to retrieve the plate text from.

===Returns===
Returns a ''string'' that corresponds to the plate on the text, ''false'' if a bad argument was passed or if the vehicle is not a car.

==Example==
<section name="Example" class="client" show="true">
This example outputs the text on the license plate of the vehicle the player is driving to the chatbox.
<syntaxhighlight lang="lua">
function outputLicensePlate ( command )
-- get the vehicle the local player is in
local localPlayerOccupiedVehicle = getPlayerOccupiedVehicle ( getLocalPlayer() )
-- if he is in a vehicle,
if localPlayerOccupiedVehicle then
-- get the license plate text
local plateText = getVehiclePlateText ( localPlayerOccupiedVehicle )
-- if there was a license plate,
if plateText then
-- output it to the chatbox
outputChatBox ( "Your license plate is: " .. plateText )
else
outputChatBox ( "Your vehicle has no license plate." )
end
else
outputChatBox ( "You're not in a vehicle." )
end
end
-- add our function as a handler to the "plate" command
addCommandHandler( "plate", outputLicensePlate )
</syntaxhighlight>
</section>

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

GetVehiclePlateText

2007-08-26T18:47:50Z

Norby89:

{{Server client function}}
{{Needs Checking|This function doesn't work, mantis #2457 --[[User:Norby89|Norby89]] 13:47, 26 August 2007 (CDT)}}
__NOTOC__
This function is used to retrieve the text on the number plate of a specified vehicle.

==Syntax==
<syntaxhighlight lang="lua">
string getVehiclePlateText ( vehicle theVehicle )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' A handle to the vehicle that you wish to retrieve the plate text from.

===Returns===
Returns a ''string'' that coresponds to the plate on the text or ''false'' if a bad argument was passed or if the vehicle is not a car.

==Example==
<section name="Server" class="server" show="true">
This example outputs the text on the license plate of the vehicle the player is driving to the chatbox.
<syntaxhighlight lang="lua">
function scriptPlate ( player, command )
local aVehicle = getPlayerOccupiedVehicle ( getLocalPlayer() )
local text = getVehiclePlateText ( aVehicle )
if ( text and aVehicle ) then
outputChatBox ( "text" )
else outputChatBox ( "your vehicle has no licence plate or you're not in a vehicle" )
end
end
addCommandHandler( "plate", scriptPlate )
</section>
</syntaxhighlight>

==See Also==

{{Vehicle functions}}

GetVehiclePlateText

2007-08-26T18:46:50Z

Norby89: /* Example */

{{Server client function}}
__NOTOC__
This function is used to retrieve the text on the number plate of a specified vehicle.

==Syntax==
<syntaxhighlight lang="lua">
string getVehiclePlateText ( vehicle theVehicle )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' A handle to the vehicle that you wish to retrieve the plate text from.

===Returns===
Returns a ''string'' that coresponds to the plate on the text or ''false'' if a bad argument was passed or if the vehicle is not a car.

==Example==
<section name="Server" class="server" show="true">
This example outputs the text on the license plate of the vehicle the player is driving to the chatbox.
<syntaxhighlight lang="lua">
function scriptPlate ( player, command )
local aVehicle = getPlayerOccupiedVehicle ( getLocalPlayer() )
local text = getVehiclePlateText ( aVehicle )
if ( text and aVehicle ) then
outputChatBox ( "text" )
else outputChatBox ( "your vehicle has no licence plate or you're not in a vehicle" )
end
end
addCommandHandler( "plate", scriptPlate )
</section>
</syntaxhighlight>

==See Also==

{{Vehicle functions}}

GetVehiclePlateText

2007-08-26T18:41:53Z

Norby89:

{{Server client function}}
__NOTOC__
This function is used to retrieve the text on the number plate of a specified vehicle.

==Syntax==
<syntaxhighlight lang="lua">
string getVehiclePlateText ( vehicle theVehicle )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' A handle to the vehicle that you wish to retrieve the plate text from.

===Returns===
Returns a ''string'' that coresponds to the plate on the text or ''false'' if a bad argument was passed or if the vehicle is not a car.

==Example==
This example outputs the text on the license plate of the vehicle the player is driving to the chatbox.
<syntaxhighlight lang="lua">
function scriptPlate ( player, command )
local aVehicle = getPlayerOccupiedVehicle ( getLocalPlayer() )
local text = getVehiclePlateText ( aVehicle )
if ( text and aVehicle ) then
outputChatBox ( "text" )
else outputChatBox ( "your vehicle has no licence plate or you're not in a vehicle" )
end
end
addCommandHandler( "plate", scriptPlate )
</syntaxhighlight>

==See Also==

{{Vehicle functions}}

GetVehiclePanelState

2007-08-26T17:30:38Z

Norby89:

__NOTOC__
{{Needs Checking|A list of panels would be nice and a more specific explanation on what the function returns --[[User:Norby89|Norby89]] 12:30, 26 August 2007 (CDT)}}
{{Server client function}}
This function returns the current state of a specifed panel on the vehicle. A vehicle can have up to 7 panels.

==Syntax==
<syntaxhighlight lang="lua">
int getVehiclePanelState ( vehicle thevehicle, int panel )
</syntaxhighlight>

==Required Arguments==
*'''theVehicle:''' A handle to the [[vehicle]] that you wish to know the panel state of.
*'''panel:''' A whole number ranging from 0 to 6.

==Returns==
Returns an [[int]] indicating the state of the specified the panel. This value can be:

NEEDS UPDATING

==Example==
This function creates an admiral and outputs every panel's state in the chatbox.
<syntaxhighlight lang="lua">local newcar = createVehicle ( 520, 1024, 1024, 1024 )
admiral = createVehicle ( 445, 0, 0, 10 )

...

for i=0, 6 do
local panel = getVehiclePanelState ( admiral, i )
outputChatBox ( panel )
end
</syntaxhighlight>

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

GetVehicleDoorState

2007-08-26T17:14:13Z

Norby89:

__NOTOC__
{{Server client function}}
This function returns the current state of a specifed door on the vehicle.

==Syntax==
<syntaxhighlight lang="lua">int getVehicleDoorState ( vehicle theVehicle, int door )</syntaxhighlight>

==Required Arguments==
*'''theVehicle:''' A handle to the [[vehicle]] that you wish to know the door state of.
*'''door:''' A whole number, 0 (hood), 1 (trunk), 2 (front left), 3 (front right), 4 (rear left), 5 (rear right)

==Returns==
Returns 4 [[int]]s indicating the states of the door. These values can be:
* '''0:''' Shut (Undamaged)
* '''1:''' Open (Undamaged)
* '''2:''' Shut (Damaged)
* '''3:''' Open (Damaged)
* '''4:''' Fallen off

==Example==
<syntaxhighlight lang="lua">local newcar = createVehicle ( 520, 1024, 1024, 1024 )
local state = getVehicleDoorState ( newcar, 2 )
outputChatBox ( "The 3rd door state on this car: " .. state )</syntaxhighlight>

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

SetWeatherBlended

2007-08-26T16:49:51Z

Norby89:

__NOTOC__
{{Needs Checking|when trying it clientside it changed the weather instantly and not over a period of time, #2422 --[[User:Norby89|Norby89]] 09:16, 5 August 2007 (CDT)}}
{{Server client function}}
This function will change the weather from the current weather (set using [[setWeather]]) to another weather state over a period of 60 seconds.

==Syntax==
<syntaxhighlight lang="lua">
bool setWeatherBlended ( int weatherID )
</syntaxhighlight>

===Required Arguments===
*'''weatherID:''' The ID of the weather state you wish to set. Valid values are 0 to 19 inclusive.

===Returns===
Returns ''true'' if successful, ''false'' if an invalid ''weatherID'' is passed.

==Example==
This example sets the weather to sunny, then makes it change to a foggy over the period of a minute.
<syntaxhighlight lang="lua">
-- Set the weather to sunny
setWeather ( 0 )
-- Blend the weather to foggy
setWeatherBlended ( 9 )
</syntaxhighlight>

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

SetVehicleRotation

2007-08-26T16:47:35Z

Norby89:

__NOTOC__
{{Needs Checking|the server side function seems to work counter clockwise meaning setting the rotation to (0 0 90) will make the vehicle face West serverside and East clentside, also serverside 0 rotation is displayed as 360 no biggie though, #2421 --[[User:Norby89|Norby89]] 09:17, 5 August 2007 (CDT)}}
{{Server client function}}
This function rotates a vehicle around a single point.

==Syntax==
<syntaxhighlight lang="lua">bool setVehicleRotation ( vehicle theVehicle, rx, ry, rz )</syntaxhighlight>

===Required Arguments===
*'''theVehicle''': The [[vehicle]] that you wish to apply the warp to.
*'''x''': The x-axis rotation in degrees.
*'''y''': The y-axis rotation in degrees.
*'''z''': The z-axis rotation in degrees.

==Returns==
Returns a boolean value ''true'' or ''false'' that tells you if it was successful or not.

==Example==
<syntaxhighlight lang="lua">local newcar = createVehicle ( 520, 1024, 1024, 1024 )
if setVehicleRotation ( newcar, 0, 0, 270 ) then
outputChatBox ( "Rotation change successful." )
end</syntaxhighlight>

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

GetVehicleWheelStates

2007-08-26T16:45:23Z

Norby89:

__NOTOC__
{{Needs Checking|the function doesn't work how it should, the order is FrontL, RearL, FrontR, RearR, when trying to pop out a tire and the ones before them (in the order I mentioned earlier) aren't flat it will remain unchanged, for instance I pop out the RealL tire the function will still say it's inflated but if I pop out the FrontL tire then it works, also it doesn't seem to work with bikes EDIT: it seems to be working well client side (except with bikes), mantis #2420 --[[User:Norby89|Norby89]] 09:15, 5 August 2007 (CDT)}}
{{Server client function}}
This function returns the current states of all the wheels on the vehicle.

No vehicles have more than 4 wheels, if they appear to they will be duplicating other wheels.

==Syntax==
<syntaxhighlight lang="lua">int, int, int, int getVehicleWheelStates ( vehicle theVehicle )</syntaxhighlight>

==Required Arguments==
*'''theVehicle:''' A handle to the [[vehicle]] that you wish to know the wheel states of.

==Returns==
Returns 4 [[int]]s indicating the states of the wheel. These values can be:
* '''0:''' Inflated
* '''1:''' Flat
* '''2:''' Fallen off

==Example==
<section name="Server" class="server" show="true">
This example displays the states of the vehicle's wheels and changes their states if any arguments were passed.
<syntaxhighlight lang="lua">
function scriptWheelStates ( thePlayer, command, newFLeft, newRLeft, newFRight, newRRight )
local theVehicle = getPlayerOccupiedVehicle ( thePlayer )
if ( theVehicle ) then -- check if the player is in a car
if ( newFLeft ) then -- if there's at least one argument passed, we change the wheel states
if not setVehicleWheelStates ( theVehicle, newFLeft, newRLeft, newFRight, newRRight ) then
outputChatBox ( "Bad arguments." )
end
end
local states = { [0]="inflated", [1]="flat", [2]="fallen off" } -- we store the states in a table
local frontLeft, frontRight, rearLeft, rearRight = getVehicleWheelStates ( theVehicle )
outputChatBox ( "Your vehicle's wheel states:", thePlayer ) -- output them in the chatbox
outputChatBox ( "Front-Left: " .. states [ frontLeft ] .. ", Front-Right: " .. states [ frontRight ]
.. ", Rear-Left: " .. states [ rearLeft ] .. ", Rear-Right: " .. states [ rearRight ], thePlayer )
else outputChatBox ( "You have to be in a vehicle to use this command.", thePlayer )
end
end
addCommandHandler ( "wheelstates", scriptWheelStates )</syntaxhighlight>
</section>
==See Also==
{{Vehicle functions}}