Multi Theft Auto: Wiki - User contributions [en]

Hibakeresés

2010-03-07T13:10:11Z

Paul Cortez: isTimer is a MTA function these days

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

==Debug console==
MTA features a built-in debug console that shows debug messages output from MTA functions or from scripts. You can open it by typing ''debugscript x'' in console, while ''x'' is the debug level:
* '''1:''' only errors
* '''2:''' errors and warnings
* '''3:''' errors, warnings and info messages
Thus, by typing ''debugscript 3'' all messages are visible, that or level 2 are recommended for most occasions. You should have debugscript enabled most of the time you are testing your scripts, this will help you detect typos or other simple issues and solve them easily.

===Example===
This example snippet has two errors:
<syntaxhighlight lang="lua">
if (getPlayerName(player) == "Fedor")
outputChatbox("Hello Fedor")
end
</syntaxhighlight>
When the script this piece of code is in is tried to be loaded, debugscript will output something similiar to this:
{{Debug info|Loading script failed: C:\<server path>\mods\deathmatch\resources\myResource\script.lua:15: 'then' expected near ´outputChatbox'}}
This means the script could not be parsed, because there was a syntax error. It shows the path of the script, so you can also see what resource it is in ('myResource' in this case) and of course the name of the script. After the filename it shows the line number and again after that what was wrong. Easy to solve now, we just forgot the 'then' keyword:
<syntaxhighlight lang="lua">
if (getPlayerName(player) == "Fedor") then
outputChatbox("Hello Fedor")
end
</syntaxhighlight>
Now the script will load fine and won't output any errors, until a player with the name 'Fedor' enters this section of the script. Then, debugscript will output:
{{Debug error|C:\<server path>\mods\deathmatch\resources\d\script.lua:15: attempt to call global 'outputChatbox' (a nil value)}}
This means the called function does not exist, which can be easily explained since the functions' name is ''outputChatBox'' (with a capital ''B''):
<syntaxhighlight lang="lua">
if (getPlayerName(player) == "Fedor") then
outputChatBox("Hello Fedor")
end
</syntaxhighlight>

This is of course just an example, there are plenty of other messages and scenarios, but you should get the idea.

==Debug logging==
You can also turn debug message logging on by editing ''coreconfig.xml'' in your GTA\MTA folder. You should find the following tag:
<syntaxhighlight lang="xml"><debugfile/></syntaxhighlight>

Replace that with a tag specifying the file you want to log messages to (file path is relative from the GTA folder):
<syntaxhighlight lang="xml"><debugfile>MTA\debugscript.log</debugfile></syntaxhighlight>

All debug messages will be appended to the specified file from now on. To turn logging off, replace that line with an empty tag again.

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

===Useful functions===
First of all some functions that may come in handy for debugging.
* [[outputDebugString]] or [[outputChatBox]] for outputting any information
* [http://www.lua.org/manual/5.1/manual.html#pdf-tostring tostring()] on a variable to turn it into a string, for example when it contains a boolean value
* [[getElementType]] to check an MTA Element for its type

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

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

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

==Example==
Imagine you created a colshape (collision shape) somewhere and you want a player to stay 10 seconds in it, then perform some action.
<syntaxhighlight lang="lua">
function colShapeHit(player)
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit",getRootElement(),colShapeHit)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[[it:Guida al Debug]]
[[Category:Scripting Concepts]]
[[ru:Debugging]]

SetRadioChannel

2010-02-26T13:52:35Z

Paul Cortez:

__NOTOC__
{{Client function}}
This function sets the currently active radio channel.

This function also works while not in a vehicle.

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

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

{{SoundID}}

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

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

==See Also==

{{Client_audio_functions}}

SetRadioChannel

2010-02-26T13:51:01Z

Paul Cortez: Believe it or not, this DOES work outside of a vehicle

__NOTOC__
{{Client function}}
This function sets the currently active radio channel.

This function also works while not in a vehicle.

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

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

{{SoundID}}

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

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

==See Also==

{{Client_audio_functions}}

GuiGridListSetItemData

2010-02-25T17:22:24Z

Paul Cortez: guiGridListSetItemData doesn't accept anything but strings

{{Client function}}
__NOTOC__
This function sets a Item Data associated to a grid list item.

==Syntax==
<syntaxhighlight lang="lua">
bool guiGridListSetItemData ( element gridList, int rowIndex, int columnIndex, string data )
</syntaxhighlight>

===Required Arguments===
*'''gridList:''' A gridlist element of the data you wish to set to
*'''rowIndex:''' The row of the item you wish to set to
*'''columnIndex:''' The column of the item you wish to set to
*'''data:''' The data you wish to set to the item.

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

==Example==
This page lacks an example
<syntaxhighlight lang="lua">
--Add an example here
</syntaxhighlight>

==See Also==
{{GUI functions}}
[[Category:Needs Example]]

OnPlayerBan

2010-02-25T16:17:09Z

Paul Cortez:

__NOTOC__
{{Server event}}
This event is triggered when a player added a ban (like onBan).

==Parameters==
<syntaxhighlight lang="lua">
ban banPointer, player responsibleElement
</syntaxhighlight>

*'''banPointer''': The ban pointer which was added.
*'''responsibleElement''': The player who added the ban

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

==Example==
This example outputs the responsible element and the banned player's name when a ban takes place.
<syntaxhighlight lang="lua">
function outputBan ( banPointer, responsibleElement ) -- Define the banner and the ban pointer in the function.
local banner = getPlayerName( responsibleElement ) or "Console" -- Get the banner's name.

outputChatBox ( banner .." has banned ".. getPlayerName( source ) ..".", getRootElement(), 255, 0, 0 ) -- Output the ban.
end
addEventHandler ( "onPlayerBan", getRootElement(), outputBan ) -- Trigger the function when there is a ban.
</syntaxhighlight>

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

GetBans

2010-02-25T16:07:21Z

Paul Cortez: This has a lot more chance to work

__NOTOC__
{{Server function}}
This function will return a table over all the [[ban]] values in the server.

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

===Returns===
Returns a [[table]] over all the [[ban]] pointers.

==Example==
This example lists every ban when somebody types "/bans". WARNING: This will spam chat (for the player that executed the command) if the server has a lot of bans.
<syntaxhighlight lang="lua">
function listBans ()
local bansList = getBans() -- Return a table of all the bans.

for banID, ban in ipairs ( banList ) do -- For every ban do the following...
local nick = getBanNick ( ban ) -- Get the IP of the ban

if nick then
outputChatBox ( "Ban #" .. banID .. ": " .. nick, source, 255, 0, 0 ) -- Output the ban.
end
end
end
addCommandHandler ( "bans", listBans ) -- Add "/bans" as the trigger for the function.
</syntaxhighlight>

==See Also==
{{Admin functions}}
[[ru:getBans]]

StartResource

2010-02-22T11:13:17Z

Paul Cortez: This has more chance of actually working

__NOTOC__
{{Server function}}
This function starts a resource either persistently or as a dependency of the current resource. If you start the resource persistently, the resource will run until stopped either using [[stopResource]] or by the server admin. A resource started as a dependency will stop when your resource stops, if no other resources have it as a depdendency. This is the same effect as using an ''include'' in your [[meta.xml]] file.

The function also allows you to specify a number of boolean options. These allow you to disable the loading of various aspects of the resource. This is generally useful for editors rather than for actual gamemodes. It could also be used as a way to preview a resource before enabling the scripting aspects, though this could produce unreliable results. There is no way for a resource to tell if it is being run with any of these booleans set.

==Syntax==
<syntaxhighlight lang="lua">
bool startResource ( resource resourceToStart, [bool persistent = false, bool startIncludedResources = true, bool loadServerConfigs = true, bool loadMaps = true, bool loadServerScripts = true, bool loadHTML = true, bool loadClientConfigs = true, bool loadClientScripts = true, bool loadFiles = true] )
</syntaxhighlight>

===Required Arguments===
*'''resourceToStart:''' The resource that should be started.

===Optional Arguments===
{{OptionalArg}}
*'''persistent:''' A boolean specifying if the resource should continue to run even after this resource has been stopped or not. If this is ''true'' then the resource will run until another resource or user terminates it or the server shuts down.
*'''startIncludedResources:''' A boolean specifying if the resource's included/dependant resources will be started.
*'''loadServerConfigs:''' A boolean specifying if server side config (XML) files should be loaded with the resource.
*'''loadMaps:''' A boolean specifying if any .map files will be started with the resource.
*'''loadServerScripts:''' A boolean specifying if server side script files should be started alongside the resource.
*'''loadHTML:''' A boolean specifying if HTML files should be started alongside the resource.
*'''loadClientConfigs:''' A boolean specifying if client configs should be loaded alongside the resource.
*'''loadClientScripts:''' A boolean specifying if client scripts should be loaded and started alongside the resource.
*'''loadFiles:''' A boolean specifying if client-side files should be loaded alongside the resource.

===Returns===
Returns ''true'' if the resource has been started successfully, ''false'' otherwise.

==Example==
This example starts a specified resource with the command; "/resource-start".
<syntaxhighlight lang="lua">
function startTheResource ( thePlayer, command, resource )
if ( resource ) then -- Check if they specified a resource name
resource = getResourceFromName ( resource ) -- Get the resource

local start = startResource ( resource ) -- Start the resource
if ( start ) then -- If it was successfully started...
outputChatBox ( resource .. " was started successfully.", thePlayer, 255, 0, 0 )
else -- If it wasn't successfully started...
outputChatBox ( "This resource doesn't exist.", thePlayer, 255, 0, 0 )
end
else -- If they didn't put a resource name...
outputChatBox ( "Please specify a resource to start.", thePlayer, 255, 0, 0 )
end
end
addCommandHandler ( "resource-start", startTheResource ) -- Make it trigger when somebody types "/resource-start"
</syntaxhighlight>

==See Also==
{{Resource_functions}}

IsDebugViewActive

2010-02-21T09:55:43Z

Paul Cortez: Removed "Needs example"

__NOTOC__
{{Client function}}
This function returns whether the ingame debug window is visible or not. This is the debugwindow visible using the "debugscript <level>" command.

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

===Returns===
Returns ''true'' if the debug view is visible, ''false'' if not.

==Example==
This example makes a /debug command to check if the client's debugscript is on or off.
<syntaxhighlight lang="lua">
function checkDebug () -- The function header
if ( isDebugViewActive() ) then -- Check if debugscript is active...
outputChatBox ( "You currently have debugscript on." ) -- If it is, output that it is
else -- If it returns anything else (that it's not active)...
outputChatBox ( "You currently have debugscript off." ) -- Output that they haven't got it on.
end
end
addCommandHandler ( "debug", checkDebug ) -- Execute the script when the client types "/debug"
</syntaxhighlight>

==See Also==
{{GUI_functions}}

IsMainMenuActive

2010-02-21T09:55:29Z

Paul Cortez: Removed "Needs example"

__NOTOC__
{{Client function}}
This function returns whether the user is in the mainmenu or not.

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

===Returns===
Returns ''true'' if the mainmenu is visible, ''false'' if not.

==Example==
This example check if the player is afk.
<syntaxhighlight lang="lua">
function isLocalPlayerActive ()
if isMainMenuActive() then
setElementData(getLocalPlayer(),"status","afk")
else
setElementData(getLocalPlayer(),"status","playing")
end
end
</syntaxhighlight>

==See Also==
{{GUI_functions}}

GetPedRotation

2010-01-30T10:25:05Z

Paul Cortez: Undo revision 22341 by Sebassje (Talk) - Revision doesn't make any sense

__NOTOC__
{{Server client function}}
Gets the rotation of a ped.

==Syntax==
<syntaxhighlight lang="lua">
float getPedRotation ( ped thePed )
</syntaxhighlight>

===Required Arguments===
*'''thePed:''' the ped to retrieve the rotation of.

===Returns===
Returns the rotation of the ped, in degrees: 0 means facing north, higher values go counter clockwise. Returns ''false'' if an invalid element was passed.

==Example==
<section name="Server" class="server" show="true">
This code adds a ''getrot'' command to get a 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 isPedInVehicle ( sourcePlayer ) then
-- store the vehicle element
local playerVehicle = getPedOccupiedVehicle ( sourcePlayer )
-- and output its rotation
local x,y,z = getElementRotation ( playerVehicle )
outputChatBox ( "Your vehicle's rotation is: " .. z, sourcePlayer )
-- if he is on foot
else
-- output the player's rotation
outputChatBox ( "Your rotation is: " .. getPedRotation ( sourcePlayer ), sourcePlayer )
end
end
end

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

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

AttachElements

2010-01-27T14:04:29Z

Paul Cortez: Sounds also appear to be compatible - check if the list is complete

__NOTOC__
{{Server client function}}
This function attaches one element to another, so that the first one follows the second whenever it moves.

If an attempt is made to attach two elements that are already attached the opposite way (eg theElement becomes theAttachToElement and vice versa), the 1st attachment order is automatically detached in favor of the 2nd attachment order. For example, if carA was attached to carB, now carB is attached to carA. Also, an element cannot be attached to two separate elements at one time. For example, two cars can be attached to one single car, but one single car cannot be attached to two separate cars. If you attempt to do this, the existing attachment will automatically be dropped in favor of the new attachment. For example, if carA is asked to attached to carB then carC, it is only attached to carC.

This is not compatible with all elements. The following elements are compatible:
* [[Marker]]s
* [[Blip]]s
* [[Object]]s
* [[Player]]s
* [[Vehicle]]s
* [[Sound]]s

==Syntax==
<syntaxhighlight lang="lua">
bool attachElements ( 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 rotation offset (default 0).
*'''yRotOffset:''' The y rotation offset (default 0).
*'''zRotOffset:''' The z rotation 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 ( getPlayerName ( 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
attachElements ( 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
attachElements ( 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
attachElements ( tank, source, 0, 0, 5 ) --Attach the tank to the player.
end
addCommandHandler( "hat", tankHat )
</syntaxhighlight>
</section>

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

CloneElement

2010-01-03T11:34:04Z

Paul Cortez: This is more likely to work, and a check can't hurt

__NOTOC__
{{Server function}}
This function clones (creates an exact copy of) an already existing element. The root node, and player elements, cannot be cloned. If a player element is a child of an element that is cloned, it will be skipped, along with the elements that exist as a child to the player element.

Players are not the only elements that cannot be cloned. This list also includes remoteclients, and console elements.

The cloned element will be placed on the element tree as a child of the same parent as the cloned element.

==Syntax==
<syntaxhighlight lang="lua">
element cloneElement ( element theElement, [ float xPos = 0, float yPos = 0, float zPos = 0, bool cloneChildren = false ] )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element that you wish to clone.

===Optional Arguments===
{{OptionalArg}}
* '''xPos''': A floating point number representing the X coordinate on the map.
* '''yPos''': A floating point number representing the Y coordinate on the map.
* '''zPos''': A floating point number representing the Z coordinate on the map.
* '''cloneChildren''': A boolean value representing whether or not the element's children will be cloned.
'''Note: if 'cloneChildren' is true, the position floats will be offsets from the cloned element's position.'''

===Returns===
Returns the handle of the new cloned element of the parent, ''false'' if invalid arguments were passed.

==Example==
This example clones the vehicle a player is in. This allows carrying over of the current state of the vehicle, including mods, for example.
<syntaxhighlight lang="lua">
function cloneVehicle ( thePlayer, commandName )
local occupiedVehicle = getPlayerOccupiedVehicle ( thePlayer ) -- get the player's vehicle
if occupiedVehicle then -- If the player is actually in a vehicle
local x, y, z = getElementPosition ( occupiedVehicle ) -- get the vehicle's position
local clone = cloneElement ( occupiedVehicle, x+5, y, z ) -- create a clone of the vehicle near it
else
outputChatBox ( "You can't clone a vehicle if you're not in a vehicle", thePlayer, 255, 0, 0 )
end
end
addCommandHandler ( "clone", cloneVehicle )
</syntaxhighlight>

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

Template:Useful Functions

2009-11-06T12:59:01Z

Paul Cortez: Added var_dump to the useful functions list

*[[callClientFunction]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows you to call any clientside function from the server's side.</span>

*[[callServerFunction]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows you to call any server-side function from the client's side.</span>

*[[Check]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks if it's arguments are of the right types and calls the error-function if one isn't.</span>

*[[doForAllElements]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function can be used to execute a specified function for all elements of a specified type.</span>

*[[findRotation]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» Takes two points and returns the direction from point A to point B.</span>

*[[FormatDate]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» Formats a date on the basis of a format string and returns it.</span>

*[[getPointFromDistanceRotation]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» Finds a point based on a starting point, direction and distance.</span>

*[[GetTimestamp]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» With this function you can get the [http://en.wikipedia.org/wiki/Unix_time UNIX timestamp].</span>

*[[IfElse]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» Returns one of two values based on a boolean expression.</span>

*[[IsYearALeapYear]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» Checks if the given year is a leap year.</span>

*[[math.round]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» Rounds a number whereas the number of decimals to keep and the method may be set.</span>

*[[setTableProtected]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» Protects a table and makes it read-only.</span>

*[[string.explode]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function splits a string at a given separator pattern and returns a table with the pieces.</span>

*[[table.copy]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function copies a whole table and all the tables in that table.</span>

*[[table.map]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function goes through a table and replaces every field with the return of the passed function, where the field's value is passed as first argument and optionally more arguments.</span>

*[[table.size]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» Finds the absolute size of a table.</span>

*[[var_dump]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">»This function outputs information about one or more variables using outputConsole(). </span>

[[Category:Useful Functions]]

User talk:Dzzagy

2009-10-16T08:10:07Z

Paul Cortez: Important note to Dzzagy

<nowiki>*ahem* In case you didn't yet notice, your recent changes are meant to be English. The Russian homepage redirects to it since there's no Russian page for it yet. Only translate pages with the prefix "RU/" to Russian!</nowiki> --[[User:Paul Cortez|Paul Cortez]] 08:10, 16 October 2009 (UTC)

SetCameraClip

2009-10-02T15:45:12Z

Paul Cortez: Just made the description a -bit- more useful. Probably needs some correcting.

{{Client function}}
__NOTOC__
This function sets if the camera will "collide" with any objects or vehicles in its way. This means that if object clip is enabled an object is in the way of where the camera actually wants to be, the camera will try to be in front of it. This function can disable that.

'''Note:''' This function doesn't fix the issue of camera clip not working on objects out of world bounds.

==Syntax==
<syntaxhighlight lang="lua">
bool setCameraClip ( bool objects, bool vehicles )
</syntaxhighlight>

===Required Arguments===
*'''objects:''' Sets if you want the camera to clip on objects.
*'''vehicles:''' Sets if you want the camera to clip on vehicles.

===Returns===
Always returns ''true''.

==Example==
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
</section>

==See Also==
{{Client camera functions}}
[[Category:Needs_Example]]
[[Category:Incomplete]]

GetSlotFromWeapon

2009-09-14T18:41:42Z

Paul Cortez: Why is this marked server-only if it also works client-side? D:

__NOTOC__
{{Server client function}}
This function allows you to identify the weapon slot that a weapon belongs to.

==Syntax==
<syntaxhighlight lang="lua">
int getSlotFromWeapon ( int weaponid )
</syntaxhighlight>

===Required Arguments===
*'''weaponid:''' The weapon ID to find the weapon slot of.

===Returns===
Returns an integer representing the given weapon ID's associated weapon slot, ''false'' if the ID was invalid.

==Example==
This will output to the chatbox what weapon slot a given weapon number belongs to when entered into the console (i.e. 'getWeaponSlot 10').
<syntaxhighlight lang="lua">
function outputWeaponSlot ( source, commandName, weaponID )
local weaponSlot = getSlotFromWeapon ( weaponID )

if (weaponSlot) then
outputChatBox ( "Weapon ID " .. weaponID .. " is in weapon slot " .. weaponSlot)
else
outputChatBox ( "Invalid weapon ID" )
end
end
addCommandHandler ( "getWeaponSlot", outputWeaponSlot )</syntaxhighlight>

==See Also==
[[Weapons|Weapon IDs]]
{{Weapon_functions}}
[[ru:getSlotFromWeapon]]

Modules/SebasIRC/ircRaw

2009-09-13T12:35:28Z

Paul Cortez: Created page with '{{ml_irc}} __NOTOC__ {{ModuleFunction|SebasIRC}} This function sends a raw message to the IRC server, with which you can perform actions ==Syntax== <syntaxhighlight lang="lua"> bool ircRaw( s…'

{{ml_irc}}
__NOTOC__
{{ModuleFunction|SebasIRC}}

This function sends a raw message to the IRC server, with which you can perform actions

==Syntax==
<syntaxhighlight lang="lua">
bool ircRaw( string message )
</syntaxhighlight>

===Required Arguments===
*'''message :''' String containing a command to make the IRC server perform an action for you.

===Returns===
Returns ''true'' if the message was send successfully, ''false'' otherwise.

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

==See also==
{{Modules/SebasIRC/Functions}}

Modules/SebasIRC/onIRCRaw

2009-09-13T12:31:48Z

Paul Cortez: Created page with '{{ml_irc}} __NOTOC__ This event triggers when raw data is sent from the IRC server to the module. Thanks to this, scripts can know when something has happened on IRC. (i.e. chat…'

{{ml_irc}}
__NOTOC__

This event triggers when raw data is sent from the IRC server to the module. Thanks to this, scripts can know when something has happened on IRC. (i.e. chatting)

==Parameters==
<syntaxhighlight lang="lua">
string content
</syntaxhighlight>

*'''content''': The raw command that has been sent to the module

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

==Example==
[[Category:Needs Example]]

==See also==
{{Modules/SebasIRC/Events}}

CreateMarker

2009-09-12T14:12:56Z

Paul Cortez: updated as asked on Mantis

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

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

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

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
marker createMarker ( float x, float y, float z, [string theType, float size, int r, int g, int b, int a, visibleTo = getRootElement()] )
</syntaxhighlight>

===Required Arguments===
* '''x''': A floating point number representing the X coordinate on the map.
* '''y''': A floating point number representing the Y coordinate on the map.
* '''z''': A floating point number representing the Z coordinate on the map.

===Optional arguments===
{{OptionalArg}}
* '''theType''': The visual type of the marker to be created. Possible values:
{{Marker_types}}
* '''size''': The diameter of the marker to be created, in meters.
* '''r''': An integer number representing the amount of red to use in the colouring of the marker (0 - 255).
* '''g''': An integer number representing the amount of green to use in the colouring of the marker (0 - 255).
* '''b''': An integer number representing the amount of blue to use in the colouring of the marker (0 - 255).
* '''a''': An integer number representing the amount of alpha to use in the colouring of the marker (0 - 255 where 0 is transparent and 255 is opaque).
* '''visibleTo''': Every element that is a child of this element can see the marker. See [[visibility]].
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
marker createMarker ( float x, float y, float z, [string theType, float size, int r, int g, int b, int a] )
</syntaxhighlight>

===Required Arguments===
* '''x''': A floating point number representing the X coordinate on the map.
* '''y''': A floating point number representing the Y coordinate on the map.
* '''z''': A floating point number representing the Z coordinate on the map.

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

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

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

<section name="Example 2" class="both" show="true">
Create a marker at the coordinates 0, 0, 20:
<syntaxhighlight lang="lua">
createMarker ( 0, 0, 20 )
</syntaxhighlight>
</section>

==See Also==
{{Marker functions}}

Resource:Missiontimer

2009-09-09T17:53:47Z

Paul Cortez: We want it to show up on the resource catalogue, don't we?

{{Resource page}}
Missiontimer is a resource used to easily create timers that count down or up in your resources.

== Overview ==

The "deathmatch" gamemode is an example use of missiontimer. It uses the "createMissionTimer" function to create a timer, and then the onMissionTimerElapsed event to trigger at the end:

<syntaxhighlight lang="lua"> g_MissionTimer = exports.missiontimer:createMissionTimer (g_TimeLimit,true,true,0.5,20,true,"default-bold",1)
addEventHandler ( "onMissionTimerElapsed", g_MissionTimer, onTimeElapsed )
</syntaxhighlight>
Then you use the onTimeElapsed function that you attached to the handler at the end of the timer.

The arguments for createMissionTimer as follows:
<syntaxhighlight lang="lua">createMissionTimer ( duration, countdown, showCS, x, y, bg, font, scale )</syntaxhighlight>
* duration - The time in milliseconds
* countdown - A bool of whether to countdown or count up. Setting it to true will count down from the duration, setting it to false will count up to the duration (latter isnt tested yet)
* showCS - A bool of whether to show Centiseconds. true shows them, false hides them. Showing centi seconds means its in the format of MM:SS:CS (e.g. 12:31:10), hiding them means its in the format of MM:SS (12:31)
* x,y - Position on the screen, this uses "smart positioning". It can be relative or absolute - the deathmatch gamemode creates it at 0.5,20. This means the x value is in the centre, the y is 20pixels from the top. If you specify a negative value it draws the other way, i.e. -20 would be 20pixels from the bottom rather than the top. The same can be done for x.
* bg - Whether to draw the default rounded-rectangle behind the timer. Setting this to false will hide it
* font - The font of the timer. Looks best in default-bold
* scale - The size of the text/bg.

There are also some other exported functions that you may or may not need:
<syntaxhighlight lang="lua">
setMissionTimerTime ( missionTimer, time ) --Sets the countdown/countup target time
getMissionTimerTime ( missionTimer ) --Gets the number currently on the clock
setMissionTimerFrozen ( missionTimer, frozen ) --Freeze the timer
isMissionTimerFrozen ( missionTimer )
</syntaxhighlight>
To remove a missiontimer from the screen, use [[destroyElement]].

Missiontimer is only compatible with MTASA 1.0.

OnPlayerConnect

2009-09-07T14:48:53Z

Paul Cortez:

__NOTOC__
{{Server event}}
This event is triggered when a player attempts to connect to the server.

==Parameters==
<syntaxhighlight lang="lua">
string playerNick, string playerIP, string playerUsername, string playerSerial
</syntaxhighlight>

*'''playerNick''': The player's current nickname.
*'''playerIP''': The player's current IP.
*'''playerUsername''': The player's community username.
*'''playerSerial''': The player's serial number.

==Cancel effect==
If this event is [[Event system#Canceling|canceled]], the player will be disconnected with an error message saying the reason specified in cancelEvent or "Disconnected: server refused the connection" if none was specified.

==Example==

This example cancels connection attempts of people who use the nick "Player" or outputs some data about the connecting player otherwise.

<syntaxhighlight lang="lua">
--when a player connects
function playerConnect (playerNick, playerIP, playerUsername, playerSerial)
if playerNick == "Player" then --check if his nick is "Player"
cancelEvent(true,"The nick \"Player\" is not allowed, please change it to something else. You can change your nick in Settings menu Multiplayer tab.") --in that case refuse the connection
else
--output some data about the player
outputChatBox (playerNick.." just connected to the server.")
outputChatBox ("IP: "..playerIP.." Username: "..playerUsername.." Serial: "..playerSerial)
end
end

--add the playerConnect function as a handler for onPlayerConnect
addEventHandler ("onPlayerConnect", getRootElement(), playerConnect)
</syntaxhighlight>

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

Modules/SebasIRC/ircChangeNick

2009-07-25T21:49:05Z

Paul Cortez: Created page with '{{ml_irc}} __NOTOC__ {{ModuleFunction|SebasIRC}} Changes the name of your bot. ==Syntax== <syntaxhighlight lang="lua"> bool ircSay(string newNick) </syntaxhighlight> ===Required arguments=== * '''newNi…'

{{ml_irc}}
__NOTOC__
{{ModuleFunction|SebasIRC}}

Changes the name of your bot.

==Syntax==
<syntaxhighlight lang="lua">
bool ircSay(string newNick)
</syntaxhighlight>

===Required arguments===
* '''newNick:''' How you want your bot to be called.

===Returns===
Returns true if the nick was changed successfully, false otherwise.

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

==See also==
{{Modules/SebasIRC/Functions}}

Modules/SebasIRC/ircDisconnect

2009-07-25T21:45:04Z

Paul Cortez: Created page with '{{ml_irc}} __NOTOC__ {{ModuleFunction|SebasIRC}} This function disconnects the server from the IRC server it's connected to. ==Syntax== <syntaxhighlight lang="lua"> bool ircDisconnect() </cod…'

{{ml_irc}}
__NOTOC__
{{ModuleFunction|SebasIRC}}

This function disconnects the server from the IRC server it's connected to.

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

===Returns===
Returns ''true'' if successfully disconnected from the server, ''false'' otherwise.

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

==See also==
{{Modules/SebasIRC/Functions}}

SetElementCollisionsEnabled

2009-07-25T11:57:52Z

Paul Cortez:

{{Client function}}
__NOTOC__
This function can disable or enable an element's collisions. An element without collisions does not interact with the physical environment and remains static.<br>
'''Note:''' This function has unwanted effects on vehicles with drivers at the moment.

==Syntax==
<syntaxhighlight lang="lua">
bool setElementCollisionsEnabled ( element theElement, bool enabled )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element you wish to set the collisions of
*'''enabled:''' A boolean to indicate whether collisions are enabled (''true'') or disabled (''false'')

===Returns===
Returns ''true'' if the collisions were set succesfully, ''false'' otherwise.

==Example==
This example disables collisions for all vehicles within a certain radius of a player:
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function disableVehicleCollisionsNearPlayer(thePlayer, maxDistance)
local playerX, playerY, playerZ = getElementPosition(thePlayer)
local vehicles = getElementsByType("vehicle")
for k,v in ipairs(vehicles) do
local vehicleX, vehicleY, vehicleZ = getElementPosition(v)
-- get the distance between the player and the vehicle:
local distance = math.sqrt((vehicleX - playerX)^2 + (vehicleY - playerY)^2 + (vehicleZ - playerZ)^2)
if (distance <= maxDistance) then
-- disable collisions for the vehicle
setElementCollisionsEnabled(v, false)
end
end
end
</syntaxhighlight>
</section>

==See Also==
{{Element_functions}}

User:Paul Cortez

2009-07-21T12:09:25Z

Paul Cortez: Replaced content with 'I'm also known as Gamesnert.'

I'm also known as Gamesnert.

GetScreenFromWorldPosition

2009-06-07T12:19:44Z

Paul Cortez: Added default values for optional arguments.

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

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

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

===Optional Arguments===
{{OptionalArg}}
{{New feature|3|1.0|
*'''edgeTolerance:''' A float value indicating the tolerance which is used to calculate the screen position of positions that are slightly off-screen
*'''relative:''' Bool that indicates if the returned x/y positions are relative to the screen size
}}

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

==See Also==
{{Client_world_functions}}

GetScreenFromWorldPosition

2009-06-07T12:16:49Z

Paul Cortez: Updated the page a little. Still needs checking I think.

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

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

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

===Optional Arguments===
{{OptionalArg}}
{{New feature|3|1.0|
*'''edgeTolerance:''' A float value indicating the tolerance which is used to calculate the screen position of positions that are slightly off-screen
*'''relative:''' Bool that indicates if the returned x/y positions are relative to the screen size
}}

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

==See Also==
{{Client_world_functions}}

Template:GUI events

2009-03-20T16:34:23Z

Paul Cortez: Same as previous, but now involves an event added in that same revision

*[[onClientGUIClick]]
*[[onClientGUIDoubleClick]]
*[[onClientGUIChanged]]
*[[onClientGUIAccepted]]
*[[onClientGUIScroll]]
*[[onClientClick]]
*[[onClientDoubleClick]]
*[[onClientMouseEnter]]
*[[onClientMouseLeave]]
*[[onClientMouseMove]]
*[[onClientMouseWheel]]
*[[onClientCursorMove]]
*[[onClientGUIMove]]
*[[onClientGUISize]]
{{New feature|3|1.0|
*[[onClientGUITabSwitch]]
}}

Template:GUI functions

2009-03-20T16:30:41Z

Paul Cortez: Functions added in r471, but weren't added on the wiki yet.

__NOTOC__
* [[guiGetAlpha]]
* [[guiGetInputEnabled]]
* [[guiGetPosition]]
* [[guiGetProperties]]
* [[guiGetProperty]]
* [[guiGetScreenSize]]
* [[guiGetSize]]
* [[guiGetText]]
* [[guiGetFont]]
* [[guiGetVisible]]
* [[guiGetEnabled]]

* [[guiSetAlpha]]
* [[guiSetInputEnabled]]
* [[guiSetPosition]]
* [[guiSetProperty]]
* [[guiSetSize]]
* [[guiSetText]]
* [[guiSetFont]]
* [[guiSetVisible]]
* [[guiSetEnabled]]

* [[guiBringToFront]]
* [[guiMoveToBack]]

* [[isChatBoxInputActive]]
* [[isConsoleActive]]
* [[isDebugViewActive]]
* [[isMainMenuActive]]
* [[isMTAWindowActive]]
* [[isTransferBoxActive]]

===Buttons===
* [[guiCreateButton]]

===Checkboxes===
* [[guiCreateCheckBox]]
* [[guiCheckBoxGetSelected]]
* [[guiCheckBoxSetSelected]]

===Edit fields===
* [[guiCreateEdit]]
{{Deprecated_feature|3|1.0|
* [[guiEditSetCaratIndex]]
}}
{{New feature|3|1.0|
* [[guiEditSetCaretIndex]]
}}
* [[guiEditSetMasked]]
* [[guiEditSetMaxLength]]
* [[guiEditSetReadOnly]]

===Gridlists===
* [[guiCreateGridList]]
* [[guiGridListAutoSizeColumn]]
* [[guiGridListAddColumn]]
* [[guiGridListAddRow]]
* [[guiGridListClear]]
* [[guiGridListGetItemData]]
* [[guiGridListGetItemText]]
{{New feature|3|1.0|
* [[guiGridListGetSelectedCount]]
* [[guiGridListGetSelectedItems]]
}}
* [[guiGridListGetSelectedItem]]
* [[guiGridListGetRowCount]]
* [[guiGridListInsertRowAfter]]
* [[guiGridListRemoveColumn]]
* [[guiGridListRemoveRow]]
{{New feature|3|1.0|
* [[guiGridListSetColumnWidth]]
}}
* [[guiGridListSetScrollBars]]
* [[guiGridListSetSortingEnabled]]
* [[guiGridListSetItemData]]
* [[guiGridListSetItemText]]
* [[guiGridListSetSelectedItem]]
* [[guiGridListSetSelectionMode]]

===Memos===
* [[guiCreateMemo]]
{{Deprecated_feature|3|1.0|
* [[guiMemoSetCaratIndex]]
}}
{{New feature|3|1.0|
* [[guiMemoSetCaretIndex]]
}}
* [[guiMemoSetReadOnly]]

===Progress bars===
* [[guiCreateProgressBar]]
* [[guiProgressBarGetProgress]]
* [[guiProgressBarSetProgress]]

===Radio buttons===
* [[guiCreateRadioButton]]
* [[guiRadioButtonGetSelected]]
* [[guiRadioButtonSetSelected]]

===Scrollbars===
* [[guiCreateScrollBar]]
* [[guiScrollBarSetScrollPosition]]
* [[guiScrollBarGetScrollPosition]]

===Scroll panes===
* [[guiCreateScrollPane]]
* [[guiScrollPaneSetScrollBars]]
* [[guiScrollPaneSetHorizontalScrollPosition]]
* [[guiScrollPaneSetVerticalScrollPosition]]
* [[guiScrollPaneGetHorizontalScrollPosition]]
* [[guiScrollPaneGetVerticalScrollPosition]]

===Static images===
* [[guiCreateStaticImage]]
* [[guiStaticImageLoadImage]]

===Tab panels===
* [[guiCreateTabPanel]]
{{New feature|3|1.0|
* [[guiSetSelectedTab]]
* [[guiGetSelectedTab]]
}}

===Tabs===
* [[guiCreateTab]]
* [[guiDeleteTab]]

===Text labels===
* [[guiCreateLabel]]
* [[guiLabelSetColor]]
* [[guiLabelSetVerticalAlign]]
* [[guiLabelSetHorizontalAlign]]
* [[guiLabelGetTextExtent]]
* [[guiLabelGetFontHeight]]

===Windows===
* [[guiCreateWindow]]
* [[guiWindowSetMovable]]
* [[guiWindowSetSizable]]

IsPlayerNametagShowing

2009-01-05T16:12:49Z

Paul Cortez: Also added client-side according to Google Code.

__NOTOC__
{{Server client function}}
{{New feature|3|1.0|Serverside only in DP2.x}}

This function will allow you to determine if a player's name tag is currently showing.

==Syntax==

<syntaxhighlight lang="lua">
bool isPlayerNametagShowing ( player thePlayer )
</syntaxhighlight>

===Required Arguments===

*'''thePlayer:''' The player whose current name tag condition you want to check

===Returns===

Returns ''true'' if the player's name tag is being shown, ''false'' otherwise.

==Example==

This example toggles a player's nametag. If no playername is given, it toggles the nametag of the player who entered the command.

<syntaxhighlight lang="lua">
function toggleNametag(sourcePlayer, command, who)
local tplayer = sourcePlayer -- by default, toggle the name tag of the player who issued the command
if ( who ) then -- if there was a nick entered in the command
tplayer = getPlayerFromNick(who) -- search for the player
else
whoNick = getClientName(sourcePlayer)
end
if (tplayer ~= false) then -- if the player was found (or no playername was entered)
if isPlayerNametagShowing(tplayer) then -- if the nametag is shown
setPlayerNametagShowing(tplayer, false) -- hide it
outputChatBox(who .. "'s nametag is now hidden", sourcePlayer) -- output a message to the player who entered the command
else -- if the nametag is not shown
setPlayerNametagShowing(tplayer, true) -- show it
outputChatBox(who .. "'s nametag is now showing", sourcePlayer) -- output a message to the player who entered the command
end
else
outputChatBox("Player not found.", sourcePlayer)
end
end
addCommandHandler("toggleNametag", toggleNametag)
</syntaxhighlight>

==See Also==

{{Player_functions}}

ProcessLineOfSight

2008-10-25T11:43:04Z

Paul Cortez: It's in pixels, not relative.

{{Client function}}
__NOTOC__
This function checks if there is anything between 2 points in the world, and if there is, tells you where and what. The two positions '''must''' be within the local player's draw distance as the collision data is not loaded outside this area.

This function is useful for checking for collisions and for editor-style scripts. If you wish to get an element that's positioned at a particular point on the screen, use this function combined with [[getWorldFromScreenPosition]].

==Syntax==
<syntaxhighlight lang="lua">
bool float float float element processLineOfSight ( float startX, float startY, float startZ, float endX, float endY, float endZ, [ bool checkBuildings = true, bool checkVehicles = true, bool checkPlayers = true, bool checkObjects = true, bool checkDummies = true, bool seeThroughStuff = false, bool ignoreSomeObjectsForCamera = false, bool shootThroughStuff = false, element ignoredElement = nil ] )
</syntaxhighlight>

===Required Arguments===
*'''startX:''' The start ''x'' position
*'''startY:''' The start ''y'' position
*'''startZ:''' The start ''z'' position
*'''endX:''' The end ''x'' position
*'''endY:''' The end ''y'' position
*'''endZ:''' The end ''z'' position

===Optional Arguments===
{{OptionalArg}}
*'''checkBuildings:''' Allow the line of sight to be blocked by GTA's internally placed buildings, i.e. the world map.
*'''checkVehicles:''' Allow the line of sight to be blocked by [[Vehicle|vehicles]].
*'''checkPlayers:''' Allow the line of sight to be blocked by [[Player|players]].
*'''checkObjects:''' Allow the line of sight to be blocked by [[Object|objects]].
*'''checkDummies:''' Allow the line of sight to be blocked by GTA's internal dummies. These are not used in the current MTA version so this argument can be set to ''false''.
*'''seeThroughStuff:''' Allow the line of sight to be blocked by translucent game objects, e.g. glass.
*'''ignoreSomeObjectsForCamera:''' Allow the line of sight to be blocked by certain objects.
*'''shootThroughStuff:''' Allow the line of sight to be blocked by things that can be shot through
*'''ignoredElement:''' Allow the line of sight to pass through a certain specified element.

===Returns===
If there is a collision, the function will return ''true'', the collision position and MTA element hit. If no element is hit, the element return value will be ''nil''. If there is no collision the function will return ''false''.

==Example==
This example shows how you can tell what position and element the camera is looking at, up to 50 units away.
<syntaxhighlight lang="lua">
local w, h = guiGetScreenSize ()
local tx, ty, tz = getWorldFromScreenPosition ( w/2, h/2, 50 )
local px, py, pz = getCameraPosition()
hit, x, y, z, elementHit = processLineOfSight ( px, py, pz, tx, ty, tz )
if hit then
outputChatBox ( "Looking at " .. x .. ", " .. y .. ", " .. z )
if elementHit then
outputChatBox ( "Hit element " .. getElementType(elementHit) )
end
end
</syntaxhighlight>

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

GetWorldFromScreenPosition

2008-10-25T11:39:55Z

Paul Cortez: It's in pixels, it's not relative.

__NOTOC__
{{Client function}}
This function allows you to retrieve the world position corresponding to the 2D position on the screen, at a certain depth.

If you want to detect what element is at a particular point on the screen, use [[processLineOfSight]] between the camera position and the position returned from this function when passed a high depth value (100 or so, depending how far away you want to detect elements at).

==Syntax==
<syntaxhighlight lang="lua">
float, float, float getWorldFromScreenPosition ( float x, float y, float depth )
</syntaxhighlight>

===Required Arguments===
*'''x:''' A float value indicating the x position on the screen, in pixels.
*'''y:''' A float value indicating the y position on the screen, in pixels.
*'''depth:''' A float value indicating the distance from the camera of the point whose coordinates we are retrieving, in units.

===Returns===
Returns three ''x'', ''y'', ''z'' [[float]]s indicating the world position if successful, ''false'' otherwise.

==Example==
This example binds the local player's "'''i'''" key to a function that creates an explosion in the middle of the screen.
<syntaxhighlight lang="lua">
function explosion ()
local w, h = guiGetScreenSize ()
local x, y, z = getWorldFromScreenPosition ( w/2, h/2, 10 )
createExplosion ( x, y, z, 11 )
end
bindKey ( "i", "down", explosion )
</syntaxhighlight>

==See Also==
{{Client_world_functions}}

User:Paul Cortez

2008-08-11T18:39:06Z

Paul Cortez: Like to have me own page. Wondered what happened if I clicked my name. :P

==Information==

Real name: None of your business ^^
Age: 14
Also known as: Gamesnert (Paul_Cortez is my RP name ^^)

==Current employment==

IRL: Nothing really
Scripting for: VNRP and on requests, topics and ofcourse for myself. But those scripts '''can''' go to VNRP or online too.

==Scripting==

If I rate MYSELF from 1 to 10, I would rate myself... Ehm... A 6. Overall I'm not extremely good, it's just a hobby. :P

I don't have any extremely special scripts. I more am a kind of: "Make what someone needs and that's quite it" kind of guy, and do not script too difficult things.

What I have done:
-I made a script to make Parachutes and Sweepers more useful with a "Mine system". Parachutes drop 'em, Sweepers sweep 'em. ^^
-I made a few missions scripts for VNRP, making the 3rd right now.
-I also made something else for VNRP, but am not allowed to tell what. :D
-And ofcourse I made alot of other unimportant scripts.

Scripting Introduction

2008-08-10T21:05:14Z

Paul Cortez:

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

Everything that has to do with scripting happens in resources, what a resource does defines if it is a gamemode, a map or anything else. MTA comes with resources that you can optionally use in your gamemodes, such as maplimits to keep playings within a playing area or deathpickups to create weapon pickups.

'''Your first step to begin Lua scripting should be using an Lua editor. This makes scripting much easier. We recommend [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] or [http://luaedit.luaforge.net/ LuaEdit].'''

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

/Your MTA Server/mods/deathmatch/resources/

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

Now you should be under this directory:

/Your MTA Server/modes/deathmatch/resources/myserver/

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

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

The ''<script />'' tag indicates the script files contained in the resource, which we will create next.
===Creating a simple script===
Note that in the ''<script />'' tag above, the .lua file is not under another directory. Therefore we'll create the file in the folder as meta.xml. Now you can copy and paste the following code into script.lua:
<syntaxhighlight lang="lua">
function joinHandler()
local x,y,z
x = 1959.55
y = -1714.46
z = 10
spawnPlayer(source, x, y, z)
fadeCamera(source, true)
outputChatBox("Welcome to My Server", source)
end
addEventHandler('onPlayerJoin', getRootElement(), joinHandler)
</syntaxhighlight>
The script will spawn you at the coordinate(x,y,z) specified above, when you join the game. Note that the ''fadeCamera'' function must be used or the screen will be black. Source indicates who triggered the event. Since a player has joined when the code is triggered, you use source to look which has joined. So it'll spawn that player instead of everyone or a random person. If we have a closer look on [[addEventHandler]], you can see 3 things: 'onPlayerJoin', which indicates when it's triggered. getRootElement(), which shows by what/who it can be triggered. (getRootElement() is everything/everyone) And joinHandler, which indicates the function that has to be triggered after the event is triggered. Other details will be explained later in another example, now let's just run the server and try it out!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Where to go from here==
You should now be familiar with the most basic aspects of MTA scripting and also a bit with the documentation. The [[Main Page]] provides you with links to more information, Tutorials and References that allow a deeper look into the topics you desire to learn about.

From here we recommend reading the [[debugging]] tutorial. Good debugging skills are an absolute necessity when you are making scripts.

[[ru:Scripting Introduction]]
[[it:Introduzione allo scripting]]

XmlNodeGetValue

2008-08-10T20:24:23Z

Paul Cortez:

[[Category:Incomplete]]

__NOTOC__
This function is made to be able to read values in XML files. (for example <something>anything</something>)

==Syntax==
<syntaxhighlight lang="lua">
string xmlNodeGetValue ( xmlnode xmlnode )
</syntaxhighlight>

===Required Arguments===
*'''xmlnode:''' The node of which you need to know the value.

===Optional Arguments===
{{OptionalArg}}
*'''none:'''

===Returns===
Returns the value of the node if successful, ''false'' otherwise.

==Example==
In this example is shown what xmlNodeSetValue does and how it works:
<syntaxhighlight lang="lua">
local xmlFile=xmlLoadFile("xmlfile.xml") --Open a file already created
if xmlFile then --If it's indeed opened:
local node=xmlCreateSubNode(xmlFile,"somesubnode") --Create a new subnode
local success=xmlNodeSetValue(node,"somevalue") --Set the value of it
if success then --Check if it was successful
xmlSaveFile(xmlFile) --Save the file
end --End what still needs to be ended
end
end
</syntaxhighlight>
The xml file wil look like:
<syntaxhighlight lang="xml">
<somenode>
<somesubnode>somevalue</somesubnode>
</somenode>
</syntaxhighlight>

==See Also==
{{FunctionArea_Functions}}
{{XML_functions}}

XmlNodeSetValue

2008-08-10T20:20:21Z

Paul Cortez:

[[Category:Incomplete]]

__NOTOC__
This function is made to be able to assign values in XML files. (for example <something>anything</something>)

==Syntax==
<syntaxhighlight lang="lua">
bool xmlNodeSetValue ( xmlnode xmlnode, string value )
</syntaxhighlight>

===Required Arguments===
*'''xmlnode:''' The node you want to set the value of.
*'''value:''' The value you want the node to have.

===Optional Arguments===
{{OptionalArg}}
*'''none'''

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

==Example==
In this example is shown what xmlNodeSetValue does and how it works:
<syntaxhighlight lang="lua">
local xmlFile=xmlLoadFile("xmlfile.xml") --Open a file already created
if xmlFile then --If it's indeed opened:
local node=xmlCreateSubNode(xmlFile,"somesubnode") --Create a new subnode
local success=xmlNodeSetValue(node,"somevalue") --Set the value of it
if success then --Check if it was successful
xmlSaveFile(xmlFile) --Save the file
end --End what still needs to be ended
end
end
</syntaxhighlight>

The xml file wil look like:
<syntaxhighlight lang="xml">
<somenode>
<somesubnode>somevalue</somesubnode>
</somenode>
</syntaxhighlight>

==See Also==
{{FunctionArea_Functions}}
{{XML_functions}}

XmlNodeSetValue

2008-08-10T20:19:17Z

Paul Cortez: /* Example */

[[Category:Incomplete]]

__NOTOC__
This fake function is for use with blah & blah and does blahblahblabhalbhl

==Syntax==
<syntaxhighlight lang="lua">
bool xmlNodeSetValue ( xmlnode xmlnode, string value )
</syntaxhighlight>

===Required Arguments===
*'''xmlnode:''' The node you want to set the value of.
*'''value:''' The value you want the node to have.

===Optional Arguments===
{{OptionalArg}}
*'''none'''

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

==Example==
In this example is shown what xmlNodeSetValue does and how it works:
<syntaxhighlight lang="lua">
local xmlFile=xmlLoadFile("xmlfile.xml") --Open a file already created
if xmlFile then --If it's indeed opened:
local node=xmlCreateSubNode(xmlFile,"somesubnode") --Create a new subnode
local success=xmlNodeSetValue(node,"somevalue") --Set the value of it
if success then --Check if it was successful
xmlSaveFile(xmlFile) --Save the file
end --End what still needs to be ended
end
end
</syntaxhighlight>

The xml file wil look like:
<syntaxhighlight lang="xml">
<somenode>
<somesubnode>somevalue</somesubnode>
</somenode>
</syntaxhighlight>

==See Also==
{{FunctionArea_Functions}}
{{XML_functions}}

XmlNodeSetValue

2008-08-10T20:12:38Z

Paul Cortez: /* Syntax */