Multi Theft Auto: Wiki - User contributions [en]

Resource:Missiontimer

2010-08-16T22:10:20Z

R3mp:

{{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,"%m:%s",0.5,20,true,"default-bold",1,255,255,255)
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, format, x, y, bg, font, scale, r, g, b )</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)
* format - A string detailing the format of the timer text to be shown. You can chose whether to show minutes, seconds or centiseconds using these 3 strings:
** %m - minutes
** %s - seconds
** %cs - centiseconds
This allows you to add normal text onto the timer as well as showing the time left (eg: "Time left: %m:%s")
* 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.
* r,g,b - The red/green/blue components to make up the colour of the timer text (defaults to white)

There are also some other exported functions that you may or may not need:

<syntaxhighlight lang="lua">setMissionTimerTime ( missionTimer, time )</syntaxhighlight>
Sets the countdown/countup target time (in milliseconds)

<syntaxhighlight lang="lua">getMissionTimerTime ( missionTimer )</syntaxhighlight>
Gets the number currently showing on the clock (in milliseconds)

<syntaxhighlight lang="lua">setMissionTimerFrozen ( missionTimer, frozen )</syntaxhighlight>
Sets the timer to frozen (true) or normal (false)

<syntaxhighlight lang="lua">isMissionTimerFrozen ( missionTimer )</syntaxhighlight>
See if the timer is frozen

<syntaxhighlight lang="lua">setMissionTimerHurryTime ( missionTimer, time )</syntaxhighlight>
Set the time that the clock will turn red (in milliseconds) (ie: to indicate there is not much time left)

<syntaxhighlight lang="lua">setMissionTimerFormat ( missionTimer, format )</syntaxhighlight>
Set the text format for the timer

To remove a missiontimer from the screen, use [[destroyElement]].

Missiontimer is only compatible with MTASA 1.0 onwards.

Resource:Missiontimer

2010-08-16T20:31:24Z

R3mp:

{{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,"%m:%s",0.5,20,true,"default-bold",1,255,255,255)
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)
* format - A string detailing the format of the timer text to be shown. You can chose whether to show minutes, seconds or centiseconds using these 3 strings:
** %m - minutes
** %s - seconds
** %cs - centiseconds
This allows you to add normal text onto the timer as well as showing the time left (eg: "Time left: %m:%s")
* 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.
* r,g,b - The red/green/blue components to make up the colour of the timer text (defaults to white)

There are also some other exported functions that you may or may not need:

<syntaxhighlight lang="lua">setMissionTimerTime ( missionTimer, time )</syntaxhighlight>
Sets the countdown/countup target time (in milliseconds)

<syntaxhighlight lang="lua">getMissionTimerTime ( missionTimer )</syntaxhighlight>
Gets the number currently showing on the clock (in milliseconds)

<syntaxhighlight lang="lua">setMissionTimerFrozen ( missionTimer, frozen )</syntaxhighlight>
Sets the timer to frozen (true) or normal (false)

<syntaxhighlight lang="lua">isMissionTimerFrozen ( missionTimer )</syntaxhighlight>
See if the timer is frozen

<syntaxhighlight lang="lua">setMissionTimerHurryTime ( missionTimer, time )</syntaxhighlight>
Set the time that the clock will turn red (in milliseconds) (ie: to indicate there is not much time left)

<syntaxhighlight lang="lua">setMissionTimerFormat ( missionTimer, format )</syntaxhighlight>
Set the text format for the timer

To remove a missiontimer from the screen, use [[destroyElement]].

Missiontimer is only compatible with MTASA 1.0 onwards.

Resource:Missiontimer

2010-08-16T16:32:09Z

R3mp:

{{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,"Time left: ")
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.
* prefix - Any text that you want to show in front of the time (eg: Time left: 00:00). Leave this blank for no text

There are also some other exported functions that you may or may not need:

<syntaxhighlight lang="lua">setMissionTimerTime ( missionTimer, time )</syntaxhighlight>
Sets the countdown/countup target time (in milliseconds)

<syntaxhighlight lang="lua">getMissionTimerTime ( missionTimer )</syntaxhighlight>
Gets the number currently showing on the clock (in milliseconds)

<syntaxhighlight lang="lua">setMissionTimerFrozen ( missionTimer, frozen )</syntaxhighlight>
Sets the timer to frozen (true) or normal (false)

<syntaxhighlight lang="lua">isMissionTimerFrozen ( missionTimer )</syntaxhighlight>
See if the timer is frozen

<syntaxhighlight lang="lua">setMissionTimerHurryTime ( missionTimer, time )</syntaxhighlight>
Set the time that the clock will turn red (in milliseconds) (ie: to indicate there is not much time left)

<syntaxhighlight lang="lua">setMissionTimerPrefix ( missionTimer, prefix )</syntaxhighlight>
Set the prefix text on the timer

To remove a missiontimer from the screen, use [[destroyElement]].

Missiontimer is only compatible with MTASA 1.0 onwards.

Resource:Missiontimer

2010-08-11T18:52:07Z

R3mp:

{{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 )</syntaxhighlight>
Sets the countdown/countup target time (in milliseconds)

<syntaxhighlight lang="lua">getMissionTimerTime ( missionTimer )</syntaxhighlight>
Gets the number currently showing on the clock (in milliseconds)

<syntaxhighlight lang="lua">setMissionTimerFrozen ( missionTimer, frozen )</syntaxhighlight>
Sets the timer to frozen (true) or normal (false)

<syntaxhighlight lang="lua">isMissionTimerFrozen ( missionTimer )</syntaxhighlight>
See if the timer is frozen

<syntaxhighlight lang="lua">setMissionTimerHurryTime ( missionTimer, time )</syntaxhighlight>
Set the time that the clock will turn red (in milliseconds) (ie: to indicate there is not much time left)

To remove a missiontimer from the screen, use [[destroyElement]].

Missiontimer is only compatible with MTASA 1.0 onwards.

Call

2010-07-26T13:27:20Z

R3mp:

__NOTOC__
{{Server client function}}
This function is used to call a function from another resource (which must be running).

The function which you wish to call '''must''' first be exported within the resource's meta. For example:
<syntaxhighlight lang="xml"><meta>
<info author="jbeta" type="script" description="Scoreboard resource" />
<script src="scoreboard_client.lua" type="client"/>
<script src="scoreboard_exports.lua" type="server"/>

<script src="scoreboard_http.lua" type="server"/>

<export function="getScoreboardColumns" http="true" />
<export function="getScoreboardRows" http="true" />

<export function="addScoreboardColumn" type="server"/>
<export function="removeScoreboardColumn" type="server"/>

<export function="setPlayerScoreboardForced" type="server"/>
<export function="setScoreboardForced" type="client"/>
</meta></syntaxhighlight>
This enables other resources to call a function from this resource.

You cannot call a server function from the client or vice versa. See [[triggerServerEvent]] and [[triggerClientEvent]] for possibilities to do that.

{{New feature|3|1.0|
There is an easier syntax replacing this function. For example, you can instead of:<br>
call ( getResourceFromName ( "resource" ), "exportedFunction", 1, "2", "three" )
do much like a normal call:<br>
exports.resource:exportedFunction ( 1, "2", "three" )
If the resource name contains illegal characters (such as hyphens), you can also do:<br>
exports["resource"]:exportedFunction ( 1, "2", "three" )

When using the [[call]] function, two extra "hidden" variables are passed to the exported function:
* '''sourceResource''' - The resource that called the exported function
* '''sourceResourceRoot''' - The resource root element of the resource which called the exported function.
}}

==Syntax==
<syntaxhighlight lang="lua">
var... call ( resource theResource, string theFunction, [ arguments... ] )
</syntaxhighlight>

===Required Arguments===
*'''theResource:''' This is a resource pointer which refers to the resource you are calling a function from.
*'''theFunction:''' This is a string with the name of the function which you want to call.

===Optional Arguments===
{{OptionalArg}}
*'''arguments:''' Any arguments you may want to pass to the function when it is called. Any number of arguments of can be specified, each being passed to the designated function.

===Returns===
Returns anything that the designated function has returned appropriately. If the function does not exist, is not exported, or the call was not successful it will return ''nil''.

==Example==
<section name="Server" class="server" show="true">
This extract shows adding of a "kills" column to the scoreboard resource. This then sets the ''gameShowKills'' variable to true, telling the rest of the script to start outputting kills.

<syntaxhighlight lang="lua">
function showKills ( option )
if option == false then
-- Remove the "kills" column
gameShowKills = false
call(getResourceFromName("scoreboard"), "removeScoreboardColumn", "kills")
else
-- Add the "kills" column
gameShowKills = true
call(getResourceFromName("scoreboard"), "addScoreboardColumn", "kills")
outputDebugString ( "Showing kills now..." )
end
end
</syntaxhighlight>
</section>

==See Also==
{{Resource_functions}}

GuiCreateScrollPane

2010-06-06T02:12:45Z

R3mp:

{{Client function}}
__NOTOC__
This creates a GUI scroll pane.

==Syntax==
<syntaxhighlight lang="lua">
element guiCreateScrollPane( float x, float y, float width, float height, bool relative, [gui-element parent = nil])
</syntaxhighlight>

===Required Arguments===
*'''x:''' the 2D x offset of the GUI scrollpane from its parent. This is affected by the relative argument.
*'''y:''' the 2D y offset of the GUI scrollbar from its parent. This is affected by the relative argument.
*'''width:''' the width of the GUI scrollpane. This is affected by the relative argument.
*'''height:''' the height of the GUI scrollpane. This is affected by the relative argument.
*'''relative:''' whether sizes and positions are relative to their parent's. If this is true, then all measures must be between 0 and 1, representing sizes/positions as a fraction of the parent widget's size.

===Optional Arguments===
*'''parent:''' the gui-element this scrollpane is attached to. By default, it is nil, meaning the widget is attached to the background.

===Returns===
The gui-element if created, otherwise false.

==Example==
<section name="Client" class="client" show="true">
This example creates a small window with a scrollpane on. Using the /fill command you can populate the scrollpane with the names of every player in the server.
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart",resourceRoot,
function()
-- create a window and create a scrollpane on it
local window = guiCreateWindow(5,5,130,150,"",false)
-- the width and height values here are largely irrelevant as the scrollpane will automatically resize when needed
scrollpane = guiCreateScrollPane(0,0,130,150,false,window)
end
)

addCommandHandler("fill",
function()
-- if the scrollpane exists
if scrollpane then
-- delete all the existing labels
for i,v in ipairs(getElementChildren(scrollpane)) do
destroyElement(v)
end

-- for every player in the server
for i,v in ipairs(getElementsByType("player")) do
-- create a label with their name on the scrollpane
guiCreateLabel(5,i*20,90,20,tostring(getPlayerName(v)),false,scrollpane)
end
end
end
)
</syntaxhighlight>
</section>

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

ExecuteCommandHandler

2010-05-31T16:16:20Z

R3mp:

{{Server client function}}
__NOTOC__
This function will call all the attached functions of an existing console command, for a specified player.

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">bool executeCommandHandler ( string commandName, player thePlayer, [ string args ] )</syntaxhighlight>

==Required Arguments==
*'''commandName:''' The name of the command you wish to execute. This is what must be typed into the console to trigger the function.
*'''thePlayer:''' The player that will be presented as executer of the command to the handler function(s) of the command.

==Optional Arguments==
{{OptionalArg}}
* '''args:''' Additional parameters that will be passed to the handler function(s) of the command that is called, separated by a space.
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">bool executeCommandHandler ( string commandName, [ string args ] )</syntaxhighlight>

==Required Arguments==
*'''commandName:''' The name of the command you wish to execute. This is what must be typed into the console to trigger the function.

==Optional Arguments==
{{OptionalArg}}
* '''args:''' Additional parameters that will be passed to the handler function(s) of the command that is called, separated by a space.
</section>
===Returns===
Returns ''true'' if the command handler was called successfully, ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
This example defines a command handler for the command ''createmarker'' (which creates a red marker at the caller's position). It then creates a second command handler ''createmarker2'' which will call the first one.
<syntaxhighlight lang="lua">
-- Define the function that will handle the 'createmarker' command
function consoleCreateMarker ( playerSource, commandName )
-- If a player triggered it (rather than the admin) then
if ( playerSource )
-- Get that player's position
x, y, z = getElementPosition ( playerSource )
-- Create a marker at their position
createMarker ( x, y, z, 0, "checkpoint", 255, 0, 0, 255 )
-- Output it in the chat box
outputChatBox ( "You got a red marker", playerSource )
end
end
-- Add the function as a handler for the command
addCommandHandler ( "createmarker", consoleCreateMarker )

-- Define a second console command that will just call the first.
-- First define the function
function consoleCreateMarker2 ( playerSource, commandName )
-- re-route back to the original
executeCommandHandler ( "createmarker", playerSource )
end
-- Then add it as a handler for the new console command
addCommandHandler ( "createmarker2", consoleCreateMarker2 )
</syntaxhighlight>
</section>

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

GuiDeleteTab

2010-03-07T00:57:59Z

R3mp:

__NOTOC__
{{Client function}}
This function deletes a tab from a tab panel.

==Syntax==
<syntaxhighlight lang="lua">
bool guiDeleteTab ( element tabToDelete, element tabPanel )
</syntaxhighlight>

===Required Arguments===
*'''tabToDelete:''' This is an element representing the tab that you want to delete.
*'''tabPanel:''' This is the [[guiCreateTabPanel|tab panel]] parent that the tab is attached to.

===Returns===
Returns ''true'' the tab was successfully deleted, ''false'' otherwise.

==Example==
This example removes a tab panel if a user LeftCtrl+Clicks a tab panel.
<syntaxhighlight lang="lua">
function deleteTabOnClick ()
if ( getKeyState ( "lctrl" ) == true ) and ( getElementType( source ) == "gui-tab" ) then -- if the user is holding down left control
guiDeleteTab ( source, getElementParent(source) ) -- delete the tab. No need to check if it was actually a tab that was clicked, as this function doesn't work on other controls anyway
end
end
addEventHandler ( "onClientGUIClick", getRootElement(), deleteTabOnClick ) -- add an event handler for clicks
</syntaxhighlight>

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

GetResourceFromName

2010-01-15T14:33:03Z

R3mp: Undo revision 22282 by Bober370 (Talk) this would only work if the code was put in the playerblips resource, making it mostly redundant anyway

__NOTOC__
{{Server client function}}
This function is used to retrieve a resource from its name. A resource's name is the same as its folder or file archive name on the server (without the extension).

==Syntax==
<syntaxhighlight lang="lua">
resource getResourceFromName ( string resourceName )
</syntaxhighlight>

===Required Arguments===
*'''resourceName:''' the name of the resource you wish to get.

===Returns===
Returns the ''resource'' with the specified name, or ''false'' if no resource of that name exists.

==Example==
<section name="Server" class="server" show="true">
This example prints out a message to the chatbox when a resource named ''playerblips'' is started.
<syntaxhighlight lang="lua">
function onStart( theResource )
local blipsResource = getResourceFromName ( "playerblips" ) -- get the resource of name "playerblips"
if ( blipsResource and theResource == blipsResource ) then -- check if the resource started was it
outputChatBox ( "Blips resource started!" )
end
end
addEventHandler ( "onResourceStart", getRootElement(), onStart )
</syntaxhighlight>
</section>

==See Also==
{{Resource_functions}}

Scripting the GUI - Tutorial 2

2010-01-15T01:29:07Z

R3mp:

'''Scripting the GUI - Tutorial 2 (Gates + Keypads)'''

In this tutorial we will look at creating GUI keypads with combination codes for map-defined object gates.
We will be using serverside keycodes, with some client - server interaction to verify the codes and report the outcome.

'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|GUI Scripting Introduction]].'''

[[Image:Gui_keypad_tutorial.png|thumb|GUI Keypad]]

==Setting up the Keypad==
To begin, open up a clientside lua file (if you have been following the [[Introduction to Scripting GUI|GUI Scripting Introduction]], this is gui.lua) to work with.

===Creating the GUI===
By now, GUI creation should seem relatively straight forward, so we will not go over this in too much detail.
As in [[Scripting the GUI - Tutorial 1|Tutorial 1]] we will be using '''absolute''' values in this tutorial.

<syntaxhighlight lang="lua">
function createKeypad()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 142,276
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)
keypadWindow = guiCreateWindow(X,Y,Width,Height,"Keypad",false)

-- don't allow people to resize the keypad
guiWindowSetSizable(keypadWindow,false)

-- create buttons labeled 0-9, "*", "#", "Enter" and "C" (clear)
keypadButton1 = guiCreateButton(13,68,37,36,"1",false,keypadWindow)
keypadButton2 = guiCreateButton(53,68,37,36,"2",false,keypadWindow)
keypadButton3 = guiCreateButton(93,68,37,36,"3",false,keypadWindow)
keypadButton4 = guiCreateButton(13,108,37,36,"4",false,keypadWindow)
keypadButton5 = guiCreateButton(53,108,37,36,"5",false,keypadWindow)
keypadButton6 = guiCreateButton(93,108,37,36,"6",false,keypadWindow)
keypadButton7 = guiCreateButton(13,148,37,36,"7",false,keypadWindow)
keypadButton8 = guiCreateButton(53,148,37,36,"8",false,keypadWindow)
keypadButton9 = guiCreateButton(93,148,37,36,"9",false,keypadWindow)
keypadButtonAsterix = guiCreateButton(13,188,37,36,"*",false,keypadWindow)
keypadButton0 = guiCreateButton(53,188,37,36,"0",false,keypadWindow)
keypadButtonHash = guiCreateButton(93,188,37,36,"#",false,keypadWindow)
keypadButtonExit = guiCreateButton(13,228,37,36,"Exit",false,keypadWindow)
keypadButtonEnter = guiCreateButton(53,228,37,36,"Enter",false,keypadWindow)
keypadButtonClear = guiCreateButton(93,228,37,36,"Clear",false,keypadWindow)

-- create a gridlist to act as a backdrop on the kaypad display
keypadGridlistDisplay = guiCreateGridList(13,25,117,33,false,keypadWindow)
guiGridListSetSelectionMode(keypadGridlistDisplay,2)
guiSetAlpha(keypadGridlistDisplay,0.6)
-- create a label so we can write text on the keypad display
keypadLabelDisplay = guiCreateLabel(14,26,115,30,"Enter Keycode.",false,keypadWindow)
guiLabelSetColor(keypadLabelDisplay,255,000,000)
guiLabelSetVerticalAlign(keypadLabelDisplay,"center")
guiLabelSetHorizontalAlign(keypadLabelDisplay,"center",false)

guiSetVisible(keypadWindow,false)
end

-- create the GUI when the resource starts
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()),createKeypad)
</syntaxhighlight>
As you can see, the keypad consists of 10 numerical keys (0-9), two character keys (* and #), a clear key, an exit key and an enter key.
This means the codes used on the keypad can contain any of these characters (0123456789*#).

===Managing the display===
We will begin by writing a small function to control the display on the keypad.
This is done by encapsulating several methods of changing the text into a single function,
which will enable us to easily add/remove text from the display later on.
<syntaxhighlight lang="lua">
function updateDisplay(text)
-- if we are passing some text
if text then
-- if its a digit or * or #, then append it to the end of the display
if tonumber(text) or text == "*" or text == "#" then
guiSetText(keypadLabelDisplay,guiGetText(keypadLabelDisplay) .. text)
-- otherwise replace the display with the new text
else
guiSetText(keypadLabelDisplay,text)
end
-- if we pass nil, clear the display entirely
else
guiSetText(keypadLabelDisplay,"")
end
end
</syntaxhighlight>
We can now simply call updateDisplay(our text) to change the text on the display, or updateDisplay(nil) to clear it.

===Detecting the clicks===
With so many buttons that do very similar tasks on our keypad, there are two methods available to us for detecting when a player clicks on them.

We could add [[onClientGUIClick]] events for every button individually, as we have done in previous tutorials; Or, alternatively,
we could add a single [[onClientGUIClick]] handle for the window (which is the parent of all our other keypad GUI elements), filter our results to include only the buttons we want and trigger our own custom event.

For the purposes of this tutorial and in the interest of outlining multiple approaches, we will explore the second method, though either one is an acceptable solution.
<syntaxhighlight lang="lua">
addEventHandler("onClientGUIClick",keypadWindow,processKeypadClicks,true)
</syntaxhighlight>
'''Notice the final argument is set to 'true'. This means that clicks on any other elements in the same branch of the tree will also trigger this event handle (eg. clicks on our buttons).'''

Add this line of code into your createKeypad function, after your GUI has been created.

Now that we are detecting all clicks on our GUI, we need to filter out the ones we do not want (ie: clicks on the window or display) and trigger our custom event:
<syntaxhighlight lang="lua">
function processKeypadClicks(button,state)
if button == "left" and state == "up" then
-- if the source of this event is a gui button
if getElementType(source) == "gui-button" then
-- trigger our custom event and send the keypad id of this keypad as an argument
triggerEvent("onKeypadButtonClicked",source,getElementData(keypadWindow,"keypadID"))
end
end
end
</syntaxhighlight>
As you can see, we are now triggering our custom event "onKeypadButtonClicked" whenever a button is clicked on the keypad.
Also note we use element data "keypadID" to differentiate between keypads. This data will need to be set whenever the player is shown a new keypad.
We will cover this in more detail later.

===Handling the clicks===
Much like when using [[triggerServerEvent]] in previous tutorials, we now need to define the event, only this time it is purely clientside:
<syntaxhighlight lang="lua">
addEvent("onKeypadButtonClicked",false)
addEventHandler("onKeypadButtonClicked",root,
function(keypadID)

end
)
</syntaxhighlight>
Note the second argument in [[addEvent]] is set to false, indicating that this event cannot be triggered from the server.
Also note, the function we are using in the [[addEventHandler]] does not have a name. If you contract it down and remove the spacing, you get:
<syntaxhighlight lang="lua">
addEventHandler("onKeypadButtonClicked",root,function() ... end)
</syntaxhighlight>
This simply means instead of storing the pointer to the function in a variable, we are passing it directly as an argument.
Doing it this way cleans up the code and will often make it easier to follow.

Now that the event has been created, we can fill in the code logic that will control our button presses.
<syntaxhighlight lang="lua">
addEvent("onKeypadButtonClicked",false)
addEventHandler("onKeypadButtonClicked",root,
function(keypadID)
-- clear the display if this is the first time its being used
if guiGetText(keypadLabelDisplay) == "Enter Keycode." or guiGetText(keypadLabelDisplay) == "Invalid Keycode." then
updateDisplay()
end

-- if its the clear button
if guiGetText(source) == "Clear" then
-- clear the display
updateDisplay()

-- if its the enter button
elseif guiGetText(source) == "Enter" then
-- get the currently entered code from the display
local code = guiGetText(keypadLabelDisplay)

-- if they have entered a code
if code then
-- trigger the server so we can verify their code
triggerServerEvent("verifyKeypadCode",getLocalPlayer(),code,keypadID)
end

-- if its the exit button
elseif guiGetText(source) == "Exit" then
-- hide the keypad and reset the display text ready for next time
guiSetVisible(keypadWindow,false)
updateDisplay("Enter Keycode.")
showCursor(false,false)

-- otherwise, it must be a character button
else
updateDisplay(guiGetText(source))
end
end
)
</syntaxhighlight>
Note how when we are clearing the display, we simply call updateDisplay() with no arguments. We do not need to pass 'nil' to it as all parameters (and variables) are nil by default.

==Serverside Verification==
For this part of the tutorial, you will need to open up a serverside lua file from your resource to work with.

===Defining the keycode===
Now that we have completed the keypad clicking logic, we need to move on to verifying the code entered into the keypad.
To do this, we need to have the correct code stored somewhere on the server, which we can check the players code against.

'''Do not store sensitive information, such as keycodes or passwords, in a clientside file. All clientside files will be downloaded to the clients computer and can be accessed and read by anyone who has joined your server.'''

For the purposes of this tutorial we will simply store the code in a serverside table, however it can be done any number of ways (such as serverside xml files or MySQL databases).
<syntaxhighlight lang="lua">
local keypadCodes = {
["a51MainGateKeypadCode"] = "4455*#"
}
</syntaxhighlight>
This table stores an entry called "a51MainGateKeypadCode" with the code 4455*#

'''This is the keycode that you will use to open the gate later on in this tutorial.'''

===Verifying the code===
Now that we have a keycode to verify against, we can write our serverside event:
<syntaxhighlight lang="lua">
addEvent("verifyKeypadCode",true)
addEventHandler("verifyKeypadCode",root,function(code,keypadID)
if code then
-- using the table we created earlier, check if the code supplied is the same as the code for this gate
if code == keypadCodes[keypadID] then
-- if it is, tell the client that it was successful
triggerClientEvent(client,"onKeypadVerificationSuccessful",client,keypadID)
else
-- if it is not, tell the client that it was not successful
triggerClientEvent(client,"onKeypadVerificationFailed",client,keypadID)
end
end
end)
</syntaxhighlight>
Here we use our table and the keypadID supplied by the player to check if the codes match.

If you are not using a table to store the codes, then you will need to replace 'keypadCodes[keypadID]' with your own storage method.
Once it is verified (or not), we can trigger the client so the appropriate information can be shown on the keypad display.

==Receiving the result==
We have now finished the serverside section of the tutorial, so you will need to open up the clientside lua file from your resource
that you were previously working on.

Once our code has been verified, the server will send back the response to the client.
In just the same way as client -> server interaction, we now need to add the event that the server is going to trigger on the client.

===Catching and processing the result===
First we will add the event for when the verification is successful:
<syntaxhighlight lang="lua">
addEvent("onKeypadVerificationSuccessful",true)
addEventHandler("onKeypadVerificationSuccessful",root,
function()
-- hide the keypad and reset the display text ready for next time
guiSetVisible(keypadWindow,false)
updateDisplay("Enter Keycode.")
showCursor(false,false)
end
)
</syntaxhighlight>

Finally we can add the event for when the verification is unsuccessful:
<syntaxhighlight lang="lua">
addEvent("onKeypadVerificationFailed",true)
addEventHandler("onKeypadVerificationFailed",root,
function()
-- update the display text to show the code was invalid
updateDisplay("Invalid Keycode.")
end
)
</syntaxhighlight>

This completes the keypad section of the tutorial.

For an example of how to implement this into a working gate system, carry on reading the next section.

==Applying the Keypad==
For the keypad to have any use, we need something to use it on.
For this tutorial we will be using gates, and as mentioned earlier we will create a main gate into A51.

===Creating the gate===
First of all, we need to create the gate object.
For the purposes of this example, we will be using a map file to store the object.
While this is the recommended method for defining objects, it is not the only way to approach it.

Navigate to your resource folder and make a new file called gate.map, then add your new map file to your meta.xml using:
<syntaxhighlight lang="lua">
<map src="gate.map"/>
</syntaxhighlight>

''If you are unsure of map file syntax, please see the [[Writing_Gamemodes| Writing Gamemodes Tutorial]] or check the [[Object]] page for help.''
<syntaxhighlight lang="lua">
<map>
<object id="a51MainGateKeypadCode" model="971" posX="96.736" posY="1918.352" posZ="20.694" rotX="0" rotY="0" rotZ="270.40" newPosX="96.751" newPosY="1914.474" newPosZ="20.694" />
</map>
</syntaxhighlight>
This will create a gate object across the A51 entrance. The object will have position and rotation data, as well as its newPosX,newPosY and newPosZ information that we need to be able to move it.

'''Note that the object id is the same as the table entry we created earlier to hold the access code.'''
This is one possible method that could be accessed to link this gate with that particular keycode.

===Opening the keypad===
Back in the clientside lua file again, we can now work on linking the gate and the keypad.

Now that we have our gate, we need a way of accessing the keypad to open it.
For the purposes of this tutorial we will use a simple command, however you could just as easily use a colshape or button press.
<syntaxhighlight lang="lua">
addCommandHandler("a51gate",function()
guiSetVisible(keypadWindow,true)
showCursor(true,true)
setElementData(keypadWindow,"keypadID","a51MainGateKeypadCode")
end)
</syntaxhighlight>
Note that we set the element data "keypadID".
This is very important because it allows us to keep track of which gate we are trying to open (in this case, the "a51MainGateKeypadCode" gate).

===Opening the gate===
With our gate created and our keypad ready, all thats left now is to open the gate.
Having created custom events earlier for successfully and unsuccessfully verifying the code, this now becomes very easy to do.
All we do is add an event handler for our custom "success" event, and using the keypadID we defined earlier we can move the gate inside it:
<syntaxhighlight lang="lua">
addEventHandler("onKeypadVerificationSuccessful",root,
-- keypadID is sent back from the server
function(keypadID)
-- get the gate object (this is where the id="a51MainGateKeypadCode" tag in the map file becomes useful)
local gate = getElementByID(keypadID)

-- if we found the object
if gate then
-- get the new position (as we defined in the map file)
local x = tonumber(getElementData(gate,"newPosX"))
local y = tonumber(getElementData(gate,"newPosY"))
local z = tonumber(getElementData(gate,"newPosZ"))

-- move the gate
moveObject(gate,1500,x,y,z)

-- get the original position
x = tonumber(getElementData(gate,"posX"))
y = tonumber(getElementData(gate,"posY"))
z = tonumber(getElementData(gate,"posZ"))

-- set a timer to close the gate in 5 seconds
setTimer(moveObject,5000,1,gate,1500,x,y,z)
end
end
)
</syntaxhighlight>
Note how by using the keypadID sent back from the server, we can use if statements and checks against the id to control any number of gates from the same function.

You should now have a working example of a GUI Keypad controlling an A51 Gate.

For further GUI tutorials, see [[Scripting the GUI - Tutorial 3|Tutorial 3 (Scrolling News Feed)]]

[[Category:GUI_Tutorials]]

Introduction to Scripting the GUI

2010-01-15T01:20:58Z

R3mp:

One important feature in MTA:SA is the ability to script customized GUI (Graphic User Interface). The GUI consists of windows, button, edit boxes, check boxes... Almost every standard form components in graphical environments. They can be displayed while the user is in game, and used for inputs and outputs in place of traditional commands.

[[Image:AdminGUI.png|thumb|Admin Console GUI]]

==A tutorial to make a login window==
In this tutorial we'll make a simple login window, with two input boxes and a button. The window appears when the player joins the game, and once the button is clicked, the player is spawned. The tutorial will continue the gamemode we made in [[Scripting Introduction|Introduction to Scripting]] ''(If you have used the [[Scripting Introduction|Introduction to Scripting]], you will need to remove or comment the [[spawnPlayer]] line in the "joinHandler" function in your code, as we will be replacing it with a gui alternative in this tutorial)''. We'll also take a look at client-side scripting.

===Draw the window===
All the GUI must be made client side. It is also a good practice to keep all the client scripts in a separate folder.

Browse to /Your MTA Server/mods/deathmatch/resources/myserver/ directory, and create a folder named "client". Under /client/ directory, create a text file and name it "gui.lua".

In this file we will write a funtion that draws the window. To create a window we will use [[guiCreateWindow]]:
<syntaxhighlight lang="lua">
function createLoginWindow()
-- define the X and Y positions of the window
local X = 0.375
local Y = 0.375
-- define the width and height of the window
local Width = 0.25
local Height = 0.25
-- create the window and save its element value into the variable 'wdwLogin'
-- click on the function's name to read its documentation
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)
end
</syntaxhighlight>

===Relative and Absolute===
Note that the final argument passed to guiCreateWindow in the above example is ''true''. This indicates that the coordinates and dimensions of the window are '''relative''', meaning they are a ''percentage'' of the total screen size. This means that if the far left side of the screen is 0, and the far right is 1, an X position of 0.5 would represent the centre point of the screen. Similarly, if the top of the screen is 0 and the bottom is 1, a Y position of 0.2 would be 20% of the way down the screen. The same principles apply to both Width and Height as well (with a Width value of 0.5 meaning the window will be half as wide as the screen).

The alternative to using relative values is using '''absolute''' (by passing ''false'' instead of true to guiCreateWindow). Absolute values are calculated as the total number of pixels from the top-left corner of the parent (if no gui element parent is specified, the parent is the screen itself). If we assume a screen resolution of 1920x1200, the far left side of the screen being 0 pixels and the far right being 1920 pixels, an X position of 960 will represent the centre point of the screen. Similarly, if the top of the screen is 0 pixels and the bottom is 1200, a Y position of 20 would be 20 pixels down from the top of the screen. The same principles apple to both Width and Height as well (with a Width value of 50 meaning the window will be 50 pixels wide). ''You can use [[guiGetScreenSize]] and a little maths to calculate certain absolute positions.''

The differences between using relative and absolute values is quite simple; gui created using absolute values will always remain exactly the same pixel size and position, while gui created using relative values will always be a percentage of its parent's size.

Absolute is generally easier to maintain when editing code by hand, however your choice of type depends on the situation you are using it for.

For the purposes of this introduction we will be using relative values.

===Adding the components===
Next, we'll add the text labels (saying "username:" and "password:"), edit boxes (for entering your data) and a button to log in.

To create buttons we use [[guiCreateButton]] and to create edit boxes use [[guiCreateEdit]]:

'''Note that we are now writing more code for our existing 'createLoginWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createLoginWindow()
local X = 0.375
local Y = 0.375
local Width = 0.25
local Height = 0.25
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)

-- define new X and Y positions for the first label
X = 0.0825
Y = 0.2
-- define new Width and Height values for the first label
Width = 0.25
Height = 0.25
-- create the first label, note the final argument passed is 'wdwLogin' meaning the window
-- we created above is the parent of this label (so all the position and size values are now relative to the position of that window)
guiCreateLabel(X, Y, Width, Height, "Username", true, wdwLogin)
-- alter the Y value, so the second label is slightly below the first
Y = 0.5
guiCreateLabel(X, Y, Width, Height, "Password", true, wdwLogin)

X = 0.415
Y = 0.2
Width = 0.5
Height = 0.15
edtUser = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
Y = 0.5
edtPass = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
-- set the maximum character length for the username and password fields to 50
guiEditSetMaxLength(edtUser, 50)
guiEditSetMaxLength(edtPass, 50)

X = 0.415
Y = 0.7
Width = 0.25
Height = 0.2
btnLogin = guiCreateButton(X, Y, Width, Height, "Log In", true, wdwLogin)

-- make the window invisible
guiSetVisible(wdwLogin, false)
end
</syntaxhighlight>
Note that every GUI component created is a child of the window, this is done by specifying the parent element (wdwLogin, in this case) when creating the component.

This is very useful because not only does it mean that all the components are attached to the window and will move with it, but also that any changes done to the parent window will be applied down the tree to these child components. For example, we can now hide all of the GUI we just created by simply hiding the window:
<syntaxhighlight lang="lua">
guiSetVisible(wdwLogin, false) --hides all the GUI we made so we can show them to the player at the appropriate moment.
</syntaxhighlight>

===Using the function we wrote===
The createLoginWindow function is now complete, but it won't do anything until we call it. It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed. Therefore, we'll write an event handler for "[[onClientResourceStart]]" to create the window:
<syntaxhighlight lang="lua">
-- attach the event handler to the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
createLoginWindow()
end
)
</syntaxhighlight>

As this is a log in window, we now need to show the window when the player joins the game.
This can be done using the same event, "[[onClientResourceStart]]", so we can modify the above code to include showing the window:

'''Note that we are now writing more code for our existing 'onClientResourceStart' handler. This is not a new event handler and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- create the log in window and its components
createLoginWindow()

-- output a brief welcome message to the player
outputChatBox("Welcome to My MTA:SA Server, please log in.")

-- if the GUI was successfully created, then show the GUI to the player
if (wdwLogin ~= nil) then
guiSetVisible(wdwLogin, true)
else
-- if the GUI hasnt been properly created, tell the player
outputChatBox("An unexpected error has occurred and the log in GUI has not been created.")
end

-- enable the players cursor (so they can select and click on the components)
showCursor(true)
-- set the input focus onto the GUI, allowing players (for example) to press 'T' without the chatbox opening
guiSetInputEnabled(true)
end
)
</syntaxhighlight>

Note that we have a simple security check before making the window visible, so in the unlikely event that the window has not been created, meaning wdwLogin is not a valid element, we don't get an error and just inform the player what has happened.
In the next step, we will create the button functionality for the log in button.

==Scripting the button==
Now that we have created our GUI and shown it to the player, we need to make it work.

===Detecting the click===
When the player clicks on any part of the GUI, the event "[[onClientGUIClick]]" will be triggered for the GUI component you clicked on. This allows us to easily detect any clicks on the GUI elements we want to use.
For example, we can attach the event to the btnLogin button to catch any clicks on it:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to btnLogin and set it to trigger the 'clientSubmitLogin' function
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>
'''Note the final argument passed is "false". This indicates that the event will only trigger directly on btnLogin, not if the event has propagated up or down the tree. Setting this to "true" while attaching to gui elements will mean that clicking on any element in the same branch will trigger this event.'''

This line of code can now be added inside the createLoginWindow function. It is a common mistake to try and attach events to non-existant GUI elements, so make sure you always attach your events '''after''' the gui element (in this case, the button) has been created:

'''Note that we are now writing more code for our existing 'createLoginWindow' function.'''
<syntaxhighlight lang="lua">
function createLoginWindow()
-- create all our GUI elements
...

-- now add our onClientGUIClick event to the button we just created
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>

===Managing the click===
Now that we can detect when the player clicks on the button, we need to write code to manage what happens when they do.
In our [[onClientGUIClick]] event handle, we told it to call the function clientSubmitLogin whenever btnLogin is clicked.
Therefore, we can now use the function clientSubmitLogin to control what happens when the button is clicked:
<syntaxhighlight lang="lua">
-- create the function and define the 'button' and 'state' parameters
-- (these are passed automatically by onClientGUIClick)
function clientSubmitLogin(button,state)
-- if our login button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- move the input focus back onto the game (allowing players to move around, open the chatbox, etc)
guiSetInputEnabled(false)
-- hide the window and all the components
guiSetVisible(wdwLogin, false)
-- hide the mouse cursor
showCursor(false)
end
end
</syntaxhighlight>
Now, when the button is clicked, the window will be hidden and all controls will be returned to the player. Next, we will tell the server to allow the player to spawn.

===Triggering the server===
Triggering the server can be done using [[triggerServerEvent]]. This allows you to trigger a specified event on the server from the client. The same can be done in reverse using [[triggerClientEvent]].
Here, we use the [[triggerServerEvent]] function to call our own custom event on the server, named "submitLogin", which will then control the spawning of the player serverside.

'''Note that we are now writing more code for our existing 'clientSubmitLogin' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function clientSubmitLogin(button,state)
if button == "left" and state == "up" then
-- get the text entered in the 'username' field
local username = guiGetText(edtUser)
-- get the text entered in the 'password' field
local password = guiGetText(edtPass)

-- if the username and password both exist
if username and password then
-- trigger the server event 'submitLogin' and pass the username and password to it
triggerServerEvent("submitLogin", getRootElement(), username, password)

-- hide the gui, hide the cursor and return control to the player
guiSetInputEnabled(false)
guiSetVisible(wdwLogin, false)
showCursor(false)
else
-- otherwise, output a message to the player, do not trigger the server
-- and do not hide the gui
outputChatBox("Please enter a username and password.")
end
end
end
</syntaxhighlight>

===Creating the serverside event===
At this point we now have all the code needed on the client side, so open up your serverside 'script.lua' file (from the [[Scripting Introduction|Introduction to Scripting]]) or another suitable serverside file to work with.

On the server side, recall that we are spawning the player as soon as they login.
So, first of all, we will need to define the custom event that we used before on the client. This can be done using [[addEvent]] and [[addEventHandler]].
<syntaxhighlight lang="lua">
-- create our loginHandler function, with username and password parameters (passed from the client gui)
function loginHandler(username,password)

end

-- define our custom event, and allow it to be triggered from the client ('true')
addEvent("submitLogin",true)
-- add an event handler so that when submitLogin is triggered, the function loginHandler is called
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>

===Logging in===
Now we have a function that is called through the custom event 'submitLogin', we can start to work on logging in and spawning the player, using our 'loginHandler' function:
<syntaxhighlight lang="lua">
function loginHandler(username,password)
-- check that the username and password are correct
if username == "user" and password == "apple" then
-- the player has successfully logged in, so spawn them
if (client) then
spawnPlayer(client, 1959.55, -1714.46, 10)
fadeCamera(client, true)
outputChatBox("Welcome to My Server.", client)
end
else
-- if the username or password are not correct, output a message to the player
outputChatBox("Invalid username and password. Please re-connect and try again.",client)
end
end

addEvent("submitLogin",true)
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>
'''For the purposes of this tutorial, a very basic username and password system is shown. For a more comprehensive alternative, you can use the Account System or a MySQL database.'''

Also note the use of the variable "client", it's an internal variable used by MTA to identify the player who triggered the event.

Finally, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

At this point, we now have a basic login window that checks the player's username and password when the login button is clicked. If they are correct, the player is automatically spawned.

For further help with GUI, see the [[:Category:GUI_Tutorials|GUI tutorials]].

[[Category:GUI_Tutorials]]
[[it:Introduzione_allo_scripting_della_GUI]]
[[ru:Introduction to Scripting the GUI]]

Scripting the GUI - Tutorial 1

2010-01-08T02:46:55Z

R3mp:

'''Scripting the Gui - Tutorial 1 (Gridlists)'''

In this tutorial we will explore the use of gridlists in creating a vehicle selection screen, with optional clientside vehicle xml data reading.

'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|Previous tutorial]].'''

==Setting up the Vehicle Selection==

===Creating the GUI===
To begin, open up a clientside lua file (if you have been following the [[Scripting Introduction]], this is gui.lua) to work with.

In this file, we will start writing our function for creating the GUI.
As covered in the [[Introduction to Scripting GUI|Previous tutorial]], there are 2 value type options available when creating gui: '''relative''' and '''absolute'''.

For the purposes of this tutorial, we will be using '''absolute''' values.

This will create a simple GUI with a window, gridlist and button:
<syntaxhighlight lang="lua">
function createVehicleSelection()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- use some simple maths to position the window in the centre of the screen
local Width,Height = 376,259
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)
windowVehicleSelection = guiCreateWindow(X,Y,Width,Height,"Vehicle Selection Window",false)

gridlistVehicleSelection = guiCreateGridList(10,26,357,192,false,windowVehicleSelection)
-- add a "Vehicle" and a "Type" collumn to the gridlist
guiGridListAddColumn(gridlistVehicleSelection,"Vehicle",0.2)
guiGridListAddColumn(gridlistVehicleSelection,"Type",0.2)

-- set the default width of the columns to roughly half the size of the gridlist (each)
guiGridListSetColumnWidth(gridlistVehicleSelection,1,0.4,true)
guiGridListSetColumnWidth(gridlistVehicleSelection,2,0.5,true)

buttonCreate = guiCreateButton(121,227,120,20,"Create",false,windowVehicleSelection)

-- add the event handler for when the button is clicked
addEventHandler("onClientGUIClick",buttonCreate,createVehicleHandler,false)

-- hide the GUI
guiSetVisible(windowVehicleSelection,false)

-- this will add all the vehicle options onto the gridlist, it is explained later in this tutorial
populateGridlist()
end
</syntaxhighlight>

We now also need to call this function somewhere, otherwise the GUI will never be created.
As in previous tutorials, to do this we can use [[onClientResourceStart]].
<syntaxhighlight lang="lua">
-- when the resource is started, create the GUI and hide it
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()),
function()
createVehicleSelection()
end
)
</syntaxhighlight>

===Showing the GUI===
Unlike in previous tutorials, we want players to be able to open this window whenever they chose, not when the resource starts.
So, we can add a [[addCommandHandler|Command]] to do this.
<syntaxhighlight lang="lua">
-- create the function that will show the window
function showVehicleSelection()
-- if the window isnt visible, show it
if not guiGetVisible(windowVehicleSelection) then
guiSetVisible(windowVehicleSelection,true)

showCursor(true,true)
end
end

-- add the command /vehicleselection and set it to call the showVehicleSelection function
addCommandHandler("vehicleselection",showVehicleSelection)
</syntaxhighlight>

===Populating the Gridlist from a table===
Now that we have our basic GUI created, we need to fill the gridlist with all of our vehicles.

To begin with, we will do this using a simple clientside table.
Later in the tutorial, we will explore expanding this method to use .xml files for storing information.
To begin, we must create a small table containing a selection of vehicles that we can spawn.

The table contains vehicles in the format ["description"] = vehicle_id :
<syntaxhighlight lang="lua">
-- create the table and fill it with a selection of vehicle ids and names
local vehicleSelectionTable = {
["Sparrow"] = 469,
["Stuntplane"] = 513,
["BF-400"] = 581,
["Freeway"] = 463,
["Speeder"] = 452,
["Jester"] = 559,
["Sabre"] = 475,
["Police Ranger"] = 599,
["Utility Van"] = 552,
["Tug"] = 583
}
</syntaxhighlight>
Place this code at the very top of your file (it does not need to be inside a function).

Next, we can write our "populateGridlist" function which will fill the Gridlist with all the vehicles in the table.
To do this we simply need to loop through all the values in the table, adding each one to the gridlist as we go.
We will also set hidden data using [[guiGridListSetItemData]] to store the vehicle id:
<syntaxhighlight lang="lua">
function populateGridlist()
-- loop through the table
for name,vehicle in pairs(vehicleSelectionTable) do
-- add a new row to the gridlist
local row = guiGridListAddRow(gridlistVehicleSelection)

-- set the text in the first column to the vehicle name
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)
-- set the text in the second column to the vehicle type
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(vehicle),false,false)

-- set the data for gridlist slot as the vehicle id
guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(vehicle))
end
end
</syntaxhighlight>

===Managing the click===
Now that we have our GUI completed, we need to be able to catch any clicks made on the "create" button.
We have attached the [[onClientGUIClick]] event to buttonCreate already, so now we need to write the function that it calls.
In this function we do some basic error checking, such as making sure a vehicle has been selected in the list.
We can then use some maths to find a position infront of the player and send the server this information to spawn the vehicle (using [[triggerServerEvent]])
<syntaxhighlight lang="lua">
function createVehicleHandler(button,state)
if button == "left" and state == "up" then
-- get the selected item in the gridlist
local row,col = guiGridListGetSelectedItem(gridlistVehicleSelection)

-- if something is selected
if row and col and row ~= -1 and col ~= -1 then
-- get the vehicle id data from the gridlist that is selected
local selected = guiGridListGetItemData(gridlistVehicleSelection,row,col)

-- make sure the vehicle id is a number not a string
selected = tonumber(selected)

-- get the players position and rotation
local rotz = getPedRotation(getLocalPlayer())
local x,y,z = getElementPosition(getLocalPlayer())
-- find the position directly infront of the player
x = x + ( math.cos ( math.rad ( rotz+90 ) ) * 3)
y = y + ( math.sin ( math.rad ( rotz+90 ) ) * 3)

if selected and x and y and z then
-- trigger the server
triggerServerEvent("createVehicleFromGUI",getRootElement(),selected,x,y,z)

-- hide the gui and the cursor
guiSetVisible(windowVehicleSelection,false)
showCursor(false,false)
else
outputChatBox("Invalid arguments.")
end
else
-- otherwise, output a message to the player
outputChatBox("Please select a vehicle.")
end
end
end
</syntaxhighlight>

===Creating the Vehicle===
At this point we now have all the code needed on the client side, so open up a serverside .lua file to work with.

On the server side, we will first of all need to define the custom event that we triggered before from the client. This can be done using [[addEvent]] and [[addEventHandler]].
Finally we will need a small function for creating the vehicle:
<syntaxhighlight lang="lua">
function createMyVehicle(vehicleid,x,y,z)
-- check all the arguments exist
if vehicleid and x and y and z then
createVehicle(vehicleid,x,y,z)
end
end

addEvent("createVehicleFromGUI",true)
addEventHandler("createVehicleFromGUI",root,createMyVehicle)
</syntaxhighlight>
Note the use of the "root" variable. This is an MTA variable containing the root element; every resource has one.

This completes the first section of the tutorial. You should now have a basic, working vehicle spawn script.

In the second section, we will cover collapsible gridlist data and clientside xml file reading.

==Expanding the code==
This section will detail several ways to improve upon the code you now have.

===Importing Data===
One big improvement over the previously mentioned method is to use external files to store the vehicle information, allowing us to much more quickly and easily manage large amounts of data.
For this tutorial, we will use a clientside xml file to hold the information.

First of all you will need to create your xml file, so navigate to your resources directory and create a new file named vehicles.xml:

''For the purpose of this example, we will include only a small fraction of the total vehicles, however the file can easily be expanded to include them all.''

If you are unsure of xml data structures, you can browse the [[Server_Scripting_Functions#XML_functions| MTA xml functions]] for help.
<syntaxhighlight lang="lua">
<root>
<group type="Bikes">
<vehicle id="581" name="BF-400"/>
<vehicle id="463" name="Freeway"/>
<vehicle id="481" name="BMX"/>
</group>
<group type="Boats">
<vehicle id="472" name="Coastguard"/>
<vehicle id="452" name="Speeder"/>
</group>
<group type="Helicopters">
<vehicle id="487" name="Maverick"/>
<vehicle id="469" name="Sparrow"/>
</group>
<group type="Planes">
<vehicle id="593" name="Dodo"/>
<vehicle id="513" name="Stuntplane"/>
</group>
<group type="Sports Cars">
<vehicle id="565" name="Flash"/>
<vehicle id="559" name="Jester"/>
<vehicle id="477" name="ZR-350"/>
</group>
<group type="2-Door">
<vehicle id="474" name="Hermes"/>
<vehicle id="475" name="Sabre"/>
</group>
<group type="Emergency">
<vehicle id="416" name="Ambulance"/>
<vehicle id="599" name="Police ranger"/>
</group>
<group type="Industrial">
<vehicle id="573" name="Dune"/>
<vehicle id="552" name="Utility van"/>
</group>
<group type="Misc">
<vehicle id="457" name="Caddy"/>
<vehicle id="583" name="Tug"/>
</group>
</root>
</syntaxhighlight>
Once you have created your file, do not forget to add it to the meta.xml of your resource with the appropriate client tag.

Note the group "type" tag. This is an arbitrary description of the vehicles contained within the group and can be renamed or added as any text.
Similarly, the vehicle "name" tag is also just a textual description of the vehicle and does not need to be the exact vehicle name.

Now that we have the data, we can import it into the game and display it in the GUI.
'''If you are following on from the first section of this tutorial, this new code will replace what is inside your existing 'populateGridlist' function.'''
First, we need to load the file:
<syntaxhighlight lang="lua">
function populateGridlist()
-- load the file and save the root node value it returns
local rootnode = xmlLoadFile("vehicles.xml")

-- check that the file exists and has been correctly loaded
if rootnode then
-- unload the xml file
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>
Always make sure you unload any files once you are finished using them.

We can now start collecting the data from the file and entering it into our gridlist.
We can do this by looping through the xml data (in a similar manner to looping through the vehicle table earlier in this tutorial) and adding each entry into the list.
<syntaxhighlight lang="lua">
function populateGridlist()
local rootnode = xmlLoadFile("vehicles.xml")

if rootnode then
-- first, we find every "group" node (they are direct children of the root)
for _,group in ipairs(xmlNodeGetChildren(rootnode)) do
-- add a new row to the gridlist
local row = guiGridListAddRow(gridlistVehicleSelection)

-- get the group name
local name = xmlNodeGetAttribute(group,"type")

-- set the text in the first column to the group type and indicate it is a section ('true')
-- (sections on gridlists show up in bold and cannot be clicked)
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,true,false)

-- then, for every group that we find, loop all of its children (the vehicle nodes)
-- and add them into the gridlist
for _,vehicle in ipairs(xmlNodeGetChildren(group)) do
-- add a new row to the gridlist
row = guiGridListAddRow(gridlistVehicleSelection)

-- get the vehicle name and id
name = xmlNodeGetAttribute(vehicle,"name")
local id = xmlNodeGetAttribute(vehicle,"id")

-- set the text in the first column to the vehicle name
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)
-- set the text in the second column to the vehicle type
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(tonumber(id)),false,false)

-- finally, set the vehicle id as data so we can access it later
guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(id))
end
end

-- unload the xml file now that we are finished
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>
Note the use of for loops in the code with [[xmlNodeGetChildren]]. This saves us a lot of time and effort as we do not have to manually code each group and vehicle into the list.

You should now have a fully working vehicle selection menu, reading all of its data from a clientside xml file.
Next, we will examine how to generate the appearance of collapsing and expanding sections in a gridlist.

===Collapsing/Expanding the Gridlist===
Allowing sections of the gridlist to be collapsed or expanded gives much more control over the visible content to the user.
This frees up space on the screen and makes the whole menu much more comfortable to use.

===Loading the data===
To be able to achieve this effect (as it is not a natural feature of gridlists) we will need to load the vehicle information into a table (from the xml file), rather than directly including it all in the gridlist.
'''If you are following on from a previous section of this tutorial, this new code will replace what is inside your existing 'populateGridlist' function.'''

This works in much the same way the previous xml loading example does, only this time instead of saving the data into the gridlist, we save it into a table entry instead.
We also set the custom data "header" on the gridlist slots to denote which gridlist entries are our "group" entries and which are vehicles.
<syntaxhighlight lang="lua">
function populateGridlist()
local rootnode = xmlLoadFile("vehicles.xml")

-- create a blank global table to store our imported data
vehicleTable = {}

if rootnode then
for _,group in ipairs(xmlNodeGetChildren(rootnode)) do
-- create an entry in the gridlist for every vehicle "group"
local row = guiGridListAddRow(gridlistVehicleSelection)

local name = xmlNodeGetAttribute(group,"type")

guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)

-- add an entry containing the group name into the table
vehicleTable[name] = {}

-- we will use the custom data "header" to indicate that this entry can be expanded/collapsed
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")

-- then, for every group that we find, loop all of its children (the vehicle nodes) and store them in a table
for _,vehicle in ipairs(xmlNodeGetChildren(group)) do
local vname = xmlNodeGetAttribute(vehicle,"name")
local id = xmlNodeGetAttribute(vehicle,"id")

-- insert both the vehicle id and the vehicle description into the table
table.insert(vehicleTable[name],{id,vname})
end
end

-- set element data on the gridlist so we know which group is currently showing
setElementData(gridlistVehicleSelection,"expanded","none")

-- unload the xml file now that we are finished
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>

Now that we have all the data stored, we can quickly manipulate it when neccessary.

===Managing the double click===
To enable the player to simply double click on a group name to expand/collapse it we need to use the [[onClientGUIDoubleClick]] event.
If we attach it to the gridlist, we can then catch any double clicks on the group names in it:
<syntaxhighlight lang="lua">
-- attach the onClientGUIDoubleClick event to the gridlist and set it to call processDoubleClick
addEventHandler("onClientGUIDoubleClick",gridlistVehicleSelection,processDoubleClick,false)
</syntaxhighlight>
Add this line of code in your createVehicleSelection, after the gridlist has been created.

As the gridlist items are not separate GUI elements, we must capture all clicks from anywhere on the gridlist then process them to filter out the ones we do not want.
This can be done by checking if an item is selected, then checking if the item is one of our "group" values (using our previously mentioned "header" data):
<syntaxhighlight lang="lua">
function processDoubleClick(button,state)
if button == "left" and state == "up" then
local row,col = guiGridListGetSelectedItem(gridlistVehicleSelection)

-- if something in the gridlist has been selected
if row and col and row ~= -1 and col ~= -1 then
-- if it is a header
if guiGridListGetItemData(gridlistVehicleSelection,row,col) == "header" then
local selected = guiGridListGetItemText(gridlistVehicleSelection,row,col)

-- call the function to collapse or expand the menu and pass which section it is as an argument
changeGridlistState(selected)
end
end
end
end
</syntaxhighlight>

Once we have narrowed down the double clicks to only those done on our group headers, we can expand/collapse them appropriately.
This can be done by simply setting new text values in the gridlist according to the newly expanded/collapsed group, which creates the convincing illusion of collapsable menus.

Note that much of the following code is reused from previous areas of this tutorial. While it is generally bad practice to clone sections of code in this way, for the purposes of this example it is far easier to understand.
<syntaxhighlight lang="lua">
function changeGridlistState(group)
if group then
-- if the group is already expanded, we want to collapse it
if getElementData(gridlistVehicleSelection,"expanded") == group then
-- first, we clear all previous data from the gridlist
guiGridListClear(gridlistVehicleSelection)

-- now, loop all the group entries in the vehicle table that we created earlier
for group,_ in pairs(vehicleTable) do
-- add each group to the list and mark them with "header"
local row = guiGridListAddRow(gridlistVehicleSelection)

guiGridListSetItemText(gridlistVehicleSelection,row,1,group,false,false)
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")
end

-- update the data to indicate that no groups are currently expanded
setElementData(gridlistVehicleSelection,"expanded","none")

-- otherwise, we want to expand it
else
guiGridListClear(gridlistVehicleSelection)

local row = guiGridListAddRow(gridlistVehicleSelection)

guiGridListSetItemText(gridlistVehicleSelection,row,1,group,false,false)
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")

-- loop every vehicle in the specified groups table
for _,vehicle in ipairs(vehicleTable[group]) do
-- add them to the gridlist and set the vehicle id as data
row = guiGridListAddRow(gridlistVehicleSelection)

-- format a "-" into the string to make it visually easier to distinguish between groups and vehicles
guiGridListSetItemText(gridlistVehicleSelection,row,1,"- "..vehicle[2],false,false)
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(tonumber(vehicle[1])),false,false)

guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(vehicle[1]))
end

-- update the data to indicate which group is currently expanded
setElementData(gridlistVehicleSelection,"expanded",group)
end
end
end
</syntaxhighlight>

This comletes the second section of the tutorial.

For further GUI tutorials, see [[Scripting the GUI - Tutorial 2|Tutorial 2 (Gates and Keypads)]]

[[Category:GUI_Tutorials]]

Introduction to Scripting the GUI - Part 3

2010-01-08T01:53:21Z

R3mp:

'''Introduction to Scripting the GUI - Part 3 (Teleport Window)'''

In this tutorial we will make a simple city teleport window, with 3 buttons (one for each city) that when clicked will teleport you to that city.

'''Note that this tutorial builds on content covered in the [[Introduction to Scripting the GUI|GUI Scripting Introduction]].'''

[[Image:Gui_teleport_tutorial.PNG|thumb|GUI Teleport Window]]

==Making the GUI==

===Getting set up===
The first thing we need to do is create our GUI elements.
For this tutorial we will be using one [[Element/GUI/Window|window]], three [[Element/GUI/Button|buttons]] and one [[Element/GUI/Text_label|label]].
We will be using '''absolute''' position values.

As noted in [[:Category:GUI_Tutorials|Previous tutorials]], all the GUI must be made client side.

If you are following on from that tutorial, open up your gui.lua file to work with.

If you are not, browse to /Your MTA Server/mods/deathmatch/resources/myserver/ directory, and create a folder named "client".
Under /client/ directory, create a text file and name it "gui.lua".

If you have not already done so, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

===Making the window===
In this file we will now write a funtion that creates the window.
To create a window we will use [[guiCreateWindow]]:
<syntaxhighlight lang="lua">
-- create the function that will hold our gui creation code
function createTeleportWindow()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 231,188
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

-- create the window
teleportWindow = guiCreateWindow(X,Y,Width,Height,"City Teleporter",false)

-- stop players from being able to resize the window
guiWindowSetSizable(teleportWindow,false)
end
</syntaxhighlight>
This will create a basic window in the centre of the screen that cannot be resized, with the title "City Teleporter".

===Making the label===
Next, we will add the label describing what the buttons do.
To create a label we will use [[guiCreateLabel]]:

'''Note that we are now writing more code for our existing 'createTeleportWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createTeleportWindow()
local sWidth, sHeight = guiGetScreenSize()

local Width,Height = 231,188
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

teleportWindow = guiCreateWindow(X,Y,Width,Height,"City Teleporter",false)

guiWindowSetSizable(teleportWindow,false)

-- create a label with our instructions on
teleportLabel = guiCreateLabel(18,23,191,33,"Click a button to teleport to that location",false,teleportWindow)

-- set the horizontal alignment of the label to center (ie: in the middle of the window)
-- also note the final argument "true"
-- this turns on wordwrap so if your text goes over the edge of the label, it will wrap around and start a new line automatically
guiLabelSetHorizontalAlign(teleportLabel,"center",true)
end
</syntaxhighlight>
You will now have a simple window with some centered instructions at the top.

===Making the buttons===
Now we need to add the city teleport buttons.
To create a button we will use [[guiCreateButton]]:

'''Note that we are now writing more code for our existing 'createTeleportWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createTeleportWindow()
local sWidth, sHeight = guiGetScreenSize()

local Width,Height = 231,188
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

teleportWindow = guiCreateWindow(X,Y,Width,Height,"City Teleporter",false)

guiWindowSetSizable(teleportWindow,false)

teleportLabel = guiCreateLabel(18,23,191,33,"Click a button to teleport to that location",false,teleportWindow)

guiLabelSetHorizontalAlign(teleportLabel,"center",true)

-- create the button for teleporting to Los Santos
teleportButtonLS = guiCreateButton(18,63,195,35,"Los Santos",false,teleportWindow)

-- slightly below that, create another button for teleporting to San Fierro
teleportButtonSF = guiCreateButton(18,103,195,35,"San Fierro",false,teleportWindow)

-- slightly below that again, create another button for teleport to Las Venturas
teleportButtonLV = guiCreateButton(18,143,195,35,"Las Venturas",false,teleportWindow)

-- hide the gui
guiSetVisible(teleportWindow,false)
end
</syntaxhighlight>

===Using the function we wrote===
Now our 'createTeleportWindow' function is ready, but it wont do anything until we call it.
It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed.

Therefore, we'll write an event handler for [[onClientResourceStart]] to create the window:
<syntaxhighlight lang="lua">
-- add our event handler, using the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- call the createTeleportWindow function to create our gui
createTeleportWindow()
end
)
</syntaxhighlight>
Now that we have our GUI created, we need a way for the players to open the window.

===Opening the GUI===
There are several ways this could be done, depending on your personal preference or the particulars of the situation.
For this tutorial, we will use a simple [[addCommandHandler|command]].

To open the GUI, we will use the command /teleportme :
<syntaxhighlight lang="lua">
-- create our function
function openTeleportWindow()
-- show the window
guiSetVisible(teleportWindow,true)

-- show the mouse cursor
showCursor(true,true)
end

-- define the command /teleportme to call the openTeleportWindow function
addCommandHandler("teleportme",openTeleportWindow)
</syntaxhighlight>
Next, we need to make the buttons actually teleport the player.

==Scripting the button==

Now that we have created our GUI and the players are able to open it, we need to make it work.

===Detecting the click===
As described in previous tutorials, when the player clicks on any part of the GUI, the event "onClientGUIClick" will be triggered for the GUI component you clicked on.
With that in mind, we will attach an event handler to each of our 3 teleport buttons:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to teleportButtonLS and set it to trigger the 'teleportPlayer' function
addEventHandler("onClientGUIClick", teleportButtonLS, teleportPlayer, false)

-- attach the event onClientGUIClick to teleportButtonSF and set it to trigger the 'teleportPlayer' function
addEventHandler("onClientGUIClick", teleportButtonSF, teleportPlayer, false)

-- attach the event onClientGUIClick to teleportButtonLV and set it to trigger the 'teleportPlayer' function
addEventHandler("onClientGUIClick", teleportButtonLV, teleportPlayer, false)
</syntaxhighlight>
Put this code into your 'createTeleportWindow' function, '''after''' the buttons have been created.

Note how we have set all 3 buttons to trigger the 'teleportPlayer' function.

This allows us to easily expand our code later on (for example, to add more teleport locations) with a simple if statement in the function.

===Managing the clicks===
Now that we can detect clicks on all our buttons, we need to manage what happens when we do.

As we just noted, we will do this using the 'teleportPlayer' function.
We will use if statements to check which button has been clicked, then trigger a custom server event with the specified teleport coordinates to move the player:
<syntaxhighlight lang="lua">
-- create our function, and add button and state parameters (these are passed automatically with onClickGUIClick)
function teleportPlayer(button,state)
-- if our button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- if the player clicked on the LS teleport button
if source == teleportButtonLS then

-- trigger the server with our Los Santos coordinates
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),1479.6,-1612.8,14.0,0)

-- output a message to the player
outputChatBox("Welcome to Los Santos!")

-- otherwise, if the player clicked on the SF teleport button
elseif source == teleportButtonSF then

-- trigger the server with our San Fierro coordinates
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),-2265.5,534.0,35.0,270)

-- output a message to the player
outputChatBox("Welcome to San Fierro!")

-- otherwise, if the player clicked on the LV teleport button
elseif source == teleportButtonLV then

-- trigger the server with our Las Venturas coordinates
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),2036.9,1545.2,10.8,270)

-- output a message to the player
outputChatBox("Welcome to Las Venturas!")

end

-- hide the window and all the components
guiSetVisible(teleportWindow, false)

-- hide the mouse cursor
showCursor(false)
end
end
</syntaxhighlight>

If you wanted to add more locations, you could simply add a new button to your GUI and check for it in this function using another if statement.
For example:
<syntaxhighlight lang="lua">
function teleportPlayer(button,state)
if button == "left" and state == "up" then
...

elseif source == yourNewButton then
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),xCoord,yCoord,zCoord,rotation)
end
...
end
end
</syntaxhighlight>

===Creating the serverside event===
At this point we now have all the code needed on the client side,
so open up your serverside 'script.lua' file (from the [[Scripting Introduction|Introduction to Scripting]]) or another suitable serverside file to work with.

On the clientside, we are triggering the server event "movePlayerToPosition". So, we will first define that event.
To do that we will use [[addEvent]], then [[addEventHandler]]:
<syntaxhighlight lang="lua">
-- create our function, with the x,y and z values we passed from the client
function moveThePlayer(x,y,z)

end

-- define our custom event, and allow it to be triggered from the client ('true')
addEvent("movePlayerToPosition",true)
-- add an event handler so that when movePlayerToPosition is triggered, the function moveThePlayer is called
addEventHandler("movePlayerToPosition",root,moveThePlayer)
</syntaxhighlight>

===Moving the player===
Now all that is left is to move the player to their new position.

'''Note that we are now writing more code for our existing 'moveThePlayer' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
-- create our function, with the x,y and z values we passed from the client
function moveThePlayer(x,y,z,rotation)
-- check we have a position and rotation
if x and y and z and rotation then
-- get the players current skin, so we can spawn them again without losing it
local skin = getElementModel(client)

-- spawn the player
spawnPlayer(client,x,y,z,rotation,skin)

-- make sure the players camera is on his character
setCameraTarget(client,client)
end
end
</syntaxhighlight>
Note the use of [[spawnPlayer]] rather than, for example, [[setElementPosition]].
Using [[spawnPlayer]] has several advantages, such as being able to set the position when 'de-spawned' or dead, and automatically refilling health.
Of course, [[setElementPosition]] would work just as well to simply move them, so the choice is yours.

Also note the use of the variable "client", it's an internal variable used by MTA to identify the player who triggered the event.

At this point, you should have a basic teleport window, allowing the player to teleport to any of the 3 major cities in San Andreas.

For further help with GUI, see the [[:Category:GUI_Tutorials|GUI tutorials]].

[[Category:GUI_Tutorials]]

Introduction to Scripting the GUI

2010-01-08T01:48:19Z

R3mp:

One important feature in MTA:SA is the ability to script customized GUI (Graphic User Interface). The GUI consists of windows, button, edit boxes, check boxes... Almost every standard form components in graphical environments. They can be displayed while the user is in game, and used for inputs and outputs in place of traditional commands.

[[Image:AdminGUI.png|thumb|Admin Console GUI]]

==A tutorial to make a login window==
In this tutorial we'll make a simple login window, with two input boxes and a button. The window appears when the player joins the game, and once the button is clicked, the player is spawned. The tutorial will continue the gamemode we made in [[Scripting Introduction|Introduction to Scripting]] ''(If you have used the [[Scripting Introduction|Introduction to Scripting]], you will need to remove or comment the [[spawnPlayer]] line in the "joinHandler" function in your code, as we will be replacing it with a gui alternative in this tutorial)''. We'll also take a look at client-side scripting.

===Draw the window===
All the GUI must be made client side. It is also a good practice to keep all the client scripts in a separate folder.

Browse to /Your MTA Server/mods/deathmatch/resources/myserver/ directory, and create a folder named "client". Under /client/ directory, create a text file and name it "gui.lua".

In this file we will write a funtion that draws the window. To create a window we will use [[guiCreateWindow]]:
<syntaxhighlight lang="lua">
function createLoginWindow()
-- define the X and Y positions of the window
local X = 0.375
local Y = 0.375
-- define the width and height of the window
local Width = 0.25
local Height = 0.25
-- create the window and save its element value into the variable 'wdwLogin'
-- click on the function's name to read its documentation
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)
end
</syntaxhighlight>

===Relative and Absolute===
Note that the final argument passed to guiCreateWindow in the above example is ''true''. This indicates that the coordinates and dimensions of the window are '''relative''', meaning they are a ''percentage'' of the total screen size. This means that if the far left side of the screen is 0, and the far right is 1, an X position of 0.5 would represent the centre point of the screen. Similarly, if the top of the screen is 0 and the bottom is 1, a Y position of 0.2 would be 20% of the way down the screen. The same principles apply to both Width and Height as well (with a Width value of 0.5 meaning the window will be half as wide as the screen).

The alternative to using relative values is using '''absolute''' (by passing ''false'' instead of true to guiCreateWindow). Absolute values are calculated as the total number of pixels from the top-left corner of the parent (if no gui element parent is specified, the parent is the screen itself). If we assume a screen resolution of 1920x1200, the far left side of the screen being 0 pixels and the far right being 1920 pixels, an X position of 960 will represent the centre point of the screen. Similarly, if the top of the screen is 0 pixels and the bottom is 1200, a Y position of 20 would be 20 pixels down from the top of the screen. The same principles apple to both Width and Height as well (with a Width value of 50 meaning the window will be 50 pixels wide). ''You can use [[guiGetScreenSize]] and a little maths to calculate certain absolute positions.''

The differences between using relative and absolute values is quite simple; gui created using absolute values will always remain exactly the same pixel size and position, while gui created using relative values will always be a percentage of its parent's size.

Absolute is generally easier to maintain when editing code by hand, however your choice of type depends on the situation you are using it for.

For the purposes of this introduction we will be using relative values.

===Adding the components===
Next, we'll add the text labels (saying "username:" and "password:"), edit boxes (for entering your data) and a button to log in.

To create buttons we use [[guiCreateButton]] and to create edit boxes use [[guiCreateEdit]]:
<syntaxhighlight lang="lua">
function createLoginWindow()
local X = 0.375
local Y = 0.375
local Width = 0.25
local Height = 0.25
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)

-- define new X and Y positions for the first label
X = 0.0825
Y = 0.2
-- define new Width and Height values for the first label
Width = 0.25
Height = 0.25
-- create the first label, note the final argument passed is 'wdwLogin' meaning the window
-- we created above is the parent of this label (so all the position and size values are now relative to the position of that window)
guiCreateLabel(X, Y, Width, Height, "Username", true, wdwLogin)
-- alter the Y value, so the second label is slightly below the first
Y = 0.5
guiCreateLabel(X, Y, Width, Height, "Password", true, wdwLogin)

X = 0.415
Y = 0.2
Width = 0.5
Height = 0.15
edtUser = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
Y = 0.5
edtPass = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
-- set the maximum character length for the username and password fields to 50
guiEditSetMaxLength(edtUser, 50)
guiEditSetMaxLength(edtPass, 50)

X = 0.415
Y = 0.7
Width = 0.25
Height = 0.2
btnLogin = guiCreateButton(X, Y, Width, Height, "Log In", true, wdwLogin)

-- make the window invisible
guiSetVisible(wdwLogin, false)
end
</syntaxhighlight>
Note that every GUI component created is a child of the window, this is done by specifying the parent element (wdwLogin, in this case) when creating the component.

This is very useful because not only does it mean that all the components are attached to the window and will move with it, but also that any changes done to the parent window will be applied down the tree to these child components. For example, we can now hide all of the GUI we just created by simply hiding the window:
<syntaxhighlight lang="lua">
guiSetVisible(wdwLogin, false) --hides all the GUI we made so we can show them to the player at the appropriate moment.
</syntaxhighlight>

===Using the function we wrote===
The createLoginWindow function is now complete, but it won't do anything until we call it. It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed. Therefore, we'll write an event handler for "[[onClientResourceStart]]" to create the window:
<syntaxhighlight lang="lua">
-- attach the event handler to the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
createLoginWindow()
end
)
</syntaxhighlight>

As this is a log in window, we now need to show the window when the player joins the game.
This can be done using the same event, "[[onClientResourceStart]]", so we can modify the above code to include showing the window:
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- create the log in window and its components
createLoginWindow()

-- output a brief welcome message to the player
outputChatBox("Welcome to My MTA:SA Server, please log in.")

-- if the GUI was successfully created, then show the GUI to the player
if (wdwLogin ~= nil) then
guiSetVisible(wdwLogin, true)
else
-- if the GUI hasnt been properly created, tell the player
outputChatBox("An unexpected error has occurred and the log in GUI has not been created.")
end

-- enable the players cursor (so they can select and click on the components)
showCursor(true)
-- set the input focus onto the GUI, allowing players (for example) to press 'T' without the chatbox opening
guiSetInputEnabled(true)
end
)
</syntaxhighlight>

Note that we have a simple security check before making the window visible, so in the unlikely event that the window has not been created, meaning wdwLogin is not a valid element, we don't get an error and just inform the player what has happened.
In the next step, we will create the button functionality for the log in button.

==Scripting the button==
Now that we have created our GUI and shown it to the player, we need to make it work.

===Detecting the click===
When the player clicks on any part of the GUI, the event "[[onClientGUIClick]]" will be triggered for the GUI component you clicked on. This allows us to easily detect any clicks on the GUI elements we want to use.
For example, we can attach the event to the btnLogin button to catch any clicks on it:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to btnLogin and set it to trigger the 'clientSubmitLogin' function
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>
'''Note the final argument passed is "false". This indicates that the event will only trigger directly on btnLogin, not if the event has propagated up or down the tree. Setting this to "true" while attaching to gui elements will mean that clicking on any element in the same branch will trigger this event.'''

This line of code can now be added inside the createLoginWindow function. It is a common mistake to try and attach events to non-existant GUI elements, so make sure you always attach your events '''after''' the gui element (in this case, the button) has been created:
<syntaxhighlight lang="lua">
function createLoginWindow()
-- create all our GUI elements
...

-- now add our onClientGUIClick event to the button we just created
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>

===Managing the click===
Now that we can detect when the player clicks on the button, we need to write code to manage what happens when they do.
In our [[onClientGUIClick]] event handle, we told it to call the function clientSubmitLogin whenever btnLogin is clicked.
Therefore, we can now use the function clientSubmitLogin to control what happens when the button is clicked:
<syntaxhighlight lang="lua">
-- create the function and define the 'button' and 'state' parameters
-- (these are passed automatically by onClientGUIClick)
function clientSubmitLogin(button,state)
-- if our login button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- move the input focus back onto the game (allowing players to move around, open the chatbox, etc)
guiSetInputEnabled(false)
-- hide the window and all the components
guiSetVisible(wdwLogin, false)
-- hide the mouse cursor
showCursor(false)
end
end
</syntaxhighlight>
Now, when the button is clicked, the window will be hidden and all controls will be returned to the player. Next, we will tell the server to allow the player to spawn.

===Triggering the server===
Triggering the server can be done using [[triggerServerEvent]]. This allows you to trigger a specified event on the server from the client. The same can be done in reverse using [[triggerClientEvent]].
Here, we use the [[triggerServerEvent]] function to call our own custom event on the server, named "submitLogin", which will then control the spawning of the player serverside.
<syntaxhighlight lang="lua">
function clientSubmitLogin(button,state)
if button == "left" and state == "up" then
-- get the text entered in the 'username' field
local username = guiGetText(edtUser)
-- get the text entered in the 'password' field
local password = guiGetText(edtPass)

-- if the username and password both exist
if username and password then
-- trigger the server event 'submitLogin' and pass the username and password to it
triggerServerEvent("submitLogin", getRootElement(), username, password)

-- hide the gui, hide the cursor and return control to the player
guiSetInputEnabled(false)
guiSetVisible(wdwLogin, false)
showCursor(false)
else
-- otherwise, output a message to the player, do not trigger the server
-- and do not hide the gui
outputChatBox("Please enter a username and password.")
end
end
end
</syntaxhighlight>

===Creating the serverside event===
At this point we now have all the code needed on the client side, so open up your serverside 'script.lua' file (from the [[Scripting Introduction|Introduction to Scripting]]) or another suitable serverside file to work with.

On the server side, recall that we are spawning the player as soon as they login.
So, first of all, we will need to define the custom event that we used before on the client. This can be done using [[addEvent]] and [[addEventHandler]].
<syntaxhighlight lang="lua">
-- create our loginHandler function, with username and password parameters (passed from the client gui)
function loginHandler(username,password)

end

-- define our custom event, and allow it to be triggered from the client ('true')
addEvent("submitLogin",true)
-- add an event handler so that when submitLogin is triggered, the function loginHandler is called
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>

===Logging in===
Now we have a function that is called through the custom event 'submitLogin', we can start to work on logging in and spawning the player, using our 'loginHandler' function:
<syntaxhighlight lang="lua">
function loginHandler(username,password)
-- check that the username and password are correct
if username == "user" and password == "apple" then
-- the player has successfully logged in, so spawn them
if (client) then
spawnPlayer(client, 1959.55, -1714.46, 10)
fadeCamera(client, true)
outputChatBox("Welcome to My Server.", client)
end
else
-- if the username or password are not correct, output a message to the player
outputChatBox("Invalid username and password. Please re-connect and try again.",client)
end
end

addEvent("submitLogin",true)
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>
'''For the purposes of this tutorial, a very basic username and password system is shown. For a more comprehensive alternative, you can use the Account System or a MySQL database.'''

Also note the use of the variable "client", it's an internal variable used by MTA to identify the player who triggered the event.

Finally, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

At this point, we now have a basic login window that checks the player's username and password when the login button is clicked. If they are correct, the player is automatically spawned.

For further help with GUI, see the [[:Category:GUI_Tutorials|GUI tutorials]].

[[Category:GUI_Tutorials]]
[[it:Introduzione_allo_scripting_della_GUI]]
[[ru:Introduction to Scripting the GUI]]

Introduction to Scripting the GUI - Part 2

2010-01-08T01:45:25Z

R3mp:

In this tutorial we will make a simple rules window, with an accept button and a list of all the server rules & information.

'''Note that this tutorial builds on content covered in the [[Introduction to Scripting the GUI|GUI Scripting Introduction]].'''

==Making the GUI==

===Getting set up===
The first thing we need to do is create our GUI elements.
For this tutorial we will be using one [[Element/GUI/Window|window]], one [[Element/GUI/Button|button]] and one [[Element/GUI/Text_label|label]].
We will be using '''absolute''' position values.

As noted in the [[Introduction to Scripting the GUI|Previous tutorial]], all the GUI must be made client side.

If you are following on from that tutorial, open up your gui.lua file to work with.

If you are not, browse to /Your MTA Server/mods/deathmatch/resources/myserver/ directory, and create a folder named "client".
Under /client/ directory, create a text file and name it "gui.lua".

If you have not already done so, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

===Making the window===
In this file we will write a funtion that draws the window:
<syntaxhighlight lang="lua">
-- create the function that will hold our gui creation code
function createRulesWindow()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 445,445
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

-- create the window
rulesWindow = guiCreateWindow(X,Y,Width,Height,"Rules",false)

-- stop players from being able to simply move the window out of the way
guiWindowSetMovable(rulesWindow,false)

-- stop players from being able to resize the window
guiWindowSetSizable(rulesWindow,false)
end
</syntaxhighlight>
This will create a basic window in the centre of the screen that cannot be moved and cannot be resized.

===Making the button===
Next, we will add the button to the bottom of our window that players can click on to accept the rules:

'''Note that we are now writing more code for our existing 'createRulesWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createRulesWindow()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 445,445
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

-- create the window and save the window gui element in a variable called 'rulesWindow'
rulesWindow = guiCreateWindow(X,Y,Width,Height,"Rules",false)

-- stop players from being able to simply move the window out of the way
-- note that we use our 'rulesWindow' variable to make changes to the window
guiWindowSetMovable(rulesWindow,false)

-- stop players from being able to resize the window
guiWindowSetSizable(rulesWindow,false)

-- create the button and save the button gui element in a variable called 'rulesButton'
rulesButton = guiCreateButton(137,394,158,37,"Accept",false,rulesWindow)
end
</syntaxhighlight>

===Making the label===
Next, we will add the label to the centre of our window that our rules will be displayed on:

'''Note that we are now writing more code for our existing 'createRulesWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createRulesWindow()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 445,445
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

-- create the window and save the window gui element in a variable called 'rulesWindow'
rulesWindow = guiCreateWindow(X,Y,Width,Height,"Rules",false)

-- stop players from being able to simply move the window out of the way
-- note that we use our 'rulesWindow' variable to make changes to the window
guiWindowSetMovable(rulesWindow,false)

-- stop players from being able to resize the window
guiWindowSetSizable(rulesWindow,false)

-- create the button and save the button gui element in a variable called 'rulesButton'
rulesButton = guiCreateButton(137,394,158,37,"Accept",false,rulesWindow)

-- create the label and save the label gui element in a variable called 'rulesLabel'
-- we set the text of the label to our rules
rulesLabel = guiCreateLabel(10,25,425,359,[[
Welcome to my MTA Server!

Please carefully read the rules before accepting.

By accepting the rules, you are agreeing to play by them.
Anyone caught breaking these rules will be kicked and/or banned from this server.

If you do not accept the rules within 90 seconds, you will be kicked.

1: No cheating.

2: No bug abuse.

3: No mods to your game.

4: No flaming.

5: Respect other players.

6: Be nice!]],false,rulesWindow)

-- set the horizontal alignment of the label to center (ie: in the middle of the window)
-- also note the final argument "true"
-- this turns on wordwrap so if your text goes over the edge of the label, it will wrap around and start a new line automatically
guiLabelSetHorizontalAlign(rulesLabel,"center",true)
end
</syntaxhighlight>

''Note that the text is added in a different way to usual (we are not using quotation marks, "").''

===Text===
There are ''two'' ways to define text for a label.
For most situations, the recommended method is to enter all your text between quotation marks:
<syntaxhighlight lang="lua">
guiSetText(guiElement,"My text here")
</syntaxhighlight>

However, when we want to have more than 1 line in our text, it becomes just as easy to use the second method.
It is purely dependant on situation and personal choice which method you chose.
For clarity's sake, i will briefly outline both here.

When using quotation marks, we can make use of the newline character: "\n"
This allows us to break onto a new line in our text by entering "\n". For example:
<syntaxhighlight lang="lua">
guiSetText(guiElement,"This is line 1. \n This is line 2. \n This is line 3.")
</syntaxhighlight>

However, if we use brackets to enclose the text instead of quotation marks, we do not need to worry about entering any extra characters.
We can simply type the text out as we want it to appear in the label. For example:
<syntaxhighlight lang="lua">
guiSetText(guiElement,[[This is line 1.
This is line 2.
This is line 3.]])
</syntaxhighlight>

Both of these examples will create exactly the same text on the label.
It is entirely up to you which method you chose to use.

===Using the function we wrote===
The createRulesWindow function is now complete, but it won't do anything until we call it.
It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed.

Therefore, we'll write an event handler for [[onClientResourceStart]] to create the window:
<syntaxhighlight lang="lua">
-- attach the event handler to the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- call the createRulesWindow function to create our gui
createRulesWindow()
end
)
</syntaxhighlight>

As this is a rules window, we need to show the window when the player joins the game.
Fortunately, GUI elements are visible by default so we do not need to write any more code to achieve this.

However, we will also need to show the cursor for the player.
This can be done using the same event, [[onClientResourceStart]], so we can modify the above code to include showing the cursor:

'''Note that we are now writing more code for our 'onClientResourceStart' event. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
-- attach the event handler to the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- call the createRulesWindow function to create our gui
createRulesWindow()

-- show the cursor to the player
showCursor(true,true)
end
)
</syntaxhighlight>

We now have a completed GUI rules window. Next, we need to write the button functionality for the accept button.

==Scripting the Button==
Now that we have created our GUI, we need to make it work.

===Detecting the click===
When the player clicks on any part of the GUI, the event "[[onClientGUIClick]]" will be triggered for the GUI component you clicked on. This allows us to easily detect any clicks on the GUI elements we want to use.
For example, we can attach the event to the 'rulesButton' button to catch any clicks on it:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to rulesButton and set it to trigger the 'acceptRules' function
addEventHandler("onClientGUIClick", rulesButton, acceptRules, false)
</syntaxhighlight>
'''Note the final argument passed is "false". This indicates that the event will only trigger directly on rulesButton, not if the event has propagated up or down the tree. Setting this to "true" while attaching to gui elements will mean that clicking on any element in the same branch will trigger this event.'''

This line of code can now be added inside the 'createRulesWindow' function. It is a common mistake to try and attach events to non-existant GUI elements, so make sure you always attach your events '''after''' the GUI element (in this case, the button) has been created:
<syntaxhighlight lang="lua">
function createRulesWindow()
-- create all our GUI elements
...

-- now add our onClientGUIClick event to the button we just created
addEventHandler("onClientGUIClick", rulesButton, acceptRules, false)
</syntaxhighlight>

===Managing the click===
Now that we can detect when the player clicks on the button, we need to write code to manage what happens when they do.
In our [[onClientGUIClick]] event handle, we told it to call the function 'acceptRules' whenever 'rulesButton' is clicked.
Therefore, we can now use the function 'acceptRules' to control what happens when the button is clicked:
<syntaxhighlight lang="lua">
-- create the function and define the 'button' and 'state' parameters
-- (these are passed automatically by onClientGUIClick)
function acceptRules(button,state)
-- if our accept button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- hide the window and all the components
guiSetVisible(rulesWindow, false)

-- hide the mouse cursor
showCursor(false,false)

-- output a message to the player
outputChatBox("Thank you for accepting our rules. Have fun!")

-- if the warning timer exists
if rulesWarningTimer then
-- stop the timer and set the variable to nil
-- this is the timer used to kick players who do not accept the rules. We will cover this in more detail in the next section.
killTimer(rulesWarningTimer)
rulesWarningTimer = nil
end
end
end
</syntaxhighlight>
Now, when the button is clicked, the window and the cursor will be hidden.

==Checking for agreement==
Currently, our window will show when the player joins the server, and they must click accept to remove it.
However, if they do not accept it they can stay in the server indefinately with the window open.

===Setting a timer===
To combat this, we will add a timer using [[setTimer]] to kick them from the server after a period of time if they have not accepted the rules.
First, we will need a global variable to store the timer pointer:
<syntaxhighlight lang="lua">
local rulesWarningTimer = nil
</syntaxhighlight>
Put this line at the very top of your script (it does not need to be inside a function)

Next, we will create our timer:

'''Note that we are now writing more code for our existing 'createRulesWindow' function.'''
<syntaxhighlight lang="lua">
function createRulesWindow()
-- create all of our gui
...

-- set a timer for 30 seconds and set it to call our 'inactivePlayer' function with "1" as an argument
rulesWarningTimer = setTimer(inactivePlayer,30000,1,1)
end
</syntaxhighlight>
Put this [[setTimer]] line at the bottom of your 'createRulesWindow' function.
This will create a timer that will trigger after 30 seconds.

===Giving a warning===
Now we will write our 'inactivePlayer' function, to administer warnings to the player and finally kick him if he does not accept:
<syntaxhighlight lang="lua">
-- create our function and define the 'status' parameter
-- the value of status will be passed from our setTimer function call
function inactivePlayer(status)
-- if status is 1 (this means it is the first warning)
if status == 1 then
-- output a warning
outputChatBox("Please accept our rules or be kicked.")

-- set another timer to call inactivePlayer in another 30 seconds, with "2" as an argument
rulesWarningTimer = setTimer(inactivePlayer,30000,1,2)

-- if status is 2 (the second warning)
elseif status == 2 then
-- output a final warning
outputChatBox("FINAL WARNING: Please accept our rules or be kicked.")

-- set a final timer to call inactivePlayer in another 30 seconds, with "3" as an argument
rulesWarningTimer = setTimer(inactivePlayer,30000,1,3)
elseif status == 3 then
-- trigger the server so we can kick the player
triggerServerEvent("clientKickInactivePlayer",getLocalPlayer())
end
end
</syntaxhighlight>
Note the use of [[triggerServerEvent]] to call the server. You should have experience with client-server interaction from the [[Introduction to Scripting the GUI|Previous tutorial]].
If not, you can go back and read the full explanation there.

We have now completed all the clientside code for this tutorial.

===Kicking the player===
We now need to catch the event on the server that we triggered from the client, so open up a serverside lua file to work with.

To begin, we will add the event on the server:
<syntaxhighlight lang="lua">
-- add the event, note the final argument "true" indicates it can be triggered from the client
addEvent("clientKickInactivePlayer",true)
-- add an event handler for this event to trigger the kickInactivePlayer function
addEventHandler("clientKickInactivePlayer",root,kickInactivePlayer)
</syntaxhighlight>
'''Make sure you add your event handler after you have defined your 'kickInactivePlayer' function.'''

Note the use of [[addEvent]] and [[addEventHandler]] on the server. You should have experience with client-server interaction from the [[Introduction to Scripting the GUI|Previous tutorial]].
If not, you can go back and read the full explanation there.

Finally, we will add the 'kickInactivePlayer' function to control kicking of the player:
<syntaxhighlight lang="lua">
-- create our function
function kickInactivePlayer()
-- kick the player
kickPlayer(client,"Please accept our rules.")
end
</syntaxhighlight>
Note the use of the 'client' variable, this is an MTA variable that holds the value of the client (player) that triggered the event.

'''Note that [[kickPlayer]] will require your resource to have kick access in your ACL.'''

'''This is most easily accomplished by adding your resource into your admin group in the ACL:'''
<syntaxhighlight lang="xml">
<group name="Admin">
...
<object name="resource.YourResourceName" />
...
</group>
</syntaxhighlight>
For more information on the [[ACL]], see the [[ACL]] wiki page.

That concludes this tutorial. You should now have a fully working rules window for your server.

For further help with GUI, see the [[:Category:GUI_Tutorials|GUI tutorials]].

[[Category:GUI_Tutorials]]

Introduction to Scripting the GUI

2010-01-08T01:45:10Z

R3mp:

One important feature in MTA:SA is the ability to script customized GUI (Graphic User Interface). The GUI consists of windows, button, edit boxes, check boxes... Almost every standard form components in graphical environments. They can be displayed while the user is in game, and used for inputs and outputs in place of traditional commands.

[[Image:AdminGUI.png|thumb|Admin Console GUI]]

==A tutorial to make a login window==
In this tutorial we'll make a simple login window, with two input boxes and a button. The window appears when the player joins the game, and once the button is clicked, the player is spawned. The tutorial will continue the gamemode we made in [[Scripting Introduction|Introduction to Scripting]] ''(If you have used the [[Scripting Introduction|Introduction to Scripting]], you will need to remove or comment the [[spawnPlayer]] line in the "joinHandler" function in your code, as we will be replacing it with a gui alternative in this tutorial)''. We'll also take a look at client-side scripting.

===Draw the window===
All the GUI must be made client side. It is also a good practice to keep all the client scripts in a separate folder. Browse to /Your MTA Server/mods/deathmatch/resources/myserver/ directory, and create a folder named "client". Under /client/ directory, create a text file and name it "gui.lua", and in this file we will write a funtion that draws the window:
<syntaxhighlight lang="lua">
function createLoginWindow()
-- define the X and Y positions of the window
local X = 0.375
local Y = 0.375
-- define the width and height of the window
local Width = 0.25
local Height = 0.25
-- create the window and save its element value into the variable 'wdwLogin'
-- click on the function's name to read its documentation
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)
end
</syntaxhighlight>

===Relative and Absolute===
Note that the final argument passed to guiCreateWindow in the above example is ''true''. This indicates that the coordinates and dimensions of the window are '''relative''', meaning they are a ''percentage'' of the total screen size. This means that if the far left side of the screen is 0, and the far right is 1, an X position of 0.5 would represent the centre point of the screen. Similarly, if the top of the screen is 0 and the bottom is 1, a Y position of 0.2 would be 20% of the way down the screen. The same principles apply to both Width and Height as well (with a Width value of 0.5 meaning the window will be half as wide as the screen).

The alternative to using relative values is using '''absolute''' (by passing ''false'' instead of true to guiCreateWindow). Absolute values are calculated as the total number of pixels from the top-left corner of the parent (if no gui element parent is specified, the parent is the screen itself). If we assume a screen resolution of 1920x1200, the far left side of the screen being 0 pixels and the far right being 1920 pixels, an X position of 960 will represent the centre point of the screen. Similarly, if the top of the screen is 0 pixels and the bottom is 1200, a Y position of 20 would be 20 pixels down from the top of the screen. The same principles apple to both Width and Height as well (with a Width value of 50 meaning the window will be 50 pixels wide). ''You can use [[guiGetScreenSize]] and a little maths to calculate certain absolute positions.''

The differences between using relative and absolute values is quite simple; gui created using absolute values will always remain exactly the same pixel size and position, while gui created using relative values will always be a percentage of its parent's size.

Absolute is generally easier to maintain when editing code by hand, however your choice of type depends on the situation you are using it for.

For the purposes of this introduction we will be using relative values.

===Adding the components===
Next, we'll add the text labels (saying "username:" and "password:"), edit boxes (for entering your data) and a button to log in:
<syntaxhighlight lang="lua">
function createLoginWindow()
local X = 0.375
local Y = 0.375
local Width = 0.25
local Height = 0.25
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)

-- define new X and Y positions for the first label
X = 0.0825
Y = 0.2
-- define new Width and Height values for the first label
Width = 0.25
Height = 0.25
-- create the first label, note the final argument passed is 'wdwLogin' meaning the window
-- we created above is the parent of this label (so all the position and size values are now relative to the position of that window)
guiCreateLabel(X, Y, Width, Height, "Username", true, wdwLogin)
-- alter the Y value, so the second label is slightly below the first
Y = 0.5
guiCreateLabel(X, Y, Width, Height, "Password", true, wdwLogin)

X = 0.415
Y = 0.2
Width = 0.5
Height = 0.15
edtUser = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
Y = 0.5
edtPass = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
-- set the maximum character length for the username and password fields to 50
guiEditSetMaxLength(edtUser, 50)
guiEditSetMaxLength(edtPass, 50)

X = 0.415
Y = 0.7
Width = 0.25
Height = 0.2
btnLogin = guiCreateButton(X, Y, Width, Height, "Log In", true, wdwLogin)

-- make the window invisible
guiSetVisible(wdwLogin, false)
end
</syntaxhighlight>
Note that every GUI component created is a child of the window, this is done by specifying the parent element (wdwLogin, in this case) when creating the component.

This is very useful because not only does it mean that all the components are attached to the window and will move with it, but also that any changes done to the parent window will be applied down the tree to these child components. For example, we can now hide all of the GUI we just created by simply hiding the window:
<syntaxhighlight lang="lua">
guiSetVisible(wdwLogin, false) --hides all the GUI we made so we can show them to the player at the appropriate moment.
</syntaxhighlight>

===Using the function we wrote===
The createLoginWindow function is now complete, but it won't do anything until we call it. It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed. Therefore, we'll write an event handler for "[[onClientResourceStart]]" to create the window:
<syntaxhighlight lang="lua">
-- attach the event handler to the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
createLoginWindow()
end
)
</syntaxhighlight>

As this is a log in window, we now need to show the window when the player joins the game.
This can be done using the same event, "[[onClientResourceStart]]", so we can modify the above code to include showing the window:
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- create the log in window and its components
createLoginWindow()

-- output a brief welcome message to the player
outputChatBox("Welcome to My MTA:SA Server, please log in.")

-- if the GUI was successfully created, then show the GUI to the player
if (wdwLogin ~= nil) then
guiSetVisible(wdwLogin, true)
else
-- if the GUI hasnt been properly created, tell the player
outputChatBox("An unexpected error has occurred and the log in GUI has not been created.")
end

-- enable the players cursor (so they can select and click on the components)
showCursor(true)
-- set the input focus onto the GUI, allowing players (for example) to press 'T' without the chatbox opening
guiSetInputEnabled(true)
end
)
</syntaxhighlight>

Note that we have a simple security check before making the window visible, so in the unlikely event that the window has not been created, meaning wdwLogin is not a valid element, we don't get an error and just inform the player what has happened.
In the next step, we will create the button functionality for the log in button.

==Scripting the button==
Now that we have created our GUI and shown it to the player, we need to make it work.

===Detecting the click===
When the player clicks on any part of the GUI, the event "[[onClientGUIClick]]" will be triggered for the GUI component you clicked on. This allows us to easily detect any clicks on the GUI elements we want to use.
For example, we can attach the event to the btnLogin button to catch any clicks on it:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to btnLogin and set it to trigger the 'clientSubmitLogin' function
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>
'''Note the final argument passed is "false". This indicates that the event will only trigger directly on btnLogin, not if the event has propagated up or down the tree. Setting this to "true" while attaching to gui elements will mean that clicking on any element in the same branch will trigger this event.'''

This line of code can now be added inside the createLoginWindow function. It is a common mistake to try and attach events to non-existant GUI elements, so make sure you always attach your events '''after''' the gui element (in this case, the button) has been created:
<syntaxhighlight lang="lua">
function createLoginWindow()
-- create all our GUI elements
...

-- now add our onClientGUIClick event to the button we just created
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>

===Managing the click===
Now that we can detect when the player clicks on the button, we need to write code to manage what happens when they do.
In our [[onClientGUIClick]] event handle, we told it to call the function clientSubmitLogin whenever btnLogin is clicked.
Therefore, we can now use the function clientSubmitLogin to control what happens when the button is clicked:
<syntaxhighlight lang="lua">
-- create the function and define the 'button' and 'state' parameters
-- (these are passed automatically by onClientGUIClick)
function clientSubmitLogin(button,state)
-- if our login button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- move the input focus back onto the game (allowing players to move around, open the chatbox, etc)
guiSetInputEnabled(false)
-- hide the window and all the components
guiSetVisible(wdwLogin, false)
-- hide the mouse cursor
showCursor(false)
end
end
</syntaxhighlight>
Now, when the button is clicked, the window will be hidden and all controls will be returned to the player. Next, we will tell the server to allow the player to spawn.

===Triggering the server===
Triggering the server can be done using [[triggerServerEvent]]. This allows you to trigger a specified event on the server from the client. The same can be done in reverse using [[triggerClientEvent]].
Here, we use the [[triggerServerEvent]] function to call our own custom event on the server, named "submitLogin", which will then control the spawning of the player serverside.
<syntaxhighlight lang="lua">
function clientSubmitLogin(button,state)
if button == "left" and state == "up" then
-- get the text entered in the 'username' field
local username = guiGetText(edtUser)
-- get the text entered in the 'password' field
local password = guiGetText(edtPass)

-- if the username and password both exist
if username and password then
-- trigger the server event 'submitLogin' and pass the username and password to it
triggerServerEvent("submitLogin", getRootElement(), username, password)

-- hide the gui, hide the cursor and return control to the player
guiSetInputEnabled(false)
guiSetVisible(wdwLogin, false)
showCursor(false)
else
-- otherwise, output a message to the player, do not trigger the server
-- and do not hide the gui
outputChatBox("Please enter a username and password.")
end
end
end
</syntaxhighlight>

===Creating the serverside event===
At this point we now have all the code needed on the client side, so open up your serverside 'script.lua' file (from the [[Scripting Introduction|Introduction to Scripting]]) or another suitable serverside file to work with.

On the server side, recall that we are spawning the player as soon as they login.
So, first of all, we will need to define the custom event that we used before on the client. This can be done using [[addEvent]] and [[addEventHandler]].
<syntaxhighlight lang="lua">
-- create our loginHandler function, with username and password parameters (passed from the client gui)
function loginHandler(username,password)

end

-- define our custom event, and allow it to be triggered from the client ('true')
addEvent("submitLogin",true)
-- add an event handler so that when submitLogin is triggered, the function loginHandler is called
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>

===Logging in===
Now we have a function that is called through the custom event 'submitLogin', we can start to work on logging in and spawning the player, using our 'loginHandler' function:
<syntaxhighlight lang="lua">
function loginHandler(username,password)
-- check that the username and password are correct
if username == "user" and password == "apple" then
-- the player has successfully logged in, so spawn them
if (client) then
spawnPlayer(client, 1959.55, -1714.46, 10)
fadeCamera(client, true)
outputChatBox("Welcome to My Server.", client)
end
else
-- if the username or password are not correct, output a message to the player
outputChatBox("Invalid username and password. Please re-connect and try again.",client)
end
end

addEvent("submitLogin",true)
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>
'''For the purposes of this tutorial, a very basic username and password system is shown. For a more comprehensive alternative, you can use the Account System or a MySQL database.'''

Also note the use of the variable "client", it's an internal variable used by MTA to identify the player who triggered the event.

Finally, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

At this point, we now have a basic login window that checks the player's username and password when the login button is clicked. If they are correct, the player is automatically spawned.

For further help with GUI, see the [[:Category:GUI_Tutorials|GUI tutorials]].

[[Category:GUI_Tutorials]]
[[it:Introduzione_allo_scripting_della_GUI]]
[[ru:Introduction to Scripting the GUI]]

Introduction to Scripting the GUI - Part 3

2010-01-08T01:44:51Z

R3mp:

'''Introduction to Scripting the GUI - Part 3 (Teleport Window)'''

In this tutorial we will make a simple city teleport window, with 3 buttons (one for each city) that when clicked will teleport you to that city.

'''Note that this tutorial builds on content covered in the [[Introduction to Scripting the GUI|GUI Scripting Introduction]].'''

[[Image:Gui_teleport_tutorial.PNG|thumb|GUI Teleport Window]]

==Making the GUI==

===Getting set up===
The first thing we need to do is create our GUI elements.
For this tutorial we will be using one [[Element/GUI/Window|window]], three [[Element/GUI/Button|buttons]] and one [[Element/GUI/Text_label|label]].
We will be using '''absolute''' position values.

As noted in the [[Introduction to Scripting the GUI|Previous tutorial]], all the GUI must be made client side.

If you are following on from that tutorial, open up your gui.lua file to work with.

If you are not, browse to /Your MTA Server/mods/deathmatch/resources/myserver/ directory, and create a folder named "client".
Under /client/ directory, create a text file and name it "gui.lua".

If you have not already done so, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

===Making the window===
In this file we will now write a funtion that creates the window.
To create a window we will use [[guiCreateWindow]]:
<syntaxhighlight lang="lua">
-- create the function that will hold our gui creation code
function createTeleportWindow()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 231,188
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

-- create the window
teleportWindow = guiCreateWindow(X,Y,Width,Height,"City Teleporter",false)

-- stop players from being able to resize the window
guiWindowSetSizable(teleportWindow,false)
end
</syntaxhighlight>
This will create a basic window in the centre of the screen that cannot be resized, with the title "City Teleporter".

===Making the label===
Next, we will add the label describing what the buttons do.
To create a label we will use [[guiCreateLabel]]:

'''Note that we are now writing more code for our existing 'createTeleportWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createTeleportWindow()
local sWidth, sHeight = guiGetScreenSize()

local Width,Height = 231,188
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

teleportWindow = guiCreateWindow(X,Y,Width,Height,"City Teleporter",false)

guiWindowSetSizable(teleportWindow,false)

-- create a label with our instructions on
teleportLabel = guiCreateLabel(18,23,191,33,"Click a button to teleport to that location",false,teleportWindow)

-- set the horizontal alignment of the label to center (ie: in the middle of the window)
-- also note the final argument "true"
-- this turns on wordwrap so if your text goes over the edge of the label, it will wrap around and start a new line automatically
guiLabelSetHorizontalAlign(teleportLabel,"center",true)
end
</syntaxhighlight>
You will now have a simple window with some centered instructions at the top.

===Making the buttons===
Now we need to add the city teleport buttons.
To create a button we will use [[guiCreateButton]]:

'''Note that we are now writing more code for our existing 'createTeleportWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createTeleportWindow()
local sWidth, sHeight = guiGetScreenSize()

local Width,Height = 231,188
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

teleportWindow = guiCreateWindow(X,Y,Width,Height,"City Teleporter",false)

guiWindowSetSizable(teleportWindow,false)

teleportLabel = guiCreateLabel(18,23,191,33,"Click a button to teleport to that location",false,teleportWindow)

guiLabelSetHorizontalAlign(teleportLabel,"center",true)

-- create the button for teleporting to Los Santos
teleportButtonLS = guiCreateButton(18,63,195,35,"Los Santos",false,teleportWindow)

-- slightly below that, create another button for teleporting to San Fierro
teleportButtonSF = guiCreateButton(18,103,195,35,"San Fierro",false,teleportWindow)

-- slightly below that again, create another button for teleport to Las Venturas
teleportButtonLV = guiCreateButton(18,143,195,35,"Las Venturas",false,teleportWindow)

-- hide the gui
guiSetVisible(teleportWindow,false)
end
</syntaxhighlight>

===Using the function we wrote===
Now our 'createTeleportWindow' function is ready, but it wont do anything until we call it.
It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed.

Therefore, we'll write an event handler for [[onClientResourceStart]] to create the window:
<syntaxhighlight lang="lua">
-- add our event handler, using the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- call the createTeleportWindow function to create our gui
createTeleportWindow()
end
)
</syntaxhighlight>
Now that we have our GUI created, we need a way for the players to open the window.

===Opening the GUI===
There are several ways this could be done, depending on your personal preference or the particulars of the situation.
For this tutorial, we will use a simple [[addCommandHandler|command]].

To open the GUI, we will use the command /teleportme :
<syntaxhighlight lang="lua">
-- create our function
function openTeleportWindow()
-- show the window
guiSetVisible(teleportWindow,true)

-- show the mouse cursor
showCursor(true,true)
end

-- define the command /teleportme to call the openTeleportWindow function
addCommandHandler("teleportme",openTeleportWindow)
</syntaxhighlight>
Next, we need to make the buttons actually teleport the player.

==Scripting the button==

Now that we have created our GUI and the players are able to open it, we need to make it work.

===Detecting the click===
As described in previous tutorials, when the player clicks on any part of the GUI, the event "onClientGUIClick" will be triggered for the GUI component you clicked on.
With that in mind, we will attach an event handler to each of our 3 teleport buttons:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to teleportButtonLS and set it to trigger the 'teleportPlayer' function
addEventHandler("onClientGUIClick", teleportButtonLS, teleportPlayer, false)

-- attach the event onClientGUIClick to teleportButtonSF and set it to trigger the 'teleportPlayer' function
addEventHandler("onClientGUIClick", teleportButtonSF, teleportPlayer, false)

-- attach the event onClientGUIClick to teleportButtonLV and set it to trigger the 'teleportPlayer' function
addEventHandler("onClientGUIClick", teleportButtonLV, teleportPlayer, false)
</syntaxhighlight>
Put this code into your 'createTeleportWindow' function, '''after''' the buttons have been created.

Note how we have set all 3 buttons to trigger the 'teleportPlayer' function.

This allows us to easily expand our code later on (for example, to add more teleport locations) with a simple if statement in the function.

===Managing the clicks===
Now that we can detect clicks on all our buttons, we need to manage what happens when we do.

As we just noted, we will do this using the 'teleportPlayer' function.
We will use if statements to check which button has been clicked, then trigger a custom server event with the specified teleport coordinates to move the player:
<syntaxhighlight lang="lua">
-- create our function, and add button and state parameters (these are passed automatically with onClickGUIClick)
function teleportPlayer(button,state)
-- if our button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- if the player clicked on the LS teleport button
if source == teleportButtonLS then

-- trigger the server with our Los Santos coordinates
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),1479.6,-1612.8,14.0,0)

-- output a message to the player
outputChatBox("Welcome to Los Santos!")

-- otherwise, if the player clicked on the SF teleport button
elseif source == teleportButtonSF then

-- trigger the server with our San Fierro coordinates
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),-2265.5,534.0,35.0,270)

-- output a message to the player
outputChatBox("Welcome to San Fierro!")

-- otherwise, if the player clicked on the LV teleport button
elseif source == teleportButtonLV then

-- trigger the server with our Las Venturas coordinates
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),2036.9,1545.2,10.8,270)

-- output a message to the player
outputChatBox("Welcome to Las Venturas!")

end

-- hide the window and all the components
guiSetVisible(teleportWindow, false)

-- hide the mouse cursor
showCursor(false)
end
end
</syntaxhighlight>

If you wanted to add more locations, you could simply add a new button to your GUI and check for it in this function using another if statement.
For example:
<syntaxhighlight lang="lua">
function teleportPlayer(button,state)
if button == "left" and state == "up" then
...

elseif source == yourNewButton then
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),xCoord,yCoord,zCoord,rotation)
end
...
end
end
</syntaxhighlight>

===Creating the serverside event===
At this point we now have all the code needed on the client side,
so open up your serverside 'script.lua' file (from the [[Scripting Introduction|Introduction to Scripting]]) or another suitable serverside file to work with.

On the clientside, we are triggering the server event "movePlayerToPosition". So, we will first define that event.
To do that we will use [[addEvent]], then [[addEventHandler]]:
<syntaxhighlight lang="lua">
-- create our function, with the x,y and z values we passed from the client
function moveThePlayer(x,y,z)

end

-- define our custom event, and allow it to be triggered from the client ('true')
addEvent("movePlayerToPosition",true)
-- add an event handler so that when movePlayerToPosition is triggered, the function moveThePlayer is called
addEventHandler("movePlayerToPosition",root,moveThePlayer)
</syntaxhighlight>

===Moving the player===
Now all that is left is to move the player to their new position.

'''Note that we are now writing more code for our existing 'moveThePlayer' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
-- create our function, with the x,y and z values we passed from the client
function moveThePlayer(x,y,z,rotation)
-- check we have a position and rotation
if x and y and z and rotation then
-- get the players current skin, so we can spawn them again without losing it
local skin = getElementModel(client)

-- spawn the player
spawnPlayer(client,x,y,z,rotation,skin)

-- make sure the players camera is on his character
setCameraTarget(client,client)
end
end
</syntaxhighlight>
Note the use of [[spawnPlayer]] rather than, for example, [[setElementPosition]].
Using [[spawnPlayer]] has several advantages, such as being able to set the position when 'de-spawned' or dead, and automatically refilling health.
Of course, [[setElementPosition]] would work just as well to simply move them, so the choice is yours.

Also note the use of the variable "client", it's an internal variable used by MTA to identify the player who triggered the event.

At this point, you should have a basic teleport window, allowing the player to teleport to any of the 3 major cities in San Andreas.

For further help with GUI, see the [[:Category:GUI_Tutorials|GUI tutorials]].

[[Category:GUI_Tutorials]]

Introduction to Scripting the GUI - Part 3

2010-01-08T01:41:35Z

R3mp:

'''Introduction to Scripting the GUI - Part 3 (Teleport Window)'''

In this tutorial we will make a simple city teleport window, with 3 buttons (one for each city) that when clicked will teleport you to that city.

'''Note that this tutorial builds on content covered in the [[Introduction to Scripting the GUI|GUI Scripting Introduction]].'''

[[Image:Gui_teleport_tutorial.PNG|thumb|GUI Teleport Window]]

==Making the GUI==

===Getting set up===
The first thing we need to do is create our GUI elements.
For this tutorial we will be using one [[Element/GUI/Window|window]], three [[Element/GUI/Button|buttons]] and one [[Element/GUI/Text_label|label]].
We will be using '''absolute''' position values.

As noted in the [[Introduction to Scripting the GUI|Previous tutorial]], all the GUI must be made client side.

If you are following on from that tutorial, open up your gui.lua file to work with.

If you are not, browse to /Your MTA Server/mods/deathmatch/resources/myserver/ directory, and create a folder named "client".
Under /client/ directory, create a text file and name it "gui.lua".

If you have not already done so, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

===Making the window===
In this file we will now write a funtion that creates the window.
To create a window we will use [[guiCreateWindow]]:
<syntaxhighlight lang="lua">
-- create the function that will hold our gui creation code
function createTeleportWindow()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 231,188
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

-- create the window
teleportWindow = guiCreateWindow(X,Y,Width,Height,"City Teleporter",false)

-- stop players from being able to resize the window
guiWindowSetSizable(teleportWindow,false)
end
</syntaxhighlight>
This will create a basic window in the centre of the screen that cannot be resized, with the title "City Teleporter".

===Making the label===
Next, we will add the label describing what the buttons do.
To create a label we will use [[guiCreateLabel]]:

'''Note that we are now writing more code for our existing 'createTeleportWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createTeleportWindow()
local sWidth, sHeight = guiGetScreenSize()

local Width,Height = 231,188
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

teleportWindow = guiCreateWindow(X,Y,Width,Height,"City Teleporter",false)

guiWindowSetSizable(teleportWindow,false)

-- create a label with our instructions on
teleportLabel = guiCreateLabel(18,23,191,33,"Click a button to teleport to that location",false,teleportWindow)

-- set the horizontal alignment of the label to center (ie: in the middle of the window)
-- also note the final argument "true"
-- this turns on wordwrap so if your text goes over the edge of the label, it will wrap around and start a new line automatically
guiLabelSetHorizontalAlign(teleportLabel,"center",true)
end
</syntaxhighlight>
You will now have a simple window with some centered instructions at the top.

===Making the buttons===
Now we need to add the city teleport buttons.
To create a button we will use [[guiCreateButton]]:

'''Note that we are now writing more code for our existing 'createTeleportWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createTeleportWindow()
local sWidth, sHeight = guiGetScreenSize()

local Width,Height = 231,188
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

teleportWindow = guiCreateWindow(X,Y,Width,Height,"City Teleporter",false)

guiWindowSetSizable(teleportWindow,false)

teleportLabel = guiCreateLabel(18,23,191,33,"Click a button to teleport to that location",false,teleportWindow)

guiLabelSetHorizontalAlign(teleportLabel,"center",true)

-- create the button for teleporting to Los Santos
teleportButtonLS = guiCreateButton(18,63,195,35,"Los Santos",false,teleportWindow)

-- slightly below that, create another button for teleporting to San Fierro
teleportButtonSF = guiCreateButton(18,103,195,35,"San Fierro",false,teleportWindow)

-- slightly below that again, create another button for teleport to Las Venturas
teleportButtonLV = guiCreateButton(18,143,195,35,"Las Venturas",false,teleportWindow)

-- hide the gui
guiSetVisible(teleportWindow,false)
end
</syntaxhighlight>

===Using the function we wrote===
Now our 'createTeleportWindow' function is ready, but it wont do anything until we call it.
It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed.

Therefore, we'll write an event handler for [[onClientResourceStart]] to create the window:
<syntaxhighlight lang="lua">
-- add our event handler, using the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- call the createTeleportWindow function to create our gui
createTeleportWindow()
end
)
</syntaxhighlight>
Now that we have our GUI created, we need a way for the players to open the window.

===Opening the GUI===
There are several ways this could be done, depending on your personal preference or the particulars of the situation.
For this tutorial, we will use a simple [[addCommandHandler|command]].

To open the GUI, we will use the command /teleportme :
<syntaxhighlight lang="lua">
-- create our function
function openTeleportWindow()
-- show the window
guiSetVisible(teleportWindow,true)

-- show the mouse cursor
showCursor(true,true)
end

-- define the command /teleportme to call the openTeleportWindow function
addCommandHandler("teleportme",openTeleportWindow)
</syntaxhighlight>
Next, we need to make the buttons actually teleport the player.

==Scripting the button==

Now that we have created our GUI and the players are able to open it, we need to make it work.

===Detecting the click===
As described in previous tutorials, when the player clicks on any part of the GUI, the event "onClientGUIClick" will be triggered for the GUI component you clicked on.
With that in mind, we will attach an event handler to each of our 3 teleport buttons:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to teleportButtonLS and set it to trigger the 'teleportPlayer' function
addEventHandler("onClientGUIClick", teleportButtonLS, teleportPlayer, false)

-- attach the event onClientGUIClick to teleportButtonSF and set it to trigger the 'teleportPlayer' function
addEventHandler("onClientGUIClick", teleportButtonSF, teleportPlayer, false)

-- attach the event onClientGUIClick to teleportButtonLV and set it to trigger the 'teleportPlayer' function
addEventHandler("onClientGUIClick", teleportButtonLV, teleportPlayer, false)
</syntaxhighlight>
Put this code into your 'createTeleportWindow' function, '''after''' the buttons have been created.

Note how we have set all 3 buttons to trigger the 'teleportPlayer' function.

This allows us to easily expand our code later on (for example, to add more teleport locations) with a simple if statement in the function.

===Managing the clicks===
Now that we can detect clicks on all our buttons, we need to manage what happens when we do.

As we just noted, we will do this using the 'teleportPlayer' function.
We will use if statements to check which button has been clicked, then trigger a custom server event with the specified teleport coordinates to move the player:
<syntaxhighlight lang="lua">
-- create our function, and add button and state parameters (these are passed automatically with onClickGUIClick)
function teleportPlayer(button,state)
-- if our button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- if the player clicked on the LS teleport button
if source == teleportButtonLS then

-- trigger the server with our Los Santos coordinates
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),1479.6,-1612.8,14.0,0)

-- output a message to the player
outputChatBox("Welcome to Los Santos!")

-- otherwise, if the player clicked on the SF teleport button
elseif source == teleportButtonSF then

-- trigger the server with our San Fierro coordinates
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),-2265.5,534.0,35.0,270)

-- output a message to the player
outputChatBox("Welcome to San Fierro!")

-- otherwise, if the player clicked on the LV teleport button
elseif source == teleportButtonLV then

-- trigger the server with our Las Venturas coordinates
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),2036.9,1545.2,10.8,270)

-- output a message to the player
outputChatBox("Welcome to Las Venturas!")

end

-- hide the window and all the components
guiSetVisible(teleportWindow, false)

-- hide the mouse cursor
showCursor(false)
end
end
</syntaxhighlight>

If you wanted to add more locations, you could simply add a new button to your GUI and check for it in this function using another if statement.
For example:
<syntaxhighlight lang="lua">
function teleportPlayer(button,state)
if button == "left" and state == "up" then
...

elseif source == yourNewButton then
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),xCoord,yCoord,zCoord,rotation)
end
...
end
end
</syntaxhighlight>

===Creating the serverside event===
At this point we now have all the code needed on the client side,
so open up your serverside 'script.lua' file (from the [[Scripting Introduction|Introduction to Scripting]]) or another suitable serverside file to work with.

On the clientside, we are triggering the server event "movePlayerToPosition". So, we will first define that event.
To do that we will use [[addEvent]], then [[addEventHandler]]:
<syntaxhighlight lang="lua">
-- create our function, with the x,y and z values we passed from the client
function moveThePlayer(x,y,z)

end

-- define our custom event, and allow it to be triggered from the client ('true')
addEvent("movePlayerToPosition",true)
-- add an event handler so that when movePlayerToPosition is triggered, the function moveThePlayer is called
addEventHandler("movePlayerToPosition",root,moveThePlayer)
</syntaxhighlight>

===Moving the player===
Now all that is left is to move the player to their new position.

'''Note that we are now writing more code for our existing 'moveThePlayer' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
-- create our function, with the x,y and z values we passed from the client
function moveThePlayer(x,y,z,rotation)
-- check we have a position and rotation
if x and y and z and rotation then
-- get the players current skin, so we can spawn them again without losing it
local skin = getElementModel(client)

-- spawn the player
spawnPlayer(client,x,y,z,rotation,skin)

-- make sure the players camera is on his character
setCameraTarget(client,client)
end
end
</syntaxhighlight>
Note the use of [[spawnPlayer]] rather than, for example, [[setElementPosition]].
Using [[spawnPlayer]] has several advantages, such as being able to set the position when 'de-spawned' or dead, and automatically refilling health.
Of course, [[setElementPosition]] would work just as well to simply move them, so the choice is yours.

Also note the use of the variable "client", it's an internal variable used by MTA to identify the player who triggered the event.

At this point, you should have a basic teleport window, allowing the player to teleport to any of the 3 major cities in San Andreas.

[[Category:GUI_Tutorials]]

File:Gui teleport tutorial.PNG

2010-01-08T01:39:01Z

R3mp:

Category:GUI Tutorials

2010-01-08T01:38:38Z

R3mp:

These are a set of tutorials with information on how to include and manipulate [[GUI widgets|GUI elements]] in your resources.

'''Beginner Tutorials:'''
** [[Introduction to Scripting the GUI|Introduction to Scripting the GUI (Login Window)]]
** [[Introduction to Scripting the GUI - Part 2|Introduction to Scripting the GUI - Part 2 (Rules Window)]]
** [[Introduction to Scripting the GUI - Part 3|Introduction to Scripting the GUI - Part 3 (Teleport Window)]]

'''Novice Tutorials:'''
** [[Scripting the GUI - Tutorial 1|Scripting the GUI - Tutorial 1 (Gridlists)]]
** [[Scripting the GUI - Tutorial 2|Scripting the GUI - Tutorial 2 (Gates + Keypads)]]
** [[Scripting the GUI - Tutorial 3|Scripting the GUI - Tutorial 3 (Scrolling News Feed)]]

Introduction to Scripting the GUI - Part 3

2010-01-08T01:38:09Z

R3mp: Created page with ''''Introduction to Scripting the GUI - Part 3 (Teleport Window)''' In this tutorial we will make a simple city teleport window, with 3 buttons (one for each city) that when clic…'

'''Introduction to Scripting the GUI - Part 3 (Teleport Window)'''

In this tutorial we will make a simple city teleport window, with 3 buttons (one for each city) that when clicked will teleport you to that city.

'''Note that this tutorial builds on content covered in the [[Introduction to Scripting the GUI|GUI Scripting Introduction]].'''

==Making the GUI==

===Getting set up===
The first thing we need to do is create our GUI elements.
For this tutorial we will be using one [[Element/GUI/Window|window]], three [[Element/GUI/Button|buttons]] and one [[Element/GUI/Text_label|label]].
We will be using '''absolute''' position values.

As noted in the [[Introduction to Scripting the GUI|Previous tutorial]], all the GUI must be made client side.

If you are following on from that tutorial, open up your gui.lua file to work with.

If you are not, browse to /Your MTA Server/mods/deathmatch/resources/myserver/ directory, and create a folder named "client".
Under /client/ directory, create a text file and name it "gui.lua".

If you have not already done so, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

===Making the window===
In this file we will now write a funtion that creates the window.
To create a window we will use [[guiCreateWindow]]:
<syntaxhighlight lang="lua">
-- create the function that will hold our gui creation code
function createTeleportWindow()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 231,188
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

-- create the window
teleportWindow = guiCreateWindow(X,Y,Width,Height,"City Teleporter",false)

-- stop players from being able to resize the window
guiWindowSetSizable(teleportWindow,false)
end
</syntaxhighlight>
This will create a basic window in the centre of the screen that cannot be resized, with the title "City Teleporter".

===Making the label===
Next, we will add the label describing what the buttons do.
To create a label we will use [[guiCreateLabel]]:

'''Note that we are now writing more code for our existing 'createTeleportWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createTeleportWindow()
local sWidth, sHeight = guiGetScreenSize()

local Width,Height = 231,188
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

teleportWindow = guiCreateWindow(X,Y,Width,Height,"City Teleporter",false)

guiWindowSetSizable(teleportWindow,false)

-- create a label with our instructions on
teleportLabel = guiCreateLabel(18,23,191,33,"Click a button to teleport to that location",false,teleportWindow)

-- set the horizontal alignment of the label to center (ie: in the middle of the window)
-- also note the final argument "true"
-- this turns on wordwrap so if your text goes over the edge of the label, it will wrap around and start a new line automatically
guiLabelSetHorizontalAlign(teleportLabel,"center",true)
end
</syntaxhighlight>
You will now have a simple window with some centered instructions at the top.

===Making the buttons===
Now we need to add the city teleport buttons.
To create a button we will use [[guiCreateButton]]:

'''Note that we are now writing more code for our existing 'createTeleportWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createTeleportWindow()
local sWidth, sHeight = guiGetScreenSize()

local Width,Height = 231,188
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

teleportWindow = guiCreateWindow(X,Y,Width,Height,"City Teleporter",false)

guiWindowSetSizable(teleportWindow,false)

teleportLabel = guiCreateLabel(18,23,191,33,"Click a button to teleport to that location",false,teleportWindow)

guiLabelSetHorizontalAlign(teleportLabel,"center",true)

-- create the button for teleporting to Los Santos
teleportButtonLS = guiCreateButton(18,63,195,35,"Los Santos",false,teleportWindow)

-- slightly below that, create another button for teleporting to San Fierro
teleportButtonSF = guiCreateButton(18,103,195,35,"San Fierro",false,teleportWindow)

-- slightly below that again, create another button for teleport to Las Venturas
teleportButtonLV = guiCreateButton(18,143,195,35,"Las Venturas",false,teleportWindow)

-- hide the gui
guiSetVisible(teleportWindow,false)
end
</syntaxhighlight>

===Using the function we wrote===
Now our 'createTeleportWindow' function is ready, but it wont do anything until we call it.
It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed.

Therefore, we'll write an event handler for [[onClientResourceStart]] to create the window:
<syntaxhighlight lang="lua">
-- add our event handler, using the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- call the createTeleportWindow function to create our gui
createTeleportWindow()
end
)
</syntaxhighlight>
Now that we have our GUI created, we need a way for the players to open the window.

===Opening the GUI===
There are several ways this could be done, depending on your personal preference or the particulars of the situation.
For this tutorial, we will use a simple [[addCommandHandler|command]].

To open the GUI, we will use the command /teleportme :
<syntaxhighlight lang="lua">
-- create our function
function openTeleportWindow()
-- show the window
guiSetVisible(teleportWindow,true)

-- show the mouse cursor
showCursor(true,true)
end

-- define the command /teleportme to call the openTeleportWindow function
addCommandHandler("teleportme",openTeleportWindow)
</syntaxhighlight>
Next, we need to make the buttons actually teleport the player.

==Scripting the button==

Now that we have created our GUI and the players are able to open it, we need to make it work.

===Detecting the click===
As described in previous tutorials, when the player clicks on any part of the GUI, the event "onClientGUIClick" will be triggered for the GUI component you clicked on.
With that in mind, we will attach an event handler to each of our 3 teleport buttons:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to teleportButtonLS and set it to trigger the 'teleportPlayer' function
addEventHandler("onClientGUIClick", teleportButtonLS, teleportPlayer, false)

-- attach the event onClientGUIClick to teleportButtonSF and set it to trigger the 'teleportPlayer' function
addEventHandler("onClientGUIClick", teleportButtonSF, teleportPlayer, false)

-- attach the event onClientGUIClick to teleportButtonLV and set it to trigger the 'teleportPlayer' function
addEventHandler("onClientGUIClick", teleportButtonLV, teleportPlayer, false)
</syntaxhighlight>
Put this code into your 'createTeleportWindow' function, '''after''' the buttons have been created.

Note how we have set all 3 buttons to trigger the 'teleportPlayer' function.

This allows us to easily expand our code later on (for example, to add more teleport locations) with a simple if statement in the function.

===Managing the clicks===
Now that we can detect clicks on all our buttons, we need to manage what happens when we do.

As we just noted, we will do this using the 'teleportPlayer' function.
We will use if statements to check which button has been clicked, then trigger a custom server event with the specified teleport coordinates to move the player:
<syntaxhighlight lang="lua">
-- create our function, and add button and state parameters (these are passed automatically with onClickGUIClick)
function teleportPlayer(button,state)
-- if our button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- if the player clicked on the LS teleport button
if source == teleportButtonLS then

-- trigger the server with our Los Santos coordinates
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),1479.6,-1612.8,14.0,0)

-- output a message to the player
outputChatBox("Welcome to Los Santos!")

-- otherwise, if the player clicked on the SF teleport button
elseif source == teleportButtonSF then

-- trigger the server with our San Fierro coordinates
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),-2265.5,534.0,35.0,270)

-- output a message to the player
outputChatBox("Welcome to San Fierro!")

-- otherwise, if the player clicked on the LV teleport button
elseif source == teleportButtonLV then

-- trigger the server with our Las Venturas coordinates
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),2036.9,1545.2,10.8,270)

-- output a message to the player
outputChatBox("Welcome to Las Venturas!")

end

-- hide the window and all the components
guiSetVisible(teleportWindow, false)

-- hide the mouse cursor
showCursor(false)
end
end
</syntaxhighlight>

If you wanted to add more locations, you could simply add a new button to your GUI and check for it in this function using another if statement.
For example:
<syntaxhighlight lang="lua">
function teleportPlayer(button,state)
if button == "left" and state == "up" then
...

elseif source == yourNewButton then
triggerServerEvent("movePlayerToPosition",getLocalPlayer(),xCoord,yCoord,zCoord,rotation)
end
...
end
end
</syntaxhighlight>

===Creating the serverside event===
At this point we now have all the code needed on the client side,
so open up your serverside 'script.lua' file (from the [[Scripting Introduction|Introduction to Scripting]]) or another suitable serverside file to work with.

On the clientside, we are triggering the server event "movePlayerToPosition". So, we will first define that event.
To do that we will use [[addEvent]], then [[addEventHandler]]:
<syntaxhighlight lang="lua">
-- create our function, with the x,y and z values we passed from the client
function moveThePlayer(x,y,z)

end

-- define our custom event, and allow it to be triggered from the client ('true')
addEvent("movePlayerToPosition",true)
-- add an event handler so that when movePlayerToPosition is triggered, the function moveThePlayer is called
addEventHandler("movePlayerToPosition",root,moveThePlayer)
</syntaxhighlight>

===Moving the player===
Now all that is left is to move the player to their new position.

'''Note that we are now writing more code for our existing 'moveThePlayer' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
-- create our function, with the x,y and z values we passed from the client
function moveThePlayer(x,y,z,rotation)
-- check we have a position and rotation
if x and y and z and rotation then
-- get the players current skin, so we can spawn them again without losing it
local skin = getElementModel(client)

-- spawn the player
spawnPlayer(client,x,y,z,rotation,skin)

-- make sure the players camera is on his character
setCameraTarget(client,client)
end
end
</syntaxhighlight>
Note the use of [[spawnPlayer]] rather than, for example, [[setElementPosition]].
Using [[spawnPlayer]] has several advantages, such as being able to set the position when 'de-spawned' or dead, and automatically refilling health.
Of course, [[setElementPosition]] would work just as well to simply move them, so the choice is yours.

Also note the use of the variable "client", it's an internal variable used by MTA to identify the player who triggered the event.

At this point, you should have a basic teleport window, allowing the player to teleport to any of the 3 major cities in San Andreas.

[[Category:GUI_Tutorials]]

Category:GUI Tutorials

2010-01-06T11:57:11Z

R3mp:

These are a set of tutorials with information on how to include and manipulate [[GUI widgets|GUI elements]] in your resources.

'''Beginner Tutorials:'''
** [[Introduction to Scripting the GUI|Introduction to Scripting the GUI (Login Window)]]
** [[Introduction to Scripting the GUI - Part 2|Introduction to Scripting the GUI - Part 2 (Rules Window)]]

'''Novice Tutorials:'''
** [[Scripting the GUI - Tutorial 1|Scripting the GUI - Tutorial 1 (Gridlists)]]
** [[Scripting the GUI - Tutorial 2|Scripting the GUI - Tutorial 2 (Gates + Keypads)]]
** [[Scripting the GUI - Tutorial 3|Scripting the GUI - Tutorial 3 (Scrolling News Feed)]]

Category:GUI Tutorials

2010-01-06T01:23:55Z

R3mp:

These are a set of tutorials with information on how to include and manipulate [[GUI widgets|GUI elements]] in your resources.

'''Beginner Tutorials:'''
** [[Introduction to Scripting the GUI]]
** [[Introduction to Scripting the GUI - Part 2]]

'''Novice Tutorials:'''
** [[Scripting the GUI - Tutorial 1|Scripting the GUI - Tutorial 1 (Gridlists)]]
** [[Scripting the GUI - Tutorial 2|Scripting the GUI - Tutorial 2 (Gates + Keypads)]]
** [[Scripting the GUI - Tutorial 3|Scripting the GUI - Tutorial 3 (Scrolling News Feed)]]

Introduction to Scripting the GUI - Part 2

2010-01-06T01:06:14Z

R3mp:

Scripting the GUI - Tutorial 3

2010-01-06T01:04:29Z

R3mp:

'''Scripting the GUI - Tutorial 3 (Scrolling News Feed)'''

In this tutorial we will explore how to create a simple scrolling news feed GUI,
allowing you to quickly and easily show server updates and other server information to your players.
We will store all news items in a clientside xml file and use some simple xml reading to load them into the game.

We will then animate the news item to scroll along the bottom of the screen, updating the news text once it has scrolled beyond the edge of the screen.

'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|GUI Scripting Introduction]].'''

==Setting up the News Feed==
To begin, open up a clientside lua file (if you have been following the [[Introduction to Scripting GUI|GUI Scripting Introduction]], this is gui.lua) to work with.

===Creating the GUI===
As with the previous tutorial, you should be suitably familiar with GUI creation already so we will not go into too much detail here.
<syntaxhighlight lang="lua">
function createNewsFeed()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the gridlist, using some maths to find the bottom-centre of the screen
local Width,Height = 800,45
local X = (sWidth/2) - (Width/2)
local Y = sHeight - (Height/2)

-- the gridlist will act as the background to our news reel
newsGridlist = guiCreateGridList(X,Y,Width,Height,false)

-- create the label in the same place, but as a child of the gridlist
-- also make it half the height of the gridlist, as half of the gridlist is off the bottom of the screen
newsLabel = guiCreateLabel(X,Y,Width,Height/2,"Test text",false,newsGridlist)

-- call our function to read the news out of the xml file
loadNews()

-- load the first news item in the table
updateNewsItem(1)

-- define a global variable called 'currentItem' with the value 1
currentItem = 1
end

addEventHandler("onClientResourceStart",resourceRoot,createNewsFeed)
</syntaxhighlight>
Note that the label is created as a child of the gridlist.
Not only is this good practice in general, but it means that we can freely move parts of the label beyond the edge of the gridlist without them showing, which is critical to the visual effect of this tutorial.

Also notice the use of the 'resourceRoot' variable. This is an MTA variable that holds the root element value of the resource you are using it in.

The 'currentItem' variable is what we will use to keep track of which news item we are currently showing

===Writing the News===
Now that we have our GUI created, we need some news to fill it with.
To do this, we will read our news items out of a clientside xml file.

So, navigate to your resource directory and create a new xml file called newsfeed.xml (don't forget to add it to your meta.xml with the appropriate client tag).

Inside this file enter the following information:
<syntaxhighlight lang="lua">
<root>
<news>This is an example news item.</news>
<news>From the 'Scripting the GUI' tutorial.</news>
<news>Showing scrolling news text.</news>
<news>Written on a GUI news feed.</news>
</root>
</syntaxhighlight>
As you can see, each news item is defined as a <news> node with the value being the news text you want to display.
There is no limit on how many news items you can add.

===Collecting the News===
Once we have written all our news items, we will need to collect them all and store them in a table on the client.
We will do this when the resource starts, saving us from having to repeatedly access the xml for new news items.

First, we need to define a table to store the items in:
<syntaxhighlight lang="lua">
local newsItems = {}
</syntaxhighlight>
Add this line to the top of your script.
Make sure it is not inside a function otherwise it will not exist outside of that function (as denoted by the prefix "local").
When defined in the main body of the script it will exist in all functions.

Next, we will need to load the xml file:
<syntaxhighlight lang="lua">
function loadNews()
-- load our "newsfeed.xml" file
local newsfile = xmlLoadFile("newsfeed.xml")

-- if it was successfully loaded
if newsfile then

-- always remember to unload files once you are finished
xmlUnloadFile(newsfile)
end
end
</syntaxhighlight>
'''Always remember to unload files once you are finished using them.'''

Finally, we can add some more code to our loadNews function to read the news items into our newsItems table:
<syntaxhighlight lang="lua">
function loadNews()
local newsfile = xmlLoadFile("newsfeed.xml")

if newsfile then
-- loop through all the children of the root node (the "news" nodes)
for index,itemNode in ipairs(xmlNodeGetChildren(newsfile)) do
-- get the text (the news item) from the node
local item = xmlNodeGetValue(itemNode)

-- insert it into our newsItems table
table.insert(newsItems,item)
end

xmlUnloadFile(newsfile)
end
end
</syntaxhighlight>
We now have a table called 'newsItems' holding all of our news text from the xml file.

==Updating the News==
Now that we have our GUI created and our news items ready, we need to write some code to update the news item being shown to players.
As stated earlier, our news items will be shown on our 'newsLabel' GUI label.

To do this, we will write a simple function to get the next news item from our 'newsItems' table and display it in our label.
<syntaxhighlight lang="lua">
-- define our function with a newIndex parameter, so that we can pass which news item we want to show
function updateNewsItem(newIndex)
-- get the new news item from the table
local item = newsItems[newIndex]

-- update the label text
guiSetText(newsLabel,item)

-- update the 'currentItem' global variable
currentItem = newIndex
end
</syntaxhighlight>

===Sizing the Label===
To make our news scrolling as accurate as possible, we need to be able to make the GUI label the same size as the news item text it is showing.

While this may seem like a tricky thing to do, it is made very easy with the function [[guiLabelGetTextExtent]].
This will tell us the extent, or width, of the text currently shown in our label.
So with a few modifications to our 'updateNewsItems' function, we get:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
local item = newsItems[newIndex]

guiSetText(newsLabel,item)

currentItem = newIndex

-- get the current dimensions of the gui label
local width,height = guiGetSize(newsLabel,false)

-- get the text width of the label
local extent = guiLabelGetTextExtent(newsLabel)

-- update the size of the label with the new width (we do not change the height)
guiSetSize(newsLabel,extent,height,false)
end
</syntaxhighlight>

===Positioning the Label===
Now that our GUI label is the correct width, we need to move it to a position where it is ready to scroll onto the screen.

Again, we can do this with a small modification to our 'updateNewsItems' function:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
local item = newsItems[newIndex]

guiSetText(newsLabel,item)

currentItem = newIndex

local width,height = guiGetSize(newsLabel,false)

local extent = guiLabelGetTextExtent(newsLabel)

guiSetSize(newsLabel,extent,height,false)

-- set the positon to the far right side of the gridlist, ready to scroll on to the left
guiSetPosition(newsLabel,1,0,true)
end
</syntaxhighlight>
Note the use of '''relative''' position values in the final line of the function.

In this case, it is far easier than calculating pixel values.

You can use both relative and absolute in the same script if you want to, the only limitation is that you cannot mix them in the same function call. The type of values you are using is defined by the final argument (true or false).

This means you cannot do the following and have it set to 400 pixels in, but 0.5% down
<syntaxhighlight lang="lua">
guiSetPosition(yourElement,400,0.5,false)
</syntaxhighlight>
The final argument "false" means both 400 and 0.5 will be read as pixel values.

==Scrolling the News==
The next step is to animate our news feed.

===Looking at Frames===
To do this, we will introduce a new event: [[onClientRender]].
As stated on the [[onClientRender]] wiki page, this event is called every time GTA renders a new frame (ie: very often).

As usual, to use this event we will need to create an event handler for it:
<syntaxhighlight lang="lua">
addEventHandler("onClientRender",root,scrollNews)
</syntaxhighlight>
This will call our scrollNews function every frame, which we will then use to update the position of our news item.

'''Make sure you add this handler after you have defined your scrollNews function.'''

For our purposes, [[onClientRender]] has one main advantage over, for example, [[setTimer]].
As it is called every frame (and therefore is dependant on the players FPS), the movement of the news item will always appear to be completely smooth,
unlike using a timer which would often appear to lag.

===Moving the News===
In our 'updateNewsItem' function, we position the 'newsLabel' to the far right, so we will scroll in from the right to the left.

For this we will simply move the X position by -1 every frame:
<syntaxhighlight lang="lua">
function scrollNews()
-- if the newsLabel exists
if newsLabel then
-- get the current position of the label
local x,y = guiGetPosition(newsLabel,false)

-- set the new x position of the label as the old position -1
guiSetPosition(newsLabel,x-1,y,false)
end
end
</syntaxhighlight>

===Looping around===
Now that our news scrolls across the screen, we need to be able to check when it has scrolled too far to the left
so we can start scrolling from the far-right side again.

We will also need to update the news item, so we should check the next item exists, and if it doesn't, go back to the first.

For this we will use some simple maths in a modification to our 'scrollNews' function:
<syntaxhighlight lang="lua">
function scrollNews()
local x,y = guiGetPosition(newsLabel,false)

local labelWidth, labelHeight = guiGetSize(newsLabel,false)

-- if the far right position of the label (x + labelWidth) is greater than or equal to 0 (ie: still showing on the gridlist)
if ((x-1) + labelWidth) >= 0 then
-- compensate for a small off-by-one bug in MTA
if x <= 0 then x = x - 1 end

-- update the position as normal
guiSetPosition(newsLabel,x-1,y,false)

-- otherwise, we move on to the next item and reset the position
else
-- get the total number of items in the 'newsItems' table
local totalItems = #newsItems

-- if the next item on our list does not exist in our table
if (currentItem + 1) > totalItems then
-- loop back to the first item in the list
updateNewsItem(1)
else
-- otherwise move onto the next item in the list
updateNewsItem(currentItem + 1)
end
end
end
</syntaxhighlight>
Notice the use of the '#' symbol to get the size of the 'newsItems' table.
This is the Lua length operator, but it only works on tables that have numerical indexes (like an array or a list).
It also works on strings, eg: #"hello" would return 5.

That completes this section of the tutorial.
For ideas on how to further improve and advance this code, continue reading the next section.

==Improving the code==
This section will detail several ways to improve upon the code you now have.

===GUI Customisation===
To give your GUI a more unique feel, you have the ability to customise some aspects of your GUI elements.

For ideas on what is possible, browse the [[Client_Scripting_Functions#GUI_functions|MTA GUI functions]].

For the purposes of this tutorial, we will be using Font, Colour and Alpha.

To start, we will change the alpha of the background gridlist GUI element we are using.
To set the alpha, use [[guiSetAlpha]] and pass a value between 1 and 0; 1 being fully opaque and 0 being fully transparent.
<syntaxhighlight lang="lua">
guiSetAlpha(newsGridlist,0.8)
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your gridlist has been created.

I find an alpha level of 0.8 looks best, however this is personal preference and you can experiment to suit your needs.

Next, we will look at the font of the label text.
To set the font, use [[guiSetFont]] and pass the string name of the font you want to use (available to see on the [[GUI Fonts]] page).
<syntaxhighlight lang="lua">
guiSetFont(newsLabel,"default-bold-small")
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your label has been created.

Finally, we will look at setting the colour of the label text.
To set the colour, use [[guiLabelSetColor]] and pass the individual red,green and blue values.
<syntaxhighlight lang="lua">
guiLabelSetColor(newsLabel,255,70,0)
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your label has been created.

This will give your news items an orange-red colour.

===Multiple News Items===
In its current form, this code is only capable of showing one news item at a time.
However, with a few modifications we can show multiple news items at once, one after another.

To begin with, we need to make sure we have a 'newItems' table defined at the very start of our script,
as well as a 'distance' variable that will control the pixel distance between each news item:
<syntaxhighlight lang="lua">
local newsItems = {}
local distance = 30
</syntaxhighlight>
So put these lines at the top of the file.

Next, we will not know how many items we have (and consequently, how many labels we need) until we have loaded the file.
With that in mind, we will move around some of the code in our 'createNewsFeed' function to support this:
<syntaxhighlight lang="lua">
function createNewsFeed()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the gridlist, using some maths to find the bottom-centre of the screen
local Width,Height = 800,45
local X = (sWidth/2) - (Width/2)
local Y = sHeight - (Height/2)

-- the gridlist will act as the background to our news reel
newsGridlist = guiCreateGridList(X,Y,Width,Height,false)

guiSetAlpha(newsGridlist,0.8)

-- call our function to read the news out of the xml file, before we create the labels
loadNews()

-- define a table to hold our labels
newsLabel = {}

-- now we can loop all our news items, and create a label for each one
for index,item in ipairs(newsItems) do

-- because we now have one label for every item, we can just set the text here and it wont need to be changed again.
newsLabel[index] = guiCreateLabel(0,0,Width,Height/2,item,false,newsGridlist)

guiSetFont(newsLabel[index],"default-bold-small")

guiLabelSetColor(newsLabel[index],255,70,0)

-- modify the width of the label to fit the text
local extent = guiLabelGetTextExtent(newsLabel[index])
guiSetSize(newsLabel[index],extent,Height/2,false)

-- get the size of the gridlist
local x,y = guiGetSize(newsGridlist,false)

-- loop from 1 until index-1 in steps of 1
-- this allows us to loop every label before the label we are currently on
for i=1, index-1, 1 do
-- tally up the sizes of all labels before our current one and store them in x
local width = guiGetSize(newsLabel[i],false)
x = x + width
end

-- put a 'distance' pixel gap between each news item
x = x + (distance*(index-1))

-- set the positon to the far right side of the gridlist, ready to scroll on to the left
guiSetPosition(newsLabel[index],x,0,false)
end
end
</syntaxhighlight>

Now we need to update our 'updateNewsItem' function to account for having multiple labels:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
-- find the index of the news item directly infront (in the looping order) of the newIndex item
local index = newIndex - 1
if index == 0 then index = #newsItems end

-- find the position of the right-edge of the label directly infront of the newIndex label
local x = guiGetPosition(newsLabel[index],false)
local width = guiGetSize(newsLabel[index],false)
x = x + width

-- add a 'distance' pixel gap in
x = x + distance

-- check the new position isnt actually on the gridlist (ie: so it wont suddenly appear in the centre of the list)
local gridlistWidth = guiGetSize(newsGridlist,false)

if x < gridlistWidth then
-- if it is, simple move it back to the edge
x = gridlistWidth
end

-- set the new position
guiSetPosition(newsLabel[newIndex],x,0,false)
end
</syntaxhighlight>

Finally, we need to make some small adjustments to our 'scrollNews' function:
<syntaxhighlight lang="lua">
function scrollNews()
if newsItems then
-- loop every news item
for index,item in ipairs(newsItems) do
local x,y = guiGetPosition(newsLabel[index],false)

local labelWidth, labelHeight = guiGetSize(newsLabel[index],false)

-- if the far right position of the label (x + labelWidth) is greater than or equal to 0 (ie: still showing on the gridlist)
if ((x-1) + labelWidth) >= 0 then
-- compensate for a small off-by-one bug in MTA
if x <= 0 then x = x - 1 end

-- update the position as normal
guiSetPosition(newsLabel[index],x-1,y,false)

-- otherwise, we move on to the next item and reset the position
else
updateNewsItem(index)
end
end
end
end
</syntaxhighlight>

You should now have multiple news items scrolling along your news feed simultaneously.

===Globally controlled scroll speed===
As with the 'distance' variable above, we can set a global variable for controlling the scroll speed of the news items as well.
Note that the speed will still be dependant on the players FPS (ie: lower FPS means slightly slower scrolling).

To do this, we simply need to create the variable at the start of our code:
<syntaxhighlight lang="lua">
local scrollSpeed = 1
</syntaxhighlight>
Put this line at the top of your file.

Then, we just replace the instance of "x-1" in our 'scrollNews' function with "x-scrollSpeed":
<syntaxhighlight lang="lua">
function scrollNews()
...
-- update the position as normal
guiSetPosition(newsLabel[index],x-scrollSpeed,y,false)
...
end
end
</syntaxhighlight>
That concludes this section of the tutorial.

[[Category:GUI_Tutorials]]

Scripting the GUI - Tutorial 2

2010-01-06T01:04:13Z

R3mp:

'''Scripting the GUI - Tutorial 2 (Gates + Keypads)'''

In this tutorial we will look at creating GUI keypads with combination codes for map-defined object gates.
We will be using serverside keycodes, with some client - server interaction to verify the codes and report the outcome.

'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|GUI Scripting Introduction]].'''

[[Image:Gui_keypad_tutorial.png|thumb|GUI Keypad]]

==Setting up the Keypad==
To begin, open up a clientside lua file (if you have been following the [[Introduction to Scripting GUI|GUI Scripting Introduction]], this is gui.lua) to work with.

===Creating the GUI===
By now, GUI creation should seem relatively straight forward, so we will not go over this in too much detail.
As in [[Scripting the GUI - Tutorial 1|Tutorial 1]] we will be using '''absolute''' values in this tutorial.

<syntaxhighlight lang="lua">
function createKeypad()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 142,276
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)
keypadWindow = guiCreateWindow(X,Y,Width,Height,"Keypad",false)

-- don't allow people to resize the keypad
guiWindowSetSizable(keypadWindow,false)

-- create buttons labeled 0-9, "*", "#", "Enter" and "C" (clear)
keypadButton1 = guiCreateButton(13,68,37,36,"1",false,keypadWindow)
keypadButton2 = guiCreateButton(53,68,37,36,"2",false,keypadWindow)
keypadButton3 = guiCreateButton(93,68,37,36,"3",false,keypadWindow)
keypadButton4 = guiCreateButton(13,108,37,36,"4",false,keypadWindow)
keypadButton5 = guiCreateButton(53,108,37,36,"5",false,keypadWindow)
keypadButton6 = guiCreateButton(93,108,37,36,"6",false,keypadWindow)
keypadButton7 = guiCreateButton(13,148,37,36,"7",false,keypadWindow)
keypadButton8 = guiCreateButton(53,148,37,36,"8",false,keypadWindow)
keypadButton9 = guiCreateButton(93,148,37,36,"9",false,keypadWindow)
keypadButtonAsterix = guiCreateButton(13,188,37,36,"*",false,keypadWindow)
keypadButton0 = guiCreateButton(53,188,37,36,"0",false,keypadWindow)
keypadButtonHash = guiCreateButton(93,188,37,36,"#",false,keypadWindow)
keypadButtonExit = guiCreateButton(13,228,37,36,"Exit",false,keypadWindow)
keypadButtonEnter = guiCreateButton(53,228,37,36,"Enter",false,keypadWindow)
keypadButtonClear = guiCreateButton(93,228,37,36,"Clear",false,keypadWindow)

-- create a gridlist to act as a backdrop on the kaypad display
keypadGridlistDisplay = guiCreateGridList(13,25,117,33,false,keypadWindow)
guiGridListSetSelectionMode(keypadGridlistDisplay,2)
guiSetAlpha(keypadGridlistDisplay,0.6)
-- create a label so we can write text on the keypad display
keypadLabelDisplay = guiCreateLabel(14,26,115,30,"Enter Keycode.",false,keypadWindow)
guiLabelSetColor(keypadLabelDisplay,255,000,000)
guiLabelSetVerticalAlign(keypadLabelDisplay,"center")
guiLabelSetHorizontalAlign(keypadLabelDisplay,"center",false)

guiSetVisible(keypadWindow,false)
end

-- create the GUI when the resource starts
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()),createKeypad)
</syntaxhighlight>
As you can see, the keypad consists of 10 numerical keys (0-9), two character keys (* and #), a clear key, an exit key and an enter key.
This means the codes used on the keypad can contain any of these characters (0123456789*#).

===Managing the display===
We will begin by writing a small function to control the display on the keypad.
This is done by encapsulating several methods of changing the text into a single function,
which will enable us to easily add/remove text from the display later on.
<syntaxhighlight lang="lua">
function updateDisplay(text)
-- if we are passing some text
if text then
-- if its a digit or * or #, then append it to the end of the display
if tonumber(text) or text == "*" or text == "#" then
guiSetText(keypadLabelDisplay,guiGetText(keypadLabelDisplay) .. text)
-- otherwise replace the display with the new text
else
guiSetText(keypadLabelDisplay,text)
end
-- if we pass nil, clear the display entirely
else
guiSetText(keypadLabelDisplay,"")
end
end
</syntaxhighlight>
We can now simply call updateDisplay(our text) to change the text on the display, or updateDisplay(nil) to clear it.

===Detecting the clicks===
With so many buttons that do very similar tasks on our keypad, there are two methods available to us for detecting when a player clicks on them.

We could add [[onClientGUIClick]] events for every button individually, as we have done in previous tutorials; Or, alternatively,
we could add a single [[onClientGUIClick]] handle for the window (which is the parent of all our other keypad GUI elements), filter our results to include only the buttons we want and trigger our own custom event.

For the purposes of this tutorial and in the interest of outlining multiple approaches, we will explore the second method, though either one is an acceptable solution.
<syntaxhighlight lang="lua">
addEventHandler("onClientGUIClick",keypadWindow,processKeypadClicks,true)
</syntaxhighlight>
'''Notice the final argument is set to 'true'. This means that clicks on any other elements in the same branch of the tree will also trigger this event handle (eg. clicks on our buttons).'''

Add this line of code into your createKeypad function, after your GUI has been created.

Now that we are detecting all clicks on our GUI, we need to filter out the ones we do not want (ie: clicks on the window or display) and trigger our custom event:
<syntaxhighlight lang="lua">
function processKeypadClicks(button,state)
if button == "left" and state == "up" then
-- if the source of this event is a gui button
if getElementType(source) == "gui-button" then
-- trigger our custom event and send the keypad id of this keypad as an argument
triggerEvent("onKeypadButtonClicked",source,getElementData(keypadWindow,"keypadID"))
end
end
end
</syntaxhighlight>
As you can see, we are now triggering our custom event "onKeypadButtonClicked" whenever a button is clicked on the keypad.
Also note we use element data "keypadID" to differentiate between keypads. This data will need to be set whenever the player is shown a new keypad.
We will cover this in more detail later.

===Handling the clicks===
Much like when using [[triggerServerEvent]] in previous tutorials, we now need to define the event, only this time it is purely clientside:
<syntaxhighlight lang="lua">
addEvent("onKeypadButtonClicked",false)
addEventHandler("onKeypadButtonClicked",root,
function(keypadID)

end
)
</syntaxhighlight>
Note the second argument in [[addEvent]] is set to false, indicating that this event cannot be triggered from the server.
Also note, the function we are using in the [[addEventHandler]] does not have a name. If you contract it down and remove the spacing, you get:
<syntaxhighlight lang="lua">
addEventHandler("onKeypadButtonClicked",root,function() ... end)
</syntaxhighlight>
This simply means instead of storing the pointer to the function in a variable, we are passing it directly as an argument.
Doing it this way cleans up the code and will often make it easier to follow.

Now that the event has been created, we can fill in the code logic that will control our button presses.
<syntaxhighlight lang="lua">
addEvent("onKeypadButtonClicked",false)
addEventHandler("onKeypadButtonClicked",root,
function(keypadID)
-- clear the display if this is the first time its being used
if guiGetText(keypadLabelDisplay) == "Enter Keycode." or guiGetText(keypadLabelDisplay) == "Invalid Keycode." then
updateDisplay()
end

-- if its the clear button
if guiGetText(source) == "Clear" then
-- clear the display
updateDisplay()

-- if its the enter button
elseif guiGetText(source) == "Enter" then
-- get the currently entered code from the display
local code = guiGetText(keypadLabelDisplay)

-- if they have entered a code
if code then
-- trigger the server so we can verify their code
triggerServerEvent("verifyKeypadCode",getLocalPlayer(),code,keypadID)
end

-- if its the exit button
elseif guiGetText(source) == "Exit" then
-- hide the keypad and reset the display text ready for next time
guiSetVisible(keypadWindow,false)
updateDisplay("Enter Keycode.")
showCursor(false,false)

-- otherwise, it must be a character button
else
updateDisplay(guiGetText(source))
end
end
)
</syntaxhighlight>

==Serverside Verification==
For this part of the tutorial, you will need to open up a serverside lua file from your resource to work with.

===Defining the keycode===
Now that we have completed the keypad clicking logic, we need to move on to verifying the code entered into the keypad.
To do this, we need to have the correct code stored somewhere on the server, which we can check the players code against.

For the purposes of this tutorial we will simply store the code in a serverside table, however it can be done any number of ways (such as serverside xml files or MySQL databases).
<syntaxhighlight lang="lua">
local keypadCodes = {
["a51MainGateKeypadCode"] = "4455*#"
}
</syntaxhighlight>
This table stores an entry called "a51MainGateKeypadCode" with the code 4455*#

'''This is the keycode that you will use to open the gate later on in this tutorial.'''

===Verifying the code===
Now that we have a keycode to verify against, we can write our serverside event:
<syntaxhighlight lang="lua">
addEvent("verifyKeypadCode",true)
addEventHandler("verifyKeypadCode",root,function(code,keypadID)
if code then
-- using the table we created earlier, check if the code supplied is the same as the code for this gate
if code == keypadCodes[keypadID] then
-- if it is, tell the client that it was successful
triggerClientEvent(client,"onKeypadVerificationSuccessful",client,keypadID)
else
-- if it is not, tell the client that it was not successful
triggerClientEvent(client,"onKeypadVerificationFailed",client,keypadID)
end
end
end)
</syntaxhighlight>
Here we use our table and the keypadID supplied by the player to check if the codes match.

If you are not using a table to store the codes, then you will need to replace 'keypadCodes[keypadID]' with your own storage method.
Once it is verified (or not), we can trigger the client so the appropriate information can be shown on the keypad display.

==Receiving the result==
We have now finished the serverside section of the tutorial, so you will need to open up the clientside lua file from your resource
that you were previously working on.

Once our code has been verified, the server will send back the response to the client.
In just the same way as client -> server interaction, we now need to add the event that the server is going to trigger on the client.

===Catching and processing the result===
First we will add the event for when the verification is successful:
<syntaxhighlight lang="lua">
addEvent("onKeypadVerificationSuccessful",true)
addEventHandler("onKeypadVerificationSuccessful",root,
function()
-- hide the keypad and reset the display text ready for next time
guiSetVisible(keypadWindow,false)
updateDisplay("Enter Keycode.")
showCursor(false,false)
end
)
</syntaxhighlight>

Finally we can add the event for when the verification is unsuccessful:
<syntaxhighlight lang="lua">
addEvent("onKeypadVerificationFailed",true)
addEventHandler("onKeypadVerificationFailed",root,
function()
-- update the display text to show the code was invalid
updateDisplay("Invalid Keycode.")
end
)
</syntaxhighlight>

This completes the keypad section of the tutorial.

For an example of how to implement this into a working gate system, carry on reading the next section.

==Applying the Keypad==
For the keypad to have any use, we need something to use it on.
For this tutorial we will be using gates, and as mentioned earlier we will create a main gate into A51.

===Creating the gate===
First of all, we need to create the gate object.
For the purposes of this example, we will be using a map file to store the object.
While this is the recommended method for defining objects, it is not the only way to approach it.

Navigate to your resource folder and make a new file called gate.map, then add your new map file to your meta.xml using:
<syntaxhighlight lang="lua">
<map src="gate.map"/>
</syntaxhighlight>

''If you are unsure of map file syntax, please see the [[Writing_Gamemodes| Writing Gamemodes Tutorial]] or check the [[Object]] page for help.''
<syntaxhighlight lang="lua">
<map>
<object id="a51MainGateKeypadCode" model="971" posX="96.736" posY="1918.352" posZ="20.694" rotX="0" rotY="0" rotZ="270.40" newPosX="96.751" newPosY="1914.474" newPosZ="20.694" />
</map>
</syntaxhighlight>
This will create a gate object across the A51 entrance. The object will have position and rotation data, as well as its newPosX,newPosY and newPosZ information that we need to be able to move it.

'''Note that the object id is the same as the table entry we created earlier to hold the access code.'''
This is one possible method that could be accessed to link this gate with that particular keycode.

===Opening the keypad===
Back in the clientside lua file again, we can now work on linking the gate and the keypad.

Now that we have our gate, we need a way of accessing the keypad to open it.
For the purposes of this tutorial we will use a simple command, however you could just as easily use a colshape or button press.
<syntaxhighlight lang="lua">
addCommandHandler("a51gate",function()
guiSetVisible(keypadWindow,true)
showCursor(true,true)
setElementData(keypadWindow,"keypadID","a51MainGateKeypadCode")
end)
</syntaxhighlight>
Note that we set the element data "keypadID".
This is very important because it allows us to keep track of which gate we are trying to open (in this case, the "a51MainGateKeypadCode" gate).

===Opening the gate===
With our gate created and our keypad ready, all thats left now is to open the gate.
Having created custom events earlier for successfully and unsuccessfully verifying the code, this now becomes very easy to do.
All we do is add an event handler for our custom "success" event, and using the keypadID we defined earlier we can move the gate inside it:
<syntaxhighlight lang="lua">
addEventHandler("onKeypadVerificationSuccessful",root,
-- keypadID is sent back from the server
function(keypadID)
-- get the gate object (this is where the id="a51MainGateKeypadCode" tag in the map file becomes useful)
local gate = getElementByID(keypadID)

-- if we found the object
if gate then
-- get the new position (as we defined in the map file)
local x = tonumber(getElementData(gate,"newPosX"))
local y = tonumber(getElementData(gate,"newPosY"))
local z = tonumber(getElementData(gate,"newPosZ"))

-- move the gate
moveObject(gate,1500,x,y,z)

-- get the original position
x = tonumber(getElementData(gate,"posX"))
y = tonumber(getElementData(gate,"posY"))
z = tonumber(getElementData(gate,"posZ"))

-- set a timer to close the gate in 5 seconds
setTimer(moveObject,5000,1,gate,1500,x,y,z)
end
end
)
</syntaxhighlight>
Note how by using the keypadID sent back from the server, we can use if statements and checks against the id to control any number of gates from the same function.

You should now have a working example of a GUI Keypad controlling an A51 Gate.

For further GUI tutorials, see [[Scripting the GUI - Tutorial 3|Tutorial 3 (Scrolling News Feed)]]

[[Category:GUI_Tutorials]]

Scripting the GUI - Tutorial 1

2010-01-06T01:03:55Z

R3mp:

'''Scripting the Gui - Tutorial 1 (Gridlists)'''

In this tutorial we will explore the use of gridlists in creating a vehicle selection screen, with optional clientside vehicle xml data reading.

'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|Previous tutorial]].'''

==Setting up the Vehicle Selection==

===Creating the GUI===
To begin, open up a clientside lua file (if you have been following the [[Scripting Introduction]], this is gui.lua) to work with.

In this file, we will start writing our function for creating the GUI.
As covered in the [[Introduction to Scripting GUI|Previous tutorial]], there are 2 value type options available when creating gui: '''relative''' and '''absolute'''.

For the purposes of this tutorial, we will be using '''absolute''' values.

This will create a simple GUI with a window, gridlist and button:
<syntaxhighlight lang="lua">
function createVehicleSelection()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- use some simple maths to position the window in the centre of the screen
local Width,Height = 376,259
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)
windowVehicleSelection = guiCreateWindow(X,Y,Width,Height,"Vehicle Selection Window",false)

gridlistVehicleSelection = guiCreateGridList(10,26,357,192,false,windowVehicleSelection)
-- add a "Vehicle" and a "Type" collumn to the gridlist
guiGridListAddColumn(gridlistVehicleSelection,"Vehicle",0.2)
guiGridListAddColumn(gridlistVehicleSelection,"Type",0.2)

-- set the default width of the columns to roughly half the size of the gridlist (each)
guiGridListSetColumnWidth(gridlistVehicleSelection,1,0.4,true)
guiGridListSetColumnWidth(gridlistVehicleSelection,2,0.5,true)

buttonCreate = guiCreateButton(121,227,120,20,"Create",false,windowVehicleSelection)

-- add the event handler for when the button is clicked
addEventHandler("onClientGUIClick",buttonCreate,createVehicleHandler,false)

-- hide the GUI
guiSetVisible(windowVehicleSelection,false)

-- this will add all the vehicle options onto the gridlist, it is explained later in this tutorial
populateGridlist()
end
</syntaxhighlight>

We now also need to call this function somewhere, otherwise the GUI will never be created.
As in previous tutorials, to do this we can use [[onClientResourceStart]].
<syntaxhighlight lang="lua">
-- when the resource is started, create the GUI and hide it
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()),
function()
createVehicleSelection()
end
)
</syntaxhighlight>

===Showing the GUI===
Unlike in previous tutorials, we want players to be able to open this window whenever they chose, not when the resource starts.
So, we can add a [[addCommandHandler|Command]] to do this.
<syntaxhighlight lang="lua">
-- create the function that will show the window
function showVehicleSelection()
-- if the window isnt visible, show it
if not guiGetVisible(windowVehicleSelection) then
guiSetVisible(windowVehicleSelection,true)

showCursor(true,true)
end
end

-- add the command /vehicleselection and set it to call the showVehicleSelection function
addCommandHandler("vehicleselection",showVehicleSelection)
</syntaxhighlight>

===Populating the Gridlist from a table===
Now that we have our basic GUI created, we need to fill the gridlist with all of our vehicles.

To begin with, we will do this using a simple clientside table.
Later in the tutorial, we will explore expanding this method to use .xml files for storing information.
To begin, we must create a small table containing a selection of vehicles that we can spawn.

The table contains vehicles in the format ["description"] = vehicle_id :
<syntaxhighlight lang="lua">
-- create the table and fill it with a selection of vehicle ids and names
local vehicleSelectionTable = {
["Sparrow"] = 469,
["Stuntplane"] = 513,
["BF-400"] = 581,
["Freeway"] = 463,
["Speeder"] = 452,
["Jester"] = 559,
["Sabre"] = 475,
["Police Ranger"] = 599,
["Utility Van"] = 552,
["Tug"] = 583
}
</syntaxhighlight>
Place this code at the very top of your file (it does not need to be inside a function).

Next, we can write our "populateGridlist" function which will fill the Gridlist with all the vehicles in the table.
To do this we simply need to loop through all the values in the table, adding each one to the gridlist as we go.
We will also set hidden data using [[guiGridListSetItemData]] to store the vehicle id:
<syntaxhighlight lang="lua">
function populateGridlist()
-- loop through the table
for name,vehicle in pairs(vehicleSelectionTable) do
-- add a new row to the gridlist
local row = guiGridListAddRow(gridlistVehicleSelection)

-- set the text in the first column to the vehicle name
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)
-- set the text in the second column to the vehicle type
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(vehicle),false,false)

-- set the data for gridlist slot as the vehicle id
guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(vehicle))
end
end
</syntaxhighlight>

===Managing the click===
Now that we have our GUI completed, we need to be able to catch any clicks made on the "create" button.
We have attached the [[onClientGUIClick]] event to buttonCreate already, so now we need to write the function that it calls.
In this function we do some basic error checking, such as making sure a vehicle has been selected in the list.
We can then use some maths to find a position infront of the player and send the server this information to spawn the vehicle (using [[triggerServerEvent]])
<syntaxhighlight lang="lua">
function createVehicleHandler(button,state)
if button == "left" and state == "up" then
-- get the selected item in the gridlist
local row,col = guiGridListGetSelectedItem(gridlistVehicleSelection)

-- if something is selected
if row and col and row ~= -1 and col ~= -1 then
-- get the vehicle id data from the gridlist that is selected
local selected = guiGridListGetItemData(gridlistVehicleSelection,row,col)

-- make sure the vehicle id is a number not a string
selected = tonumber(selected)

-- get the players position and rotation
local rotz = getPedRotation(getLocalPlayer())
local x,y,z = getElementPosition(getLocalPlayer())
-- find the position directly infront of the player
x = x + ( math.cos ( math.rad ( rotz+90 ) ) * 3)
y = y + ( math.sin ( math.rad ( rotz+90 ) ) * 3)

if selected and x and y and z then
-- trigger the server
triggerServerEvent("createVehicleFromGUI",getRootElement(),selected,x,y,z)

-- hide the gui and the cursor
guiSetVisible(windowVehicleSelection,false)
showCursor(false,false)
else
outputChatBox("Invalid arguments.")
end
else
-- otherwise, output a message to the player
outputChatBox("Please select a vehicle.")
end
end
end
</syntaxhighlight>

===Creating the Vehicle===
At this point we now have all the code needed on the client side, so open up a serverside .lua file to work with.

On the server side, we will first of all need to define the custom event that we triggered before from the client. This can be done using [[addEvent]] and [[addEventHandler]].
Finally we will need a small function for creating the vehicle:
<syntaxhighlight lang="lua">
function createMyVehicle(vehicleid,x,y,z)
-- check all the arguments exist
if vehicleid and x and y and z then
createVehicle(vehicleid,x,y,z)
end
end

addEvent("createVehicleFromGUI",true)
addEventHandler("createVehicleFromGUI",root,createMyVehicle)
</syntaxhighlight>
Note the use of the "root" variable. This is an MTA variable containing the root element; every resource has one.

This completes the first section of the tutorial. You should now have a basic, working vehicle spawn script.

In the second section, we will cover collapsible gridlist data and clientside xml file reading.

==Expanding the code==
This section will detail several ways to improve upon the code you now have.

===Importing Data===
One big improvement over the previously mentioned method is to use external files to store the vehicle information, allowing us to much more quickly and easily manage large amounts of data.
For this tutorial, we will use a clientside xml file to hold the information.

First of all you will need to create your xml file, so navigate to your resources directory and create a new file named vehicles.xml:

''For the purpose of this example, we will include only a small fraction of the total vehicles, however the file can easily be expanded to include them all.''

If you are unsure of xml data structures, you can browse the [http://wiki.multitheftauto.com/wiki/Server_Scripting_Functions#XML_functions| MTA xml functions] for help.
<syntaxhighlight lang="lua">
<root>
<group type="Bikes">
<vehicle id="581" name="BF-400"/>
<vehicle id="463" name="Freeway"/>
<vehicle id="481" name="BMX"/>
</group>
<group type="Boats">
<vehicle id="472" name="Coastguard"/>
<vehicle id="452" name="Speeder"/>
</group>
<group type="Helicopters">
<vehicle id="487" name="Maverick"/>
<vehicle id="469" name="Sparrow"/>
</group>
<group type="Planes">
<vehicle id="593" name="Dodo"/>
<vehicle id="513" name="Stuntplane"/>
</group>
<group type="Sports Cars">
<vehicle id="565" name="Flash"/>
<vehicle id="559" name="Jester"/>
<vehicle id="477" name="ZR-350"/>
</group>
<group type="2-Door">
<vehicle id="474" name="Hermes"/>
<vehicle id="475" name="Sabre"/>
</group>
<group type="Emergency">
<vehicle id="416" name="Ambulance"/>
<vehicle id="599" name="Police ranger"/>
</group>
<group type="Industrial">
<vehicle id="573" name="Dune"/>
<vehicle id="552" name="Utility van"/>
</group>
<group type="Misc">
<vehicle id="457" name="Caddy"/>
<vehicle id="583" name="Tug"/>
</group>
</root>
</syntaxhighlight>
Once you have created your file, do not forget to add it to the meta.xml of your resource with the appropriate client tag.

Note the group "type" tag. This is an arbitrary description of the vehicles contained within the group and can be renamed or added as any text.
Similarly, the vehicle "name" tag is also just a textual description of the vehicle and does not need to be the exact vehicle name.

Now that we have the data, we can import it into the game and display it in the GUI.
'''If you are following on from the first section of this tutorial, this new code will replace what is inside your existing 'populateGridlist' function.'''
First, we need to load the file:
<syntaxhighlight lang="lua">
function populateGridlist()
-- load the file and save the root node value it returns
local rootnode = xmlLoadFile("vehicles.xml")

-- check that the file exists and has been correctly loaded
if rootnode then
-- unload the xml file
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>
Always make sure you unload any files once you are finished using them.

We can now start collecting the data from the file and entering it into our gridlist.
We can do this by looping through the xml data (in a similar manner to looping through the vehicle table earlier in this tutorial) and adding each entry into the list.
<syntaxhighlight lang="lua">
function populateGridlist()
local rootnode = xmlLoadFile("vehicles.xml")

if rootnode then
-- first, we find every "group" node (they are direct children of the root)
for _,group in ipairs(xmlNodeGetChildren(rootnode)) do
-- add a new row to the gridlist
local row = guiGridListAddRow(gridlistVehicleSelection)

-- get the group name
local name = xmlNodeGetAttribute(group,"type")

-- set the text in the first column to the group type and indicate it is a section ('true')
-- (sections on gridlists show up in bold and cannot be clicked)
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,true,false)

-- then, for every group that we find, loop all of its children (the vehicle nodes)
-- and add them into the gridlist
for _,vehicle in ipairs(xmlNodeGetChildren(group)) do
-- add a new row to the gridlist
row = guiGridListAddRow(gridlistVehicleSelection)

-- get the vehicle name and id
name = xmlNodeGetAttribute(vehicle,"name")
local id = xmlNodeGetAttribute(vehicle,"id")

-- set the text in the first column to the vehicle name
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)
-- set the text in the second column to the vehicle type
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(tonumber(id)),false,false)

-- finally, set the vehicle id as data so we can access it later
guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(id))
end
end

-- unload the xml file now that we are finished
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>
Note the use of for loops in the code with [[xmlNodeGetChildren]]. This saves us a lot of time and effort as we do not have to manually code each group and vehicle into the list.

You should now have a fully working vehicle selection menu, reading all of its data from a clientside xml file.
Next, we will examine how to generate the appearance of collapsing and expanding sections in a gridlist.

===Collapsing/Expanding the Gridlist===
Allowing sections of the gridlist to be collapsed or expanded gives much more control over the visible content to the user.
This frees up space on the screen and makes the whole menu much more comfortable to use.

===Loading the data===
To be able to achieve this effect (as it is not a natural feature of gridlists) we will need to load the vehicle information into a table (from the xml file), rather than directly including it all in the gridlist.
'''If you are following on from a previous section of this tutorial, this new code will replace what is inside your existing 'populateGridlist' function.'''

This works in much the same way the previous xml loading example does, only this time instead of saving the data into the gridlist, we save it into a table entry instead.
We also set the custom data "header" on the gridlist slots to denote which gridlist entries are our "group" entries and which are vehicles.
<syntaxhighlight lang="lua">
function populateGridlist()
local rootnode = xmlLoadFile("vehicles.xml")

-- create a blank global table to store our imported data
vehicleTable = {}

if rootnode then
for _,group in ipairs(xmlNodeGetChildren(rootnode)) do
-- create an entry in the gridlist for every vehicle "group"
local row = guiGridListAddRow(gridlistVehicleSelection)

local name = xmlNodeGetAttribute(group,"type")

guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)

-- add an entry containing the group name into the table
vehicleTable[name] = {}

-- we will use the custom data "header" to indicate that this entry can be expanded/collapsed
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")

-- then, for every group that we find, loop all of its children (the vehicle nodes) and store them in a table
for _,vehicle in ipairs(xmlNodeGetChildren(group)) do
local vname = xmlNodeGetAttribute(vehicle,"name")
local id = xmlNodeGetAttribute(vehicle,"id")

-- insert both the vehicle id and the vehicle description into the table
table.insert(vehicleTable[name],{id,vname})
end
end

-- set element data on the gridlist so we know which group is currently showing
setElementData(gridlistVehicleSelection,"expanded","none")

-- unload the xml file now that we are finished
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>

Now that we have all the data stored, we can quickly manipulate it when neccessary.

===Managing the double click===
To enable the player to simply double click on a group name to expand/collapse it we need to use the [[onClientGUIDoubleClick]] event.
If we attach it to the gridlist, we can then catch any double clicks on the group names in it:
<syntaxhighlight lang="lua">
-- attach the onClientGUIDoubleClick event to the gridlist and set it to call processDoubleClick
addEventHandler("onClientGUIDoubleClick",gridlistVehicleSelection,processDoubleClick,false)
</syntaxhighlight>
Add this line of code in your createVehicleSelection, after the gridlist has been created.

As the gridlist items are not separate GUI elements, we must capture all clicks from anywhere on the gridlist then process them to filter out the ones we do not want.
This can be done by checking if an item is selected, then checking if the item is one of our "group" values (using our previously mentioned "header" data):
<syntaxhighlight lang="lua">
function processDoubleClick(button,state)
if button == "left" and state == "up" then
local row,col = guiGridListGetSelectedItem(gridlistVehicleSelection)

-- if something in the gridlist has been selected
if row and col and row ~= -1 and col ~= -1 then
-- if it is a header
if guiGridListGetItemData(gridlistVehicleSelection,row,col) == "header" then
local selected = guiGridListGetItemText(gridlistVehicleSelection,row,col)

-- call the function to collapse or expand the menu and pass which section it is as an argument
changeGridlistState(selected)
end
end
end
end
</syntaxhighlight>

Once we have narrowed down the double clicks to only those done on our group headers, we can expand/collapse them appropriately.
This can be done by simply setting new text values in the gridlist according to the newly expanded/collapsed group, which creates the convincing illusion of collapsable menus.

Note that much of the following code is reused from previous areas of this tutorial. While it is generally bad practice to clone sections of code in this way, for the purposes of this example it is far easier to understand.
<syntaxhighlight lang="lua">
function changeGridlistState(group)
if group then
-- if the group is already expanded, we want to collapse it
if getElementData(gridlistVehicleSelection,"expanded") == group then
-- first, we clear all previous data from the gridlist
guiGridListClear(gridlistVehicleSelection)

-- now, loop all the group entries in the vehicle table that we created earlier
for group,_ in pairs(vehicleTable) do
-- add each group to the list and mark them with "header"
local row = guiGridListAddRow(gridlistVehicleSelection)

guiGridListSetItemText(gridlistVehicleSelection,row,1,group,false,false)
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")
end

-- update the data to indicate that no groups are currently expanded
setElementData(gridlistVehicleSelection,"expanded","none")

-- otherwise, we want to expand it
else
guiGridListClear(gridlistVehicleSelection)

local row = guiGridListAddRow(gridlistVehicleSelection)

guiGridListSetItemText(gridlistVehicleSelection,row,1,group,false,false)
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")

-- loop every vehicle in the specified groups table
for _,vehicle in ipairs(vehicleTable[group]) do
-- add them to the gridlist and set the vehicle id as data
row = guiGridListAddRow(gridlistVehicleSelection)

-- format a "-" into the string to make it visually easier to distinguish between groups and vehicles
guiGridListSetItemText(gridlistVehicleSelection,row,1,"- "..vehicle[2],false,false)
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(tonumber(vehicle[1])),false,false)

guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(vehicle[1]))
end

-- update the data to indicate which group is currently expanded
setElementData(gridlistVehicleSelection,"expanded",group)
end
end
end
</syntaxhighlight>

This comletes the second section of the tutorial.

For further GUI tutorials, see [[Scripting the GUI - Tutorial 2|Tutorial 2 (Gates and Keypads)]]

[[Category:GUI_Tutorials]]

Introduction to Scripting the GUI - Part 2

2010-01-06T01:03:38Z

R3mp:

In this tutorial we will make a simple rules window, with an accept button and a list of all the server rules & information.

==Making the GUI==

===Getting set up===
The first thing we need to do is create our GUI elements.
For this tutorial we will be using one [[Element/GUI/Window|window]], one [[Element/GUI/Button|button]] and one [[Element/GUI/Text_label|label]].
We will be using '''absolute''' position values.

As noted in the [[Introduction to Scripting the GUI|Previous tutorial]], all the GUI must be made client side.

If you are following on from that tutorial, open up your gui.lua file to work with.

If you are not, browse to /Your MTA Server/mods/deathmatch/resources/myserver/ directory, and create a folder named "client".
Under /client/ directory, create a text file and name it "gui.lua".

If you have not already done so, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

===Making the window===
In this file we will write a funtion that draws the window:
<syntaxhighlight lang="lua">
-- create the function that will hold our gui creation code
function createRulesWindow()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 445,445
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

-- create the window
rulesWindow = guiCreateWindow(X,Y,Width,Height,"Rules",false)

-- stop players from being able to simply move the window out of the way
guiWindowSetMovable(rulesWindow,false)

-- stop players from being able to resize the window
guiWindowSetSizable(rulesWindow,false)
end
</syntaxhighlight>
This will create a basic window in the centre of the screen that cannot be moved and cannot be resized.

===Making the button===
Next, we will add the button to the bottom of our window that players can click on to accept the rules:

'''Note that we are now writing more code for our existing 'createRulesWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createRulesWindow()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 445,445
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

-- create the window and save the window gui element in a variable called 'rulesWindow'
rulesWindow = guiCreateWindow(X,Y,Width,Height,"Rules",false)

-- stop players from being able to simply move the window out of the way
-- note that we use our 'rulesWindow' variable to make changes to the window
guiWindowSetMovable(rulesWindow,false)

-- stop players from being able to resize the window
guiWindowSetSizable(rulesWindow,false)

-- create the button and save the button gui element in a variable called 'rulesButton'
rulesButton = guiCreateButton(137,394,158,37,"Accept",false,rulesWindow)
end
</syntaxhighlight>

===Making the label===
Next, we will add the label to the centre of our window that our rules will be displayed on:

'''Note that we are now writing more code for our existing 'createRulesWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createRulesWindow()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 445,445
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)

-- create the window and save the window gui element in a variable called 'rulesWindow'
rulesWindow = guiCreateWindow(X,Y,Width,Height,"Rules",false)

-- stop players from being able to simply move the window out of the way
-- note that we use our 'rulesWindow' variable to make changes to the window
guiWindowSetMovable(rulesWindow,false)

-- stop players from being able to resize the window
guiWindowSetSizable(rulesWindow,false)

-- create the button and save the button gui element in a variable called 'rulesButton'
rulesButton = guiCreateButton(137,394,158,37,"Accept",false,rulesWindow)

-- create the label and save the label gui element in a variable called 'rulesLabel'
-- we set the text of the label to our rules
rulesLabel = guiCreateLabel(10,25,425,359,[[
Welcome to my MTA Server!

Please carefully read the rules before accepting.

By accepting the rules, you are agreeing to play by them.
Anyone caught breaking these rules will be kicked and/or banned from this server.

If you do not accept the rules within 90 seconds, you will be kicked.

1: No cheating.

2: No bug abuse.

3: No mods to your game.

4: No flaming.

5: Respect other players.

6: Be nice!]],false,rulesWindow)

-- set the horizontal alignment of the label to center (ie: in the middle of the window)
-- also note the final argument "true"
-- this turns on wordwrap so if your text goes over the edge of the label, it will wrap around and start a new line automatically
guiLabelSetHorizontalAlign(rulesLabel,"center",true)
end
</syntaxhighlight>

''Note that the text is added in a different way to usual (we are not using quotation marks, "").''

===Text===
There are ''two'' ways to define text for a label.
For most situations, the recommended method is to enter all your text between quotation marks:
<syntaxhighlight lang="lua">
guiSetText(guiElement,"My text here")
</syntaxhighlight>

However, when we want to have more than 1 line in our text, it becomes just as easy to use the second method.
It is purely dependant on situation and personal choice which method you chose.
For clarity's sake, i will briefly outline both here.

When using quotation marks, we can make use of the newline character: "\n"
This allows us to break onto a new line in our text by entering "\n". For example:
<syntaxhighlight lang="lua">
guiSetText(guiElement,"This is line 1. \n This is line 2. \n This is line 3.")
</syntaxhighlight>

However, if we use brackets to enclose the text instead of quotation marks, we do not need to worry about entering any extra characters.
We can simply type the text out as we want it to appear in the label. For example:
<syntaxhighlight lang="lua">
guiSetText(guiElement,[[This is line 1.
This is line 2.
This is line 3.]])
</syntaxhighlight>

Both of these examples will create exactly the same text on the label.
It is entirely up to you which method you chose to use.

===Using the function we wrote===
The createRulesWindow function is now complete, but it won't do anything until we call it.
It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed.

Therefore, we'll write an event handler for [[onClientResourceStart]] to create the window:
<syntaxhighlight lang="lua">
-- attach the event handler to the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- call the createRulesWindow function to create our gui
createRulesWindow()
end
)
</syntaxhighlight>

As this is a rules window, we need to show the window when the player joins the game.
Fortunately, GUI elements are visible by default so we do not need to write any more code to achieve this.

However, we will also need to show the cursor for the player.
This can be done using the same event, [[onClientResourceStart]], so we can modify the above code to include showing the cursor:

'''Note that we are now writing more code for our 'onClientResourceStart' event. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
-- attach the event handler to the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- call the createRulesWindow function to create our gui
createRulesWindow()

-- show the cursor to the player
showCursor(true,true)
end
)
</syntaxhighlight>

We now have a completed GUI rules window. Next, we need to write the button functionality for the accept button.

==Scripting the Button==
Now that we have created our GUI, we need to make it work.

===Detecting the click===
When the player clicks on any part of the GUI, the event "[[onClientGUIClick]]" will be triggered for the GUI component you clicked on. This allows us to easily detect any clicks on the GUI elements we want to use.
For example, we can attach the event to the 'rulesButton' button to catch any clicks on it:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to rulesButton and set it to trigger the 'acceptRules' function
addEventHandler("onClientGUIClick", rulesButton, acceptRules, false)
</syntaxhighlight>
'''Note the final argument passed is "false". This indicates that the event will only trigger directly on rulesButton, not if the event has propagated up or down the tree. Setting this to "true" while attaching to gui elements will mean that clicking on any element in the same branch will trigger this event.'''

This line of code can now be added inside the 'createRulesWindow' function. It is a common mistake to try and attach events to non-existant GUI elements, so make sure you always attach your events '''after''' the GUI element (in this case, the button) has been created:
<syntaxhighlight lang="lua">
function createRulesWindow()
-- create all our GUI elements
...

-- now add our onClientGUIClick event to the button we just created
addEventHandler("onClientGUIClick", rulesButton, acceptRules, false)
</syntaxhighlight>

===Managing the click===
Now that we can detect when the player clicks on the button, we need to write code to manage what happens when they do.
In our [[onClientGUIClick]] event handle, we told it to call the function 'acceptRules' whenever 'rulesButton' is clicked.
Therefore, we can now use the function 'acceptRules' to control what happens when the button is clicked:
<syntaxhighlight lang="lua">
-- create the function and define the 'button' and 'state' parameters
-- (these are passed automatically by onClientGUIClick)
function acceptRules(button,state)
-- if our accept button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- hide the window and all the components
guiSetVisible(rulesWindow, false)

-- hide the mouse cursor
showCursor(false,false)

-- output a message to the player
outputChatBox("Thank you for accepting our rules. Have fun!")

-- if the warning timer exists
if rulesWarningTimer then
-- stop the timer and set the variable to nil
-- this is the timer used to kick players who do not accept the rules. We will cover this in more detail in the next section.
killTimer(rulesWarningTimer)
rulesWarningTimer = nil
end
end
end
</syntaxhighlight>
Now, when the button is clicked, the window and the cursor will be hidden.

==Checking for agreement==
Currently, our window will show when the player joins the server, and they must click accept to remove it.
However, if they do not accept it they can stay in the server indefinately with the window open.

===Setting a timer===
To combat this, we will add a timer using [[setTimer]] to kick them from the server after a period of time if they have not accepted the rules.
First, we will need a global variable to store the timer pointer:
<syntaxhighlight lang="lua">
local rulesWarningTimer = nil
</syntaxhighlight>
Put this line at the very top of your script (it does not need to be inside a function)

Next, we will create our timer:

'''Note that we are now writing more code for our existing 'createRulesWindow' function.'''
<syntaxhighlight lang="lua">
function createRulesWindow()
-- create all of our gui
...

-- set a timer for 30 seconds and set it to call our 'inactivePlayer' function with "1" as an argument
rulesWarningTimer = setTimer(inactivePlayer,30000,1,1)
end
</syntaxhighlight>
Put this [[setTimer]] line at the bottom of your 'createRulesWindow' function.
This will create a timer that will trigger after 30 seconds.

===Giving a warning===
Now we will write our 'inactivePlayer' function, to administer warnings to the player and finally kick him if he does not accept:
<syntaxhighlight lang="lua">
-- create our function and define the 'status' parameter
-- the value of status will be passed from our setTimer function call
function inactivePlayer(status)
-- if status is 1 (this means it is the first warning)
if status == 1 then
-- output a warning
outputChatBox("Please accept our rules or be kicked.")

-- set another timer to call inactivePlayer in another 30 seconds, with "2" as an argument
rulesWarningTimer = setTimer(inactivePlayer,30000,1,2)

-- if status is 2 (the second warning)
elseif status == 2 then
-- output a final warning
outputChatBox("FINAL WARNING: Please accept our rules or be kicked.")

-- set a final timer to call inactivePlayer in another 30 seconds, with "3" as an argument
rulesWarningTimer = setTimer(inactivePlayer,30000,1,3)
elseif status == 3 then
-- trigger the server so we can kick the player
triggerServerEvent("clientKickInactivePlayer",getLocalPlayer())
end
end
</syntaxhighlight>
Note the use of [[triggerServerEvent]] to call the server. You should have experience with client-server interaction from the [[Introduction to Scripting the GUI|Previous tutorial]].
If not, you can go back and read the full explanation there.

We have now completed all the clientside code for this tutorial.

===Kicking the player===
We now need to catch the event on the server that we triggered from the client, so open up a serverside lua file to work with.

To begin, we will add the event on the server:
<syntaxhighlight lang="lua">
-- add the event, note the final argument "true" indicates it can be triggered from the client
addEvent("clientKickInactivePlayer",true)
-- add an event handler for this event to trigger the kickInactivePlayer function
addEventHandler("clientKickInactivePlayer",root,kickInactivePlayer)
</syntaxhighlight>
'''Make sure you add your event handler after you have defined your 'kickInactivePlayer' function.'''

Note the use of [[addEvent]] and [[addEventHandler]] on the server. You should have experience with client-server interaction from the [[Introduction to Scripting the GUI|Previous tutorial]].
If not, you can go back and read the full explanation there.

Finally, we will add the 'kickInactivePlayer' function to control kicking of the player:
<syntaxhighlight lang="lua">
-- create our function
function kickInactivePlayer()
-- kick the player
kickPlayer(client,"Please accept our rules.")
end
</syntaxhighlight>
Note the use of the 'client' variable, this is an MTA variable that holds the value of the client (player) that triggered the event.

'''Note that [[kickPlayer]] will require your resource to have kick access in your ACL.'''

'''This is most easily accomplished by adding your resource into your admin group in the ACL:'''
<syntaxhighlight lang="xml">
<group name="Admin">
...
<object name="resource.YourResourceName" />
...
</group>
</syntaxhighlight>
For more information on the [[ACL]], see the [[ACL]] wiki page.

That concludes this tutorial. You should now have a fully working rules window for your server.

[[Category:GUI_Tutorials]]

Introduction to Scripting the GUI

2010-01-06T01:03:17Z

R3mp:

One important feature in MTA:SA is the ability to script customized GUI (Graphic User Interface). The GUI consists of windows, button, edit boxes, check boxes... Almost every standard form components in graphical environments. They can be displayed while the user is in game, and used for inputs and outputs in place of traditional commands.

[[Image:AdminGUI.png|thumb|Admin Console GUI]]

==A tutorial to make a login window==
In this tutorial we'll make a simple login window, with two input boxes and a button. The window appears when the player joins the game, and once the button is clicked, the player is spawned. The tutorial will continue the gamemode we made in [[Scripting Introduction|Introduction to Scripting]] ''(If you have used the [[Scripting Introduction|Introduction to Scripting]], you will need to remove or comment the [[spawnPlayer]] line in the "joinHandler" function in your code, as we will be replacing it with a gui alternative in this tutorial)''. We'll also take a look at client-side scripting.

===Draw the window===
All the GUI must be made client side. It is also a good practice to keep all the client scripts in a separate folder. Browse to /Your MTA Server/mods/deathmatch/resources/myserver/ directory, and create a folder named "client". Under /client/ directory, create a text file and name it "gui.lua", and in this file we will write a funtion that draws the window:
<syntaxhighlight lang="lua">
function createLoginWindow()
-- define the X and Y positions of the window
local X = 0.375
local Y = 0.375
-- define the width and height of the window
local Width = 0.25
local Height = 0.25
-- create the window and save its element value into the variable 'wdwLogin'
-- click on the function's name to read its documentation
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)
end
</syntaxhighlight>

===Relative and Absolute===
Note that the final argument passed to guiCreateWindow in the above example is ''true''. This indicates that the coordinates and dimensions of the window are '''relative''', meaning they are a ''percentage'' of the total screen size. This means that if the far left side of the screen is 0, and the far right is 1, an X position of 0.5 would represent the centre point of the screen. Similarly, if the top of the screen is 0 and the bottom is 1, a Y position of 0.2 would be 20% of the way down the screen. The same principles apply to both Width and Height as well (with a Width value of 0.5 meaning the window will be half as wide as the screen).

The alternative to using relative values is using '''absolute''' (by passing ''false'' instead of true to guiCreateWindow). Absolute values are calculated as the total number of pixels from the top-left corner of the parent (if no gui element parent is specified, the parent is the screen itself). If we assume a screen resolution of 1920x1200, the far left side of the screen being 0 pixels and the far right being 1920 pixels, an X position of 960 will represent the centre point of the screen. Similarly, if the top of the screen is 0 pixels and the bottom is 1200, a Y position of 20 would be 20 pixels down from the top of the screen. The same principles apple to both Width and Height as well (with a Width value of 50 meaning the window will be 50 pixels wide). ''You can use [[guiGetScreenSize]] and a little maths to calculate certain absolute positions.''

The differences between using relative and absolute values is quite simple; gui created using absolute values will always remain exactly the same pixel size and position, while gui created using relative values will always be a percentage of its parent's size.

Absolute is generally easier to maintain when editing code by hand, however your choice of type depends on the situation you are using it for.

For the purposes of this introduction we will be using relative values.

===Adding the components===
Next, we'll add the text labels (saying "username:" and "password:"), edit boxes (for entering your data) and a button to log in:
<syntaxhighlight lang="lua">
function createLoginWindow()
local X = 0.375
local Y = 0.375
local Width = 0.25
local Height = 0.25
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)

-- define new X and Y positions for the first label
X = 0.0825
Y = 0.2
-- define new Width and Height values for the first label
Width = 0.25
Height = 0.25
-- create the first label, note the final argument passed is 'wdwLogin' meaning the window
-- we created above is the parent of this label (so all the position and size values are now relative to the position of that window)
guiCreateLabel(X, Y, Width, Height, "Username", true, wdwLogin)
-- alter the Y value, so the second label is slightly below the first
Y = 0.5
guiCreateLabel(X, Y, Width, Height, "Password", true, wdwLogin)

X = 0.415
Y = 0.2
Width = 0.5
Height = 0.15
edtUser = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
Y = 0.5
edtPass = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
-- set the maximum character length for the username and password fields to 50
guiEditSetMaxLength(edtUser, 50)
guiEditSetMaxLength(edtPass, 50)

X = 0.415
Y = 0.7
Width = 0.25
Height = 0.2
btnLogin = guiCreateButton(X, Y, Width, Height, "Log In", true, wdwLogin)

-- make the window invisible
guiSetVisible(wdwLogin, false)
end
</syntaxhighlight>
Note that every GUI component created is a child of the window, this is done by specifying the parent element (wdwLogin, in this case) when creating the component.

This is very useful because not only does it mean that all the components are attached to the window and will move with it, but also that any changes done to the parent window will be applied down the tree to these child components. For example, we can now hide all of the GUI we just created by simply hiding the window:
<syntaxhighlight lang="lua">
guiSetVisible(wdwLogin, false) --hides all the GUI we made so we can show them to the player at the appropriate moment.
</syntaxhighlight>

===Using the function we wrote===
The createLoginWindow function is now complete, but it won't do anything until we call it. It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed. Therefore, we'll write an event handler for "[[onClientResourceStart]]" to create the window:
<syntaxhighlight lang="lua">
-- attach the event handler to the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
createLoginWindow()
end
)
</syntaxhighlight>

As this is a log in window, we now need to show the window when the player joins the game.
This can be done using the same event, "[[onClientResourceStart]]", so we can modify the above code to include showing the window:
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- create the log in window and its components
createLoginWindow()

-- output a brief welcome message to the player
outputChatBox("Welcome to My MTA:SA Server, please log in.")

-- if the GUI was successfully created, then show the GUI to the player
if (wdwLogin ~= nil) then
guiSetVisible(wdwLogin, true)
else
-- if the GUI hasnt been properly created, tell the player
outputChatBox("An unexpected error has occurred and the log in GUI has not been created.")
end

-- enable the players cursor (so they can select and click on the components)
showCursor(true)
-- set the input focus onto the GUI, allowing players (for example) to press 'T' without the chatbox opening
guiSetInputEnabled(true)
end
)
</syntaxhighlight>

Note that we have a simple security check before making the window visible, so in the unlikely event that the window has not been created, meaning wdwLogin is not a valid element, we don't get an error and just inform the player what has happened.
In the next step, we will create the button functionality for the log in button.

==Scripting the button==
Now that we have created our GUI and shown it to the player, we need to make it work.

===Detecting the click===
When the player clicks on any part of the GUI, the event "[[onClientGUIClick]]" will be triggered for the GUI component you clicked on. This allows us to easily detect any clicks on the GUI elements we want to use.
For example, we can attach the event to the btnLogin button to catch any clicks on it:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to btnLogin and set it to trigger the 'clientSubmitLogin' function
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>
'''Note the final argument passed is "false". This indicates that the event will only trigger directly on btnLogin, not if the event has propagated up or down the tree. Setting this to "true" while attaching to gui elements will mean that clicking on any element in the same branch will trigger this event.'''

This line of code can now be added inside the createLoginWindow function. It is a common mistake to try and attach events to non-existant GUI elements, so make sure you always attach your events '''after''' the gui element (in this case, the button) has been created:
<syntaxhighlight lang="lua">
function createLoginWindow()
-- create all our GUI elements
...

-- now add our onClientGUIClick event to the button we just created
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>

===Managing the click===
Now that we can detect when the player clicks on the button, we need to write code to manage what happens when they do.
In our [[onClientGUIClick]] event handle, we told it to call the function clientSubmitLogin whenever btnLogin is clicked.
Therefore, we can now use the function clientSubmitLogin to control what happens when the button is clicked:
<syntaxhighlight lang="lua">
-- create the function and define the 'button' and 'state' parameters
-- (these are passed automatically by onClientGUIClick)
function clientSubmitLogin(button,state)
-- if our login button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- move the input focus back onto the game (allowing players to move around, open the chatbox, etc)
guiSetInputEnabled(false)
-- hide the window and all the components
guiSetVisible(wdwLogin, false)
-- hide the mouse cursor
showCursor(false)
end
end
</syntaxhighlight>
Now, when the button is clicked, the window will be hidden and all controls will be returned to the player. Next, we will tell the server to allow the player to spawn.

===Triggering the server===
Triggering the server can be done using [[triggerServerEvent]]. This allows you to trigger a specified event on the server from the client. The same can be done in reverse using [[triggerClientEvent]].
Here, we use the [[triggerServerEvent]] function to call our own custom event on the server, named "submitLogin", which will then control the spawning of the player serverside.
<syntaxhighlight lang="lua">
function clientSubmitLogin(button,state)
if button == "left" and state == "up" then
-- get the text entered in the 'username' field
local username = guiGetText(edtUser)
-- get the text entered in the 'password' field
local password = guiGetText(edtPass)

-- if the username and password both exist
if username and password then
-- trigger the server event 'submitLogin' and pass the username and password to it
triggerServerEvent("submitLogin", getRootElement(), username, password)

-- hide the gui, hide the cursor and return control to the player
guiSetInputEnabled(false)
guiSetVisible(wdwLogin, false)
showCursor(false)
else
-- otherwise, output a message to the player, do not trigger the server
-- and do not hide the gui
outputChatBox("Please enter a username and password.")
end
end
end
</syntaxhighlight>

===Creating the serverside event===
At this point we now have all the code needed on the client side, so open up your serverside 'script.lua' file (from the [[Scripting Introduction|Introduction to Scripting]]) or another suitable serverside file to work with.

On the server side, recall that we are spawning the player as soon as they login.
So, first of all, we will need to define the custom event that we used before on the client. This can be done using [[addEvent]] and [[addEventHandler]].
<syntaxhighlight lang="lua">
-- create our loginHandler function, with username and password parameters (passed from the client gui)
function loginHandler(username,password)

end

-- define our custom event, and allow it to be triggered from the client ('true')
addEvent("submitLogin",true)
-- add an event handler so that when submitLogin is triggered, the function loginHandler is called
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>

===Logging in===
Now we have a function that is called through the custom event 'submitLogin', we can start to work on logging in and spawning the player, using our 'loginHandler' function:
<syntaxhighlight lang="lua">
function loginHandler(username,password)
-- check that the username and password are correct
if username == "user" and password == "apple" then
-- the player has successfully logged in, so spawn them
if (client) then
spawnPlayer(client, 1959.55, -1714.46, 10)
fadeCamera(client, true)
outputChatBox("Welcome to My Server.", client)
end
else
-- if the username or password are not correct, output a message to the player
outputChatBox("Invalid username and password. Please re-connect and try again.",client)
end
end

addEvent("submitLogin",true)
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>
'''For the purposes of this tutorial, a very basic username and password system is shown. For a more comprehensive alternative, you can use the Account System or a MySQL database.'''

Also note the use of the variable "client", it's an internal variable used by MTA to identify the player who triggered the event.

Finally, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

At this point, we now have a basic login window that checks the player's username and password when the login button is clicked. If they are correct, the player is automatically spawned.

For further GUI tutorials, see [[Scripting the GUI - Tutorial 1|Scripting the GUI - Tutorial 1 (Gridlists)]]

[[Category:GUI_Tutorials]]
[[it:Introduzione_allo_scripting_della_GUI]]
[[ru:Introduction to Scripting the GUI]]

Category:GUI Tutorials

2010-01-06T01:02:38Z

R3mp: Created page with 'These are a set of tutorials with information on how to include and manipulate GUI elements in your resources.'

These are a set of tutorials with information on how to include and manipulate [[GUI widgets|GUI elements]] in your resources.

Introduction to Scripting the GUI - Part 2

2010-01-06T00:49:10Z

R3mp: Created page with 'In this tutorial we will make a simple rules window, with an accept button and a list of all the server rules & information. ==Making the GUI== ===Getting set up=== The first t…'

Scripting the GUI - Tutorial 3

2010-01-05T22:44:11Z

R3mp:

Scripting the GUI - Tutorial 3

2010-01-05T22:43:19Z

R3mp:

'''Scripting the GUI - Tutorial 3 (Scrolling News Feed)'''

In this tutorial we will explore how to create a simple scrolling news feed GUI,
allowing you to quickly and easily show server updates and other server information to your players.
We will store all news items in a clientside xml file and use some simple xml reading to load them into the game.

We will then animate the news item to scroll along the bottom of the screen, updating the news text once it has scrolled beyond the edge of the screen.

'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|GUI Scripting Introduction]].'''

==Setting up the News Feed==
To begin, open up a clientside lua file (if you have been following the [[Introduction to Scripting GUI|GUI Scripting Introduction]], this is gui.lua) to work with.

===Creating the GUI===
As with the previous tutorial, you should be suitably familiar with GUI creation already so we will not go into too much detail here.
<syntaxhighlight lang="lua">
function createNewsFeed()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the gridlist, using some maths to find the bottom-centre of the screen
local Width,Height = 800,45
local X = (sWidth/2) - (Width/2)
local Y = sHeight - (Height/2)

-- the gridlist will act as the background to our news reel
newsGridlist = guiCreateGridList(X,Y,Width,Height,false)

-- create the label in the same place, but as a child of the gridlist
-- also make it half the height of the gridlist, as half of the gridlist is off the bottom of the screen
newsLabel = guiCreateLabel(X,Y,Width,Height/2,"Test text",false,newsGridlist)

-- call our function to read the news out of the xml file
loadNews()

-- load the first news item in the table
updateNewsItem(1)

-- define a global variable called 'currentItem' with the value 1
currentItem = 1
end

addEventHandler("onClientResourceStart",resourceRoot,createNewsFeed)
</syntaxhighlight>
Note that the label is created as a child of the gridlist.
Not only is this good practice in general, but it means that we can freely move parts of the label beyond the edge of the gridlist without them showing, which is critical to the visual effect of this tutorial.

Also notice the use of the 'resourceRoot' variable. This is an MTA variable that holds the root element value of the resource you are using it in.

The 'currentItem' variable is what we will use to keep track of which news item we are currently showing

===Writing the News===
Now that we have our GUI created, we need some news to fill it with.
To do this, we will read our news items out of a clientside xml file.

So, navigate to your resource directory and create a new xml file called newsfeed.xml (don't forget to add it to your meta.xml with the appropriate client tag).

Inside this file enter the following information:
<syntaxhighlight lang="lua">
<root>
<news>This is an example news item.</news>
<news>From the 'Scripting the GUI' tutorial.</news>
<news>Showing scrolling news text.</news>
<news>Written on a GUI news feed.</news>
</root>
</syntaxhighlight>
As you can see, each news item is defined as a <news> node with the value being the news text you want to display.
There is no limit on how many news items you can add.

===Collecting the News===
Once we have written all our news items, we will need to collect them all and store them in a table on the client.
We will do this when the resource starts, saving us from having to repeatedly access the xml for new news items.

First, we need to define a table to store the items in:
<syntaxhighlight lang="lua">
local newsItems = {}
</syntaxhighlight>
Add this line to the top of your script.
Make sure it is not inside a function otherwise it will not exist outside of that function (as denoted by the prefix "local").
When defined in the main body of the script it will exist in all functions.

Next, we will need to load the xml file:
<syntaxhighlight lang="lua">
function loadNews()
-- load our "newsfeed.xml" file
local newsfile = xmlLoadFile("newsfeed.xml")

-- if it was successfully loaded
if newsfile then

-- always remember to unload files once you are finished
xmlUnloadFile(newsfile)
end
end
</syntaxhighlight>
'''Always remember to unload files once you are finished using them.'''

Finally, we can add some more code to our loadNews function to read the news items into our newsItems table:
<syntaxhighlight lang="lua">
function loadNews()
local newsfile = xmlLoadFile("newsfeed.xml")

if newsfile then
-- loop through all the children of the root node (the "news" nodes)
for index,itemNode in ipairs(xmlNodeGetChildren(newsfile)) do
-- get the text (the news item) from the node
local item = xmlNodeGetValue(itemNode)

-- insert it into our newsItems table
table.insert(newsItems,item)
end

xmlUnloadFile(newsfile)
end
end
</syntaxhighlight>
We now have a table called 'newsItems' holding all of our news text from the xml file.

==Updating the News==
Now that we have our GUI created and our news items ready, we need to write some code to update the news item being shown to players.
As stated earlier, our news items will be shown on our 'newsLabel' GUI label.

To do this, we will write a simple function to get the next news item from our 'newsItems' table and display it in our label.
<syntaxhighlight lang="lua">
-- define our function with a newIndex parameter, so that we can pass which news item we want to show
function updateNewsItem(newIndex)
-- get the new news item from the table
local item = newsItems[newIndex]

-- update the label text
guiSetText(newsLabel,item)

-- update the 'currentItem' global variable
currentItem = newIndex
end
</syntaxhighlight>

===Sizing the Label===
To make our news scrolling as accurate as possible, we need to be able to make the GUI label the same size as the news item text it is showing.

While this may seem like a tricky thing to do, it is made very easy with the function [[guiLabelGetTextExtent]].
This will tell us the extent, or width, of the text currently shown in our label.
So with a few modifications to our 'updateNewsItems' function, we get:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
local item = newsItems[newIndex]

guiSetText(newsLabel,item)

currentItem = newIndex

-- get the current dimensions of the gui label
local width,height = guiGetSize(newsLabel,false)

-- get the text width of the label
local extent = guiLabelGetTextExtent(newsLabel)

-- update the size of the label with the new width (we do not change the height)
guiSetSize(newsLabel,extent,height,false)
end
</syntaxhighlight>

===Positioning the Label===
Now that our GUI label is the correct width, we need to move it to a position where it is ready to scroll onto the screen.

Again, we can do this with a small modification to our 'updateNewsItems' function:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
local item = newsItems[newIndex]

guiSetText(newsLabel,item)

currentItem = newIndex

local width,height = guiGetSize(newsLabel,false)

local extent = guiLabelGetTextExtent(newsLabel)

guiSetSize(newsLabel,extent,height,false)

-- set the positon to the far right side of the gridlist, ready to scroll on to the left
guiSetPosition(newsLabel,1,0,true)
end
</syntaxhighlight>
Note the use of '''relative''' position values in the final line of the function.

In this case, it is far easier than calculating pixel values.

You can use both relative and absolute in the same script if you want to, the only limitation is that you cannot mix them in the same function call. The type of values you are using is defined by the final argument (true or false).

This means you cannot do the following and have it set to 400 pixels in, but 0.5% down
<syntaxhighlight lang="lua">
guiSetPosition(yourElement,400,0.5,false)
</syntaxhighlight>
The final argument "true" means both 400 and 0.5 will be read as pixel values.

==Scrolling the News==
The next step is to animate our news feed.

===Looking at Frames===
To do this, we will introduce a new event: [[onClientRender]].
As stated on the [[onClientRender]] wiki page, this event is called every time GTA renders a new frame (ie: very often).

As usual, to use this event we will need to create an event handler for it:
<syntaxhighlight lang="lua">
addEventHandler("onClientRender",root,scrollNews)
</syntaxhighlight>
This will call our scrollNews function every frame, which we will then use to update the position of our news item.

'''Make sure you add this handler after you have defined your scrollNews function.'''

For our purposes, [[onClientRender]] has one main advantage over, for example, [[setTimer]].
As it is called every frame (and therefore is dependant on the players FPS), the movement of the news item will always appear to be completely smooth,
unlike using a timer which would often appear to lag.

===Moving the News===
In our 'updateNewsItem' function, we position the 'newsLabel' to the far right, so we will scroll in from the right to the left.

For this we will simply move the X position by -1 every frame:
<syntaxhighlight lang="lua">
function scrollNews()
-- if the newsLabel exists
if newsLabel then
-- get the current position of the label
local x,y = guiGetPosition(newsLabel,false)

-- set the new x position of the label as the old position -1
guiSetPosition(newsLabel,x-1,y,false)
end
end
</syntaxhighlight>

===Looping around===
Now that our news scrolls across the screen, we need to be able to check when it has scrolled too far to the left
so we can start scrolling from the far-right side again.

We will also need to update the news item, so we should check the next item exists, and if it doesn't, go back to the first.

For this we will use some simple maths in a modification to our 'scrollNews' function:
<syntaxhighlight lang="lua">
function scrollNews()
local x,y = guiGetPosition(newsLabel,false)

local labelWidth, labelHeight = guiGetSize(newsLabel,false)

-- if the far right position of the label (x + labelWidth) is greater than or equal to 0 (ie: still showing on the gridlist)
if ((x-1) + labelWidth) >= 0 then
-- compensate for a small off-by-one bug in MTA
if x <= 0 then x = x - 1 end

-- update the position as normal
guiSetPosition(newsLabel,x-1,y,false)

-- otherwise, we move on to the next item and reset the position
else
-- get the total number of items in the 'newsItems' table
local totalItems = #newsItems

-- if the next item on our list does not exist in our table
if (currentItem + 1) > totalItems then
-- loop back to the first item in the list
updateNewsItem(1)
else
-- otherwise move onto the next item in the list
updateNewsItem(currentItem + 1)
end
end
end
</syntaxhighlight>
Notice the use of the '#' symbol to get the size of the 'newsItems' table.
This is the Lua length operator, but it only works on tables that have numerical indexes (like an array or a list).
It also works on strings, eg: #"hello" would return 5.

That completes this section of the tutorial.
For ideas on how to further improve and advance this code, continue reading the next section.

==Improving the code==
This section will detail several ways to improve upon the code you now have.

===GUI Customisation===
To give your GUI a more unique feel, you have the ability to customise some aspects of your GUI elements.

For ideas on what is possible, browse the [[Client_Scripting_Functions#GUI_functions|MTA GUI functions]].

For the purposes of this tutorial, we will be using Font, Colour and Alpha.

To start, we will change the alpha of the background gridlist GUI element we are using.
To set the alpha, use [[guiSetAlpha]] and pass a value between 1 and 0; 1 being fully opaque and 0 being fully transparent.
<syntaxhighlight lang="lua">
guiSetAlpha(newsGridlist,0.8)
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your gridlist has been created.

I find an alpha level of 0.8 looks best, however this is personal preference and you can experiment to suit your needs.

Next, we will look at the font of the label text.
To set the font, use [[guiSetFont]] and pass the string name of the font you want to use (available to see on the [[GUI Fonts]] page).
<syntaxhighlight lang="lua">
guiSetFont(newsLabel,"default-bold-small")
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your label has been created.

Finally, we will look at setting the colour of the label text.
To set the colour, use [[guiLabelSetColor]] and pass the individual red,green and blue values.
<syntaxhighlight lang="lua">
guiLabelSetColor(newsLabel,255,70,0)
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your label has been created.

This will give your news items an orange-red colour.

===Multiple News Items===
In its current form, this code is only capable of showing one news item at a time.
However, with a few modifications we can show multiple news items at once, one after another.

To begin with, we need to make sure we have a 'newItems' table defined at the very start of our script,
as well as a 'distance' variable that will control the pixel distance between each news item:
<syntaxhighlight lang="lua">
local newsItems = {}
local distance = 30
</syntaxhighlight>
So put these lines at the top of the file.

Next, we will not know how many items we have (and consequently, how many labels we need) until we have loaded the file.
With that in mind, we will move around some of the code in our 'createNewsFeed' function to support this:
<syntaxhighlight lang="lua">
function createNewsFeed()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the gridlist, using some maths to find the bottom-centre of the screen
local Width,Height = 800,45
local X = (sWidth/2) - (Width/2)
local Y = sHeight - (Height/2)

-- the gridlist will act as the background to our news reel
newsGridlist = guiCreateGridList(X,Y,Width,Height,false)

guiSetAlpha(newsGridlist,0.8)

-- call our function to read the news out of the xml file, before we create the labels
loadNews()

-- define a table to hold our labels
newsLabel = {}

-- now we can loop all our news items, and create a label for each one
for index,item in ipairs(newsItems) do

-- because we now have one label for every item, we can just set the text here and it wont need to be changed again.
newsLabel[index] = guiCreateLabel(0,0,Width,Height/2,item,false,newsGridlist)

guiSetFont(newsLabel[index],"default-bold-small")

guiLabelSetColor(newsLabel[index],255,70,0)

-- modify the width of the label to fit the text
local extent = guiLabelGetTextExtent(newsLabel[index])
guiSetSize(newsLabel[index],extent,Height/2,false)

-- get the size of the gridlist
local x,y = guiGetSize(newsGridlist,false)

-- loop from 1 until index-1 in steps of 1
-- this allows us to loop every label before the label we are currently on
for i=1, index-1, 1 do
-- tally up the sizes of all labels before our current one and store them in x
local width = guiGetSize(newsLabel[i],false)
x = x + width
end

-- put a 'distance' pixel gap between each news item
x = x + (distance*(index-1))

-- set the positon to the far right side of the gridlist, ready to scroll on to the left
guiSetPosition(newsLabel[index],x,0,false)
end
end
</syntaxhighlight>

Now we need to update our 'updateNewsItem' function to account for having multiple labels:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
-- find the index of the news item directly infront (in the looping order) of the newIndex item
local index = newIndex - 1
if index == 0 then index = #newsItems end

-- find the position of the right-edge of the label directly infront of the newIndex label
local x = guiGetPosition(newsLabel[index],false)
local width = guiGetSize(newsLabel[index],false)
x = x + width

-- add a 'distance' pixel gap in
x = x + distance

-- check the new position isnt actually on the gridlist (ie: so it wont suddenly appear in the centre of the list)
local gridlistWidth = guiGetSize(newsGridlist,false)

if x < gridlistWidth then
-- if it is, simple move it back to the edge
x = gridlistWidth
end

-- set the new position
guiSetPosition(newsLabel[newIndex],x,0,false)
end
</syntaxhighlight>

Finally, we need to make some small adjustments to our 'scrollNews' function:
<syntaxhighlight lang="lua">
function scrollNews()
if newsItems then
-- loop every news item
for index,item in ipairs(newsItems) do
local x,y = guiGetPosition(newsLabel[index],false)

local labelWidth, labelHeight = guiGetSize(newsLabel[index],false)

-- if the far right position of the label (x + labelWidth) is greater than or equal to 0 (ie: still showing on the gridlist)
if ((x-1) + labelWidth) >= 0 then
-- compensate for a small off-by-one bug in MTA
if x <= 0 then x = x - 1 end

-- update the position as normal
guiSetPosition(newsLabel[index],x-1,y,false)

-- otherwise, we move on to the next item and reset the position
else
updateNewsItem(index)
end
end
end
end
</syntaxhighlight>

You should now have multiple news items scrolling along your news feed simultaneously.

===Globally controlled scroll speed===
As with the 'distance' variable above, we can set a global variable for controlling the scroll speed of the news items as well.
Note that the speed will still be dependant on the players FPS (ie: lower FPS means slightly slower scrolling).

To do this, we simply need to create the variable at the start of our code:
<syntaxhighlight lang="lua">
local scrollSpeed = 1
</syntaxhighlight>
Put this line at the top of your file.

Then, we just replace the instance of "x-1" in our 'scrollNews' function with "x-scrollSpeed":
<syntaxhighlight lang="lua">
function scrollNews()
...
-- update the position as normal
guiSetPosition(newsLabel[index],x-scrollSpeed,y,false)
...
end
end
</syntaxhighlight>
That concludes this section of the tutorial.

Scripting the GUI - Tutorial 1

2010-01-05T21:52:53Z

R3mp:

'''Scripting the Gui - Tutorial 1 (Gridlists)'''

In this tutorial we will explore the use of gridlists in creating a vehicle selection screen, with optional clientside vehicle xml data reading.

'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|Previous tutorial]].'''

==Setting up the Vehicle Selection==

===Creating the GUI===
To begin, open up a clientside lua file (if you have been following the [[Scripting Introduction]], this is gui.lua) to work with.

In this file, we will start writing our function for creating the GUI.
As covered in the [[Introduction to Scripting GUI|Previous tutorial]], there are 2 value type options available when creating gui: '''relative''' and '''absolute'''.

For the purposes of this tutorial, we will be using '''absolute''' values.

This will create a simple GUI with a window, gridlist and button:
<syntaxhighlight lang="lua">
function createVehicleSelection()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- use some simple maths to position the window in the centre of the screen
local Width,Height = 376,259
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)
windowVehicleSelection = guiCreateWindow(X,Y,Width,Height,"Vehicle Selection Window",false)

gridlistVehicleSelection = guiCreateGridList(10,26,357,192,false,windowVehicleSelection)
-- add a "Vehicle" and a "Type" collumn to the gridlist
guiGridListAddColumn(gridlistVehicleSelection,"Vehicle",0.2)
guiGridListAddColumn(gridlistVehicleSelection,"Type",0.2)

-- set the default width of the columns to roughly half the size of the gridlist (each)
guiGridListSetColumnWidth(gridlistVehicleSelection,1,0.4,true)
guiGridListSetColumnWidth(gridlistVehicleSelection,2,0.5,true)

buttonCreate = guiCreateButton(121,227,120,20,"Create",false,windowVehicleSelection)

-- add the event handler for when the button is clicked
addEventHandler("onClientGUIClick",buttonCreate,createVehicleHandler,false)

-- hide the GUI
guiSetVisible(windowVehicleSelection,false)

-- this will add all the vehicle options onto the gridlist, it is explained later in this tutorial
populateGridlist()
end
</syntaxhighlight>

We now also need to call this function somewhere, otherwise the GUI will never be created.
As in previous tutorials, to do this we can use [[onClientResourceStart]].
<syntaxhighlight lang="lua">
-- when the resource is started, create the GUI and hide it
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()),
function()
createVehicleSelection()
end
)
</syntaxhighlight>

===Showing the GUI===
Unlike in previous tutorials, we want players to be able to open this window whenever they chose, not when the resource starts.
So, we can add a [[addCommandHandler|Command]] to do this.
<syntaxhighlight lang="lua">
-- create the function that will show the window
function showVehicleSelection()
-- if the window isnt visible, show it
if not guiGetVisible(windowVehicleSelection) then
guiSetVisible(windowVehicleSelection,true)

showCursor(true,true)
end
end

-- add the command /vehicleselection and set it to call the showVehicleSelection function
addCommandHandler("vehicleselection",showVehicleSelection)
</syntaxhighlight>

===Populating the Gridlist from a table===
Now that we have our basic GUI created, we need to fill the gridlist with all of our vehicles.

To begin with, we will do this using a simple clientside table.
Later in the tutorial, we will explore expanding this method to use .xml files for storing information.
To begin, we must create a small table containing a selection of vehicles that we can spawn.

The table contains vehicles in the format ["description"] = vehicle_id :
<syntaxhighlight lang="lua">
-- create the table and fill it with a selection of vehicle ids and names
local vehicleSelectionTable = {
["Sparrow"] = 469,
["Stuntplane"] = 513,
["BF-400"] = 581,
["Freeway"] = 463,
["Speeder"] = 452,
["Jester"] = 559,
["Sabre"] = 475,
["Police Ranger"] = 599,
["Utility Van"] = 552,
["Tug"] = 583
}
</syntaxhighlight>
Place this code at the very top of your file (it does not need to be inside a function).

Next, we can write our "populateGridlist" function which will fill the Gridlist with all the vehicles in the table.
To do this we simply need to loop through all the values in the table, adding each one to the gridlist as we go.
We will also set hidden data using [[guiGridListSetItemData]] to store the vehicle id:
<syntaxhighlight lang="lua">
function populateGridlist()
-- loop through the table
for name,vehicle in pairs(vehicleSelectionTable) do
-- add a new row to the gridlist
local row = guiGridListAddRow(gridlistVehicleSelection)

-- set the text in the first column to the vehicle name
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)
-- set the text in the second column to the vehicle type
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(vehicle),false,false)

-- set the data for gridlist slot as the vehicle id
guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(vehicle))
end
end
</syntaxhighlight>

===Managing the click===
Now that we have our GUI completed, we need to be able to catch any clicks made on the "create" button.
We have attached the [[onClientGUIClick]] event to buttonCreate already, so now we need to write the function that it calls.
In this function we do some basic error checking, such as making sure a vehicle has been selected in the list.
We can then use some maths to find a position infront of the player and send the server this information to spawn the vehicle (using [[triggerServerEvent]])
<syntaxhighlight lang="lua">
function createVehicleHandler(button,state)
if button == "left" and state == "up" then
-- get the selected item in the gridlist
local row,col = guiGridListGetSelectedItem(gridlistVehicleSelection)

-- if something is selected
if row and col and row ~= -1 and col ~= -1 then
-- get the vehicle id data from the gridlist that is selected
local selected = guiGridListGetItemData(gridlistVehicleSelection,row,col)

-- make sure the vehicle id is a number not a string
selected = tonumber(selected)

-- get the players position and rotation
local rotz = getPedRotation(getLocalPlayer())
local x,y,z = getElementPosition(getLocalPlayer())
-- find the position directly infront of the player
x = x + ( math.cos ( math.rad ( rotz+90 ) ) * 3)
y = y + ( math.sin ( math.rad ( rotz+90 ) ) * 3)

if selected and x and y and z then
-- trigger the server
triggerServerEvent("createVehicleFromGUI",getRootElement(),selected,x,y,z)

-- hide the gui and the cursor
guiSetVisible(windowVehicleSelection,false)
showCursor(false,false)
else
outputChatBox("Invalid arguments.")
end
else
-- otherwise, output a message to the player
outputChatBox("Please select a vehicle.")
end
end
end
</syntaxhighlight>

===Creating the Vehicle===
At this point we now have all the code needed on the client side, so open up a serverside .lua file to work with.

On the server side, we will first of all need to define the custom event that we triggered before from the client. This can be done using [[addEvent]] and [[addEventHandler]].
Finally we will need a small function for creating the vehicle:
<syntaxhighlight lang="lua">
function createMyVehicle(vehicleid,x,y,z)
-- check all the arguments exist
if vehicleid and x and y and z then
createVehicle(vehicleid,x,y,z)
end
end

addEvent("createVehicleFromGUI",true)
addEventHandler("createVehicleFromGUI",root,createMyVehicle)
</syntaxhighlight>
Note the use of the "root" variable. This is an MTA variable containing the root element; every resource has one.

This completes the first section of the tutorial. You should now have a basic, working vehicle spawn script.

In the second section, we will cover collapsible gridlist data and clientside xml file reading.

==Expanding the code==
This section will detail several ways to improve upon the code you now have.

===Importing Data===
One big improvement over the previously mentioned method is to use external files to store the vehicle information, allowing us to much more quickly and easily manage large amounts of data.
For this tutorial, we will use a clientside xml file to hold the information.

First of all you will need to create your xml file, so navigate to your resources directory and create a new file named vehicles.xml:

''For the purpose of this example, we will include only a small fraction of the total vehicles, however the file can easily be expanded to include them all.''

If you are unsure of xml data structures, you can browse the [http://wiki.multitheftauto.com/wiki/Server_Scripting_Functions#XML_functions| MTA xml functions] for help.
<syntaxhighlight lang="lua">
<root>
<group type="Bikes">
<vehicle id="581" name="BF-400"/>
<vehicle id="463" name="Freeway"/>
<vehicle id="481" name="BMX"/>
</group>
<group type="Boats">
<vehicle id="472" name="Coastguard"/>
<vehicle id="452" name="Speeder"/>
</group>
<group type="Helicopters">
<vehicle id="487" name="Maverick"/>
<vehicle id="469" name="Sparrow"/>
</group>
<group type="Planes">
<vehicle id="593" name="Dodo"/>
<vehicle id="513" name="Stuntplane"/>
</group>
<group type="Sports Cars">
<vehicle id="565" name="Flash"/>
<vehicle id="559" name="Jester"/>
<vehicle id="477" name="ZR-350"/>
</group>
<group type="2-Door">
<vehicle id="474" name="Hermes"/>
<vehicle id="475" name="Sabre"/>
</group>
<group type="Emergency">
<vehicle id="416" name="Ambulance"/>
<vehicle id="599" name="Police ranger"/>
</group>
<group type="Industrial">
<vehicle id="573" name="Dune"/>
<vehicle id="552" name="Utility van"/>
</group>
<group type="Misc">
<vehicle id="457" name="Caddy"/>
<vehicle id="583" name="Tug"/>
</group>
</root>
</syntaxhighlight>
Once you have created your file, do not forget to add it to the meta.xml of your resource with the appropriate client tag.

Note the group "type" tag. This is an arbitrary description of the vehicles contained within the group and can be renamed or added as any text.
Similarly, the vehicle "name" tag is also just a textual description of the vehicle and does not need to be the exact vehicle name.

Now that we have the data, we can import it into the game and display it in the GUI.
'''If you are following on from the first section of this tutorial, this new code will replace what is inside your existing 'populateGridlist' function.'''
First, we need to load the file:
<syntaxhighlight lang="lua">
function populateGridlist()
-- load the file and save the root node value it returns
local rootnode = xmlLoadFile("vehicles.xml")

-- check that the file exists and has been correctly loaded
if rootnode then
-- unload the xml file
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>
Always make sure you unload any files once you are finished using them.

We can now start collecting the data from the file and entering it into our gridlist.
We can do this by looping through the xml data (in a similar manner to looping through the vehicle table earlier in this tutorial) and adding each entry into the list.
<syntaxhighlight lang="lua">
function populateGridlist()
local rootnode = xmlLoadFile("vehicles.xml")

if rootnode then
-- first, we find every "group" node (they are direct children of the root)
for _,group in ipairs(xmlNodeGetChildren(rootnode)) do
-- add a new row to the gridlist
local row = guiGridListAddRow(gridlistVehicleSelection)

-- get the group name
local name = xmlNodeGetAttribute(group,"type")

-- set the text in the first column to the group type and indicate it is a section ('true')
-- (sections on gridlists show up in bold and cannot be clicked)
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,true,false)

-- then, for every group that we find, loop all of its children (the vehicle nodes)
-- and add them into the gridlist
for _,vehicle in ipairs(xmlNodeGetChildren(group)) do
-- add a new row to the gridlist
row = guiGridListAddRow(gridlistVehicleSelection)

-- get the vehicle name and id
name = xmlNodeGetAttribute(vehicle,"name")
local id = xmlNodeGetAttribute(vehicle,"id")

-- set the text in the first column to the vehicle name
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)
-- set the text in the second column to the vehicle type
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(tonumber(id)),false,false)

-- finally, set the vehicle id as data so we can access it later
guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(id))
end
end

-- unload the xml file now that we are finished
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>
Note the use of for loops in the code with [[xmlNodeGetChildren]]. This saves us a lot of time and effort as we do not have to manually code each group and vehicle into the list.

You should now have a fully working vehicle selection menu, reading all of its data from a clientside xml file.
Next, we will examine how to generate the appearance of collapsing and expanding sections in a gridlist.

===Collapsing/Expanding the Gridlist===
Allowing sections of the gridlist to be collapsed or expanded gives much more control over the visible content to the user.
This frees up space on the screen and makes the whole menu much more comfortable to use.

===Loading the data===
To be able to achieve this effect (as it is not a natural feature of gridlists) we will need to load the vehicle information into a table (from the xml file), rather than directly including it all in the gridlist.
'''If you are following on from a previous section of this tutorial, this new code will replace what is inside your existing 'populateGridlist' function.'''

This works in much the same way the previous xml loading example does, only this time instead of saving the data into the gridlist, we save it into a table entry instead.
We also set the custom data "header" on the gridlist slots to denote which gridlist entries are our "group" entries and which are vehicles.
<syntaxhighlight lang="lua">
function populateGridlist()
local rootnode = xmlLoadFile("vehicles.xml")

-- create a blank global table to store our imported data
vehicleTable = {}

if rootnode then
for _,group in ipairs(xmlNodeGetChildren(rootnode)) do
-- create an entry in the gridlist for every vehicle "group"
local row = guiGridListAddRow(gridlistVehicleSelection)

local name = xmlNodeGetAttribute(group,"type")

guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)

-- add an entry containing the group name into the table
vehicleTable[name] = {}

-- we will use the custom data "header" to indicate that this entry can be expanded/collapsed
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")

-- then, for every group that we find, loop all of its children (the vehicle nodes) and store them in a table
for _,vehicle in ipairs(xmlNodeGetChildren(group)) do
local vname = xmlNodeGetAttribute(vehicle,"name")
local id = xmlNodeGetAttribute(vehicle,"id")

-- insert both the vehicle id and the vehicle description into the table
table.insert(vehicleTable[name],{id,vname})
end
end

-- set element data on the gridlist so we know which group is currently showing
setElementData(gridlistVehicleSelection,"expanded","none")

-- unload the xml file now that we are finished
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>

Now that we have all the data stored, we can quickly manipulate it when neccessary.

===Managing the double click===
To enable the player to simply double click on a group name to expand/collapse it we need to use the [[onClientGUIDoubleClick]] event.
If we attach it to the gridlist, we can then catch any double clicks on the group names in it:
<syntaxhighlight lang="lua">
-- attach the onClientGUIDoubleClick event to the gridlist and set it to call processDoubleClick
addEventHandler("onClientGUIDoubleClick",gridlistVehicleSelection,processDoubleClick,false)
</syntaxhighlight>
Add this line of code in your createVehicleSelection, after the gridlist has been created.

As the gridlist items are not separate GUI elements, we must capture all clicks from anywhere on the gridlist then process them to filter out the ones we do not want.
This can be done by checking if an item is selected, then checking if the item is one of our "group" values (using our previously mentioned "header" data):
<syntaxhighlight lang="lua">
function processDoubleClick(button,state)
if button == "left" and state == "up" then
local row,col = guiGridListGetSelectedItem(gridlistVehicleSelection)

-- if something in the gridlist has been selected
if row and col and row ~= -1 and col ~= -1 then
-- if it is a header
if guiGridListGetItemData(gridlistVehicleSelection,row,col) == "header" then
local selected = guiGridListGetItemText(gridlistVehicleSelection,row,col)

-- call the function to collapse or expand the menu and pass which section it is as an argument
changeGridlistState(selected)
end
end
end
end
</syntaxhighlight>

Once we have narrowed down the double clicks to only those done on our group headers, we can expand/collapse them appropriately.
This can be done by simply setting new text values in the gridlist according to the newly expanded/collapsed group, which creates the convincing illusion of collapsable menus.

Note that much of the following code is reused from previous areas of this tutorial. While it is generally bad practice to clone sections of code in this way, for the purposes of this example it is far easier to understand.
<syntaxhighlight lang="lua">
function changeGridlistState(group)
if group then
-- if the group is already expanded, we want to collapse it
if getElementData(gridlistVehicleSelection,"expanded") == group then
-- first, we clear all previous data from the gridlist
guiGridListClear(gridlistVehicleSelection)

-- now, loop all the group entries in the vehicle table that we created earlier
for group,_ in pairs(vehicleTable) do
-- add each group to the list and mark them with "header"
local row = guiGridListAddRow(gridlistVehicleSelection)

guiGridListSetItemText(gridlistVehicleSelection,row,1,group,false,false)
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")
end

-- update the data to indicate that no groups are currently expanded
setElementData(gridlistVehicleSelection,"expanded","none")

-- otherwise, we want to expand it
else
guiGridListClear(gridlistVehicleSelection)

local row = guiGridListAddRow(gridlistVehicleSelection)

guiGridListSetItemText(gridlistVehicleSelection,row,1,group,false,false)
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")

-- loop every vehicle in the specified groups table
for _,vehicle in ipairs(vehicleTable[group]) do
-- add them to the gridlist and set the vehicle id as data
row = guiGridListAddRow(gridlistVehicleSelection)

-- format a "-" into the string to make it visually easier to distinguish between groups and vehicles
guiGridListSetItemText(gridlistVehicleSelection,row,1,"- "..vehicle[2],false,false)
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(tonumber(vehicle[1])),false,false)

guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(vehicle[1]))
end

-- update the data to indicate which group is currently expanded
setElementData(gridlistVehicleSelection,"expanded",group)
end
end
end
</syntaxhighlight>

This comletes the second section of the tutorial.

For further GUI tutorials, see [[Scripting the GUI - Tutorial 2|Tutorial 2 (Gates and Keypads)]]

Scripting the GUI - Tutorial 3

2010-01-05T21:50:30Z

R3mp:

'''Scripting the GUI - Tutorial 3 (Scrolling News Feed)'''

In this tutorial we will explore how to create a simple scrolling news feed GUI,
allowing you to quickly and easily show server updates and other server information to your players.
We will store all news items in a clientside xml file and use some simple xml reading to load them into the game.

We will then animate the news item to scroll along the bottom of the screen, updating the news text once it has scrolled beyond the edge of the screen.

'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|GUI Scripting Introduction]].'''

==Setting up the News Feed==
To begin, open up a clientside lua file (if you have been following the [[Introduction to Scripting GUI|GUI Scripting Introduction]], this is gui.lua) to work with.

===Creating the GUI===
As with the previous tutorial, you should be suitably familiar with GUI creation already so we will not go into too much detail here.
<syntaxhighlight lang="lua">
function createNewsFeed()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the gridlist, using some maths to find the bottom-centre of the screen
local Width,Height = 800,45
local X = (sWidth/2) - (Width/2)
local Y = sHeight - (Height/2)

-- the gridlist will act as the background to our news reel
newsGridlist = guiCreateGridList(X,Y,Width,Height,false)

-- create the label in the same place, but as a child of the gridlist
-- also make it half the height of the gridlist, as half of the gridlist is off the bottom of the screen
newsLabel = guiCreateLabel(X,Y,Width,Height/2,"Test text",false,newsGridlist)

-- call our function to read the news out of the xml file
loadNews()

-- load the first news item in the table
updateNewsItem(1)

-- define a global variable called 'currentItem' with the value 1
currentItem = 1
end

addEventHandler("onClientResourceStart",resourceRoot,createNewsFeed)
</syntaxhighlight>
Note that the label is created as a child of the gridlist.
Not only is this good practice in general, but it means that we can freely move parts of the label beyond the edge of the gridlist without them showing, which is critical to the visual effect of this tutorial.

Also notice the use of the 'resourceRoot' variable. This is an MTA variable that holds the root element value of the resource you are using it in.

The 'currentItem' variable is what we will use to keep track of which news item we are currently showing

===Writing the News===
Now that we have our GUI created, we need some news to fill it with.
To do this, we will read our news items out of a clientside xml file.

So, navigate to your resource directory and create a new xml file called newsfeed.xml (don't forget to add it to your meta.xml with the appropriate client tag).

Inside this file enter the following information:
<syntaxhighlight lang="lua">
<root>
<news>This is an example news item.</news>
<news>From the 'Scripting the GUI' tutorial.</news>
<news>Showing scrolling news text.</news>
<news>Written on a GUI news feed.</news>
</root>
</syntaxhighlight>
As you can see, each news item is defined as a <news> node with the value being the news text you want to display.
There is no limit on how many news items you can add.

===Collecting the News===
Once we have written all our news items, we will need to collect them all and store them in a table on the client.
We will do this when the resource starts, saving us from having to repeatedly access the xml for new news items.

First, we need to define a table to store the items in:
<syntaxhighlight lang="lua">
local newsItems = {}
</syntaxhighlight>
Add this line to the top of your script.
Make sure it is not inside a function otherwise it will not exist outside of that function (as denoted by the prefix "local").
When defined in the main body of the script it will exist in all functions.

Next, we will need to load the xml file:
<syntaxhighlight lang="lua">
function loadNews()
-- load our "newsfeed.xml" file
local newsfile = xmlLoadFile("newsfeed.xml")

-- if it was successfully loaded
if newsfile then

-- always remember to unload files once you are finished
xmlUnloadFile(newsfile)
end
end
</syntaxhighlight>
'''Always remember to unload files once you are finished using them.'''

Finally, we can add some more code to our loadNews function to read the news items into our newsItems table:
<syntaxhighlight lang="lua">
function loadNews()
local newsfile = xmlLoadFile("newsfeed.xml")

if newsfile then
-- loop through all the children of the root node (the "news" nodes)
for index,itemNode in ipairs(xmlNodeGetChildren(newsfile)) do
-- get the text (the news item) from the node
local item = xmlNodeGetValue(itemNode)

-- insert it into our newsItems table
table.insert(newsItems,item)
end

xmlUnloadFile(newsfile)
end
end
</syntaxhighlight>
We now have a table called 'newsItems' holding all of our news text from the xml file.

==Updating the News==
Now that we have our GUI created and our news items ready, we need to write some code to update the news item being shown to players.
As stated earlier, our news items will be shown on our 'newsLabel' GUI label.

To do this, we will write a simple function to get the next news item from our 'newsItems' table and display it in our label.
<syntaxhighlight lang="lua">
-- define our function with a newIndex parameter, so that we can pass which news item we want to show
function updateNewsItem(newIndex)
-- get the new news item from the table
local item = newsItems[newIndex]

-- update the label text
guiSetText(newsLabel,item)

-- update the 'currentItem' global variable
currentItem = newIndex
end
</syntaxhighlight>

===Sizing the Label===
To make our news scrolling as accurate as possible, we need to be able to make the GUI label the same size as the news item text it is showing.

While this may seem like a tricky thing to do, it is made very easy with the function [[guiLabelGetTextExtent]].
This will tell us the extent, or width, of the text currently shown in our label.
So with a few modifications to our 'updateNewsItems' function, we get:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
local item = newsItems[newIndex]

guiSetText(newsLabel,item)

currentItem = newIndex

-- get the current dimensions of the gui label
local width,height = guiGetSize(newsLabel,false)

-- get the text width of the label
local extent = guiLabelGetTextExtent(newsLabel)

-- update the size of the label with the new width (we do not change the height)
guiSetSize(newsLabel,extent,height,false)
end
</syntaxhighlight>

===Positioning the Label===
Now that our GUI label is the correct width, we need to move it to a position where it is ready to scroll onto the screen.

Again, we can do this with a small modification to our 'updateNewsItems' function:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
local item = newsItems[newIndex]

guiSetText(newsLabel,item)

currentItem = newIndex

local width,height = guiGetSize(newsLabel,false)

local extent = guiLabelGetTextExtent(newsLabel)

guiSetSize(newsLabel,extent,height,false)

-- set the positon to the far right side of the gridlist, ready to scroll on to the left
guiSetPosition(newsLabel,1,0,true)
end
</syntaxhighlight>

==Scrolling the News==
The next step is to animate our news feed.

===Looking at Frames===
To do this, we will introduce a new event: [[onClientRender]].
As stated on the [[onClientRender]] wiki page, this event is called every time GTA renders a new frame (ie: very often).

As usual, to use this event we will need to create an event handler for it:
<syntaxhighlight lang="lua">
addEventHandler("onClientRender",root,scrollNews)
</syntaxhighlight>
This will call our scrollNews function every frame, which we will then use to update the position of our news item.

'''Make sure you add this handler after you have defined your scrollNews function.'''

For our purposes, [[onClientRender]] has one main advantage over, for example, [[setTimer]].
As it is called every frame (and therefore is dependant on the players FPS), the movement of the news item will always appear to be completely smooth,
unlike using a timer which would often appear to lag.

===Moving the News===
In our 'updateNewsItem' function, we position the 'newsLabel' to the far right, so we will scroll in from the right to the left.

For this we will simply move the X position by -1 every frame:
<syntaxhighlight lang="lua">
function scrollNews()
-- if the newsLabel exists
if newsLabel then
-- get the current position of the label
local x,y = guiGetPosition(newsLabel,false)

-- set the new x position of the label as the old position -1
guiSetPosition(newsLabel,x-1,y,false)
end
end
</syntaxhighlight>

===Looping around===
Now that our news scrolls across the screen, we need to be able to check when it has scrolled too far to the left
so we can start scrolling from the far-right side again.

We will also need to update the news item, so we should check the next item exists, and if it doesn't, go back to the first.

For this we will use some simple maths in a modification to our 'scrollNews' function:
<syntaxhighlight lang="lua">
function scrollNews()
local x,y = guiGetPosition(newsLabel,false)

local labelWidth, labelHeight = guiGetSize(newsLabel,false)

-- if the far right position of the label (x + labelWidth) is greater than or equal to 0 (ie: still showing on the gridlist)
if ((x-1) + labelWidth) >= 0 then
-- compensate for a small off-by-one bug in MTA
if x <= 0 then x = x - 1 end

-- update the position as normal
guiSetPosition(newsLabel,x-1,y,false)

-- otherwise, we move on to the next item and reset the position
else
-- get the total number of items in the 'newsItems' table
local totalItems = #newsItems

-- if the next item on our list does not exist in our table
if (currentItem + 1) > totalItems then
-- loop back to the first item in the list
updateNewsItem(1)
else
-- otherwise move onto the next item in the list
updateNewsItem(currentItem + 1)
end
end
end
</syntaxhighlight>
Notice the use of the '#' symbol to get the size of the 'newsItems' table.
This is the Lua length operator, but it only works on tables that have numerical indexes (like an array or a list).
It also works on strings, eg: #"hello" would return 5.

That completes this section of the tutorial.
For ideas on how to further improve and advance this code, continue reading the next section.

==Improving the code==
This section will detail several ways to improve upon the code you now have.

===GUI Customisation===
To give your GUI a more unique feel, you have the ability to customise some aspects of your GUI elements.

For ideas on what is possible, browse the [[Client_Scripting_Functions#GUI_functions|MTA GUI functions]].

For the purposes of this tutorial, we will be using Font, Colour and Alpha.

To start, we will change the alpha of the background gridlist GUI element we are using.
To set the alpha, use [[guiSetAlpha]] and pass a value between 1 and 0; 1 being fully opaque and 0 being fully transparent.
<syntaxhighlight lang="lua">
guiSetAlpha(newsGridlist,0.8)
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your gridlist has been created.

I find an alpha level of 0.8 looks best, however this is personal preference and you can experiment to suit your needs.

Next, we will look at the font of the label text.
To set the font, use [[guiSetFont]] and pass the string name of the font you want to use (available to see on the [[GUI Fonts]] page).
<syntaxhighlight lang="lua">
guiSetFont(newsLabel,"default-bold-small")
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your label has been created.

Finally, we will look at setting the colour of the label text.
To set the colour, use [[guiLabelSetColor]] and pass the individual red,green and blue values.
<syntaxhighlight lang="lua">
guiLabelSetColor(newsLabel,255,70,0)
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your label has been created.

This will give your news items an orange-red colour.

===Multiple News Items===
In its current form, this code is only capable of showing one news item at a time.
However, with a few modifications we can show multiple news items at once, one after another.

To begin with, we need to make sure we have a 'newItems' table defined at the very start of our script,
as well as a 'distance' variable that will control the pixel distance between each news item:
<syntaxhighlight lang="lua">
local newsItems = {}
local distance = 30
</syntaxhighlight>
So put these lines at the top of the file.

Next, we will not know how many items we have (and consequently, how many labels we need) until we have loaded the file.
With that in mind, we will move around some of the code in our 'createNewsFeed' function to support this:
<syntaxhighlight lang="lua">
function createNewsFeed()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the gridlist, using some maths to find the bottom-centre of the screen
local Width,Height = 800,45
local X = (sWidth/2) - (Width/2)
local Y = sHeight - (Height/2)

-- the gridlist will act as the background to our news reel
newsGridlist = guiCreateGridList(X,Y,Width,Height,false)

guiSetAlpha(newsGridlist,0.8)

-- call our function to read the news out of the xml file, before we create the labels
loadNews()

-- define a table to hold our labels
newsLabel = {}

-- now we can loop all our news items, and create a label for each one
for index,item in ipairs(newsItems) do

-- because we now have one label for every item, we can just set the text here and it wont need to be changed again.
newsLabel[index] = guiCreateLabel(0,0,Width,Height/2,item,false,newsGridlist)

guiSetFont(newsLabel[index],"default-bold-small")

guiLabelSetColor(newsLabel[index],255,70,0)

-- modify the width of the label to fit the text
local extent = guiLabelGetTextExtent(newsLabel[index])
guiSetSize(newsLabel[index],extent,Height/2,false)

-- get the size of the gridlist
local x,y = guiGetSize(newsGridlist,false)

-- loop from 1 until index-1 in steps of 1
-- this allows us to loop every label before the label we are currently on
for i=1, index-1, 1 do
-- tally up the sizes of all labels before our current one and store them in x
local width = guiGetSize(newsLabel[i],false)
x = x + width
end

-- put a 'distance' pixel gap between each news item
x = x + (distance*(index-1))

-- set the positon to the far right side of the gridlist, ready to scroll on to the left
guiSetPosition(newsLabel[index],x,0,false)
end
end
</syntaxhighlight>

Now we need to update our 'updateNewsItem' function to account for having multiple labels:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
-- find the index of the news item directly infront (in the looping order) of the newIndex item
local index = newIndex - 1
if index == 0 then index = #newsItems end

-- find the position of the right-edge of the label directly infront of the newIndex label
local x = guiGetPosition(newsLabel[index],false)
local width = guiGetSize(newsLabel[index],false)
x = x + width

-- add a 'distance' pixel gap in
x = x + distance

-- check the new position isnt actually on the gridlist (ie: so it wont suddenly appear in the centre of the list)
local gridlistWidth = guiGetSize(newsGridlist,false)

if x < gridlistWidth then
-- if it is, simple move it back to the edge
x = gridlistWidth
end

-- set the new position
guiSetPosition(newsLabel[newIndex],x,0,false)
end
</syntaxhighlight>

Finally, we need to make some small adjustments to our 'scrollNews' function:
<syntaxhighlight lang="lua">
function scrollNews()
if newsItems then
-- loop every news item
for index,item in ipairs(newsItems) do
local x,y = guiGetPosition(newsLabel[index],false)

local labelWidth, labelHeight = guiGetSize(newsLabel[index],false)

-- if the far right position of the label (x + labelWidth) is greater than or equal to 0 (ie: still showing on the gridlist)
if ((x-1) + labelWidth) >= 0 then
-- compensate for a small off-by-one bug in MTA
if x <= 0 then x = x - 1 end

-- update the position as normal
guiSetPosition(newsLabel[index],x-1,y,false)

-- otherwise, we move on to the next item and reset the position
else
updateNewsItem(index)
end
end
end
end
</syntaxhighlight>

You should now have multiple news items scrolling along your news feed simultaneously.

===Globally controlled scroll speed===
As with the 'distance' variable above, we can set a global variable for controlling the scroll speed of the news items as well.
Note that the speed will still be dependant on the players FPS (ie: lower FPS means slightly slower scrolling).

To do this, we simply need to create the variable at the start of our code:
<syntaxhighlight lang="lua">
local scrollSpeed = 1
</syntaxhighlight>
Put this line at the top of your file.

Then, we just replace the instance of "x-1" in our 'scrollNews' function with "x-scrollSpeed":
<syntaxhighlight lang="lua">
function scrollNews()
...
-- update the position as normal
guiSetPosition(newsLabel[index],x-scrollSpeed,y,false)
...
end
end
</syntaxhighlight>
That concludes this section of the tutorial.

Scripting the GUI - Tutorial 3

2010-01-05T21:19:29Z

R3mp:

'''Scripting the GUI - Tutorial 3 (Scrolling News Feed)'''

In this tutorial we will explore how to create a simple scrolling news feed GUI,
allowing you to quickly and easily show server updates and other server information to your players.
We will store all news items in a clientside xml file and use some simple xml reading to load them into the game.

We will then animate the news item to scroll along the bottom of the screen, updating the news text once it has scrolled beyond the edge of the screen.

'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|GUI Scripting Introduction]].'''

==Setting up the News Feed==
To begin, open up a clientside lua file (if you have been following the [[Introduction to Scripting GUI|GUI Scripting Introduction]], this is gui.lua) to work with.

===Creating the GUI===
As with the previous tutorial, you should be suitably familiar with GUI creation already so we will not go into too much detail here.
<syntaxhighlight lang="lua">
function createNewsFeed()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the gridlist, using some maths to find the bottom-centre of the screen
local Width,Height = 800,45
local X = (sWidth/2) - (Width/2)
local Y = sHeight - (Height/2)

-- the gridlist will act as the background to our news reel
newsGridlist = guiCreateGridList(X,Y,Width,Height,false)

-- create the label in the same place, but as a child of the gridlist
-- also make it half the height of the gridlist, as half of the gridlist is off the bottom of the screen
newsLabel = guiCreateLabel(X,Y,Width,Height/2,"Test text",false,newsGridlist)

-- call our function to read the news out of the xml file
loadNews()

-- load the first news item in the table
updateNewsItem(1)

-- define a global variable called 'currentItem' with the value 1
currentItem = 1
end

addEventHandler("onClientResourceStart",resourceRoot,createNewsFeed)
</syntaxhighlight>
Note that the label is created as a child of the gridlist.
Not only is this good practice in general, but it means that we can freely move parts of the label beyond the edge of the gridlist without them showing, which is critical to the visual effect of this tutorial.

Also notice the use of the 'resourceRoot' variable. This is an MTA variable that holds the root value of the resource you are using it in.

The 'currentItem' variable is what we will use to keep track of which news item we are currently showing

===Writing the News===
Now that we have our GUI created, we need some news to fill it with.
To do this, we will read our news items out of a clientside xml file.

So, navigate to your resource directory and create a new xml file called newsfeed.xml (don't forget to add it to your meta.xml with the appropriate client tag).

Inside this file enter the following information:
<syntaxhighlight lang="lua">
<root>
<news>This is an example news item.</news>
<news>From the 'Scripting the GUI' tutorial.</news>
<news>Showing scrolling news text.</news>
<news>Written on a GUI news feed.</news>
</root>
</syntaxhighlight>
As you can see, each news item is defined as a <news> node with the value being the news text you want to display.
There is no limit on how many news items you can add.

===Collecting the News===
Once we have written all our news items, we will need to collect them all and store them in a table on the client.
We will do this when the resource starts, saving us from having to repeatedly access the xml for new news items.

First, we need to define a table to store the items in:
<syntaxhighlight lang="lua">
local newsItems = {}
</syntaxhighlight>
Add this line to the top of your script.
Make sure it is not inside a function otherwise it will not exist outside of that function (as denoted by the prefix "local").
When defined in the main body of the script it will exist in all functions.

Next, we will need to load the xml file:
<syntaxhighlight lang="lua">
function loadNews()
-- load our "newsfeed.xml" file
local newsfile = xmlLoadFile("newsfeed.xml")

-- if it was successfully loaded
if newsfile then

-- always remember to unload files once you are finished
xmlUnloadFile(newsfile)
end
end
</syntaxhighlight>
'''Always remember to unload files once you are finished using them.'''

Finally, we can add some more code to our loadNews function to read the news items into our newsItems table:
<syntaxhighlight lang="lua">
function loadNews()
local newsfile = xmlLoadFile("newsfeed.xml")

if newsfile then
-- loop through all the children of the root node (the "news" nodes)
for index,itemNode in ipairs(xmlNodeGetChildren(newsfile)) do
-- get the text (the news item) from the node
local item = xmlNodeGetValue(itemNode)

-- insert it into our newsItems table
table.insert(newsItems,item)
end

xmlUnloadFile(newsfile)
end
end
</syntaxhighlight>
We now have a table called 'newsItems' holding all of our news text from the xml file.

==Updating the News==
Now that we have our GUI created and our news items ready, we need to write some code to update the news item being shown to players.
As stated earlier, our news items will be shown on our 'newsLabel' GUI label.

To do this, we will write a simple function to get the next news item from our 'newsItems' table and display it in our label.
<syntaxhighlight lang="lua">
-- define our function with a newIndex parameter, so that we can pass which news item we want to show
function updateNewsItem(newIndex)
-- get the new news item from the table
local item = newsItems[newIndex]

-- update the label text
guiSetText(newsLabel,item)

-- update the 'currentItem' global variable
currentItem = newIndex
end
</syntaxhighlight>

===Sizing the Label===
To make our news scrolling as accurate as possible, we need to be able to make the GUI label the same size as the news item text it is showing.

While this may seem like a tricky thing to do, it is made very easy with the function [[guiLabelGetTextExtent]].
This will tell us the extent, or width, of the text currently shown in our label.
So with a few modifications to our 'updateNewsItems' function, we get:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
local item = newsItems[newIndex]

guiSetText(newsLabel,item)

currentItem = newIndex

-- get the current dimensions of the gui label
local width,height = guiGetSize(newsLabel,false)

-- get the text width of the label
local extent = guiLabelGetTextExtent(newsLabel)

-- update the size of the label with the new width (we do not change the height)
guiSetSize(newsLabel,extent,height,false)
end
</syntaxhighlight>

===Positioning the Label===
Now that our GUI label is the correct width, we need to move it to a position where it is ready to scroll onto the screen.

Again, we can do this with a small modification to our 'updateNewsItems' function:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
local item = newsItems[newIndex]

guiSetText(newsLabel,item)

currentItem = newIndex

local width,height = guiGetSize(newsLabel,false)

local extent = guiLabelGetTextExtent(newsLabel)

guiSetSize(newsLabel,extent,height,false)

-- set the positon to the far right side of the gridlist, ready to scroll on to the left
guiSetPosition(newsLabel,1,0,true)
end
</syntaxhighlight>

==Scrolling the News==
The next step is to animate our news feed.

===Looking at Frames===
To do this, we will introduce a new event: [[onClientRender]].
As stated on the [[onClientRender]] wiki page, this event is called every time GTA renders a new frame (ie: very often).

As usual, to use this event we will need to create an event handler for it:
<syntaxhighlight lang="lua">
addEventHandler("onClientRender",root,scrollNews)
</syntaxhighlight>
This will call our scrollNews function every frame, which we will then use to update the position of our news item.

'''Make sure you add this handler after you have defined your scrollNews function.'''

For our purposes, [[onClientRender]] has one main advantage over, for example, [[setTimer]].
As it is called every frame (and therefore is dependant on the players FPS), the movement of the news item will always appear to be completely smooth,
unlike using a timer which would often appear to lag.

===Moving the News===
In our 'updateNewsItem' function, we position the 'newsLabel' to the far right, so we will scroll in from the right to the left.

For this we will simply move the X position by -1 every frame:
<syntaxhighlight lang="lua">
function scrollNews()
-- if the newsLabel exists
if newsLabel then
-- get the current position of the label
local x,y = guiGetPosition(newsLabel,false)

-- set the new x position of the label as the old position -1
guiSetPosition(newsLabel,x-1,y,false)
end
end
</syntaxhighlight>

===Looping around===
Now that our news scrolls across the screen, we need to be able to check when it has scrolled too far to the left
so we can start scrolling from the far-right side again.

We will also need to update the news item, so we should check the next item exists, and if it doesn't, go back to the first.

For this we will use some simple maths in a modification to our 'scrollNews' function:
<syntaxhighlight lang="lua">
function scrollNews()
local x,y = guiGetPosition(newsLabel,false)

local labelWidth, labelHeight = guiGetSize(newsLabel,false)

-- if the far right position of the label (x + labelWidth) is greater than or equal to 0 (ie: still showing on the gridlist)
if ((x-1) + labelWidth) >= 0 then
-- compensate for a small off-by-one bug in MTA
if x <= 0 then x = x - 1 end

-- update the position as normal
guiSetPosition(newsLabel,x-1,y,false)

-- otherwise, we move on to the next item and reset the position
else
-- get the total number of items in the 'newsItems' table
local totalItems = #newsItems

-- if the next item on our list does not exist in our table
if (currentItem + 1) > totalItems then
-- loop back to the first item in the list
updateNewsItem(1)
else
-- otherwise move onto the next item in the list
updateNewsItem(currentItem + 1)
end
end
end
</syntaxhighlight>
Notice the use of the '#' symbol to get the size of the 'newsItems' table.
This is the Lua length operator, but it only works on tables that have numerical indexes (like an array or a list).
It also works on strings, eg: #"hello" would return 5.

That completes this section of the tutorial.
For ideas on how to further improve and advance this code, continue reading the next section.

==Improving the code==
This section will detail several ways to improve upon the code you now have.

===GUI Customisation===
To give your GUI a more unique feel, you have the ability to customise some aspects of your GUI elements.

For ideas on what is possible, browse the [[Client_Scripting_Functions#GUI_functions|MTA GUI functions]].

For the purposes of this tutorial, we will be using Font, Colour and Alpha.

To start, we will change the alpha of the background gridlist GUI element we are using.
To set the alpha, use [[guiSetAlpha]] and pass a value between 1 and 0; 1 being fully opaque and 0 being fully transparent.
<syntaxhighlight lang="lua">
guiSetAlpha(newsGridlist,0.8)
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your gridlist has been created.

I find an alpha level of 0.8 looks best, however this is personal preference and you can experiment to suit your needs.

Next, we will look at the font of the label text.
To set the font, use [[guiSetFont]] and pass the string name of the font you want to use (available to see on the [[GUI Fonts]] page).
<syntaxhighlight lang="lua">
guiSetFont(newsLabel,"default-bold-small")
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your label has been created.

Finally, we will look at setting the colour of the label text.
To set the colour, use [[guiLabelSetColor]] and pass the individual red,green and blue values.
<syntaxhighlight lang="lua">
guiLabelSetColor(newsLabel,255,70,0)
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your label has been created.

This will give your news items an orange-red colour.

===Multiple News Items===
In its current form, this code is only capable of showing one news item at a time.
However, with a few modifications we can show multiple news items at once, one after another.

To begin with, we need to make sure we have a 'newItems' table defined at the very start of our script,
as well as a 'distance' variable that will control the pixel distance between each news item:
<syntaxhighlight lang="lua">
local newsItems = {}
local distance = 30
</syntaxhighlight>
So put these lines at the top of the file.

Next, we will not know how many items we have (and consequently, how many labels we need) until we have loaded the file.
With that in mind, we will move around some of the code in our 'createNewsFeed' function to support this:
<syntaxhighlight lang="lua">
function createNewsFeed()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the gridlist, using some maths to find the bottom-centre of the screen
local Width,Height = 800,45
local X = (sWidth/2) - (Width/2)
local Y = sHeight - (Height/2)

-- the gridlist will act as the background to our news reel
newsGridlist = guiCreateGridList(X,Y,Width,Height,false)

guiSetAlpha(newsGridlist,0.8)

-- call our function to read the news out of the xml file, before we create the labels
loadNews()

-- define a table to hold our labels
newsLabel = {}

-- now we can loop all our news items, and create a label for each one
for index,item in ipairs(newsItems) do

-- because we now have one label for every item, we can just set the text here and it wont need to be changed again.
newsLabel[index] = guiCreateLabel(0,0,Width,Height/2,item,false,newsGridlist)

guiSetFont(newsLabel[index],"default-bold-small")

guiLabelSetColor(newsLabel[index],255,70,0)

-- modify the width of the label to fit the text
local extent = guiLabelGetTextExtent(newsLabel[index])
guiSetSize(newsLabel[index],extent,Height/2,false)

-- get the size of the gridlist
local x,y = guiGetSize(newsGridlist,false)

-- loop from 1 until index-1 in steps of 1
-- this allows us to loop every label before the label we are currently on
for i=1, index-1, 1 do
-- tally up the sizes of all labels before our current one and store them in x
local width = guiGetSize(newsLabel[i],false)
x = x + width
end

-- put a 'distance' pixel gap between each news item
x = x + (distance*(index-1))

-- set the positon to the far right side of the gridlist, ready to scroll on to the left
guiSetPosition(newsLabel[index],x,0,false)
end
end
</syntaxhighlight>

Now we need to update our 'updateNewsItem' function to account for having multiple labels:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
-- find the index of the news item directly infront (in the looping order) of the newIndex item
local index = newIndex - 1
if index == 0 then index = #newsItems end

-- find the position of the right-edge of the label directly infront of the newIndex label
local x = guiGetPosition(newsLabel[index],false)
local width = guiGetSize(newsLabel[index],false)
x = x + width

-- add a 'distance' pixel gap in
x = x + distance

-- check the new position isnt actually on the gridlist (ie: so it wont suddenly appear in the centre of the list)
local gridlistWidth = guiGetSize(newsGridlist,false)

if x < gridlistWidth then
-- if it is, simple move it back to the edge
x = gridlistWidth
end

-- set the new position
guiSetPosition(newsLabel[newIndex],x,0,false)
end
</syntaxhighlight>

Finally, we need to make some small adjustments to our 'scrollNews' function:
<syntaxhighlight lang="lua">
function scrollNews()
if newsItems then
-- loop every news item
for index,item in ipairs(newsItems) do
local x,y = guiGetPosition(newsLabel[index],false)

local labelWidth, labelHeight = guiGetSize(newsLabel[index],false)

-- if the far right position of the label (x + labelWidth) is greater than or equal to 0 (ie: still showing on the gridlist)
if ((x-1) + labelWidth) >= 0 then
-- compensate for a small off-by-one bug in MTA
if x <= 0 then x = x - 1 end

-- update the position as normal
guiSetPosition(newsLabel[index],x-1,y,false)

-- otherwise, we move on to the next item and reset the position
else
updateNewsItem(index)
end
end
end
end
</syntaxhighlight>

You should now have multiple news items scrolling along your news feed simultaneously.

===Globally controlled scroll speed===
As with the 'distance' variable above, we can set a global variable for controlling the scroll speed of the news items as well.
Note that the speed will still be dependant on the players FPS (ie: lower FPS means slightly slower scrolling).

To do this, we simply need to create the variable at the start of our code:
<syntaxhighlight lang="lua">
local scrollSpeed = 1
</syntaxhighlight>
Put this line at the top of your file.

Then, we just replace the instance of "x-1" in our 'scrollNews' function with "x-scrollSpeed":
<syntaxhighlight lang="lua">
function scrollNews()
...
-- update the position as normal
guiSetPosition(newsLabel[index],x-scrollSpeed,y,false)
...
end
end
</syntaxhighlight>
That concludes this section of the tutorial.

Scripting the GUI - Tutorial 2

2010-01-05T21:19:12Z

R3mp:

'''Scripting the GUI - Tutorial 2 (Gates + Keypads)'''

In this tutorial we will look at creating GUI keypads with combination codes for map-defined object gates.
We will be using serverside keycodes, with some client - server interaction to verify the codes and report the outcome.

'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|GUI Scripting Introduction]].'''

[[Image:Gui_keypad_tutorial.png|thumb|GUI Keypad]]

==Setting up the Keypad==
To begin, open up a clientside lua file (if you have been following the [[Introduction to Scripting GUI|GUI Scripting Introduction]], this is gui.lua) to work with.

===Creating the GUI===
By now, GUI creation should seem relatively straight forward, so we will not go over this in too much detail.
As in [[Scripting the GUI - Tutorial 1|Tutorial 1]] we will be using '''absolute''' values in this tutorial.

<syntaxhighlight lang="lua">
function createKeypad()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 142,276
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)
keypadWindow = guiCreateWindow(X,Y,Width,Height,"Keypad",false)

-- don't allow people to resize the keypad
guiWindowSetSizable(keypadWindow,false)

-- create buttons labeled 0-9, "*", "#", "Enter" and "C" (clear)
keypadButton1 = guiCreateButton(13,68,37,36,"1",false,keypadWindow)
keypadButton2 = guiCreateButton(53,68,37,36,"2",false,keypadWindow)
keypadButton3 = guiCreateButton(93,68,37,36,"3",false,keypadWindow)
keypadButton4 = guiCreateButton(13,108,37,36,"4",false,keypadWindow)
keypadButton5 = guiCreateButton(53,108,37,36,"5",false,keypadWindow)
keypadButton6 = guiCreateButton(93,108,37,36,"6",false,keypadWindow)
keypadButton7 = guiCreateButton(13,148,37,36,"7",false,keypadWindow)
keypadButton8 = guiCreateButton(53,148,37,36,"8",false,keypadWindow)
keypadButton9 = guiCreateButton(93,148,37,36,"9",false,keypadWindow)
keypadButtonAsterix = guiCreateButton(13,188,37,36,"*",false,keypadWindow)
keypadButton0 = guiCreateButton(53,188,37,36,"0",false,keypadWindow)
keypadButtonHash = guiCreateButton(93,188,37,36,"#",false,keypadWindow)
keypadButtonExit = guiCreateButton(13,228,37,36,"Exit",false,keypadWindow)
keypadButtonEnter = guiCreateButton(53,228,37,36,"Enter",false,keypadWindow)
keypadButtonClear = guiCreateButton(93,228,37,36,"Clear",false,keypadWindow)

-- create a gridlist to act as a backdrop on the kaypad display
keypadGridlistDisplay = guiCreateGridList(13,25,117,33,false,keypadWindow)
guiGridListSetSelectionMode(keypadGridlistDisplay,2)
guiSetAlpha(keypadGridlistDisplay,0.6)
-- create a label so we can write text on the keypad display
keypadLabelDisplay = guiCreateLabel(14,26,115,30,"Enter Keycode.",false,keypadWindow)
guiLabelSetColor(keypadLabelDisplay,255,000,000)
guiLabelSetVerticalAlign(keypadLabelDisplay,"center")
guiLabelSetHorizontalAlign(keypadLabelDisplay,"center",false)

guiSetVisible(keypadWindow,false)
end

-- create the GUI when the resource starts
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()),createKeypad)
</syntaxhighlight>
As you can see, the keypad consists of 10 numerical keys (0-9), two character keys (* and #), a clear key, an exit key and an enter key.
This means the codes used on the keypad can contain any of these characters (0123456789*#).

===Managing the display===
We will begin by writing a small function to control the display on the keypad.
This is done by encapsulating several methods of changing the text into a single function,
which will enable us to easily add/remove text from the display later on.
<syntaxhighlight lang="lua">
function updateDisplay(text)
-- if we are passing some text
if text then
-- if its a digit or * or #, then append it to the end of the display
if tonumber(text) or text == "*" or text == "#" then
guiSetText(keypadLabelDisplay,guiGetText(keypadLabelDisplay) .. text)
-- otherwise replace the display with the new text
else
guiSetText(keypadLabelDisplay,text)
end
-- if we pass nil, clear the display entirely
else
guiSetText(keypadLabelDisplay,"")
end
end
</syntaxhighlight>
We can now simply call updateDisplay(our text) to change the text on the display, or updateDisplay(nil) to clear it.

===Detecting the clicks===
With so many buttons that do very similar tasks on our keypad, there are two methods available to us for detecting when a player clicks on them.

We could add [[onClientGUIClick]] events for every button individually, as we have done in previous tutorials; Or, alternatively,
we could add a single [[onClientGUIClick]] handle for the window (which is the parent of all our other keypad GUI elements), filter our results to include only the buttons we want and trigger our own custom event.

For the purposes of this tutorial and in the interest of outlining multiple approaches, we will explore the second method, though either one is an acceptable solution.
<syntaxhighlight lang="lua">
addEventHandler("onClientGUIClick",keypadWindow,processKeypadClicks,true)
</syntaxhighlight>
'''Notice the final argument is set to 'true'. This means that clicks on any other elements in the same branch of the tree will also trigger this event handle (eg. clicks on our buttons).'''

Add this line of code into your createKeypad function, after your GUI has been created.

Now that we are detecting all clicks on our GUI, we need to filter out the ones we do not want (ie: clicks on the window or display) and trigger our custom event:
<syntaxhighlight lang="lua">
function processKeypadClicks(button,state)
if button == "left" and state == "up" then
-- if the source of this event is a gui button
if getElementType(source) == "gui-button" then
-- trigger our custom event and send the keypad id of this keypad as an argument
triggerEvent("onKeypadButtonClicked",source,getElementData(keypadWindow,"keypadID"))
end
end
end
</syntaxhighlight>
As you can see, we are now triggering our custom event "onKeypadButtonClicked" whenever a button is clicked on the keypad.
Also note we use element data "keypadID" to differentiate between keypads. This data will need to be set whenever the player is shown a new keypad.
We will cover this in more detail later.

===Handling the clicks===
Much like when using [[triggerServerEvent]] in previous tutorials, we now need to define the event, only this time it is purely clientside:
<syntaxhighlight lang="lua">
addEvent("onKeypadButtonClicked",false)
addEventHandler("onKeypadButtonClicked",root,
function(keypadID)

end
)
</syntaxhighlight>
Note the second argument in [[addEvent]] is set to false, indicating that this event cannot be triggered from the server.
Also note, the function we are using in the [[addEventHandler]] does not have a name. If you contract it down and remove the spacing, you get:
<syntaxhighlight lang="lua">
addEventHandler("onKeypadButtonClicked",root,function() ... end)
</syntaxhighlight>
This simply means instead of storing the pointer to the function in a variable, we are passing it directly as an argument.
Doing it this way cleans up the code and will often make it easier to follow.

Now that the event has been created, we can fill in the code logic that will control our button presses.
<syntaxhighlight lang="lua">
addEvent("onKeypadButtonClicked",false)
addEventHandler("onKeypadButtonClicked",root,
function(keypadID)
-- clear the display if this is the first time its being used
if guiGetText(keypadLabelDisplay) == "Enter Keycode." or guiGetText(keypadLabelDisplay) == "Invalid Keycode." then
updateDisplay()
end

-- if its the clear button
if guiGetText(source) == "Clear" then
-- clear the display
updateDisplay()

-- if its the enter button
elseif guiGetText(source) == "Enter" then
-- get the currently entered code from the display
local code = guiGetText(keypadLabelDisplay)

-- if they have entered a code
if code then
-- trigger the server so we can verify their code
triggerServerEvent("verifyKeypadCode",getLocalPlayer(),code,keypadID)
end

-- if its the exit button
elseif guiGetText(source) == "Exit" then
-- hide the keypad and reset the display text ready for next time
guiSetVisible(keypadWindow,false)
updateDisplay("Enter Keycode.")
showCursor(false,false)

-- otherwise, it must be a character button
else
updateDisplay(guiGetText(source))
end
end
)
</syntaxhighlight>

==Serverside Verification==
For this part of the tutorial, you will need to open up a serverside lua file from your resource to work with.

===Defining the keycode===
Now that we have completed the keypad clicking logic, we need to move on to verifying the code entered into the keypad.
To do this, we need to have the correct code stored somewhere on the server, which we can check the players code against.

For the purposes of this tutorial we will simply store the code in a serverside table, however it can be done any number of ways (such as serverside xml files or MySQL databases).
<syntaxhighlight lang="lua">
local keypadCodes = {
["a51MainGateKeypadCode"] = "4455*#"
}
</syntaxhighlight>
This table stores an entry called "a51MainGateKeypadCode" with the code 4455*#

'''This is the keycode that you will use to open the gate later on in this tutorial.'''

===Verifying the code===
Now that we have a keycode to verify against, we can write our serverside event:
<syntaxhighlight lang="lua">
addEvent("verifyKeypadCode",true)
addEventHandler("verifyKeypadCode",root,function(code,keypadID)
if code then
-- using the table we created earlier, check if the code supplied is the same as the code for this gate
if code == keypadCodes[keypadID] then
-- if it is, tell the client that it was successful
triggerClientEvent(client,"onKeypadVerificationSuccessful",client,keypadID)
else
-- if it is not, tell the client that it was not successful
triggerClientEvent(client,"onKeypadVerificationFailed",client,keypadID)
end
end
end)
</syntaxhighlight>
Here we use our table and the keypadID supplied by the player to check if the codes match.

If you are not using a table to store the codes, then you will need to replace 'keypadCodes[keypadID]' with your own storage method.
Once it is verified (or not), we can trigger the client so the appropriate information can be shown on the keypad display.

==Receiving the result==
We have now finished the serverside section of the tutorial, so you will need to open up the clientside lua file from your resource
that you were previously working on.

Once our code has been verified, the server will send back the response to the client.
In just the same way as client -> server interaction, we now need to add the event that the server is going to trigger on the client.

===Catching and processing the result===
First we will add the event for when the verification is successful:
<syntaxhighlight lang="lua">
addEvent("onKeypadVerificationSuccessful",true)
addEventHandler("onKeypadVerificationSuccessful",root,
function()
-- hide the keypad and reset the display text ready for next time
guiSetVisible(keypadWindow,false)
updateDisplay("Enter Keycode.")
showCursor(false,false)
end
)
</syntaxhighlight>

Finally we can add the event for when the verification is unsuccessful:
<syntaxhighlight lang="lua">
addEvent("onKeypadVerificationFailed",true)
addEventHandler("onKeypadVerificationFailed",root,
function()
-- update the display text to show the code was invalid
updateDisplay("Invalid Keycode.")
end
)
</syntaxhighlight>

This completes the keypad section of the tutorial.

For an example of how to implement this into a working gate system, carry on reading the next section.

==Applying the Keypad==
For the keypad to have any use, we need something to use it on.
For this tutorial we will be using gates, and as mentioned earlier we will create a main gate into A51.

===Creating the gate===
First of all, we need to create the gate object.
For the purposes of this example, we will be using a map file to store the object.
While this is the recommended method for defining objects, it is not the only way to approach it.

Navigate to your resource folder and make a new file called gate.map, then add your new map file to your meta.xml using:
<syntaxhighlight lang="lua">
<map src="gate.map"/>
</syntaxhighlight>

''If you are unsure of map file syntax, please see the [[Writing_Gamemodes| Writing Gamemodes Tutorial]] or check the [[Object]] page for help.''
<syntaxhighlight lang="lua">
<map>
<object id="a51MainGateKeypadCode" model="971" posX="96.736" posY="1918.352" posZ="20.694" rotX="0" rotY="0" rotZ="270.40" newPosX="96.751" newPosY="1914.474" newPosZ="20.694" />
</map>
</syntaxhighlight>
This will create a gate object across the A51 entrance. The object will have position and rotation data, as well as its newPosX,newPosY and newPosZ information that we need to be able to move it.

'''Note that the object id is the same as the table entry we created earlier to hold the access code.'''
This is one possible method that could be accessed to link this gate with that particular keycode.

===Opening the keypad===
Back in the clientside lua file again, we can now work on linking the gate and the keypad.

Now that we have our gate, we need a way of accessing the keypad to open it.
For the purposes of this tutorial we will use a simple command, however you could just as easily use a colshape or button press.
<syntaxhighlight lang="lua">
addCommandHandler("a51gate",function()
guiSetVisible(keypadWindow,true)
showCursor(true,true)
setElementData(keypadWindow,"keypadID","a51MainGateKeypadCode")
end)
</syntaxhighlight>
Note that we set the element data "keypadID".
This is very important because it allows us to keep track of which gate we are trying to open (in this case, the "a51MainGateKeypadCode" gate).

===Opening the gate===
With our gate created and our keypad ready, all thats left now is to open the gate.
Having created custom events earlier for successfully and unsuccessfully verifying the code, this now becomes very easy to do.
All we do is add an event handler for our custom "success" event, and using the keypadID we defined earlier we can move the gate inside it:
<syntaxhighlight lang="lua">
addEventHandler("onKeypadVerificationSuccessful",root,
-- keypadID is sent back from the server
function(keypadID)
-- get the gate object (this is where the id="a51MainGateKeypadCode" tag in the map file becomes useful)
local gate = getElementByID(keypadID)

-- if we found the object
if gate then
-- get the new position (as we defined in the map file)
local x = tonumber(getElementData(gate,"newPosX"))
local y = tonumber(getElementData(gate,"newPosY"))
local z = tonumber(getElementData(gate,"newPosZ"))

-- move the gate
moveObject(gate,1500,x,y,z)

-- get the original position
x = tonumber(getElementData(gate,"posX"))
y = tonumber(getElementData(gate,"posY"))
z = tonumber(getElementData(gate,"posZ"))

-- set a timer to close the gate in 5 seconds
setTimer(moveObject,5000,1,gate,1500,x,y,z)
end
end
)
</syntaxhighlight>
Note how by using the keypadID sent back from the server, we can use if statements and checks against the id to control any number of gates from the same function.

You should now have a working example of a GUI Keypad controlling an A51 Gate.

For further GUI tutorials, see [[Scripting the GUI - Tutorial 3|Tutorial 3 (Scrolling News Feed)]]

Scripting the GUI - Tutorial 3

2010-01-05T21:14:10Z

R3mp: Created page with ''''Scripting the GUI - Tutorial 3 (Scrolling News GUI)''' In this tutorial we will explore how to create a simple scrolling news feed GUI, allowing you to quickly and easily sh…'

'''Scripting the GUI - Tutorial 3 (Scrolling News GUI)'''

In this tutorial we will explore how to create a simple scrolling news feed GUI,
allowing you to quickly and easily show server updates and other server information to your players.
We will store all news items in a clientside xml file and use some simple xml reading to load them into the game.

We will then animate the news item to scroll along the bottom of the screen, updating the news text once it has scrolled beyond the edge of the screen.

'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|GUI Scripting Introduction]].'''

==Setting up the News Feed==
To begin, open up a clientside lua file (if you have been following the [[Introduction to Scripting GUI|GUI Scripting Introduction]], this is gui.lua) to work with.

===Creating the GUI===
As with the previous tutorial, you should be suitably familiar with GUI creation already so we will not go into too much detail here.
<syntaxhighlight lang="lua">
function createNewsFeed()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the gridlist, using some maths to find the bottom-centre of the screen
local Width,Height = 800,45
local X = (sWidth/2) - (Width/2)
local Y = sHeight - (Height/2)

-- the gridlist will act as the background to our news reel
newsGridlist = guiCreateGridList(X,Y,Width,Height,false)

-- create the label in the same place, but as a child of the gridlist
-- also make it half the height of the gridlist, as half of the gridlist is off the bottom of the screen
newsLabel = guiCreateLabel(X,Y,Width,Height/2,"Test text",false,newsGridlist)

-- call our function to read the news out of the xml file
loadNews()

-- load the first news item in the table
updateNewsItem(1)

-- define a global variable called 'currentItem' with the value 1
currentItem = 1
end

addEventHandler("onClientResourceStart",resourceRoot,createNewsFeed)
</syntaxhighlight>
Note that the label is created as a child of the gridlist.
Not only is this good practice in general, but it means that we can freely move parts of the label beyond the edge of the gridlist without them showing, which is critical to the visual effect of this tutorial.

Also notice the use of the 'resourceRoot' variable. This is an MTA variable that holds the root value of the resource you are using it in.

The 'currentItem' variable is what we will use to keep track of which news item we are currently showing

===Writing the News===
Now that we have our GUI created, we need some news to fill it with.
To do this, we will read our news items out of a clientside xml file.

So, navigate to your resource directory and create a new xml file called newsfeed.xml (don't forget to add it to your meta.xml with the appropriate client tag).

Inside this file enter the following information:
<syntaxhighlight lang="lua">
<root>
<news>This is an example news item.</news>
<news>From the 'Scripting the GUI' tutorial.</news>
<news>Showing scrolling news text.</news>
<news>Written on a GUI news feed.</news>
</root>
</syntaxhighlight>
As you can see, each news item is defined as a <news> node with the value being the news text you want to display.
There is no limit on how many news items you can add.

===Collecting the News===
Once we have written all our news items, we will need to collect them all and store them in a table on the client.
We will do this when the resource starts, saving us from having to repeatedly access the xml for new news items.

First, we need to define a table to store the items in:
<syntaxhighlight lang="lua">
local newsItems = {}
</syntaxhighlight>
Add this line to the top of your script.
Make sure it is not inside a function otherwise it will not exist outside of that function (as denoted by the prefix "local").
When defined in the main body of the script it will exist in all functions.

Next, we will need to load the xml file:
<syntaxhighlight lang="lua">
function loadNews()
-- load our "newsfeed.xml" file
local newsfile = xmlLoadFile("newsfeed.xml")

-- if it was successfully loaded
if newsfile then

-- always remember to unload files once you are finished
xmlUnloadFile(newsfile)
end
end
</syntaxhighlight>
'''Always remember to unload files once you are finished using them.'''

Finally, we can add some more code to our loadNews function to read the news items into our newsItems table:
<syntaxhighlight lang="lua">
function loadNews()
local newsfile = xmlLoadFile("newsfeed.xml")

if newsfile then
-- loop through all the children of the root node (the "news" nodes)
for index,itemNode in ipairs(xmlNodeGetChildren(newsfile)) do
-- get the text (the news item) from the node
local item = xmlNodeGetValue(itemNode)

-- insert it into our newsItems table
table.insert(newsItems,item)
end

xmlUnloadFile(newsfile)
end
end
</syntaxhighlight>
We now have a table called 'newsItems' holding all of our news text from the xml file.

==Updating the News==
Now that we have our GUI created and our news items ready, we need to write some code to update the news item being shown to players.
As stated earlier, our news items will be shown on our 'newsLabel' GUI label.

To do this, we will write a simple function to get the next news item from our 'newsItems' table and display it in our label.
<syntaxhighlight lang="lua">
-- define our function with a newIndex parameter, so that we can pass which news item we want to show
function updateNewsItem(newIndex)
-- get the new news item from the table
local item = newsItems[newIndex]

-- update the label text
guiSetText(newsLabel,item)

-- update the 'currentItem' global variable
currentItem = newIndex
end
</syntaxhighlight>

===Sizing the Label===
To make our news scrolling as accurate as possible, we need to be able to make the GUI label the same size as the news item text it is showing.

While this may seem like a tricky thing to do, it is made very easy with the function [[guiLabelGetTextExtent]].
This will tell us the extent, or width, of the text currently shown in our label.
So with a few modifications to our 'updateNewsItems' function, we get:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
local item = newsItems[newIndex]

guiSetText(newsLabel,item)

currentItem = newIndex

-- get the current dimensions of the gui label
local width,height = guiGetSize(newsLabel,false)

-- get the text width of the label
local extent = guiLabelGetTextExtent(newsLabel)

-- update the size of the label with the new width (we do not change the height)
guiSetSize(newsLabel,extent,height,false)
end
</syntaxhighlight>

===Positioning the Label===
Now that our GUI label is the correct width, we need to move it to a position where it is ready to scroll onto the screen.

Again, we can do this with a small modification to our 'updateNewsItems' function:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
local item = newsItems[newIndex]

guiSetText(newsLabel,item)

currentItem = newIndex

local width,height = guiGetSize(newsLabel,false)

local extent = guiLabelGetTextExtent(newsLabel)

guiSetSize(newsLabel,extent,height,false)

-- set the positon to the far right side of the gridlist, ready to scroll on to the left
guiSetPosition(newsLabel,1,0,true)
end
</syntaxhighlight>

==Scrolling the News==
The next step is to animate our news feed.

===Looking at Frames===
To do this, we will introduce a new event: [[onClientRender]].
As stated on the [[onClientRender]] wiki page, this event is called every time GTA renders a new frame (ie: very often).

As usual, to use this event we will need to create an event handler for it:
<syntaxhighlight lang="lua">
addEventHandler("onClientRender",root,scrollNews)
</syntaxhighlight>
This will call our scrollNews function every frame, which we will then use to update the position of our news item.

'''Make sure you add this handler after you have defined your scrollNews function.'''

For our purposes, [[onClientRender]] has one main advantage over, for example, [[setTimer]].
As it is called every frame (and therefore is dependant on the players FPS), the movement of the news item will always appear to be completely smooth,
unlike using a timer which would often appear to lag.

===Moving the News===
In our 'updateNewsItem' function, we position the 'newsLabel' to the far right, so we will scroll in from the right to the left.

For this we will simply move the X position by -1 every frame:
<syntaxhighlight lang="lua">
function scrollNews()
-- if the newsLabel exists
if newsLabel then
-- get the current position of the label
local x,y = guiGetPosition(newsLabel,false)

-- set the new x position of the label as the old position -1
guiSetPosition(newsLabel,x-1,y,false)
end
end
</syntaxhighlight>

===Looping around===
Now that our news scrolls across the screen, we need to be able to check when it has scrolled too far to the left
so we can start scrolling from the far-right side again.

We will also need to update the news item, so we should check the next item exists, and if it doesn't, go back to the first.

For this we will use some simple maths in a modification to our 'scrollNews' function:
<syntaxhighlight lang="lua">
function scrollNews()
local x,y = guiGetPosition(newsLabel,false)

local labelWidth, labelHeight = guiGetSize(newsLabel,false)

-- if the far right position of the label (x + labelWidth) is greater than or equal to 0 (ie: still showing on the gridlist)
if ((x-1) + labelWidth) >= 0 then
-- compensate for a small off-by-one bug in MTA
if x <= 0 then x = x - 1 end

-- update the position as normal
guiSetPosition(newsLabel,x-1,y,false)

-- otherwise, we move on to the next item and reset the position
else
-- get the total number of items in the 'newsItems' table
local totalItems = #newsItems

-- if the next item on our list does not exist in our table
if (currentItem + 1) > totalItems then
-- loop back to the first item in the list
updateNewsItem(1)
else
-- otherwise move onto the next item in the list
updateNewsItem(currentItem + 1)
end
end
end
</syntaxhighlight>
Notice the use of the '#' symbol to get the size of the 'newsItems' table.
This is the Lua length operator, but it only works on tables that have numerical indexes (like an array or a list).
It also works on strings, eg: #"hello" would return 5.

That completes this section of the tutorial.
For ideas on how to further improve and advance this code, continue reading the next section.

==Improving the code==
This section will detail several ways to improve upon the code you now have.

===GUI Customisation===
To give your GUI a more unique feel, you have the ability to customise some aspects of your GUI elements.

For ideas on what is possible, browse the [[Client_Scripting_Functions#GUI_functions|MTA GUI functions]].

For the purposes of this tutorial, we will be using Font, Colour and Alpha.

To start, we will change the alpha of the background gridlist GUI element we are using.
To set the alpha, use [[guiSetAlpha]] and pass a value between 1 and 0; 1 being fully opaque and 0 being fully transparent.
<syntaxhighlight lang="lua">
guiSetAlpha(newsGridlist,0.8)
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your gridlist has been created.

I find an alpha level of 0.8 looks best, however this is personal preference and you can experiment to suit your needs.

Next, we will look at the font of the label text.
To set the font, use [[guiSetFont]] and pass the string name of the font you want to use (available to see on the [[GUI Fonts]] page).
<syntaxhighlight lang="lua">
guiSetFont(newsLabel,"default-bold-small")
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your label has been created.

Finally, we will look at setting the colour of the label text.
To set the colour, use [[guiLabelSetColor]] and pass the individual red,green and blue values.
<syntaxhighlight lang="lua">
guiLabelSetColor(newsLabel,255,70,0)
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your label has been created.

This will give your news items an orange-red colour.

===Multiple News Items===
In its current form, this code is only capable of showing one news item at a time.
However, with a few modifications we can show multiple news items at once, one after another.

To begin with, we need to make sure we have a 'newItems' table defined at the very start of our script,
as well as a 'distance' variable that will control the pixel distance between each news item:
<syntaxhighlight lang="lua">
local newsItems = {}
local distance = 30
</syntaxhighlight>
So put these lines at the top of the file.

Next, we will not know how many items we have (and consequently, how many labels we need) until we have loaded the file.
With that in mind, we will move around some of the code in our 'createNewsFeed' function to support this:
<syntaxhighlight lang="lua">
function createNewsFeed()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the gridlist, using some maths to find the bottom-centre of the screen
local Width,Height = 800,45
local X = (sWidth/2) - (Width/2)
local Y = sHeight - (Height/2)

-- the gridlist will act as the background to our news reel
newsGridlist = guiCreateGridList(X,Y,Width,Height,false)

guiSetAlpha(newsGridlist,0.8)

-- call our function to read the news out of the xml file, before we create the labels
loadNews()

-- define a table to hold our labels
newsLabel = {}

-- now we can loop all our news items, and create a label for each one
for index,item in ipairs(newsItems) do

-- because we now have one label for every item, we can just set the text here and it wont need to be changed again.
newsLabel[index] = guiCreateLabel(0,0,Width,Height/2,item,false,newsGridlist)

guiSetFont(newsLabel[index],"default-bold-small")

guiLabelSetColor(newsLabel[index],255,70,0)

-- modify the width of the label to fit the text
local extent = guiLabelGetTextExtent(newsLabel[index])
guiSetSize(newsLabel[index],extent,Height/2,false)

-- get the size of the gridlist
local x,y = guiGetSize(newsGridlist,false)

-- loop from 1 until index-1 in steps of 1
-- this allows us to loop every label before the label we are currently on
for i=1, index-1, 1 do
-- tally up the sizes of all labels before our current one and store them in x
local width = guiGetSize(newsLabel[i],false)
x = x + width
end

-- put a 'distance' pixel gap between each news item
x = x + (distance*(index-1))

-- set the positon to the far right side of the gridlist, ready to scroll on to the left
guiSetPosition(newsLabel[index],x,0,false)
end
end
</syntaxhighlight>

Now we need to update our 'updateNewsItem' function to account for having multiple labels:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
-- find the index of the news item directly infront (in the looping order) of the newIndex item
local index = newIndex - 1
if index == 0 then index = #newsItems end

-- find the position of the right-edge of the label directly infront of the newIndex label
local x = guiGetPosition(newsLabel[index],false)
local width = guiGetSize(newsLabel[index],false)
x = x + width

-- add a 'distance' pixel gap in
x = x + distance

-- check the new position isnt actually on the gridlist (ie: so it wont suddenly appear in the centre of the list)
local gridlistWidth = guiGetSize(newsGridlist,false)

if x < gridlistWidth then
-- if it is, simple move it back to the edge
x = gridlistWidth
end

-- set the new position
guiSetPosition(newsLabel[newIndex],x,0,false)
end
</syntaxhighlight>

Finally, we need to make some small adjustments to our 'scrollNews' function:
<syntaxhighlight lang="lua">
function scrollNews()
if newsItems then
-- loop every news item
for index,item in ipairs(newsItems) do
local x,y = guiGetPosition(newsLabel[index],false)

local labelWidth, labelHeight = guiGetSize(newsLabel[index],false)

-- if the far right position of the label (x + labelWidth) is greater than or equal to 0 (ie: still showing on the gridlist)
if ((x-1) + labelWidth) >= 0 then
-- compensate for a small off-by-one bug in MTA
if x <= 0 then x = x - 1 end

-- update the position as normal
guiSetPosition(newsLabel[index],x-1,y,false)

-- otherwise, we move on to the next item and reset the position
else
updateNewsItem(index)
end
end
end
end
</syntaxhighlight>

You should now have multiple news items scrolling along your news feed simultaneously.

===Globally controlled scroll speed===
As with the 'distance' variable above, we can set a global variable for controlling the scroll speed of the news items as well.
Note that the speed will still be dependant on the players FPS (ie: lower FPS means slightly slower scrolling).

To do this, we simply need to create the variable at the start of our code:
<syntaxhighlight lang="lua">
local scrollSpeed = 1
</syntaxhighlight>
Put this line at the top of your file.

Then, we just replace the instance of "x-1" in our 'scrollNews' function with "x-scrollSpeed":
<syntaxhighlight lang="lua">
function scrollNews()
...
-- update the position as normal
guiSetPosition(newsLabel[index],x-scrollSpeed,y,false)
...
end
end
</syntaxhighlight>
That concludes this section of the tutorial.

SetPlayerMuted

2010-01-03T22:08:08Z

R3mp:

__NOTOC__
{{Server function}}
Use this function to mute or unmute the player.

==Syntax==
<syntaxhighlight lang="lua">bool setPlayerMuted ( player thePlayer, bool state )</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The [[player]] you are muting or unmuting.
*'''state:''' Use '''true''' to mute and '''false''' to unmute the player.

===Returns===
Returns ''true'' if the player was successfully muted or unmuted, ''false'' otherwise.

==Example==
This adds a /mute command that can be used to mute a player.
<syntaxhighlight lang="lua">
-- create the function
function mutePlayer(player,command,victimName)
-- if the player has specified a victim name to mute
if victimName then
-- get the victim player element from their name
local victim = getPlayerFromNick(victimName)
-- if the player exists
if victim then
-- if they arent already muted
if ( not isPlayerMuted(victim) ) then
-- mute them and output a message to the chat
setPlayerMuted(victim, true)
outputChatBox("You have been muted.",victim)
end
else
outputChatBox("Could not find player with name: "..tostring(victimName),player)
end
else
outputChatBox("Usage: /mute <player name>",player)
end
end
-- add the /mute command
addCommandHandler("mute",mutePlayer)
</syntaxhighlight>

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

Scripting the GUI - Tutorial 2

2010-01-03T20:25:36Z

R3mp:

'''Scripting the GUI - Tutorial 2 (Gates + Keypads)'''

In this tutorial we will look at creating GUI keypads with combination codes for map-defined object gates.
We will be using serverside keycodes, with some client - server interaction to verify the codes and report the outcome.

'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|GUI Scripting Introduction]].'''

[[Image:Gui_keypad_tutorial.png|thumb|GUI Keypad]]

==Setting up the Keypad==
To begin, open up a clientside lua file (if you have been following the [[Introduction to Scripting GUI|GUI Scripting Introduction]], this is gui.lua) to work with.

===Creating the GUI===
By now, GUI creation should seem relatively straight forward, so we will not go over this in too much detail.
As in [[Scripting the GUI - Tutorial 1|Tutorial 1]] we will be using '''absolute''' values in this tutorial.

<syntaxhighlight lang="lua">
function createKeypad()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 142,276
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)
keypadWindow = guiCreateWindow(X,Y,Width,Height,"Keypad",false)

-- don't allow people to resize the keypad
guiWindowSetSizable(keypadWindow,false)

-- create buttons labeled 0-9, "*", "#", "Enter" and "C" (clear)
keypadButton1 = guiCreateButton(13,68,37,36,"1",false,keypadWindow)
keypadButton2 = guiCreateButton(53,68,37,36,"2",false,keypadWindow)
keypadButton3 = guiCreateButton(93,68,37,36,"3",false,keypadWindow)
keypadButton4 = guiCreateButton(13,108,37,36,"4",false,keypadWindow)
keypadButton5 = guiCreateButton(53,108,37,36,"5",false,keypadWindow)
keypadButton6 = guiCreateButton(93,108,37,36,"6",false,keypadWindow)
keypadButton7 = guiCreateButton(13,148,37,36,"7",false,keypadWindow)
keypadButton8 = guiCreateButton(53,148,37,36,"8",false,keypadWindow)
keypadButton9 = guiCreateButton(93,148,37,36,"9",false,keypadWindow)
keypadButtonAsterix = guiCreateButton(13,188,37,36,"*",false,keypadWindow)
keypadButton0 = guiCreateButton(53,188,37,36,"0",false,keypadWindow)
keypadButtonHash = guiCreateButton(93,188,37,36,"#",false,keypadWindow)
keypadButtonExit = guiCreateButton(13,228,37,36,"Exit",false,keypadWindow)
keypadButtonEnter = guiCreateButton(53,228,37,36,"Enter",false,keypadWindow)
keypadButtonClear = guiCreateButton(93,228,37,36,"Clear",false,keypadWindow)

-- create a gridlist to act as a backdrop on the kaypad display
keypadGridlistDisplay = guiCreateGridList(13,25,117,33,false,keypadWindow)
guiGridListSetSelectionMode(keypadGridlistDisplay,2)
guiSetAlpha(keypadGridlistDisplay,0.6)
-- create a label so we can write text on the keypad display
keypadLabelDisplay = guiCreateLabel(14,26,115,30,"Enter Keycode.",false,keypadWindow)
guiLabelSetColor(keypadLabelDisplay,255,000,000)
guiLabelSetVerticalAlign(keypadLabelDisplay,"center")
guiLabelSetHorizontalAlign(keypadLabelDisplay,"center",false)

guiSetVisible(keypadWindow,false)
end

-- create the GUI when the resource starts
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()),createKeypad)
</syntaxhighlight>
As you can see, the keypad consists of 10 numerical keys (0-9), two character keys (* and #), a clear key, an exit key and an enter key.
This means the codes used on the keypad can contain any of these characters (0123456789*#).

===Managing the display===
We will begin by writing a small function to control the display on the keypad.
This is done by encapsulating several methods of changing the text into a single function,
which will enable us to easily add/remove text from the display later on.
<syntaxhighlight lang="lua">
function updateDisplay(text)
-- if we are passing some text
if text then
-- if its a digit or * or #, then append it to the end of the display
if tonumber(text) or text == "*" or text == "#" then
guiSetText(keypadLabelDisplay,guiGetText(keypadLabelDisplay) .. text)
-- otherwise replace the display with the new text
else
guiSetText(keypadLabelDisplay,text)
end
-- if we pass nil, clear the display entirely
else
guiSetText(keypadLabelDisplay,"")
end
end
</syntaxhighlight>
We can now simply call updateDisplay(our text) to change the text on the display, or updateDisplay(nil) to clear it.

===Detecting the clicks===
With so many buttons that do very similar tasks on our keypad, there are two methods available to us for detecting when a player clicks on them.

We could add [[onClientGUIClick]] events for every button individually, as we have done in previous tutorials; Or, alternatively,
we could add a single [[onClientGUIClick]] handle for the window (which is the parent of all our other keypad GUI elements), filter our results to include only the buttons we want and trigger our own custom event.

For the purposes of this tutorial and in the interest of outlining multiple approaches, we will explore the second method, though either one is an acceptable solution.
<syntaxhighlight lang="lua">
addEventHandler("onClientGUIClick",keypadWindow,processKeypadClicks,true)
</syntaxhighlight>
'''Notice the final argument is set to 'true'. This means that clicks on any other elements in the same branch of the tree will also trigger this event handle (eg. clicks on our buttons).'''

Add this line of code into your createKeypad function, after your GUI has been created.

Now that we are detecting all clicks on our GUI, we need to filter out the ones we do not want (ie: clicks on the window or display) and trigger our custom event:
<syntaxhighlight lang="lua">
function processKeypadClicks(button,state)
if button == "left" and state == "up" then
-- if the source of this event is a gui button
if getElementType(source) == "gui-button" then
-- trigger our custom event and send the keypad id of this keypad as an argument
triggerEvent("onKeypadButtonClicked",source,getElementData(keypadWindow,"keypadID"))
end
end
end
</syntaxhighlight>
As you can see, we are now triggering our custom event "onKeypadButtonClicked" whenever a button is clicked on the keypad.
Also note we use element data "keypadID" to differentiate between keypads. This data will need to be set whenever the player is shown a new keypad.
We will cover this in more detail later.

===Handling the clicks===
Much like when using [[triggerServerEvent]] in previous tutorials, we now need to define the event, only this time it is purely clientside:
<syntaxhighlight lang="lua">
addEvent("onKeypadButtonClicked",false)
addEventHandler("onKeypadButtonClicked",root,
function(keypadID)

end
)
</syntaxhighlight>
Note the second argument in [[addEvent]] is set to false, indicating that this event cannot be triggered from the server.
Also note, the function we are using in the [[addEventHandler]] does not have a name. If you contract it down and remove the spacing, you get:
<syntaxhighlight lang="lua">
addEventHandler("onKeypadButtonClicked",root,function() ... end)
</syntaxhighlight>
This simply means instead of storing the pointer to the function in a variable, we are passing it directly as an argument.
Doing it this way cleans up the code and will often make it easier to follow.

Now that the event has been created, we can fill in the code logic that will control our button presses.
<syntaxhighlight lang="lua">
addEvent("onKeypadButtonClicked",false)
addEventHandler("onKeypadButtonClicked",root,
function(keypadID)
-- clear the display if this is the first time its being used
if guiGetText(keypadLabelDisplay) == "Enter Keycode." or guiGetText(keypadLabelDisplay) == "Invalid Keycode." then
updateDisplay()
end

-- if its the clear button
if guiGetText(source) == "Clear" then
-- clear the display
updateDisplay()

-- if its the enter button
elseif guiGetText(source) == "Enter" then
-- get the currently entered code from the display
local code = guiGetText(keypadLabelDisplay)

-- if they have entered a code
if code then
-- trigger the server so we can verify their code
triggerServerEvent("verifyKeypadCode",getLocalPlayer(),code,keypadID)
end

-- if its the exit button
elseif guiGetText(source) == "Exit" then
-- hide the keypad and reset the display text ready for next time
guiSetVisible(keypadWindow,false)
updateDisplay("Enter Keycode.")
showCursor(false,false)

-- otherwise, it must be a character button
else
updateDisplay(guiGetText(source))
end
end
)
</syntaxhighlight>

==Serverside Verification==
For this part of the tutorial, you will need to open up a serverside lua file from your resource to work with.

===Defining the keycode===
Now that we have completed the keypad clicking logic, we need to move on to verifying the code entered into the keypad.
To do this, we need to have the correct code stored somewhere on the server, which we can check the players code against.

For the purposes of this tutorial we will simply store the code in a serverside table, however it can be done any number of ways (such as serverside xml files or MySQL databases).
<syntaxhighlight lang="lua">
local keypadCodes = {
["a51MainGateKeypadCode"] = "4455*#"
}
</syntaxhighlight>
This table stores an entry called "a51MainGateKeypadCode" with the code 4455*#

'''This is the keycode that you will use to open the gate later on in this tutorial.'''

===Verifying the code===
Now that we have a keycode to verify against, we can write our serverside event:
<syntaxhighlight lang="lua">
addEvent("verifyKeypadCode",true)
addEventHandler("verifyKeypadCode",root,function(code,keypadID)
if code then
-- using the table we created earlier, check if the code supplied is the same as the code for this gate
if code == keypadCodes[keypadID] then
-- if it is, tell the client that it was successful
triggerClientEvent(client,"onKeypadVerificationSuccessful",client,keypadID)
else
-- if it is not, tell the client that it was not successful
triggerClientEvent(client,"onKeypadVerificationFailed",client,keypadID)
end
end
end)
</syntaxhighlight>
Here we use our table and the keypadID supplied by the player to check if the codes match.

If you are not using a table to store the codes, then you will need to replace 'keypadCodes[keypadID]' with your own storage method.
Once it is verified (or not), we can trigger the client so the appropriate information can be shown on the keypad display.

==Receiving the result==
We have now finished the serverside section of the tutorial, so you will need to open up the clientside lua file from your resource
that you were previously working on.

Once our code has been verified, the server will send back the response to the client.
In just the same way as client -> server interaction, we now need to add the event that the server is going to trigger on the client.

===Catching and processing the result===
First we will add the event for when the verification is successful:
<syntaxhighlight lang="lua">
addEvent("onKeypadVerificationSuccessful",true)
addEventHandler("onKeypadVerificationSuccessful",root,
function()
-- hide the keypad and reset the display text ready for next time
guiSetVisible(keypadWindow,false)
updateDisplay("Enter Keycode.")
showCursor(false,false)
end
)
</syntaxhighlight>

Finally we can add the event for when the verification is unsuccessful:
<syntaxhighlight lang="lua">
addEvent("onKeypadVerificationFailed",true)
addEventHandler("onKeypadVerificationFailed",root,
function()
-- update the display text to show the code was invalid
updateDisplay("Invalid Keycode.")
end
)
</syntaxhighlight>

This completes the keypad section of the tutorial.

For an example of how to implement this into a working gate system, carry on reading the next section.

==Applying the Keypad==
For the keypad to have any use, we need something to use it on.
For this tutorial we will be using gates, and as mentioned earlier we will create a main gate into A51.

===Creating the gate===
First of all, we need to create the gate object.
For the purposes of this example, we will be using a map file to store the object.
While this is the recommended method for defining objects, it is not the only way to approach it.

Navigate to your resource folder and make a new file called gate.map, then add your new map file to your meta.xml using:
<syntaxhighlight lang="lua">
<map src="gate.map"/>
</syntaxhighlight>

''If you are unsure of map file syntax, please see the [http://wiki.multitheftauto.com/wiki/Writing_Gamemodes| Writing Gamemodes Tutorial] or check the [[Object]] page for help.''
<syntaxhighlight lang="lua">
<map>
<object id="a51MainGateKeypadCode" model="971" posX="96.736" posY="1918.352" posZ="20.694" rotX="0" rotY="0" rotZ="270.40" newPosX="96.751" newPosY="1914.474" newPosZ="20.694" />
</map>
</syntaxhighlight>
This will create a gate object across the A51 entrance. The object will have position and rotation data, as well as its newPosX,newPosY and newPosZ information that we need to be able to move it.

'''Note that the object id is the same as the table entry we created earlier to hold the access code.'''
This is one possible method that could be accessed to link this gate with that particular keycode.

===Opening the keypad===
Back in the clientside lua file again, we can now work on linking the gate and the keypad.

Now that we have our gate, we need a way of accessing the keypad to open it.
For the purposes of this tutorial we will use a simple command, however you could just as easily use a colshape or button press.
<syntaxhighlight lang="lua">
addCommandHandler("a51gate",function()
guiSetVisible(keypadWindow,true)
showCursor(true,true)
setElementData(keypadWindow,"keypadID","a51MainGateKeypadCode")
end)
</syntaxhighlight>
Note that we set the element data "keypadID".
This is very important because it allows us to keep track of which gate we are trying to open (in this case, the "a51MainGateKeypadCode" gate).

===Opening the gate===
With our gate created and our keypad ready, all thats left now is to open the gate.
Having created custom events earlier for successfully and unsuccessfully verifying the code, this now becomes very easy to do.
All we do is add an event handler for our custom "success" event, and using the keypadID we defined earlier we can move the gate inside it:
<syntaxhighlight lang="lua">
addEventHandler("onKeypadVerificationSuccessful",root,
-- keypadID is sent back from the server
function(keypadID)
-- get the gate object (this is where the id="a51MainGateKeypadCode" tag in the map file becomes useful)
local gate = getElementByID(keypadID)

-- if we found the object
if gate then
-- get the new position (as we defined in the map file)
local x = tonumber(getElementData(gate,"newPosX"))
local y = tonumber(getElementData(gate,"newPosY"))
local z = tonumber(getElementData(gate,"newPosZ"))

-- move the gate
moveObject(gate,1500,x,y,z)

-- get the original position
x = tonumber(getElementData(gate,"posX"))
y = tonumber(getElementData(gate,"posY"))
z = tonumber(getElementData(gate,"posZ"))

-- set a timer to close the gate in 5 seconds
setTimer(moveObject,5000,1,gate,1500,x,y,z)
end
end
)
</syntaxhighlight>
Note how by using the keypadID sent back from the server, we can use if statements and checks against the id to control any number of gates from the same function.

You should now have a working example of a GUI Keypad controlling an A51 Gate.

File:Gui keypad tutorial.png

2010-01-03T20:24:48Z

R3mp:

Scripting the GUI - Tutorial 1

2010-01-03T20:22:42Z

R3mp:

'''Scripting the Gui - Tutorial 1 (Gridlists)'''

In this tutorial we will explore the use of gridlists in creating a vehicle selection screen, with optional clientside vehicle xml data reading.
'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|Previous tutorial]].'''

==Setting up the Vehicle Selection==

===Creating the GUI===
To begin, open up a clientside lua file (if you have been following the [[Scripting Introduction]], this is gui.lua) to work with.

In this file, we will start writing our function for creating the GUI.
As covered in the [[Introduction to Scripting GUI|Previous tutorial]], there are 2 value type options available when creating gui: '''relative''' and '''absolute'''.

For the purposes of this tutorial, we will be using '''absolute''' values.

This will create a simple GUI with a window, gridlist and button:
<syntaxhighlight lang="lua">
function createVehicleSelection()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- use some simple maths to position the window in the centre of the screen
local Width,Height = 376,259
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)
windowVehicleSelection = guiCreateWindow(X,Y,Width,Height,"Vehicle Selection Window",false)

gridlistVehicleSelection = guiCreateGridList(10,26,357,192,false,windowVehicleSelection)
-- add a "Vehicle" and a "Type" collumn to the gridlist
guiGridListAddColumn(gridlistVehicleSelection,"Vehicle",0.2)
guiGridListAddColumn(gridlistVehicleSelection,"Type",0.2)

-- set the default width of the columns to roughly half the size of the gridlist (each)
guiGridListSetColumnWidth(gridlistVehicleSelection,1,0.4,true)
guiGridListSetColumnWidth(gridlistVehicleSelection,2,0.5,true)

buttonCreate = guiCreateButton(121,227,120,20,"Create",false,windowVehicleSelection)

-- add the event handler for when the button is clicked
addEventHandler("onClientGUIClick",buttonCreate,createVehicleHandler,false)

-- hide the GUI
guiSetVisible(windowVehicleSelection,false)

-- this will add all the vehicle options onto the gridlist, it is explained later in this tutorial
populateGridlist()
end
</syntaxhighlight>

We now also need to call this function somewhere, otherwise the GUI will never be created.
As in previous tutorials, to do this we can use [[onClientResourceStart]].
<syntaxhighlight lang="lua">
-- when the resource is started, create the GUI and hide it
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()),
function()
createVehicleSelection()
end
)
</syntaxhighlight>

===Showing the GUI===
Unlike in previous tutorials, we want players to be able to open this window whenever they chose, not when the resource starts.
So, we can add a [[addCommandHandler|Command]] to do this.
<syntaxhighlight lang="lua">
-- create the function that will show the window
function showVehicleSelection()
-- if the window isnt visible, show it
if not guiGetVisible(windowVehicleSelection) then
guiSetVisible(windowVehicleSelection,true)

showCursor(true,true)
end
end

-- add the command /vehicleselection and set it to call the showVehicleSelection function
addCommandHandler("vehicleselection",showVehicleSelection)
</syntaxhighlight>

===Populating the Gridlist from a table===
Now that we have our basic GUI created, we need to fill the gridlist with all of our vehicles.

To begin with, we will do this using a simple clientside table.
Later in the tutorial, we will explore expanding this method to use .xml files for storing information.
To begin, we must create a small table containing a selection of vehicles that we can spawn.

The table contains vehicles in the format ["description"] = vehicle_id :
<syntaxhighlight lang="lua">
-- create the table and fill it with a selection of vehicle ids and names
local vehicleSelectionTable = {
["Sparrow"] = 469,
["Stuntplane"] = 513,
["BF-400"] = 581,
["Freeway"] = 463,
["Speeder"] = 452,
["Jester"] = 559,
["Sabre"] = 475,
["Police Ranger"] = 599,
["Utility Van"] = 552,
["Tug"] = 583
}
</syntaxhighlight>
Place this code at the very top of your file (it does not need to be inside a function).

Next, we can write our "populateGridlist" function which will fill the Gridlist with all the vehicles in the table.
To do this we simply need to loop through all the values in the table, adding each one to the gridlist as we go.
We will also set hidden data using [[guiGridListSetItemData]] to store the vehicle id:
<syntaxhighlight lang="lua">
function populateGridlist()
-- loop through the table
for name,vehicle in pairs(vehicleSelectionTable) do
-- add a new row to the gridlist
local row = guiGridListAddRow(gridlistVehicleSelection)

-- set the text in the first column to the vehicle name
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)
-- set the text in the second column to the vehicle type
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(vehicle),false,false)

-- set the data for gridlist slot as the vehicle id
guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(vehicle))
end
end
</syntaxhighlight>

===Managing the click===
Now that we have our GUI completed, we need to be able to catch any clicks made on the "create" button.
We have attached the [[onClientGUIClick]] event to buttonCreate already, so now we need to write the function that it calls.
In this function we do some basic error checking, such as making sure a vehicle has been selected in the list.
We can then use some maths to find a position infront of the player and send the server this information to spawn the vehicle (using [[triggerServerEvent]])
<syntaxhighlight lang="lua">
function createVehicleHandler(button,state)
if button == "left" and state == "up" then
-- get the selected item in the gridlist
local row,col = guiGridListGetSelectedItem(gridlistVehicleSelection)

-- if something is selected
if row and col and row ~= -1 and col ~= -1 then
-- get the vehicle id data from the gridlist that is selected
local selected = guiGridListGetItemData(gridlistVehicleSelection,row,col)

-- make sure the vehicle id is a number not a string
selected = tonumber(selected)

-- get the players position and rotation
local rotz = getPedRotation(getLocalPlayer())
local x,y,z = getElementPosition(getLocalPlayer())
-- find the position directly infront of the player
x = x + ( math.cos ( math.rad ( rotz+90 ) ) * 3)
y = y + ( math.sin ( math.rad ( rotz+90 ) ) * 3)

if selected and x and y and z then
-- trigger the server
triggerServerEvent("createVehicleFromGUI",getRootElement(),selected,x,y,z)

-- hide the gui and the cursor
guiSetVisible(windowVehicleSelection,false)
showCursor(false,false)
else
outputChatBox("Invalid arguments.")
end
else
-- otherwise, output a message to the player
outputChatBox("Please select a vehicle.")
end
end
end
</syntaxhighlight>

===Creating the Vehicle===
At this point we now have all the code needed on the client side, so open up a serverside .lua file to work with.

On the server side, we will first of all need to define the custom event that we triggered before from the client. This can be done using [[addEvent]] and [[addEventHandler]].
Finally we will need a small function for creating the vehicle:
<syntaxhighlight lang="lua">
function createMyVehicle(vehicleid,x,y,z)
-- check all the arguments exist
if vehicleid and x and y and z then
createVehicle(vehicleid,x,y,z)
end
end

addEvent("createVehicleFromGUI",true)
addEventHandler("createVehicleFromGUI",root,createMyVehicle)
</syntaxhighlight>
Note the use of the "root" variable. This is an MTA variable containing the root element; every resource has one.

This completes the first section of the tutorial. You should now have a basic, working vehicle spawn script.

In the second section, we will cover collapsible gridlist data and clientside xml file reading.

==Expanding the code==
This section will detail several ways to improve upon the code you now have.

===Importing Data===
One big improvement over the previously mentioned method is to use external files to store the vehicle information, allowing us to much more quickly and easily manage large amounts of data.
For this tutorial, we will use a clientside xml file to hold the information.

First of all you will need to create your xml file, so navigate to your resources directory and create a new file named vehicles.xml:

''For the purpose of this example, we will include only a small fraction of the total vehicles, however the file can easily be expanded to include them all.''

If you are unsure of xml data structures, you can browse the [http://wiki.multitheftauto.com/wiki/Server_Scripting_Functions#XML_functions| MTA xml functions] for help.
<syntaxhighlight lang="lua">
<root>
<group type="Bikes">
<vehicle id="581" name="BF-400"/>
<vehicle id="463" name="Freeway"/>
<vehicle id="481" name="BMX"/>
</group>
<group type="Boats">
<vehicle id="472" name="Coastguard"/>
<vehicle id="452" name="Speeder"/>
</group>
<group type="Helicopters">
<vehicle id="487" name="Maverick"/>
<vehicle id="469" name="Sparrow"/>
</group>
<group type="Planes">
<vehicle id="593" name="Dodo"/>
<vehicle id="513" name="Stuntplane"/>
</group>
<group type="Sports Cars">
<vehicle id="565" name="Flash"/>
<vehicle id="559" name="Jester"/>
<vehicle id="477" name="ZR-350"/>
</group>
<group type="2-Door">
<vehicle id="474" name="Hermes"/>
<vehicle id="475" name="Sabre"/>
</group>
<group type="Emergency">
<vehicle id="416" name="Ambulance"/>
<vehicle id="599" name="Police ranger"/>
</group>
<group type="Industrial">
<vehicle id="573" name="Dune"/>
<vehicle id="552" name="Utility van"/>
</group>
<group type="Misc">
<vehicle id="457" name="Caddy"/>
<vehicle id="583" name="Tug"/>
</group>
</root>
</syntaxhighlight>
Once you have created your file, do not forget to add it to the meta.xml of your resource with the appropriate client tag.

Note the group "type" tag. This is an arbitrary description of the vehicles contained within the group and can be renamed or added as any text.
Similarly, the vehicle "name" tag is also just a textual description of the vehicle and does not need to be the exact vehicle name.

Now that we have the data, we can import it into the game and display it in the GUI.
'''If you are following on from the first section of this tutorial, this new code will replace what is inside your existing 'populateGridlist' function.'''
First, we need to load the file:
<syntaxhighlight lang="lua">
function populateGridlist()
-- load the file and save the root node value it returns
local rootnode = xmlLoadFile("vehicles.xml")

-- check that the file exists and has been correctly loaded
if rootnode then
-- unload the xml file
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>
Always make sure you unload any files once you are finished using them.

We can now start collecting the data from the file and entering it into our gridlist.
We can do this by looping through the xml data (in a similar manner to looping through the vehicle table earlier in this tutorial) and adding each entry into the list.
<syntaxhighlight lang="lua">
function populateGridlist()
local rootnode = xmlLoadFile("vehicles.xml")

if rootnode then
-- first, we find every "group" node (they are direct children of the root)
for _,group in ipairs(xmlNodeGetChildren(rootnode)) do
-- add a new row to the gridlist
local row = guiGridListAddRow(gridlistVehicleSelection)

-- get the group name
local name = xmlNodeGetAttribute(group,"type")

-- set the text in the first column to the group type and indicate it is a section ('true')
-- (sections on gridlists show up in bold and cannot be clicked)
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,true,false)

-- then, for every group that we find, loop all of its children (the vehicle nodes)
-- and add them into the gridlist
for _,vehicle in ipairs(xmlNodeGetChildren(group)) do
-- add a new row to the gridlist
row = guiGridListAddRow(gridlistVehicleSelection)

-- get the vehicle name and id
name = xmlNodeGetAttribute(vehicle,"name")
local id = xmlNodeGetAttribute(vehicle,"id")

-- set the text in the first column to the vehicle name
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)
-- set the text in the second column to the vehicle type
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(tonumber(id)),false,false)

-- finally, set the vehicle id as data so we can access it later
guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(id))
end
end

-- unload the xml file now that we are finished
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>
Note the use of for loops in the code with [[xmlNodeGetChildren]]. This saves us a lot of time and effort as we do not have to manually code each group and vehicle into the list.

You should now have a fully working vehicle selection menu, reading all of its data from a clientside xml file.
Next, we will examine how to generate the appearance of collapsing and expanding sections in a gridlist.

===Collapsing/Expanding the Gridlist===
Allowing sections of the gridlist to be collapsed or expanded gives much more control over the visible content to the user.
This frees up space on the screen and makes the whole menu much more comfortable to use.

===Loading the data===
To be able to achieve this effect (as it is not a natural feature of gridlists) we will need to load the vehicle information into a table (from the xml file), rather than directly including it all in the gridlist.
'''If you are following on from a previous section of this tutorial, this new code will replace what is inside your existing 'populateGridlist' function.'''

This works in much the same way the previous xml loading example does, only this time instead of saving the data into the gridlist, we save it into a table entry instead.
We also set the custom data "header" on the gridlist slots to denote which gridlist entries are our "group" entries and which are vehicles.
<syntaxhighlight lang="lua">
function populateGridlist()
local rootnode = xmlLoadFile("vehicles.xml")

-- create a blank global table to store our imported data
vehicleTable = {}

if rootnode then
for _,group in ipairs(xmlNodeGetChildren(rootnode)) do
-- create an entry in the gridlist for every vehicle "group"
local row = guiGridListAddRow(gridlistVehicleSelection)

local name = xmlNodeGetAttribute(group,"type")

guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)

-- add an entry containing the group name into the table
vehicleTable[name] = {}

-- we will use the custom data "header" to indicate that this entry can be expanded/collapsed
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")

-- then, for every group that we find, loop all of its children (the vehicle nodes) and store them in a table
for _,vehicle in ipairs(xmlNodeGetChildren(group)) do
local vname = xmlNodeGetAttribute(vehicle,"name")
local id = xmlNodeGetAttribute(vehicle,"id")

-- insert both the vehicle id and the vehicle description into the table
table.insert(vehicleTable[name],{id,vname})
end
end

-- set element data on the gridlist so we know which group is currently showing
setElementData(gridlistVehicleSelection,"expanded","none")

-- unload the xml file now that we are finished
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>

Now that we have all the data stored, we can quickly manipulate it when neccessary.

===Managing the double click===
To enable the player to simply double click on a group name to expand/collapse it we need to use the [[onClientGUIDoubleClick]] event.
If we attach it to the gridlist, we can then catch any double clicks on the group names in it:
<syntaxhighlight lang="lua">
-- attach the onClientGUIDoubleClick event to the gridlist and set it to call processDoubleClick
addEventHandler("onClientGUIDoubleClick",gridlistVehicleSelection,processDoubleClick,false)
</syntaxhighlight>
Add this line of code in your createVehicleSelection, after the gridlist has been created.

As the gridlist items are not separate GUI elements, we must capture all clicks from anywhere on the gridlist then process them to filter out the ones we do not want.
This can be done by checking if an item is selected, then checking if the item is one of our "group" values (using our previously mentioned "header" data):
<syntaxhighlight lang="lua">
function processDoubleClick(button,state)
if button == "left" and state == "up" then
local row,col = guiGridListGetSelectedItem(gridlistVehicleSelection)

-- if something in the gridlist has been selected
if row and col and row ~= -1 and col ~= -1 then
-- if it is a header
if guiGridListGetItemData(gridlistVehicleSelection,row,col) == "header" then
local selected = guiGridListGetItemText(gridlistVehicleSelection,row,col)

-- call the function to collapse or expand the menu and pass which section it is as an argument
changeGridlistState(selected)
end
end
end
end
</syntaxhighlight>

Once we have narrowed down the double clicks to only those done on our group headers, we can expand/collapse them appropriately.
This can be done by simply setting new text values in the gridlist according to the newly expanded/collapsed group, which creates the convincing illusion of collapsable menus.

Note that much of the following code is reused from previous areas of this tutorial. While it is generally bad practice to clone sections of code in this way, for the purposes of this example it is far easier to understand.
<syntaxhighlight lang="lua">
function changeGridlistState(group)
if group then
-- if the group is already expanded, we want to collapse it
if getElementData(gridlistVehicleSelection,"expanded") == group then
-- first, we clear all previous data from the gridlist
guiGridListClear(gridlistVehicleSelection)

-- now, loop all the group entries in the vehicle table that we created earlier
for group,_ in pairs(vehicleTable) do
-- add each group to the list and mark them with "header"
local row = guiGridListAddRow(gridlistVehicleSelection)

guiGridListSetItemText(gridlistVehicleSelection,row,1,group,false,false)
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")
end

-- update the data to indicate that no groups are currently expanded
setElementData(gridlistVehicleSelection,"expanded","none")

-- otherwise, we want to expand it
else
guiGridListClear(gridlistVehicleSelection)

local row = guiGridListAddRow(gridlistVehicleSelection)

guiGridListSetItemText(gridlistVehicleSelection,row,1,group,false,false)
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")

-- loop every vehicle in the specified groups table
for _,vehicle in ipairs(vehicleTable[group]) do
-- add them to the gridlist and set the vehicle id as data
row = guiGridListAddRow(gridlistVehicleSelection)

-- format a "-" into the string to make it visually easier to distinguish between groups and vehicles
guiGridListSetItemText(gridlistVehicleSelection,row,1,"- "..vehicle[2],false,false)
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(tonumber(vehicle[1])),false,false)

guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(vehicle[1]))
end

-- update the data to indicate which group is currently expanded
setElementData(gridlistVehicleSelection,"expanded",group)
end
end
end
</syntaxhighlight>

This comletes the second section of the tutorial.

For further GUI tutorials, see [[Scripting the GUI - Tutorial 2|Tutorial 2 (Gates and Keypads)]]

Scripting the GUI - Tutorial 2

2010-01-03T20:21:20Z

R3mp: Created page with ''''Scripting the GUI - Tutorial 2 (Gates + Keypads)''' In this tutorial we will look at creating GUI keypads with combination codes for map-defined object gates. We will be usin…'

'''Scripting the GUI - Tutorial 2 (Gates + Keypads)'''

In this tutorial we will look at creating GUI keypads with combination codes for map-defined object gates.
We will be using serverside keycodes, with some client - server interaction to verify the codes and report the outcome.

'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|GUI Scripting Introduction]].'''

==Setting up the Keypad==
To begin, open up a clientside lua file (if you have been following the [[Introduction to Scripting GUI|GUI Scripting Introduction]], this is gui.lua) to work with.

===Creating the GUI===
By now, GUI creation should seem relatively straight forward, so we will not go over this in too much detail.
As in [[Scripting the GUI - Tutorial 1|Tutorial 1]] we will be using '''absolute''' values in this tutorial.

<syntaxhighlight lang="lua">
function createKeypad()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- create the window, using some maths to find the centre of the screen
local Width,Height = 142,276
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)
keypadWindow = guiCreateWindow(X,Y,Width,Height,"Keypad",false)

-- don't allow people to resize the keypad
guiWindowSetSizable(keypadWindow,false)

-- create buttons labeled 0-9, "*", "#", "Enter" and "C" (clear)
keypadButton1 = guiCreateButton(13,68,37,36,"1",false,keypadWindow)
keypadButton2 = guiCreateButton(53,68,37,36,"2",false,keypadWindow)
keypadButton3 = guiCreateButton(93,68,37,36,"3",false,keypadWindow)
keypadButton4 = guiCreateButton(13,108,37,36,"4",false,keypadWindow)
keypadButton5 = guiCreateButton(53,108,37,36,"5",false,keypadWindow)
keypadButton6 = guiCreateButton(93,108,37,36,"6",false,keypadWindow)
keypadButton7 = guiCreateButton(13,148,37,36,"7",false,keypadWindow)
keypadButton8 = guiCreateButton(53,148,37,36,"8",false,keypadWindow)
keypadButton9 = guiCreateButton(93,148,37,36,"9",false,keypadWindow)
keypadButtonAsterix = guiCreateButton(13,188,37,36,"*",false,keypadWindow)
keypadButton0 = guiCreateButton(53,188,37,36,"0",false,keypadWindow)
keypadButtonHash = guiCreateButton(93,188,37,36,"#",false,keypadWindow)
keypadButtonExit = guiCreateButton(13,228,37,36,"Exit",false,keypadWindow)
keypadButtonEnter = guiCreateButton(53,228,37,36,"Enter",false,keypadWindow)
keypadButtonClear = guiCreateButton(93,228,37,36,"Clear",false,keypadWindow)

-- create a gridlist to act as a backdrop on the kaypad display
keypadGridlistDisplay = guiCreateGridList(13,25,117,33,false,keypadWindow)
guiGridListSetSelectionMode(keypadGridlistDisplay,2)
guiSetAlpha(keypadGridlistDisplay,0.6)
-- create a label so we can write text on the keypad display
keypadLabelDisplay = guiCreateLabel(14,26,115,30,"Enter Keycode.",false,keypadWindow)
guiLabelSetColor(keypadLabelDisplay,255,000,000)
guiLabelSetVerticalAlign(keypadLabelDisplay,"center")
guiLabelSetHorizontalAlign(keypadLabelDisplay,"center",false)

guiSetVisible(keypadWindow,false)
end

-- create the GUI when the resource starts
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()),createKeypad)
</syntaxhighlight>
As you can see, the keypad consists of 10 numerical keys (0-9), two character keys (* and #), a clear key, an exit key and an enter key.
This means the codes used on the keypad can contain any of these characters (0123456789*#).

===Managing the display===
We will begin by writing a small function to control the display on the keypad.
This is done by encapsulating several methods of changing the text into a single function,
which will enable us to easily add/remove text from the display later on.
<syntaxhighlight lang="lua">
function updateDisplay(text)
-- if we are passing some text
if text then
-- if its a digit or * or #, then append it to the end of the display
if tonumber(text) or text == "*" or text == "#" then
guiSetText(keypadLabelDisplay,guiGetText(keypadLabelDisplay) .. text)
-- otherwise replace the display with the new text
else
guiSetText(keypadLabelDisplay,text)
end
-- if we pass nil, clear the display entirely
else
guiSetText(keypadLabelDisplay,"")
end
end
</syntaxhighlight>
We can now simply call updateDisplay(our text) to change the text on the display, or updateDisplay(nil) to clear it.

===Detecting the clicks===
With so many buttons that do very similar tasks on our keypad, there are two methods available to us for detecting when a player clicks on them.

We could add [[onClientGUIClick]] events for every button individually, as we have done in previous tutorials; Or, alternatively,
we could add a single [[onClientGUIClick]] handle for the window (which is the parent of all our other keypad GUI elements), filter our results to include only the buttons we want and trigger our own custom event.

For the purposes of this tutorial and in the interest of outlining multiple approaches, we will explore the second method, though either one is an acceptable solution.
<syntaxhighlight lang="lua">
addEventHandler("onClientGUIClick",keypadWindow,processKeypadClicks,true)
</syntaxhighlight>
'''Notice the final argument is set to 'true'. This means that clicks on any other elements in the same branch of the tree will also trigger this event handle (eg. clicks on our buttons).'''

Add this line of code into your createKeypad function, after your GUI has been created.

Now that we are detecting all clicks on our GUI, we need to filter out the ones we do not want (ie: clicks on the window or display) and trigger our custom event:
<syntaxhighlight lang="lua">
function processKeypadClicks(button,state)
if button == "left" and state == "up" then
-- if the source of this event is a gui button
if getElementType(source) == "gui-button" then
-- trigger our custom event and send the keypad id of this keypad as an argument
triggerEvent("onKeypadButtonClicked",source,getElementData(keypadWindow,"keypadID"))
end
end
end
</syntaxhighlight>
As you can see, we are now triggering our custom event "onKeypadButtonClicked" whenever a button is clicked on the keypad.
Also note we use element data "keypadID" to differentiate between keypads. This data will need to be set whenever the player is shown a new keypad.
We will cover this in more detail later.

===Handling the clicks===
Much like when using [[triggerServerEvent]] in previous tutorials, we now need to define the event, only this time it is purely clientside:
<syntaxhighlight lang="lua">
addEvent("onKeypadButtonClicked",false)
addEventHandler("onKeypadButtonClicked",root,
function(keypadID)

end
)
</syntaxhighlight>
Note the second argument in [[addEvent]] is set to false, indicating that this event cannot be triggered from the server.
Also note, the function we are using in the [[addEventHandler]] does not have a name. If you contract it down and remove the spacing, you get:
<syntaxhighlight lang="lua">
addEventHandler("onKeypadButtonClicked",root,function() ... end)
</syntaxhighlight>
This simply means instead of storing the pointer to the function in a variable, we are passing it directly as an argument.
Doing it this way cleans up the code and will often make it easier to follow.

Now that the event has been created, we can fill in the code logic that will control our button presses.
<syntaxhighlight lang="lua">
addEvent("onKeypadButtonClicked",false)
addEventHandler("onKeypadButtonClicked",root,
function(keypadID)
-- clear the display if this is the first time its being used
if guiGetText(keypadLabelDisplay) == "Enter Keycode." or guiGetText(keypadLabelDisplay) == "Invalid Keycode." then
updateDisplay()
end

-- if its the clear button
if guiGetText(source) == "Clear" then
-- clear the display
updateDisplay()

-- if its the enter button
elseif guiGetText(source) == "Enter" then
-- get the currently entered code from the display
local code = guiGetText(keypadLabelDisplay)

-- if they have entered a code
if code then
-- trigger the server so we can verify their code
triggerServerEvent("verifyKeypadCode",getLocalPlayer(),code,keypadID)
end

-- if its the exit button
elseif guiGetText(source) == "Exit" then
-- hide the keypad and reset the display text ready for next time
guiSetVisible(keypadWindow,false)
updateDisplay("Enter Keycode.")
showCursor(false,false)

-- otherwise, it must be a character button
else
updateDisplay(guiGetText(source))
end
end
)
</syntaxhighlight>

==Serverside Verification==
For this part of the tutorial, you will need to open up a serverside lua file from your resource to work with.

===Defining the keycode===
Now that we have completed the keypad clicking logic, we need to move on to verifying the code entered into the keypad.
To do this, we need to have the correct code stored somewhere on the server, which we can check the players code against.

For the purposes of this tutorial we will simply store the code in a serverside table, however it can be done any number of ways (such as serverside xml files or MySQL databases).
<syntaxhighlight lang="lua">
local keypadCodes = {
["a51MainGateKeypadCode"] = "4455*#"
}
</syntaxhighlight>
This table stores an entry called "a51MainGateKeypadCode" with the code 4455*#

'''This is the keycode that you will use to open the gate later on in this tutorial.'''

===Verifying the code===
Now that we have a keycode to verify against, we can write our serverside event:
<syntaxhighlight lang="lua">
addEvent("verifyKeypadCode",true)
addEventHandler("verifyKeypadCode",root,function(code,keypadID)
if code then
-- using the table we created earlier, check if the code supplied is the same as the code for this gate
if code == keypadCodes[keypadID] then
-- if it is, tell the client that it was successful
triggerClientEvent(client,"onKeypadVerificationSuccessful",client,keypadID)
else
-- if it is not, tell the client that it was not successful
triggerClientEvent(client,"onKeypadVerificationFailed",client,keypadID)
end
end
end)
</syntaxhighlight>
Here we use our table and the keypadID supplied by the player to check if the codes match.

If you are not using a table to store the codes, then you will need to replace 'keypadCodes[keypadID]' with your own storage method.
Once it is verified (or not), we can trigger the client so the appropriate information can be shown on the keypad display.

==Receiving the result==
We have now finished the serverside section of the tutorial, so you will need to open up the clientside lua file from your resource
that you were previously working on.

Once our code has been verified, the server will send back the response to the client.
In just the same way as client -> server interaction, we now need to add the event that the server is going to trigger on the client.

===Catching and processing the result===
First we will add the event for when the verification is successful:
<syntaxhighlight lang="lua">
addEvent("onKeypadVerificationSuccessful",true)
addEventHandler("onKeypadVerificationSuccessful",root,
function()
-- hide the keypad and reset the display text ready for next time
guiSetVisible(keypadWindow,false)
updateDisplay("Enter Keycode.")
showCursor(false,false)
end
)
</syntaxhighlight>

Finally we can add the event for when the verification is unsuccessful:
<syntaxhighlight lang="lua">
addEvent("onKeypadVerificationFailed",true)
addEventHandler("onKeypadVerificationFailed",root,
function()
-- update the display text to show the code was invalid
updateDisplay("Invalid Keycode.")
end
)
</syntaxhighlight>

This completes the keypad section of the tutorial.

For an example of how to implement this into a working gate system, carry on reading the next section.

==Applying the Keypad==
For the keypad to have any use, we need something to use it on.
For this tutorial we will be using gates, and as mentioned earlier we will create a main gate into A51.

===Creating the gate===
First of all, we need to create the gate object.
For the purposes of this example, we will be using a map file to store the object.
While this is the recommended method for defining objects, it is not the only way to approach it.

Navigate to your resource folder and make a new file called gate.map, then add your new map file to your meta.xml using:
<syntaxhighlight lang="lua">
<map src="gate.map"/>
</syntaxhighlight>

''If you are unsure of map file syntax, please see the [http://wiki.multitheftauto.com/wiki/Writing_Gamemodes| Writing Gamemodes Tutorial] or check the [[Object]] page for help.''
<syntaxhighlight lang="lua">
<map>
<object id="a51MainGateKeypadCode" model="971" posX="96.736" posY="1918.352" posZ="20.694" rotX="0" rotY="0" rotZ="270.40" newPosX="96.751" newPosY="1914.474" newPosZ="20.694" />
</map>
</syntaxhighlight>
This will create a gate object across the A51 entrance. The object will have position and rotation data, as well as its newPosX,newPosY and newPosZ information that we need to be able to move it.

'''Note that the object id is the same as the table entry we created earlier to hold the access code.'''
This is one possible method that could be accessed to link this gate with that particular keycode.

===Opening the keypad===
Back in the clientside lua file again, we can now work on linking the gate and the keypad.

Now that we have our gate, we need a way of accessing the keypad to open it.
For the purposes of this tutorial we will use a simple command, however you could just as easily use a colshape or button press.
<syntaxhighlight lang="lua">
addCommandHandler("a51gate",function()
guiSetVisible(keypadWindow,true)
showCursor(true,true)
setElementData(keypadWindow,"keypadID","a51MainGateKeypadCode")
end)
</syntaxhighlight>
Note that we set the element data "keypadID".
This is very important because it allows us to keep track of which gate we are trying to open (in this case, the "a51MainGateKeypadCode" gate).

===Opening the gate===
With our gate created and our keypad ready, all thats left now is to open the gate.
Having created custom events earlier for successfully and unsuccessfully verifying the code, this now becomes very easy to do.
All we do is add an event handler for our custom "success" event, and using the keypadID we defined earlier we can move the gate inside it:
<syntaxhighlight lang="lua">
addEventHandler("onKeypadVerificationSuccessful",root,
-- keypadID is sent back from the server
function(keypadID)
-- get the gate object (this is where the id="a51MainGateKeypadCode" tag in the map file becomes useful)
local gate = getElementByID(keypadID)

-- if we found the object
if gate then
-- get the new position (as we defined in the map file)
local x = tonumber(getElementData(gate,"newPosX"))
local y = tonumber(getElementData(gate,"newPosY"))
local z = tonumber(getElementData(gate,"newPosZ"))

-- move the gate
moveObject(gate,1500,x,y,z)

-- get the original position
x = tonumber(getElementData(gate,"posX"))
y = tonumber(getElementData(gate,"posY"))
z = tonumber(getElementData(gate,"posZ"))

-- set a timer to close the gate in 5 seconds
setTimer(moveObject,5000,1,gate,1500,x,y,z)
end
end
)
</syntaxhighlight>
Note how by using the keypadID sent back from the server, we can use if statements and checks against the id to control any number of gates from the same function.

You should now have a working example of a GUI Keypad controlling an A51 Gate.

Introduction to Scripting the GUI

2010-01-03T02:10:24Z

R3mp:

One important feature in MTA:SA is the ability to script customized GUI (Graphic User Interface). The GUI consists of windows, button, edit boxes, check boxes... Almost every standard form components in graphical environments. They can be displayed while the user is in game, and used for inputs and outputs in place of traditional commands.

[[Image:AdminGUI.png|thumb|Admin Console GUI]]

==A tutorial to make a login window==
In this tutorial we'll make a simple login window, with two input boxes and a button. The window appears when the player joins the game, and once the button is clicked, the player is spawned. The tutorial will continue the gamemode we made in [[Scripting Introduction|Introduction to Scripting]] ''(If you have used the [[Scripting Introduction|Introduction to Scripting]], you will need to remove or comment the [[spawnPlayer]] line in the "joinHandler" function in your code, as we will be replacing it with a gui alternative in this tutorial)''. We'll also take a look at client-side scripting.

===Draw the window===
All the GUI must be made client side. It is also a good practice to keep all the client scripts in a separate folder. Browse to /Your MTA Server/mods/deathmatch/resources/myserver/ directory, and create a folder named "client". Under /client/ directory, create a text file and name it "gui.lua", and in this file we will write a funtion that draws the window:
<syntaxhighlight lang="lua">
function createLoginWindow()
-- define the X and Y positions of the window
local X = 0.375
local Y = 0.375
-- define the width and height of the window
local Width = 0.25
local Height = 0.25
-- create the window and save its element value into the variable 'wdwLogin'
-- click on the function's name to read its documentation
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)
end
</syntaxhighlight>

===Relative and Absolute===
Note that the final argument passed to guiCreateWindow in the above example is ''true''. This indicates that the coordinates and dimensions of the window are '''relative''', meaning they are a ''percentage'' of the total screen size. This means that if the far left side of the screen is 0, and the far right is 1, an X position of 0.5 would represent the centre point of the screen. Similarly, if the top of the screen is 0 and the bottom is 1, a Y position of 0.2 would be 20% of the way down the screen. The same principles apply to both Width and Height as well (with a Width value of 0.5 meaning the window will be half as wide as the screen).

The alternative to using relative values is using '''absolute''' (by passing ''false'' instead of true to guiCreateWindow). Absolute values are calculated as the total number of pixels from the top-left corner of the parent (if no gui element parent is specified, the parent is the screen itself). If we assume a screen resolution of 1920x1200, the far left side of the screen being 0 pixels and the far right being 1920 pixels, an X position of 960 will represent the centre point of the screen. Similarly, if the top of the screen is 0 pixels and the bottom is 1200, a Y position of 20 would be 20 pixels down from the top of the screen. The same principles apple to both Width and Height as well (with a Width value of 50 meaning the window will be 50 pixels wide). ''You can use [[guiGetScreenSize]] and a little maths to calculate certain absolute positions.''

The differences between using relative and absolute values is quite simple; gui created using absolute values will always remain exactly the same pixel size and position, while gui created using relative values will always be a percentage of its parent's size.

Absolute is generally easier to maintain when editing code by hand, however your choice of type depends on the situation you are using it for.

For the purposes of this introduction we will be using relative values.

===Adding the components===
Next, we'll add the text labels (saying "username:" and "password:"), edit boxes (for entering your data) and a button to log in:
<syntaxhighlight lang="lua">
function createLoginWindow()
local X = 0.375
local Y = 0.375
local Width = 0.25
local Height = 0.25
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)

-- define new X and Y positions for the first label
X = 0.0825
Y = 0.2
-- define new Width and Height values for the first label
Width = 0.25
Height = 0.25
-- create the first label, note the final argument passed is 'wdwLogin' meaning the window
-- we created above is the parent of this label (so all the position and size values are now relative to the position of that window)
guiCreateLabel(X, Y, Width, Height, "Username", true, wdwLogin)
-- alter the Y value, so the second label is slightly below the first
Y = 0.5
guiCreateLabel(X, Y, Width, Height, "Password", true, wdwLogin)

X = 0.415
Y = 0.2
Width = 0.5
Height = 0.15
edtUser = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
Y = 0.5
edtPass = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
-- set the maximum character length for the username and password fields to 50
guiEditSetMaxLength(edtUser, 50)
guiEditSetMaxLength(edtPass, 50)

X = 0.415
Y = 0.7
Width = 0.25
Height = 0.2
btnLogin = guiCreateButton(X, Y, Width, Height, "Log In", true, wdwLogin)

-- make the window invisible
guiSetVisible(wdwLogin, false)
end
</syntaxhighlight>
Note that every GUI component created is a child of the window, this is done by specifying the parent element (wdwLogin, in this case) when creating the component.

This is very useful because not only does it mean that all the components are attached to the window and will move with it, but also that any changes done to the parent window will be applied down the tree to these child components. For example, we can now hide all of the GUI we just created by simply hiding the window:
<syntaxhighlight lang="lua">
guiSetVisible(wdwLogin, false) --hides all the GUI we made so we can show them to the player at the appropriate moment.
</syntaxhighlight>

===Using the function we wrote===
The createLoginWindow function is now complete, but it won't do anything until we call it. It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed. Therefore, we'll write an event handler for "[[onClientResourceStart]]" to create the window:
<syntaxhighlight lang="lua">
-- attach the event handler to the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
createLoginWindow()
end
)
</syntaxhighlight>

As this is a log in window, we now need to show the window when the player joins the game.
This can be done using the same event, "[[onClientResourceStart]]", so we can modify the above code to include showing the window:
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- create the log in window and its components
createLoginWindow()

-- output a brief welcome message to the player
outputChatBox("Welcome to My MTA:SA Server, please log in.")

-- if the GUI was successfully created, then show the GUI to the player
if (wdwLogin ~= nil) then
guiSetVisible(wdwLogin, true)
else
-- if the GUI hasnt been properly created, tell the player
outputChatBox("An unexpected error has occurred and the log in GUI has not been created.")
end

-- enable the players cursor (so they can select and click on the components)
showCursor(true)
-- set the input focus onto the GUI, allowing players (for example) to press 'T' without the chatbox opening
guiSetInputEnabled(true)
end
)
</syntaxhighlight>

Note that we have a simple security check before making the window visible, so in the unlikely event that the window has not been created, meaning wdwLogin is not a valid element, we don't get an error and just inform the player what has happened.
In the next step, we will create the button functionality for the log in button.

==Scripting the button==
Now that we have created our GUI and shown it to the player, we need to make it work.

===Detecting the click===
When the player clicks on any part of the GUI, the event "[[onClientGUIClick]]" will be triggered for the GUI component you clicked on. This allows us to easily detect any clicks on the GUI elements we want to use.
For example, we can attach the event to the btnLogin button to catch any clicks on it:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to btnLogin and set it to trigger the 'clientSubmitLogin' function
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>
'''Note the final argument passed is "false". This indicates that the event will only trigger directly on btnLogin, not if the event has propagated up or down the tree. Setting this to "true" while attaching to gui elements will mean that clicking on any element in the same branch will trigger this event.'''

This line of code can now be added inside the createLoginWindow function. It is a common mistake to try and attach events to non-existant GUI elements, so make sure you always attach your events '''after''' the gui element (in this case, the button) has been created:
<syntaxhighlight lang="lua">
function createLoginWindow()
-- create all our GUI elements
...

-- now add our onClientGUIClick event to the button we just created
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>

===Managing the click===
Now that we can detect when the player clicks on the button, we need to write code to manage what happens when they do.
In our [[onClientGUIClick]] event handle, we told it to call the function clientSubmitLogin whenever btnLogin is clicked.
Therefore, we can now use the function clientSubmitLogin to control what happens when the button is clicked:
<syntaxhighlight lang="lua">
-- create the function and define the 'button' and 'state' parameters
-- (these are passed automatically by onClientGUIClick)
function clientSubmitLogin(button,state)
-- if our login button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- move the input focus back onto the game (allowing players to move around, open the chatbox, etc)
guiSetInputEnabled(false)
-- hide the window and all the components
guiSetVisible(wdwLogin, false)
-- hide the mouse cursor
showCursor(false)
end
end
</syntaxhighlight>
Now, when the button is clicked, the window will be hidden and all controls will be returned to the player. Next, we will tell the server to allow the player to spawn.

===Triggering the server===
Triggering the server can be done using [[triggerServerEvent]]. This allows you to trigger a specified event on the server from the client. The same can be done in reverse using [[triggerClientEvent]].
Here, we use the [[triggerServerEvent]] function to call our own custom event on the server, named "submitLogin", which will then control the spawning of the player serverside.
<syntaxhighlight lang="lua">
function clientSubmitLogin(button,state)
if button == "left" and state == "up" then
-- get the text entered in the 'username' field
local username = guiGetText(edtUser)
-- get the text entered in the 'password' field
local password = guiGetText(edtPass)

-- if the username and password both exist
if username and password then
-- trigger the server event 'submitLogin' and pass the username and password to it
triggerServerEvent("submitLogin", getRootElement(), username, password)

-- hide the gui, hide the cursor and return control to the player
guiSetInputEnabled(false)
guiSetVisible(wdwLogin, false)
showCursor(false)
else
-- otherwise, output a message to the player, do not trigger the server
-- and do not hide the gui
outputChatBox("Please enter a username and password.")
end
end
end
</syntaxhighlight>

===Creating the serverside event===
At this point we now have all the code needed on the client side, so open up your serverside 'script.lua' file (from the [[Scripting Introduction|Introduction to Scripting]]) or another suitable serverside file to work with.

On the server side, recall that we are spawning the player as soon as they login.
So, first of all, we will need to define the custom event that we used before on the client. This can be done using [[addEvent]] and [[addEventHandler]].
<syntaxhighlight lang="lua">
-- create our loginHandler function, with username and password parameters (passed from the client gui)
function loginHandler(username,password)

end

-- define our custom event, and allow it to be triggered from the client ('true')
addEvent("submitLogin",true)
-- add an event handler so that when submitLogin is triggered, the function loginHandler is called
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>

===Logging in===
Now we have a function that is called through the custom event 'submitLogin', we can start to work on logging in and spawning the player, using our 'loginHandler' function:
<syntaxhighlight lang="lua">
function loginHandler(username,password)
-- check that the username and password are correct
if username == "user" and password == "apple" then
-- the player has successfully logged in, so spawn them
if (client) then
spawnPlayer(client, 1959.55, -1714.46, 10)
fadeCamera(client, true)
outputChatBox("Welcome to My Server.", client)
end
else
-- if the username or password are not correct, output a message to the player
outputChatBox("Invalid username and password. Please re-connect and try again.",client)
end
end

addEvent("submitLogin",true)
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>
'''For the purposes of this tutorial, a very basic username and password system is shown. For a more comprehensive alternative, you can use the Account System or a MySQL database.'''

Also note the use of the variable "client", it's an internal variable used by MTA to identify the player who triggered the event.

Finally, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

At this point, we now have a basic login window that checks the player's username and password when the login button is clicked. If they are correct, the player is automatically spawned.

For further GUI tutorials, see [[Scripting the GUI - Tutorial 1|Scripting the GUI - Tutorial 1 (Gridlists)]]

[[it:Introduzione_allo_scripting_della_GUI]]
[[ru:Introduction to Scripting the GUI]]

Scripting the GUI - Tutorial 1

2010-01-03T02:06:05Z

R3mp: Created page with ''''Scripting the Gui - Tutorial 1 (Gridlists)''' In this tutorial we will explore the use of gridlists in creating a vehicle selection screen, with optional clientside vehicle x…'

'''Scripting the Gui - Tutorial 1 (Gridlists)'''

In this tutorial we will explore the use of gridlists in creating a vehicle selection screen, with optional clientside vehicle xml data reading.
'''Note that this tutorial assumes you are familiar with all the content covered in the [[Introduction to Scripting GUI|Previous tutorial]].'''

==Setting up the Vehicle Selection==

===Creating the GUI===
To begin, open up a clientside lua file (if you have been following the [[Scripting Introduction]], this is gui.lua) to work with.

In this file, we will start writing our function for creating the GUI.
As covered in the [[Introduction to Scripting GUI|Previous tutorial]], there are 2 value type options available when creating gui: '''relative''' and '''absolute'''.

For the purposes of this tutorial, we will be using '''absolute''' values.

This will create a simple GUI with a window, gridlist and button:
<syntaxhighlight lang="lua">
function createVehicleSelection()
-- get the screen width and height
local sWidth, sHeight = guiGetScreenSize()

-- use some simple maths to position the window in the centre of the screen
local Width,Height = 376,259
local X = (sWidth/2) - (Width/2)
local Y = (sHeight/2) - (Height/2)
windowVehicleSelection = guiCreateWindow(X,Y,Width,Height,"Vehicle Selection Window",false)

gridlistVehicleSelection = guiCreateGridList(10,26,357,192,false,windowVehicleSelection)
-- add a "Vehicle" and a "Type" collumn to the gridlist
guiGridListAddColumn(gridlistVehicleSelection,"Vehicle",0.2)
guiGridListAddColumn(gridlistVehicleSelection,"Type",0.2)

-- set the default width of the columns to roughly half the size of the gridlist (each)
guiGridListSetColumnWidth(gridlistVehicleSelection,1,0.4,true)
guiGridListSetColumnWidth(gridlistVehicleSelection,2,0.5,true)

buttonCreate = guiCreateButton(121,227,120,20,"Create",false,windowVehicleSelection)

-- add the event handler for when the button is clicked
addEventHandler("onClientGUIClick",buttonCreate,createVehicleHandler,false)

-- hide the GUI
guiSetVisible(windowVehicleSelection,false)

-- this will add all the vehicle options onto the gridlist, it is explained later in this tutorial
populateGridlist()
end
</syntaxhighlight>

We now also need to call this function somewhere, otherwise the GUI will never be created.
As in previous tutorials, to do this we can use [[onClientResourceStart]].
<syntaxhighlight lang="lua">
-- when the resource is started, create the GUI and hide it
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()),
function()
createVehicleSelection()
end
)
</syntaxhighlight>

===Showing the GUI===
Unlike in previous tutorials, we want players to be able to open this window whenever they chose, not when the resource starts.
So, we can add a [[addCommandHandler|Command]] to do this.
<syntaxhighlight lang="lua">
-- create the function that will show the window
function showVehicleSelection()
-- if the window isnt visible, show it
if not guiGetVisible(windowVehicleSelection) then
guiSetVisible(windowVehicleSelection,true)

showCursor(true,true)
end
end

-- add the command /vehicleselection and set it to call the showVehicleSelection function
addCommandHandler("vehicleselection",showVehicleSelection)
</syntaxhighlight>

===Populating the Gridlist from a table===
Now that we have our basic GUI created, we need to fill the gridlist with all of our vehicles.

To begin with, we will do this using a simple clientside table.
Later in the tutorial, we will explore expanding this method to use .xml files for storing information.
To begin, we must create a small table containing a selection of vehicles that we can spawn.

The table contains vehicles in the format ["description"] = vehicle_id :
<syntaxhighlight lang="lua">
-- create the table and fill it with a selection of vehicle ids and names
local vehicleSelectionTable = {
["Sparrow"] = 469,
["Stuntplane"] = 513,
["BF-400"] = 581,
["Freeway"] = 463,
["Speeder"] = 452,
["Jester"] = 559,
["Sabre"] = 475,
["Police Ranger"] = 599,
["Utility Van"] = 552,
["Tug"] = 583
}
</syntaxhighlight>
Place this code at the very top of your file (it does not need to be inside a function).

Next, we can write our "populateGridlist" function which will fill the Gridlist with all the vehicles in the table.
To do this we simply need to loop through all the values in the table, adding each one to the gridlist as we go.
We will also set hidden data using [[guiGridListSetItemData]] to store the vehicle id:
<syntaxhighlight lang="lua">
function populateGridlist()
-- loop through the table
for name,vehicle in pairs(vehicleSelectionTable) do
-- add a new row to the gridlist
local row = guiGridListAddRow(gridlistVehicleSelection)

-- set the text in the first column to the vehicle name
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)
-- set the text in the second column to the vehicle type
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(vehicle),false,false)

-- set the data for gridlist slot as the vehicle id
guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(vehicle))
end
end
</syntaxhighlight>

===Managing the click===
Now that we have our GUI completed, we need to be able to catch any clicks made on the "create" button.
We have attached the [[onClientGUIClick]] event to buttonCreate already, so now we need to write the function that it calls.
In this function we do some basic error checking, such as making sure a vehicle has been selected in the list.
We can then use some maths to find a position infront of the player and send the server this information to spawn the vehicle (using [[triggerServerEvent]])
<syntaxhighlight lang="lua">
function createVehicleHandler(button,state)
if button == "left" and state == "up" then
-- get the selected item in the gridlist
local row,col = guiGridListGetSelectedItem(gridlistVehicleSelection)

-- if something is selected
if row and col and row ~= -1 and col ~= -1 then
-- get the vehicle id data from the gridlist that is selected
local selected = guiGridListGetItemData(gridlistVehicleSelection,row,col)

-- make sure the vehicle id is a number not a string
selected = tonumber(selected)

-- get the players position and rotation
local rotz = getPedRotation(getLocalPlayer())
local x,y,z = getElementPosition(getLocalPlayer())
-- find the position directly infront of the player
x = x + ( math.cos ( math.rad ( rotz+90 ) ) * 3)
y = y + ( math.sin ( math.rad ( rotz+90 ) ) * 3)

if selected and x and y and z then
-- trigger the server
triggerServerEvent("createVehicleFromGUI",getRootElement(),selected,x,y,z)

-- hide the gui and the cursor
guiSetVisible(windowVehicleSelection,false)
showCursor(false,false)
else
outputChatBox("Invalid arguments.")
end
else
-- otherwise, output a message to the player
outputChatBox("Please select a vehicle.")
end
end
end
</syntaxhighlight>

===Creating the Vehicle===
At this point we now have all the code needed on the client side, so open up a serverside .lua file to work with.

On the server side, we will first of all need to define the custom event that we triggered before from the client. This can be done using [[addEvent]] and [[addEventHandler]].
Finally we will need a small function for creating the vehicle:
<syntaxhighlight lang="lua">
function createMyVehicle(vehicleid,x,y,z)
-- check all the arguments exist
if vehicleid and x and y and z then
createVehicle(vehicleid,x,y,z)
end
end

addEvent("createVehicleFromGUI",true)
addEventHandler("createVehicleFromGUI",root,createMyVehicle)
</syntaxhighlight>
Note the use of the "root" variable. This is an MTA variable containing the root element; every resource has one.

This completes the first section of the tutorial. You should now have a basic, working vehicle spawn script.

In the second section, we will cover collapsible gridlist data and clientside xml file reading.

==Expanding the code==
This section will detail several ways to improve upon the code you now have.

===Importing Data===
One big improvement over the previously mentioned method is to use external files to store the vehicle information, allowing us to much more quickly and easily manage large amounts of data.
For this tutorial, we will use a clientside xml file to hold the information.

First of all you will need to create your xml file, so navigate to your resources directory and create a new file named vehicles.xml:

''For the purpose of this example, we will include only a small fraction of the total vehicles, however the file can easily be expanded to include them all.''

If you are unsure of xml data structures, you can browse the [http://wiki.multitheftauto.com/wiki/Server_Scripting_Functions#XML_functions| MTA xml functions] for help.
<syntaxhighlight lang="lua">
<root>
<group type="Bikes">
<vehicle id="581" name="BF-400"/>
<vehicle id="463" name="Freeway"/>
<vehicle id="481" name="BMX"/>
</group>
<group type="Boats">
<vehicle id="472" name="Coastguard"/>
<vehicle id="452" name="Speeder"/>
</group>
<group type="Helicopters">
<vehicle id="487" name="Maverick"/>
<vehicle id="469" name="Sparrow"/>
</group>
<group type="Planes">
<vehicle id="593" name="Dodo"/>
<vehicle id="513" name="Stuntplane"/>
</group>
<group type="Sports Cars">
<vehicle id="565" name="Flash"/>
<vehicle id="559" name="Jester"/>
<vehicle id="477" name="ZR-350"/>
</group>
<group type="2-Door">
<vehicle id="474" name="Hermes"/>
<vehicle id="475" name="Sabre"/>
</group>
<group type="Emergency">
<vehicle id="416" name="Ambulance"/>
<vehicle id="599" name="Police ranger"/>
</group>
<group type="Industrial">
<vehicle id="573" name="Dune"/>
<vehicle id="552" name="Utility van"/>
</group>
<group type="Misc">
<vehicle id="457" name="Caddy"/>
<vehicle id="583" name="Tug"/>
</group>
</root>
</syntaxhighlight>
Once you have created your file, do not forget to add it to the meta.xml of your resource with the appropriate client tag.

Note the group "type" tag. This is an arbitrary description of the vehicles contained within the group and can be renamed or added as any text.
Similarly, the vehicle "name" tag is also just a textual description of the vehicle and does not need to be the exact vehicle name.

Now that we have the data, we can import it into the game and display it in the GUI.
'''If you are following on from the first section of this tutorial, this new code will replace what is inside your existing 'populateGridlist' function.'''
First, we need to load the file:
<syntaxhighlight lang="lua">
function populateGridlist()
-- load the file and save the root node value it returns
local rootnode = xmlLoadFile("vehicles.xml")

-- check that the file exists and has been correctly loaded
if rootnode then
-- unload the xml file
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>
Always make sure you unload any files once you are finished using them.

We can now start collecting the data from the file and entering it into our gridlist.
We can do this by looping through the xml data (in a similar manner to looping through the vehicle table earlier in this tutorial) and adding each entry into the list.
<syntaxhighlight lang="lua">
function populateGridlist()
local rootnode = xmlLoadFile("vehicles.xml")

if rootnode then
-- first, we find every "group" node (they are direct children of the root)
for _,group in ipairs(xmlNodeGetChildren(rootnode)) do
-- add a new row to the gridlist
local row = guiGridListAddRow(gridlistVehicleSelection)

-- get the group name
local name = xmlNodeGetAttribute(group,"type")

-- set the text in the first column to the group type and indicate it is a section ('true')
-- (sections on gridlists show up in bold and cannot be clicked)
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,true,false)

-- then, for every group that we find, loop all of its children (the vehicle nodes)
-- and add them into the gridlist
for _,vehicle in ipairs(xmlNodeGetChildren(group)) do
-- add a new row to the gridlist
row = guiGridListAddRow(gridlistVehicleSelection)

-- get the vehicle name and id
name = xmlNodeGetAttribute(vehicle,"name")
local id = xmlNodeGetAttribute(vehicle,"id")

-- set the text in the first column to the vehicle name
guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)
-- set the text in the second column to the vehicle type
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(tonumber(id)),false,false)

-- finally, set the vehicle id as data so we can access it later
guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(id))
end
end

-- unload the xml file now that we are finished
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>
Note the use of for loops in the code with [[xmlNodeGetChildren]]. This saves us a lot of time and effort as we do not have to manually code each group and vehicle into the list.

You should now have a fully working vehicle selection menu, reading all of its data from a clientside xml file.
Next, we will examine how to generate the appearance of collapsing and expanding sections in a gridlist.

===Collapsing/Expanding the Gridlist===
Allowing sections of the gridlist to be collapsed or expanded gives much more control over the visible content to the user.
This frees up space on the screen and makes the whole menu much more comfortable to use.

===Loading the data===
To be able to achieve this effect (as it is not a natural feature of gridlists) we will need to load the vehicle information into a table (from the xml file), rather than directly including it all in the gridlist.
'''If you are following on from a previous section of this tutorial, this new code will replace what is inside your existing 'populateGridlist' function.'''

This works in much the same way the previous xml loading example does, only this time instead of saving the data into the gridlist, we save it into a table entry instead.
We also set the custom data "header" on the gridlist slots to denote which gridlist entries are our "group" entries and which are vehicles.
<syntaxhighlight lang="lua">
function populateGridlist()
local rootnode = xmlLoadFile("vehicles.xml")

-- create a blank global table to store our imported data
vehicleTable = {}

if rootnode then
for _,group in ipairs(xmlNodeGetChildren(rootnode)) do
-- create an entry in the gridlist for every vehicle "group"
local row = guiGridListAddRow(gridlistVehicleSelection)

local name = xmlNodeGetAttribute(group,"type")

guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)

-- add an entry containing the group name into the table
vehicleTable[name] = {}

-- we will use the custom data "header" to indicate that this entry can be expanded/collapsed
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")

-- then, for every group that we find, loop all of its children (the vehicle nodes) and store them in a table
for _,vehicle in ipairs(xmlNodeGetChildren(group)) do
local vname = xmlNodeGetAttribute(vehicle,"name")
local id = xmlNodeGetAttribute(vehicle,"id")

-- insert both the vehicle id and the vehicle description into the table
table.insert(vehicleTable[name],{id,vname})
end
end

-- set element data on the gridlist so we know which group is currently showing
setElementData(gridlistVehicleSelection,"expanded","none")

-- unload the xml file now that we are finished
xmlUnloadFile(rootnode)
end
end
</syntaxhighlight>

Now that we have all the data stored, we can quickly manipulate it when neccessary.

===Managing the double click===
To enable the player to simply double click on a group name to expand/collapse it we need to use the [[onClientGUIDoubleClick]] event.
If we attach it to the gridlist, we can then catch any double clicks on the group names in it:
<syntaxhighlight lang="lua">
-- attach the onClientGUIDoubleClick event to the gridlist and set it to call processDoubleClick
addEventHandler("onClientGUIDoubleClick",gridlistVehicleSelection,processDoubleClick,false)
</syntaxhighlight>
Add this line of code in your createVehicleSelection, after the gridlist has been created.

As the gridlist items are not separate GUI elements, we must capture all clicks from anywhere on the gridlist then process them to filter out the ones we do not want.
This can be done by checking if an item is selected, then checking if the item is one of our "group" values (using our previously mentioned "header" data):
<syntaxhighlight lang="lua">
function processDoubleClick(button,state)
if button == "left" and state == "up" then
local row,col = guiGridListGetSelectedItem(gridlistVehicleSelection)

-- if something in the gridlist has been selected
if row and col and row ~= -1 and col ~= -1 then
-- if it is a header
if guiGridListGetItemData(gridlistVehicleSelection,row,col) == "header" then
local selected = guiGridListGetItemText(gridlistVehicleSelection,row,col)

-- call the function to collapse or expand the menu and pass which section it is as an argument
changeGridlistState(selected)
end
end
end
end
</syntaxhighlight>

Once we have narrowed down the double clicks to only those done on our group headers, we can expand/collapse them appropriately.
This can be done by simply setting new text values in the gridlist according to the newly expanded/collapsed group, which creates the convincing illusion of collapsable menus.

Note that much of the following code is reused from previous areas of this tutorial. While it is generally bad practice to clone sections of code in this way, for the purposes of this example it is far easier to understand.
<syntaxhighlight lang="lua">
function changeGridlistState(group)
if group then
-- if the group is already expanded, we want to collapse it
if getElementData(gridlistVehicleSelection,"expanded") == group then
-- first, we clear all previous data from the gridlist
guiGridListClear(gridlistVehicleSelection)

-- now, loop all the group entries in the vehicle table that we created earlier
for group,_ in pairs(vehicleTable) do
-- add each group to the list and mark them with "header"
local row = guiGridListAddRow(gridlistVehicleSelection)

guiGridListSetItemText(gridlistVehicleSelection,row,1,group,false,false)
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")
end

-- update the data to indicate that no groups are currently expanded
setElementData(gridlistVehicleSelection,"expanded","none")

-- otherwise, we want to expand it
else
guiGridListClear(gridlistVehicleSelection)

local row = guiGridListAddRow(gridlistVehicleSelection)

guiGridListSetItemText(gridlistVehicleSelection,row,1,group,false,false)
guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")

-- loop every vehicle in the specified groups table
for _,vehicle in ipairs(vehicleTable[group]) do
-- add them to the gridlist and set the vehicle id as data
row = guiGridListAddRow(gridlistVehicleSelection)

-- format a "-" into the string to make it visually easier to distinguish between groups and vehicles
guiGridListSetItemText(gridlistVehicleSelection,row,1,"- "..vehicle[2],false,false)
guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(tonumber(vehicle[1])),false,false)

guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(vehicle[1]))
end

-- update the data to indicate which group is currently expanded
setElementData(gridlistVehicleSelection,"expanded",group)
end
end
end
</syntaxhighlight>

This comletes the second section of the tutorial.

Introduction to Scripting the GUI

2010-01-02T18:15:41Z

R3mp:

One important feature in MTA:SA is the ability to script customized GUI (Graphic User Interface). The GUI consists of windows, button, edit boxes, check boxes... Almost every standard form components in graphical environments. They can be displayed while the user is in game, and used for inputs and outputs in place of traditional commands.

[[Image:AdminGUI.png|thumb|Admin Console GUI]]

==A tutorial to make a login window==
In this tutorial we'll make a simple login window, with two input boxes and a button. The window appears when the player joins the game, and once the button is clicked, the player is spawned. The tutorial will continue the gamemode we made in [[Scripting Introduction|Introduction to Scripting]] ''(If you have used the [[Scripting Introduction|Introduction to Scripting]], you will need to remove or comment the [[spawnPlayer]] line in the "joinHandler" function in your code, as we will be replacing it with a gui alternative in this tutorial)''. We'll also take a look at client-side scripting.

===Draw the window===
All the GUI must be made client side. It is also a good practice to keep all the client scripts in a separate folder. Browse to /Your MTA Server/mods/deathmatch/resources/myserver/ directory, and create a folder named "client". Under /client/ directory, create a text file and name it "gui.lua", and in this file we will write a funtion that draws the window:
<syntaxhighlight lang="lua">
function createLoginWindow()
-- define the X and Y positions of the window
local X = 0.375
local Y = 0.375
-- define the width and height of the window
local Width = 0.25
local Height = 0.25
-- create the window and save its element value into the variable 'wdwLogin'
-- click on the function's name to read its documentation
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)
end
</syntaxhighlight>

===Relative and Absolute===
Note that the final argument passed to guiCreateWindow in the above example is ''true''. This indicates that the coordinates and dimensions of the window are '''relative''', meaning they are a ''percentage'' of the total screen size. This means that if the far left side of the screen is 0, and the far right is 1, an X position of 0.5 would represent the centre point of the screen. Similarly, if the top of the screen is 0 and the bottom is 1, a Y position of 0.2 would be 20% of the way down the screen. The same principles apply to both Width and Height as well (with a Width value of 0.5 meaning the window will be half as wide as the screen).

The alternative to using relative values is using '''absolute''' (by passing ''false'' instead of true to guiCreateWindow). Absolute values are calculated as the total number of pixels from the top-left corner of the parent (if no gui element parent is specified, the parent is the screen itself). If we assume a screen resolution of 1920x1200, the far left side of the screen being 0 pixels and the far right being 1920 pixels, an X position of 960 will represent the centre point of the screen. Similarly, if the top of the screen is 0 pixels and the bottom is 1200, a Y position of 20 would be 20 pixels down from the top of the screen. The same principles apple to both Width and Height as well (with a Width value of 50 meaning the window will be 50 pixels wide). ''You can use [[guiGetScreenSize]] and a little maths to calculate certain absolute positions.''

The differences between using relative and absolute values is quite simple; gui created using absolute values will always remain exactly the same pixel size and position, while gui created using relative values will always be a percentage of its parent's size.

Absolute is generally easier to maintain when editing code by hand, however your choice of type depends on the situation you are using it for.

For the purposes of this introduction we will be using relative values.

===Adding the components===
Next, we'll add the text labels (saying "username:" and "password:"), edit boxes (for entering your data) and a button to log in:
<syntaxhighlight lang="lua">
function createLoginWindow()
local X = 0.375
local Y = 0.375
local Width = 0.25
local Height = 0.25
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)

-- define new X and Y positions for the first label
X = 0.0825
Y = 0.2
-- define new Width and Height values for the first label
Width = 0.25
Height = 0.25
-- create the first label, note the final argument passed is 'wdwLogin' meaning the window
-- we created above is the parent of this label (so all the position and size values are now relative to the position of that window)
guiCreateLabel(X, Y, Width, Height, "Username", true, wdwLogin)
-- alter the Y value, so the second label is slightly below the first
Y = 0.5
guiCreateLabel(X, Y, Width, Height, "Password", true, wdwLogin)

X = 0.415
Y = 0.2
Width = 0.5
Height = 0.15
edtUser = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
Y = 0.5
edtPass = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
-- set the maximum character length for the username and password fields to 50
guiEditSetMaxLength(edtUser, 50)
guiEditSetMaxLength(edtPass, 50)

X = 0.415
Y = 0.7
Width = 0.25
Height = 0.2
btnLogin = guiCreateButton(X, Y, Width, Height, "Log In", true, wdwLogin)

-- make the window invisible
guiSetVisible(wdwLogin, false)
end
</syntaxhighlight>
Note that every GUI component created is a child of the window, this is done by specifying the parent element (wdwLogin, in this case) when creating the component.

This is very useful because not only does it mean that all the components are attached to the window and will move with it, but also that any changes done to the parent window will be applied down the tree to these child components. For example, we can now hide all of the GUI we just created by simply hiding the window:
<syntaxhighlight lang="lua">
guiSetVisible(wdwLogin, false) --hides all the GUI we made so we can show them to the player at the appropriate moment.
</syntaxhighlight>

===Using the function we wrote===
The createLoginWindow function is now complete, but it won't do anything until we call it. It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed. Therefore, we'll write an event handler for "[[onClientResourceStart]]" to create the window:
<syntaxhighlight lang="lua">
-- attach the event handler to the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
createLoginWindow()
end
)
</syntaxhighlight>

As this is a log in window, we now need to show the window when the player joins the game.
This can be done using the same event, "[[onClientResourceStart]]", so we can modify the above code to include showing the window:
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- create the log in window and its components
createLoginWindow()

-- output a brief welcome message to the player
outputChatBox("Welcome to My MTA:SA Server, please log in.")

-- if the GUI was successfully created, then show the GUI to the player
if (wdwLogin ~= nil) then
guiSetVisible(wdwLogin, true)
else
-- if the GUI hasnt been properly created, tell the player
outputChatBox("An unexpected error has occurred and the log in GUI has not been created.")
end

-- enable the players cursor (so they can select and click on the components)
showCursor(true)
-- set the input focus onto the GUI, allowing players (for example) to press 'T' without the chatbox opening
guiSetInputEnabled(true)
end
)
</syntaxhighlight>

Note that we have a simple security check before making the window visible, so in the unlikely event that the window has not been created, meaning wdwLogin is not a valid element, we don't get an error and just inform the player what has happened.
In the next step, we will create the button functionality for the log in button.

==Scripting the button==
Now that we have created our GUI and shown it to the player, we need to make it work.

===Detecting the click===
When the player clicks on any part of the GUI, the event "[[onClientGUIClick]]" will be triggered for the GUI component you clicked on. This allows us to easily detect any clicks on the GUI elements we want to use.
For example, we can attach the event to the btnLogin button to catch any clicks on it:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to btnLogin and set it to trigger the 'clientSubmitLogin' function
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>
'''Note the final argument passed is "false". This indicates that the event will only trigger directly on btnLogin, not if the event has propagated up or down the tree. Setting this to "true" while attaching to gui elements will mean that clicking on any element in the same branch will trigger this event.'''

This line of code can now be added inside the createLoginWindow function. It is a common mistake to try and attach events to non-existant GUI elements, so make sure you always attach your events '''after''' the gui element (in this case, the button) has been created:
<syntaxhighlight lang="lua">
function createLoginWindow()
-- create all our GUI elements
...

-- now add our onClientGUIClick event to the button we just created
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>

===Managing the click===
Now that we can detect when the player clicks on the button, we need to write code to manage what happens when they do.
In our [[onClientGUIClick]] event handle, we told it to call the function clientSubmitLogin whenever btnLogin is clicked.
Therefore, we can now use the function clientSubmitLogin to control what happens when the button is clicked:
<syntaxhighlight lang="lua">
-- create the function and define the 'button' and 'state' parameters
-- (these are passed automatically by onClientGUIClick)
function clientSubmitLogin(button,state)
-- if our login button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- move the input focus back onto the game (allowing players to move around, open the chatbox, etc)
guiSetInputEnabled(false)
-- hide the window and all the components
guiSetVisible(wdwLogin, false)
-- hide the mouse cursor
showCursor(false)
end
end
</syntaxhighlight>
Now, when the button is clicked, the window will be hidden and all controls will be returned to the player. Next, we will tell the server to allow the player to spawn.

===Triggering the server===
Triggering the server can be done using [[triggerServerEvent]]. This allows you to trigger a specified event on the server from the client. The same can be done in reverse using [[triggerClientEvent]].
Here, we use the [[triggerServerEvent]] function to call our own custom event on the server, named "submitLogin", which will then control the spawning of the player serverside.
<syntaxhighlight lang="lua">
function clientSubmitLogin(button,state)
if button == "left" and state == "up" then
-- get the text entered in the 'username' field
local username = guiGetText(edtUser)
-- get the text entered in the 'password' field
local password = guiGetText(edtPass)

-- if the username and password both exist
if username and password then
-- trigger the server event 'submitLogin' and pass the username and password to it
triggerServerEvent("submitLogin", getRootElement(), username, password)

-- hide the gui, hide the cursor and return control to the player
guiSetInputEnabled(false)
guiSetVisible(wdwLogin, false)
showCursor(false)
else
-- otherwise, output a message to the player, do not trigger the server
-- and do not hide the gui
outputChatBox("Please enter a username and password.")
end
end
end
</syntaxhighlight>

===Creating the serverside event===
At this point we now have all the code needed on the client side, so open up your serverside 'script.lua' file (from the [[Scripting Introduction|Introduction to Scripting]]) or another suitable serverside file to work with.

On the server side, recall that we are spawning the player as soon as they login.
So, first of all, we will need to define the custom event that we used before on the client. This can be done using [[addEvent]] and [[addEventHandler]].
<syntaxhighlight lang="lua">
-- create our loginHandler function, with username and password parameters (passed from the client gui)
function loginHandler(username,password)

end

-- define our custom event, and allow it to be triggered from the client ('true')
addEvent("submitLogin",true)
-- add an event handler so that when submitLogin is triggered, the function loginHandler is called
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>

===Logging in===
Now we have a function that is called through the custom event 'submitLogin', we can start to work on logging in and spawning the player, using our 'loginHandler' function:
<syntaxhighlight lang="lua">
function loginHandler(username,password)
-- check that the username and password are correct
if username == "user" and password == "apple" then
-- the player has successfully logged in, so spawn them
if (client) then
spawnPlayer(client, 1959.55, -1714.46, 10)
fadeCamera(client, true)
outputChatBox("Welcome to My Server.", client)
end
else
-- if the username or password are not correct, output a message to the player
outputChatBox("Invalid username and password. Please re-connect and try again.",client)
end
end

addEvent("submitLogin",true)
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>
'''For the purposes of this tutorial, a very basic username and password system is shown. For a more comprehensive alternative, you can use the Account System or a MySQL database.'''

Also note the use of the variable "client", it's an internal variable used by MTA to identify the player who triggered the event.

Finally, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

At this point, we now have a basic login window that checks the player's username and password when the login button is clicked. If they are correct, the player is automatically spawned.

[[it:Introduzione_allo_scripting_della_GUI]]
[[ru:Introduction to Scripting the GUI]]

Template:Client ped functions

2009-09-23T19:44:38Z

R3mp:

{{New feature|3|1.0|
*[[blendPedAnimation]]
*[[canPedBeKnockedOffBike]]
*[[createPed]]
*[[doesPedHaveJetPack]]
*[[getPedAmmoInClip]]
*[[getPedAnimation]]
*[[getPedAnimationData]]
*[[getPedArmor]]
*[[getPedBonePosition]]
*[[getPedClothes]]
*[[getPedContactElement]]
*[[getPedControlState]]
*[[getPedOccupiedVehicle]]
*[[getPedRotation]]
*[[getPedSimplestTask]]
*[[getPedSkin]]
*[[getPedStat]]
*[[getPedTarget]]
*[[getPedTargetCollision]]
*[[getPedTargetEnd]]
*[[getPedTargetRange]]
*[[getPedTargetStart]]
*[[getPedTask]]
*[[getPedTotalAmmo]]
*[[getPedVoice]]
*[[getPedWeapon]]
*[[getPedWeaponMuzzlePosition]]
*[[getPedWeaponSlot]]
*[[isPedChoking]]
*[[isPedDoingGangDriveby]]
*[[isPedDoingTask]]
*[[isPedDucked]]
*[[isPedFrozen]]
*[[isPedHeadless]]
*[[isPedInVehicle]]
*[[isPedInWater]]
*[[isPedOnFire]]
*[[isPedOnGround]]
*[[setPedAimTarget]]
*[[setPedAnimation]]
*[[setPedCameraRotation]]
*[[setPedCanBeKnockedOffBike]]
*[[setPedControlState]]
*[[setPedDoingGangDriveby]]
*[[setPedFrozen]]
*[[setPedHeadless]]
*[[setPedLookAt]]
*[[setPedOnFire]]
*[[setPedRotation]]
*[[setPedSkin]]
*[[setPedVoice]]
*[[setPedWeaponSlot]]
}}

SetPlayerMoney

2009-09-22T22:06:14Z

R3mp:

__NOTOC__
{{Server client function}}
Sets a player's money to a certain value, regardless of current player money. It should be noted that setting negative values does not work and in fact gives the player large amounts of money.

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

===Required Arguments===
*'''thePlayer:''' Which player to set the money of
*'''amount:''' A whole integer specifying the new amount of money the player will have
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool setPlayerMoney (int amount ) </syntaxhighlight>

===Required Arguments===
*'''amount:''' A whole integer specifying the new amount of money the local player will have
</section>

===Returns===
Returns ''true'' if the money was added, or ''false'' if invalid parameters were passed.

==Example==
'''Example 1:''' This example sets the player's money to the desired amount when he types "setcash" in console.
<syntaxhighlight lang="lua">
function setCash ( thePlayer, command, amount ) -- when the setcash function is called
setPlayerMoney ( thePlayer, tonumber(amount) ) -- change player's money to the desired amount
end
addCommandHandler ( "setcash", setCash ) -- add a command handler for setcash
</syntaxhighlight>
'''Example 2:''' This gives all players the amount of 1337 money when "leet" is typed in console.
<syntaxhighlight lang="lua">
function leetmoney()
setPlayerMoney( getRootElement(), 1337 )
end
addCommandHandler("leet", leetmoney)
</syntaxhighlight>

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

OnClientColShapeLeave

2009-08-25T02:27:25Z

R3mp:

__NOTOC__
{{Client event}}
This event triggers whenever an element (a player, a vehicle...) leaves a collision shape.

==Parameters==
<syntaxhighlight lang="lua">
element theElement, bool matchingDimension
</syntaxhighlight>
*'''theElement:''' the element that left the colshape.
*'''matchingDimension:''' ''true'' if theElement is in the same dimension as the colshape, ''false'' otherwise.

==Source==
The source of this event is the colshape that the element left.

==Example==
This example outputs "Out." to the chatbox whenever a local user leaves a collision shape.
<syntaxhighlight lang="lua">
function onClientColShapeLeave( theElement, matchingDimension )
if ( theElement == getLocalPlayer() ) then -- Checks whether the leaving element is the local player
outputChatBox( "Out." ) --Outputs.
end
end
addEventHandler("onClientColShapeLeave",getRootElement(),onClientColShapeLeave)
</syntaxhighlight>

==See Also==
===Client colshape events===
{{Client_colshape_events}}
===Client event functions===
{{Client_event_functions}}

OnClientColShapeHit

2009-08-25T02:26:58Z

R3mp:

{{Client event}}
__NOTOC__
This event triggers whenever an element (a player, a vehicle...) enters a collision shape.

==Parameters==
<syntaxhighlight lang="lua">
element theElement, bool matchingDimension
</syntaxhighlight>
*'''theElement:''' the element that entered the colshape.
*'''matchingDimension:''' ''true'' if theElement is in the same dimension as the colshape, ''false'' otherwise.

==Source==
The source of this event is the colshape that was hit.

==Example==
This example outputs "In." to the chatbox whenever a local user enters a collision shape.
<syntaxhighlight lang="lua">
function onClientColShapeHit( theElement, matchingDimension )
if ( theElement == getLocalPlayer() ) then -- Checks whether the entering element is the local player
outputChatBox( "In." ) --Outputs.
end
end
addEventHandler("onClientColShapeHit",getRootElement(),onClientColShapeHit)
</syntaxhighlight>

==See Also==
===Client colshape events===
{{Client_colshape_events}}
===Client event functions===
{{Client_event_functions}}