Multi Theft Auto: Wiki - User contributions [en]

RefreshResource

2016-01-23T14:23:52Z

VenadHD:

{{Useful Function}}
<lowercasetitle/>
__NOTOC__
This code refreshes your resource if any part of the code or some resource file has changed, it works just like "refreshResources ()" but adapted for one particular resource
==Syntax==
<syntaxhighlight lang="lua">refreshResource()</syntaxhighlight>

==Return==
Returns '''false''' if none has changed
==code==
<syntaxhighlight lang="lua">
local Bytes = 0
addEventHandler("onResourceStart", resourceRoot,
function()
local meta = xmlLoadFile(":"..getResourceName(getThisResource()).."/meta.xml")
if meta then
for k,v in ipairs(xmlNodeGetChildren(meta)) do
if fileExists(xmlNodeGetAttribute(v, "src")) then
local file = fileOpen(xmlNodeGetAttribute(v, "src"))
local _ = fileGetSize(file)
Bytes = Bytes + _
fileClose(file)
end
end
end
end
)
--USEFUL FUNCTION
function refreshResource ()
local newBytes = 0
local meta = xmlLoadFile(":"..getResourceName(getThisResource()).."/meta.xml")
if meta then
for k,v in ipairs(xmlNodeGetChildren(meta)) do
if fileExists(xmlNodeGetAttribute(v, "src")) then
local file = fileOpen(xmlNodeGetAttribute(v, "src"))
local _ = fileGetSize(file)
newBytes = newBytes + _
fileClose(file)
end
end
if newBytes ~= Bytes then
print(getResourceName(getThisResource()).." has changed.. reloading...")
restartResource(getThisResource())
else
return false
end
end
end
</syntaxhighlight>

==Example==
<section name="Example" class="server" show="true">
TODO.
<syntaxhighlight lang="lua">
TODO
</syntaxhighlight>
</section>

==See Also==
{{Useful_Functions}}

Template:Useful Functions

2016-01-04T23:01:57Z

VenadHD:

