Multi Theft Auto: Wiki - User contributions [en]

GetElementMatrix

2015-03-10T09:55:43Z

Arezu: Why was this text changed? the regular getElementMatrix returns false for objects that are not streamed in.

{{Client function}}
__NOTOC__
This function gets an [[element]]'s transform [[matrix]]. This contains 16 float values that multiplied to a point will give you the point transformed. It is most useful for matrix calculations such as calculating offsets. For further information, please refer to a tutorial of matrices in computer graphics programming.
{{Note|The [[matrix]] returned by this function is [http://bugs.mtasa.com/view.php?id{{=}}6984 not setup correctly for some calculations] unless the '''legacy''' argument is set to '''''false'''''.}}
{{Tip|''For [[matrix]] manipulation which goes beyond the basic examples given on this page, see the [[Lua matrix library]].'' If you are using MTA: SA 1.4 or higher, using the built-in [[matrix]] class is also recommended.}}
==Syntax==
<syntaxhighlight lang="lua">
table getElementMatrix ( element theElement [, bool legacy = true ] )
</syntaxhighlight>
{{OOP||[[element]]:getMatrix|matrix|setElementMatrix}}

===Required Arguments===
*'''theElement:''' The [[element]] which you wish to retrieve the [[matrix]] for.

===Optional Arguments===
*'''legacy:''' Set to ''false'' to return correctly setup [[matrix]] (i.e. Last column in the first 3 rows set to zero).

===Returns===
Returns a multi-dimensional array (which can be transformed into a proper [[matrix]] class using ''Matrix.create'' method) containing a 4x4 matrix. Returns ''false'' if the element is not streamed in, and not a [[vehicle]], [[ped]] or [[object]].

==Example==
This example creates a utility function that turns an offset into a position that is relative to the specified element.
<syntaxhighlight lang="lua">
function getPositionFromElementOffset(element,offX,offY,offZ)
local m = getElementMatrix ( element ) -- Get the matrix
local x = offX * m[1][1] + offY * m[2][1] + offZ * m[3][1] + m[4][1] -- Apply transform
local y = offX * m[1][2] + offY * m[2][2] + offZ * m[3][2] + m[4][2]
local z = offX * m[1][3] + offY * m[2][3] + offZ * m[3][3] + m[4][3]
return x, y, z -- Return the transformed point
end

-- Get the position of a point 3 units to the right of the element:
x,y,z = getPositionFromElementOffset(element,3,0,0)

-- Get the position of a point 2 units in front of the element:
x,y,z = getPositionFromElementOffset(element,0,2,0)

-- Get the position of a point 1 unit above the element:
x,y,z = getPositionFromElementOffset(element,0,0,1)

</syntaxhighlight>

This example creates some more matrix utility functions
<syntaxhighlight lang="lua">
function getMatrixLeft(m)
return m[1][1], m[1][2], m[1][3]
end
function getMatrixForward(m)
return m[2][1], m[2][2], m[2][3]
end
function getMatrixUp(m)
return m[3][1], m[3][2], m[3][3]
end
function getMatrixPosition(m)
return m[4][1], m[4][2], m[4][3]
end

local mat = getElementMatrix(element) -- Get the matrix
x,y,z = getMatrixLeft(mat) -- Get the matrix left direction
x,y,z = getMatrixForward(mat) -- Get the matrix forward direction
x,y,z = getMatrixUp(mat) -- Get the matrix up direction

</syntaxhighlight>

This example function allows you to get the element matrix of an element that is not streamed in.
<syntaxhighlight lang="lua">
function getElementMatrix(element)
local rx, ry, rz = getElementRotation(element, "ZXY")
rx, ry, rz = math.rad(rx), math.rad(ry), math.rad(rz)
local matrix = {}
matrix[1] = {}
matrix[1][1] = math.cos(rz)*math.cos(ry) - math.sin(rz)*math.sin(rx)*math.sin(ry)
matrix[1][2] = math.cos(ry)*math.sin(rz) + math.cos(rz)*math.sin(rx)*math.sin(ry)
matrix[1][3] = -math.cos(rx)*math.sin(ry)
matrix[1][4] = 1

matrix[2] = {}
matrix[2][1] = -math.cos(rx)*math.sin(rz)
matrix[2][2] = math.cos(rz)*math.cos(rx)
matrix[2][3] = math.sin(rx)
matrix[2][4] = 1

matrix[3] = {}
matrix[3][1] = math.cos(rz)*math.sin(ry) + math.cos(ry)*math.sin(rz)*math.sin(rx)
matrix[3][2] = math.sin(rz)*math.sin(ry) - math.cos(rz)*math.cos(ry)*math.sin(rx)
matrix[3][3] = math.cos(rx)*math.cos(ry)
matrix[3][4] = 1

matrix[4] = {}
matrix[4][1], matrix[4][2], matrix[4][3] = getElementPosition(element)
matrix[4][4] = 1

return matrix
end
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04186|Added legacy argument}}

==See Also==
{{Client_element_functions}}

CreateProjectile

2015-02-23T20:02:47Z

Arezu: /* Example */

__NOTOC__
{{Client function}}
This function creates a projectile of the specified type on the specified coordinates.

{{Note|
*'''Model''' argument is not synchronized between clients. Clients differs from local player see always standard projectile model.
*'''Target''' argument can only be defined as a player or another projectile.
}}

==Syntax==
<syntaxhighlight lang="lua">
projectile createProjectile ( element creator, int weaponType [, float posX, float posY, float posZ, float force = 1.0, element target = nil, float rotX, float rotY, float rotZ, float velX, float velY, float velZ, int model ] )
</syntaxhighlight>
{{OOP||[[Projectile]]}}

===Required Arguments===
*'''creator:''' The [[element]] representing creator of the projectile. In case you want the projectile to be synced for everybody creator must be the local player or his vehicle.
*'''weaponType:''' [[int]] representing the projectile weaponType (characteristics). Valid IDs are:
{{Projectiles}}

===Optional Arguments===
{{OptionalArg}}
*'''posX''', '''posY''', '''posZ''': [[float]] starting coordinates for the projectile. They are coordinates of creator by default.
*'''force''': [[float]] representing the starting force for throwable projectiles.
*'''target''': [[element]] target used for heat seeking rockets.
*'''rotX''', '''rotY''', '''rotZ''': [[float]] starting rotation for the projectile.
*'''velX''', '''velY''', '''velZ''': [[float]] starting velocity for the projectile.
*'''model''': Integer representing the projectile's model, uses default model for weaponType if not specified.

==Returns==
Returns a ''[[projectile]]'' element if [[projectile]] creation was successful. Returns ''false'' if unable to create a [[projectile]] (wrong weapon ID or projectiles limit was reached).

==Example==
This example makes a rocket minigun (minigun shooting with rockets).
<syntaxhighlight lang="lua">
-- This function gets triggered everytime player shoots.
function onClientPlayerWeaponFireFunc(weapon,ammo,ammoInClip,hitX,hitY,hitZ,hitElement)
if weapon == 38 then -- if source is a local player and he uses minigun...
x,y,z = getElementPosition(getLocalPlayer())
if not createProjectile(getLocalPlayer(),19,x,y,z,200) then -- then we either create a projectile...
outputChatBox ( "Rocket minigun overheated! Give it a rest pal!", source ) -- or if projectile limit is reached we output player a chat message
end
end
end

-- Don't forget to add the onClientPlayerWeaponFireFunc function as a handler for onClientPlayerWeaponFire.
addEventHandler("onClientPlayerWeaponFire", getLocalPlayer(), onClientPlayerWeaponFireFunc)
</syntaxhighlight>

This example code shoots a projectile from your occupied vehicle that travels in the direction your vehicle is facing when you press vehicle_fire (left mouse button with default controls)
<syntaxhighlight lang="lua">

function shootProjectile()
local vehicle = getPedOccupiedVehicle(localPlayer)
-- Only create projectile if we are inside a vehicle
if(vehicle)then
local x, y, z = getElementPosition(vehicle)
createProjectile(vehicle, 19, x, y, z)
end
end

bindKey("vehicle_fire", "down", shootProjectile)
</syntaxhighlight>

==Issues==
{{Issues|
{{Issue|8132|Projectile target only allows player element (and a projectile?)}}
{{Issue|5072|createProjectile creates one projectile for every person in the vehicle}}
}}

==See also==
{{Client projectile functions}}

[[it:createProjectile]]

Matrix

2014-08-27T17:58:43Z

Arezu: /* Variables */

Matrix

2014-08-27T17:29:14Z

Arezu:

GetElementMatrix

2014-08-27T16:59:38Z

Arezu: /* Example */

{{Client function}}
__NOTOC__
This function gets an element's transform matrix. This contains 16 float values that multiplied to a point will give you the point transformed. It is most useful for matrix calculations such as calculating offsets. For further information, please refer to a tutorial of matrices in computer graphics programming.
{{Note|The matrix returned by this function is [http://bugs.mtasa.com/view.php?id{{=}}6984 not setup correctly for some calculations.] unless the '''legacy''' argument is set to '''false'''}}
{{Tip|''For matrix manipulation which goes beyond the basic examples given on this page, see the [[Lua matrix library]].''}}
==Syntax==
<syntaxhighlight lang="lua">
table getElementMatrix ( element theElement [, bool legacy = true ] )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element which you wish to retrieve the matrix for

===Optional Arguments===
*'''legacy :''' Set to false to return correctly setup matrix. (i.e. Last column in the first 3 rows set to zero.)

===Returns===
Returns a multi-dimensional array containing a 4x4 matrix. Returns false if the element is not streamed in, and not a vehicle or ped.

==Example==
This example creates a utility function that turns an offset into a position that is relative to the specified element.
<syntaxhighlight lang="lua">
function getPositionFromElementOffset(element,offX,offY,offZ)
local m = getElementMatrix ( element ) -- Get the matrix
local x = offX * m[1][1] + offY * m[2][1] + offZ * m[3][1] + m[4][1] -- Apply transform
local y = offX * m[1][2] + offY * m[2][2] + offZ * m[3][2] + m[4][2]
local z = offX * m[1][3] + offY * m[2][3] + offZ * m[3][3] + m[4][3]
return x, y, z -- Return the transformed point
end

-- Get the position of a point 3 units to the left of the element:
x,y,z = getPositionFromElementOffset(element,3,0,0)

-- Get the position of a point 2 units in front of the element:
x,y,z = getPositionFromElementOffset(element,0,2,0)

-- Get the position of a point 1 unit above the element:
x,y,z = getPositionFromElementOffset(element,0,0,1)

</syntaxhighlight>

This example creates some more matrix utility functions
<syntaxhighlight lang="lua">
function getMatrixLeft(m)
return m[1][1], m[1][2], m[1][3]
end
function getMatrixForward(m)
return m[2][1], m[2][2], m[2][3]
end
function getMatrixUp(m)
return m[3][1], m[3][2], m[3][3]
end
function getMatrixPosition(m)
return m[4][1], m[4][2], m[4][3]
end

local mat = getElementMatrix(element) -- Get the matrix
x,y,z = getMatrixLeft(mat) -- Get the matrix left direction
x,y,z = getMatrixForward(mat) -- Get the matrix forward direction
x,y,z = getMatrixUp(mat) -- Get the matrix up direction

</syntaxhighlight>

This example function shows you what getElementMatrix does internally
<syntaxhighlight lang="lua">
function getElementMatrix(element)
local rx, ry, rz = getElementRotation(element, "ZXY")
rx, ry, rz = math.rad(rx), math.rad(ry), math.rad(rz)
local matrix = {}
matrix[1] = {}
matrix[1][1] = math.cos(rz)*math.cos(ry) - math.sin(rz)*math.sin(rx)*math.sin(ry)
matrix[1][2] = math.cos(ry)*math.sin(rz) + math.cos(rz)*math.sin(rx)*math.sin(ry)
matrix[1][3] = -math.cos(rx)*math.sin(ry)
matrix[1][4] = 1

matrix[2] = {}
matrix[2][1] = -math.cos(rx)*math.sin(rz)
matrix[2][2] = math.cos(rz)*math.cos(rx)
matrix[2][3] = math.sin(rx)
matrix[2][4] = 1

matrix[3] = {}
matrix[3][1] = math.cos(rz)*math.sin(ry) + math.cos(ry)*math.sin(rz)*math.sin(rx)
matrix[3][2] = math.sin(rz)*math.sin(ry) - math.cos(rz)*math.cos(ry)*math.sin(rx)
matrix[3][3] = math.cos(rx)*math.cos(ry)
matrix[3][4] = 1

matrix[4] = {}
matrix[4][1], matrix[4][2], matrix[4][3] = getElementPosition(element)
matrix[4][4] = 1

return matrix
end
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04186|Added legacy argument}}

==See Also==
{{Client_element_functions}}

SetCameraTarget

2013-07-15T12:26:13Z

Arezu: /* Syntax */

{{Note|The function already places camera behind the player. No second call or a timer is needed.
{{Needs Checking|No it doesn't. A timer of no less than 112 ms was required for the rotation to be set.}}}}

__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 [, element target = nil ] )
</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The player whose camera you wish to modify.

===Optional Arguments===
*'''target:''' The element that 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 ( element target )
</syntaxhighlight>

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

{{New feature/item|4.0132|1.3.1|5212|
<section name="Client 2" class="client" show="true">
<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 == getLocalPlayer() 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>

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

AddVehicleUpgrade

2013-07-15T12:22:26Z

Arezu: /* Required Arguments */

__NOTOC__
{{Server client function}}
This function adds an upgrade to an existing vehicle, eg: nos, hyrdraulics.

==Syntax==
<syntaxhighlight lang="lua">bool addVehicleUpgrade ( vehicle theVehicle, int upgrade )</syntaxhighlight>

===Required Arguments===
*'''theVehicle''': The [[element]] representing the [[vehicle]] you wish to add the upgrade to.
*'''upgrade''': The id of the upgrade you wish to add. (1000 to 1193), ''see [[Vehicle Upgrades]]''
'''Note:''' setCameraTarget will behave strangely if you use hydraulics (upgrade id: 1087) server sided and when your camera target is the player inside the vehicle with hydraulics and if the player is not you.

==Returns==
Returns ''true'' if the upgrade was successfully added to the vehicle, otherwise ''false''.

==Example==
<section name="Example 1" class="server" show="true">
This serverside function allows the user to get an upgrade by typing a command:
<syntaxhighlight lang="lua">
-- define the handler function for our command
function consoleAddUpgrade ( thePlayer, commandName, id )
-- make sure the player is in a vehicle
if ( isPedInVehicle ( thePlayer ) ) then
-- convert the given ID from a string to a number
local id = tonumber ( id )
-- get the player's vehicle
local theVehicle = getPedOccupiedVehicle ( thePlayer )
-- add the requested upgrade to the vehicle
local success = addVehicleUpgrade ( theVehicle, id )
-- inform the player of whether the upgrade was added successfully
if ( success ) then
outputConsole ( getVehicleUpgradeSlotName ( id ) .. " upgrade added.", thePlayer )
else
outputConsole ( "Failed to add upgrade.", thePlayer )
end
else
outputConsole ( "You must be in a vehicle!", thePlayer )
end
end
-- add the function as a handler for the "addupgrade" command
addCommandHandler ( "addupgrade", consoleAddUpgrade )
</syntaxhighlight>
</section>

<section name="Example 2" class="client" show="true">
This client-side script gives vehicles a nitro upgrade whenever they pass through a certain collision shape:
<syntaxhighlight lang="lua">
-- create a collision shape
local nitroColShape = createColSphere ( 1337, 100, 12, 2 )

-- attach the collision shape to an 'onClientColShapeHit' event
function onNitroColShapeHit ( hitElement, matchingDimension )
if ( getElementType ( hitElement ) == "vehicle" ) then
-- add a nitro upgrade if the element that hit the colshape is a vehicle
addVehicleUpgrade ( hitElement, 1010 )
end
end
addEventHandler ( "onClientColShapeHit", nitroColShape, onNitroColShapeHit )
</syntaxhighlight>
</section>

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

AddVehicleUpgrade

2013-07-15T12:21:49Z

Arezu: /* Required Arguments */

__NOTOC__
{{Server client function}}
This function adds an upgrade to an existing vehicle, eg: nos, hyrdraulics.

==Syntax==
<syntaxhighlight lang="lua">bool addVehicleUpgrade ( vehicle theVehicle, int upgrade )</syntaxhighlight>

===Required Arguments===
*'''theVehicle''': The [[element]] representing the [[vehicle]] you wish to add the upgrade to.
*'''upgrade''': The id of the upgrade you wish to add. (1000 to 1193), ''see [[Vehicle Upgrades]]''
'''Note:''' setCameraTarget will behave strangely if you use hydraulics (upgrade id: 1087) server sided and when your camera target is the player inside the vehicle with hydraulics and the player is not you.

==Returns==
Returns ''true'' if the upgrade was successfully added to the vehicle, otherwise ''false''.

==Example==
<section name="Example 1" class="server" show="true">
This serverside function allows the user to get an upgrade by typing a command:
<syntaxhighlight lang="lua">
-- define the handler function for our command
function consoleAddUpgrade ( thePlayer, commandName, id )
-- make sure the player is in a vehicle
if ( isPedInVehicle ( thePlayer ) ) then
-- convert the given ID from a string to a number
local id = tonumber ( id )
-- get the player's vehicle
local theVehicle = getPedOccupiedVehicle ( thePlayer )
-- add the requested upgrade to the vehicle
local success = addVehicleUpgrade ( theVehicle, id )
-- inform the player of whether the upgrade was added successfully
if ( success ) then
outputConsole ( getVehicleUpgradeSlotName ( id ) .. " upgrade added.", thePlayer )
else
outputConsole ( "Failed to add upgrade.", thePlayer )
end
else
outputConsole ( "You must be in a vehicle!", thePlayer )
end
end
-- add the function as a handler for the "addupgrade" command
addCommandHandler ( "addupgrade", consoleAddUpgrade )
</syntaxhighlight>
</section>

<section name="Example 2" class="client" show="true">
This client-side script gives vehicles a nitro upgrade whenever they pass through a certain collision shape:
<syntaxhighlight lang="lua">
-- create a collision shape
local nitroColShape = createColSphere ( 1337, 100, 12, 2 )

-- attach the collision shape to an 'onClientColShapeHit' event
function onNitroColShapeHit ( hitElement, matchingDimension )
if ( getElementType ( hitElement ) == "vehicle" ) then
-- add a nitro upgrade if the element that hit the colshape is a vehicle
addVehicleUpgrade ( hitElement, 1010 )
end
end
addEventHandler ( "onClientColShapeHit", nitroColShape, onNitroColShapeHit )
</syntaxhighlight>
</section>

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

SetElementDimension

2013-07-15T12:16:09Z

Arezu: /* Returns */

{{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>

===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", getRootElement ( ), 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", getRootElement ( ), onPlayerExitVehicle )
</syntaxhighlight>
</section>

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

[[de:setElementDimension]]

SetElementDimension

2013-07-15T12:14:46Z

Arezu: /* Returns */

{{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>

===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.

==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", getRootElement ( ), 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", getRootElement ( ), onPlayerExitVehicle )
</syntaxhighlight>
</section>

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

[[de:setElementDimension]]

SetElementDimension

2013-07-15T12:14:23Z

Arezu: /* Returns */

{{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>

===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, and if '''theElement''' is a player, then it has to be alive, ''false'' otherwise.

==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", getRootElement ( ), 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", getRootElement ( ), onPlayerExitVehicle )
</syntaxhighlight>
</section>

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

[[de:setElementDimension]]

SetElementDimension

2013-07-15T12:13:37Z

Arezu: /* Returns */

{{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>

===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, and if '''theElement''' is a player and is alive, ''false'' otherwise.

==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", getRootElement ( ), 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", getRootElement ( ), onPlayerExitVehicle )
</syntaxhighlight>
</section>

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

[[de:setElementDimension]]

SetElementDimension

2013-07-15T12:09:33Z

Arezu: /* Returns */

{{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>

===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.

==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", getRootElement ( ), 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", getRootElement ( ), onPlayerExitVehicle )
</syntaxhighlight>
</section>

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

[[de:setElementDimension]]

SetElementDimension

2013-07-15T12:09:06Z

Arezu: /* Returns */

{{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>

===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.</br>
'''Note:''' If '''theElement''' is a player, then it has to be alive to be able to change its dimension.

==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", getRootElement ( ), 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", getRootElement ( ), onPlayerExitVehicle )
</syntaxhighlight>
</section>

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

[[de:setElementDimension]]

SetElementDimension

2013-07-15T12:08:31Z

Arezu: /* Returns */

{{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>

===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.
'''Note:''' If '''theElement''' is a player, then it has to be alive to be able to change its dimension.

==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", getRootElement ( ), 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", getRootElement ( ), onPlayerExitVehicle )
</syntaxhighlight>
</section>

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

[[de:setElementDimension]]

CreateProjectile

2013-07-10T17:01:05Z

Arezu: /* Required Arguments */

__NOTOC__
{{Client function}}
This function creates a projectile of the specified type on the specified coordinates.

==Syntax==
<syntaxhighlight lang="lua">
projectile createProjectile ( element creator, int weaponType [, float posX, float posY, float posZ, float force = 1.0, element target = nil, float rotX, float rotY, float rotZ, float velX, float velY, float velZ, int model ] )
</syntaxhighlight>

==Required Arguments==
*'''creator:''' The [[element]] representing creator of the projectile. In case you want the projectile to be synced for everybody creator must be the local player or his vehicle.
*'''weaponType:''' [[int]] representing the projectile weaponType (characteristics). Valid IDs are:
{{Projectiles}}

==Optional Arguments==
{{OptionalArg}}
*'''posX''','''posY''','''posZ''': [[float]] starting coordinates for the projectile. They are coordinates of creator by default.
*'''force''': [[float]] representing the starting force of the projectile.
*'''target''': [[element]] target used for heat seeking rockets.
*'''rotX''','''rotY''','''rotZ''': [[float]] starting rotation for the projectile.
*'''velX''','''velY''','''velZ''': [[float]] starting velocity for the projectile.
*'''model''': Integer representing the projectile's model, uses default model for weaponType if not specified.

==Returns==
Returns a ''[[projectile]]'' element if [[projectile]] creation was succesfull. Returns ''false'' if unable to create a [[projectile]] (wrong weapon ID or projectiles limit was reached).

==Example==
This example makes a rocket minigun (minigun shooting with rockets).
<syntaxhighlight lang="lua">
-- This function gets triggered everytime player shoots.
function onClientPlayerWeaponFireFunc(weapon,ammo,ammoInClip,hitX,hitY,hitZ,hitElement)
if weapon == 38 then -- if source is a local player and he uses minigun...
x,y,z = getElementPosition(getLocalPlayer())
if not createProjectile(getLocalPlayer(),19,x,y,z,200) then -- then we either create a projectile...
outputChatBox ( "Rocket minigun overheated! Give it a rest pal!", source ) -- or if projectile limit is reached we output player a chat message
end
end
end

-- Don't forget to add the onClientPlayerWeaponFireFunc function as a handler for onClientPlayerWeaponFire.
addEventHandler("onClientPlayerWeaponFire", getLocalPlayer(), onClientPlayerWeaponFireFunc)
</syntaxhighlight>

==See also==
{{Client projectile functions}}

[[it:createProjectile]]

GetElementMatrix

2013-07-10T12:31:03Z

Arezu: /* Example */

{{Client function}}
__NOTOC__
This function gets an element's transform matrix. This contains 16 float values that multiplied to a point will give you the point transformed. It is most useful for matrix calculations such as calculating offsets. For further information, please refer to a tutorial of matrices in computer graphics programming.
{{Note|The matrix returned by this function is [http://bugs.mtasa.com/view.php?id{{=}}6984 not setup correctly for some calculations.] unless the '''legacy''' argument is set to '''false'''}}
{{Tip|''For matrix manipulation which goes beyond the basic examples given on this page, see the [[Lua matrix library]].''}}
==Syntax==
<syntaxhighlight lang="lua">
table getElementMatrix ( element theElement [, bool legacy = true ] )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element which you wish to retrieve the matrix for

===Optional Arguments===
*'''legacy :''' Set to false to return correctly setup matrix. (i.e. Last column in the first 3 rows set to zero.)

===Returns===
Returns a multi-dimensional array containing a 4x4 matrix. Returns false if the element is not streamed in, and not a vehicle or ped.

==Example==
This example creates a utility function that turns an offset into a position that is relative to the specified element.
<syntaxhighlight lang="lua">
function getPositionFromElementOffset(element,offX,offY,offZ)
local m = getElementMatrix ( element ) -- Get the matrix
local x = offX * m[1][1] + offY * m[2][1] + offZ * m[3][1] + m[4][1] -- Apply transform
local y = offX * m[1][2] + offY * m[2][2] + offZ * m[3][2] + m[4][2]
local z = offX * m[1][3] + offY * m[2][3] + offZ * m[3][3] + m[4][3]
return x, y, z -- Return the transformed point
end

-- Get the position of a point 3 units to the left of the element:
x,y,z = getPositionFromElementOffset(element,3,0,0)

-- Get the position of a point 2 units in front of the element:
x,y,z = getPositionFromElementOffset(element,0,2,0)

-- Get the position of a point 1 unit above the element:
x,y,z = getPositionFromElementOffset(element,0,0,1)

</syntaxhighlight>

This example creates some more matrix utility functions
<syntaxhighlight lang="lua">
function getMatrixLeft(m)
return m[1][1], m[1][2], m[1][3]
end
function getMatrixForward(m)
return m[2][1], m[2][2], m[2][3]
end
function getMatrixUp(m)
return m[3][1], m[3][2], m[3][3]
end
function getMatrixPosition(m)
return m[4][1], m[4][2], m[4][3]
end

local mat = getElementMatrix(element) -- Get the matrix
x,y,z = getMatrixLeft(mat) -- Get the matrix left direction
x,y,z = getMatrixForward(mat) -- Get the matrix forward direction
x,y,z = getMatrixUp(mat) -- Get the matrix up direction

</syntaxhighlight>

This example function allows you to get the element matrix of an element that is outside your stream range.
<syntaxhighlight lang="lua">
-- Override normal getElementMatrix with our own version
function getElementMatrix(element)
local rx, ry, rz = getElementRotation(element, "ZXY")
rx, ry, rz = math.rad(rx), math.rad(ry), math.rad(rz)
local matrix = {}
matrix[1] = {}
matrix[1][1] = math.cos(rz)*math.cos(ry) - math.sin(rz)*math.sin(rx)*math.sin(ry)
matrix[1][2] = math.cos(ry)*math.sin(rz) + math.cos(rz)*math.sin(rx)*math.sin(ry)
matrix[1][3] = -math.cos(rx)*math.sin(ry)
matrix[1][4] = 1

matrix[2] = {}
matrix[2][1] = -math.cos(rx)*math.sin(rz)
matrix[2][2] = math.cos(rz)*math.cos(rx)
matrix[2][3] = math.sin(rx)
matrix[2][4] = 1

matrix[3] = {}
matrix[3][1] = math.cos(rz)*math.sin(ry) + math.cos(ry)*math.sin(rz)*math.sin(rx)
matrix[3][2] = math.sin(rz)*math.sin(ry) - math.cos(rz)*math.cos(ry)*math.sin(rx)
matrix[3][3] = math.cos(rx)*math.cos(ry)
matrix[3][4] = 1

matrix[4] = {}
matrix[4][1], matrix[4][2], matrix[4][3] = getElementPosition(element) -- this is kinda useless but is used to have the same structure as getElementMatrix
matrix[4][4] = 1

return matrix
end

local mat = getElementMatrix(element) -- this gives the same result as normal getElementMatrix(element), except that it also works if the element is not streamed in
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04186|Added legacy argument}}

==See Also==
{{Client_element_functions}}

GetElementMatrix

2013-07-10T12:26:03Z

Arezu: /* Example */

{{Client function}}
__NOTOC__
This function gets an element's transform matrix. This contains 16 float values that multiplied to a point will give you the point transformed. It is most useful for matrix calculations such as calculating offsets. For further information, please refer to a tutorial of matrices in computer graphics programming.
{{Note|The matrix returned by this function is [http://bugs.mtasa.com/view.php?id{{=}}6984 not setup correctly for some calculations.] unless the '''legacy''' argument is set to '''false'''}}
{{Tip|''For matrix manipulation which goes beyond the basic examples given on this page, see the [[Lua matrix library]].''}}
==Syntax==
<syntaxhighlight lang="lua">
table getElementMatrix ( element theElement [, bool legacy = true ] )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element which you wish to retrieve the matrix for

===Optional Arguments===
*'''legacy :''' Set to false to return correctly setup matrix. (i.e. Last column in the first 3 rows set to zero.)

===Returns===
Returns a multi-dimensional array containing a 4x4 matrix. Returns false if the element is not streamed in, and not a vehicle or ped.

==Example==
This example creates a utility function that turns an offset into a position that is relative to the specified element.
<syntaxhighlight lang="lua">
function getPositionFromElementOffset(element,offX,offY,offZ)
local m = getElementMatrix ( element ) -- Get the matrix
local x = offX * m[1][1] + offY * m[2][1] + offZ * m[3][1] + m[4][1] -- Apply transform
local y = offX * m[1][2] + offY * m[2][2] + offZ * m[3][2] + m[4][2]
local z = offX * m[1][3] + offY * m[2][3] + offZ * m[3][3] + m[4][3]
return x, y, z -- Return the transformed point
end

-- Get the position of a point 3 units to the left of the element:
x,y,z = getPositionFromElementOffset(element,3,0,0)

-- Get the position of a point 2 units in front of the element:
x,y,z = getPositionFromElementOffset(element,0,2,0)

-- Get the position of a point 1 unit above the element:
x,y,z = getPositionFromElementOffset(element,0,0,1)

</syntaxhighlight>

This example creates some more matrix utility functions
<syntaxhighlight lang="lua">
function getMatrixLeft(m)
return m[1][1], m[1][2], m[1][3]
end
function getMatrixForward(m)
return m[2][1], m[2][2], m[2][3]
end
function getMatrixUp(m)
return m[3][1], m[3][2], m[3][3]
end
function getMatrixPosition(m)
return m[4][1], m[4][2], m[4][3]
end

local mat = getElementMatrix(element) -- Get the matrix
x,y,z = getMatrixLeft(mat) -- Get the matrix left direction
x,y,z = getMatrixForward(mat) -- Get the matrix forward direction
x,y,z = getMatrixUp(mat) -- Get the matrix up direction

</syntaxhighlight>

This example function allows you to get the element matrix of an element that is outside your stream range.
<syntaxhighlight lang="lua">
-- Override normal getElementMatrix with our own version
function getElementMatrix(element)
local rx, ry, rz = getElementRotation(element, "ZXY")
rx, ry, rz = math.rad(rx), math.rad(ry), math.rad(rz)
local matrix = {}
matrix[1] = {}
matrix[1][1] = math.cos(rz)*math.cos(ry) - math.sin(rz)*math.sin(rx)*math.sin(ry)
matrix[1][2] = math.cos(ry)*math.sin(rz) + math.cos(rz)*math.sin(rx)*math.sin(ry)
matrix[1][3] = -math.cos(rx)*math.sin(ry)

matrix[2] = {}
matrix[2][1] = -math.cos(rx)*math.sin(rz)
matrix[2][2] = math.cos(rz)*math.cos(rx)
matrix[2][3] = math.sin(rx)

matrix[3] = {}
matrix[3][1] = math.cos(rz)*math.sin(ry) + math.cos(ry)*math.sin(rz)*math.sin(rx)
matrix[3][2] = math.sin(rz)*math.sin(ry) - math.cos(rz)*math.cos(ry)*math.sin(rx)
matrix[3][3] = math.cos(rx)*math.cos(ry)

matrix[4] = {}
matrix[4][1], matrix[4][2], matrix[4][3] = getElementPosition(element) -- this is kinda useless but is used to have the same structure as getElementMatrix

return matrix
end

local mat = getElementMatrix(element) -- this gives the same result as normal getElementMatrix(element), except that it also works if the element is not streamed in
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04186|Added legacy argument}}

==See Also==
{{Client_element_functions}}

GetElementMatrix

2013-07-10T12:25:11Z

Arezu: /* Example */

{{Client function}}
__NOTOC__
This function gets an element's transform matrix. This contains 16 float values that multiplied to a point will give you the point transformed. It is most useful for matrix calculations such as calculating offsets. For further information, please refer to a tutorial of matrices in computer graphics programming.
{{Note|The matrix returned by this function is [http://bugs.mtasa.com/view.php?id{{=}}6984 not setup correctly for some calculations.] unless the '''legacy''' argument is set to '''false'''}}
{{Tip|''For matrix manipulation which goes beyond the basic examples given on this page, see the [[Lua matrix library]].''}}
==Syntax==
<syntaxhighlight lang="lua">
table getElementMatrix ( element theElement [, bool legacy = true ] )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element which you wish to retrieve the matrix for

===Optional Arguments===
*'''legacy :''' Set to false to return correctly setup matrix. (i.e. Last column in the first 3 rows set to zero.)

===Returns===
Returns a multi-dimensional array containing a 4x4 matrix. Returns false if the element is not streamed in, and not a vehicle or ped.

==Example==
This example creates a utility function that turns an offset into a position that is relative to the specified element.
<syntaxhighlight lang="lua">
function getPositionFromElementOffset(element,offX,offY,offZ)
local m = getElementMatrix ( element ) -- Get the matrix
local x = offX * m[1][1] + offY * m[2][1] + offZ * m[3][1] + m[4][1] -- Apply transform
local y = offX * m[1][2] + offY * m[2][2] + offZ * m[3][2] + m[4][2]
local z = offX * m[1][3] + offY * m[2][3] + offZ * m[3][3] + m[4][3]
return x, y, z -- Return the transformed point
end

-- Get the position of a point 3 units to the left of the element:
x,y,z = getPositionFromElementOffset(element,3,0,0)

-- Get the position of a point 2 units in front of the element:
x,y,z = getPositionFromElementOffset(element,0,2,0)

-- Get the position of a point 1 unit above the element:
x,y,z = getPositionFromElementOffset(element,0,0,1)

</syntaxhighlight>

This example creates some more matrix utility functions
<syntaxhighlight lang="lua">
function getMatrixLeft(m)
return m[1][1], m[1][2], m[1][3]
end
function getMatrixForward(m)
return m[2][1], m[2][2], m[2][3]
end
function getMatrixUp(m)
return m[3][1], m[3][2], m[3][3]
end
function getMatrixPosition(m)
return m[4][1], m[4][2], m[4][3]
end

local mat = getElementMatrix(element) -- Get the matrix
x,y,z = getMatrixLeft(mat) -- Get the matrix left direction
x,y,z = getMatrixForward(mat) -- Get the matrix forward direction
x,y,z = getMatrixUp(mat) -- Get the matrix up direction

</syntaxhighlight>

This example allows you to get the element matrix of an element that is outside your stream range.
<syntaxhighlight lang="lua">
-- Override normal getElementMatrix with our own version
function getElementMatrix(element)
local rx, ry, rz = getElementRotation(element, "ZXY")
rx, ry, rz = math.rad(rx), math.rad(ry), math.rad(rz)
local matrix = {}
matrix[1] = {}
matrix[1][1] = math.cos(rz)*math.cos(ry) - math.sin(rz)*math.sin(rx)*math.sin(ry)
matrix[1][2] = math.cos(ry)*math.sin(rz) + math.cos(rz)*math.sin(rx)*math.sin(ry)
matrix[1][3] = -math.cos(rx)*math.sin(ry)

matrix[2] = {}
matrix[2][1] = -math.cos(rx)*math.sin(rz)
matrix[2][2] = math.cos(rz)*math.cos(rx)
matrix[2][3] = math.sin(rx)

matrix[3] = {}
matrix[3][1] = math.cos(rz)*math.sin(ry) + math.cos(ry)*math.sin(rz)*math.sin(rx)
matrix[3][2] = math.sin(rz)*math.sin(ry) - math.cos(rz)*math.cos(ry)*math.sin(rx)
matrix[3][3] = math.cos(rx)*math.cos(ry)

matrix[4] = {}
matrix[4][1], matrix[4][2], matrix[4][3] = getElementPosition(element) -- this is kinda useless but is used to have the same structure as getElementMatrix

return matrix
end

local mat = getElementMatrix(element) -- this gives the same result as normal getElementMatrix(element), except that it also works if the element is not streamed in
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04186|Added legacy argument}}

==See Also==
{{Client_element_functions}}

GetElementMatrix

2013-05-27T02:51:04Z

Arezu:

{{Client function}}
__NOTOC__
This function gets an element's transform matrix. This contains 16 float values that multiplied to a point will give you the point transformed. It is most useful for matrix calculations such as calculating offsets. For further information, please refer to a tutorial of matrices in computer graphics programming.
{{Note|The matrix returned by this function is [http://bugs.mtasa.com/view.php?id{{=}}6984 not setup correctly for some calculations.] unless the '''legacy''' argument is set to '''false'''}}
{{Tip|''For matrix manipulation which goes beyond the basic examples given on this page, see the [[Lua matrix library]].''}}
==Syntax==
<syntaxhighlight lang="lua">
table getElementMatrix ( element theElement [, bool legacy = true ] )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element which you wish to retrieve the matrix for

===Optional Arguments===
*'''legacy :''' Set to false to return correctly setup matrix. (i.e. Last column in the first 3 rows set to zero.)

===Returns===
Returns a multi-dimensional array containing a 4x4 matrix. Returns false if the element is not streamed in, and not a vehicle or ped.

==Example==
This example creates a utility function that turns an offset into a position that is relative to the specified element.
<syntaxhighlight lang="lua">
function getPositionFromElementOffset(element,offX,offY,offZ)
local m = getElementMatrix ( element ) -- Get the matrix
local x = offX * m[1][1] + offY * m[2][1] + offZ * m[3][1] + m[4][1] -- Apply transform
local y = offX * m[1][2] + offY * m[2][2] + offZ * m[3][2] + m[4][2]
local z = offX * m[1][3] + offY * m[2][3] + offZ * m[3][3] + m[4][3]
return x, y, z -- Return the transformed point
end

-- Get the position of a point 3 units to the left of the element:
x,y,z = getPositionFromElementOffset(element,3,0,0)

-- Get the position of a point 2 units in front of the element:
x,y,z = getPositionFromElementOffset(element,0,2,0)

-- Get the position of a point 1 unit above the element:
x,y,z = getPositionFromElementOffset(element,0,0,1)

</syntaxhighlight>

This example creates some more matrix utility functions
<syntaxhighlight lang="lua">
function getMatrixLeft(m)
return m[1][1], m[1][2], m[1][3]
end
function getMatrixForward(m)
return m[2][1], m[2][2], m[2][3]
end
function getMatrixUp(m)
return m[3][1], m[3][2], m[3][3]
end
function getMatrixPosition(m)
return m[4][1], m[4][2], m[4][3]
end

local mat = getElementMatrix(element) -- Get the matrix
x,y,z = getMatrixLeft(mat) -- Get the matrix left direction
x,y,z = getMatrixForward(mat) -- Get the matrix forward direction
x,y,z = getMatrixUp(mat) -- Get the matrix up direction

</syntaxhighlight>

This example allows you to get the element matrix of an element that is outside your stream range.
<syntaxhighlight lang="lua">
-- Override normal getElementMatrix with our own version
function getElementMatrix(element)
local rx, ry, rz = getElementRotation(element, "ZXY")
local rx, ry, rz = math.rad(rotX), math.rad(rotY), math.rad(rotZ)
local matrix = {}
matrix[1] = {}
matrix[1][1] = math.cos(rz)*math.cos(ry) - math.sin(rz)*math.sin(rx)*math.sin(ry)
matrix[1][2] = math.cos(ry)*math.sin(rz) + math.cos(rz)*math.sin(rx)*math.sin(ry)
matrix[1][3] = -math.cos(rx)*math.sin(ry)

matrix[2] = {}
matrix[2][1] = -math.cos(rx)*math.sin(rz)
matrix[2][2] = math.cos(rz)*math.cos(rx)
matrix[2][3] = math.sin(rx)

matrix[3] = {}
matrix[3][1] = math.cos(rz)*math.sin(ry) + math.cos(ry)*math.sin(rz)*math.sin(rx)
matrix[3][2] = math.sin(rz)*math.sin(ry) - math.cos(rz)*math.cos(ry)*math.sin(rx)
matrix[3][3] = math.cos(rx)*math.cos(ry)

matrix[4] = {}
matrix[4][1], matrix[4][2], matrix[4][3] = getElementPosition(element) -- this is kinda useless but is used to have the same structure as getElementMatrix

return matrix
end

local mat = getElementMatrix(element) -- this gives the same result as normal getElementMatrix(element), except that it also works if the element is not streamed in
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04186|Added legacy argument}}

==See Also==
{{Client_element_functions}}

GetElementMatrix

2013-05-27T02:49:19Z

Arezu:

{{Client function}}
__NOTOC__
This function gets an element's transform matrix. This contains 16 float values that multiplied to a point will give you the point transformed. It is most useful for matrix calculations such as calculating offsets. For further information, please refer to a tutorial of matrices in computer graphics programming.
{{Note|The matrix returned by this function is [http://bugs.mtasa.com/view.php?id{{=}}6984 not setup correctly for some calculations.] unless the '''legacy''' argument is set to '''false'''}}
{{Tip|''For matrix manipulation which goes beyond the basic examples given on this page, see the [[Lua matrix library]].''}}
==Syntax==
<syntaxhighlight lang="lua">
table getElementMatrix ( element theElement [, bool legacy = true ] )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element which you wish to retrieve the matrix for

===Optional Arguments===
*'''legacy :''' Set to false to return correctly setup matrix. (i.e. Last column in the first 3 rows set to zero.)

===Returns===
Returns a multi-dimensional array containing a 4x4 matrix. Returns false if the element is not streamed in, and not a vehicle or ped.

==Example==
This example creates a utility function that turns an offset into a position that is relative to the specified element.
<syntaxhighlight lang="lua">
function getPositionFromElementOffset(element,offX,offY,offZ)
local m = getElementMatrix ( element ) -- Get the matrix
local x = offX * m[1][1] + offY * m[2][1] + offZ * m[3][1] + m[4][1] -- Apply transform
local y = offX * m[1][2] + offY * m[2][2] + offZ * m[3][2] + m[4][2]
local z = offX * m[1][3] + offY * m[2][3] + offZ * m[3][3] + m[4][3]
return x, y, z -- Return the transformed point
end

-- Get the position of a point 3 units to the left of the element:
x,y,z = getPositionFromElementOffset(element,3,0,0)

-- Get the position of a point 2 units in front of the element:
x,y,z = getPositionFromElementOffset(element,0,2,0)

-- Get the position of a point 1 unit above the element:
x,y,z = getPositionFromElementOffset(element,0,0,1)

</syntaxhighlight>

This example creates some more matrix utility functions
<syntaxhighlight lang="lua">
function getMatrixLeft(m)
return m[1][1], m[1][2], m[1][3]
end
function getMatrixForward(m)
return m[2][1], m[2][2], m[2][3]
end
function getMatrixUp(m)
return m[3][1], m[3][2], m[3][3]
end
function getMatrixPosition(m)
return m[4][1], m[4][2], m[4][3]
end

local mat = getElementMatrix(element) -- Get the matrix
x,y,z = getMatrixLeft(mat) -- Get the matrix left direction
x,y,z = getMatrixForward(mat) -- Get the matrix forward direction
x,y,z = getMatrixUp(mat) -- Get the matrix up direction

</syntaxhighlight>

This example allows you to get the element matrix of an element that is outside your stream range.
<syntaxhighlight lang="lua">
function getElementMatrix(element)
local rx, ry, rz = getElementRotation(element, "ZXY")
local rx, ry, rz = math.rad(rotX), math.rad(rotY), math.rad(rotZ)
local matrix = {}
matrix[1] = {}
matrix[1][1] = math.cos(rz)*math.cos(ry) - math.sin(rz)*math.sin(rx)*math.sin(ry)
matrix[1][2] = math.cos(ry)*math.sin(rz) + math.cos(rz)*math.sin(rx)*math.sin(ry)
matrix[1][3] = -math.cos(rx)*math.sin(ry)

matrix[2] = {}
matrix[2][1] = -math.cos(rx)*math.sin(rz)
matrix[2][2] = math.cos(rz)*math.cos(rx)
matrix[2][3] = math.sin(rx)

matrix[3] = {}
matrix[3][1] = math.cos(rz)*math.sin(ry) + math.cos(ry)*math.sin(rz)*math.sin(rx)
matrix[3][2] = math.sin(rz)*math.sin(ry) - math.cos(rz)*math.cos(ry)*math.sin(rx)
matrix[3][3] = math.cos(rx)*math.cos(ry)

matrix[4] = {}
matrix[4][1], matrix[4][2], matrix[4][3] = getElementPosition(element) -- this is kinda useless but is used to have the same structure as getElementMatrix

return matrix
end

local mat = getElementMatrix(element) -- this gives the same result as normal getElementMatrix(element), except that it also works if the element is not streamed in
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04186|Added legacy argument}}

==See Also==
{{Client_element_functions}}

AddCommandHandler

2012-09-11T15:24:02Z

Arezu:

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

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

For users, a command is in the format:

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

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

==Syntax==

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

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

</section>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

AddCommandHandler

2012-09-11T15:23:44Z

Arezu:

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

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

For users, a command is in the format:

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

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

==Syntax==

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

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

</section>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

AddCommandHandler

2012-09-11T15:23:12Z

Arezu:

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

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

For users, a command is in the format:

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

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

==Syntax==

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

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

</section>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

GuiCreateWindow

2012-09-07T08:15:18Z

Arezu: /* Syntax */

__NOTOC__
{{Client function}}
This function is for creating a new GUI window. This provides a base for other gui elements to be created within. However, windows do not have a parent and cannot be created in any GUI elements.

==Syntax==
<syntaxhighlight lang="lua">
element guiCreateWindow ( float x, float y, float width, float height, string titleBarText, bool relative )
</syntaxhighlight>

===Required Arguments===
*'''x:''' A float of the 2D x position of the GUI window on a player's screen. This is affected by the ''relative'' argument.
*'''y:''' A float of the 2D y position of the GUI window on a player's screen. This is affected by the ''relative'' argument.
*'''width:''' A float of the width of the GUI window. This is affected by the ''relative'' argument.
*'''height:''' A float of the height of the GUI window. This is affected by the ''relative'' argument.
*'''titleBarText:''' A string of the text that will be displayed in the title bar of the window.
*'''relative:''' 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 sizes/positions as a fraction of the screen size. If ''false'', then the size and co-ordinates are based on client's resolution, accessible using [[guiGetScreenSize]].

===Returns===
Returns a gui window element if it was created successfully, false otherwise.

==Example==
'''Example 1:''' This example creates a information window and adds two tabs to a "tabPanel" tabpanel, and adds some other gui elements to it.
<syntaxhighlight lang="lua">
local myWindow = guiCreateWindow ( 0, 0, 0.5, 0.4, "Information", true ) -- create a window which has "Information" in the title bar.
local tabPanel = guiCreateTabPanel ( 0, 0.1, 1, 1, true, myWindow ) -- create a tab panel which fills the whole window
local tabMap = guiCreateTab( "Map Information", tabPanel ) -- create a tab named "Map Information" on 'tabPanel'
local tabHelp = guiCreateTab( "Help", tabPanel ) -- create another tab named "Help" on 'tabPanel'

-- adds a label (text) to each tab
guiCreateLabel(0.02, 0.04, 0.94, 0.2, "This is information about the current map", true, tabMap)
guiCreateLabel(0.02, 0.04, 0.94, 0.92, "This is help text.", true, tabHelp)
</syntaxhighlight>

'''Example 2:''' This example creates a weapon selection screen, complete with a window, gridlist and a button. Users can select a shotgun or a machine gun. The window is not movable or sizable.
<syntaxhighlight lang="lua">
--Setup some tables

shotguns = {
"chrome",
"sawn-off",
"combat"
}

machineGun = {
"m4",
"ak-47"
}

function setupWeaponSelection ( theResource )
-- getResourceRootElement(getThisResource()) at the bottom means it will only create the gui on this resource start
-- Create a window for our spawnscreen, with the title "Select your weapons".
spawnScreenMenu = guiCreateWindow ( 0.15, 0.33, 0.7, 0.34, "Select your weapons", true )
-- create an OK button to allow the user to confirm their selections, and attach it to the confirmSelection function
spawnScreenOKButton = guiCreateButton ( 0.4, 0.85, 0.20, 0.15, "OK", true, spawnScreenMenu )
-- ensure the user can't move or resize our spawnscreen.
guiWindowSetMovable ( spawnScreenMenu, false )
guiWindowSetSizable ( spawnScreenMenu, false )
-- create our gridlist, which fills up most of the window.
spawnScreenGridList = guiCreateGridList ( 0, 0.1, 1, 0.9, true, spawnScreenMenu )
guiGridListSetSelectionMode ( spawnScreenGridList, 2 ) -- ensure the selection mode is one per column
-- Since we have 2 sets of weapons, create a column for shotguns and one for machine guns
guiGridListAddColumn ( spawnScreenGridList, "Shotguns", 0.3 )
guiGridListAddColumn ( spawnScreenGridList, "Machine guns", 0.3 )
-- next, we loop through our handguns table to add handgun items to the gridlist
for key,weaponName in pairs(shotguns) do
-- add a new row to our gridlist each time
local row = guiGridListAddRow ( spawnScreenGridList )
-- next, we set that row's text to the weapon name. Column is 1 since the "Shotguns" column was created first.
guiGridListSetItemText ( spawnScreenGridList, row, 1, weaponName, false, false )
end
-- we repeat the process for other weapon list, changing the column number
row = 0
for key,weaponName in pairs(machineGun) do
-- we don't need to create new rows as that was done in the previous loop
-- we just set the row's text to the weapon name. Column is 2 since the "Machine guns" column was created second.
guiGridListSetItemText ( spawnScreenGridList, row, 2, weaponName, false, false )
row = row + 1 -- increase the row number
end
end
addEventHandler ( "onClientResourceStart", getResourceRootElement(getThisResource()), setupWeaponSelection )
</syntaxhighlight>

==See Also==
{{GUI_functions}}

GuiCreateWindow

2012-09-07T08:14:48Z

Arezu: /* Syntax */

__NOTOC__
{{Client function}}
This function is for creating a new GUI window. This provides a base for other gui elements to be created within. However, windows do not have a parent and cannot be created in any GUI elements.

==Syntax==
<syntaxhighlight lang="lua">
gui-window guiCreateWindow ( float x, float y, float width, float height, string titleBarText, bool relative )
</syntaxhighlight>

===Required Arguments===
*'''x:''' A float of the 2D x position of the GUI window on a player's screen. This is affected by the ''relative'' argument.
*'''y:''' A float of the 2D y position of the GUI window on a player's screen. This is affected by the ''relative'' argument.
*'''width:''' A float of the width of the GUI window. This is affected by the ''relative'' argument.
*'''height:''' A float of the height of the GUI window. This is affected by the ''relative'' argument.
*'''titleBarText:''' A string of the text that will be displayed in the title bar of the window.
*'''relative:''' 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 sizes/positions as a fraction of the screen size. If ''false'', then the size and co-ordinates are based on client's resolution, accessible using [[guiGetScreenSize]].

===Returns===
Returns a gui window element if it was created successfully, false otherwise.

==Example==
'''Example 1:''' This example creates a information window and adds two tabs to a "tabPanel" tabpanel, and adds some other gui elements to it.
<syntaxhighlight lang="lua">
local myWindow = guiCreateWindow ( 0, 0, 0.5, 0.4, "Information", true ) -- create a window which has "Information" in the title bar.
local tabPanel = guiCreateTabPanel ( 0, 0.1, 1, 1, true, myWindow ) -- create a tab panel which fills the whole window
local tabMap = guiCreateTab( "Map Information", tabPanel ) -- create a tab named "Map Information" on 'tabPanel'
local tabHelp = guiCreateTab( "Help", tabPanel ) -- create another tab named "Help" on 'tabPanel'

-- adds a label (text) to each tab
guiCreateLabel(0.02, 0.04, 0.94, 0.2, "This is information about the current map", true, tabMap)
guiCreateLabel(0.02, 0.04, 0.94, 0.92, "This is help text.", true, tabHelp)
</syntaxhighlight>

'''Example 2:''' This example creates a weapon selection screen, complete with a window, gridlist and a button. Users can select a shotgun or a machine gun. The window is not movable or sizable.
<syntaxhighlight lang="lua">
--Setup some tables

shotguns = {
"chrome",
"sawn-off",
"combat"
}

machineGun = {
"m4",
"ak-47"
}

function setupWeaponSelection ( theResource )
-- getResourceRootElement(getThisResource()) at the bottom means it will only create the gui on this resource start
-- Create a window for our spawnscreen, with the title "Select your weapons".
spawnScreenMenu = guiCreateWindow ( 0.15, 0.33, 0.7, 0.34, "Select your weapons", true )
-- create an OK button to allow the user to confirm their selections, and attach it to the confirmSelection function
spawnScreenOKButton = guiCreateButton ( 0.4, 0.85, 0.20, 0.15, "OK", true, spawnScreenMenu )
-- ensure the user can't move or resize our spawnscreen.
guiWindowSetMovable ( spawnScreenMenu, false )
guiWindowSetSizable ( spawnScreenMenu, false )
-- create our gridlist, which fills up most of the window.
spawnScreenGridList = guiCreateGridList ( 0, 0.1, 1, 0.9, true, spawnScreenMenu )
guiGridListSetSelectionMode ( spawnScreenGridList, 2 ) -- ensure the selection mode is one per column
-- Since we have 2 sets of weapons, create a column for shotguns and one for machine guns
guiGridListAddColumn ( spawnScreenGridList, "Shotguns", 0.3 )
guiGridListAddColumn ( spawnScreenGridList, "Machine guns", 0.3 )
-- next, we loop through our handguns table to add handgun items to the gridlist
for key,weaponName in pairs(shotguns) do
-- add a new row to our gridlist each time
local row = guiGridListAddRow ( spawnScreenGridList )
-- next, we set that row's text to the weapon name. Column is 1 since the "Shotguns" column was created first.
guiGridListSetItemText ( spawnScreenGridList, row, 1, weaponName, false, false )
end
-- we repeat the process for other weapon list, changing the column number
row = 0
for key,weaponName in pairs(machineGun) do
-- we don't need to create new rows as that was done in the previous loop
-- we just set the row's text to the weapon name. Column is 2 since the "Machine guns" column was created second.
guiGridListSetItemText ( spawnScreenGridList, row, 2, weaponName, false, false )
row = row + 1 -- increase the row number
end
end
addEventHandler ( "onClientResourceStart", getResourceRootElement(getThisResource()), setupWeaponSelection )
</syntaxhighlight>

==See Also==
{{GUI_functions}}

GetElementsByType

2012-09-07T07:56:40Z

Arezu: /* Required Arguments */

{{Server_client_function}}
__NOTOC__
This function is used to retrieve a list of all elements of the specified type. This can be useful, as it disregards ''where'' in the element tree it is. It can be used with either the built in types (listed below) or with any custom type used in a .map file. For example, if there is an element of type "flag" (e.g. <flag />) in the .map file, the using "flag" as the type argument would find it.

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
table getElementsByType ( string theType, [ element startat=getRootElement() ] )
</syntaxhighlight>
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
table getElementsByType ( string theType, [ element startat=getRootElement(), bool streamedIn=false ] )
</syntaxhighlight>
</section>

===Required Arguments===
*'''theType:''' The type of element you want a list of. This is the same as the tag name in the .map file, so this can be used with a custom element type if desired. Built in types are:
**'''"player":''' A player connected to the server
**'''"ped":''' A ped
**'''"water":''' A water polygon
**'''"sound":''' A playing sound
**'''"vehicle":''' A vehicle
**'''"object":''' An object
**'''"pickup":''' A pickup
**'''"marker":''' A marker
**'''"colshape":''' A collision shape
**'''"blip":''' A blip
**'''"radararea":''' A radar area
**'''"team":''' A team
**'''"spawnpoint":''' A spawnpoint
**'''"remoteclient":''' A remote client connected to the server
**'''"console":''' The server Console
**'''"projectile":''' A projectile

==Optional Arguments==
{{OptionalArg}}
*'''startat:''' The [[element]] the search should start at. Children of this element are searched, siblings or parents will not be found. By default, this is the root element which should suit most uses.

<section name="Client" class="client" show="true">
*'''streamedIn:''' If true, function will only return elements that are streamed in.
</section>

===Returns===
Returns a ''table'' containing all the elements of the specified type. Returns an empty ''table'' if there are no elements of the specified type. Returns ''false'' if the string specified is invalid (or not a string).

==Example==
'''Example 1:''' This example retrieves a table of the players in the server, and checks whether or not each one is in a vehicle:
<syntaxhighlight lang="lua">
local players = getElementsByType ( "player" ) -- get a table of all the players in the server
for theKey,thePlayer in ipairs(players) do -- use a generic for loop to step through each player
if ( isPlayerInVehicle ( thePlayer ) ) then -- if the player is in a vehicle, announce it
outputChatBox ( getPlayerName ( thePlayer ) .. " is in a vehicle" )
else -- if the player isn't in a vehicle, announce that he/she is on foot
outputChatBox ( getPlayerName ( thePlayer ) .. " is on foot" )
end
end
</syntaxhighlight>

'''Example 2:''' This example retrieves a table of the teams in the server, and display them in chat:
<syntaxhighlight lang="lua">
local teams = getElementsByType("team")
for i,team in ipairs(teams) do
local teamName = getTeamName(team) -- get the team name
outputChatBox(teamName) -- display the team name in chat
end
</syntaxhighlight>

'''Example 3:''' This shows how you could create a new element to describe a gas station:
<syntaxhighlight lang="lua">
function createGasStations(below)
local gasstations = getElementsByType ( "gasstation", below ) -- get a table of all the gas station elements in the element tree
for theKey,theGasStation in ipairs(gasstations) do
local x = getElementData(theGasStation, "posX") -- get the position of the element
local y = getElementData(theGasStation, "posY")
local z = getElementData(theGasStation, "posZ")
setElementParent(createColSphere(x, y, z, 10), theGasStation) -- create a colshape for the gas station at the gas station's position
addEventHandler("onColShapeHit", theGasStation, giveGas) -- when the player hits
end
end

function mapLoad()
createGasStations(source) -- create gas stations for the map that's just loaded
end
addEventHandler("onResourceStart", getRootElement(), mapLoad)

function giveGas(hittingElement)
local theGasStation = source
if getElementType(hittingElement) == "vehicle" then
local gas_left = getElementData(theGasStation, "amount")
local gas_speed = getElementData(theGasStation, "speed")
if gas_left > 0 then

local gas_to_remove = gas_speed
if gas_left < gas_speed then
gas_to_remove = gas_left

local current_vehicle_gas = getElementData(hittingElement, "gas")
current_vehicle_gas = current_vehicle_gas + gas_to_remove
gas_left = gas_left - gas_to_remove

setElementData(hittingElement, "gas", current_vehicle_gas)
setElementData(theGasStation, "amount", gas_left)
else
outputChatBox("Pump is out of gas!")
end
end
end
</syntaxhighlight>

==See Also==
{{Element_functions}}

CreateWeapon

2012-09-03T02:56:44Z

Arezu:

__NOTOC__
{{Client function}}
Creates a custom weapon that can fire bullets not related to player held weapons.
'''Note:''' All weapon types does not work.

==Syntax==
<syntaxhighlight lang="lua">weapon createWeapon ( string theType, float x, float y, float z )</syntaxhighlight>

===Required Arguments===
* '''theType:''' The weapon type such as M4.
* '''x:''' The x position to create the weapon.
* '''y:''' The y position to create the weapon.
* '''z:''' The z position to create the weapon.

===Returns===
Returns a custom weapon element type and creates a simulated weapon at that position.

==Requirements==
{{Requirements|1.3.0-4555|1.3.0-4555|}}

==See Also==
{{Client weapon creation functions}}
[[ru:createWeapon]]

CreateWeapon

2012-09-03T02:56:23Z

Arezu:

__NOTOC__
{{Client function}}
Creates a custom weapon that can fire bullets not related to player held weapons.
'''Note:''' All weapons does not work.

==Syntax==
<syntaxhighlight lang="lua">weapon createWeapon ( string theType, float x, float y, float z )</syntaxhighlight>

===Required Arguments===
* '''theType:''' The weapon type such as M4.
* '''x:''' The x position to create the weapon.
* '''y:''' The y position to create the weapon.
* '''z:''' The z position to create the weapon.

===Returns===
Returns a custom weapon element type and creates a simulated weapon at that position.

==Requirements==
{{Requirements|1.3.0-4555|1.3.0-4555|}}

==See Also==
{{Client weapon creation functions}}
[[ru:createWeapon]]

CreateWeapon

2012-09-03T02:56:13Z

Arezu: /* Required Arguments */

__NOTOC__
{{Client function}}
Creates a custom weapon that can fire bullets not related to player held weapons.

==Syntax==
<syntaxhighlight lang="lua">weapon createWeapon ( string theType, float x, float y, float z )</syntaxhighlight>

===Required Arguments===
* '''theType:''' The weapon type such as M4.
* '''x:''' The x position to create the weapon.
* '''y:''' The y position to create the weapon.
* '''z:''' The z position to create the weapon.

===Returns===
Returns a custom weapon element type and creates a simulated weapon at that position.

==Requirements==
{{Requirements|1.3.0-4555|1.3.0-4555|}}

==See Also==
{{Client weapon creation functions}}
[[ru:createWeapon]]

CreateWeapon

2012-09-03T02:55:52Z

Arezu: /* Required Arguments */

__NOTOC__
{{Client function}}
Creates a custom weapon that can fire bullets not related to player held weapons.

==Syntax==
<syntaxhighlight lang="lua">weapon createWeapon ( string theType, float x, float y, float z )</syntaxhighlight>

===Required Arguments===
* '''theType:''' The weapon type such as M4. '''Note:''' All weapons does not work.
* '''x:''' The x position to create the weapon.
* '''y:''' The y position to create the weapon.
* '''z:''' The z position to create the weapon.

===Returns===
Returns a custom weapon element type and creates a simulated weapon at that position.

==Requirements==
{{Requirements|1.3.0-4555|1.3.0-4555|}}

==See Also==
{{Client weapon creation functions}}
[[ru:createWeapon]]

GetElementMatrix

2012-08-30T21:49:06Z

Arezu:

{{Client function}}
__NOTOC__
This function gets an element's transform matrix. This contains 16 float values that multiplied to a point will give you the point transformed. It is most useful for matrix calculations such as calculating offsets. For further information, please refer to a tutorial of matrices in computer graphics programming.

Note that the matrix returned by this function is [http://bugs.mtasa.com/view.php?id=6984 not setup correctly for some calculations.]

''For matrix manipulation which goes beyond the basic examples given on this page, see the [[Lua matrix library]].''
==Syntax==
<syntaxhighlight lang="lua">
table getElementMatrix ( element theElement )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element which you wish to retrieve the matrix for

===Returns===
Returns a multi-dimensional array containing a 4x4 matrix. Returns false if the element is not streamed in.

==Example==
This example creates a utility function that turns an offset into a position that is relative to the specified element.
<syntaxhighlight lang="lua">
function getPositionFromElementOffset(element,offX,offY,offZ)
local m = getElementMatrix ( element ) -- Get the matrix
local x = offX * m[1][1] + offY * m[2][1] + offZ * m[3][1] + m[4][1] -- Apply transform
local y = offX * m[1][2] + offY * m[2][2] + offZ * m[3][2] + m[4][2]
local z = offX * m[1][3] + offY * m[2][3] + offZ * m[3][3] + m[4][3]
return x, y, z -- Return the transformed point
end

-- Get the position of a point 3 units to the left of the element:
x,y,z = getPositionFromElementOffset(element,3,0,0)

-- Get the position of a point 2 units in front of the element:
x,y,z = getPositionFromElementOffset(element,0,2,0)

-- Get the position of a point 1 unit above the element:
x,y,z = getPositionFromElementOffset(element,0,0,1)

</syntaxhighlight>

This example creates some more matrix utility functions
<syntaxhighlight lang="lua">
function getMatrixLeft(m)
return m[1][1], m[1][2], m[1][3]
end
function getMatrixForward(m)
return m[2][1], m[2][2], m[2][3]
end
function getMatrixUp(m)
return m[3][1], m[3][2], m[3][3]
end
function getMatrixPosition(m)
return m[4][1], m[4][2], m[4][3]
end

local mat = getElementMatrix(element) -- Get the matrix
x,y,z = getMatrixLeft(mat) -- Get the matrix left direction
x,y,z = getMatrixForward(mat) -- Get the matrix forward direction
x,y,z = getMatrixUp(mat) -- Get the matrix up direction

</syntaxhighlight>

This example allows you to get the element matrix of an element that is outside your stream range.
<syntaxhighlight lang="lua">
function getMatrix(posX, posY, posZ, rotX, rotY, rotZ)
local rx, ry, rz = math.rad(rotX), math.rad(rotY), math.rad(rotZ)
local matrix = {}
matrix[1] = {}
matrix[1][1] = math.cos(rz)*math.cos(ry) - math.sin(rz)*math.sin(rx)*math.sin(ry)
matrix[1][2] = math.cos(ry)*math.sin(rz) + math.cos(rz)*math.sin(rx)*math.sin(ry)
matrix[1][3] = -math.cos(rx)*math.sin(ry)

matrix[2] = {}
matrix[2][1] = -math.cos(rx)*math.sin(rz)
matrix[2][2] = math.cos(rz)*math.cos(rx)
matrix[2][3] = math.sin(rx)

matrix[3] = {}
matrix[3][1] = math.cos(rz)*math.sin(ry) + math.cos(ry)*math.sin(rz)*math.sin(rx)
matrix[3][2] = math.sin(rz)*math.sin(ry) - math.cos(rz)*math.cos(ry)*math.sin(rx)
matrix[3][3] = math.cos(rx)*math.cos(ry)

matrix[4] = {}
matrix[4][1], matrix[4][2], matrix[4][3] = posX, posY, posZ -- this is kinda useless but is used to have the same structure as getElementMatrix

return matrix
end

local posX, posY, posZ = getElementPosition(element)
local rotX, rotY, rotZ = getElementRotation(element)
local mat = getMatrix(posX, posY, posZ, rotX, rotY, rotZ) -- this gives the same result as getElementMatrix(element), but also works if the element is not streamed in
</syntaxhighlight>

==See Also==
{{Client_element_functions}}

GetElementMatrix

2012-08-30T21:42:03Z

Arezu: