Multi Theft Auto: Wiki - User contributions [en]

OnClientKey

2015-03-01T19:16:28Z

FabioGNR: Added info about cancelling 'escape' key.

{{Client event}}
__NOTOC__
This event triggers whenever the user presses a button on their keyboard.
This event can also be used to see if the client scrolls his mousewheel.

==Parameters==
<syntaxhighlight lang="lua">string button, bool pressOrRelease
</syntaxhighlight>
* '''button''': This refers the button pressed. see [[Key names]] for list of keys string
* '''pressOrRelease''': This refers to whether they were pressing or releasing the key, true when pressing, false when releasing.

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

==Cancel effect==
{{New items|5620|1.4|
If this event is [[Event system#Canceling|canceled]], then all GTA and MTA binds, bound to the canceled key, won't be triggered.
'''Note:''' the escape key can only be cancelled once. If a user presses the escape key twice in a row the main menu will still open.
}}

==Example==
This example will say in chatbox every time the user presses down a a key.
<syntaxhighlight lang="lua">
function playerPressedKey(button, press)
if (press) then -- Only output when they press it down
outputChatBox("You pressed the "..button.." key!")
end
end
addEventHandler("onClientKey", root, playerPressedKey)
</syntaxhighlight>

This example outputs if the client moves his mousewheel.
<syntaxhighlight lang="lua">
addEventHandler( "onClientKey", root, function(button,press)
-- Since mouse_wheel_up and mouse_wheel_down cant return a release, we dont have to check the press.
if button == "mouse_wheel_up" or button == "mouse_wheel_down" then
outputDebugString( button .. " moved." )
return true
end
return false
end )
</syntaxhighlight>

==See Also==
===GUI events===
{{GUI_events}}
===Client event functions===
{{Client_event_functions}}

GetAllElementData

2014-08-20T16:00:50Z

FabioGNR: fixed example

__NOTOC__
{{Server function}}

Returns a table of all element data of an element.

==Syntax==
<syntaxhighlight lang="lua">
table getAllElementData ( element theElement )
</syntaxhighlight>
{{OOP|This function is also a static function underneath the Element class.|[[element]]:getAllData||}}

===Required Arguments===
*'''theElement:''' the element you want to get the element data of.

===Returns===
If successful, returns a table with as keys the names of the element data and as values the corresponding element data values. Returns ''false'' in case of failure.

==Example==
This example script creates a new console command that displays all element data that is currently set on the player who enters the command.
<syntaxhighlight lang="lua">
function getMyData ( thePlayer, command )
local data = getAllElementData ( thePlayer ) -- get all the element data of the player who entered the command
for k, v in pairs ( data ) do -- loop through the table that was returned
outputConsole ( k .. ": " .. tostring ( v ) ) -- print the name (k) and value (v) of each element data, we need to make the value a string, since it can be of any data type
end
end
addCommandHandler ( "elemdata", getMyData )
</syntaxhighlight>

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

AddEventHandler

2014-08-16T15:29:24Z

FabioGNR: fixed example

__NOTOC__
{{Server client function}}
{{Note_box|It is strongly advised that you do not use the same name for your handler function as the event name, as this can lead to confusion if multiple handler functions are used.}}
This function will add an [[event]] handler. An event handler is a function that will be called when the event it's attached to is triggered. See [[event system]] for more information on how the event system works.

Event handlers are functions that are called when a particular event happens. Each event specifies a specific set of variables that are passed to the event handler and can be read by your function. The following global variables are available for use in handler functions:
*'''source''': the element that triggered the event
*'''this''': the element that the event handler is attached to

*'''client''': the client that triggered the event using [[triggerServerEvent]]. Not set if the event was not triggered from a client.
{{New_feature|3|1.0|
*'''eventName''': the name of the event which triggered the handler function.
}}

It is important to remember that events pass up and down the [[element tree]]. An event triggered on the root element is triggered on every element in the tree. An event triggered on any other element is triggered on its ancestors (its parent element and its parent's parent etc) and its children, grandchildren and great-grandchildren. You can use the ''getPropagated'' argument to specify if you wish your handler to receive events that have propagated up or down the tree.

The order in which event handlers are triggered is undefined, you should not rely on one event handler being executed before another.
{{Note|See [[Script security]] for tips on preventing cheaters when using events and element data}}
==Syntax==
<syntaxhighlight lang="lua">
bool addEventHandler ( string eventName, element attachedTo, function handlerFunction, [ bool getPropagated = true, string priority = "normal" ] )
</syntaxhighlight>

===Required Arguments===
*'''eventName:''' The name of the [[event]] you want to attach the handler function to.
*'''attachedTo:''' The [[element]] you wish to attach the handler to. The handler will only be called when the event it is attached to is triggered for this element, or one of its children. Often, this can be the root element (meaning the handler will be called when the event is triggered for ''any'' element).
*'''handlerFunction:''' The handler function you wish to call when the event is triggered. This function will be passed all of the event's parameters as arguments, but it isn't required that it takes all of them.

===Optional Arguments===
*'''getPropagated:''' A boolean representing whether the handler will be triggered if the event was propagated down or up the [[element tree]] (starting from the source), and not triggered directly on attachedTo (that is, handlers attached with this argument set to ''false'' will only be triggered if ''source == this'').
{{New_feature|3.0131|1.3.1|
*'''priority :''' A string representing the trigger order priority relative to other event handlers of the same name. Possible values are:
**'''"high"'''
**'''"normal"'''
**'''"low"'''
''It is also possible to add finer priority control by appending a positive or negative number to the priority string. For example (in priority order for reference): "high+4" "high" "high-1" "normal-6" "normal-7" "low+1" "low" "low-1"''
'''Important note:''' Anything bound to a specific element will be run before other handlers that are bound to something higher in the element tree (like root) This means that "high+10" bound to root won't trigger before "normal" bound directly to an element.
}}

===Returns===
Returns ''true'' if the event handler was attached successfully. Returns ''false'' if the specified event could not be found or any parameters were invalid.

==Example==
<section name="Server" class="server" show="true">
This serverside example sends a message to everyone in the server when a player spawns.
<syntaxhighlight lang="lua">
-- get the root element
rootElement = getRootElement()
-- define our handler function
function onPlayerSpawnHandler ( )
-- get the player's name, source is the player because he was spawned
local playerName = getPlayerName( source )
-- output in the chat box that they've spawned
outputChatBox ( playerName .. " has spawned!" )
end

addEventHandler( "onPlayerSpawn", rootElement, onPlayerSpawnHandler )
</syntaxhighlight>
</section>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.03795|Added priority argument}}

==See Also==
{{Event_functions}}
[[ru:addEventHandler]]

BitExtract

2013-09-05T18:00:21Z

FabioGNR: added small example

{{Server client function}}
{{Needs_Example}}
__NOTOC__
{{New feature/item|3.0132|1.3.2|5340|
This function returns the unsigned number formed by the bits field to field + width - 1 (range: 0-31).
}}

==Syntax==
<syntaxhighlight lang="lua">
uint bitExtract ( uint var, int field, [int width = 1] )
</syntaxhighlight>

===Required arguments===
*'''var:''' The value
*'''field:''' The field number
*'''width:''' Number of bits to extract

===Returns===
Returns the extracted value/bit sequence.

==Example==
<syntaxhighlight lang="lua">
function getColorAlpha(color)
return bitExtract(color,24,8) -- return bits 24-32 ( the alpha, http://en.wikipedia.org/wiki/RGBA_color_space )
end
</syntaxhighlight>

==See Also==
{{Bit_functions}}

Requested Functions and Events

2013-08-20T17:40:40Z

FabioGNR: /* Server-side */

==Server-side==

Event like onServerTick wich is run very often. Like the clientside onClientRender. This could be useful for constat checking wich must be done under 50ms (lower than timers can handle).

----
onVehicleCreated or an equivalent... shouldn't be too hard? -Robhol (14:15 Jul 6, 08)
:If we did it, it'd be onElementCreated - what do you want this for? [[User:EAi|eAi]] 08:58, 7 July 2008 (CDT)
::onElementCreated is a good idea - it could be used for lots of things. Also, how about onVehicleDrown or whatever? that is, when a vehicle hits deep water. Checking for collisions and stuff is very awkward, and client-side only, and has to be checked constantly.. -Robhol (17:31 Jul 9 08)
:::I second that. It would be useful if you use like me element data like the fuel amount or other stuff. And an event like this would help me to setup those element data, when a car spawns. Otherwise I would either have to edit every car spawn script I use or do a post-setup when someone is entering the car.. [[User:MaddDogg14]] (04:34 Apr 4, 10 (CEST))
::::i definetly agree, onElementCreated would be VERY useful for utility/librares scripts, but i think this should be limited by ACL, because "evil" scripts could abuse this othervise -Karlis (9:10 Apr 5, 10)

----

I ask for a function that detects if a ped is on floor, eg. '''isPedOnFloor(ped thePed)''', thanks. --<span style="font-family:Courier New, Courier, monospace">[[User:Shadd|Shadd]]</span><sub>([[User_talk:Shadd|In caso di emergenza rompere le scatole]])</sub> 11:29, 15 June 2008 (CDT)
: [[isPedOnGround]]? [[User:Awwu|Awwu]] 12:58, 15 June 2008 (CDT)
::I need to know if the player has its back touching the ground, not if it's simply "on ground". --<span style="font-family:Courier New, Courier, monospace">[[User:Shadd|Shadd]]</span><sub>([[User_talk:Shadd|In caso di emergenza rompere le scatole]])</sub> 14:16, 16 June 2008 (CDT)
:::Check what task the player has, they should have TASK_COMPLEX_FALL_AND_GET_UP or TASK_COMPLEX_FALL_AND_STAY_DOWN... [[User:EAi|eAi]] 19:12, 16 June 2008 (CDT)
::::Thanks. What task does player have after being hitten by a melee attack that cause it to fall down? Would "TASK_SIMPLE_BE_KICKED_ON_GROUND" and "TASK_SIMPLE_GET_UP" work? --<span style="font-family:Courier New, Courier, monospace">[[User:Shadd|Shadd]]</span><sub>([[User_talk:Shadd|In caso di emergenza rompere le scatole]])</sub> 09:35, 17 June 2008 (CDT)
:::::Try it, I'm not entirely sure. You should be able to produce some code to show the player's current tasks very easily... [[User:EAi|eAi]] 19:20, 17 June 2008 (CDT)
::::::My goal is to edit the standard damage of the attacks, in this case i have to know when player is on ground to cause higher damage. However it doesn't seem to work, when i hit the player it simply gets up without animation with no damage. --<span style="font-family:Courier New, Courier, monospace">[[User:Shadd|Shadd]]</span><sub>([[User_talk:Shadd|In caso di emergenza rompere le scatole]])</sub> 19:10, 19 June 2008 (CDT)

----

It may looks strange and useless (waste of time?) but I think that it could be a awesome feature. Having a web browser.
Like: http://www.youtube.com/watch?v=wT1UR6qEgdg
http://princeofcode.com/awesomium.php
:definetly useles and waste of time, suporting xfire enought. -karlis
::Really Karlis, who asked you bro. It could be very useful, actually. For example, creating dynamic billboards. Instead of changing the TXD, they could set up a browser object over the billboard. That way they can also set up a timer to change the image, etc. [[User:JacobS|JacobS]] 20:08, 1 August 2010 (UTC)

----

There could be something like createBrowser( float x, float y, float z, [float rx, float ry, float rz, float width, float high, string url, bool locked] )
locked parameter: false = navigation bar present, true = no navigation bar
toggleBrowserFullsceenMode(browser theBrowser, bool tog, [bool smooth])
smooth parameter: If set to true the browser will smoothly move from his ingame position to the fullscreen position
toggleBrowserBackground(browser theBrowser, bool tog)
Set the browser background transparent.

----

Security: Disable file downloads, disable popups (disable flash, javascript and any other protocols than http and https [no mailto and stuff...]?)

----

Should be a Client and server function. --[[User:Masterofquebec|Masterofquebec]] 00:10, 15 October 2009 (UTC)

----

Support of tooltips from CEGUI would be cool. I saw a property for that, but it didn't work for me. [[User:MaddDogg14]] (04:36 Apr 4, 10 (CEST))

----

I request a function that gets all clothes from a ped, just like getPedClothes but for all bodyparts. With this function it would be more ease to save clothes to database.
:That's so easy to do yourself that it's barely worth adding. Just loop all the indexes 0-17 and save them to a table. [[User:Awwu|Awwu]] 19:26, 17 April 2010 (UTC)

----

[[setProjectileTarget]] for setting a projectile to target a specific entity. I am trying to create a Battlefield Bad Company type of gamemode and in that game, you can plant a 'tracer'. Any rocket fired (if the tracer is on screen) will seek the tracer. [[User:LeetWoovie|LeetWoovie]] 05:01, 19 April 2010 (UTC)

----

(marcol07, June the 25th, 2010) I would like to have some function to create light source as element or sth like createFire, for example createLight(x,y,z,xrot,yrot,zrot,f,r,g,b) where "f" is an angle of lightning. or it is possible with some model or function? It would be good to create for example fog lamps or classic street lamps

----

moveElement available for markers, objects, pedestrians and players or maybe more if you can do. [[User:Socialz|Socialz]] 13:10, 1 January 2012 (CET)

==Client-Side==

Event "onClientVehicleFire", which would be triggered when a vehicle shoots.
:See [[OnVehicleWeaponFire]] --[[User:X86dev|X86dev]] 12:11, 19 April 2013 (UTC)
----

Adding possibility to toggle radio hud label by '''showHudComponent''' -karlis

----

Pickup events clientside please, onClientPickupHit onClientPickupUse.

----

Would it be possible to add a color arg to guiGridListSetItemText()? Im trying to get each item colored differently in one list. Thanks, ABEL

----

I need a function which could get current target of hydra or a HS rocket launcher, like when someone press space and targets a element, to get what element is it for calculating distance from it. '''getPlayerOccupiedVehicleTarget''' or '''getPlayerHSTarget'''.
Thanks in advance -Nidza a.k.a. CodeMaster 2:26 PM 19th June 2008.

----

It'd be useful to have something to disable elements of the default hud (weapon display, health display, armor, radar, etcetera) so that you can create your own HUDs. Something like '''setHudElement(element name, toggle)'''.

[[User:Lord Xalphox|Lord Xalphox]] 19:32, 22 March 2009 (CET)
:[[showPlayerHudComponent]]? [[User:Awwu|Awwu]] 19:43, 22 March 2009 (CET)

----

I'd like to have a function that sets the chatbox input line text. Then I could script my own chat history function (that inserts the last sent text into the input line again by pressing arrow up) (which samp has since 0.2 btw) since nobody builds it into the client. [[User:NeonBlack|NeonBlack]] 12:03, 4 July 2009 (CEST) PS.: samp also supports cut, copy and paste :P
----

A function setElementMatrix, doing the exact opposite of getElementMatrix would be much appreciated. --[[User:Kayl|Kayl]] 15:21, 13 November 2009 (UTC)

----

Functions like setTrainPosition(train,track,pos) and track,pos getTrainPosition(train) would be great in order to allow more script side control of trains.
The track argument would be an index of the track number (currently there are around 4 tracks handled, including 1 incompletely defined).
The position would be a float between 0 and 1 (or however you guys handle it) telling where on the track the train currently is.
It would be great if those functions could be available client and server side. --[[User:Kayl|Kayl]] 12:58, 23 November 2009 (UTC)

----

need this function client and server side '''movePlayerHudComponent(string component, float x, float y)''' --[[User:SuatEyrice|SuatEyrice]] 00:18, 26 February 2010 (UTC)

----

'''(marcol07, June the 27th, 2010)''' I would be so happy to have fuction to set Analog control of player sth like '''getAnalogControlState(string controlName)''' but inverted to '''setAnalogControlState(string controlName, float state)'''

----
OnPedDamage (serverside) event. There is OnClientPedDamage, but it's clientside. [[User:damage22|damage22]]

----
'''setRadioVolume(element thePlayer, int volume)''', to create GUI volume control, turn off the radio without changing the station, etc. [[User:JacobS|JacobS]] 14:47, 29 July 2010 (UTC)
----
'''setVehicleHydraulics(element theVehicle, bool state)''', to force hydraulics to be up (true) or down (false)
----
'''createFire(x, y, z, theSize, dimension)''', just like [[createFire]], only with the option to enter a dimension for the fire to appear in
----
'''setGunshotsEnabled(bool enabled)''', '''getGunshotsEnabled()''' and '''createGunshot(x,y,z,radius)''' - to enable/disable the game's gunshot ambience, and to create gunshots at specific locations with radii that it is audible in [[User:JacobS.|JacobS.]] 19:28, 11 September 2010 (MDT)

----
onClick should pass the name of the clicked SUBobject too (eg: vehicle parts, bone names etc.)--[[User:Lcaseidefensis|Lcaseidefensis]] 16:48, 21 May 2012 (UTC)

----
something to open/close doors like in singleplayer (teleports are a bit unrealistic)

DxDrawImage

2013-08-02T12:08:10Z

FabioGNR: /* Syntax */

__NOTOC__
{{Client function}}

Draws an image on the screen for a single frame. In order for the image to stay visible continuously, you need to call this function with the same parameters on each frame update (see [[onClientRender]]).<br/>
Image files should ideally have dimensions that are a power of two, to prevent possible blurring.<br/>
<b>Power of two: 2px, 4px, 8px, 16px, 32px, 64px, 128px, 256px, 512px, 1024px...</b>
{{Note|To help prevent edge artifacts when drawing textures, set '''textureEdge''' to '''"clamp"''' when calling [[dxCreateTexture]]}}
==Syntax==
<syntaxhighlight lang="lua">
bool dxDrawImage ( float posX, float posY, float width, float height, mixed image [, float rotation = 0, float rotationCenterOffsetX = 0,
float rotationCenterOffsetY = 0, int color = tocolor(255,255,255), bool postGUI = false ] )
</syntaxhighlight>

===Required Arguments===
*'''posX:''' the absolute X coordinate of the top left corner of the image
*'''posY:''' the absolute Y coordinate of the top left corner of the image
*'''width:''' the absolute width of the image
*'''height:''' the absolute height of the image
*'''image:''' Either a [[material]] element or a [[filepath]] of the image which is going to be drawn. (.dds images are also supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring.

===Optional Arguments===
*'''rotation:''' the rotation, in degrees for the image.
*'''rotationCenterOffsetX:''' the absolute X offset from the image center for which to rotate the image from.
*'''rotationCenterOffsetY:''' the absolute Y offset from the image center for which to rotate the image from.
*'''color:''' Tints the image with a value produced by [[tocolor]] or hexadecimal number in format: 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
*'''postgui :''' A bool representing whether the image should be drawn on top of or behind any ingame GUI (rendered by CEGUI).

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

==Example==
<section name="Client" class="client" show="true">
Example of a pendulum swinging from the top of the screen, made using dxDrawImage.
<syntaxhighlight lang="lua">
local screenWidth,screenHeight = guiGetScreenSize() -- Get screen resolution.

function renderDisplay ( )
local seconds = getTickCount() / 1000
local angle = math.sin(seconds) * 80
-- This will draw the graphic file 'arrow.png' at the top middle of the screen
-- using the size of 100 pixels wide, and 240 pixels high.
-- The center of rotation is at the top of the image.
dxDrawImage ( screenWidth/2 - 50, 0, 100, 240, 'arrow.png', angle, 0, -120 )
end

function HandleTheRendering ( )
addEventHandler("onClientRender", getRootElement(), renderDisplay) -- Keep everything visible with onClientRender.
end
addEventHandler("onClientResourceStart",resourceRoot, HandleTheRendering)
</syntaxhighlight>
</section>

==See Also==
{{Drawing_functions}}

Damage Types

2013-01-11T16:57:56Z

FabioGNR: fixed table

The following death reasons are used by event like onPlayerWasted for the killerWeapon argument to describe the reason, why a ped died.<br>
When a player was shot by a weapon, the respective weapon ID is the death reason ID. The weapon IDs can be found [[Weapons|here]].
<br>
<br>
:{|class="wikitable sortable" style="width: auto; table-layout: fixed;"
|-
!ID
! class="unsortable" |Death reason
! class="unsortable" |Additional info
|-
!19
|Rocket
|Actual death reason / weapon ID when dying from a rocket launcher
|-
!37
|Burnt
|This is used by a death by fire, even when the fire is created by a rocket explosion or a molotov
|-
!49
|Rammed
|
|-
!50
|Ranover
|This is also called when dying because of helicopter blades
|-
!51
|Explosion
|This may sometimes also be used at an indirect death through an exploding rocket
|-
!52
|Driveby
|This is NOT used for a driveby kill with e.g. the 'realdriveby' resource
|-
!53
|Drowned
|
|-
!54
|Fall
|
|-
!55
|Unknown
|No known information about this death reason
|-
!56
|Melee
|Seems to be never called (?); for an actual melee death, the fist weapon ID (0) is used (see [[Weapons|here]])
|-
!57
|Weapon
|Seems to be never called (?)
|-
!59
|Tank Grenade
|
|-
!63
|Blown
|Actual death reason when dying in a vehicle explosion
|-
|}

Death Reasons in lua table
<syntaxhighlight lang="lua">
local deathReasons = {
[19] = "Rocket",
[37] = "Burnt",
[49] = "Rammed",
[50] = "Ranover/Helicopter Blades",
[51] = "Explosion",
[52] = "Driveby",
[53] = "Drowned",
[54] = "Fall",
[55] = "Unkown",
[56] = "Meele",
[57] = "Weapon",
[59] = "Tank Grenade",
[63] = "Blown"
}
</syntaxhighlight>

[[ru:Death Reasons]]
[[de:Todesgründe]]

[[Category:ID Lists]]

RestoreAllWorldModels

2012-11-10T20:21:58Z

FabioGNR: /* Returns */

__NOTOC__
{{Server client function|New items}}
This function allows restoring of all world objects,which were removed with [[RemoveWorldModel]].

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

==Returns==
Returns ''true'' if the world objects were restored, ''false'' otherwise.

==Requirements==
{{Requirements|1.2.0-9.03618|1.2.0-9.03618|}}

==Example==
This example restore all world objects.
<syntaxhighlight lang="lua">
addCommandHandler("restoreallworldobjects",
function()
restoreAllWorldModels()
end
)
</syntaxhighlight>

==See Also==
{{Client_world_functions}}

DownloadFile

2012-09-22T23:34:10Z

FabioGNR: /* Example */

{{Client function}}
__NOTOC__
{{New items|3.0151|1.4|
This function downloads a file from the HTTP server. This can only be used on files on the HTTP server associated with the MTA server and will only download files from within the folder of the resource that is calling it. The '''file''' should also be included in meta.xml with the '''download''' attribute set to "false", see [[meta.xml]] for more details. If the file has been previously downloaded and the CRC matches, the file will not be downloaded again but [[onClientFileDownloadComplete]] will still run.
}}

==Syntax==
<syntaxhighlight lang="lua">
bool downloadFile ( string fileName )
</syntaxhighlight>

===Required Arguments===
* '''fileName''': A string referencing the name of the file to download

===Returns===
Returns ''true'' if file download has been queued, ''false'' otherwise.

==Example==
'''Example 1:''' This client side event downloads a file when the current resource has started.
<syntaxhighlight lang="lua">
-- the function is called on resource start
function onThisResourceStart ( )
downloadFile ( "test.txt" )
end
addEventHandler ( "onClientResourceStart", resourceRoot, onThisResourceStart )
</syntaxhighlight>

==See Also==
{{Client_utility_functions}}

Control names

2012-09-02T15:23:38Z

FabioGNR: /* GTA control list */

This page lists all the control names. These can be used as key arguments by the console commands ''bind'' and ''unbind'' as well as the script functions [[bindKey]], [[unbindKey]] etc.

==GTA control list==
<div style="border:3px solid green;margin-bottom:3px;"><div style="float:right;padding-right:5px;font-weight:bold;">ON FOOT</div>
* '''fire''' Fire a player's weapon
* '''next_weapon''' Switch to the next weapon
* '''previous_weapon''' Switch to the previous weapon
* '''forwards''' Move forwards
* '''backwards''' Move backwards
* '''left''' Move left
* '''right''' Move right
* '''zoom_in''' Zoom targeted weapon in (sniper/rocket launcher/camera etc)
* '''zoom_out''' Zoom targeted weapon out
* '''change_camera''' Change camera mode
* '''jump''' Make the player jump
* '''sprint''' Make the player sprint
* '''look_behind''' Make the player look behind (and allow the player to see behind them)
* '''crouch''' Make the player crouch/duck
* '''action''' Show the stats menu
* '''walk''' Make the player move slowly/quietly
* '''aim_weapon''' Aim the player's current weapon (if possible)
* '''conversation_yes''' Answer yes to a question
* '''conversation_no''' Answer no to a question
* '''group_control_forwards''' Make the group you are controlling move forwards
* '''group_control_back''' Make the group you are controlling move backwards
* '''enter_exit''' Make the player enter a vehicle. Also used for alternative fighting styles.
</div>
<div style="border:3px solid red;margin-bottom:3px;"><div style="float:right;padding-right:5px;font-weight:bold;">IN VEHICLE</div>
* '''vehicle_fire''' Fire the player's vehicle's primary weapon (e.g. hunter's missiles) or shoot with driveby
* '''vehicle_secondary_fire''' Fire the player's vehicle's secondary weapon (e.g. hunter's minigun)
* '''vehicle_left''' Make the player's vehicle turn left
* '''vehicle_right''' Make the player's vehicle turn right
* '''steer_forward''' Make the player's vehicle turn down (lean forwards for helicopters/planes)
* '''steer_back''' Make the player's vehicle turn up (lean backwards for helicopters/planes)
* '''accelerate''' Make the player's vehicle accelerate
* '''brake_reverse''' Make the player's vehicle brake (slow down) and if stationary reverse
* '''radio_next''' Change to the next radio station
* '''radio_previous''' Change to the previous radio station
* '''radio_user_track_skip''' Skip the current track being played on the custom radio station
* '''horn''' Play the horn of the player's vehicle (if the vehicle has a horn) and can trigger the siren on emergency vehicles
* '''sub_mission''' Start a submission if one is avaliable (e.g. taxi missions)
* '''handbrake''' Apply the handbrake on the player's vehicle
* '''vehicle_look_left''' Look to the left
* '''vehicle_look_right''' Look to the right
* '''vehicle_look_behind''' Look behind
* '''vehicle_mouse_look'''
* '''special_control_left''' Move the some special vehicle component left (e.g. tank's turret)
* '''special_control_right''' Move the some special vehicle component right (e.g. tank's turret)
* '''special_control_down''' Move the some special vehicle component down (e.g. tank's turret)
* '''special_control_up''' Move the some special vehicle component up (e.g. tank's turret)
* '''enter_exit''' Make the player exit a vehicle
</div>

==MTA hard-coded commands==
The following are names of hard-coded MTA commands which do not use bindKey, but can act as bindKey by using them in an [[addCommandHandler]]. Other than that, this control list will '''only''' work with the functions [[toggleControl]] and [[toggleAllControls]]. Please note that [[toggleControl]] can't disable screenshot.

<div style="border:3px solid blue;margin-bottom:3px;"><div
style="float:right;padding-right:5px;font-weight:bold;">MTA COMMANDS</div>
* '''enter_passenger''' Enter's the closest vehicle as passenger
* '''playerlist''' Toggles the player-list showing
* '''screenshot''' Takes a screenshot
* '''chatbox''' Opens the chatbox for input
* '''radar''' Toggles the radar-map showing
* '''radar_zoom_in''' Zooms in on the radar-map
* '''radar_zoom_out''' Zooms out on the radar-map
* '''radar_move_north''' Moves north on the radar-map
* '''radar_move_south''' Moves south on the radar-map
* '''radar_move_east''' Moves east on the radar-map
* '''radar_move_west''' Moves west on the radar-map
* '''radar_attach''' Attaches the view to the local-player on the radar-map
</div>
[[Category:Scripting Concepts]]

ToggleControl

2012-08-19T17:05:12Z

FabioGNR: /* Example */

__NOTOC__
{{Server client function}}
{{Needs Checking|By enabling a control all bindings belonging to it seem to be deleted. (tested clientside) --[[User:NeonBlack|NeonBlack]] 16:48, 28 August 2009 (UTC)}}
Enables or disables the use of a GTA control for a specific player.

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">bool toggleControl ( player thePlayer, string control, bool enabled ) </syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The player you wish to toggle the control ability of.
*'''control:''' The control that you want to toggle the ability of. See [[control names]] for a list of possible controls.
*'''enable:''' A boolean value representing whether or not the key will be usable or not.
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">bool toggleControl ( string control, bool enabled ) </syntaxhighlight>

===Required Arguments===
*'''control:''' The control that you want to toggle the ability of. See [[control names]] for a list of possible controls.
*'''enable:''' A boolean value representing whether or not the key will be usable or not.
</section>

==Returns==
This function ''true'' if the control was set successfully, ''false'' otherwise.

==Example==
<section name="Example 1" class="server" show="true">
This function will disable the use of the vehicle secondary-fire key for anyone in a Hydra, consequently removing the ability to fire rockets.
<syntaxhighlight lang="lua">
function disableFireForHydra ( theVehicle, seat, jacked )
if ( getElementModel ( theVehicle ) == 520 ) then -- if they entered a hydra
toggleControl ( source, "vehicle_secondary_fire", false ) -- disable their fire key
else -- if they entered another vehicle
toggleControl ( source, "vehicle_secondary_fire", true ) -- enable their fire key
end
end
addEventHandler ( "onPlayerVehicleEnter", getRootElement(), disableFireForHydra )
</syntaxhighlight>
</section>
<section name="Example 2" class="client" show="true">
This function will disable the use of the vehicle secondary-fire key for anyone in a Hydra, consequently removing the ability to fire rockets.
<syntaxhighlight lang="lua">
function disableFireForHydra ( theVehicle, seat )
if ( getElementModel ( theVehicle ) == 520 ) then -- if they entered a hydra
toggleControl ( "vehicle_secondary_fire", false ) -- disable their fire key
else -- if they entered another vehicle
toggleControl ( "vehicle_secondary_fire", true ) -- enable their fire key
end
end
addEventHandler ( "onClientPlayerVehicleEnter", getLocalPlayer(), disableFireForHydra )
</syntaxhighlight>
</section>

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

ToggleControl

2012-08-19T17:05:01Z

FabioGNR: /* Example */

__NOTOC__
{{Server client function}}
{{Needs Checking|By enabling a control all bindings belonging to it seem to be deleted. (tested clientside) --[[User:NeonBlack|NeonBlack]] 16:48, 28 August 2009 (UTC)}}
Enables or disables the use of a GTA control for a specific player.

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">bool toggleControl ( player thePlayer, string control, bool enabled ) </syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The player you wish to toggle the control ability of.
*'''control:''' The control that you want to toggle the ability of. See [[control names]] for a list of possible controls.
*'''enable:''' A boolean value representing whether or not the key will be usable or not.
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">bool toggleControl ( string control, bool enabled ) </syntaxhighlight>

===Required Arguments===
*'''control:''' The control that you want to toggle the ability of. See [[control names]] for a list of possible controls.
*'''enable:''' A boolean value representing whether or not the key will be usable or not.
</section>

==Returns==
This function ''true'' if the control was set successfully, ''false'' otherwise.

==Example==
<section name="Example 1" class="server" show="true">
This function will disable the use of the vehicle secondary-fire key for anyone in a Hydra, consequently removing the ability to fire rockets.
<syntaxhighlight lang="lua">
function disableFireForHydra ( theVehicle, seat, jacked )
if ( getElementModel ( theVehicle ) == 520 ) then -- if they entered a hydra
toggleControl ( source, "vehicle_secondary_fire", false ) -- disable their fire key
else -- if they entered another vehicle
toggleControl ( source, "vehicle_secondary_fire", true ) -- enable their fire key
end
end
addEventHandler ( "onPlayerVehicleEnter", getRootElement(), disableFireForHydra )
</syntaxhighlight>
''Note: The same can be achieved by using [[setVehicleGunsEnabled]]''.
</section>
<section name="Example 2" class="client" show="true">
This function will disable the use of the vehicle secondary-fire key for anyone in a Hydra, consequently removing the ability to fire rockets.
<syntaxhighlight lang="lua">
function disableFireForHydra ( theVehicle, seat )
if ( getElementModel ( theVehicle ) == 520 ) then -- if they entered a hydra
toggleControl ( "vehicle_secondary_fire", false ) -- disable their fire key
else -- if they entered another vehicle
toggleControl ( "vehicle_secondary_fire", true ) -- enable their fire key
end
end
addEventHandler ( "onClientPlayerVehicleEnter", getLocalPlayer(), disableFireForHydra )
</syntaxhighlight>
</section>

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

OnClientProjectileCreation

2012-05-17T22:45:36Z

FabioGNR: /* Example */ fixed some grammar

__NOTOC__
{{Client event}}
This event is triggered when a [[projectile]] is created.

==Parameters==
<syntaxhighlight lang="lua">
element creator
</syntaxhighlight>

==Source==
The [[event system#Event source|source]] of this event is the [[projectile]] that was created.

==Example==
This will output a chatbox message when someone creates a projectile.
<syntaxhighlight lang="lua">
function projectileCreation()
outputChatBox("A projectile was created!")
end
addEventHandler("onClientProjectileCreation", getRootElement(), projectileCreation)
</syntaxhighlight>

This will punish a player for throwing a teargas grenade. When he throws it he keeps getting warped to the location where the teargas got created, and also the teargas keeps getting warped to it. This will result in +/-60hp loss for the creator.
<syntaxhighlight lang="lua">
function punishSatchelUsersz ( creator )
local zeType = getProjectileType( source )
if zeType == 17 then
local zePlayerName = getPlayerName ( creator )
outputChatBox ( zePlayerName.." is a noob teargas user! But he got punished for it don't worry." )
local x, y, z = getElementPosition ( source ) --Getting the position from the projectile creator
setTimer ( setElementPosition, 50, 250, source, x, y, z-0.5 )
setTimer ( setElementPosition, 50, 250, creator, x, y, z-0.5 )
end
end
addEventHandler( "onClientProjectileCreation", getRootElement(), punishSatchelUsersz )
</syntaxhighlight>

This will disable people from creating flares. ( Dropped by Hydras )
<syntaxhighlight lang="lua">
function disableFlares ( )
local projType = getProjectileType( source ) -- get the projectile type

if projType == 58 then -- if the projectile is a flare

destroyElement(source) -- notice cancelEvent() does not work, so this destroys the projectile element after it was created.

end

end

addEventHandler( "onClientProjectileCreation", getRootElement(), disableFlares ) -- when a projectile gets created call disableFlares.
</syntaxhighlight>

==See Also==
===Client projectile events===
{{Client_projectile_events}}

OnClientProjectileCreation

2012-05-17T22:18:13Z

FabioGNR: /* Example */

__NOTOC__
{{Client event}}
This event is triggered when a [[projectile]] is created.

==Parameters==
<syntaxhighlight lang="lua">
element creator
</syntaxhighlight>

==Source==
The [[event system#Event source|source]] of this event is the [[projectile]] that was created.

==Example==
This will output a chatbox message when someone creates a projectile.
<syntaxhighlight lang="lua">
function projectileCreation()
outputChatBox("A projectile was created!")
end
addEventHandler("onClientProjectileCreation", getRootElement(), projectileCreation)
</syntaxhighlight>

This will punish a player for throwing a teargas grenade. When he throws it he keeps getting warped to the location where the teargas got created, and also the teargas keeps getting warped to it. This will result in +/-60hp loss for the creator.
<syntaxhighlight lang="lua">
function punishSatchelUsersz ( creator )
local zeType = getProjectileType( source )
if zeType == 17 then
local zePlayerName = getPlayerName ( creator )
outputChatBox ( zePlayerName.." is a noob teargas user! But he got punished for it don't worry." )
local x, y, z = getElementPosition ( source ) --Getting the position from the projectile creator
setTimer ( setElementPosition, 50, 250, source, x, y, z-0.5 )
setTimer ( setElementPosition, 50, 250, creator, x, y, z-0.5 )
end
end
addEventHandler( "onClientProjectileCreation", getRootElement(), punishSatchelUsersz )
</syntaxhighlight>

This will disable people from creating flares. ( Dropped by hydra's )
<syntaxhighlight lang="lua">
function disableFlares ( )
local projType = getProjectileType( source ) -- get the projectile type

if projType == 58 then -- if the projectile is a flare

destroyElement(source) -- notice cancelEvent() does not work, so this destroys the projectile element after it was created.

end

end

addEventHandler( "onClientProjectileCreation", getRootElement(), disableFlares ) -- when a projectile gets created call disableFlares.
</syntaxhighlight>

==See Also==
===Client projectile events===
{{Client_projectile_events}}

OnClientProjectileCreation

2012-05-17T22:15:12Z

FabioGNR: /* Example */

__NOTOC__
{{Client event}}
This event is triggered when a [[projectile]] is created.

==Parameters==
<syntaxhighlight lang="lua">
element creator
</syntaxhighlight>

==Source==
The [[event system#Event source|source]] of this event is the [[projectile]] that was created.

==Example==
This will output a chatbox message when someone creates a projectile.
<syntaxhighlight lang="lua">
function projectileCreation()
outputChatBox("A projectile was created!")
end
addEventHandler("onClientProjectileCreation", getRootElement(), projectileCreation)
</syntaxhighlight>

This will punish a player for throwing a teargas grenade. When he throws it he keeps getting warped to the location where the teargas got created, and also the teargas keeps getting warped to it. This will result in +/-60hp loss for the creator.
<syntaxhighlight lang="lua">
function punishSatchelUsersz ( creator )
local zeType = getProjectileType( source )
if zeType == 17 then
local zePlayerName = getPlayerName ( creator )
outputChatBox ( zePlayerName.." is a noob teargas user! But he got punished for it don't worry." )
local x, y, z = getElementPosition ( source ) --Getting the position from the projectile creator
setTimer ( setElementPosition, 50, 250, source, x, y, z-0.5 )
setTimer ( setElementPosition, 50, 250, creator, x, y, z-0.5 )
end
end
addEventHandler( "onClientProjectileCreation", getRootElement(), punishSatchelUsersz )
</syntaxhighlight>

This will disable people from creating flares. ( Dropped by hydra's )
<syntaxhighlight lang="lua">
function disableFlares ( creator )
local projType = getProjectileType( source ) -- get the projectile type
if projType == 58 then -- if the projectile is a flare

destroyElement(source) -- notice cancelEvent() does not work, so this destroys the projectile element after it was created.

end

end

addEventHandler( "onClientProjectileCreation", getRootElement(), disableFlares ) -- when a projectile gets created call disableFlares.
</syntaxhighlight>
==See Also==
===Client projectile events===
{{Client_projectile_events}}

OnClientProjectileCreation

2012-05-17T22:15:01Z

FabioGNR: /* Example */

__NOTOC__
{{Client event}}
This event is triggered when a [[projectile]] is created.

==Parameters==
<syntaxhighlight lang="lua">
element creator
</syntaxhighlight>

==Source==
The [[event system#Event source|source]] of this event is the [[projectile]] that was created.

==Example==
This will output a chatbox message when someone creates a projectile.
<syntaxhighlight lang="lua">
function projectileCreation()
outputChatBox("A projectile was created!")
end
addEventHandler("onClientProjectileCreation", getRootElement(), projectileCreation)
</syntaxhighlight>

This will punish a player for throwing a teargas grenade. When he throws it he keeps getting warped to the location where the teargas got created, and also the teargas keeps getting warped to it. This will result in +/-60hp loss for the creator.
<syntaxhighlight lang="lua">
function punishSatchelUsersz ( creator )
local zeType = getProjectileType( source )
if zeType == 17 then
local zePlayerName = getPlayerName ( creator )
outputChatBox ( zePlayerName.." is a noob teargas user! But he got punished for it don't worry." )
local x, y, z = getElementPosition ( source ) --Getting the position from the projectile creator
setTimer ( setElementPosition, 50, 250, source, x, y, z-0.5 )
setTimer ( setElementPosition, 50, 250, creator, x, y, z-0.5 )
end
end
addEventHandler( "onClientProjectileCreation", getRootElement(), punishSatchelUsersz )
</syntaxhighlight>

This will disable people from creating flares. ( Dropped by hydra's )
<syntaxhighlight lang="lua">
function disableFlares ( creator )
local projType = getProjectileType( source ) -- get the projectile type
if projType == 58 then -- if the projectile is a flare

destroyElement(source) -- notice cancelEvent() does not work, so this destroys the projectile element after it was created.

end

end

addEventHandler( "onClientProjectileCreation", getRootElement(), disableFlares ) -- when a projectile gets created call disableFlares.

==See Also==
===Client projectile events===
{{Client_projectile_events}}

Template:Projectiles

2012-05-17T21:53:20Z

FabioGNR: Adding flare from hydra

{| class="wikitable" style="width: auto; text-align: center; table-layout: fixed;"
|-
!ID
!Name/Description
|-
|'''16'''
|Grenade
|-
|'''17'''
|Tear Gas Grenade
|-
|'''18'''
|Molotov
|-
|'''19'''
|Rocket (simple)
|-
|'''20'''
|Rocket (heat seeking)
|-
|'''21'''
|Air Bomb
|-
|'''39'''
|Satchel Charge
|-
|'''58'''
|Flare from hydra
|-
|}

OutputChatBox

2012-05-13T00:56:59Z

FabioGNR: /* Syntax */

{{Server client function}}
{{Note_box|Avoid outputting text to the chatbox that isn't actually chat, as this can be annoying for players. Output information and status messages to the HUD.}}
__NOTOC__
This outputs the specified text string to the chatbox. It can be specified as a message to certain player(s) or all players.

It can optionally allow you to embed color changes into the string by setting the colorCoded boolean to true. This allows:
<syntaxhighlight lang="lua">
outputChatBox ( "#FF0000Hello #00FF00World", getRootElement(), 255, 255, 255, true )
</syntaxhighlight>
This will display as: '''<span style='color:red;'>Hello</span> <span style='color:green'>World</span> '''

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">bool outputChatBox ( string text [, element visibleTo=getRootElement(), int r=255, int g=255, int b=255, bool colorCoded=false ] )</syntaxhighlight>

==Required Arguments==
*'''text:''' The text string that you wish to send to the chat window. If more than 128 characters it will not be showed in chat.

==Optional Arguments==
{{OptionalArg}}
*'''visibleTo:''' This specifies who the chat is visible to. Any players in this element will see the chat message. See [[visibility]].
*'''r:''' The amount of red in the color of the text. Default value is 255.
*'''g:''' The amount of green in the color of the text. Default value is 255.
*'''b:''' The amount of blue in the color of the text. Default value is 255.
*'''colorCoded:''' A boolean value determining whether or not '#RRGGBB' tags should be used.
Note: '''visibleTo''' can also be a Team object, in this case, the text will be visible to all the players of that team. Also the #RRGGBB format must contain capital letters a-f is not acceptable but A-F is.
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">bool outputChatBox ( string text [, int r=255, int g=255, int b=255, bool colorCoded=false ] )</syntaxhighlight>

==Required Arguments==
*'''text:''' The text string that you wish to send to the chat window. If more than 128 characters it will not be showed in chat.

==Optional Arguments==
{{OptionalArg}}
*'''r:''' The amount of red in the color of the text. Default value is 255.
*'''g:''' The amount of green in the color of the text. Default value is 255.
*'''b:''' The amount of blue in the color of the text. Default value is 255.
*'''colorCoded:''' A boolean value determining whether or not '#RRGGBB' tags should be used.
</section>

==Returns==
Returns ''true'' if the message was displayed successfully. Returns ''false'' if invalid arguments are specified.

==Example==
<section name="Server" class="server" show="true">
'''Example 1:''' This example displays a chat message to all users.
<syntaxhighlight lang="lua">
x = 5
y = 10
-- Displays the message
outputChatBox ( "I have " .. x .. " apples and " .. y .. " oranges." )
</syntaxhighlight>

'''Example 2:''' This example outputs a simple colour coded message, "Red White", where the 'White' is in white colour, and 'Red' is in a red colour.
<syntaxhighlight lang="lua">
outputChatBox ( "Red #FFFFFFWhite", getRootElement(), 255, 0, 0, true )
</syntaxhighlight>

'''Example 3:''' This example allows for coloured chat, according to a player's nametag. This makes use of colour coded outputs.
<syntaxhighlight lang="lua">
function colouredChat ( message, theType )
if theType == 0 then --if its normal chat (not /me or teamchat) then
cancelEvent() --prevent MTA from outputting chat
message = string.gsub(message, "#%x%x%x%x%x%x", "") --remove any hex tags in a player's chat to prevent custom colours by using lua's string.gsub
local r,g,b = getPlayerNametagColor ( source ) --get the player's nametag colour
local chatterName = getPlayerName ( source ) --get his name
--output a message with the name as his nametag colour, and the rest in white.
outputChatBox ( chatterName..":#FFFFFF "..message, getRootElement(), r, g, b, true )
end
end
</syntaxhighlight>

'''Example 4:''' This example displays a chat message to a single user called ''someguy''.
<syntaxhighlight lang="lua">
-- Find the player element for the player called 'someguy'
myPlayer = getPlayerFromName ( "someguy" )
-- If a player was found called 'someguy' then...
if ( myPlayer ~= false ) then
x = 5
y = 10
-- Display the message
outputChatBox ( "I have " .. x .. " apples and " .. y .. " oranges.", myPlayer )
end
</syntaxhighlight>

'''Example 5:''' These two functions can speed up typing, and display a message when a player Joins.
<syntaxhighlight lang="lua">
local msg_red,msg_green,msg_blue = 255,255,0

function servertalkprivate(message, sendto)
--Talk to one client only
outputChatBox(tostring(message), sendto, msg_red, msg_green, msg_blue, true)
end

function servertalk(message)
--Talk to everyone
servertalkprivate(message, getRootElement())
end

function onJoin()
servertalkprivate("Welcome to My Server", source)
end

addEventHandler("onPlayerJoin",getRootElement(),onJoin)
</syntaxhighlight>
</section>

==See Also==
{{Server functions}}
[[ru:outputChatBox]]

AddCommandHandler

2012-05-13T00:43:50Z

FabioGNR: /* Syntax */

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

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

For users, a command is in the format:

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

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

==Syntax==

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

===Required Arguments===
*'''commandName:''' This is the name of the command you wish to attach a handler to. This is what must be typed into the console to trigger the function.
*'''handlerFunction:''' This is the function that you want the command to trigger, which has to be defined before you add the handler. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command (see below). These are all optional.
===Optional Arguments===
{{OptionalArg}}
*'''restricted:''' Specify whether or not this command should be restricted by default. Use this on commands that should be inaccessible to everyone as default except special users specified in the ACL (Access Control List). This is to make sure admin commands such as ie. 'punish' won't be available to everyone if a server administrator forgets masking it in ACL. Make sure to add the command to your ACL under the proper group for it to be usefull (i.e <right name="command.killEveryone" access="true"></right>). This argument defaults to false if nothing is specified.
{{New feature|3|1.0|
*'''caseSensitive:''' Specifies if the command handler will ignore the case for this command name.
}}

</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction, [bool caseSensitive = true] )
</syntaxhighlight>

===Required Arguments===
*'''commandName:''' This is the name of the command you wish to attach a handler to. This is what must be typed into the console to trigger the function.
*'''handlerFunction:''' This is the function that you want the command to trigger, which has to be defined before you add the handler. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command (see below). These are all optional.
===Optional Arguments===
{{OptionalArg}}
{{New feature|3|1.0|
*'''caseSensitive:''' Specifies if the command handler will ignore the case for this command name.
}}
</section>

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

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

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

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

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

<section name="Server" class="server" show="hide">
'''Example 2:''' This example makes use of Lua's vararg expression to implement a ''check_parameters'' command to count the number of parameters passed, merge them all into a single string and output it. This is also shows you how you can use table.concat to merge all the passed arguments. This is particularly useful when you want to read in a sentence of text passed from the user.
<syntaxhighlight lang="lua">
-- Define our function that will handle this command (which can accept a variable number of arguments after commandName)
function consoleCheckParameters ( playerSource, commandName, ... )
-- If a player, not an admin, triggered it,
if playerSource then
local arg = {...}
-- Get the number of arguments in the arg table (arg table is the same as: {...})
local parameterCount = #arg
-- Output it to the player's chatbox
outputChatBox ( "Number of parameters: " .. parameterCount, playerSource )
-- Join them together in a single comma-separated string
local stringWithAllParameters = table.concat( arg, ", " )
-- Output this parameter list to the player's chatbox
outputChatBox ( "Parameters passed: " .. stringWithAllParameters, playerSource )
end
end
-- Attach the 'consoleCheckParameters' function to the "check_parameters" command
addCommandHandler ( "check_parameters", consoleCheckParameters )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="hide">
'''Example 3:''' This example shows using a single function to handle multiple command handlers. This isn't advised for general usage, as it makes code harder to understand, but where multiple command handlers share some logic, it can be a useful way of reducing duplicated code. Generally, it would be preferable to put this shared logic in a separate function instead, as this gives you more control over the flow.

<syntaxhighlight lang="lua">
-- make the function
function moneyCmd(player, cmd, amount)
if getElementData(player, "canUseMoneyFunctions") then -- the shared logic
if cmd == "givemoney" then
amount = tonumber(amount)
if amount then
givePlayerMoney(player, amount)
else
outputChatBox("[usage] /givemoney [amount]", player)
end
else if cmd == "takemoney" then
amount = tonumber(amount)
if amount then
takePlayerMoney(player, amount)
else
outputChatBox("[usage] /takemoney [amount]", player)
end
end
else
outputChatBox("You aren't able to use this command", player)
end
end

addCommandHandler("givemoney", moneyCmd);
addCommandHandler("takemoney", moneyCmd);
</syntaxhighlight>
</section>

<section name="Client" class="client" show="false">
'''Example 1:''' This example warps the local player to a random nearby location (useful for when a player gets stuck somewhere).

<syntaxhighlight lang="lua">function escapeMe ()
local x, y, z = getElementPosition ( localPlayer ) --Get player's position
setElementPosition ( localPlayer, x+(math.random(-10,10)), y+(math.random(-10,10)), z+(math.random(1,15)) ) --Move a player randomly to a nearby location. X is current x + a number between -10, 10 and so on.
end
addCommandHandler ( "escape", escapeMe ) --When player types "/escape" in chatbox or "escape" in console
</syntaxhighlight>
</section>

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

GuiGridListInsertRowAfter

2012-05-07T15:44:37Z

FabioGNR: /* Required Arguments */

{{Client function}}
__NOTOC__
This allows you to insert a new row after a specified row. Good for inserting new rows in the middle of existing rows.

==Syntax==

<syntaxhighlight lang="lua">
int guiGridListInsertRowAfter ( element gridList, int rowIndex )
</syntaxhighlight>

===Required Arguments===
*'''gridList:''' The grid list you want to add a row to
*'''rowIndex:''' Row ID of the row you want to insert the '''new row''' after.

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

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

==See Also==

{{GUI functions}}
[[Category:Needs Example]]

GuiGridListInsertRowAfter

2012-05-07T15:43:51Z

FabioGNR: /* Required Arguments */

{{Client function}}
__NOTOC__
This allows you to insert a new row after a specified row. Good for inserting new rows in the middle of existing rows.

==Syntax==

<syntaxhighlight lang="lua">
int guiGridListInsertRowAfter ( element gridList, int rowIndex )
</syntaxhighlight>

===Required Arguments===
*'''gridList:''' The grid list you want to add a row to
*'''rowIndex:''' Row ID of the row you want to insert the [b] new [/b] row after.

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

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

==See Also==

{{GUI functions}}
[[Category:Needs Example]]

GuiLabelSetHorizontalAlign

2012-04-28T16:07:53Z

FabioGNR: /* Required Arguments */

{{Client function}}
__NOTOC__
This function sets the horizontal alignment of a text label.

==Syntax==
<syntaxhighlight lang="lua">
bool guiLabelSetHorizontalAlign ( element theLabel, string align, [ bool wordwrap = false ] )
</syntaxhighlight>

===Required Arguments===
*'''theLabel:''' The text label to set the horizontal alignment on.
*'''align:''' The alignment type. Valid type strings are:
**"left"
**"center"
**"right"
*'''wordwrap:''' Wordwrap: http://en.wikipedia.org/wiki/Word_wrap for more information.

===Returns===
Returns ''true'' on success, ''false'' otherwise.

==Example==

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

Requested Functions and Events

2012-04-24T17:56:30Z

FabioGNR: /* Server-side */

==Server-side==

Element type: GUI, for getElemensByType("GUI")
----------
Event like onServerTick wich is run very often. Like the clientside onClientRender. This could be useful for constat checking wich must be done under 50ms (lower than timers can handle).

----
onVehicleCreated or an equivalent... shouldn't be too hard? -Robhol (14:15 Jul 6, 08)
:If we did it, it'd be onElementCreated - what do you want this for? [[User:EAi|eAi]] 08:58, 7 July 2008 (CDT)
::onElementCreated is a good idea - it could be used for lots of things. Also, how about onVehicleDrown or whatever? that is, when a vehicle hits deep water. Checking for collisions and stuff is very awkward, and client-side only, and has to be checked constantly.. -Robhol (17:31 Jul 9 08)
:::I second that. It would be useful if you use like me element data like the fuel amount or other stuff. And an event like this would help me to setup those element data, when a car spawns. Otherwise I would either have to edit every car spawn script I use or do a post-setup when someone is entering the car.. [[User:MaddDogg14]] (04:34 Apr 4, 10 (CEST))
::::i definetly agree, onElementCreated would be VERY useful for utility/librares scripts, but i think this should be limited by ACL, because "evil" scripts could abuse this othervise -Karlis (9:10 Apr 5, 10)

----

I ask for a function that detects if a ped is on floor, eg. '''isPedOnFloor(ped thePed)''', thanks. --<span style="font-family:Courier New, Courier, monospace">[[User:Shadd|Shadd]]</span><sub>([[User_talk:Shadd|In caso di emergenza rompere le scatole]])</sub> 11:29, 15 June 2008 (CDT)
: [[isPedOnGround]]? [[User:Awwu|Awwu]] 12:58, 15 June 2008 (CDT)
::I need to know if the player has its back touching the ground, not if it's simply "on ground". --<span style="font-family:Courier New, Courier, monospace">[[User:Shadd|Shadd]]</span><sub>([[User_talk:Shadd|In caso di emergenza rompere le scatole]])</sub> 14:16, 16 June 2008 (CDT)
:::Check what task the player has, they should have TASK_COMPLEX_FALL_AND_GET_UP or TASK_COMPLEX_FALL_AND_STAY_DOWN... [[User:EAi|eAi]] 19:12, 16 June 2008 (CDT)
::::Thanks. What task does player have after being hitten by a melee attack that cause it to fall down? Would "TASK_SIMPLE_BE_KICKED_ON_GROUND" and "TASK_SIMPLE_GET_UP" work? --<span style="font-family:Courier New, Courier, monospace">[[User:Shadd|Shadd]]</span><sub>([[User_talk:Shadd|In caso di emergenza rompere le scatole]])</sub> 09:35, 17 June 2008 (CDT)
:::::Try it, I'm not entirely sure. You should be able to produce some code to show the player's current tasks very easily... [[User:EAi|eAi]] 19:20, 17 June 2008 (CDT)
::::::My goal is to edit the standard damage of the attacks, in this case i have to know when player is on ground to cause higher damage. However it doesn't seem to work, when i hit the player it simply gets up without animation with no damage. --<span style="font-family:Courier New, Courier, monospace">[[User:Shadd|Shadd]]</span><sub>([[User_talk:Shadd|In caso di emergenza rompere le scatole]])</sub> 19:10, 19 June 2008 (CDT)

----

It may looks strange and useless (waste of time?) but I think that it could be a awesome feature. Having a web browser.
Like: http://www.youtube.com/watch?v=wT1UR6qEgdg
http://princeofcode.com/awesomium.php
:definetly useles and waste of time, suporting xfire enought. -karlis
::Really Karlis, who asked you bro. It could be very useful, actually. For example, creating dynamic billboards. Instead of changing the TXD, they could set up a browser object over the billboard. That way they can also set up a timer to change the image, etc. [[User:JacobS|JacobS]] 20:08, 1 August 2010 (UTC)

----

There could be something like createBrowser( float x, float y, float z, [float rx, float ry, float rz, float width, float high, string url, bool locked] )
locked parameter: false = navigation bar present, true = no navigation bar
toggleBrowserFullsceenMode(browser theBrowser, bool tog, [bool smooth])
smooth parameter: If set to true the browser will smoothly move from his ingame position to the fullscreen position
toggleBrowserBackground(browser theBrowser, bool tog)
Set the browser background transparent.

----

Security: Disable file downloads, disable popups (disable flash, javascript and any other protocols than http and https [no mailto and stuff...]?)

----

Should be a Client and server function. --[[User:Masterofquebec|Masterofquebec]] 00:10, 15 October 2009 (UTC)

----

Support of tooltips from CEGUI would be cool. I saw a property for that, but it didn't work for me. [[User:MaddDogg14]] (04:36 Apr 4, 10 (CEST))

----

I request a function that gets all clothes from a ped, just like getPedClothes but for all bodyparts. With this function it would be more ease to save clothes to database.
:That's so easy to do yourself that it's barely worth adding. Just loop all the indexes 0-17 and save them to a table. [[User:Awwu|Awwu]] 19:26, 17 April 2010 (UTC)

----

[[setProjectileTarget]] for setting a projectile to target a specific entity. I am trying to create a Battlefield Bad Company type of gamemode and in that game, you can plant a 'tracer'. Any rocket fired (if the tracer is on screen) will seek the tracer. [[User:LeetWoovie|LeetWoovie]] 05:01, 19 April 2010 (UTC)

----

(marcol07, June the 25th, 2010) I would like to have some function to create light source as element or sth like createFire, for example createLight(x,y,z,xrot,yrot,zrot,f,r,g,b) where "f" is an angle of lightning. or it is possible with some model or function? It would be good to create for example fog lamps or classic street lamps

----

moveElement available for markers, objects, pedestrians and players or maybe more if you can do. [[User:Socialz|Socialz]] 13:10, 1 January 2012 (CET)

==Client-Side==
----

Adding possibility to toggle radio hud label by '''showHudComponent''' -karlis

----

Pickup events clientside please, onClientPickupHit onClientPickupUse.

----

Would it be possible to add a color arg to guiGridListSetItemText()? Im trying to get each item colored differently in one list. Thanks, ABEL

----

I need a function which could get current target of hydra or a HS rocket launcher, like when someone press space and targets a element, to get what element is it for calculating distance from it. '''getPlayerOccupiedVehicleTarget''' or '''getPlayerHSTarget'''.
Thanks in advance -Nidza a.k.a. CodeMaster 2:26 PM 19th June 2008.

----

It'd be useful to have something to disable elements of the default hud (weapon display, health display, armor, radar, etcetera) so that you can create your own HUDs. Something like '''setHudElement(element name, toggle)'''.

[[User:Lord Xalphox|Lord Xalphox]] 19:32, 22 March 2009 (CET)
:[[showPlayerHudComponent]]? [[User:Awwu|Awwu]] 19:43, 22 March 2009 (CET)

----

I'd like to have a function that sets the chatbox input line text. Then I could script my own chat history function (that inserts the last sent text into the input line again by pressing arrow up) (which samp has since 0.2 btw) since nobody builds it into the client. [[User:NeonBlack|NeonBlack]] 12:03, 4 July 2009 (CEST) PS.: samp also supports cut, copy and paste :P
----

A function setElementMatrix, doing the exact opposite of getElementMatrix would be much appreciated. --[[User:Kayl|Kayl]] 15:21, 13 November 2009 (UTC)

----

Functions like setTrainPosition(train,track,pos) and track,pos getTrainPosition(train) would be great in order to allow more script side control of trains.
The track argument would be an index of the track number (currently there are around 4 tracks handled, including 1 incompletely defined).
The position would be a float between 0 and 1 (or however you guys handle it) telling where on the track the train currently is.
It would be great if those functions could be available client and server side. --[[User:Kayl|Kayl]] 12:58, 23 November 2009 (UTC)

----

need this function client and server side '''movePlayerHudComponent(string component, float x, float y)''' --[[User:SuatEyrice|SuatEyrice]] 00:18, 26 February 2010 (UTC)

----

'''(marcol07, June the 27th, 2010)''' I would be so happy to have fuction to set Analog control of player sth like '''getAnalogControlState(string controlName)''' but inverted to '''setAnalogControlState(string controlName, float state)'''

----
OnPedDamage (serverside) event. There is OnClientPedDamage, but it's clientside. [[User:damage22|damage22]]

----
'''setRadioVolume(element thePlayer, int volume)''', to create GUI volume control, turn off the radio without changing the station, etc. [[User:JacobS|JacobS]] 14:47, 29 July 2010 (UTC)
----
'''setVehicleHydraulics(element theVehicle, bool state)''', to force hydraulics to be up (true) or down (false)
----
'''createFire(x, y, z, theSize, dimension)''', just like [[createFire]], only with the option to enter a dimension for the fire to appear in
----
'''setGunshotsEnabled(bool enabled)''', '''getGunshotsEnabled()''' and '''createGunshot(x,y,z,radius)''' - to enable/disable the game's gunshot ambience, and to create gunshots at specific locations with radii that it is audible in [[User:JacobS.|JacobS.]] 19:28, 11 September 2010 (MDT)

Requested Functions and Events

2012-04-02T11:04:24Z

FabioGNR: /* Server-side */

==Server-side==

onPedWarpedIntoVehicle would be useful, instead of checking if a player is in a vehicle. Since onVehicleEnter doesn't work for warps
----------
Event like onServerTick wich is run very often. Like the clientside onClientRender. This could be useful for constat checking wich must be done under 50ms (lower than timers can handle).

----
onVehicleCreated or an equivalent... shouldn't be too hard? -Robhol (14:15 Jul 6, 08)
:If we did it, it'd be onElementCreated - what do you want this for? [[User:EAi|eAi]] 08:58, 7 July 2008 (CDT)
::onElementCreated is a good idea - it could be used for lots of things. Also, how about onVehicleDrown or whatever? that is, when a vehicle hits deep water. Checking for collisions and stuff is very awkward, and client-side only, and has to be checked constantly.. -Robhol (17:31 Jul 9 08)
:::I second that. It would be useful if you use like me element data like the fuel amount or other stuff. And an event like this would help me to setup those element data, when a car spawns. Otherwise I would either have to edit every car spawn script I use or do a post-setup when someone is entering the car.. [[User:MaddDogg14]] (04:34 Apr 4, 10 (CEST))
::::i definetly agree, onElementCreated would be VERY useful for utility/librares scripts, but i think this should be limited by ACL, because "evil" scripts could abuse this othervise -Karlis (9:10 Apr 5, 10)

----

I ask for a function that detects if a ped is on floor, eg. '''isPedOnFloor(ped thePed)''', thanks. --<span style="font-family:Courier New, Courier, monospace">[[User:Shadd|Shadd]]</span><sub>([[User_talk:Shadd|In caso di emergenza rompere le scatole]])</sub> 11:29, 15 June 2008 (CDT)
: [[isPedOnGround]]? [[User:Awwu|Awwu]] 12:58, 15 June 2008 (CDT)
::I need to know if the player has its back touching the ground, not if it's simply "on ground". --<span style="font-family:Courier New, Courier, monospace">[[User:Shadd|Shadd]]</span><sub>([[User_talk:Shadd|In caso di emergenza rompere le scatole]])</sub> 14:16, 16 June 2008 (CDT)
:::Check what task the player has, they should have TASK_COMPLEX_FALL_AND_GET_UP or TASK_COMPLEX_FALL_AND_STAY_DOWN... [[User:EAi|eAi]] 19:12, 16 June 2008 (CDT)
::::Thanks. What task does player have after being hitten by a melee attack that cause it to fall down? Would "TASK_SIMPLE_BE_KICKED_ON_GROUND" and "TASK_SIMPLE_GET_UP" work? --<span style="font-family:Courier New, Courier, monospace">[[User:Shadd|Shadd]]</span><sub>([[User_talk:Shadd|In caso di emergenza rompere le scatole]])</sub> 09:35, 17 June 2008 (CDT)
:::::Try it, I'm not entirely sure. You should be able to produce some code to show the player's current tasks very easily... [[User:EAi|eAi]] 19:20, 17 June 2008 (CDT)
::::::My goal is to edit the standard damage of the attacks, in this case i have to know when player is on ground to cause higher damage. However it doesn't seem to work, when i hit the player it simply gets up without animation with no damage. --<span style="font-family:Courier New, Courier, monospace">[[User:Shadd|Shadd]]</span><sub>([[User_talk:Shadd|In caso di emergenza rompere le scatole]])</sub> 19:10, 19 June 2008 (CDT)

----

It may looks strange and useless (waste of time?) but I think that it could be a awesome feature. Having a web browser.
Like: http://www.youtube.com/watch?v=wT1UR6qEgdg
http://princeofcode.com/awesomium.php
:definetly useles and waste of time, suporting xfire enought. -karlis
::Really Karlis, who asked you bro. It could be very useful, actually. For example, creating dynamic billboards. Instead of changing the TXD, they could set up a browser object over the billboard. That way they can also set up a timer to change the image, etc. [[User:JacobS|JacobS]] 20:08, 1 August 2010 (UTC)

----

There could be something like createBrowser( float x, float y, float z, [float rx, float ry, float rz, float width, float high, string url, bool locked] )
locked parameter: false = navigation bar present, true = no navigation bar
toggleBrowserFullsceenMode(browser theBrowser, bool tog, [bool smooth])
smooth parameter: If set to true the browser will smoothly move from his ingame position to the fullscreen position
toggleBrowserBackground(browser theBrowser, bool tog)
Set the browser background transparent.

----

Security: Disable file downloads, disable popups (disable flash, javascript and any other protocols than http and https [no mailto and stuff...]?)

----

Should be a Client and server function. --[[User:Masterofquebec|Masterofquebec]] 00:10, 15 October 2009 (UTC)

----

Support of tooltips from CEGUI would be cool. I saw a property for that, but it didn't work for me. [[User:MaddDogg14]] (04:36 Apr 4, 10 (CEST))

----

I request a function that gets all clothes from a ped, just like getPedClothes but for all bodyparts. With this function it would be more ease to save clothes to database.
:That's so easy to do yourself that it's barely worth adding. Just loop all the indexes 0-17 and save them to a table. [[User:Awwu|Awwu]] 19:26, 17 April 2010 (UTC)

----

[[setProjectileTarget]] for setting a projectile to target a specific entity. I am trying to create a Battlefield Bad Company type of gamemode and in that game, you can plant a 'tracer'. Any rocket fired (if the tracer is on screen) will seek the tracer. [[User:LeetWoovie|LeetWoovie]] 05:01, 19 April 2010 (UTC)

----

(marcol07, June the 25th, 2010) I would like to have some function to create light source as element or sth like createFire, for example createLight(x,y,z,xrot,yrot,zrot,f,r,g,b) where "f" is an angle of lightning. or it is possible with some model or function? It would be good to create for example fog lamps or classic street lamps

----

moveElement available for markers, objects, pedestrians and players or maybe more if you can do. [[User:Socialz|Socialz]] 13:10, 1 January 2012 (CET)

==Client-Side==
----

Adding possibility to toggle radio hud label by '''showHudComponent''' -karlis

----

Pickup events clientside please, onClientPickupHit onClientPickupUse.

----

Would it be possible to add a color arg to guiGridListSetItemText()? Im trying to get each item colored differently in one list. Thanks, ABEL

----

I need a function which could get current target of hydra or a HS rocket launcher, like when someone press space and targets a element, to get what element is it for calculating distance from it. '''getPlayerOccupiedVehicleTarget''' or '''getPlayerHSTarget'''.
Thanks in advance -Nidza a.k.a. CodeMaster 2:26 PM 19th June 2008.

----

It'd be useful to have something to disable elements of the default hud (weapon display, health display, armor, radar, etcetera) so that you can create your own HUDs. Something like '''setHudElement(element name, toggle)'''.

[[User:Lord Xalphox|Lord Xalphox]] 19:32, 22 March 2009 (CET)
:[[showPlayerHudComponent]]? [[User:Awwu|Awwu]] 19:43, 22 March 2009 (CET)

----

I'd like to have a function that sets the chatbox input line text. Then I could script my own chat history function (that inserts the last sent text into the input line again by pressing arrow up) (which samp has since 0.2 btw) since nobody builds it into the client. [[User:NeonBlack|NeonBlack]] 12:03, 4 July 2009 (CEST) PS.: samp also supports cut, copy and paste :P
----

A function setElementMatrix, doing the exact opposite of getElementMatrix would be much appreciated. --[[User:Kayl|Kayl]] 15:21, 13 November 2009 (UTC)

----

Functions like setTrainPosition(train,track,pos) and track,pos getTrainPosition(train) would be great in order to allow more script side control of trains.
The track argument would be an index of the track number (currently there are around 4 tracks handled, including 1 incompletely defined).
The position would be a float between 0 and 1 (or however you guys handle it) telling where on the track the train currently is.
It would be great if those functions could be available client and server side. --[[User:Kayl|Kayl]] 12:58, 23 November 2009 (UTC)

----

need this function client and server side '''movePlayerHudComponent(string component, float x, float y)''' --[[User:SuatEyrice|SuatEyrice]] 00:18, 26 February 2010 (UTC)

----

'''(marcol07, June the 27th, 2010)''' I would be so happy to have fuction to set Analog control of player sth like '''getAnalogControlState(string controlName)''' but inverted to '''setAnalogControlState(string controlName, float state)'''

----
OnPedDamage (serverside) event. There is OnClientPedDamage, but it's clientside. [[User:damage22|damage22]]

----
'''setRadioVolume(element thePlayer, int volume)''', to create GUI volume control, turn off the radio without changing the station, etc. [[User:JacobS|JacobS]] 14:47, 29 July 2010 (UTC)
----
'''setVehicleHydraulics(element theVehicle, bool state)''', to force hydraulics to be up (true) or down (false)
----
'''createFire(x, y, z, theSize, dimension)''', just like [[createFire]], only with the option to enter a dimension for the fire to appear in
----
'''setGunshotsEnabled(bool enabled)''', '''getGunshotsEnabled()''' and '''createGunshot(x,y,z,radius)''' - to enable/disable the game's gunshot ambience, and to create gunshots at specific locations with radii that it is audible in [[User:JacobS.|JacobS.]] 19:28, 11 September 2010 (MDT)

SetVehicleRespawnPosition

2012-03-30T23:22:21Z

FabioGNR: /* Required Arguments */

__NOTOC__
{{Server function}}
This function sets the position (and rotation) the vehicle will respawn to.

==Syntax==
<syntaxhighlight lang="lua">bool setVehicleRespawnPosition ( vehicle theVehicle, float x, float y, float z, [float rx, float ry, float rz ] )</syntaxhighlight>

===Required Arguments===
*'''theVehicle''': The [[vehicle]] you wish to change the respawn position of.
* '''x''': A floating point number representing the X coordinate on the map.
* '''y''': A floating point number representing the Y coordinate on the map.
* '''z''': A floating point number representing the Z coordinate on the map.

===Optional Arguments===
{{OptionalArg}}
* '''rx''': A floating point number representing the rotation about the X axis in Degrees.
* '''ry''': A floating point number representing the rotation about the Y axis in Degrees.
* '''rz''': A floating point number representing the rotation about the Z axis in Degrees.

==Returns==
Returns ''true'' if the vehicle was found and edited, ''false'' otherwise.

==Example==
This example creates a vehicle and changes its respawn position.
<syntaxhighlight lang="lua">
local vehicle = createVehicle ( 400, 1, 1, 1 ) -- create us a new vehicle
if ( vehicle ) then
setVehicleRespawnPosition ( vehicle, 10, 10, 10 ) -- tell the server to respawn the vehicle at position (10,10,10)
end
</syntaxhighlight>

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

OnPedWasted

2012-03-27T16:10:28Z

FabioGNR: /* Example */

__NOTOC__
{{Server event}}
This event is triggered when a ped is killed or dies.

==Parameters==
<syntaxhighlight lang="lua">int totalAmmo, element killer, int killerWeapon, int bodypart [, bool stealth ]
</syntaxhighlight>

*'''totalAmmo''': an integer representing the total ammo the victim had when he died.
*'''killer''': an [[element]] representing the player or vehicle who was the killer. If there was no killer this is ''false''.
*'''killerWeapon''': an integer representing the [[Weapons|killer weapon]] or the [[Death Reasons|death reason]].
*'''bodypart''': an integer representing the bodypart ID the victim was hit on when he died.
{{BodyParts}}
*'''stealth''': boolean value representing whether or not this was a stealth kill

==Source==
The [[event system#Event source|source]] of this event is the [[ped]] that died or got killed.

<section name="Example 1" class="server" show="true">
<syntaxhighlight lang="lua">
function pedDied(totalAmmo, killer, killerWeapon)
if ( getElementType("killer") == "player" ) and ( getElementType("source") == "player" ) then -- if the killer is a player and the ped who died is then
outputChatBox( getPlayerName(source) .. " was killed by " .. getPlayerName(killer) .. " with " .. killerWeapon .. ".")--Say who killed who with what weapon
end
end
addEventHandler("onPedWasted", getRootElement(), pedDied) -- onPedWasted the function pedDied gets called
</syntaxhighlight>
</section>

==See Also==
{{Ped_events}}

OnElementStopSync

2012-03-27T16:08:46Z

FabioGNR: /* Source */

__NOTOC__
{{Server event}}
{{Warning|In 1.1.x, Destroying the source of this event could crash the server!|true}}
{{Needs Example}}

This event is triggered when an element is no longer synced by a player.

==Parameters==
<syntaxhighlight lang="lua">
player oldSyncer
</syntaxhighlight>

*'''oldSyncer''': [[player]] element representing the last player who was syncing the element

==Source==
The [[event system#Event source|source]] of this event is the [[element]] which is no longer synced by a player.

<section name="Example" class="server" show="true">
<syntaxhighlight lang="lua">
veh = createVehicle(520, 0,0,4) -- create our testing vehicle

function syncStop()
if source == veh then -- check if the element that stopped getting synced was our vehicle
outputChatBox("You stopped syncing the vehicle!!",oldSyncer) -- tell the player he stopped syncing the vehicle ( veh )
end
end

addEventHandler("onElementStopSync",getRootElement(),syncStop) -- onElementStopSync, the function syncStop gets called
</syntaxhighlight>
</section>
{{See also/Server event|Element events}}

OnElementStopSync

2012-03-27T16:08:30Z

FabioGNR: /* Example */

__NOTOC__
{{Server event}}
{{Warning|In 1.1.x, Destroying the source of this event could crash the server!|true}}
{{Needs Example}}

This event is triggered when an element is no longer synced by a player.

==Parameters==
<syntaxhighlight lang="lua">
player oldSyncer
</syntaxhighlight>

*'''oldSyncer''': [[player]] element representing the last player who was syncing the element

==Source==
The [[event system#Event source|source]] of this event is the [[element]] which is no longer synced by a player.

<section name="Example" class="server" show="true"></section>
<syntaxhighlight lang="lua">
veh = createVehicle(520, 0,0,4) -- create our testing vehicle

function syncStop()
if source == veh then -- check if the element that stopped getting synced was our vehicle
outputChatBox("You stopped syncing the vehicle!!",oldSyncer) -- tell the player he stopped syncing the vehicle ( veh )
end
end

addEventHandler("onElementStopSync",getRootElement(),syncStop) -- onElementStopSync, the function syncStop gets called
</syntaxhighlight>

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

OnElementStopSync

2012-03-27T16:08:03Z

FabioGNR: /* Example */

__NOTOC__
{{Server event}}
{{Warning|In 1.1.x, Destroying the source of this event could crash the server!|true}}
{{Needs Example}}

This event is triggered when an element is no longer synced by a player.

==Parameters==
<syntaxhighlight lang="lua">
player oldSyncer
</syntaxhighlight>

*'''oldSyncer''': [[player]] element representing the last player who was syncing the element

==Source==
The [[event system#Event source|source]] of this event is the [[element]] which is no longer synced by a player.

==Example==
<syntaxhighlight lang="lua">
veh = createVehicle(520, 0,0,4) -- create our testing vehicle

function syncStop()
if source == veh then -- check if the element that stopped getting synced was our vehicle
outputChatBox("You stopped syncing the vehicle!!",oldSyncer) -- tell the player he stopped syncing the vehicle ( veh )
end
end

addEventHandler("onElementStopSync",getRootElement(),syncStop) -- onElementStopSync, the function syncStop gets called
</syntaxhighlight>

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

OnElementStopSync

2012-03-27T16:03:39Z

FabioGNR: /* Example */

__NOTOC__
{{Server event}}
{{Warning|In 1.1.x, Destroying the source of this event could crash the server!|true}}
{{Needs Example}}

This event is triggered when an element is no longer synced by a player.

==Parameters==
<syntaxhighlight lang="lua">
player oldSyncer
</syntaxhighlight>

*'''oldSyncer''': [[player]] element representing the last player who was syncing the element

==Source==
The [[event system#Event source|source]] of this event is the [[element]] which is no longer synced by a player.

==Example==
<syntaxhighlight lang="lua">
veh = createVehicle(520, 0,0,1) -- create our testing vehicle

function syncStop()
if source == veh then -- check if the element that stopped getting synced was our vehicle
outputChatBox("You stopped syncing the vehicle!!",oldSyncer) -- tell the player he stopped syncing the vehicle ( veh )
end
end

addEventHandler("onElementStopSync",getRootElement(),syncStop) -- onElementStopSync, the function syncStop gets called
</syntaxhighlight>

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

Introduction to Scripting the GUI

2012-03-26T17:03:48Z

FabioGNR: /* Relative and Absolute */

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 apply 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)
setCameraTarget(client, client)
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]]
[[es:Introducción a la Programación de GUI]]

OnPedWasted

2012-03-24T22:55:33Z

FabioGNR: /* Example */

__NOTOC__
{{Server event}}
This event is triggered when a ped is killed or dies.

==Parameters==
<syntaxhighlight lang="lua">int totalAmmo, element killer, int killerWeapon, int bodypart [, bool stealth ]
</syntaxhighlight>

*'''totalAmmo''': an integer representing the total ammo the victim had when he died.
*'''killer''': an [[element]] representing the player or vehicle who was the killer. If there was no killer this is ''false''.
*'''killerWeapon''': an integer representing the [[Weapons|killer weapon]] or the [[Death Reasons|death reason]].
*'''bodypart''': an integer representing the bodypart ID the victim was hit on when he died.
{{BodyParts}}
*'''stealth''': boolean value representing whether or not this was a stealth kill

==Source==
The [[event system#Event source|source]] of this event is the [[ped]] that died or got killed.

==Example==
<syntaxhighlight lang="lua">
function pedDied(totalAmmo, killer, killerWeapon)
if ( getElementType("killer") == "player" ) and ( getElementType("source") == "player" ) then
outputChatBox( getPlayerName(source) .. " was killed by " .. getPlayerName(killer) .. " with " .. killerWeapon .. ".")
end
end
addEventHandler("onPedWasted", getRootElement(), pedDied)
</syntaxhighlight>

==See Also==
{{Ped_events}}

OnPedWasted

2012-03-24T22:51:04Z

FabioGNR: /* Example */

__NOTOC__
{{Server event}}
This event is triggered when a ped is killed or dies.

==Parameters==
<syntaxhighlight lang="lua">int totalAmmo, element killer, int killerWeapon, int bodypart [, bool stealth ]
</syntaxhighlight>

*'''totalAmmo''': an integer representing the total ammo the victim had when he died.
*'''killer''': an [[element]] representing the player or vehicle who was the killer. If there was no killer this is ''false''.
*'''killerWeapon''': an integer representing the [[Weapons|killer weapon]] or the [[Death Reasons|death reason]].
*'''bodypart''': an integer representing the bodypart ID the victim was hit on when he died.
{{BodyParts}}
*'''stealth''': boolean value representing whether or not this was a stealth kill

==Source==
The [[event system#Event source|source]] of this event is the [[ped]] that died or got killed.

==Example==
<syntaxhighlight lang="lua">
function pedDied(totalAmmo, killer, killerWeapon)
outputChatBox( getPlayerName(source) .. " was killed by " .. getPlayerName(killer) .. " with " .. killerWeapon .. ".")
end
addEventHandler("onPedWasted", getRootElement(), pedDied)
</syntaxhighlight>

==See Also==
{{Ped_events}}