Multi Theft Auto: Wiki - User contributions [en]

Template:Useful Functions

2017-08-11T04:53:24Z

El Zorro: /* Utility */

=== ACL functions ===
*[[aclGroupClone]] » This function clone a group to another group with/without ACLs and/or objects.
*[[getPlayerAcls]] » This function returns a table of all ACL groups on a player.
*[[isPlayerInACL]] » This function checks if a player element is in an ACL group.
*[[renameAclGroup]] » This function gives an existing ACL group a new name.

=== Account functions ===
*[[setAccountName]] » This function is used to change an existing account's name.
*[[removeAccountData]] » This function is used to remove data from account .

=== Camera functions ===
*[[smoothMoveCamera]] » This function allows you to create a cinematic camera flight.

=== Cursor functions ===
*[[getCursorMoveOn]] » This function checks in which way the cursor is currently moving.

=== Drawing functions ===
*[[dxDrawAnimWindow]] » This function draws an animated 2D window on the screen.
*[[dxDrawCircle]] » This function draws a number of 2D lines in order to achieve a circle shape on the screen.
*[[dxDrawOctagon3D]] » This function creates a 3D Octagon
*[[dxDrawTriangle]] » This is a function that will create a triangle with dx lines.
*[[dxDrawLinedRectangle]] » This is a function that will create a rectangle outline with dx lines.
*[[dxDrawBorderedRectangle]] » This is a function that will create a bordered rectangle .
*[[dxDrawGifImage]] » This function simulates the effect of a GIF image by using image sprites in 2D.
*[[dxDrawImage3D]] » This function draws a 3D image in GTA world.
*[[dxDrawImageOnElement]] » This function draws an image on any element.
*[[dxDrawLoading]] » This function draws a loading bar on the screen.
*[[dxDrawProgressBar]] » This function simulates a progress bar drawed using DirectDraw.
*[[dxDrawRectangle3D]] » This function draws a 3D rectangle in GTA world.
*[[dxDrawTextOnElement]] » This function draws a text on any element.
*[[dxGetFontSizeFromHeight]] » This function calculates the font size from given height.
*[[dxGetRealFontHeight]] » This function calculates the height of a font.

=== Effects functions ===
*[[attachEffect]] » This function allows you attach an effect to an element.

=== Elements functions ===
*[[getElementSpeed]] » This function returns the specified element's speed in m/s, km/h or mph.
*[[getElementsInDimension]] » This function returns a table of elements that are in the specified dimension.
*[[getElementsWithinMarker]] » This function returns a table of elements that are within a marker's collision shape.
*[[isElementInPhotograph]] » This function checks if an element is in the player's camera picture area.
*[[isElementInRange]] » This function allows you to check if an element's range to a main point is within the maximum range.
*[[isElementMoving]]» This function checks if an element is moving.
*[[isElementWithinAColShape]]» This function checks if an element is within a collision shape element.
*[[multi_check]] » This function checks one element to many, handy and clean.
*[[setElementSpeed]] » This function allows you to set the speed of an element in kph or mph units.

=== Events ===
*[[onVehicleWeaponFire]] » This code implements an event that is triggered when a player in a vehicle fires a vehicle's weapon.

=== Input functions ===
*[[bindControlKeys]] » This function allows you to bind each key bound to a control individually. Doing this bypasses a little MTA restriction.
*[[getBoundControls]] » This function returns a table of control names that are bound to the specified key.
*[[unbindControlKeys]] » This function allows you to unbind each key bound to a control individually. Use this function with [[bindControlKeys]].

