Multi Theft Auto: Wiki - User contributions [en]

AddEventHandler

2022-06-26T00:56:26Z

Skully: Fix invalid characters.

__NOTOC__
{{Server client function}}
{{Important Note|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. On the same note, for multiple reasons, it is '''NOT''' a good idea to export the same functions that you use locally as remote event handlers.}}
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.
{{Important Note|See code for this note below}}

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
*'''sourceResource''': the resource that triggered the event
*'''sourceResourceRoot''': the root element of the resource that triggered the event
*'''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 ''propagate'' 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}}
{{Note|See [[Event_Source_Element|Event Source Element]] for a descriptive visualization of the event system handling an event trigger.}}

Each function closure can only be added once to each event. On the second attempt to add the function closure to the same event a warning will be emitted to the debug console and the call to addEventHandler will fail.
==Syntax==
<syntaxhighlight lang="lua">
bool addEventHandler ( string eventName, element attachedTo, function handlerFunction [, bool propagate = true, string priority = "normal" ] )
</syntaxhighlight>

===Required Arguments===
*'''eventName:''' The name of the [[event]] you want to attach the handler function to. '''Note: The maximum allowed length is 100 ASCII characters (that is, English letters and numerals)'''
*'''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===
*'''propagate:''' 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''). In GUI events you will probably want to set this to ''false''.
{{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.

==Remarks==
Due to the additional set of global variables, the event-trigger specific variables it is '''NOT a good idea to use the same function locally as well as directly as an event handler'''. Event handlers often make use of the source element variable which would often find no use in generic functions. Inside of server-side remote event handlers it is important to add protections against exploits due to unexpected client event triggers or network-based load situations while generic functions, due to being part of a controlled call-stack, do not in general face the same issues. It is recommended to adapt a '''good-natured distancing''' principle between code meant to run from local logic in separation to code meant to run from remote logic.

==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">
-- 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", root, onPlayerSpawnHandler ) -- root is a predefined global variable for getRootElement()
</syntaxhighlight>
</section>

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

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

CURL Errors

2022-06-18T00:04:47Z

Skully: Fix inline heading.

{{Historical}}
List of CURL Errors, updates can be found [https://curl.haxx.se/libcurl/c/libcurl-errors.html here]

'''CURLE_OK (0)'''

All fine. Proceed as usual.

'''CURLE_UNSUPPORTED_PROTOCOL (1)'''

The URL you passed to libcurl used a protocol that this libcurl does not support. The support might be a compile-time option that you didn't use, it can be a misspelled protocol string or just a protocol libcurl has no code for.

'''CURLE_FAILED_INIT (2)'''

Very early initialization code failed. This is likely to be an internal error or problem.

'''CURLE_URL_MALFORMAT (3)'''

The URL was not properly formatted.

'''CURLE_COULDNT_RESOLVE_PROXY (5)'''

Couldn't resolve proxy. The given proxy host could not be resolved.

'''CURLE_COULDNT_RESOLVE_HOST (6)'''

Couldn't resolve host. The given remote host was not resolved.

'''CURLE_COULDNT_CONNECT (7)'''

Failed to connect() to host or proxy.

'''CURLE_FTP_WEIRD_SERVER_REPLY (8)'''

After connecting to a FTP server, libcurl expects to get a certain reply back. This error code implies that it got a strange or bad reply. The given remote server is probably not an OK FTP server.

'''CURLE_REMOTE_ACCESS_DENIED (9)'''

We were denied access to the resource given in the URL. For FTP, this occurs while trying to change to the remote directory.
'''
CURLE_FTP_WEIRD_PASS_REPLY (11)'''

After having sent the FTP password to the server, libcurl expects a proper reply. This error code indicates that an unexpected code was returned.

'''CURLE_FTP_WEIRD_PASV_REPLY (13)'''

libcurl failed to get a sensible result back from the server as a response to either a PASV or a EPSV command. The server is flawed.

'''CURLE_FTP_WEIRD_227_FORMAT (14)'''

FTP servers return a 227-line as a response to a PASV command. If libcurl fails to parse that line, this return code is passed back.

'''CURLE_FTP_CANT_GET_HOST (15)'''

An internal failure to lookup the host used for the new connection.

'''CURLE_FTP_COULDNT_SET_TYPE (17)'''

Received an error when trying to set the transfer mode to binary or ASCII.

'''CURLE_PARTIAL_FILE (18)'''

A file transfer was shorter or larger than expected. This happens when the server first reports an expected transfer size, and then delivers data that doesn't match the previously given size.

'''CURLE_FTP_COULDNT_RETR_FILE (19)'''

This was either a weird reply to a 'RETR' command or a zero byte transfer complete.

'''CURLE_QUOTE_ERROR (21)'''

When sending custom "QUOTE" commands to the remote server, one of the commands returned an error code that was 400 or higher (for FTP) or otherwise indicated unsuccessful completion of the command.

'''CURLE_HTTP_RETURNED_ERROR (22)'''

This is returned if CURLOPT_FAILONERROR is set TRUE and the HTTP server returns an error code that is >= 400. (This error code was formerly known as CURLE_HTTP_NOT_FOUND.)

'''CURLE_WRITE_ERROR (23)'''

An error occurred when writing received data to a local file, or an error was returned to libcurl from a write callback.

'''CURLE_UPLOAD_FAILED (25)'''

Failed starting the upload. For FTP, the server typically denied the STOR command. The error buffer usually contains the server's explanation for this. (This error code was formerly known as CURLE_FTP_COULDNT_STOR_FILE.)

'''CURLE_READ_ERROR (26)'''

There was a problem reading a local file or an error returned by the read callback.

'''CURLE_OUT_OF_MEMORY (27)'''

A memory allocation request failed. This is serious badness and things are severely screwed up if this ever occurs.

'''CURLE_OPERATION_TIMEDOUT (28)'''

Operation timeout. The specified time-out period was reached according to the conditions.

'''CURLE_FTP_PORT_FAILED (30)'''

The FTP PORT command returned error. This mostly happens when you haven't specified a good enough address for libcurl to use. See CURLOPT_FTPPORT.

'''CURLE_FTP_COULDNT_USE_REST (31)'''

The FTP REST command returned error. This should never happen if the server is sane.

'''CURLE_RANGE_ERROR (33)'''

The server does not support or accept range requests.

'''CURLE_HTTP_POST_ERROR (34)'''

This is an odd error that mainly occurs due to internal confusion.

'''CURLE_SSL_CONNECT_ERROR (35)'''

A problem occurred somewhere in the SSL/TLS handshake. You really want the error buffer and read the message there as it pinpoints the problem slightly more. Could be certificates (file formats, paths, permissions), passwords, and others.

'''CURLE_FTP_BAD_DOWNLOAD_RESUME (36)'''

Attempting FTP resume beyond file size.

'''CURLE_FILE_COULDNT_READ_FILE (37)'''

A file given with FILE:// couldn't be opened. Most likely because the file path doesn't identify an existing file. Did you check file permissions?

'''CURLE_LDAP_CANNOT_BIND (38)'''

LDAP cannot bind. LDAP bind operation failed.

'''CURLE_LDAP_SEARCH_FAILED (39)'''

LDAP search failed.

'''CURLE_FUNCTION_NOT_FOUND (41)'''

Function not found. A required zlib function was not found.

'''CURLE_ABORTED_BY_CALLBACK (42)'''

Aborted by callback. A callback returned "abort" to libcurl.

'''CURLE_BAD_FUNCTION_ARGUMENT (43)'''

Internal error. A function was called with a bad parameter.

'''CURLE_INTERFACE_FAILED (45)'''

Interface error. A specified outgoing interface could not be used. Set which interface to use for outgoing connections' source IP address with CURLOPT_INTERFACE. (This error code was formerly known as CURLE_HTTP_PORT_FAILED.)

'''CURLE_TOO_MANY_REDIRECTS (47)'''

Too many redirects. When following redirects, libcurl hit the maximum amount. Set your limit with CURLOPT_MAXREDIRS.

'''CURLE_UNKNOWN_TELNET_OPTION (48)'''

An option set with CURLOPT_TELNETOPTIONS was not recognized/known. Refer to the appropriate documentation.

'''CURLE_TELNET_OPTION_SYNTAX (49)'''

A telnet option string was Illegally formatted.

'''CURLE_PEER_FAILED_VERIFICATION (51)'''

The remote server's SSL certificate or SSH md5 fingerprint was deemed not OK.

'''CURLE_GOT_NOTHING (52)'''

Nothing was returned from the server, and under the circumstances, getting nothing is considered an error.

'''CURLE_SSL_ENGINE_NOTFOUND (53)'''

The specified crypto engine wasn't found.

'''CURLE_SSL_ENGINE_SETFAILED (54)'''

Failed setting the selected SSL crypto engine as default!

'''CURLE_SEND_ERROR (55)'''

Failed sending network data.

'''CURLE_RECV_ERROR (56)'''

Failure with receiving network data.

'''CURLE_SSL_CERTPROBLEM (58)'''

problem with the local client certificate.

'''CURLE_SSL_CIPHER (59)'''

Couldn't use specified cipher.

'''CURLE_SSL_CACERT (60)'''

Peer certificate cannot be authenticated with known CA certificates.

'''CURLE_BAD_CONTENT_ENCODING (61)'''

Unrecognized transfer encoding.

'''CURLE_LDAP_INVALID_URL (62)'''

Invalid LDAP URL.

'''CURLE_FILESIZE_EXCEEDED (63)'''

Maximum file size exceeded.

'''CURLE_USE_SSL_FAILED (64)'''

Requested FTP SSL level failed.

'''CURLE_SEND_FAIL_REWIND (65)'''

When doing a send operation curl had to rewind the data to retransmit, but the rewinding operation failed.

'''CURLE_SSL_ENGINE_INITFAILED (66)'''

Initiating the SSL Engine failed.

'''CURLE_LOGIN_DENIED (67)'''

The remote server denied curl to login (Added in 7.13.1)

'''CURLE_TFTP_NOTFOUND (68)'''

File not found on TFTP server.

'''CURLE_TFTP_PERM (69)'''

Permission problem on TFTP server.

'''CURLE_REMOTE_DISK_FULL (70)'''

Out of disk space on the server.

'''CURLE_TFTP_ILLEGAL (71)'''

Illegal TFTP operation.

'''CURLE_TFTP_UNKNOWNID (72)'''

Unknown TFTP transfer ID.

'''CURLE_REMOTE_FILE_EXISTS (73)'''

File already exists and will not be overwritten.

'''CURLE_TFTP_NOSUCHUSER (74)'''

This error should never be returned by a properly functioning TFTP server.

'''CURLE_CONV_FAILED (75)'''

Character conversion failed.

'''CURLE_CONV_REQD (76)'''

Caller must register conversion callbacks.

'''CURLE_SSL_CACERT_BADFILE (77)'''

Problem with reading the SSL CA cert (path? access rights?)

'''CURLE_REMOTE_FILE_NOT_FOUND (78)'''

The resource referenced in the URL does not exist.

'''CURLE_SSH (79)'''

An unspecified error occurred during the SSH session.

'''CURLE_SSL_SHUTDOWN_FAILED (80)'''

Failed to shut down the SSL connection.

'''CURLE_AGAIN (81)'''

Socket is not ready for send/recv wait till it's ready and try again. This return code is only returned from curl_easy_recv(3) and curl_easy_send(3) (Added in 7.18.2)

'''CURLE_SSL_CRL_BADFILE (82)'''

Failed to load CRL file (Added in 7.19.0)

'''CURLE_SSL_ISSUER_ERROR (83)'''

Issuer check failed (Added in 7.19.0)

IsPlayerInWater

2021-09-22T06:08:32Z

Skully: Change deprecated function alternative.

__NOTOC__
{{Server client function}}
{{Deprecated|isElementInWater}}

This function is used to determine whether or not a player is currently in water. Player is in water only if breath bar appears.

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

===Required Arguments===
*'''thePlayer:''' The [[player]] you are checking.

===Returns===
Returns ''true'' if the player is in water, ''false'' otherwise.

==Example==
<section name="Serverside example" class="server" show="true">
This example shows all players that are in water in a list to the player who enters the 'playersInWater' command.
<syntaxhighlight lang="lua">
function showPlayersInWater(sourcePlayer, command)
local players = getElementsByType("player")
local list = ""
for k,v in ipairs(players) do
if isPlayerInWater(v) then
list = list .. " " .. getClientName(v)
end
end
outputChatBox("Players pretending to be trouts: " .. list, sourcePlayer)
end
addCommandHandler("playersInWater", showPlayersInWater)
</syntaxhighlight>
</section>

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

CreateFire

2021-09-08T01:53:18Z

Skully: Fixed English and clarified explanation of size argument.

__NOTOC__
{{Client function}}
[[Image:Fire.png|thumb|200px|Fire with default size (1.8)]]

Creates a patch of fire that will spread a bit and die out after a while. Because it's a client side only function, other players won't see it, so custom events or custom objects will be needed to make a fire visible to some players.

==Syntax==
<syntaxhighlight lang="lua">bool createFire ( float x, float y, float z [, float size = 1.8 ] )</syntaxhighlight>

===Required Arguments===
*'''x, y, z:''' the coordinates when the initial patch of fire will be created.

===Optional Arguments===
*'''size:''' a float value indicating the size of the initial patch of fire, this value also affects the duration of how long the fire remains.

===Returns===
Returns ''true'' if successful, ''false'' if bad arguments were passed or the limit of active fires was reached. There can be a maximum of 60 active fires.

== Example ==

This example adds a /fire command, which creates a patch of fire in the position of the player that types it.

<syntaxhighlight lang="lua">
local function burn(commandName, theSize)
if tonumber(theSize) then
local x, y, z = getElementPosition(getLocalPlayer())
createFire(x, y, z, tonumber(theSize))
outputChatBox("Burn, buuuuurn >:]")
else
outputChatBox("Syntax: /fire <size>")
end
end
addCommandHandler("fire", burn)
</syntaxhighlight>

==See Also==
{{Client fire functions}}

IsResourceProtected

2020-08-07T09:16:27Z

Skully: /* Added script example. */

__NOTOC__
{{Server function}}

{{New feature/item|3.0158|1.5.7|20468|
This will check if a resource is currently protected, as defined in [[Server_mtaserver.conf#resource|mtaserver.conf]].
}}
==Syntax==

<syntaxhighlight lang="lua">
bool isResourceProtected(resource theResource)
</syntaxhighlight>
{{OOP||[[resource]]:isProtected|protected}}
===Required Arguments===

*'''theResource:''' the resource to check

===Returns===

Returns ''true'' if the resource is 'protected', ''false'' otherwise.

==Example==
This example creates a command which allows you to check if the given resource with the name provided is protected. The command is "/isprotected [Resource Name]".

<syntaxhighlight lang="lua">
function resourceProtectedCommand(thePlayer, command, resourceName)
if resourceName then -- If the player provided a resource name.
local theResource = getResourceFromName(resourceName) -- Get the resource element.
if theResource then -- If we have an element, the resource must exist.
local protectedResource = isResourceProtected(theResource) -- Check to see if the resource is protected.
if protectedResource then -- if it is protected.
outputChatBox("This resource is a protected resource in the server config.", thePlayer, 0, 255, 0)
else -- If the resource is not protected.
outputChatBox("This resource is not a protected resource in the server config.", thePlayer, 0, 255, 0)
end
else -- A resource with the name didn't exist.
outputChatBox("A resource with the name '" .. resourceName .. "' does not exist!", thePlayer, 255, 0, 0)
end
else -- The player didn't provide a resource name.
outputChatBox("Please specify a resource name.", thePlayer, 255, 0, 0)
end
end
addCommandHandler("isprotected", resourceProtectedCommand)
</syntaxhighlight>

==See Also==

{{Resource_functions}}

GetKeyState

2020-07-26T03:22:55Z

Skully: /* Removed unrequired boolean comparison and fixed punctuation. */

__NOTOC__
{{Client function}}
This function determines if a certain key is pressed or not.

'''Note:''' 'ralt' may trigger both 'ralt' and 'lctrl', this is due to AltGr

==Syntax==
<syntaxhighlight lang="lua">
bool getKeyState ( string keyName )
</syntaxhighlight>

===Required Arguments===
*'''keyName:''' The name of the key you're checking state of. See [[Key names]].

===Returns===
Returns ''true'' if the specified key is pressed, ''false'' if it isn't or if an invalid key name is passed.

==Example==
This clientside example prints a message when "p" is pressed, and a different one for the "control+p" combination.
<syntaxhighlight lang="lua">
-- define a function that outputs a message if control is pressed, and a different one if it isn't
function printMessageFunction()
-- if the left or right control keys are pressed, the user has pressed the "lctrl + p" combo.
if getKeyState("lctrl") or getKeyState("rctrl") then
outputChatBox ("You have pressed 'Left Control + P'.")
-- if none of those were pressed, the player just pressed the "p" key.
else
outputChatBox ("You have pressed 'p'.")
end
end
-- bind the "p" key to our function
bindKey("p", "down", printMessageFunction)
</syntaxhighlight>

==See Also==
{{Client_input_functions}}

OnDgsCheckBoxChange

2018-06-02T22:21:19Z

Skully: /* Fixed not calling exported function. */

{{Client event}}
__NOTOC__
This event is triggered each time the dgs check box state has changed.

==Parameters==
<syntaxhighlight lang="lua">
bool state
</syntaxhighlight>

==Source==
The [[event system#Event source|source]] of this event is the dgs check box.

==Example==
<syntaxhighlight lang="lua">
DGS = exports.dgs

local cb1 = DGS:dgsCreateCheckBox(300,300,200,30, "CheckBox Test 1", false)
local cb2 = DGS:dgsCreateCheckBox(300,320,200,30, "CheckBox Test 2", false)

function onStateChanged(state)
if source == cb1 and state == true then
outputChatBox("Selected CheckBox 1")
end
end
addEventHandler("onDgsCheckBoxChange", root, onStateChanged)

</syntaxhighlight>

==See Also==
===DGS events===
{{DGSEVENTS}}
===Client event functions===
{{Client_event_functions}}

GetNearestVehicle

2018-05-24T04:41:01Z

Skully: /* Fixed minor typo. */

{{Useful Function}}
==Syntax==
<syntaxhighlight lang="lua">vehicle getNearestVehicle( element thePlayer )</syntaxhighlight>
===Required Arguments===
* '''thePlayer''': The player you want to get the nearest vehicle of.

===Returns===
Return a vehicle element if success, false if there's no vehicles in a 10meter circle..
==Code==
<section name="Server- and/or clientside Script" class="both" show="true">
<syntaxhighlight lang="lua">
function getNearestVehicle(player,distance)
local tempTable = {}
local lastMinDis = distance-0.0001
local nearestVeh = false
local px,py,pz = getElementPosition(player)
local pint = getElementInterior(player)
local pdim = getElementDimension(player)

for _,v in pairs(getElementsByType("vehicle")) do
local vint,vdim = getElementInterior(v),getElementDimension(v)
if vint == pint and vdim == pdim then
local vx,vy,vz = getElementPosition(v)
local dis = getDistanceBetweenPoints3D(px,py,pz,vx,vy,vz)
if dis < distance then
if dis < lastMinDis then
lastMinDis = dis
nearestVeh = v
end
end
end
end
return nearestVeh
end

</syntaxhighlight></section>

{{Useful_Functions}}

GetVehiclePanelState

2018-04-07T00:25:23Z

Skully: Fixed broken redirect.

__NOTOC__
{{Server client function}}
This function returns the current state of a specifed panel on the vehicle. A vehicle can have up to 7 panels.

==Syntax==
<syntaxhighlight lang="lua">
int getVehiclePanelState ( vehicle theVehicle, int panel )
</syntaxhighlight>
{{OOP||[[vehicle]]:getPanelState||setVehiclePanelState}}

==Required Arguments==
*'''theVehicle:''' the [[vehicle]] that you wish to know the panel state of.
*'''panel:''' an ''integer'' specifying the panel you want to know the state of. Not every vehicle has every panel. Possible values are:
** '''0:''' Front-left panel
** '''1:''' Front-right panel
** '''2:''' Rear-left panel
** '''3:''' Rear-right panel
** '''4:''' Windscreen
** '''5:''' Front bumper
** '''6:''' Rear bumper

==Returns==
Returns an [[int]] indicating the state of the specified the panel. This is a value between 0 and 3, with 0 indicating the panel is undamaged and 3 indicating it is very damaged.

==Example==
This function creates an admiral and outputs every panel's state in the chatbox.
<syntaxhighlight lang="lua">
local admiral = createVehicle ( 445, 0, 0, 10 )
for i=0, 6 do
local panel = getVehiclePanelState ( admiral, i )
outputChatBox ( tostring ( panel ) )
end
</syntaxhighlight>

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

SetVehiclePanelState

2018-04-06T22:29:57Z

Skully: Added OOP syntax.

__NOTOC__
{{Server client function}}

This function allows you to change the state of one of the six panels vehicle's can have. When executed on the server-side resources, the damage will be synched for all players, whereas the change is only client-side if the function is used in a client resource.

==Syntax==
<syntaxhighlight lang="lua">bool setVehiclePanelState ( vehicle theVehicle, int panelID, int state )</syntaxhighlight>
{{OOP||[[vehicle]]:setPanelState||getVehiclePanelState}}

==Required Arguments==
*'''theVehicle:''' The [[vehicle]] you would like to modify the panel of.
*'''panelID:''' An ID specifying the part of the vehicle. Possible values are:

*'''Cars:'''
** '''0:''' Front-left panel
** '''1:''' Front-right panel
** '''2:''' Rear-left panel
** '''3:''' Rear-right panel
** '''4:''' Windscreen
** '''5:''' Front bumper
** '''6:''' Rear bumper

*'''Planes:'''
**'''0:''' Engine Smoke (left engine for a Nevada or a Beagle)
**'''1:''' Engine Smoke (right engine for a Nevada or a Beagle)
**'''2:''' Rudder
**'''3:''' Elevators
**'''4:''' Ailerons
**'''5:''' Unknown
**'''6:''' Unknown

''NOTE:'' Settings are not applicable for all vehicles of these types, for instance panel 0 effects a Dodo, but does nothing to a hydra.

*'''state:''' How damaged the part is on the scale of 0 to 3, with 0 being undamaged and 3 being very damaged. How this is manifested depends on the panel and the vehicle.

==Returns==
Returns ''true'' if the panel state has been updated, ''false'' otherwise

==Example==
<section name="Example 1: Server" class="server" show="true">
<syntaxhighlight lang="lua">
-- create a new vehicle
local newcar = createVehicle ( 520, 1024, 1024, 1024 )
-- break the front bumper off
setVehiclePanelState ( newcar, 5, 3 )
</syntaxhighlight>
</section>

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

SetVehicleDoorState

2018-04-06T22:21:19Z

Skully: Added OOP syntax.

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

==Syntax==
<syntaxhighlight lang="lua">bool setVehicleDoorState ( vehicle theVehicle, int door, int state )</syntaxhighlight>
{{OOP||[[vehicle]]:setDoorState||getVehicleDoorState}}

==Required Arguments==
*'''theVehicle:''' The [[vehicle]] that you wish to change the door state of.
*'''door:''' An integer representing which door to set the state of. Valid values are:
**'''0:''' Hood
**'''1:''' Trunk
**'''2:''' Front left
**'''3:''' Front right
**'''4:''' Rear left
**'''5:''' Rear right
*'''state:''' An integer representing the state to set the door to. Valid values are:
**'''0:''' Shut, intact
**'''1:''' Ajar, intact
**'''2:''' Shut, damaged
**'''3:''' Ajar, damaged
**'''4:''' Missing

==Returns==
Returns ''true'' if the door state was successfully set, ''false'' otherwise.

==Example==
<syntaxhighlight lang="lua">
-- create a new vehicle
local newcar = createVehicle ( 520, 1024, 1024, 1024 )
-- break its front left door off
state = setVehicleDoorState ( newcar, 2, 4 )
</syntaxhighlight>

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

SetVehicleLightState

2018-04-06T22:05:38Z

Skully: Defined associated light to lights parameter.

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

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

==Required Arguments==
*'''theVehicle:''' A handle to the [[vehicle]] that you wish to change the light state of.
*'''light:''' A whole number determining the individual light:
**'''0:''' Front left
**'''1:''' Front right
**'''2:''' Rear right
**'''3:''' Rear left

*'''state:''' A whole number determining the new state of the light. ''0'' represents normal lights, and ''1'' represents broken lights.

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

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

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

User:Skully

2018-02-19T22:38:20Z

Skully: /* Hello! */

==Hello!==

I like dank memes, thanks for stopping by.

== Contact ==
*[https://forum.mtasa.com/profile/57023-skully/ Forum Profile]
*[https://github.com/ImSkully GitHub Profile]

PasswordHash

2018-02-19T19:53:02Z

Skully: Updated options parameter to be required.

__NOTOC__
{{Shared function}}
{{Note box|Using '''passwordHash''' is the recommended way of storing passwords.}}
{{New feature/item|3.0154|1.5.4|11277|
This function creates a new password hash using a specified hashing algorithm.
}}

{{Warning|It is strongly recommended to use the async version of the function (i.e. provide a callback function). Otherwise, you will experience short freezes due to the slow nature of the bcrypt algorithm}}
==Syntax==
<syntaxhighlight lang="lua">
string passwordHash ( string password, string algorithm, table options = {} [, function callback ])
</syntaxhighlight>

===Required Arguments===
*'''password:''' The password to hash.
*'''algorithm:''' The algorithm to use:
** ''bcrypt'': use the bcrypt hashing algorithm. Hash length: 60 characters. <span style="color:red">Note that only the prefix ''$2y$'' is supported (older prefixes can cause security issues).</span>
*'''options:''' table with options for the hashing algorithm, as detailed below.

===Optional Arguments===
{{New feature/item|3.0154|1.5.4|11281|
*'''callback:''' providing a callback will run this function asynchronously, the arguments to the callback are the same as the returned values below.
}}
===Options for each hashing algorithm===
* ''bcrypt'':
** ''cost'' (int), default: 10. Visit [http://security.stackexchange.com/questions/17207/recommended-of-rounds-for-bcrypt this link] to determine the number of rounds appropriate for your server.
** ''salt'' (string), default: automatically generate salt
*** an empty string will automatically generate a salt with the ''cost'' provided
*** if a string is provided, the given salt is used (do not do this!)
*** the provided string should be longer or equal than 22 characters

===Returns===
Returns the hash as a string if hashing was successful, ''false'' otherwise. If a callback was provided, the aforementioned values are arguments to the callback, and this function will always return ''true''.

==Example==
{{Warning|If you will be using "Example 1" then you will have to save account data "hash_password" after server restart, otherwise this script will no longer work.}}
This example makes use of [https://wiki.multitheftauto.com/wiki/PasswordHash passwordHash] and [https://wiki.multitheftauto.com/wiki/PasswordVerify passwordVerify] in account creation and account login to boost up security.
<section name="Example 1" class="server" show="true">
* Use '''</accountCreate [username] [password]>''' to create an account.
* Use '''</accountLogin [username] [password]>''' to login in account.
<syntaxhighlight lang="lua">
-- lets add command handler that will handle the account creation
addCommandHandler("accountCreate",function(source,cmd,username,password)
if (username and password) then
local hashedPassword = passwordHash(password,"bcrypt") -- create new hash for password
if (hashedPassword) then -- check if hash has been generated
local account = addAccount(username,hashedPassword) -- now lets add account with new hash what we got when we made it for password.
if (account) then
setAccountData(account,"hash_password",hashedPassword) -- store accounts password hash in order to verify it when it's needed.
outputChatBox("Account successfuly created! Now please login. Syntax </accountLogin [username] [password]>",source,20,160,20)
else
outputChatBox("Account already exists! Please try again with different username.",source,20,160,20)
end
else
outputChatBox("Securing your password failed! Please try again or contact an administrator.",source,160,20,20)
end
else
outputChatBox("Wrong parameters! Correct Syntax </accountCreate [username] [password]>",source,160,20,20)
end
end);

-- lets add command handler that will handle the account login
addCommandHandler("accountLogin",function(source,cmd,username,password)
if (username and password) then
local account = getAccount(username) -- get entered account
if (account) then -- check if entered account exists
local hashedPassword = getAccountData(account,"hash_password") -- lets get hashed password
if (passwordVerify(password,hashedPassword)) then -- check if hash and entered password matches
if logIn(source,account,hashedPassword) then -- now lets login player into account
outputChatBox("Login successfull. Welcome, "..getAccountName(account).."!",source,20,160,20)
end
else
outputChatBox("Password is incorrect!",source,160,20,20)
end
else
outputChatBox("Account doesn't exist! Please try again with different account.",source,160,20,20)
end
else
outputChatBox("Wrong parameters! Correct Syntax </accountLogin [username] [password]>",source,160,20,20)
end
end);
</syntaxhighlight>
</section>

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

Sha256

2018-02-17T05:34:08Z

Skully: Fixed typo and hyperlinked function.

__NOTOC__
{{Server client function}}

{{Note box|returns an uppercase string, so make sure you string.upper() anything else you are checking against that has been sha256'd elsewhere.}}
{{Tip|The sha module and this function may conflict with eachother, if you use this function uninstall the module!}}
{{Warning|It is strongly recommended to use [[passwordHash]] to hash passwords, because Sha256 is easily decodable.}}

Calculates the sha256 hash of the specified string.

==Syntax==
<syntaxhighlight lang="lua">string sha256 ( string str )</syntaxhighlight>

===Required Arguments===
*'''str:''' the string to hash.

===Returns===
Returns the sha256 hash of the input string if successful, ''false'' otherwise.

==Requirements==
{{Requirements|1.3.1-9.04836|1.3.1-9.04836|}}

==Example==
<syntaxhighlight lang="lua">
addCommandHandler ( "sha", -- Create a command
function ( thePlayer, command, input )
if ( input ) then -- Check if the string exist
local sha256hash = sha256( input ) -- Generate the hash
outputChatBox( sha256hash ) -- Output the hash in the chat
end
end
)
</syntaxhighlight>

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

User:Skully

2018-02-05T01:00:29Z

Skully:

==Hello!==

I like dank memes, thanks for stopping by.

'''Forum Profile:''' https://forum.mtasa.com/profile/57023-skully/

User talk:Thisdp

2018-02-05T00:59:19Z

Skully: Created page with "== DGS Wiki == Thanks for the great work on your resource and the Wiki itself, it's extremely useful! --~~~~"

== DGS Wiki ==
Thanks for the great work on your resource and the Wiki itself, it's extremely useful! --[[User:Skully|Skully]] ([[User talk:Skully|talk]]) 00:58, 5 February 2018 (UTC)

User:Skully

2018-02-05T00:54:15Z

Skully: Created page with "Hello! I like dank memes, thanks for stopping by."

Hello!

I like dank memes, thanks for stopping by.

DgsComboBoxGetSelectedItem

2018-02-05T00:52:21Z

Skully: /* Fixed error in example not calling exported function. */

{{Client function}}
__NOTOC__
This function returns the index of the selected dgs combobox item.

==Syntax==
<syntaxhighlight lang="lua">
int dgsComboBoxGetSelectedItem ( element comboBox )
</syntaxhighlight>

===Required Arguments===
*'''comboBox:''' the dgs combobox you want to know the selected item index of

===Returns===
Returns the index of the selected item if the specified dgs combobox is valid and has a selected item, ''-1'' if no item is selected, ''false'' or ''nil'' otherwise.

==Example==
This example outputs selected item's text and ID to the chat.
<syntaxhighlight lang="lua">
DGS = exports.dgs

comboBox = DGS:dgsCreateComboBox(200,200,100,30,false)
for i=1,5 do
DGS:dgsComboBoxAddItem(comboBox,i.."test")
end

addCommandHandler("getSelected",function (command)
local item = DGS:dgsComboBoxGetSelectedItem (comboBox)
local text = DGS:dgsComboBoxGetItemText(comboBox, item)
outputChatBox("Currently selected item with ID: " .. tostring(item) .. " and with text: " .. text)
end)
</syntaxhighlight>

==See Also==
{{DGSFUNCTIONS}}

TriggerClientEvent

2018-02-03T20:21:24Z

Skully: Parameter order fixed.

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

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

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

Keep in mind the bandwidth issues when using events - don't pass a large list of arguments unless you really need to. It is marginally more efficient to pass one large event than two smaller ones.
==Syntax==
<syntaxhighlight lang="lua">
bool triggerClientEvent ( [table/element sendTo=getRootElement()], string name, element sourceElement, [arguments...] )
</syntaxhighlight>
{{OOP||[[player]]:triggerEvent||}}

===Required Arguments===
*'''sourceElement:''' The element that is the [[Event system#Event handlers|source]] of the event.
*'''name:''' The name of the event to trigger client side. You should register this event with [[addEvent]] and add at least one event handler using [[addEventHandler]].
{{Note|To save client CPU, you should avoid setting '''sourceElement''' to the [[root element]] where possible. Using [[GetThisResource|resourceRoot]] is usually sufficient if the event is handled by the same resource on the client.}}

===Optional Arguments===
{{OptionalArg}}
*'''sendTo:''' The event will be sent to all [[player]]s that are children of the specified element. By default this is the root element, and hence the event is sent to all players. If you specify a single player it will just be sent to that player. This argument can also be a table of player elements.
*'''arguments...:''' A list of arguments to trigger with the event. You can pass any lua data type (except functions). You can also pass [[element]]s.

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

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

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function greetingHandler ( message )
outputChatBox ( "The server says: " .. message )
end
addEvent( "onGreeting", true )
addEventHandler( "onGreeting", localPlayer, greetingHandler )
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function greetingCommand ( playerSource, commandName )
triggerClientEvent ( playerSource, "onGreeting", playerSource, "Hello World!" )
end
addCommandHandler ( "greet", greetingCommand )
</syntaxhighlight>
</section>

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

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

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function greetingHandler ( message )
outputChatBox ( "The server says: " .. message )
end
addEvent( "onGreeting", true )
addEventHandler( "onGreeting", localPlayer, greetingHandler )
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function greetingCommandOne ( playerSource, commandName, playerName )
if playerName then
local thePlayer = getPlayerFromName ( playerName )
if thePlayer then
triggerClientEvent ( thePlayer, "onGreeting", thePlayer, "Hello World!" )
else
-- invalid player name specified
end
else
-- No player name specified
end
end
addCommandHandler ( "greet_one", greetingCommandOne )
</syntaxhighlight>
</section>

This works like the first example except an extra ''thePlayer'' argument is specified for triggerClientEvent.

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04570|Added option to use a list of player elements for the 'sendTo' argument}}

==See Also==
{{Event functions}}
[[ru:triggerClientEvent]]

Resource:DGS

2018-02-02T19:08:49Z

Skully: Another adjustment to fix grammatical issues and english.

<pageclass class="resource" subcaption="Resource"></pageclass>
[[Image:DGSNetStatus.png|300px|thumb|right|DGS Network Monitor]]

This resource is designed to allow you to create directX GUI's as an alternative to the original MTA:SA GUI functions.

'''Full Name''': Thisdp's DirectX Graphical User Interface System (DxGUI Lib)

'''Author''': [[User:thisdp|thisdp]]

'''State''': OpenSource (WIP)

'''GitHub Source''': https://github.com/thisdp/dgs/tree/master

=Features=

[[Image:DGSS.png|400px|thumb|right|]]

'''How does it work?'''
*DGS is just like the original gui system that is based on element system. I use a simple way that can make it easier to understand.
*DGS elements are rendered in "onClientRender". There is two or more tables store DGS elements. When "onClientRender" is called, "for" loop will loop and calculate every DGS element.

'''What's different?'''
*This resource is based on dx* functions. It allows us to edit our gui and make it in customlization.

'''Update System'''
*It have an update system that can keep your DGS latest.
*When a newer version has been pushed, it will detected and notice you to update dgs.
*Execute command "'''updatedgs'''" to check the least version and update your DGS.
*You can check the version of DGS by command "dgsver"

'''Update Logs'''
*'''You can view the update logs here: [http://angel.mtaip.cn:233/dgsUpdate/ Update Log]'''

'''You Should Know'''
*Scroll Pane, Grid List, Combo Box, Memo and Edit box use Render Target, which means if you don't have enough video memory, '''Render Target won't be created.'''

[[Image:Dx_7.PNG|400px|thumb|right|Example DGS Cmd]]

'''Examples scripts'''
*1.https://community.multitheftauto.com/index.php?p=resources&s=details&id=14757 By ([[User:Ahmed Ly|Ahmed Ly]] ,Mahmod Algeriany)
*2. Also File test.lua its have more Examples You can See it

'''Auto Completion'''
*1. Link: http://www.mediafire.com/file/m6dm7815d5dihax/lua.zip By [[User:Ahmed Ly|Ahmed Ly]]
*2. '''Note''': You must put it in file Notepad++\plugins\APIs.
*3. Not all of DGS Functions are added, but the rest will be added soon.

'''Debug'''
* You can enter the debug mode by executing the command "'''debugdgs'''".

'''DGS Type'''
[[Image:Dx Dgs.jpg|400px|thumb|right|Hurt World GUI Example]]
* Button (dgs-dxbutton): A button.
* Command (dgs-dxcmd): A command just like windows.
* Ellipse Detect Area (dgs-dxeda): An oval detect area.
* Edit (dgs-dxedit): An edit.
* Memo (dgs-dxmemo): A memo.
* Gridlist (dgs-dxgridlist): A grid list.
* Image (dgs-dximage): A dynamic image.
* Label (dgs-dxlabel): A text label.
* Ellipse Detect Area (EDA)
* ScrollBar (dgs-dxscrollbar): A scroll bar.
* ScrollPane (dgs-dxscrollpane): A scroll pane.
* Tab Panel (dgs-dxtabpanel + dgs-dxtab) : A tab panel.
* Window (dgs-dxwindow): A window.
* Progress Bar (dgs-dxprogressbar): A Progress Bar.
* Radio Button (dgs-dxradiobutton): A Radio Button.
* Combo Box (dgs-dxcombobox + dgs-dxcombobox-Box) : A combo box.
* Check Box (dgs-dxcheckbox) : A check box that with 3 states (checked, unchecked and indeterminate).

'''Notice'''
*It is recommended to change the resource name to 'dgs'.
*This is a resource, if you want to use the functions exported by this resource, you should use a exported function call in your code, such as "'''exports.dgs:dgsCreateLabel(0, 0, 0.5, 0.1, "text", true)'''".
*Here is a feasible way to shorten the name of an exported function:
<syntaxhighlight lang="lua">
DGS = exports.dgs --shorten the export function prefix
label = DGS:dgsCreateLabel(0,0,0.5,0.1,"text",false) --create a label
</syntaxhighlight>

'''Special thanks to the following for their help''':
[[Image:Tab.PNG |200px|thumb|right|Example tab panel and label .]]
* Axel: Gives some tips and provide some functions.
* Senpai: Helps write wiki.
* ZoNe: Helps write wiki.
* DiGiTal: Helps write wiki.
* #Dv^: Helps write wiki.

Special thanks to:
* Ahmed Ly: Helps write wiki, release auto completion for N++.

='''DGS Element Properties'''=
{{DGSPROPERTIES}}

='''Client Functions'''=
{{DGSFUNCTIONS}}

=Client Events=
{{DGSEVENTS}}

=Last=
'''Everyone is welcome to make suggestions, test the script, help make adjustments/finish the wiki, etc.'''
[[Category:Resource]]

[[ZH-CN:Dgs]]

Resource:DGS

2018-02-02T19:05:25Z

Skully: Adjusted grammar and fixed english.

<pageclass class="resource" subcaption="Resource"></pageclass>
[[Image:DGSNetStatus.png|300px|thumb|right|DGS Network Monitor]]

This resource is designed to allow you to create directX GUI's as an alternative to the original MTA:SA GUI functions.

'''Full Name''': Thisdp's DirectX Graphical User Interface System (DxGUI Lib)

'''Author''': [[User:thisdp|thisdp]]

'''State''': OpenSource (WIP)

'''GitHub Source''': https://github.com/thisdp/dgs/tree/master

=Features=

[[Image:DGSS.png|400px|thumb|right|]]

'''How does it work?'''
*DGS is just like the original gui system that is based on element system. I use a simple way that can make it easier to understand.
*DGS elements are rendered in "onClientRender". There is two or more tables store DGS elements. When "onClientRender" is called, "for" loop will loop and calculate every DGS element.

'''What's different?'''
*This resource is based on dx* functions. It allows us to edit our gui and make it in customlization.

'''Update System'''
*It have an update system that can keep your DGS latest.
*When a newer version has been pushed, it will detected and notice you to update dgs.
*Execute command "'''updatedgs'''" to check the least version and update your DGS.
*You can check the version of DGS by command "dgsver"

'''Update Logs'''
*'''[http://angel.mtaip.cn:233/dgsUpdate/ Update Log]'''

'''You Should Know'''
*'''Scroll Pane/Grid List/Combo Box/Memo/Edit use Render Target, which means if you don't have enough video memory, Render Target won't be created.'''

[[Image:Dx_7.PNG|400px|thumb|right|Example DGS Cmd]]

'''Examples scripts'''
*1.https://community.multitheftauto.com/index.php?p=resources&s=details&id=14757 By ([[User:Ahmed Ly|Ahmed Ly]] ,Mahmod Algeriany)
*2. Also File test.lua its have more Examples You can See it

'''Auto Completion'''
*1.link:http://www.mediafire.com/file/m6dm7815d5dihax/lua.zip By [[User:Ahmed Ly|Ahmed Ly]]
*'''Note''':
*2.You must put it in file Notepad++\plugins\APIs.
*3.Not all of DGS Functions are added, but the rest will be added soon.

'''Debug'''
*You can enter the debug mode by executing the command "'''debugdgs'''".

'''DGS Type'''
[[Image:Dx Dgs.jpg|400px|thumb|right|Hurt World GUI Example]]
* Button (dgs-dxbutton): A button.
* Command (dgs-dxcmd): A command just like windows.
* Ellipse Detect Area (dgs-dxeda): An oval detect area.
* Edit (dgs-dxedit): An edit.
* Memo (dgs-dxmemo): A memo.
* Gridlist (dgs-dxgridlist): A grid list.
* Image (dgs-dximage): A dynamic image.
* Label (dgs-dxlabel): A text label.
* Ellipse Detect Area (EDA)
* ScrollBar (dgs-dxscrollbar): A scroll bar.
* ScrollPane (dgs-dxscrollpane): A scroll pane.
* Tab Panel (dgs-dxtabpanel + dgs-dxtab) : A tab panel.
* Window (dgs-dxwindow): A window.
* Progress Bar (dgs-dxprogressbar): A Progress Bar.
* Radio Button (dgs-dxradiobutton): A Radio Button.
* Combo Box (dgs-dxcombobox + dgs-dxcombobox-Box) : A combo box.
* Check Box (dgs-dxcheckbox) : A check box that with 3 states (checked, unchecked and indeterminate).

'''Notice'''
*It is recommended to change the resource name to 'dgs'.
*This is a resource, if you want to use the functions exported by this resource, you should use a exported function call in your code, such as "'''exports.dgs:dgsCreateLabel(0, 0, 0.5, 0.1, "text", true)'''".
*Here is a feasible way to shorten the name of an exported function:
<syntaxhighlight lang="lua">
DGS = exports.dgs --shorten the export function prefix
label = DGS:dgsCreateLabel(0,0,0.5,0.1,"text",false) --create a label
</syntaxhighlight>

'''Special thanks to the following for their help''' :
[[Image:Tab.PNG |200px|thumb|right|Example tab panel and label .]]
* Axel: Gives some tips and provide some functions.
* Senpai: Helps write wiki.
* ZoNe: Helps write wiki.
* DiGiTal: Helps write wiki.
* #Dv^: Helps write wiki.
-->Especially For:
* Ahmed Ly: Helps write wiki, release auto completion for N++.

='''DGS Element Properties'''=
{{DGSPROPERTIES}}

='''Client Functions'''=
{{DGSFUNCTIONS}}

=Client Events=
{{DGSEVENTS}}

=Last=
'''Everyone is welcome to make suggestions, test the script, help make adjustments/finish the wiki, etc.'''
[[Category:Resource]]

[[ZH-CN:Dgs]]

ToggleControl

2017-09-14T13:53:46Z

Skully:

__NOTOC__
{{Server client function}}
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.
*'''enabled:''' 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.
*'''enabled:''' 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}}

GetElementSpeed

2017-09-14T13:51:19Z

Skully: /* Optional arguments */

__NOTOC__
{{Useful Function}}
This function returns the speed of an element in m/s, km/h or mph.

==Syntax==
<syntaxhighlight lang="lua">
float/nil getElementSpeed ( element theElement [, int/string unit="m/s" ] )
</syntaxhighlight>

===Required arguments===
* '''theElement''': the [[element]] you want to get the speed of. Compatible [[element]] types are:
** [[Player|Players]]
** [[Ped|Peds]]
** [[Object|Objects]]
** [[Vehicle|Vehicles]]
** [[Projectile|Projectiles]]

===Optional arguments===
{{OptionalArg}}
* '''Unit''': The unit of the speed returned. If not specified, the unit will be ''m/s''. It can be specified as a ''[[string]]'' or ''number'' as follows:
** '''0''' or '''m/s''': meters per second (speed unit of the [http://en.wikipedia.org/wiki/International_System_of_Units International System of Units], used in formal contexts).
** '''1''' or '''km/h''': kilometres per hour (the most common speed unit, used in most countries).
** '''2''' or '''mph''': miles per hour (used in some English-speaking countries).

==Returns==
This function returns a ''number'' containing the [[element]]'s speed if the arguments provided are valid. It returns ''[[nil]]'' plus an ''error'' otherwise.

==Code==
<section name="Function source" class="both" show="true">
'''It is recommended to use MTA:SA 1.4''' or higher with this function to use [[OOP]].
<syntaxhighlight lang="lua">
function getElementSpeed(theElement, unit)
-- Check arguments for errors
assert(isElement(theElement), "Bad argument 1 @ getElementSpeed (element expected, got " .. type(theElement) .. ")")
local elementType = getElementType(theElement)
assert(elementType == "player" or elementType == "ped" or elementType == "object" or elementType == "vehicle" or elementType == "projectile", "Invalid element type @ getElementSpeed (player/ped/object/vehicle/projectile expected, got " .. elementType .. ")")
assert((unit == nil or type(unit) == "string" or type(unit) == "number") and (unit == nil or (tonumber(unit) and (tonumber(unit) == 0 or tonumber(unit) == 1 or tonumber(unit) == 2)) or unit == "m/s" or unit == "km/h" or unit == "mph"), "Bad argument 2 @ getElementSpeed (invalid speed unit)")
-- Default to m/s if no unit specified and 'ignore' argument type if the string contains a number
unit = unit == nil and 0 or ((not tonumber(unit)) and unit or tonumber(unit))
-- Setup our multiplier to convert the velocity to the specified unit
local mult = (unit == 0 or unit == "m/s") and 50 or ((unit == 1 or unit == "km/h") and 180 or 111.84681456)
-- Return the speed by calculating the length of the velocity vector, after converting the velocity to the specified unit
return (Vector3(getElementVelocity(theElement)) * mult).length
end
</syntaxhighlight>
</section>

==Example==
<section name="Clientside example" class="client" show="true">
This example draws the local player's speed rounded to a single decimal in the top-right corner of the screen in different units.
<syntaxhighlight lang="lua">
local sx = guiGetScreenSize()
local function drawSpeed()
local speedms, speedkmh, speedmph = getElementSpeed(localPlayer), getElementSpeed(localPlayer, 1), getElementSpeed(localPlayer, 2)
local roundedSpeedms, roundedSpeedkmh, roundedSpeedmph = math.floor(speedms) == speedms and speedms or string.format(speedms, "%.1f"), math.floor(speedkmh) == speedkmh and speedkmh or string.format(speedkmh, "%.1f"), math.floor(speedmph) == speedmph and speedmph or string.format(speedmph, "%.1f")
local speedoText = "Current speed: " .. roundedSpeedms .. " m/s | " .. roundedSpeedkmh .. " km/h | " .. roundedSpeedmph .. " mph"
dxDrawText(speedoText, sx - dxGetTextWidth(speedoText), 0)
end
addEventHandler("onClientPreRender", root, drawSpeed)
</syntaxhighlight>
</section>

==See also==
{{Useful_Functions}}

GetElementSpeed

2017-09-14T13:50:00Z

Skully: /* English improved. */

__NOTOC__
{{Useful Function}}
This function returns the speed of an element in m/s, km/h or mph.

==Syntax==
<syntaxhighlight lang="lua">
float/nil getElementSpeed ( element theElement [, int/string unit="m/s" ] )
</syntaxhighlight>

===Required arguments===
* '''theElement''': the [[element]] you want to get the speed of. Compatible [[element]] types are:
** [[Player|Players]]
** [[Ped|Peds]]
** [[Object|Objects]]
** [[Vehicle|Vehicles]]
** [[Projectile|Projectiles]]

===Optional arguments===
{{OptionalArg}}
* '''unit''': the unit of the speed returned. If not specified, the unit will be ''m/s''. It can be specified as a ''[[string]]'' or ''number'' as follows:
** '''0''' or '''m/s''': meters per second (speed unit of the [http://en.wikipedia.org/wiki/International_System_of_Units International System of Units], used in formal contexts).
** '''1''' or '''km/h''': kilometres per hour (the most common speed unit, used in most countries).
** '''2''' or '''mph''': miles per hour (used in some English-speaking countries).

==Returns==
This function returns a ''number'' containing the [[element]]'s speed if the arguments provided are valid. It returns ''[[nil]]'' plus an ''error'' otherwise.

==Code==
<section name="Function source" class="both" show="true">
'''It is recommended to use MTA:SA 1.4''' or higher with this function to use [[OOP]].
<syntaxhighlight lang="lua">
function getElementSpeed(theElement, unit)
-- Check arguments for errors
assert(isElement(theElement), "Bad argument 1 @ getElementSpeed (element expected, got " .. type(theElement) .. ")")
local elementType = getElementType(theElement)
assert(elementType == "player" or elementType == "ped" or elementType == "object" or elementType == "vehicle" or elementType == "projectile", "Invalid element type @ getElementSpeed (player/ped/object/vehicle/projectile expected, got " .. elementType .. ")")
assert((unit == nil or type(unit) == "string" or type(unit) == "number") and (unit == nil or (tonumber(unit) and (tonumber(unit) == 0 or tonumber(unit) == 1 or tonumber(unit) == 2)) or unit == "m/s" or unit == "km/h" or unit == "mph"), "Bad argument 2 @ getElementSpeed (invalid speed unit)")
-- Default to m/s if no unit specified and 'ignore' argument type if the string contains a number
unit = unit == nil and 0 or ((not tonumber(unit)) and unit or tonumber(unit))
-- Setup our multiplier to convert the velocity to the specified unit
local mult = (unit == 0 or unit == "m/s") and 50 or ((unit == 1 or unit == "km/h") and 180 or 111.84681456)
-- Return the speed by calculating the length of the velocity vector, after converting the velocity to the specified unit
return (Vector3(getElementVelocity(theElement)) * mult).length
end
</syntaxhighlight>
</section>

==Example==
<section name="Clientside example" class="client" show="true">
This example draws the local player's speed rounded to a single decimal in the top-right corner of the screen in different units.
<syntaxhighlight lang="lua">
local sx = guiGetScreenSize()
local function drawSpeed()
local speedms, speedkmh, speedmph = getElementSpeed(localPlayer), getElementSpeed(localPlayer, 1), getElementSpeed(localPlayer, 2)
local roundedSpeedms, roundedSpeedkmh, roundedSpeedmph = math.floor(speedms) == speedms and speedms or string.format(speedms, "%.1f"), math.floor(speedkmh) == speedkmh and speedkmh or string.format(speedkmh, "%.1f"), math.floor(speedmph) == speedmph and speedmph or string.format(speedmph, "%.1f")
local speedoText = "Current speed: " .. roundedSpeedms .. " m/s | " .. roundedSpeedkmh .. " km/h | " .. roundedSpeedmph .. " mph"
dxDrawText(speedoText, sx - dxGetTextWidth(speedoText), 0)
end
addEventHandler("onClientPreRender", root, drawSpeed)
</syntaxhighlight>
</section>

==See also==
{{Useful_Functions}}

GetElementSpeed

2017-09-14T13:49:02Z

Skully: /* Code */

__NOTOC__
{{Useful Function}}
This function returns the speed of an element in m/s, km/h or mph.

==Syntax==
<syntaxhighlight lang="lua">
float/nil getElementSpeed ( element theElement [, int/string unit="m/s" ] )
</syntaxhighlight>

===Required arguments===
* '''theElement''': the [[element]] you want to get the speed of. Compatible [[element]] types are:
** [[Player|Players]]
** [[Ped|Peds]]
** [[Object|Objects]]
** [[Vehicle|Vehicles]]
** [[Projectile|Projectiles]]

===Optional arguments===
{{OptionalArg}}
* '''unit''': the unit of the speed returned. If not specified, the unit will be ''m/s''. It can be specified as a ''[[string]]'' or ''number'' as follows:
** '''0''' or '''m/s''': meters per second (speed unit of the [http://en.wikipedia.org/wiki/International_System_of_Units International System of Units], used in formal contexts).
** '''1''' or '''km/h''': kilometres per hour (the most common speed unit, used in most countries).
** '''2''' or '''mph''': miles per hour (used in some English-speaking countries).

==Returns==
This function returns a ''number'' containing the [[element]]'s speed if the arguments provided are valid. It returns ''[[nil]]'' plus an ''error'' otherwise.

==Code==
<section name="Function source" class="both" show="true">
'''It is recommended to use MTA:SA 1.4''' or higher with this function to use [[OOP]].
<syntaxhighlight lang="lua">
function getElementSpeed(theElement, unit)
-- Check arguments for errors
assert(isElement(theElement), "Bad argument 1 @ getElementSpeed (element expected, got " .. type(theElement) .. ")")
local elementType = getElementType(theElement)
assert(elementType == "player" or elementType == "ped" or elementType == "object" or elementType == "vehicle" or elementType == "projectile", "Invalid element type @ getElementSpeed (player/ped/object/vehicle/projectile expected, got " .. elementType .. ")")
assert((unit == nil or type(unit) == "string" or type(unit) == "number") and (unit == nil or (tonumber(unit) and (tonumber(unit) == 0 or tonumber(unit) == 1 or tonumber(unit) == 2)) or unit == "m/s" or unit == "km/h" or unit == "mph"), "Bad argument 2 @ getElementSpeed (invalid speed unit)")
-- Default to m/s if no unit specified and 'ignore' argument type if the string contains a number
unit = unit == nil and 0 or ((not tonumber(unit)) and unit or tonumber(unit))
-- Setup our multiplier to convert the velocity to the specified unit
local mult = (unit == 0 or unit == "m/s") and 50 or ((unit == 1 or unit == "km/h") and 180 or 111.84681456)
-- Return the speed by calculating the length of the velocity vector, after converting the velocity to the specified unit
return (Vector3(getElementVelocity(theElement)) * mult).length
end
</syntaxhighlight>
</section>

==Example==
<section name="Clientside example" class="client" show="true">
This example draws the local player's speed rounded to a single decimal in the up-right corner of the screen in different units.
<syntaxhighlight lang="lua">
local sx = guiGetScreenSize()
local function drawSpeed()
local speedms, speedkmh, speedmph = getElementSpeed(localPlayer), getElementSpeed(localPlayer, 1), getElementSpeed(localPlayer, 2)
local roundedSpeedms, roundedSpeedkmh, roundedSpeedmph = math.floor(speedms) == speedms and speedms or string.format(speedms, "%.1f"), math.floor(speedkmh) == speedkmh and speedkmh or string.format(speedkmh, "%.1f"), math.floor(speedmph) == speedmph and speedmph or string.format(speedmph, "%.1f")
local speedoText = "Current speed: " .. roundedSpeedms .. " m/s | " .. roundedSpeedkmh .. " km/h | " .. roundedSpeedmph .. " mph"
dxDrawText(speedoText, sx - dxGetTextWidth(speedoText), 0)
end
addEventHandler("onClientPreRender", root, drawSpeed)
</syntaxhighlight>
</section>

==See also==
{{Useful_Functions}}