*[[attachEffect]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows you attach an effect to an element.</span>
*[[bindControlKeys]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows you to bind each key bound to a control individually. Doing this bypasses a little MTA restriction.</span>
*[[callClientFunction]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows you to call any client-side function from the server's side.</span>
*[[callServerFunction]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows you to call any server-side function from the client's side.</span>
*[[capitalize]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function capitalizes a given string.</span>
*[[centerWindow]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function centers a CEGUI window element responsively in any resolution.</span>
*[[Check]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks if its arguments are of the right type and calls the error-function if one is not.</span>
*[[convertNumber]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function converts and formats large numbers.</span>
*[[convertServerTickToTimeStamp]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function converts server ticks to a unix timestamp.</span>
*[[convertTextToSpeech]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function converts the provided text to a speech in the provided language which players can hear.</span>
*[[coroutine.resume]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function applies a fix for hidden coroutine error messages.</span>
*[[dxDrawAnimWindow]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function draws an animated 2D window on the screen.</span>
*[[dxDrawCircle]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function draws a number of 2D lines in order to achieve a circle shape on the screen.</span>
*[[dxDrawEmptyRectangle]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function draws an empty 2D rectangle on the screen.</span>
*[[dxDrawGifImage]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function simulates the effect of a GIF image by using image sprites in 2D.</span>
*[[dxDrawImage3D]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function draws a 3D image in GTA world.</span>
*[[dxDrawLoading]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function draws a loading bar on the screen.</span>
*[[dxDrawRectangle3D]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function draws a 3D rectangle in GTA world.</span>
*[[dxGetFontSizeFromHeight]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function calculates the font size from given height.</span>
*[[dxGetRealFontHeight]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function calculates the height of a font.</span>
*[[findRotation]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function takes two points and returns the direction from point A to point B.</span>
*[[FormatDate]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function formats a date on the basis of a format string and returns it.</span>
*[[generateString]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function generates a random string with any characters.</span>
*[[generateRandomASCIIString]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a random string which uses ASCII characters. </span>
*[[getAge]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function calculates the age of a given birthday.</span>
*[[getAlivePlayers (Client)|getAlivePlayers]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a table of the alive players client-side.</span>
*[[getAlivePlayersInTeam]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a table of the alive players in a team.</span>
*[[getBanFromName]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This functions returns the ban of the given playername.</span>
*[[getBoundControls]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a table of control names that are bound to the specified key.</span>
*[[getCurrentFPS]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns the frames per second at which GTA: SA is running.</span>
*[[getCursorMoveOn]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks in which way the cursor is currently moving.</span>
*[[getDistanceBetweenPointAndSegment2D]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function takes point coordinates and line (a segment) starting and ending coordinates. It returns the shortest distance between the point and the line.</span>
*[[getElementSpeed]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns the specified element's speed in m/s, km/h or mph.</span>
*[[getElementsInDimension]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a table of elements that are in the specified dimension.</span>
*[[getElementsWithinMarker]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a table of elements that are within a marker's collision shape.</span>
*[[getJetpackWeaponsEnabled]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a table of enabled weapons usable on a jetpack.</span>
*[[getKeyFromValueInTable]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns the key of the specified value in a table.</span>
*[[getOffsetFromXYZ]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.</span>
*[[getOnlineAdmins]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a table of all logged-in administrators.</span>
*[[getOnlineStaff]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a string of all logged-in administrators separated by two whitespace characters.</span>
*[[getPedMaxHealth]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a pedestrians's maximum health by converting it from their maximum health stat.</span>
*[[getPedMaxOxygenLevel]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a ped's maximum oxygen level by converting it from their maximum underwater stamina stat.</span>
*[[getPlayerFromNamePart]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a player from partial name.</span>
*[[getPlayerFromSerial]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a player from their serial.</span>
*[[getPlayerAcls]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a table of all ACL groups on a player.</span>
*[[getPlayersByData]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a table of players that have the specified data name.</span>
*[[getPlayersInPhotograph]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a table of all players in photograph.</span>
*[[getPointFromDistanceRotation]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function finds a point based on a starting point, direction and distance.</span>
*[[getResourceSettings]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a table of the resource settings.</span>
*[[getResourceScripts]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a table of the resource scripts.</span>
*[[getRGColorFromPercentage]] <span style="color:gray; font-family:'Georgia', sans-serif; font-size:smaller;">»This function returns two integers representing red and green colors according to the specified percentage.</span>
*[[getScreenRotationFromWorldPosition]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a screen relative rotation to a world position.</span>
*[[getTeamFromColor]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a team element by the specified color.</span>
*[[getTeamWithFewestPlayers]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a team element with least players of all the specified teams.</span>
*[[getTimestamp]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns the UNIX timestamp of a specified date and time.</span>
*[[getValidVehicleModels]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a table of all valid vehicle models.</span>
*[[getVehicleRespawnPosition]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows you to get the respawn position of a vehicle.</span>
*[[getXMLNodes]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns all children of a XML node.</span>
*[[getGridListRowIndexFromText]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns the GridList row index from the specified text.</span>
*[[guiComboBoxAdjustHeight]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function adjusts a CEGUI combobox element to have the correct height.</span>
*[[guiGridListGetSelectedText]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a string containing the inner text of a selected gridlist item.</span>
*[[IfElse]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns one of two values based on a boolean expression.</span>
*[[isCursorOnElement]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks whether the cursor is in a particular area.</span>
*[[isElementInPhotograph]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks if an element is in the player's camera picture area.</span>
*[[isElementInRange]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows you to check if an element's range to a main point is within the maximum range.</span>
*[[isElementMoving]]<span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks if an element is moving.</span>
*[[isElementWithinAColShape]]<span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks if an element is within a collision shape element.</span>
*[[isLeapYear]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a boolean representing if a given year is a leap year.</span>
*[[isMouseInPosition]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows you to check whether the mouse cursor/pointer is within a rectangular position.</span>
*[[isPedAiming]]<span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks if a pedestrian is aiming their weapon.</span>
*[[isPedDrivingVehicle]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks if a specified pedestrian is driving a vehicle.</span>
*[[isPlayerInACL]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks if a player element is in an ACL group.</span>
*[[isPlayerInTeam]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks if a player is in a specified team.</span>
*[[isSoundFinished]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks if a sound element has finished.</span>
*[[isVehicleEmpty]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks whether a vehicle is empty.</span>
*[[isVehicleOccupied]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks if a specified vehicle is occupied.</span>
*[[isVehicleOnRoof]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks whether vehicle is on roof.</span>
*[[isPedAimingNearPed]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This is similar to isPedAiming but uses a colshape to be more precise.</span>
*[[isTextInGridList]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks if some text exist or not in the GridList.</span>
*[[iterElements]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns ''a time-saving'' iterator for your for-loops.</span>
*[[mathNumber]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function is a workaround for the client-side floating-point precision of 24-bits.</span>
*[[math.percent]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a percentage from two number values.</span>
*[[math.round]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» Rounds a number whereas the number of decimals to keep and the method may be set.</span>
*[[multi_check]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks one element to many, handy and clean.</span>
*[[onVehicleWeaponFire]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This code implements an event that is triggered when a player in a vehicle fires a vehicle's weapon.</span>
*[[rangeToTable]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function converts a string range to a table containing number values.</span>
*[[refreshResource]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function refreshes your resource if you changed any of the files
*[[renameAclGroup]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function gives an existing ACL group a new name.</span>
*[[RGBToHex]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns a string representing the color in hexadecimal.</span>
*[[secondsToTimeDesc]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function converts a plain seconds-integer into a user-friendly time description.</span>
*[[setAccountName]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function is used to change an existing account's name.</span>
*[[setElementSpeed]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows you to set the speed of an element in kph or mph units.</span>
*[[setTableProtected]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function protects a table and makes it read-only.</span>
*[[setVehicleGravityPoint]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function sets a vehicle's gravity in the direction of a 3 dimensional coordinate with the strength specified.</span>
*[[smoothMoveCamera]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows you to create a cinematic camera flight.
*[[string.count]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function counts the amount of occurences of a string in a string.</span>
*[[string.explode]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function splits a string at a given separator pattern and returns a table with the pieces.</span>
*[[switch]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows the value of a variable or expression to control the flow of program execution via a multiway branch.</span>
*[[table.copy]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function copies a whole table and all the tables in that table.</span>
*[[table.compare]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks whether two given tables are equal.</span>
*[[table.empty]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function checks whether a table is empty.</span>
*[[table.map]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function goes through a table and replaces every field with the return of the passed function, where the field's value is passed as first argument and optionally more arguments.</span>
*[[table.merge]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function merges two or more tables together.</span>
*[[table.random]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function retrieves a random value from a table.</span>
*[[table.size]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function returns the absolute size of a table.</span>
*[[table.removeValue]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function removes a specified value from a table.</span>
*[[toHex]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function converts a decimal number to a hexadecimal number, as a fix to be used client-side.</span>
*[[unbindControlKeys]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function allows you to unbind each key bound to a control individually. Use this function with [[bindControlKeys]].</span>
*[[var dump]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function outputs information about one or more variables using outputConsole.</span>
*[[wavelengthToRGBA]] <span style="color:gray; font-family:'Georgia',sans-serif; font-size:smaller;">» This function converts a physical wavelength of light to a RGBA color.</span>
[[Category:Useful Functions]]

RefreshResource

2016-01-04T22:54:36Z

VenadHD:

{{Useful Function}}
<lowercasetitle/>
__NOTOC__
This code refreshes your resource if any part of the code or some resource file has changed, it works just like "refreshResources ()" but adapted for one particular resource
==Syntax==
<syntaxhighlight lang="lua">refreshResource()</syntaxhighlight>

==Return==
Returns '''false''' if none has changed
==code==
<syntaxhighlight lang="lua">
local files = {}
local Bytes = 0
addEventHandler("onResourceStart", resourceRoot,
function()
local meta = xmlLoadFile(":"..getResourceName(getThisResource()).."/meta.xml")
if meta then
for k,v in ipairs(xmlNodeGetChildren(meta)) do
if fileExists(xmlNodeGetAttribute(v, "src")) then
local file = fileOpen(xmlNodeGetAttribute(v, "src"))
local _ = fileGetSize(file)
Bytes = Bytes + _
files[xmlNodeGetAttribute(v, "src")] = _
fileClose(file)
end
end
end
end
)
--USEFUL FUNCTION
function refreshResource ()
local newBytes = 0
local meta = xmlLoadFile(":"..getResourceName(getThisResource()).."/meta.xml")
if meta then
for k,v in ipairs(xmlNodeGetChildren(meta)) do
if fileExists(xmlNodeGetAttribute(v, "src")) then
local file = fileOpen(xmlNodeGetAttribute(v, "src"))
local _ = fileGetSize(file)
newBytes = newBytes + _
fileClose(file)
end
end
if newBytes ~= Bytes then
print(getResourceName(getThisResource()).." has changed.. reloading...")
restartResource(getThisResource())
else
return false
end
end
end
</syntaxhighlight>

==Example==
<section name="Example" class="server" show="true">
TODO.
<syntaxhighlight lang="lua">
TODO
</syntaxhighlight>
</section>

==See Also==
{{Useful_Functions}}

RefreshResource

2016-01-04T22:54:09Z

VenadHD: Created page with "{{Useful Function}} <lowercasetitle/> __NOTOC__ This code refreshes your resource if any part of the code or some resource file has changed, it works just like "refreshResourc..."

{{Useful Function}}
<lowercasetitle/>
__NOTOC__
This code refreshes your resource if any part of the code or some resource file has changed, it works just like "refreshResources ()" but adapted for one particular resource
==Syntax==
<syntaxhighlight lang="lua">refreshResource()</syntaxhighlight>

==Return==
Returns '''false''' if none has changed
==code==
<syntaxhighlight lang="lua">
local files = {}
local Bytes = 0
addEventHandler("onResourceStart", resourceRoot,
function()
local meta = xmlLoadFile(":"..getResourceName(getThisResource()).."/meta.xml")
if meta then
for k,v in ipairs(xmlNodeGetChildren(meta)) do
if fileExists(xmlNodeGetAttribute(v, "src")) then
local file = fileOpen(xmlNodeGetAttribute(v, "src"))
local _ = fileGetSize(file)
Bytes = Bytes + _
files[xmlNodeGetAttribute(v, "src")] = _
fileClose(file)
end
end
end
end
)
--USEFULL FUNCTION
function refreshResource ()
local newBytes = 0
local meta = xmlLoadFile(":"..getResourceName(getThisResource()).."/meta.xml")
if meta then
for k,v in ipairs(xmlNodeGetChildren(meta)) do
if fileExists(xmlNodeGetAttribute(v, "src")) then
local file = fileOpen(xmlNodeGetAttribute(v, "src"))
local _ = fileGetSize(file)
newBytes = newBytes + _
fileClose(file)
end
end
if newBytes ~= Bytes then
print(getResourceName(getThisResource()).." has changed.. reloading...")
restartResource(getThisResource())
else
return false
end
end
end
</syntaxhighlight>

==Example==
<section name="Example" class="server" show="true">
TODO.
<syntaxhighlight lang="lua">
TODO
</syntaxhighlight>
</section>

==See Also==
{{Useful_Functions}}

CancelLatentEvent

2015-08-19T16:44:46Z

VenadHD:

{{Needs_Example}}
__NOTOC__
{{Server client function}}
Stops a latent event from completing

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool cancelLatentEvent( player thePlayer, int handle )
</syntaxhighlight>
===Required Arguments===
*'''thePlayer:''' The player who is receiving the event.
*'''handle:''' A handle previous got from [[getLatentEventHandles]].
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool cancelLatentEvent( int handle )
</syntaxhighlight>
===Required Arguments===
*'''handle:''' A handle previous got from [[getLatentEventHandles]].
</section>

===Returns===
Returns a true if the latent event was successfully cancelled, or false if it was not

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

==Requirements==
{{Requirements|1.3.0-9.03772|1.3.0-9.03772|}}

==See Also==
{{Event functions}}

EngineReplaceCOL

2015-08-19T16:41:53Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}
{{Note box|Please note the loading order that is used in the examples as other orders can cause collisions, textures or the DFF not to load due to technical limitations}}

This function replaces the collision file of the given model id to the collision file passed. Use [[engineLoadCOL]] to load the collision file first.

'''Note:''' Collision libraries (.col files containing multiple collision models) are not supported. See [[COL]] for details. Object models are supported only (no vehicles or players).

==Syntax==
<syntaxhighlight lang="lua">
bool engineReplaceCOL ( col theCol, int modelID )
</syntaxhighlight>
{{OOP||[[COL|col]]:replace}}
===Required Arguments===
*'''theCol:''' The collision file to replace with
*'''modelID:''' The model ID whose collision file you want to replace

===Returns===
Returns ''true'' if the collision was successfully replaced, ''false'' or ''nil'' if the collision could not be replaced for a reason.

==Example==
<section name="Client" class="client" show="true">
Client-Side example for replacing object collision with custom one.
<syntaxhighlight lang="lua">
function ReplaceCollision ( )
outputChatBox ( "> Replacing Collision Data." )
col = engineLoadCOL( "myColFile.col" )
engineReplaceCOL( col, 3356 )
end

addEvent ( "collisionReplace", true )
addEventHandler ( "collisionReplace", root, ReplaceCollision )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
Server-side example function for triggering the replace.
<syntaxhighlight lang="lua">
function ReplaceCols ( )
triggerClientEvent ( "collisionReplace", root, collisionReplace )
end
addCommandHandler("replacecol", ReplaceCols)
</syntaxhighlight>
</section>

==See Also==

{{Engine_functions}}

Element tree

2015-08-19T16:41:18Z

VenadHD: /* Tree elements */

[[File:Tre.png|frame|Element tree]]
MTA uses a so-called ''element tree'' to store all the elements that exist on the server and the client. This is directly related to the set of running [[resources]] and their map files' XML layout, although it can be changed at run-time by scripts.

If you are familiar with the concept of ''trees'' in computer-science, this should be easy to understand. If you are not, think of it like a family tree - except everyone only has a single parent. Every [[element]] has a ''parent'' element.

All elements that are created within scripts or from .map files are child elements of the resource they belong to. Thus, most elements (except for [[client]]s) exist only within resources and are also destroyed as soon as their resource is stopped.

==Tree elements==
* '''root''': This is at the very base of the tree - all elements are children (or descendants) of this element.
<syntaxhighlight lang="lua">
getRootElement()
</syntaxhighlight>
* '''resource''': These are direct children of the root element - with one for each ''running'' resource. This element is called the ''resource root''. Its ID holds the name of the resource.
<syntaxhighlight lang="lua">
getResourceRootElement()
</syntaxhighlight>
* '''map''': Each resource element contains at least one map element, representing either a ".map" file in the resource or the one containing the elements created by scripts (this is called the ''dynamic'' map). Their IDs contain the maps' filenames, or ''dynamic'' for the dynamic map.
** Map files can contain a number of other [[element]]s as well as an unlimited number of custom elements.

==Example==
This in an example of a serverside tree dumped to XML from a running server.
''Please note that it is shortened on some places for the sake of overview.''
<syntaxhighlight lang="xml">
<root>
<console/>
<player dontRespawn="false"/>
<player dontRespawn="false" lastSpawnarea=""/>
<resource id="resourcebrowser"/>
<resource id="ajax"/>
<resource id="resourcemanager"/>
<resource id="spawnmanager"/>
<resource id="mapmanager"/>
<resource id="runcode"/>
<resource id="fr">
<map id="dynamic">
<vehicle/>
</map>
</resource>
<resource id="elementbrowser"/>
<resource id="assault">
<map id="dynamic">
<team/>
<team/>
<blip/>
<marker/>
<colshape/>
<blip/>
<blip/>
</map>
</resource>
<resource id="as-farm">
<map id="dynamic"/>
<map id="as-farm.map">
<spawngroup req="" type="attacker">
<spawnarea posY="-8.3976354598999" posX="20.182683944702" skins="9" ... />
</spawngroup>
<spawngroup req="" type="attacker">
<spawnarea posY="32.166355133057" posX="-46.90763092041" skins="9" ... />
</spawngroup>
<spawngroup req="" type="attacker">
<spawnarea posY="35.214984893799" posX="-33.486911773682" skins="9" ... />
</spawngroup>
<spawngroup req="" type="attacker">
<spawnarea posY="35.214984893799" posX="-33.486911773682" skins="9" ... />
</spawngroup>
<objective id="first" type="checkpoint" description="Breach into the farm" ... />
<pickup type="weapon" ... />
</map>
</resource>
</root>
</syntaxhighlight>
===Explanation===
This tree consists of a number of resource root elements, the [[Element/Console|server console]] and two [[player]] elements, that are direct children of the '''root''' element. All these resources have a ''dynamic map'' as child element (it is just not shown for most of them). These contain the elements that are created dynamically by this resource using scripts, for example a [[vehicle]]. If the resource has a map file, it is also a child element, itself containing all the elements in the .map file.

Let's have a closer look at the '''assault''' resource: This contains just one ''dynamic'' map that has 2 teams, 3 blips, 1 marker and 1 colshape as child elements. These are the elements that are created by the script, for example the marker, the colshape and one of the blips are probably used for the objective.

The '''as-farm''' resource's function on the contrary is to be a map for the '''assault''' gamemode. The dynamic map is empty (it could contain elements if there was a script in it though), while there is a map called 'as-farm.map', that contains a number of elements. These are mostly custom elements (like spawngroup, spawnarea, objective) but also a few elements that MTA creates automactically after loading the map (like pickup). In the brackets after the element type, you can see the element data it contains. These are identical with the attributes the .map file contains within these elements, while you can also set and get element data for any other elements (e.g. players) with [[setElementData]] and [[getElementData]].

==Pratical application==
Elements can have as many children as they like. This does not directly affect the map in any way, but it comes in to its own when combined with the scripting system.

===Setting data for elements===
If you call a set... function on a node of the element tree, the function will affect every element within it (that it can work on).

So, the following code would set the size of every marker (the only type of element the setMarkerSize function can work on) that is below the root element to ''2.5''.
<syntaxhighlight lang="lua">
setMarkerSize ( getRootElement(), 2.5 )
</syntaxhighlight>

The same can be done on any element, it is not restricted to the root element.

===Map manager===
The [[#Example|example above]] shows the way the [[map manager]] uses different resources. The 'assault' resource is the gamemode, that manages what happens on the server using scripts and thus by creating elements in the tree dynamically. When a map resource is started, the gamemode receives a [[resource|resource pointer]] referring to the started resource - in this case ''as-farm'' - from which you can retrieve and store the resource root element. Using this element in conjunction with functions like [[getElementsByType]], [[getElementData]] and various others, you can access any of the information that was loaded into the tree from the 'as-farm.map'-file through scripts in the gamemode resource.

Another thing that has to be considered related to the tree of elements is the fact that when you change the map, you don't have to remove any elements you created within the map resource, while you '''do''' have to remove elements that are created within the gamemode resource, '''if''' they are specific to the map (which will be probably the case for those items you create based on information read from the map resource's .map files).

==Element browser==
You can start the resource ''elementbrowser'' to see a live view of the element tree on your server. Just start the resource and browser to your server's web page and choose the ''Element browser'' option in the sidebar (firefox only currently).
[[Category:Scripting Concepts]]
[[es:Árbol de elementos]]
[[ru:Element tree]]

EngineReplaceModel

2015-08-19T16:38:03Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}
{{Note box|Please note the loading order that is used in the examples as other orders can cause collisions, textures or the DFF not to load due to technical limitations}}

This function replaces the given model in the given model ID with the DFF file passed. This function supports vehicles and objects at the moment.

As of 1.1.1 This supports Ped and Weapon models. For replace weapon models you can't use weapon ID's, you should use object ID's. All weapon model ID's here: [[Weapons]].

Note: Due to a bug, when replacing models with built in collisions (i.e. vehicles), the collision may not get replaced correctly. The current work around is to load the dff again and do another replace after a short delay.
{{Note|To replace models in the original GTA map, use one of the [[EngineReplaceModel notes|methods shown here]]}}
==Syntax==
<syntaxhighlight lang="lua">
bool engineReplaceModel ( dff theModel, int modelID [, bool alphaTransparency = false ] )
</syntaxhighlight>
{{OOP||[[DFF|dff]]:replace}}
===Required Arguments===
*'''theModel:''' The model to replace the given model ID with
*'''modelID:''' The model it to replace the model of

===Optional Arguments===
*'''alphaTransparency:''' Set to true to enable special thing

===Returns===
Returns ''true'' if the model was successfully replaced, ''false'' if it failed for some reason, ie. the DFF or the model ID is not valid.

==Example==
'''Example 1:'''
<section name="Client" class="client" show="true">
Client-Side example for replacing vehicle model and texture with custom ones.
<syntaxhighlight lang="lua">
function ReplaceVehicle ( )
outputChatBox ( "> replacing the euros vehicle" )

txd = engineLoadTXD ( "data/euros.txd" )
engineImportTXD ( txd, 587 )
dff = engineLoadDFF ( "data/euros.dff" )
engineReplaceModel ( dff, 587 )
end

addEvent ( "replaceVeh", true )
addEventHandler ( "replaceVeh", root, ReplaceVehicle )
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
Server-side example function for triggering the replace.
<syntaxhighlight lang="lua">
function ReplaceCommand ( )
triggerClientEvent( "replaceVeh", root, replaceVeh )
end
addCommandHandler( "replace", ReplaceCommand )
</syntaxhighlight>
</section>

'''Example 2:'''
<section name="Client" class="client" show="true">
Client-Side example for replacing object collision, texture and model with custom ones.
<syntaxhighlight lang="lua">
function ReplaceObject ( )

col = engineLoadCOL( "MyModel.col" )
txd = engineLoadTXD( "MyModel.txd" )
dff = engineLoadDFF( "MyModel.dff", 0 )

engineReplaceCOL( col, 1234 )
engineImportTXD( txd, 1234 )
engineReplaceModel( dff, 1234 )-- replace the model at least

end

addEvent ( "replaceObj", true )
addEventHandler ( "replaceObj", root, ReplaceObject )
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
Server-side example function for triggering the replace.
<syntaxhighlight lang="lua">
function ReplaceCommand ( )
triggerClientEvent( "replaceObj", root, replaceObj )
end
addCommandHandler( "replace", ReplaceCommand )
</syntaxhighlight>
</section>

==See Also==
{{Engine_functions}}

EngineRestoreModel

2015-08-19T16:36:49Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}

This function restores the visual DFF and TXD model of the given model ID. This restores the result of [[engineReplaceModel]].

==Syntax==

<syntaxhighlight lang="lua">
bool engineRestoreModel ( int modelID )
</syntaxhighlight>
{{OOP||Engine.restoreModel}}
===Required Arguments===

*'''modelID:''' The model ID to restore the visuals of

===Returns===

Returns ''true'' if the model was successfully restored, ''false'' or ''nil'' if it failed for some reason.

==Example==


<section name="Client" class="client" show="true">
Client-Side example for restoring model / vehicle.
<syntaxhighlight lang="lua">
function ResetModel ( )
engineRestoreModel ( 587 ) -- Object / Vehicle to restore to default GTA one.
end

addEvent ( "restoreClientModel", true )
addEventHandler ( "restoreClientModel", root, ResetModel )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
Server-Side example for triggering model / vehicle restore function with "restore" command.
<syntaxhighlight lang="lua">
function RestoreModel ( )
triggerClientEvent ( "restoreClientModel", root, restoreClientModel )
end
addCommandHandler( "restore", RestoreModel )
</syntaxhighlight>
</section>

==See Also==

{{Engine_functions}}

SetElementPosition

2015-08-19T16:32:23Z

VenadHD: /* Example */

__NOTOC__
{{Server client function}}
This function sets the position of an element to the specified coordinates.

<div style="background: #FF7070; border: 3px solid #FF0000;">
'''Attention:''' Do not use this function to spawn a [[ped]]/[[player]]. It will cause problems with other functions like [[warpPedIntoVehicle]]. <br>
Use [[spawnPlayer]] and [[createPed]] instead.
</div>

==Syntax==
<syntaxhighlight lang="lua">
bool setElementPosition ( element theElement, float x, float y, float z [, bool warp = true ] )
</syntaxhighlight>
{{OOP||[[element]]:setPosition|position|}}

===Required Arguments===
*'''theElement:''' A valid [[element]] to be moved.
*'''x:''' The x coordinate of the destination.
*'''y:''' The y coordinate of the destination.
*'''z:''' The z coordinate of the destination.

===Optional Arguments===
*'''warp:''' teleports players, resetting any animations they were doing. Setting this to ''false'' preserves the current animation.

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

==Example==
<section name="Example 1" class="server" show="true">
This example adds a "setpos" command to console, which allows setting of a player's position.
<syntaxhighlight lang="lua">
function consoleSetPlayerPosition ( source, commandName, posX, posY, posZ )
setElementPosition ( source, posX, posY, posZ )
end
addCommandHandler ( "setpos", consoleSetPlayerPosition )
</syntaxhighlight>
</section>
<section name="Example 2" class="client" show="false">
This example adds a "setpos" command to console, which allows setting of the local player's position.
<syntaxhighlight lang="lua">
function consoleSetPlayerPosition ( commandName, posX, posY, posZ )
setElementPosition ( localPlayer, posX, posY, posZ )
end
addCommandHandler ( "setpos", consoleSetPlayerPosition )
</syntaxhighlight>
</section>
<section name="Example 3" class="server" show="false">
This example enables a player to type /warpto <playername> to warp to them. If the player being warped to is in a vehicle with a free passenger seat, it will warp into the vehicle.
<syntaxhighlight lang="lua">
function consoleWarpTo ( sourcePlayer, commandName, player2nick )
-- Make sure required parameters are set
if ( not sourcePlayer or not player2nick ) then return end
-- Setup the variables we will be using for teleportation
local x, y, z, r, d = 0, 0, 0, 0, 2.5
-- Grab the element identifier of the player we are trying to warp to
local player2 = getPlayerFromNick ( player2nick )
-- Make sure it exists!
if ( player2 ) then
-- Is the player we're warping to in a vehicle?
if ( isPlayerInVehicle ( player2 ) ) then
-- Indeed they are, let's get the vehicle information such as the vehicle element itself, and the seats it's got.
local player2vehicle = getPlayerOccupiedVehicle ( player2 )
local numseats = getVehicleMaxPassengers ( player2vehicle )
local i = 0
-- Loop over the seats to see if there's a free one
while ( i < numseats ) do
if ( getVehicleOccupant ( player2vehicle, i ) ) then
-- This seat isn't free, go ahead and check the next one
i = i + 1
else
-- This seat is free, get out of the loop
break
end
end
-- Check if 'i' is lower than the number of seats. If it is, it means it's the number of a free seat
if ( i < numseats ) then
-- Teleport the player into the seat
warpPlayerIntoVehicle ( sourcePlayer, player2vehicle, i )
else
-- There are no free seats, tell the player that.
outputChatBox ( "Sorry, the player's vehicle is full (" .. getVehicleName ( player2vehicle ) .. " " .. i .. "/" .. numseats .. ")", sourcePlayer )
end
else
-- The player isn't in a vehicle, let's get the player's position and warp to them.
x, y, z = getElementPosition ( player2 )
r = getPlayerRotation ( player2 )
-- Make sure we get interior data, they might be inside one!
interior = getElementInterior ( player2 )
dimension = getElementDimension ( player2 )
-- Do some funky math to make sure that we dont teleport inside of them (get us both stuck inside each other)
x = x - ( ( math.cos ( math.rad ( r + 90 ) ) ) * d )
y = y - ( ( math.sin ( math.rad ( r + 90 ) ) ) * d )
-- Set a few timers for setting interiors, dimensions and positions
setTimer ( setElementInterior, 800, 1, sourcePlayer, interior )
setTimer ( setElementDimension, 900, 1, sourcePlayer, dimension )
setTimer ( setElementPosition, 1000, 1, sourcePlayer, x, y, z )
setTimer ( setPlayerRotation, 1000, 1, sourcePlayer, r )
-- Fade the camera to make it look nicer
fadeCamera ( sourcePlayer, false, 1, 0, 0, 0 )
-- Fade it back once it's all complete!
setTimer ( fadeCamera, 1000, 1, sourcePlayer, true, 1 )
end
else
-- No player by the specified name was found, tell the warper this.
outputChatBox ( "No such player.", sourcePlayer )
end
end
addCommandHandler ( "warpto", consoleWarpTo )
</syntaxhighlight>
</section>

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

SetElementInterior

2015-08-19T16:29:58Z

VenadHD: /* Example */

{{Server client function}}
__NOTOC__
This function allows you to set the [[interior]] of any element. An interior is the current loaded place, 0 being outside.
{{Note|If passing the same interior as the element is in, the call will be ignored and position (optional arguments) will not be set either. Use [[setElementPosition]] separately to be sure the position will be set.}}

==Syntax==
<syntaxhighlight lang="lua">
bool setElementInterior ( element theElement, int interior [, float x, float y, float z] )
</syntaxhighlight>
{{OOP||[[element]]:setInterior||}}

===Required Arguments===
*'''theElement:''' The element in which you'd like to set the interior of.
*'''interior:''' The interior you want to set the element to. Valid values are 0 to 255.

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

===Returns===
Returns ''true'' if '''theElement''' and '''interior''' are valid arguments, ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
In this example, if a player were to type /interior 1, they would be teleported into this interior
<syntaxhighlight lang="lua">
function interior ( source, commandName, interior )
--Let's see if they gave an interior ID
if ( interior ) then
--They did, so lets assign them to that interior and teleport them there (all in 1 function call!)
setElementInterior ( source, interior, 2233.91, 1714.73, 1011.38 )
else
--They didn't give one, so set them to the interior they wanted, but don't teleport them.
setElementInterior ( source, 0 )
end
end
addCommandHandler ( "interior", interior )
</syntaxhighlight>
</section>

<section name="Client" class="client" show="true">
In this example, if a player were to type /interior 1, they would be teleported into this interior
<syntaxhighlight lang="lua">
function interior ( commandName, interior )
--Let's see if they gave a interior ID
if ( interior ) then
--They did, so let's assign them to that interior and teleport them there (all in 1 function call!)
setElementInterior ( localPlayer, interior, 2233.91, 1714.73, 1011.38 )
else
--They didn't give one, so set them to the interior they wanted, but don't teleport them.
setElementInterior ( localPlayer, 0 )
end
end
addCommandHandler ( "interior", interior )
</syntaxhighlight>
</section>

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

[[de:setElementInterior]]

SetElementDimension

2015-08-19T16:25:56Z

VenadHD: /* Example */

{{Server client function}}
__NOTOC__
This function allows you to set the [[dimension]] of any element. The dimension determines what/who the element is visible to.

==Syntax==
<syntaxhighlight lang="lua">
bool setElementDimension ( element theElement, int dimension )
</syntaxhighlight>
{{OOP||[[element]]:setDimension|dimension|}}

===Required Arguments===
*'''theElement:''' The element in which you'd like to set the dimension of.
*'''dimension:''' An integer representing the dimension ID

===Returns===
Returns ''true'' if '''theElement''' and '''dimension''' are valid, ''false'' otherwise.
Also returns false if '''theElement''' is a player and it's not alive.

==Example==
<section name="Server" class="server" show="true">
In this example the player's dimension is set to ID 1 when they enter a vehicle, and set back to dimension 0 when they exit the vehicle.
<syntaxhighlight lang="lua">
function onPlayerEnterVehicle ( theVehicle, seat, jacked )
if ( getElementDimension ( source ) == 0 ) then -- if the player is in dimension 0
setElementDimension ( source, 1 ) -- set his dimension to 1
setElementDimension ( theVehicle, 1 ) -- set his vehicle's dimension to 1 as well
end
end
addEventHandler ( "onPlayerVehicleEnter", root, onPlayerEnterVehicle )

function onPlayerExitVehicle ( theVehicle, seat, jacker )
if ( getElementDimension ( source ) == 1 ) then -- if the player is in dimension 1
setElementDimension ( source, 0 ) -- set his dimension back to 0
setElementDimension ( theVehicle, 0 ) -- set his vehicle's dimension back to 0 as well
end
end
addEventHandler ( "onPlayerVehicleExit", root, onPlayerExitVehicle )
</syntaxhighlight>
</section>

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

[[de:setElementDimension]]

SetElementAttachedOffsets

2015-08-19T16:24:35Z

VenadHD: /* Example */

__NOTOC__
{{Server client function}}
This function updates the offsets of an element that has been attached to another element using [[attachElements]].

==Syntax==
<syntaxhighlight lang="lua">
bool setElementAttachedOffsets ( element theElement, [ float xPosOffset, float yPosOffset, float zPosOffset, float xRotOffset, float yRotOffset, float zRotOffset ])
</syntaxhighlight>
{{OOP||[[element]]:setAttachedOffsets||}}

===Required Arguments===
*'''theElement:''' The attached element.

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

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

==Example==
<section name="Client" class="client" show="true">
'''Example:''' This example creates a car with a minigun
<syntaxhighlight lang="lua">
-- Offsets
local x,y,z,rx,ry,rz= 0,-1.5,-0.1,0,0,-90

function createArmedBobcat(cmd)
local lx,ly,lz = getElementPosition(root) -- get the position of the player
lx = lx + 5 -- add 5 units to the x position

veh = createVehicle( 422, lx, ly, lz) -- create a bobcat
base = createObject( 2985, 2,2,2) -- create a minigun_base object
setElementCollisionsEnabled ( base, false ) -- the minigun_base damages the car
-- you could alternatively load an empty col file for the minigun object
attachElements ( base, veh, x,y,z,rx,ry,rz) -- attach the base to the bobcat
end

function rotateIt(cmd, addZ)
if(addZ) then
rz=rz+addZ
setElementAttachedOffsets (base,x,y,z,rx,ry,rz) --update offsets
end
end

addCommandHandler("bobcat", createArmedBobcat)
addCommandHandler("rotate", rotateIt)
</syntaxhighlight>
</section>

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

GetRootElement

2015-08-19T16:19:02Z

VenadHD: /* Example */

{{Server client function}}
__NOTOC__
This function returns the root node of the [[element tree]], called ''root''. This node contains every other element: all resource root elements, players and remote clients. It is never destroyed and cannot be destroyed using [[destroyElement]].

It is often used to attach handler functions to events triggered for any element, or also to make a scripting function affect all elements.
{{Note|All resources have a [[Predefined_variables_list|predefined global variable]] called ''root'' that has the root element as value. The variable exists server side as well as client side.}}

==Syntax==
<syntaxhighlight lang="lua">
element getRootElement ( )
</syntaxhighlight>

===Returns===
Returns the root [[element]].

==Example==
This example will output the number of loaded resources by counting ''resource'' elements that are children of the ''root'' node.
<syntaxhighlight lang="lua">
--By default, predefined variable 'root' is getRootElement()
local rootChildren = getElementChildren( root )

local resourceCount = 0
for k, child in ipairs( rootChildren ) do
if getElementType( child ) == "resource" then
resourceCount = resourceCount + 1
end
end

outputChatBox( "There are " .. resourceCount .. " loaded resources." )
</syntaxhighlight>

==See Also==
{{Element functions}}
[[ru:getRootElement]]

GetElementType

2015-08-19T16:16:38Z

VenadHD: /* Example */

{{Server client function}}
__NOTOC__
This function is used to retrieve the type of an element.

==Syntax==
<syntaxhighlight lang="lua">
string getElementType ( element theElement )
</syntaxhighlight>
{{OOP||[[element]]:getType|type|}}

===Required Arguments===
*'''theElement:''' The [[element]] you wish to get the type of.

===Returns===
Returns a ''string'' containing the element type, ''false'' if invalid arguments were passed.

==Example==
<section name="Server" class="server" show="true">
This example destroys a haystack when a player targets it
<syntaxhighlight lang="lua">
function onPlayerTarget ( targetElem )
-- if the targeted object is a haystack (an object with model ID 3374) remove it from the game
if getElementType ( targetElem ) == "object" and getElementModel ( targetElem ) == 3374 then
destroyElement ( targetElem )
end
end
addEventHandler ( "onPlayerTarget", root, onPlayerTarget ) -- add above function as handler for targeting event
</syntaxhighlight>
</section>

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

GetElementRotation

2015-08-19T16:15:22Z

VenadHD: /* Example */

{{Server client function}}
__NOTOC__
Retrieve the rotation of elements.

==Syntax==
<syntaxhighlight lang="lua">
float float float getElementRotation ( element theElement [, string rotOrder = "default" ] )
</syntaxhighlight>
{{OOP||[[element]]:getRotation|rotation|}}

===Required Arguments===
*'''theElement:''' The element whose rotation will be retrieved

===Optional Arguments===
*'''rotOrder:''' A string representing the rotation order desired when returning the [http://en.wikipedia.org/wiki/Euler_angles euler angles]. If omitted, default value is ''"default"''. Allowed values are:
**''"default":'' default MTA behavior prior to 1.1, where rotation order depends on element type
**''"ZXY":'' rotation about the Z axis (''up''), then about the resulting X axis (''right'') and finally about the resulting Y axis (''front''). This is the default rotation order for [[object|objects]]
**''"ZYX":'' rotation about the Z axis (''up''), then about the resulting Y axis (''front''), and finally about the resulting X axis (''right''). This is the default rotation order for [[vehicle|vehicles]]

The default rotation order for peds/players is Z-Y-X (clientside) and -Z-Y-X (serverside) but those rotation orders (set using ''"default"'' on peds) can not be used manually on other element types since they only exist due to historical and backward compatibility reasons.
Specifying a rotation order other than ''"default"'' allows the same angles to later be uniformly used on several elements without having to consider their type.

===Returns===
* ''rx, ry, rz'': 3 ''float''s representing the Euler rotation angles on the axis X, Y and Z (with the rotation order depending on the ''rotOrder'' argument) if ''element'' exists and is a valid element, ''false'' if it's invalid.

==Example==
If a player points at a player element with a gun, its rotation will appear in the chat box.
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function onPlayerTargeted ( targetElem )
if ( isElement(targetElem) and getElementType (targetElem) == "player" ) then
local x,y,z = getElementRotation ( targetElem )
outputChatBox ( "Target player rotation: " .. x .. " " .. y .. " " .. z )
end
end
addEventHandler ( "onClientPlayerTarget", root, onPlayerTargeted )
</syntaxhighlight>
</section>

==See Also==
{{Client_element_functions}}

GetElementParent

2015-08-19T16:14:13Z

VenadHD: /* Example */

{{Server client function}}
__NOTOC__
This function is used to determine the parent of an ''element''.

==Syntax==
<syntaxhighlight lang="lua">
element getElementParent ( element theElement )
</syntaxhighlight>
{{OOP||[[element]]:getParent|parent|}}

===Required Arguments===
*'''theElement:''' The child of the parent element you want returned.

===Returns===
This returns the parent as an ''element''. It returns ''false'' if ''theElement'' is invalid, or is the root node.

==Example==
<section name="Server" class="server" show="true">
Consider the following map file:
<syntaxhighlight lang="xml">
<spawngroup id="red">
<spawnpoint id="spawnpoint_0" posX="2507.8715820313" posY="2772.6071777344" posZ="10.8203125" rot="270" skin="285"/>
<spawnpoint id="spawnpoint_1" posX="2508.060546875" posY="2780.3647460938" posZ="10.8203125" rot="270" skin="285"/>
</spawngroup>
<spawngroup id="blue">
<spawnpoint id="spawnpoint_5" posX="2733.4184570313" posY="2753.1276855469" posZ="10.8203125" rot="90" skin="124"/>
<spawnpoint id="spawnpoint_6" posX="2733.5258789063" posY="2748.1110839844" posZ="10.8203125" rot="90" skin="125"/>
</spawngroup>
</syntaxhighlight>

This function determines a spawnpoint's parent element, and announces its ID:
<syntaxhighlight lang="lua">
function spawnpointUse ( thePlayer ) -- this function gets called whenever a spawnpoint is used
theSpawnGroup = getElementParent ( source ) -- get the spawnpoint's parent element
-- announce the parent's ID and the player who spawned there:
outputChatBox ( getPlayerName ( thePlayer ) .. " spawned at team " .. getElementID ( theSpawnGroup ) .. "'s spawnpoint." )
-- Example output: "Joe spawned at team blue's spawnpoint."
end
addEventHandler ( "onSpawnpointUse", root, spawnpointUse )
</syntaxhighlight>
</section>

==See Also==
{{element_functions}}

GetElementModel

2015-08-19T16:13:21Z

VenadHD: /* Example */

__NOTOC__
{{Server client function}}

Returns the model ID of a given element. This can be a player/ped skin, a pickup model, an object model or a vehicle model.

==Syntax==
<syntaxhighlight lang="lua">
int getElementModel ( element theElement )
</syntaxhighlight>
{{OOP||[[element]]:getModel|model|}}

===Required Arguments===
*'''theElement:''' the element to retrieve the model ID of.

===Returns===
Returns the model ID if successful, ''false'' otherwise.
* For players/peds: A GTASA player model (skin) ID. See [[Character Skins]].
* For vehicles: The [[Vehicle IDs|vehicle ID]] of the vehicle.
* For objects: An [[int]] specifying the model id.

==Example==
<section class="server" name="Example 1 (Server)" show="true">
This example destroys a haystack when a player targets it.
<syntaxhighlight lang="lua">
function onPlayerTargeted ( targetElem )
if ( getElementType ( targetElem ) == "object" ) and ( getElementModel ( targetElem ) == 3374 ) then
destroyElement ( targetElem )
end
end
addEventHandler ( "onPlayerTarget", root, onPlayerTargeted )
</syntaxhighlight>
</section>
<section class="server" name="Example 2 (Server)" show="true">
This example prints out a message when a Shamal or AT-400 is entered by a player.
<syntaxhighlight lang="lua">
function planeEnter ( theVehicle, seat, jacked ) -- when someone enters a vehicle
local id = getElementModel ( theVehicle ) -- get the model ID of the vehicle
if id == 519 or id == 577 then -- if theVehicle is either Shamal or AT-400
local vehicleName = getVehicleName ( theVehicle ) -- get the name of theVehicle
outputChatBox ( "Someone stole a " .. vehicleName .. "!" ) -- announce that someone stole the plane
end
end
-- add the event handler to the event
addEventHandler ( "onPlayerVehicleEnter", root, planeEnter )
</syntaxhighlight>
</section>

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

GetElementHealth

2015-08-19T16:10:59Z

VenadHD: /* Example */

{{Server client function}}
__NOTOC__
This function returns the current health for the specified [[element]]. This can be a [[player]], a [[ped]], or a [[vehicle]].

==Syntax==
<syntaxhighlight lang="lua">
float getElementHealth ( element theElement )
</syntaxhighlight>
{{OOP||[[element]]:getHealth|health|}}

===Required Arguments===
*'''theElement:''' The [[player]] or [[vehicle]] whose health you want to check.

===Returns===
Returns a float indicating the element's health, or ''false'' if invalid arguments were passed.

==Example==
<section name="Clientside example" class="client" show="true">
This example outputs the health of the player who enters the command 'showhealth', and their vehicle's health.
<syntaxhighlight lang="lua">
function showLocalHealth()
-- get the player's health and output it
local playerHealth = getElementHealth ( localPlayer )
outputChatBox ( "Your health: " .. playerHealth )

-- get the player's vehicle: if he is in one, output its health as well
local playerVehicle = getPedOccupiedVehicle ( localPlayer )
if playerVehicle then
local vehicleHealth = getElementHealth ( playerVehicle ) / 10 -- Divide this by 10, as default the denominator is 1000
outputChatBox ( "Your vehicle's health: " .. vehicleHealth )
end
end
addCommandHandler ( "showhealth", showLocalHealth )
</syntaxhighlight>
</section>

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

GetElementDimension

2015-08-19T16:08:32Z

VenadHD: /* Example */

__NOTOC__
{{Server client function}}
This function allows you to retrieve the dimension of any element. The dimension determines what/who the element is visible to.

==Syntax==
<syntaxhighlight lang="lua">
int getElementDimension ( element theElement )
</syntaxhighlight>
{{OOP||[[element]]:getDimension|dimension|}}

===Required Arguments===
*'''theElement:''' The element in which you'd like to retrieve the dimension of.

===Returns===
Returns an integer for the dimension if '''theElement''' is valid, ''false'' otherwise.

==Example==
This example puts all vehicles with drivers in dimension 1, while all other vehicles are in dimension 0. This would have the effect of making on-foot players invisible to drivers, and vice versa. It'd also make entering a vehicle as passenger after the driver has entered impossible, as the vehicle would appear to vanish to any on foot players.
<section show="true" name="Server" class="server">
<syntaxhighlight lang="lua">
function onPlayerEnterVehicle ( theVehicle, seat, jacked )
if ( getElementDimension ( source ) == 0 and seat == 0 ) then -- if the player is in dimension 0 and is entering the driver seat
setElementDimension ( source, 1 ) -- set his dimension to 1
setElementDimension ( theVehicle, 1 ) -- set his vehicle's dimension to 1 as well
end
end
addEventHandler ( "onPlayerVehicleEnter", root, onPlayerEnterVehicle )

function onPlayerExitVehicle ( theVehicle, seat, jacker )
if ( getElementDimension ( source ) == 1 and seat == 0 ) then -- if the player is in dimension 1 and was in the driver's seat
setElementDimension ( source, 0 ) -- set his dimension back to 0
setElementDimension ( theVehicle, 0 ) -- set his vehicle's dimension back to 0 as well
end
end
addEventHandler ( "onPlayerVehicleExit", root, onPlayerExitVehicle )
</syntaxhighlight>
</section>

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

GetElementData

2015-08-19T16:06:06Z

VenadHD: /* Example */

__NOTOC__
{{Server client function}}
This function retrieves [[element data]] attached to an element under a certain key.

==Syntax==
<syntaxhighlight lang="lua">var getElementData ( element theElement, string key [, inherit = true] )</syntaxhighlight>
{{OOP||[[element]]:getData||}}

===Required Arguments===
*'''theElement:''' This is the element with data you want to retrieve.
*'''key:''' The name of the element data entry you want to retrieve. (Maximum 31 characters.)

===Optional Arguments===
*'''inherit:''' - toggles whether or not the function should go up the hierarchy to find the requested key in case the specified element doesn't have it.

===Returns===
This function returns a ''variable'' containing the requested element data, or ''false'' if the element or the element data does not exist. When getting data corresponding to a XML attribute, this is always a ''string''.

==Example==
This example stores the tick count when a player joins and then allows players to see how long they are connected using a console function 'joinTime'.
<section show="true" name="Server" class="server">
<syntaxhighlight lang="lua">
function joinTime ( )
setElementData ( source, "joinTime", getTickCount() ) -- Store the current tick count in the player's data with the key 'joinTime'
end
-- Make our 'joinTime' function be called when a player joins
addEventHandler ( "onPlayerJoin", root, joinTime )

function showJoinTime ( source, commandName, playerName )
if ( playerName ) then -- see if a player was specified
thePlayer = getPlayerFromName ( playerName ) -- get the player element for the specified player
if ( thePlayer ) then -- if one was found...
local timeOnline = (getTickCount() - getElementData ( thePlayer, "joinTime" )) / 1000 -- calculates the time since join
outputChatBox ( getPlayerName ( thePlayer ).." joined "..timeOnline.." seconds ago", source ) -- output the player's join time
else
outputChatBox ( "Couldn't find '" .. playerName .. "'", source ) -- display an error
end
else
-- display when the player who used the function joined and inform how to see other people's join time
local timeOnline = (getTickCount() - getElementData ( source, "joinTime" )) / 1000 -- calculate the time since join
outputChatBox ( "You joined " ..timeOnline.." seconds ago", source )
outputChatBox ( "Use 'join_time <player name>' to see other people's join time", source )
end
end
-- Add a console command joinTime, that takes an optional parameter of a player's name
addCommandHandler ( "joinTime", showJoinTime )
</syntaxhighlight>
</section>

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

GetElementAttachedOffsets

2015-08-19T15:58:10Z

VenadHD: /* Example */

__NOTOC__
{{Server client function}}
This function returns the offsets of an element that has been attached to another element using [[attachElements]].

==Syntax==
<syntaxhighlight lang="lua">
float, float, float, float, float, float getElementAttachedOffsets ( element theElement )
</syntaxhighlight>
{{OOP||[[element]]:getAttachedOffsets||}}

===Required Arguments===
*'''theElement:''' The attached element.

===Returns===
Returns 6 [[float|floats]], of which the first 3 indicate the position offset (x, y, z), and the last 3 indicate the rotation offset (x, y, z), if successful. ''false'' otherwise.

==Example==
<section name="Client" class="client" show="true">
'''Example:''' This example creates a car with a minigun
<syntaxhighlight lang="lua">
-- Offsets
local x,y,z,rx,ry,rz= 0,-1.5,-0.1,0,0,-90

function createArmedBobcat(cmd)
local lx, ly, lz = getElementPosition(localPlayer) -- get the position of the player
lx = lx + 5 -- add 5 units to the x position

veh = createVehicle( 422, lx, ly, lz) -- create a bobcat
base = createObject( 2985, 2,2,2) -- create a minigun_base object
setElementCollisionsEnabled ( base, false ) -- the minigun_base damages the car
-- you could alternatively load an empty col file for the minigun object
attachElements ( base, veh, x,y,z,rx,ry,rz) -- attach the base to the bobcat
end

function rotateIt(cmd, addZ)
if(addZ) then
local x, y, z, rx, ry, rz = getElementAttachedOffsets (base) -- get the offsets
rz = rz + addZ
setElementAttachedOffsets (base, x, y, z, rx, ry, rz) -- update offsets
end
end

addCommandHandler("bobcat", createArmedBobcat)
addCommandHandler("rotate", rotateIt)
</syntaxhighlight>
</section>

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

DestroyElement

2015-08-19T15:55:40Z

VenadHD: /* Example */

__NOTOC__
{{Server client function}}
This function destroys an [[element]] and all elements within it in the hierarchy (its children, the children of those children etc). [[player|Player]] elements cannot be destroyed using this function. A player can only be removed from the hierarchy when they quit or are kicked. The root element also cannot be destroyed, however, passing the root as an argument will wipe all elements from the server, except for the players and clients, which will become direct descendants of the root node, and other elements that cannot be destroyed, such as resource root elements.

Players are not the only elements that cannot be deleted. This list also includes remote clients and console elements.
{{Note|As element ids are eventually recycled, always make sure you nil variables containing the element after calling this function}}

==Syntax==
<syntaxhighlight lang="lua">
bool destroyElement ( element elementToDestroy )
</syntaxhighlight>
{{OOP||[[element]]:destroy||}}

===Required Arguments===
*'''elementToDestroy:''' The element you wish to destroy.

===Returns===
Returns ''true'' if the element was destroyed successfully, ''false'' if either the element passed to it was invalid or it could not be destroyed for some other reason (for example, clientside destroyElement can't destroy serverside elements).

==Example==
'''Example 1:''' This example would destroy every element in the map, with the exception of players and the root element itself.
<syntaxhighlight lang="lua">
-- Destroy all its children, except players.
destroyElement ( root )
</syntaxhighlight>

'''Example 2:''' This example destroys all vehicles of the specified model:
<syntaxhighlight lang="lua">
function destroyVehiclesOfModel(modelID)
-- get a table of all the vehicles that exist and loop through it
local vehicles = getElementsByType("vehicle")
for i,v in ipairs(vehicles) do
-- if the vehicle's ID is the one provided, destroy it
if (getElementModel(v) == modelID) then
destroyElement(v)
end
end
end

destroyVehiclesOfModel(445)
</syntaxhighlight>

'''Example 3:''' This example allows creation of claymores, which trigger and explode. When they explode, the colshape and object for the claymore are destroyed.
<syntaxhighlight lang="lua">function createClaymore ( x,y,z, creator )
local claymoreObject = createObject ( 1945, x, y, z - 1, 0, 0, 90 ) -- create an object which looks like a claymore
local claymoreCol = createColSphere ( x, y, z, 1 ) -- create a col sphere with radius 1
setElementData ( claymoreCol, "object", claymoreObject ) -- store the object of the claymore
setElementData ( claymoreCol, "creatorPlayer", creator ) -- store the person who created it
addEventHandler ( "onColShapeHit", claymoreCol, claymoreHit ) -- add an event handler to the colshape
end

function claymoreHit ( thePlayer, matchingDimension )
-- retrieve the object associated to the claymore, and who created it
local claymoreObject = getElementData ( source, "object" )
local claymoreCreator = getElementData ( source, "creatorPlayer" )
-- get the position of the claymore
local x,y,z = getElementPosition ( source )
createExplosion ( x,y,z, 12, claymoreCreator ) -- create an explosion, associated to the creator, of a small size at the col's position
-- remove the event handler for the colshape
removeEventHandler ( "onColShapeHit", source, claymoreHit )
-- destroy the claymore object, and the col shape so it doesn't trigger again.
destroyElement ( claymoreObject )
destroyElement ( source )
end
</syntaxhighlight>
'''Example 4:''' This example destroys all vehicles, regardless of ID, name, etc:
<syntaxhighlight lang="lua">
function allvehiclesaredoomed()
-- get a table of all the vehicles that exist and loop through it
vehicles = getElementsByType("vehicle")
for i,v in ipairs(vehicles) do
-- destroy every vehicle.
destroyElement(v)
end
end
--The command handler below will destroy all vehicles once
--you enter /vdoom in the chat box or vdoom in the game console.
addCommandHandler("vdoom", allvehiclesaredoomed)
--This is very useful if you use the freeroam resource and some
--heartless players start spawn spamming.
--You can also set it on a timer to have your server clear all
--vehicles ever 60 minutes, (1 hour). Timer below:
setTimer(allvehiclesaredoomed, 3600000, 0)
</syntaxhighlight>

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

AttachElements

2015-08-19T15:54:09Z

VenadHD: /* Example */

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

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

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

'''Note:''' The offset coodinates reflect the object space, not the world space. This means that you cannot calculate the exact offsets between two objects by pre-positioning them in the map editor as a reference. Please see [[attachElementsOffsets]] for more details.

'''Note #2:''' Due to a limitation in GTA, unexpected attach rotations may occur if all rotation offsets are non-zero. (i.e. Try to ensure at least one of 'xRotOffset', 'yRotOffset' or 'zRotOffset' is zero)

==Syntax==
<syntaxhighlight lang="lua">
bool attachElements ( element theElement, element theAttachToElement, [ float xPosOffset, float yPosOffset, float zPosOffset, float xRotOffset, float yRotOffset, float zRotOffset ] )
</syntaxhighlight>
{{OOP||[[element]]:attach||}}

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

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

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

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

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

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

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

GuiCreateBrowser

2015-08-19T15:38:30Z

VenadHD: /* Example */

__NOTOC__
{{Client_function}}
{{New feature/item|3.0150|1.5||
This function creates a new CEGUI web [[Element/Browser|browser]] element.
}}

==Syntax==
<syntaxhighlight lang="lua">gui-browser guiCreateBrowser( float x, float y, float width, float height, bool isLocal, bool isTransparent, bool isRelative [ , element parent = nil ] )</syntaxhighlight>
{{OOP||[[Element/gui-browser|GuiBrowser]]}}

===Required Arguments===
*'''x, y:''' The browser's position
*'''width:''' The browser's native width
*'''height:''' The browser's native height
*'''isLocal:''' See examples
*'''isTransparent:''' ''true'' if you want the browser to support transparency, ''false'' otherwise
*'''isRelative:''' This is whether sizes and positioning are relative. If this is true, then all x,y,width,height floats must be between 0 and 1, representing measures relative to the parent.

===Optional Arguments===
*'''parent:''' This is the parent that the radio button is attached to. If the relative argument is true, sizes and positioning will be made relative to this parent. If the relative argument is false, positioning will be the number of offset pixels from the parent's origin. If no parent is passed, the parent will become the screen - causing positioning and sizing according to screen positioning.

===Returns===
Returns ''true'' if the [[gui-browser]] element was successfully created, ''false'' otherwise. Returns also ''false'', if the user disabled remote pages and ''isLocal'' was set to ''false''.

==Example==
This examples attached a webbrowser to a CEGUI window, '''not is tested'''
<syntaxhighlight lang="lua">
--In order to render the browser on the full screen, we need to know the dimensions.
local screenWidth, screenHeight = guiGetScreenSize()

--Let's create a new browser in remote mode.
local window = guiCreateWindow(0, 0, screenWidth, screenHeight, "Webbrowser", false)
local browser = guiCreateBrowser(0, 0, 800, 600, false, false, false, window)

-- The event onClientBrowserCreated will be triggered, after the browser has been initialized.
-- After this event has been triggered, we will be able to load our URL
local theBrowser = guiGetBrowser(browser) -- Get the browser element from gui-browser
addEventHandler("onClientBrowserCreated", theBrowser,
function()
-- After the browser has been initialized, we can load www.youtube.com
loadBrowserURL(source, "http://www.youtube.com")
end
)
</syntaxhighlight>

==See Also==
{{GUI_functions}}

GuiCreateBrowser

2015-08-19T15:36:49Z

VenadHD: /* Example */

__NOTOC__
{{Client_function}}
{{New feature/item|3.0150|1.5||
This function creates a new CEGUI web [[Element/Browser|browser]] element.
}}

==Syntax==
<syntaxhighlight lang="lua">gui-browser guiCreateBrowser( float x, float y, float width, float height, bool isLocal, bool isTransparent, bool isRelative [ , element parent = nil ] )</syntaxhighlight>
{{OOP||[[Element/gui-browser|GuiBrowser]]}}

===Required Arguments===
*'''x, y:''' The browser's position
*'''width:''' The browser's native width
*'''height:''' The browser's native height
*'''isLocal:''' See examples
*'''isTransparent:''' ''true'' if you want the browser to support transparency, ''false'' otherwise
*'''isRelative:''' This is whether sizes and positioning are relative. If this is true, then all x,y,width,height floats must be between 0 and 1, representing measures relative to the parent.

===Optional Arguments===
*'''parent:''' This is the parent that the radio button is attached to. If the relative argument is true, sizes and positioning will be made relative to this parent. If the relative argument is false, positioning will be the number of offset pixels from the parent's origin. If no parent is passed, the parent will become the screen - causing positioning and sizing according to screen positioning.

===Returns===
Returns ''true'' if the [[gui-browser]] element was successfully created, ''false'' otherwise. Returns also ''false'', if the user disabled remote pages and ''isLocal'' was set to ''false''.

==Example==
This examples attached a webbrowser to a CEGUI window, '''not is tested'''
<syntaxhighlight lang="lua">
--In order to render the browser on the full screen, we need to know the dimensions.
local screenWidth, screenHeight = guiGetScreenSize()

--Let's create a new browser in remote mode.
local window = guiCreateWindow(200, 200, screenWidth, screenHeight, "Webbrowser", false)
local browser = guiCreateBrowser(0, 0, 800, 600, false, false, false, window)

-- The event onClientBrowserCreated will be triggered, after the browser has been initialized.
-- After this event has been triggered, we will be able to load our URL
local theBrowser = guiGetBrowser(browser) -- Get the browser element from gui-browser
addEventHandler("onClientBrowserCreated", theBrowser,
function()
-- After the browser has been initialized, we can load www.youtube.com
loadBrowserURL(source, "http://www.youtube.com")
end
)
</syntaxhighlight>

==See Also==
{{GUI_functions}}

GetBrowserSettings

2015-08-19T15:35:31Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}
{{Needs Example}}
{{New feature/item|3.0150|1.5||
This function returns a table containing the browser settings.
}}

==Syntax==
<syntaxhighlight lang="lua">
table getBrowserSettings ()
</syntaxhighlight>
{{OOP||[[Element/Browser|Browser]].getSettings||getBrowserSettings}}

==Returns==
A table having the following keys:
* '''RemoteEnabled''': ''true'' if remote websites are enabled, ''false'' otherwise
* '''RemoteJavascript''': ''true'' if Javascript is enabled on remote websites, ''false'' otherwise
* '''PluginsEnabled''': ''true'' if plugins such as Flash, Silverlight (but not Java) are enabled, ''false'' otherwise. This setting is ''false'' by default.

==Example==
This example is '''not tested'''
<syntaxhighlight lang="lua">
local window = guiCreateWindow(200, 200, 1024, 768, "Webbrowser", false)
local browser = guiCreateBrowser(0, 0, 800, 600, false, false, false, window)

for k,v in pairs(getBrowserSettings(browser)) do
outputChatBox("['"..tostring(k).."'] = '"..tostring(v))
end
</syntaxhighlight>

==See Also==
{{CEF_functions}}

FxAddBlood

2015-08-18T12:52:58Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}
[[Image:Fxblood.png|thumb|200px|Blood splatter]]
Creates a blood splatter particle effect.

==Syntax==
<syntaxhighlight lang="lua">
bool fxAddBlood ( float posX, float posY, float posZ, float dirX, float dirY, float dirZ, [int count=1, float brightness=1.0] )
</syntaxhighlight>
{{OOP||[[Effect]].addBlood}}

===Required Arguments===
*'''posX, posY, posZ:''' the world coordinates where the effect originates.
*'''dirX, dirY, dirZ:''' a direction vector indicating where the blood flies to.

===Optional Arguments===
{{OptionalArg}}
*'''count:''' the number of flying droplets to create.
*'''brightness:''' the brightness. Ranges from 0 (almost black) to 1 (normal color).

==Example==
<section name="Client" class="client" show="true">
This example creates blood effects when a player gets shot.
<syntaxhighlight lang="lua">
function BloodonDamage( attacker, weapon, bodypart, loss )
if loss > 25 then -- if the player loses more than 25 hp, then...
local x, y, z = getElementPosition( source ) -- get player's position for adding blood
local randombloodamount = math.random( 1, 3 ) -- random blood amount 1-3
fxAddBlood ( x, y, z-2, 0.00000, 0.00000, 0.00000, randombloodamount, 1 )
-- this adds blood to player's current position
end
end
addEventHandler( "onClientPlayerDamage", root, BloodonDamage ) -- calls the function when a player loses hp
</syntaxhighlight>
</section>

==See Also==
{{Client Effects functions}}
[[ru:FxAddBlood]]

FxAddWaterHydrant

2015-08-18T12:49:55Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}
[[Image:Fxwaterhydrant.png|thumb|200px|Water hydrant]]
This function creates a water hydrant particle effect.

==Syntax==
<syntaxhighlight lang="lua">
bool fxAddWaterHydrant ( float posX, float posY, float posZ )
</syntaxhighlight>
{{OOP||[[Effect]].addWaterHydrant}}

===Required Arguments===
* '''posX:''' A float representing the '''x''' position of the hydrant
* '''posY:''' A float representing the '''y''' position of the hydrant
* '''posZ:''' A float representing the '''z''' position of the hydrant

===Returns===
Returns a true if the operation was successful, false otherwise.

==Example==
This example will create 20 water hydrant effects around the players position when they use the command: hydrantmania.
<syntaxhighlight lang="lua">
function createHydrants()
local x, y, z = getElementPosition(localPlayer) -- Get your location.
for i=0, 20 do -- 20 Hydrants.
fxAddWaterHydrant(x + math.random(-5,5), y + math.random(-5,5), z) -- Using math.random, and your current location 20 water hydrants are created.
end
end
addCommandHandler("hydrantmania", createHydrants)
</syntaxhighlight>

==See Also==
{{Client Effects functions}}

DxSetPixelColor

2015-08-18T12:47:09Z

VenadHD: /* Example */

{{Client function}}
__NOTOC__
This function sets the color of a single pixel for [[Texture_pixels|pixels]] contained in a string. It only works with ''''plain'''' format pixels.

==Syntax==
<syntaxhighlight lang="lua">
bool dxSetPixelColor ( string pixels, int x, int y, int r, int g, int b [, int a = 255 ] )
</syntaxhighlight>

===Required Arguments===
*'''pixels :''' The pixels to use
*'''x:''' The X coordinate for the pixel
*'''y:''' The Y coordinate for the pixel
*'''r:''' The red channel for the color (0-255)
*'''g:''' The green channel for the color (0-255)
*'''b:''' The blue channel for the color (0-255)

===Optional Arguments===
*'''a:''' The alpha channel for the color (0-255)

==Returns==
Returns true if successful, or ''false'' if invalid arguments were passed to the function.

==Example==
<section name="Client" class="client" show="true">
This example creates a 64x64 texture with random pixel colors, and draw it on the screen.
<syntaxhighlight lang="lua">
addEventHandler ("onClientResourceStart", resourceRoot,
function ()
texture = dxCreateTexture (64, 64)
local pixels = dxGetTexturePixels (texture)
for i=0,63 do
for j=0,63 do
dxSetPixelColor (pixels, j, i, math.random (255), math.random (255), math.random (255), 255)
end;
end;
dxSetTexturePixels (texture, pixels)
end)

addEventHandler ("onClientRender", root,
function ()
dxDrawImage (300, 300, 64, 64, texture)
end)
</syntaxhighlight>
</section>

==See Also==
{{Drawing_functions}}

DxGetTextWidth

2015-08-18T12:41:14Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}
This function retrieves the theoretical width of a certain piece of text, if it were to be drawn using [[dxDrawText]].

==Syntax==
<syntaxhighlight lang="lua">
float dxGetTextWidth ( string text, [float scale=1, mixed font="default", bool bColorCoded=false] )
</syntaxhighlight>
{{New feature/item|3.0141|1.4.1|6942|{{OOP|This syntax requires you to ignore the font argument above| [[Element/DX font|font]]:getTextWidth}}}}
===Required Arguments===
* '''text:''' A string representing the text for which you wish to retrieve with width for.

==Optional Arguments==
{{OptionalArg}}
* '''scale:''' The size of the text.
* '''font:''' Either a custom [[DX font]] element or the name of a built-in dx font:
{{DxFonts}}
* '''bColorCoded:''' Should we exclude color codes from the width? (false will include the hex in the length)

===Returns===
Returns the float of the width of the text.

==Example==
<section name="Example" class="client" show="true">
This will show you the width of a message in a normal chatbox sent by a player
<syntaxhighlight lang="lua">
function dxwidth(msg)
chatbox = getChatboxLayout()
local length = dxGetTextWidth(msg,chatbox["chat_scale"][1])
outputChatBox(tostring(length))
end
addEventHandler("onClientChatMessage",root,dxwidth)
</syntaxhighlight>
</section>

==See Also==
{{Drawing_functions}}

DxGetFontHeight

2015-08-18T12:40:19Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}
This function retrieves the theoretical height of a certain piece of text, if it were to be drawn using [[dxDrawText]].
{{Note|The returned height will be in logical units which are 1.75 times the actual pixel height.}}

==Syntax==
<syntaxhighlight lang="lua">
int dxGetFontHeight ( [float scale=1, mixed font="default"] )
</syntaxhighlight>
{{New feature/item|3.0141|1.4.1|6942|{{OOP|This syntax requires you to ignore the font argument above| [[Element/DX font|font]]:getHeight}}}}
===Required Arguments===
''None''

===Optional Arguments===
{{OptionalArg}}
* '''scale:''' The size of the text.
* '''font:''' Either a custom [[DX font]] element or the name of a built-in dx font:
{{DxFonts}}

===Returns===
Returns an integer of the height of the text.

==Example==
The following example will draw two lines of text one above the other.
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
screenWidth, screenHeight = guiGetScreenSize() -- Get the screen resolution
scale = 2 -- The scale of both texts

-- We add an event handler to keep drawing the text
addEventHandler("onClientRender",root,function()

-- Draw the first text 400 pixels from the top and left of the screen
dxDrawText("Hello!", 400, 400, screenWidth,screenHeight,tocolor(255,255,255,255),scale,"pricedown")

-- Draw the second text above the first one.
-- The variable "offset" will return the height of the first text, so we can position the second text above the first one.
-- If we changed the scale, the second text would still be above the first one, since we calculated the height of the font.
offset = dxGetFontHeight(scale,"pricedown")
dxDrawText("Hello!", 400, 400 - offset, screenWidth, screenHeight,tocolor(255,255,255,255),scale,"pricedown")
end)
</syntaxhighlight>
</section>

==See Also==
{{Drawing_functions}}

DxDrawLine3D

2015-08-18T12:36:35Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}
This function draws a 3D line between two points in the 3D world - rendered for '''one''' frame. This should be used in conjunction with [[onClientRender]] in order to display continuously.

==Syntax==
<syntaxhighlight lang="lua">
bool dxDrawLine3D ( float startX, float startY, float startZ, float endX, float endY, float endZ, int color[, int width, bool postGUI ] )
</syntaxhighlight>

===Required Arguments===
* '''startX:''' The start X position of the 3D line, representing a coordinate in the GTA world.
* '''startY:''' The start Y position of the 3D line, representing a coordinate in the GTA world.
* '''startZ:''' The start Z position of the 3D line, representing a coordinate in the GTA world.
* '''endX:''' The end X position of the 3D line, representing a coordinate in the GTA world.
* '''endY:''' The end Y position of the 3D line, representing a coordinate in the GTA world.
* '''endZ:''' The end Z position of the 3D line, representing a coordinate in the GTA world.
* '''color:''' An integer of the hex color, produced using [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).

==Optional Arguments==
{{OptionalArg}}
* '''width:''' The width/thickness of the line
* '''postGUI:''' A bool representing whether the line should be drawn on top of or behind any ingame GUI (rendered by CEGUI).

===Returns===
Returns a ''true'' if the operation was successful, ''false'' otherwise.

==Example==
This is a small example of creating 3D Line / "Rope" between vehicle and player.
<syntaxhighlight lang="lua">
function makeLineAppear()
testVehicle = createVehicle ( 411, 0, 0, 5 ) -- Create our test vehicle.
addEventHandler("onClientRender", root, createLine) -- onClientRender keeps the 3D Line visible.
end
function createLine ( )
x1, y1, z1 = getElementPosition ( testVehicle ) -- Get test vehicles position.
x2, y2, z2 = getElementPosition ( localPlayer ) -- Get local players position.
dxDrawLine3D ( x1, y1, z1, x2, y2, z2, tocolor ( 0, 255, 0, 230 ), 2) -- Create 3D Line between test vehicle and local player.
end
addCommandHandler("test", makeLineAppear)
</syntaxhighlight>

==See Also==
{{Drawing_functions}}

DxDrawImage

2015-08-18T12:33:44Z

VenadHD: /* Example */

__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,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 (RR = red, GG = green, BB = blue, AA = alpha).
*'''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==
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", root, renderDisplay) -- Keep everything visible with onClientRender.
end
addEventHandler("onClientResourceStart",resourceRoot, HandleTheRendering)
</syntaxhighlight>

==See Also==
{{Drawing_functions}}

IsElementWithinColShape

2015-08-18T12:27:07Z

VenadHD: /* Example */

{{Server client function}}
__NOTOC__
This function is used to determine if an element is within a collision shape. Please note that for legacy reasons, a colshape created on the client does not collide with elements already existing at that location until they first move. Please also note that before 1.0.3, this did not function correctly when moving a colshape.

Please note that this function doesn't verify whether element is in the same dimension and interior, additional checks could be implemented manually if they are needed.

==Syntax==
<syntaxhighlight lang="lua">bool isElementWithinColShape ( element theElement, colshape theShape )</syntaxhighlight>
{{OOP||[[element]]:isWithinColShape}}

===Required Arguments===
*'''theElement:''' The [[element]] you're checking.
*'''theShape:''' The [[colshape]] you're checking

===Returns===
Returns ''true'' if the element is within the colshape, ''false'' otherwise

==Example==
This small script is an example of detecting if a player is within a certain defined colshape. This could serve as a base to perform many functions, rather than just an output.
<syntaxhighlight lang="lua">
local circlearea = createColCircle ( 0, 0, 10 )

function ColShapeHit ( thePlayer, matchingDimension )
local detection = isElementWithinColShape ( thePlayer, circlearea )
--A variable called 'detection' stores the result of asking if the player
--who entered a colshape is within the specific colshape called 'circlearea'.
--The result is either true or false.
detection = detection and getElementDimension( thePlayer ) == getElementDimension( circlearea )
--Let's additionally check element dimensions.
if detection then
outputChatBox ( getPlayerName(thePlayer).." is in the 'circle area' col shape" )
end
--if detection was true then the player is in the col shape. Output a
--message to confirm this
end
addEventHandler ( "onColShapeHit", root, ColShapeHit )
</syntaxhighlight>

==See Also==
{{element functions}}

RemovePedClothes

2015-08-18T12:18:43Z

VenadHD: /* Example */

__NOTOC__
{{Server client function}}
This function is used to remove the current clothes of a certain type on a [[ped]]. It will remove them if the clothesTexture and clothesModel aren't specified, or if they match the current clothes on that slot.

==Syntax==
<syntaxhighlight lang="lua">
bool removePedClothes ( ped thePed, int clothesType, [ string clothesTexture, string clothesModel ] )
</syntaxhighlight>
{{OOP||[[ped]]:removeClothes}}

===Required Arguments===
*'''thePed''': The [[ped]] you want to remove clothes from.
*'''clothesType''': the clothes slot/type to remove. See the [[CJ Clothes|clothes catalog]].

===Optional Arguments===
*'''clothesTexture''': (Server only) A string determining the clothes texture that will be removed. See the [[CJ Clothes|clothes catalog]].
*'''clothesModel''': (Server only) A string determining the clothes model that will be removed. See the [[CJ Clothes|clothes catalog]].

==Returns==
This function returns ''true'' if the clothes were successfully removed from the ped, ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
This example adds a 'moto' helmet to a player when he gets on a nrg bike, and removes it when he gets off.
<syntaxhighlight lang="lua">
function addHelmetOnEnter ( vehicleEntered, seat, jacked )
if getElementModel ( vehicleEntered ) == 522 then -- if it's a nrg
addPedClothes ( source, "moto", "moto", 16 ) -- add the helmet
end
end
addEventHandler ( "onPlayerVehicleEnter", root, addHelmetOnEnter )

function removeHelmetOnExit ( vehicleExited, seat, jacked )
if getElementModel ( vehicleExited ) == 522 then -- if it's a nrg
removePedClothes ( source, 16, "moto", "moto" ) -- remove that helmet
end
end
addEventHandler ( "onPlayerVehicleExit", root, removeHelmetOnExit )
</syntaxhighlight>
</section>

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

GetBodyPartName

2015-08-18T12:16:39Z

VenadHD: /* Example */

{{Server client function}}
__NOTOC__
This function is used to get the name of a body part on a player.

==Syntax==
<syntaxhighlight lang="lua">
string getBodyPartName ( int bodyPartID )
</syntaxhighlight>

===Required Arguments===
*'''bodyPartID''': An integer representing the body part ID you wish to retrieve the name of.
{{BodyParts}}

==Returns==
This function returns a string containing the body part name if the ID is valid, ''false'' otherwise.

==Example==
This example prints the killer and body part to the chat on the wasted/kill event.
<syntaxhighlight lang="lua">
function deathMessageOnWasted ( ammo, attacker, weapon, bodypart )
if ( attacker ) then -- if we have an attacker
if ( getElementType ( attacker ) == "player" ) then -- make sure the element that killed him was a player
tempString = getPlayerName ( attacker ) .. " killed " .. getPlayerName ( source ) .. " (" .. getWeaponNameFromID ( weapon ) .. ")"
if ( bodypart == 9 ) then -- if he was shot in the head
tempString = tempString .. " (HEADSHOT!)"
else
tempString = tempString .. " (" .. getBodyPartName ( bodypart ) .. ")"
end
outputChatBox ( tempString )
else
outputChatBox ( getPlayerName ( source ) .. " died. (" .. getWeaponNameFromID ( weapon ) .. ") (" .. getBodyPartName ( bodypart ) .. ")" )
end
else
outputChatBox ( getPlayerName ( source ) .. " died. (" .. getWeaponNameFromID ( weapon ) .. ") (" .. getBodyPartName ( bodypart ) .. ")" )
end
end
addEventHandler ( "onPlayerWasted", root, deathMessageOnWasted )
</syntaxhighlight>

==See Also==
{{Clothes and body functions}}

AddPedClothes

2015-08-18T12:15:46Z

VenadHD: /* Example */

__NOTOC__
{{Server client function}}
{{Note|This function only works with peds using CJ skin (ID 0).}}
This function is used to set the current clothes on a [[ped]].

==Syntax==
<syntaxhighlight lang="lua">
bool addPedClothes ( ped thePed, string clothesTexture, string clothesModel, int clothesType )
</syntaxhighlight>
{{OOP||[[ped]]:addClothes||getPedClothes}}

===Required Arguments===
*'''thePed''': The [[ped]] whose clothes you want to change.
*'''clothesTexture''': A string determining the clothes texture that will be added. See the [[CJ Clothes|clothes catalog]].
*'''clothesModel''': A string determining the clothes model that will be added. See the [[CJ Clothes|clothes catalog]].
*'''clothesType''': A integer representing the clothes slot/type the clothes should be added to. See the [[CJ Clothes|clothes catalog]].

===Returns===
This function returns ''true'' if the clothes were successfully added to the ped, ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
This example adds a 'moto' helmet to a player when he gets on a nrg bike, and removes it when he gets off.
<syntaxhighlight lang="lua">
function onEnterVehicle ( theVehicle, seat, jacked )
if getElementModel ( theVehicle ) == 522 then -- if it's an nrg
addPedClothes ( source, "moto", "moto", 16 ) -- add the helmet
end
end
addEventHandler ( "onPlayerVehicleEnter", root, onEnterVehicle )

function onExitVehicle ( theVehicle, seat, jacked )
if getElementModel ( theVehicle ) == 522 then -- if it's an nrg
removePedClothes ( source, 16 ) -- remove the helmet
end
end
addEventHandler ( "onPlayerVehicleExit", root, onExitVehicle )
</syntaxhighlight>
</section>

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

AddPedClothes

2015-08-18T12:15:27Z

VenadHD: /* Example */

__NOTOC__
{{Server client function}}
{{Note|This function only works with peds using CJ skin (ID 0).}}
This function is used to set the current clothes on a [[ped]].

==Syntax==
<syntaxhighlight lang="lua">
bool addPedClothes ( ped thePed, string clothesTexture, string clothesModel, int clothesType )
</syntaxhighlight>
{{OOP||[[ped]]:addClothes||getPedClothes}}

===Required Arguments===
*'''thePed''': The [[ped]] whose clothes you want to change.
*'''clothesTexture''': A string determining the clothes texture that will be added. See the [[CJ Clothes|clothes catalog]].
*'''clothesModel''': A string determining the clothes model that will be added. See the [[CJ Clothes|clothes catalog]].
*'''clothesType''': A integer representing the clothes slot/type the clothes should be added to. See the [[CJ Clothes|clothes catalog]].

===Returns===
This function returns ''true'' if the clothes were successfully added to the ped, ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
This example adds a 'moto' helmet to a player when he gets on a nrg bike, and removes it when he gets off.
<syntaxhighlight lang="lua">
function onEnterVehicle ( theVehicle, seat, jacked )
if getElementModel ( theVehicle ) == 522 then -- if it's an nrg
addPedClothes ( source, "moto", "moto", 16 ) -- add the helmet
end
end
addEventHandler ( "onPlayerVehicleEnter", getRootElement(), onEnterVehicle )

function onExitVehicle ( theVehicle, seat, jacked )
if getElementModel ( theVehicle ) == 522 then -- if it's an nrg
removePedClothes ( source, 16 ) -- remove the helmet
end
end
addEventHandler ( "onPlayerVehicleExit", root, onExitVehicle )
</syntaxhighlight>
</section>

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

SetCameraShakeLevel

2015-08-18T12:13:50Z

VenadHD: /* Example */

{{Client function}}
__NOTOC__
{{New feature/item|3.0150|1.5|7343|
This function sets the camera shake level (as seen on the ''Are you going to San Fierro?'' singleplayer mission).}}

==Syntax==
<syntaxhighlight lang="lua">
bool setCameraShakeLevel ( int shakeLevel )
</syntaxhighlight>

===Required arguments===
*'''shakeLevel''': an integer between 0 and 255, which represents the camera shake intensity level.

===Returns===
Returns ''true'' if the camera shake level was changed, ''false'' if the required argument is incorrect or missing.

==Example==
This example adds a ''/camshake'' command which allows any player to manually change its camera shake level.
<syntaxhighlight lang="lua">
addCommandHandler( "camshake",
function( _, level )
local level = math.floor( level )
if level and level >=0 and level <= 255 then
setCameraShakeLevel( level )
outputChatBox( "Camera shake level updated to " .. level .. "." )
else
outputChatBox( "Camera shake level must be between 0 and 255." )
end
end
)
</syntaxhighlight>

==See also==
{{Client_camera_functions}}

SetCameraViewMode

2015-08-18T12:12:45Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}
This function allows you to set the camera's view mode if you are inside a [[vehicle]]. This indicates at what distance the camera will follow the player.

==Syntax==
<syntaxhighlight lang="lua">
bool setCameraViewMode ( int viewMode )
</syntaxhighlight>

===Required Arguments===
*'''viewMode''': The view mode you wish to use
{{Camera view modes}}

===Returns===
Returns ''true'' if the view was set correctly, ''false'' otherwise.

==Example==
This example sets the camera to bumper view when the local player enters any vehicle.
<syntaxhighlight lang="lua">
addEventHandler("onClientPlayerVehicleEnter", localPlayer, function()
setCameraViewMode(0)
end)
</syntaxhighlight>

==See Also==
{{Client camera functions}}

SetCameraTarget

2015-08-18T12:12:04Z

VenadHD: /* Example */

__NOTOC__
{{Server client function}}
This function allows you to set a player's camera to follow other elements instead. Currently supported element type is:
*[[Player]]s

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool setCameraTarget ( player thePlayer [, player target = nil ] )
</syntaxhighlight>
{{OOP||[[player]]:setCameraTarget|cameraTarget|getCameraTarget}}
===Required Arguments===
*'''thePlayer:''' The player whose camera you wish to modify.

===Optional Arguments===
*'''target:''' The player who you want the camera to follow. If none is specified, the camera will target the player.
'''Note:''' setCameraTarget will behave strangely if the target you want the camera to follow is inside a vehicle that has hydraulics (upgrade id: 1087) added server sided and if the target is not you.
</section>

<section name="Client 1" class="client" show="true">
<syntaxhighlight lang="lua">
bool setCameraTarget ( player target )
</syntaxhighlight>

===Required Arguments===
*'''target:''' The player who you want the local camera to follow.
</section>

{{New feature/item|3.0132|1.3.1|5212|
<section name="Client 2" class="client" show="true">
This syntax mantains the player targeted by the camera, but makes the camera look at the specified coordinates. It has no effect when the camera doesn't have a target.
<syntaxhighlight lang="lua">bool setCameraTarget ( float targetX, float targetY, float targetZ )</syntaxhighlight>

===Required Arguments===
*'''targetX, targetY, targetZ:''' The target position that you want the local camera to look at.
</section>}}

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

==Example==
This is an example of how one could implement a spectator function. Using the left and right arrow keys you can view other players. Note that this code isn't complete as it doesn't take into account joining or quitting players.
<section class="client" name="Client script" show="true">
<syntaxhighlight lang="lua">
g_Players = getElementsByType("player") -- get a list of all players in the server
for i,aPlayer in ipairs(g_Players) do -- find out what index the local player has in the list
if aPlayer == localPlayer then
g_CurrentSpectated = i
break
end
end

function spectatePrevious() -- decrement the spectate index and spectate the corresponding player
if g_CurrentSpectated == 1 then
g_CurrentSpectated = #g_Players
else
g_CurrentSpectated = g_CurrentSpectated - 1
end
setCameraTarget(g_Players[g_CurrentSpectated])
end

function spectateNext() -- increment the spectate index and spectate the corresponding player
if g_CurrentSpectated == #g_Players then
g_CurrentSpectated = 1
else
g_CurrentSpectated = g_CurrentSpectated + 1
end
setCameraTarget(g_Players[g_CurrentSpectated])
end

-- Bind above functions to arrow keys
bindKey("arrow_l", "down", spectatePrevious)
bindKey("arrow_r", "down", spectateNext)
</syntaxhighlight>
</section>

== Issues ==
{{Issues|
{{Issue|7594|setCameraTarget on a player inside a vehicle with hydraulics bugs camera}}
}}

==See Also==
{{Camera functions}}

SetCameraMatrix

2015-08-18T12:11:21Z

VenadHD: /* Example */

__NOTOC__
{{Server client function}}
This function sets the camera's position and direction. The first three arguments are the point at which the camera lies, the last three are the point the camera faces (or the point it "looks at").

'''Note:''' Calling this function takes the camera's focus away from the player and sets the camera in a fixed position and rotation. The camera's focus can be brought back to the player using the [[setCameraTarget]] function.
==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool setCameraMatrix ( player thePlayer, float positionX, float positionY, float positionZ [, float lookAtX, float lookAtY, float lookAtZ, float roll = 0, float fov = 70 ] )
</syntaxhighlight>
{{OOP||[[player]]:setCameraMatrix|cameraMatrix|getCameraMatrix}}
===Required Arguments===
*'''thePlayer:''' The player whose camera is to be changed.
*'''positionX:''' The x coordinate of the camera's position.
*'''positionY:''' The y coordinate of the camera's position.
*'''positionZ:''' The z coordinate of the camera's position.
*'''{{New feature/item|3.0141|1.4.1|7005|Instead of six coordinates, or two vectors, a Matrix can be supplied.}}'''

===Optional Arguments===
*'''lookAtX:''' The x coordinate of the point the camera faces.
*'''lookAtY:''' The y coordinate of the point the camera faces.
*'''lookAtZ:''' The z coordinate of the point the camera faces.
*'''roll:''' The camera roll angle, -180 to 180. A value of 0 means the camera sits straight, positive values will turn it counter-clockwise and negative values will turn it clockwise. -180 or 180 means the camera is upside down.
*'''fov:''' the field of view angle, 0 to 180. The higher this value is, the more you will be able to see what is to your sides.
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool setCameraMatrix ( float positionX, float positionY, float positionZ [, float lookAtX, float lookAtY, float lookAtZ, float roll = 0, float fov = 70 ] )
</syntaxhighlight>
{{OOP|This is under the static class '''Camera'''|Camera.setMatrix|matrix|getCameraMatrix}}

===Required Arguments===
*'''positionX:''' The x coordinate of the camera's position.
*'''positionY:''' The y coordinate of the camera's position.
*'''positionZ:''' The z coordinate of the camera's position.
*'''{{New feature/item|3.0141|1.4.1|7005|Instead of six coordinates, or two vectors, a Matrix can be supplied.}}'''

===Optional Arguments===
*'''lookAtX:''' The x coordinate of the point the camera faces.
*'''lookAtY:''' The y coordinate of the point the camera faces.
*'''lookAtZ:''' The z coordinate of the point the camera faces.
*'''roll:''' The camera roll angle, -180 to 180. A value of 0 means the camera sits straight, positive values will turn it counter-clockwise and negative values will turn it clockwise. -180 or 180 means the camera is upside down.
*'''fov:''' the field of view angle, 0 to 180. The higher this value is, the more you will be able to see what is to your sides.
</section>

===Returns===
Returns ''true'' if the arguments are valid, ''false'' otherwise.

==Example==
This code fixates the camera onto the Vinewood sign in Los Santos for any player that joins the server:
<section class="server" name="Server script" show="true">
<syntaxhighlight lang="lua">
function setCameraOnPlayerJoin()
-- slowly fade the camera in to make the screen visible
fadeCamera(source, true, 5)
-- set the player's camera to a fixed position, looking at a fixed point
setCameraMatrix(source, 1468.8785400391, -919.25317382813, 100.153465271, 1468.388671875, -918.42474365234, 99.881813049316)
end
addEventHandler("onPlayerJoin", root, setCameraOnPlayerJoin)</syntaxhighlight>
</section>

==See Also==
{{Camera functions}}

SetCameraClip

2015-08-18T12:10:29Z

VenadHD: /* Example */

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

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

==Syntax==
<syntaxhighlight lang="lua">
bool setCameraClip ( [ bool objects = true, bool vehicles = true ] )
</syntaxhighlight>
{{OOP||[[Camera]].setClip||getCameraClip}}

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

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

==Example==
This function enables it to look though cars
<syntaxhighlight lang="lua">
function enableCameraThoughCars ()
setCameraClip (true,false)
outputChatBox ("Your camera can see the vehicle interior now!",255,0,0,false)
end
addEventHandler ("onClientResourceStart",resourceRoot,enableCameraThoughCars)
</syntaxhighlight>

==See Also==
{{Client camera functions}}

GetCameraViewMode

2015-08-18T12:08:41Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}
This function allows you to get the camera's view mode. This indicates at what distance the camera will follow the player.
*'''Note:''' It currently only returns vehicle view modes

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

===Returns===
Returns an [[int]] indicating the current camera view mode. Their meanings can be seen below.

{{Camera view modes}}

==Example==
This example tells the player their current camera view when they change it
<syntaxhighlight lang="lua">
function onPlayerSpawn ( theSpawnpoint )
currentCam("fire") -- start a repeating check
end
addEventHandler ( "onClientPlayerSpawn", root, onPlayerSpawn )

function currentCam(key)
if (getControlState(key)) then
outputChatBox("Your current cam view is: "..getCameraViewMode()..".")
end
end
</syntaxhighlight>

==See Also==
{{Client camera functions}}

FadeCamera

2015-08-18T12:06:56Z

VenadHD: /* Example */

{{Server client function}}
__NOTOC__
This function will fade a player's camera to a color or back to normal over a specified time period. This will also affect the sound volume for the player (50% faded = 50% volume, full fade = no sound). For clientside scripts you can perform 2 fade ins or fade outs in a row, but for serverside scripts you must use one then the other.

''Note: The speed of the effect depends directly on the current gamespeed.''

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool fadeCamera ( player thePlayer, bool fadeIn, [ float timeToFade = 1.0, int red = 0, int green = 0, int blue = 0 ] )
</syntaxhighlight>
{{OOP||[[player]]:fadeCamera}}
===Required Arguments===
* '''thePlayer:''' The player whose camera you wish to fade.
* '''fadeIn:''' Should the camera be faded in or out? Pass ''true'' to fade the camera in, ''false'' to fade it out to a color.

===Optional Arguments===
* '''timeToFade:''' The number of seconds it should take to fade. Any number less than 1 makes the fade instant.
* '''red:''' The amount of red in the color that the camera fades out to (0 - 255). Not required for fading in.
* '''green:''' The amount of green in the color that the camera fades out to (0 - 255). Not required for fading in.
* '''blue:''' The amount of blue in the color that the camera fades out to (0 - 255). Not required for fading in.
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool fadeCamera ( bool fadeIn, [ float timeToFade = 1.0, int red = 0, int green = 0, int blue = 0 ] )
</syntaxhighlight>
{{OOP||Camera.fade}}
===Required Arguments===
* '''fadeIn:''' Should the camera be faded in our out? Pass ''true'' to fade the camera in, ''false'' to fade it out to a color.

===Optional Arguments===
* '''timeToFade:''' The number of seconds it should take to fade. Any number less than 1 makes the fade instant.
* '''red:''' The amount of red in the color that the camera fades out to (0 - 255). Not required for fading in.
* '''green:''' The amount of green in the color that the camera fades out to (0 - 255). Not required for fading in.
* '''blue:''' The amount of blue in the color that the camera fades out to (0 - 255). Not required for fading in.
</section>

===Returns===
Returns ''true'' if the camera was faded successfully, ''false'' if invalid arguments were passed to the function.

==Example==
<section name="Server example" class="server" show="true">
When a player gets damaged, place a quick fade-to-red effect on his screen.
<syntaxhighlight lang="lua">
function addRednessOnDamage ( )
fadeCamera ( source, false, 1.0, 255, 0, 0 ) -- fade the player's camera to red over a period of 1 second
setTimer ( fadeCameraDelayed, 500, 1, source ) -- don't let it go to opaque red, interrupt it after half a second and fade back to normal
end
addEventHandler ( "onPlayerDamage", root, addRednessOnDamage )

function fadeCameraDelayed(player) -- This function prevents debug warnings when the player disconnects while the timer is running.
if (isElement(player)) then
fadeCamera(player, true, 0.5)
end
end
</syntaxhighlight>
</section>

==See Also==
{{Camera_functions}}

StopSound

2015-08-18T11:56:10Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}
Stops the sound playback for specified [[sound]] [[element]]. The sound element is also destroyed.

==Syntax==
<syntaxhighlight lang="lua">bool stopSound ( element theSound )</syntaxhighlight>
{{OOP||[[sound]]:stop}}
===Required Arguments===
*'''theSound:''' the [[sound]] [[element]] you want to stop playing.

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

==Example==
<syntaxhighlight lang="lua">
function startMySound()
sound = playSound( "sound.mp3", true )
end
addEventHandler( "onClientResourceStart", resourceRoot, startMySound )

function stopMySound()
stopSound( sound )
end
addCommandHandler ( "stopsound", stopMySound ) --using the command 'stopsound' will stop the sound
</syntaxhighlight>

==See Also==
{{Client_audio_functions}}
[[AR:stopSound]]

SetSoundVolume

2015-08-18T11:55:24Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}
This function is used to change the volume level of the specified [[sound]] [[element]].
Use a player element to control a players voice with this function.

==Syntax==
<syntaxhighlight lang="lua">bool setSoundVolume ( element theSound, float volume )</syntaxhighlight>
{{OOP||[[sound]]:setVolume|volume|getSoundVolume}}
===Required Arguments===
*'''theSound:''' The [[sound]] [[element]] which volume you want to modify.
*'''volume:''' A [[float]]ing point number representing the desired volume level. Range is from '''0.0''' to '''1.0'''

===Returns===
Returns ''true'' if the [[sound]] [[element]] volume was successfully changed, ''false'' otherwise.

==Example==
<syntaxhighlight lang="lua">
function wasted (killer, weapon, bodypart)
local sound = playSound("sounds/wasted.mp3") --Play wasted.mp3 from the sounds folder
setSoundVolume(sound, 0.5) -- set the sound volume to 50%
end

addEventHandler("onClientPlayerWasted", localPlayer, wasted) --add the event handler
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.2|Added player element for voice control}}

==See Also==
{{Client_audio_functions}}
[[AR:setSoundVolume]]

PlaySoundFrontEnd

2015-08-18T11:52:56Z

VenadHD: /* Example */

{{Server client function}}
__NOTOC__
This function plays a frontend sound for the specified player.
{{Note|These sounds can be disabled with [[setWorldSoundEnabled]] so if these sounds stop working you should check if you're disabling the sounds.}}

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

===Required Arguments===
*'''thePlayer:''' the [[player]] you want the sound to play for.
*'''sound:''' a whole [[int]] specifying the sound id to play. Valid values are:
{{Sounds}}
</section>
<section name="Client" class="client" show="false">
<syntaxhighlight lang="lua">
bool playSoundFrontEnd ( int sound )
</syntaxhighlight>
{{New feature/item|3.0141|1.4.0|6987|{{OOP||[[Sound]].playFrontEnd}}}}

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

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

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

==See Also==
{{Client_audio_functions}}

[[de:playSoundFrontEnd]]
[[ar:playSoundFrontEnd]]

PlaySound3D

2015-08-18T11:51:55Z

VenadHD: /* Example */

__NOTOC__
{{Client function}}
Creates a [[sound]] [[element]] in the GTA world and plays it immediately after creation for the local player. [[setElementPosition]] can be used to move the [[sound]] element around after it has been created. Remember to use [[setElementDimension]] after creating the sound to play it outside of dimension 0.<br />
<br />
'''Note:''' The only supported audio formats are MP3, WAV, OGG, RIFF, MOD, XM, IT and S3M.
{{Note|For performance reasons, when using playSound3D for effects that will be played lots (i.e. weapon fire), it is recommend that you convert your audio file to a one channel (mono) WAV with sample rate of 22050 Hz or less. Also consider adding a limit on how often the effect can be played e.g. once every 50ms.}}
==Syntax==
<syntaxhighlight lang="lua">element playSound3D ( string soundPath, float x, float y, float z, [ bool looped = false, bool throttled = true ] )</syntaxhighlight>
{{OOP||[[Sound|Sound3D]].create}}
===Required Arguments===
*'''soundPath:''' the [[filepath]] to the sound file you want to play. (Sound file has to be predefined in the [[meta.xml]] file with <file /> tag. And also can use url instead of [[filepath]] )
*'''x:''' a [[float]]ing point number representing the X coordinate on the map.
*'''y:''' a [[float]]ing point number representing the Y coordinate on the map.
*'''z:''' a [[float]]ing point number representing the Z coordinate on the map.

===Optional Arguments===
{{OptionalArg}}
*'''looped:''' A [[boolean]] representing whether the sound will be looped. To loop the sound, use ''true''.
{{New feature/item|3.0150|1.5||
*'''throttled:''' a [[boolean]] representing whether the sound will be throttled (i.e. given reduced download bandwidth). To throttle the sound, use ''true''. Sounds will be throttled per default and only for URLs.
}}

===Returns===
Returns a [[sound]] [[element]] if the sound was successfully created, ''false'' otherwise.

==Example==
This example creates a looping sound within a pizza shop. The pizza shop is in san fierro near pier 69
<section name="Example" class="client" show="true">
<syntaxhighlight lang="lua">
function onResourceStart()
local sound = playSound3D("sounds/song.mp3", 373.14, -125.21, 1001, true)
end
addEventHandler("onClientResourceStart", resourceRoot, onResourceStart)
</syntaxhighlight>
</section>
This example play internet radio in groove street.
<section name="Example 2" class="client" show="true" >
<syntaxhighlight lang="lua">
addEventHandler( 'onClientResourceStart', resourceRoot,
function( )
local uSound = playSound3D( 'http://193.34.51.25:80', 2498, -1659, 12 )
setSoundMaxDistance( uSound, 100 )
end
)
</syntaxhighlight>
</section>

==See Also==
{{Client_audio_functions}}
[[AR:playSound3D]]
[[DE:playSound3D]]
[[RU:playSound3D]]