=== Data functions ===
*[[Byte2human]] » This function converts an integer (number of bytes) into a human-readable unit.
*[[capitalize]] » This function capitalizes a given string.
*[[convertNumber]] » This function converts and formats large numbers.
*[[convertServerTickToTimeStamp]] » This function converts server ticks to a unix timestamp.
*[[convertTextToSpeech]] » This function converts the provided text to a speech in the provided language which players can hear.
*[[findRotation]] » This function takes two points and returns the direction from point A to point B.
*[[FormatDate]] » This function formats a date on the basis of a format string and returns it.
*[[getRealMonthM]] » This function gives you the real months name
*[[getRealMonthH]] » This function convert english months to arabic months
*[[generateString]] » This function generates a random string with any characters.
*[[generateRandomASCIIString]] » This function returns a random string which uses ASCII characters. 
*[[getAge]] » This function calculates the age of a given birthday.
*[[getDistanceBetweenPointAndSegment2D]] » This function takes point coordinates and line (a segment) starting and ending coordinates. It returns the shortest distance between the point and the line.
*[[getEasterDate]] » This function returns easter date monthday and month for a given year.
*[[getKeyFromValueInTable]] » This function returns the key of the specified value in a table.
*[[getOffsetFromXYZ]] » This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.
*[[getPointFromDistanceRotation]] » This function finds a point based on a starting point, direction and distance.
*[[getRGColorFromPercentage]] »This function returns two integers representing red and green colors according to the specified percentage.
*[[getScreenRotationFromWorldPosition]] » This function returns a screen relative rotation to a world position.
*[[getTimestamp]] » This function returns the UNIX timestamp of a specified date and time.
*[[isLeapYear]] » This function returns a boolean representing if a given year is a leap year.
*[[isValidMail]] » This function checks whether a provided e-mail string is valid.
*[[removeHex]] » This function is used to remove hexadecimal numbers (colors, for example) from strings.
*[[RGBToHex]] » This function returns a string representing the color in hexadecimal.
*[[toHex]] » This function converts a decimal number to a hexadecimal number, as a fix to be used client-side.
*[[secondsToTimeDesc]] » This function converts a plain seconds-integer into a user-friendly time description.
*[[string.count]] » This function counts the amount of occurences of a string in a string.
*[[string.explode]] » This function splits a string at a given separator pattern and returns a table with the pieces.
*[[switch]] » This function allows the value of a variable or expression to control the flow of program execution via a multiway branch.
*[[var dump]] » This function outputs information about one or more variables using outputConsole.
*[[wavelengthToRGBA]] » This function converts a physical wavelength of light to a RGBA color.

=== GUI functions ===
*[[centerWindow]] » This function centers a CEGUI window element responsively in any resolution.
=====Comboboxes=====
*[[guiComboBoxAdjustHeight]] » This function adjusts a CEGUI combobox element to have the correct height.
=====Gridlists=====
*[[getGridListRowIndexFromText]] » This function returns the GridList row index from the specified text.
*[[guiGridListGetSelectedText]] » This function returns a string containing the inner text of a selected gridlist item.
*[[guiGridListAddPlayers]] » This function add all online players to a grid list.
*[[isTextInGridList]] » This function checks if some text exist or not in the GridList.

=== Math functions ===
*[[mathNumber]] » This function is a workaround for the client-side floating-point precision of 24-bits.
*[[math.hypot]] » This function returns the Hypotenuse of the triangle given by sides x and y.
*[[math.percent]] » This function returns a percentage from two number values.
*[[math.round]] » Rounds a number whereas the number of decimals to keep and the method may be set.
*[[reMap]] » Re-maps a number from one range to another.

=== Ped functions ===
*[[getAlivePlayers (Client)|getAlivePlayers]] » This function returns a table of the alive players client-side.
*[[getAlivePlayersInTeam]] » This function returns a table of the alive players in a team.
*[[getOnlineAdmins]] » This function returns a table of all logged-in administrators.
*[[getPedMaxHealth]] » This function returns a pedestrians's maximum health by converting it from their maximum health stat.
*[[getPedMaxOxygenLevel]] » This function returns a ped's maximum oxygen level by converting it from their maximum underwater stamina stat.
*[[getPlayerFromNamePart]] » This function returns a player from partial name.
*[[getPlayerFromSerial]] » This function returns a player from their serial.
*[[getPlayersInGroup]] » This function returns all Players In Group .
*[[getGuestPlayers]] » This function gets a players not login or players Guest .
*[[getDimensionEmpty]] » This function returns id Dimension Empty .
*[[getPlayersByData]] » This function returns a table of players that have the specified data name.
*[[getPlayersInPhotograph]] » This function returns a table of all players in photograph.
*[[isPedAiming]]» This function checks if a pedestrian is aiming their weapon.
*[[isPedDrivingVehicle]] » This function checks if a specified pedestrian is driving a vehicle.
*[[isPlayerInTeam]] » This function checks if a player is in a specified team.
*[[isPedAimingNearPed]] » This is similar to isPedAiming but uses a colshape to be more precise.
*[[getPedEyesPosition]] » This function allows you to get peds eyes position.

=== Resource functions ===
*[[getResourceSettings]] » This function returns a table of the resource settings.
*[[getResourceScripts]] » This function returns a table of the resource scripts.
*[[refreshResource]] » This function refreshes your resource if you changed any of the files

=== Sound functions ===
*[[isSoundFinished]] » This function checks if a sound element has finished.
*[[stopSoundSlowly]] » This function stop your sound element slowly.

=== Table functions ===
*[[rangeToTable]] » This function converts a string range to a table containing number values.
*[[setTableProtected]] » This function protects a table and makes it read-only.
*[[table.copy]] » This function copies a whole table and all the tables in that table.
*[[table.compare]] » This function checks whether two given tables are equal.
*[[table.empty]] » This function checks whether a table is empty.
*[[table.map]] » This function goes through a table and replaces every field with the return of the passed function, where the field's value is passed as first argument and optionally more arguments.
*[[table.merge]] » This function merges two or more tables together.
*[[table.random]] » This function retrieves a random value from a table.
*[[table.size]] » This function returns the absolute size of a table.
*[[table.removeValue]] » This function removes a specified value from a table.

=== Team functions ===
*[[getTeamFromColor]] » This function returns a team element by the specified color.
*[[getTeamWithFewestPlayers]] » This function returns a team element with least players of all the specified teams.

=== Vehicle funcions ===
*[[getRandomVehicle]] » This function gets a random vehicle.
*[[getValidVehicleModels]] » This function returns a table of all valid vehicle models.
*[[getVehicleRespawnPosition]] » This function allows you to get the respawn position of a vehicle.
*[[getVehiclesCountByType]] » This function returns the amount of vehicles by the given type as an integer value.
*[[isVehicleEmpty]] » This function checks whether a vehicle is empty.
*[[getNearestVehicle]] » This function gets the nearest vehicle to the specified player in a specified distance.
*[[isVehicleOccupied]] » This function checks if a specified vehicle is occupied.
*[[isVehicleOnRoof]] » This function checks whether vehicle is on roof.
*[[setVehicleGravityPoint]] » This function sets a vehicle's gravity in the direction of a 3 dimensional coordinate with the strength specified.

=== Weapon functions ===
*[[getJetpackWeaponsEnabled]] » This function returns a table of enabled weapons usable on a jetpack.

=== XML functions ===
*[[getXMLNodes]] » This function returns all children of a XML node.

=== Utility ===
*[[Check]] » This function checks if its arguments are of the right type and calls the error-function if one is not.
*[[coroutine.resume]] » This function applies a fix for hidden coroutine error messages.
*[[callClientFunction]] » This function allows you to call any client-side function from the server's side.
*[[callServerFunction]] » This function allows you to call any server-side function from the client's side.
*[[animate]] » This function allows you to use interpolateBetween without render event and easily used.
*[[getBanFromName]] » This functions returns the ban of the given playername.
*[[getCurrentFPS]] » This function returns the frames per second at which GTA: SA is running.
*[[IfElse]] » This function returns one of two values based on a boolean expression.
*[[isCursorOnElement]] » This function checks whether the cursor is in a particular area.
*[[isMouseInCircle]] » This function checks if a cursor position is in circular area or not.
*[[isMouseInPosition]] » This function allows you to check whether the mouse cursor/pointer is within a rectangular position.
*[[iterElements]] » This function returns ''a time-saving'' iterator for your for-loops.
*[[vector3:compare]] » This method checks whether two vectors match, with optional precision.
*[[thisCommandHandlersExist]] » This method checks a string if this exist as command Handlers

[[Category:Useful Functions]]

GetElementMatrix

2017-08-10T20:35:34Z

El Zorro: /* Example */

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

<section name="Server side: Front to Front" class="server" show="true">
-- create a Ped (0, 0, 5, 0) and put the player to 10 m of distance, front to front
<syntaxhighlight lang="lua">
function startedThisResource (res)
if getThisResource() == res then
local thePed = createPed ( 287, 0, 0, 5, 0)
local matrix = getElementMatrix(thePed)
nx = 0 * matrix[1][1] + 10 * matrix[2][1] + 0 * matrix[3][1] + 1 * matrix[4][1]
ny = 0 * matrix[1][2] + 10 * matrix[2][2] + 0 * matrix[3][2] + 1 * matrix[4][2]
nz = 0 * matrix[1][3] + 10 * matrix[2][3] + 0 * matrix[3][3] + 1 * matrix[4][3]
for a, z in ipairs(getElementsByType("player")) do
setElementPosition (z, nx, ny, nz)
local playerX, playerY, playerZ = getElementPosition(z)
local pedX, pedY, pedZ = getElementPosition(thePed)
local rotZ = findRotation( playerX, playerY, pedX, pedY )
setElementRotation(z, 0, 0, rotZ)
end
end
end
addEventHandler("onResourceStart", getRootElement(), startedThisResource)

function findRotation( x1, y1, x2, y2 )
local t = -math.deg( math.atan2( x2 - x1, y2 - y1 ) )
return t < 0 and t + 360 or t
end
</syntaxhighlight>
</section>

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

==See Also==
{{Client_element_functions}}

GetElementMatrix

2017-08-10T20:34:40Z

El Zorro: /* Example */

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

<section name="Front to Front" class="server" show="true">
-- create a Ped (0, 0, 5, 0) and put the player to 10 m of distance, front to front
<syntaxhighlight lang="lua">
function startedThisResource (res)
if getThisResource() == res then
local thePed = createPed ( 287, 0, 0, 5, 0)
local matrix = getElementMatrix(thePed)
nx = 0 * matrix[1][1] + 10 * matrix[2][1] + 0 * matrix[3][1] + 1 * matrix[4][1]
ny = 0 * matrix[1][2] + 10 * matrix[2][2] + 0 * matrix[3][2] + 1 * matrix[4][2]
nz = 0 * matrix[1][3] + 10 * matrix[2][3] + 0 * matrix[3][3] + 1 * matrix[4][3]
for a, z in ipairs(getElementsByType("player")) do
setElementPosition (z, nx, ny, nz)
local playerX, playerY, playerZ = getElementPosition(z)
local pedX, pedY, pedZ = getElementPosition(thePed)
local rotZ = findRotation( playerX, playerY, pedX, pedY )
setElementRotation(z, 0, 0, rotZ)
end
end
end
addEventHandler("onResourceStart", getRootElement(), startedThisResource)

function findRotation( x1, y1, x2, y2 )
local t = -math.deg( math.atan2( x2 - x1, y2 - y1 ) )
return t < 0 and t + 360 or t
end
</syntaxhighlight>
</section>

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

==See Also==
{{Client_element_functions}}

GetElementMatrix

2017-08-10T20:33:48Z

El Zorro: /* Example */

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

<section name="Testing" class="server" show="true">
-- create a Ped (0, 0, 5, 0) and put the player to 10 m of distance, front to front
<syntaxhighlight lang="lua">
function startedThisResource (res)
if getThisResource() == res then
local thePed = createPed ( 287, 0, 0, 5, 0)
local matrix = getElementMatrix(thePed)
nx = 0 * matrix[1][1] + 10 * matrix[2][1] + 0 * matrix[3][1] + 1 * matrix[4][1]
ny = 0 * matrix[1][2] + 10 * matrix[2][2] + 0 * matrix[3][2] + 1 * matrix[4][2]
nz = 0 * matrix[1][3] + 10 * matrix[2][3] + 0 * matrix[3][3] + 1 * matrix[4][3]
for a, z in ipairs(getElementsByType("player")) do
setElementPosition (z, nx, ny, nz)
local playerX, playerY, playerZ = getElementPosition(z)
local pedX, pedY, pedZ = getElementPosition(thePed)
local rotZ = findRotation( playerX, playerY, pedX, pedY )
setElementRotation(z, 0, 0, rotZ)
end
end
end
addEventHandler("onResourceStart", getRootElement(), startedThisResource)

function findRotation( x1, y1, x2, y2 )
local t = -math.deg( math.atan2( x2 - x1, y2 - y1 ) )
return t < 0 and t + 360 or t
end
</syntaxhighlight>
</section>

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

==See Also==
{{Client_element_functions}}