Multi Theft Auto: Wiki - User contributions [en]

ProcessLineOfSight

2024-06-08T19:18:48Z

Pirulax:

{{Client function}}
__NOTOC__
This function casts a ray between two points in the world, and tells you information about the point that was hit, if any. The two positions '''must''' be within the local player's draw distance as the collision data is not loaded outside this area, and the call will just fail as if the ray didn't hit.

This function is relatively expensive to call, so over use of this in scripts may have a detrimental effect on performance.

This function is useful for checking for collisions and for editor-style scripts. If you wish to find what element is positioned at a particular point on the screen, use this function combined with [[getWorldFromScreenPosition]]. If you wish to just know if something is hit, and don't care about what or where was hit, use [[isLineOfSightClear]].

{{Note|Due to a bug, shootThroughStuff argument does currently check for seeThroughStuff!}}
{{Note|Due to a bug, seeThroughStuff argument has no effect. It mistakenly checks for "shootThrough" surfaces and will always behave as if the argument is set to FALSE (It will never hit).}}

==Syntax==
Return values labelled for ease of reference.
<syntaxhighlight lang="lua">
bool -- hit
float float float -- hitX, hitY, hitZ
element -- hitElement
float float float -- normalX, normalY, normalZ
int -- material
float -- lighting
int -- piece
int -- worldModelID
float float float -- worldModelPositionX,Y,Z
float float float -- worldModelRotationX,Y,Z
int -- worldLODModelID
float float -- uvX, uvY
string -- textureName,
string -- frameName,
float float float -- extraHitX, extraHitY, extraHitZ
processLineOfSight ( float startX, float startY, float startZ,
float endX, float endY, float endZ,
[ bool checkBuildings = true,
bool checkVehicles = true,
bool checkPlayers = true,
bool checkObjects = true,
bool checkDummies = true,
bool seeThroughStuff = false,
bool ignoreSomeObjectsForCamera = false,
bool shootThroughStuff = false,
element ignoredElement = nil,
bool includeWorldModelInformation = false,
bool bIncludeCarTyres = false,
bool bIncludeExtraMateriaInfo = false ] )
</syntaxhighlight>

===Required Arguments===
*'''startX:''' The start ''x'' position
*'''startY:''' The start ''y'' position
*'''startZ:''' The start ''z'' position
*'''endX:''' The end ''x'' position
*'''endY:''' The end ''y'' position
*'''endZ:''' The end ''z'' position

===Optional Arguments===
{{OptionalArg}}
*'''checkBuildings:''' Allow the line of sight to be blocked by GTA's internally placed buildings, i.e. the world map.
*'''checkVehicles:''' Allow the line of sight to be blocked by [[Vehicle|vehicles]].
*'''checkPlayers:''' Allow the line of sight to be blocked by [[Player|players]].
*'''checkObjects:''' Allow the line of sight to be blocked by [[Object|objects]].
*'''checkDummies:''' Allow the line of sight to be blocked by GTA's internal dummies. These are not used in the current MTA version so this argument can be set to ''false''.
*'''seeThroughStuff:''' Allow the line of sight '''pass through''' collision materials that have this flag enabled (By default material IDs 52, 55 and 66 which are some fences that you can shoot throug but still walk on them).
*'''ignoreSomeObjectsForCamera:''' Allow the line of sight to '''pass through''' objects that have (K) property enabled in "object.dat" data file. (i.e. Most dynamic objects like boxes or barrels)
*'''shootThroughStuff:''' Allow the line of sight to '''pass through''' collision materials that have this flag enabled (By default material IDs 28, 29, 31, 32, 33, 74, 75, 76, 77, 78, 79, 96, 97, 98, 99, 100 which are exclusively sand / beach or underwater objects).
*'''ignoredElement:''' Allow the line of sight to '''pass through''' a certain specified element. This is usually set to the object you are tracing from so it does not interfere with the results.
*'''includeWorldModelInformation :''' Include the results of hitting a world model.
*'''bIncludeCarTyres :''' Includes car tyre hits.
{{New feature/item|3.161|1.6.0|22173|
*'''bIncludeExtraMateriaInfo:''' Include the material info like UV coords, textureName, frameName and precision clump hit position.
}}

===Returns===
*'''hit:''' ''true'' if there is a collision, ''false'' otherwise
The other values are only filled if there is a collision, they contain ''nil'' otherwise
*'''hitX, hitY, hitZ:''' collision position
*'''hitElement:''' the MTA element hit if any, ''nil'' otherwise
*'''normalX, normalY, normalZ:''' the normal of the surface hit
*'''material:''' an integer representing the [[Material IDs|GTASA material ID]] of the surface hit when applicable (world, objects)
*'''lighting:''' a float between 0 (fully dark) and 1 (bright) representing the amount of light that the hit building surface will transfer to peds or vehicles that are in contact with it. The value can be affected by the game time of day, usually with a lower (darker) value being returned during the night.
*'''piece:''' an integer representing the part of the element hit if hitElement is a vehicle or a ped/player, ''0'' otherwise.
**For a ped/player, piece represents the body part hit:
{{BodyParts}}
**For vehicles, piece represents the vehicle part hit:
{{VehicleParts}}
*'''worldModelID:''' If includeWorldModelInformation was set to ''true'' and a world model was hit, this will contain the model ID.
*'''worldModelPositionX,Y,Z:''' If worldModelID is set, this will contain the world model position.
*'''worldModelRotationX,Y,Z:''' If worldModelID is set, this will contain the world model rotation.
*'''worldLODModelID:''' If worldModelID is set, this will contain the LOD model ID if applicable.
*'''uvX, uvY:''' If bIncludeExtraMateriaInfo is set, it contains the texture UV positions of the hit triangle of the hit entity.
*'''textureName:''' Same as above, but contains the texture name.
*'''frameName:''' Same as above, but contains the frame name. (This, for example in case of cars this is (but not limited to) a [[Vehicle Components]])
*'''modelHitX, modelHitY, modelHitZ:''' Same as above, but contains the exact position hit on the model itself (It is much more precise than the `hitX, hitY, hitZ` returned above, as those are only processed against the much more simpler collision mesh, while these are obtained from processing the visual mesh itself (the DFF))

==Examples==
This example shows how you can tell what position and element the camera is looking at, up to 50 units away.
<syntaxhighlight lang="lua">
local w, h = guiGetScreenSize ()
local tx, ty, tz = getWorldFromScreenPosition ( w/2, h/2, 50 )
local px, py, pz = getCameraMatrix()
hit, x, y, z, elementHit = processLineOfSight ( px, py, pz, tx, ty, tz )
if hit then
outputChatBox ( "Looking at " .. x .. ", " .. y .. ", " .. z )
if elementHit then
outputChatBox ( "Hit element " .. getElementType(elementHit) )
end
end
</syntaxhighlight>
This example shows how you can get the surface type a vehicle is on. This is useful if you want to do a script to dirt cars over time. Please note that this function doesn't count if the vehicle is streamed in or not, so expect this function to fail or return incorrect values on unloaded vehicles.
<syntaxhighlight lang="lua">
function getSurfaceVehicleIsOn(vehicle)
if isElement(vehicle) and (isVehicleOnGround(vehicle) or isElementInWater(vehicle)) then -- Is an element and is touching any surface?
local cx, cy, cz = getElementPosition(vehicle) -- Get the position of the vehicle
local gz = getGroundPosition(cx, cy, cz) - 0.001 -- Get the Z position of the ground the vehicle is on (-0.001 because of processLineOfSight)
local hit, _, _, _, _, _, _, _, surface = processLineOfSight(cx, cy, cz, cx, cy, gz) -- This will get the material of the thing the car is standing on
if hit then
return surface -- If everything is correct, stop executing this function and return the surface type
end
end
return false -- If something isn't correct, return false
end
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04273|''bIncludeCarTyres'' argument added}}
{{ChangelogItem|1.3.0-9.04273|''worldModelID'' return value fixed}}
{{ChangelogItem|1.3.0-9.04405|''lighting'' return value fixed}}
{{ChangelogItem|1.6.0-9.22173|''bIncludeExtraMateriaInfo '' argument added}}

==See Also==
{{Client world functions}}

ProcessLineOfSight

2024-06-08T19:18:06Z

Pirulax: Fix last edit (Clarify function arguments)

{{Client function}}
__NOTOC__
This function casts a ray between two points in the world, and tells you information about the point that was hit, if any. The two positions '''must''' be within the local player's draw distance as the collision data is not loaded outside this area, and the call will just fail as if the ray didn't hit.

This function is relatively expensive to call, so over use of this in scripts may have a detrimental effect on performance.

This function is useful for checking for collisions and for editor-style scripts. If you wish to find what element is positioned at a particular point on the screen, use this function combined with [[getWorldFromScreenPosition]]. If you wish to just know if something is hit, and don't care about what or where was hit, use [[isLineOfSightClear]].

{{Note|Due to a bug, shootThroughStuff argument does currently check for seeThroughStuff!}}
{{Note|Due to a bug, seeThroughStuff argument has no effect. It mistakenly checks for "shootThrough" surfaces and will always behave as if the argument is set to FALSE (It will never hit).}}

==Syntax==
Return values labelled for ease of reference.
<syntaxhighlight lang="lua">
bool -- hit
float float float -- hitX, hitY, hitZ
element -- hitElement
float float float -- normalX, normalY, normalZ
int -- material
float -- lighting
int -- piece
int -- worldModelID
float float float -- worldModelPositionX,Y,Z
float float float -- worldModelRotationX,Y,Z
int -- worldLODModelID
float float -- uvX, uvY
string -- textureName,
string -- frameName,
float float float -- extraHitX, extraHitY, extraHitZ
processLineOfSight ( float startX, float startY, float startZ,
float endX, float endY, float endZ,
[ bool checkBuildings = true,
bool checkVehicles = true,
bool checkPlayers = true,
bool checkObjects = true,
bool checkDummies = true,
bool seeThroughStuff = false,
bool ignoreSomeObjectsForCamera = false,
bool shootThroughStuff = false,
element ignoredElement = nil,
bool includeWorldModelInformation = false,
bool bIncludeCarTyres = false,
bool bIncludeExtraMateriaInfo = false ] )
</syntaxhighlight>

===Required Arguments===
*'''startX:''' The start ''x'' position
*'''startY:''' The start ''y'' position
*'''startZ:''' The start ''z'' position
*'''endX:''' The end ''x'' position
*'''endY:''' The end ''y'' position
*'''endZ:''' The end ''z'' position

===Optional Arguments===
{{OptionalArg}}
*'''checkBuildings:''' Allow the line of sight to be blocked by GTA's internally placed buildings, i.e. the world map.
*'''checkVehicles:''' Allow the line of sight to be blocked by [[Vehicle|vehicles]].
*'''checkPlayers:''' Allow the line of sight to be blocked by [[Player|players]].
*'''checkObjects:''' Allow the line of sight to be blocked by [[Object|objects]].
*'''checkDummies:''' Allow the line of sight to be blocked by GTA's internal dummies. These are not used in the current MTA version so this argument can be set to ''false''.
*'''seeThroughStuff:''' Allow the line of sight '''pass through''' collision materials that have this flag enabled (By default material IDs 52, 55 and 66 which are some fences that you can shoot throug but still walk on them).
*'''ignoreSomeObjectsForCamera:''' Allow the line of sight to '''pass through''' objects that have (K) property enabled in "object.dat" data file. (i.e. Most dynamic objects like boxes or barrels)
*'''shootThroughStuff:''' Allow the line of sight to '''pass through''' collision materials that have this flag enabled (By default material IDs 28, 29, 31, 32, 33, 74, 75, 76, 77, 78, 79, 96, 97, 98, 99, 100 which are exclusively sand / beach or underwater objects).
*'''ignoredElement:''' Allow the line of sight to '''pass through''' a certain specified element. This is usually set to the object you are tracing from so it does not interfere with the results.
*'''includeWorldModelInformation :''' Include the results of hitting a world model.
*'''bIncludeCarTyres :''' Includes car tyre hits.
{{New feature/item|3.161|1.6.0|22173|
*'''bIncludeExtraMateriaInfo:''' Include the material info like UV coords, textureName, frameName and precision clump hit position.
}}

===Returns===
*'''hit:''' ''true'' if there is a collision, ''false'' otherwise
The other values are only filled if there is a collision, they contain ''nil'' otherwise
*'''hitX, hitY, hitZ:''' collision position
*'''hitElement:''' the MTA element hit if any, ''nil'' otherwise
*'''normalX, normalY, normalZ:''' the normal of the surface hit
*'''material:''' an integer representing the [[Material IDs|GTASA material ID]] of the surface hit when applicable (world, objects)
*'''lighting:''' a float between 0 (fully dark) and 1 (bright) representing the amount of light that the hit building surface will transfer to peds or vehicles that are in contact with it. The value can be affected by the game time of day, usually with a lower (darker) value being returned during the night.
*'''piece:''' an integer representing the part of the element hit if hitElement is a vehicle or a ped/player, ''0'' otherwise.
**For a ped/player, piece represents the body part hit:
{{BodyParts}}
**For vehicles, piece represents the vehicle part hit:
{{VehicleParts}}
*'''worldModelID:''' If includeWorldModelInformation was set to ''true'' and a world model was hit, this will contain the model ID.
*'''worldModelPositionX,Y,Z:''' If worldModelID is set, this will contain the world model position.
*'''worldModelRotationX,Y,Z:''' If worldModelID is set, this will contain the world model rotation.
*'''worldLODModelID:''' If worldModelID is set, this will contain the LOD model ID if applicable.
*'''uvX, uvY:''' If bIncludeExtraMateriaInfo is set, it contains the texture UV positions of the triangle of the hit entity.
*'''textureName:''' Same as above, but contains the texture name.
*'''frameName:''' Same as above, but contains the frame name. (This, for example in case of cars this is (but not limited to) a [[Vehicle Components]])
*'''modelHitX, modelHitY, modelHitZ:''' Same as above, but contains the exact position hit on the model itself (It is much more precise than the `hitX, hitY, hitZ` returned above, as those are only processed against the much more simpler collision mesh, while these are obtained from processing the visual mesh itself (the DFF))

==Examples==
This example shows how you can tell what position and element the camera is looking at, up to 50 units away.
<syntaxhighlight lang="lua">
local w, h = guiGetScreenSize ()
local tx, ty, tz = getWorldFromScreenPosition ( w/2, h/2, 50 )
local px, py, pz = getCameraMatrix()
hit, x, y, z, elementHit = processLineOfSight ( px, py, pz, tx, ty, tz )
if hit then
outputChatBox ( "Looking at " .. x .. ", " .. y .. ", " .. z )
if elementHit then
outputChatBox ( "Hit element " .. getElementType(elementHit) )
end
end
</syntaxhighlight>
This example shows how you can get the surface type a vehicle is on. This is useful if you want to do a script to dirt cars over time. Please note that this function doesn't count if the vehicle is streamed in or not, so expect this function to fail or return incorrect values on unloaded vehicles.
<syntaxhighlight lang="lua">
function getSurfaceVehicleIsOn(vehicle)
if isElement(vehicle) and (isVehicleOnGround(vehicle) or isElementInWater(vehicle)) then -- Is an element and is touching any surface?
local cx, cy, cz = getElementPosition(vehicle) -- Get the position of the vehicle
local gz = getGroundPosition(cx, cy, cz) - 0.001 -- Get the Z position of the ground the vehicle is on (-0.001 because of processLineOfSight)
local hit, _, _, _, _, _, _, _, surface = processLineOfSight(cx, cy, cz, cx, cy, gz) -- This will get the material of the thing the car is standing on
if hit then
return surface -- If everything is correct, stop executing this function and return the surface type
end
end
return false -- If something isn't correct, return false
end
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04273|''bIncludeCarTyres'' argument added}}
{{ChangelogItem|1.3.0-9.04273|''worldModelID'' return value fixed}}
{{ChangelogItem|1.3.0-9.04405|''lighting'' return value fixed}}
{{ChangelogItem|1.6.0-9.22173|''bIncludeExtraMateriaInfo '' argument added}}

==See Also==
{{Client world functions}}

ProcessLineAgainstMesh

2023-09-23T17:38:28Z

Pirulax:

__NOTOC__
{{Client function}}
{{Added feature/item|3.0161|1.6.0|22173|Does a raycast against an element's renderable mesh model directly}}
Does a raycast against an element's renderable mesh model [not the collision model!].
The same functionality is already present in [[processLineOfSight]], but the latter is a little buggy due to the fact that the collision model is always simplified, and not exactly the same as the mesh, which leads to situations where no hit is detected, even though the visible mesh is hittable [or vice versa].
Also, when one is interested in a specific element the overhead is a lot smaller [as we can skip all the collision detection done by the before-mentioned function].

==Syntax==
Return values labelled for ease of reference.
<syntaxhighlight lang="lua">
bool -- hit
float float -- texU, texV
string -- textureName
string -- frameName
float float float -- worldX, worldY, worldZ
processLineAgainstMesh(element toTest,
float startX, float startY, float startZ,
float endX, float endY, float endZ)
</syntaxhighlight>

===Required Arguments===
*'''toProcess:''' The element to process the line against
*'''startX, startY, startZ:''' The start [origin] of the line
*'''endX, endY, endZ:''' The end of the line

===Returns===
*'''hit:''' ''true'' if there is a collision with the given element's mesh, ''false'' otherwise [in which case all other values are nil]
*'''texU, texV:''' the U, V coordinates on the hit geometry's texture
*'''textureName:''' name of the hit geometry's texture
*'''frameName:''' hit frame's name
*'''worldX, worldY, worldZ:''' collision position in world space

==Requirements==
{{Requirements|n/a|1.6.0-9.22173|}}

==See Also==
{{Client world functions}}

ProcessLineAgainstMesh

2023-09-23T17:37:23Z

Pirulax: Add "Added feature/item" header

ProcessLineAgainstMesh

2023-09-23T17:33:37Z

Pirulax: Add "See Also"

{{Client function}}
__NOTOC__
Does a raycast against an element's renderable mesh model [not the collision model!].
The same functionality is already present in [[processLineOfSight]], but the latter is a little buggy due to the fact that the collision model is always simplified, and not exactly the same as the mesh, which leads to situations where no hit is detected, even though the visible mesh is hittable [or vice versa].
Also, when one is interested in a specific element the overhead is a lot smaller [as we can skip all the collision detection done by the before-mentioned function].

==Syntax==
Return values labelled for ease of reference.
<syntaxhighlight lang="lua">
bool -- hit
float float -- texU, texV
string -- textureName
string -- frameName
float float float -- worldX, worldY, worldZ
processLineAgainstMesh(element toTest,
float startX, float startY, float startZ,
float endX, float endY, float endZ)
</syntaxhighlight>

===Required Arguments===
*'''toProcess:''' The element to process the line against
*'''startX, startY, startZ:''' The start [origin] of the line
*'''endX, endY, endZ:''' The end of the line

===Returns===
*'''hit:''' ''true'' if there is a collision with the given element's mesh, ''false'' otherwise [in which case all other values are nil]
*'''texU, texV:''' the U, V coordinates on the hit geometry's texture
*'''textureName:''' name of the hit geometry's texture
*'''frameName:''' hit frame's name
*'''worldX, worldY, worldZ:''' collision position in world space

==See Also==
{{Client world functions}}

ProcessLineAgainstMesh

2023-09-23T17:32:56Z

Pirulax: Create the page. Needs an example!

OnMarkerHit

2023-09-20T20:40:31Z

Pirulax: Add important note regarding weird behavior

__NOTOC__
{{Server event}}
This event is triggered when an element enters a marker created using [[createMarker]].
{{Important Note|The event is not triggered when only the dimension changes of the player. So, if you use the `matchingDimension` when teleporting players into existing markers you should always first set their dimension/interior and only then the position}}

==Parameters==
<syntaxhighlight lang="lua">
element hitElement, bool matchingDimension
</syntaxhighlight>

*'''hitElement''': the [[element]] that hit the [[marker]].
*'''matchingDimension''': a [[boolean]] representing whether the [[element]] is in the same dimension as the [[marker]].

==Source==
The [[event system#Event source|source]] of this event is the [[marker]] that got hit by the element.

==Example==

This example will output a message what type of element has entered a marker.

<syntaxhighlight lang="lua">
local playerMarker = createMarker(0, 0, 2, "cylinder", 5, 10, 244, 23, 200, root)

function handlePlayerMarker(hitElement)
local elementType = getElementType(hitElement)

outputChatBox("Element ("..elementType..") has entered marker.")
end
addEventHandler("onMarkerHit", playerMarker, handlePlayerMarker)
</syntaxhighlight>

==Issues==
{{Issues|
{{Issue|551|If a marker was attached to another element, onMarkerHit won't be triggered}}
{{Issue|519|onMarkerHit not always triggered in interiors}}
{{Issue|923|Server side markers with size < 1.5 don't trigger event}}
}}

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

OnClientMarkerHit

2023-09-20T20:39:42Z

Pirulax:

__NOTOC__
{{Client event}}
This event is triggered when a player enters a marker created using [[createMarker]].

{{Important Note|The event is not triggered when only the dimension changes of the player. So, if you use the `matchingDimension` when teleporting players into existing markers you should always first set their dimension/interior and only then the position}}

==Parameters==
<syntaxhighlight lang="lua">
player hitPlayer, bool matchingDimension
</syntaxhighlight>

*'''hitPlayer:''' the [[player]] that hit the [[marker]].
*'''matchingDimension:''' ''true'' if the [[player]] is in the same [[dimension]] as the hit [[marker]].

==Source==
The [[event system#Event source|source]] of this event is the [[marker]] that got hit by the player.

==Example==
This code will output a message to the chatbox whenever any player walks into any marker.

<syntaxhighlight lang="lua">
function MarkerHit ( hitPlayer, matchingDimension )
outputChatBox ( getPlayerName(hitPlayer) .. " entered a marker" )
end
addEventHandler ( "onClientMarkerHit", getRootElement(), MarkerHit )
</syntaxhighlight>

==See Also==
===Client marker events===
{{Client marker events}}
===Client marker functions===
{{Client_marker_functions}}

OnClientMarkerHit

2023-09-20T20:39:17Z

Pirulax: Add important note regarding weird behaviour

__NOTOC__
{{Client event}}
This event is triggered when a player enters a marker created using [[createMarker]].

{{Important Note|The event is not triggered when only the dimension changes of an element. So, if you use the `matchingDimension` when teleporting players into existing markers you should always first set their dimension/interior and only then the position}}

==Parameters==
<syntaxhighlight lang="lua">
player hitPlayer, bool matchingDimension
</syntaxhighlight>

*'''hitPlayer:''' the [[player]] that hit the [[marker]].
*'''matchingDimension:''' ''true'' if the [[player]] is in the same [[dimension]] as the hit [[marker]].

==Source==
The [[event system#Event source|source]] of this event is the [[marker]] that got hit by the player.

==Example==
This code will output a message to the chatbox whenever any player walks into any marker.

<syntaxhighlight lang="lua">
function MarkerHit ( hitPlayer, matchingDimension )
outputChatBox ( getPlayerName(hitPlayer) .. " entered a marker" )
end
addEventHandler ( "onClientMarkerHit", getRootElement(), MarkerHit )
</syntaxhighlight>

==See Also==
===Client marker events===
{{Client marker events}}
===Client marker functions===
{{Client_marker_functions}}

EngineRequestModel

2023-08-26T18:02:05Z

Pirulax: Add note about having to call engineFreeModel in onClientResourceStop

__NOTOC__
{{Client function}}
{{New feature/item|3.0158|1.5.7|20147|This function is used to assign the next available model ID to a certain element type.}}
{{note|Before release '''1.5.8 r20716''' this must be "ped". After release '''1.5.8 r20716''' this function supports "vehicle" and "object" too.}}
{{note|Vehicle unique features may be unsupported, see [https://github.com/multitheftauto/mtasa-blue/issues/1861 issue 1861] for examples and details}}
{{Important Note|Unlike some other functions, the side-effects of this function aren't reverted on resource stop, so you must manually call [[engineFreeModel]] in [[onClientResourceStop]] (Just like the example below does)}}
==Syntax==
<syntaxhighlight lang="lua">
int engineRequestModel ( string elementType [, int parentID ] )
</syntaxhighlight>
===Required Arguments===
*'''elementType''': "ped", "vehicle" or "object".

===Optional Arguments===
*'''parentID''': The ID of the parent model (by default this is: 1337 - objects, 400 - vehicles, 7 - peds).

===Returns===
{{New feature/item|3.0158|1.5.7|20147| Returns an ''integer'' of the model ID that was available to be assigned to the element type, ''false'' if no free model ID available or invalid element type.}}
Do not rely on the model numbers returned being consistent across multiple clients or multiple runs of resources. There is no guarantee for the order of the numbers or that the same numbers will always correspond to the same element type. Any patterns are coincidental.

==Example==
This example creates a ped and then gives you the opportunity to change its model. If the resource stops, then the IDs allocated will be deallocated. Use ''/cap'' for creating the ped and ''/sap'' to skin the ped. You will need some skins added to a folder and to the meta.xml for ''/sap'' to work:
<syntaxhighlight lang="lua">
local peds = {}
function createAllocatedPed()
local x, y, z = getElementPosition(localPlayer)
local id = engineRequestModel("ped")
peds[id] = createPed(id, x+0.5, y, z+0.5)
outputChatBox("New ped with ID "..id.." created.")
end
addCommandHandler("cap", createAllocatedPed, false, false)

function skinAllocatedPeds()
local txd, dff;
for id,ped in pairs(peds) do
if fileExists("skins/" .. id .. ".txd") and fileExists("skins/" .. id .. ".dff") then
txd = engineLoadTXD("skins/" .. id .. ".txd")
engineImportTXD(txd, id)
dff = engineLoadDFF("skins/" .. id .. ".dff")
engineReplaceModel(dff, id)
outputChatBox("Model ID "..id.." changed correctly.")
else
outputChatBox("Model ID "..id.." couldn't change. REASON: skins/" .. id .. ".txd or skins/" .. id .. ".dff does not exist.")
end
end
end
addCommandHandler("sap", skinAllocatedPeds, false, false)

function onStop()
for id,ped in pairs(peds) do
engineFreeModel(id)
end
end
addEventHandler("onClientResourceStop", resourceRoot, onStop)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.5.7-9.20147|}}

==See Also==
{{Engine functions}}

EngineStreaming

2023-08-25T23:36:45Z

Pirulax:

Static class used for manipulating the GTA:SA streaming engine.

==See more==
{{Engine_functions}}

EngineStreamingGetMemorySize

2023-08-25T23:34:27Z

Pirulax:

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21874|Gets the maximum amount of RAM [in bytes] that can be used for streaming}}
{{Tip|The `showmemstat` command can be used to see this value in real-time [You might have to scroll down using PgDown on your keyboard]}}
==Syntax==
<syntaxhighlight lang="lua">
number engineStreamingGetMemorySize()
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:getMemorySize|memorySize|engineStreamingSetMemorySize}}

===Returns===
The maximum amount of RAM [in bytes] that can be used for streaming. It is always a non-zero positive number.

==Example==
This example adds a command that can be used to change the streaming memory size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("ssms", function(_, sizeMB)
if tonumber(sizeMB) then
outputChatbox("The maximum streaming memory available has been changed from " .. math.floor(engineGetStreamingMemorySize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
engineStreamingSetMemorySize(tonumber(sizeMB) * 1024 * 1024) -- Convert MB to Bytes
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21874|}}

==See Also==
{{Engine functions}}

EngineStreamingSetMemorySize

2023-08-25T23:34:17Z

Pirulax:

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21874|Sets the maximum amount of RAM [in bytes] that can be used for streaming}}
{{Tip|The `showmemstat` command can be used to see this value in real-time [You might have to scroll down using PgDown on your keyboard]}}
{{Tip|To restore to default value use [[engineStreamingRestoreMemorySize]]}}
{{Important Note|'''This function is meant for advanced users only, as it can lead to stability issues'''. Using a very high value might result in more crashes, while using a value too low might lead to frequent pop-in [and due to the way MTA works micro-stutter as well]}}
==Syntax==
<syntaxhighlight lang="lua">
nil engineStreamingSetMemorySize( number sizeBytes )
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:setMemorySize|memorySize|engineStreamingGetMemorySize}}

===Required Arguments===
*'''sizeBytes ''': The maximum amount of RAM [in bytes] that can be used for streaming. Must be a positive non-zero number.

==Example==
This example adds a command that can be used to change the streaming memory size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("ssms", function(_, sizeMB)
if tonumber(sizeMB) then
outputChatbox("The maximum streaming memory available has been changed from " .. math.floor(engineGetStreamingMemorySize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
engineStreamingSetMemorySize(tonumber(sizeMB) * 1024 * 1024) -- Convert MB to Bytes
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21874|}}

==See Also==
{{Engine functions}}

EngineStreamingGetBufferSize

2023-08-25T23:32:47Z

Pirulax:

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21874|Get the streaming buffer size ['''not''' maximum memory size]}}
==Syntax==
<syntaxhighlight lang="lua">
number engineStreamingGetBufferSize()
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:getBufferSize|bufferSize|engineStreamingSetBufferSize}}

===Returns===
The streaming buffer size. It is always a positive non-zero number.

==Example==
This example adds a command that can be used to change the streaming buffer size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("sbs", function(_, sizeMB)
if tonumber(sizeMB) then
if engineStreamingSetBufferSize(tonumber(sizeMB) * 1024 * 1024) then -- Convert MB to Bytes
outputChatbox("The streaming buffer size has been changed from " .. math.floor(engineStreamingGetBufferSize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
else
outputChatbox("Not enough memory!")
end
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21874|}}

==See Also==
{{Engine functions}}

EngineStreamingGetBufferSize

2023-08-25T23:32:30Z

Pirulax: Created page with "__NOTOC__ {{Client function}} {{New feature/item|3.0160|1.6.0|21874|Get the streaming buffer size ['''not''' maximum memory size]}} ==Syntax== <syntaxhighlight lang="lua"> number engineStreamingGetBufferSize() </syntaxhighlight> {{OOP||EngineStreaming:setBufferSize|bufferSize|engineStreamingGetBufferSize}} ===Returns=== The streaming buffer size. It is always a positive non-zero number. ==Example== This example adds a command that can be used to change the streamin..."

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21874|Get the streaming buffer size ['''not''' maximum memory size]}}
==Syntax==
<syntaxhighlight lang="lua">
number engineStreamingGetBufferSize()
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:setBufferSize|bufferSize|engineStreamingGetBufferSize}}

===Returns===
The streaming buffer size. It is always a positive non-zero number.

==Example==
This example adds a command that can be used to change the streaming buffer size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("sbs", function(_, sizeMB)
if tonumber(sizeMB) then
if engineStreamingSetBufferSize(tonumber(sizeMB) * 1024 * 1024) then -- Convert MB to Bytes
outputChatbox("The streaming buffer size has been changed from " .. math.floor(engineStreamingGetBufferSize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
else
outputChatbox("Not enough memory!")
end
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21874|}}

==See Also==
{{Engine functions}}

EngineStreamingSetBufferSize

2023-08-25T23:30:48Z

Pirulax:

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21874|Set the streaming buffer size. The larger it is, the more models can be loaded in one go BUT increases the RAM ['''not''' streaming memory!] usage. Can help with custom IMG loading speed by reducing pop-in.}}
{{Important Note|'''This function is meant for advanced users only, as it can lead to stability issues'''. Using a very high value might result in more crashes, while using a value too low might lead to frequent pop-in!}}
==Syntax==
<syntaxhighlight lang="lua">
bool engineStreamingSetBufferSize( number sizeBytes )
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:setBufferSize|bufferSize|engineStreamingGetBufferSize}}

===Required Arguments===
*'''sizeBytes ''': The streaming buffer size. Must be a positive non-zero number.

===Returns===
True if there was enough memory to allocate the buffer, false otherwise.

==Example==
This example adds a command that can be used to change the streaming buffer size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("sbs", function(_, sizeMB)
if tonumber(sizeMB) then
if engineStreamingSetBufferSize(tonumber(sizeMB) * 1024 * 1024) then -- Convert MB to Bytes
outputChatbox("The streaming buffer size has been changed from " .. math.floor(engineStreamingGetBufferSize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
else
outputChatbox("Not enough memory!")
end
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21874|}}

==See Also==
{{Engine functions}}

EngineStreamingSetBufferSize

2023-08-25T23:30:17Z

Pirulax: Created page with "__NOTOC__ {{Client function}} {{New feature/item|3.0160|1.6.0|21874|Get the streaming buffer size. The larger it is, the more models can be loaded in one go BUT increases the RAM ['''not''' streaming memory!] usage. Can help with custom IMG loading speed by reducing pop-in.}} {{Important Note|'''This function is meant for advanced users only, as it can lead to stability issues'''. Using a very high value might result in more crashes, while using a value too low might le..."

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21874|Get the streaming buffer size. The larger it is, the more models can be loaded in one go BUT increases the RAM ['''not''' streaming memory!] usage. Can help with custom IMG loading speed by reducing pop-in.}}
{{Important Note|'''This function is meant for advanced users only, as it can lead to stability issues'''. Using a very high value might result in more crashes, while using a value too low might lead to frequent pop-in!}}
==Syntax==
<syntaxhighlight lang="lua">
bool engineStreamingSetBufferSize( number sizeBytes )
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:setBufferSize|bufferSize|engineStreamingGetBufferSize}}

===Required Arguments===
*'''sizeBytes ''': The streaming buffer size. Must be a positive non-zero number.

===Returns===
True if there was enough memory to allocate the buffer, false otherwise.

==Example==
This example adds a command that can be used to change the streaming buffer size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("sbs", function(_, sizeMB)
if tonumber(sizeMB) then
if engineStreamingSetBufferSize(tonumber(sizeMB) * 1024 * 1024) then -- Convert MB to Bytes
outputChatbox("The streaming buffer size has been changed from " .. math.floor(engineStreamingGetBufferSize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
else
outputChatbox("Not enough memory!")
end
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21874|}}

==See Also==
{{Engine functions}}

EngineStreamingSetMemorySize

2023-08-25T23:21:20Z

Pirulax: Change build number to the correct value

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21874|Sets the maximum amount of RAM [in bytes] that can be used for streaming}}
{{Tip|To restore to default value use [[engineStreamingRestoreMemorySize]]}}
{{Important Note|'''This function is meant for advanced users only, as it can lead to stability issues'''. Using a very high value might result in more crashes, while using a value too low might lead to frequent pop-in [and due to the way MTA works micro-stutter as well]}}
==Syntax==
<syntaxhighlight lang="lua">
nil engineStreamingSetMemorySize( number sizeBytes )
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:setMemorySize|memorySize|engineStreamingGetMemorySize}}

===Required Arguments===
*'''sizeBytes ''': The maximum amount of RAM [in bytes] that can be used for streaming. Must be a positive non-zero number.

==Example==
This example adds a command that can be used to change the streaming memory size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("ssms", function(_, sizeMB)
if tonumber(sizeMB) then
outputChatbox("The maximum streaming memory available has been changed from " .. math.floor(engineGetStreamingMemorySize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
engineStreamingSetMemorySize(tonumber(sizeMB) * 1024 * 1024) -- Convert MB to Bytes
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21874|}}

==See Also==
{{Engine functions}}

EngineStreamingGetMemorySize

2023-08-25T23:20:39Z

Pirulax: Fix Returns styling

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21874|Gets the maximum amount of RAM [in bytes] that can be used for streaming}}
==Syntax==
<syntaxhighlight lang="lua">
number engineStreamingGetMemorySize()
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:getMemorySize|memorySize|engineStreamingSetMemorySize}}

===Returns===
The maximum amount of RAM [in bytes] that can be used for streaming. It is always a non-zero positive number.

==Example==
This example adds a command that can be used to change the streaming memory size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("ssms", function(_, sizeMB)
if tonumber(sizeMB) then
outputChatbox("The maximum streaming memory available has been changed from " .. math.floor(engineGetStreamingMemorySize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
engineStreamingSetMemorySize(tonumber(sizeMB) * 1024 * 1024) -- Convert MB to Bytes
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21874|}}

==See Also==
{{Engine functions}}

EngineStreamingGetMemorySize

2023-08-25T23:20:04Z

Pirulax: Change build number to the correct value

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21874|Gets the maximum amount of RAM [in bytes] that can be used for streaming}}
==Syntax==
<syntaxhighlight lang="lua">
number engineStreamingGetMemorySize()
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:getMemorySize|memorySize|engineStreamingSetMemorySize}}

==Returns==
The maximum amount of RAM [in bytes] that can be used for streaming. It is always a non-zero positive number.

==Example==
This example adds a command that can be used to change the streaming memory size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("ssms", function(_, sizeMB)
if tonumber(sizeMB) then
outputChatbox("The maximum streaming memory available has been changed from " .. math.floor(engineGetStreamingMemorySize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
engineStreamingSetMemorySize(tonumber(sizeMB) * 1024 * 1024) -- Convert MB to Bytes
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21874|}}

==See Also==
{{Engine functions}}

EngineStreamingRestoreMemorySize

2023-08-25T23:19:01Z

Pirulax: Created page with "__NOTOC__ {{Client function}} {{New feature/item|3.0160|1.6.0|21874|Restores the maximum amount of RAM [in bytes] that can be used for streaming to the default value}} {{Tip|The function to manipulate the memory size is engineStreamingSetMemorySize}} ==Syntax== <syntaxhighlight lang="lua"> nil engineStreamingSetMemorySize() </syntaxhighlight> {{OOP||EngineStreaming:restoreMemorySize||}} ==Example== This example adds a command that can be used to change the stre..."

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21874|Restores the maximum amount of RAM [in bytes] that can be used for streaming to the default value}}
{{Tip|The function to manipulate the memory size is [[engineStreamingSetMemorySize]]}}

==Syntax==
<syntaxhighlight lang="lua">
nil engineStreamingSetMemorySize()
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:restoreMemorySize||}}

==Example==
This example adds a command that can be used to change the streaming memory size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("rsms", function()
local prevMB = math.floor(engineGetStreamingMemorySize() / 1024 / 1024)
engineStreamingRestoreMemorySize()
outputChatbox("The maximum streaming memory available has been restored to the original value of " .. math.floor(engineGetStreamingMemorySize() / 1024 / 1024) .. " MB [Was " .. prevMB .. " MB]")
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21874|}}

==See Also==
{{Engine functions}}

EngineStreamingSetMemorySize

2023-08-25T23:10:35Z

Pirulax:

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21946|Sets the maximum amount of RAM [in bytes] that can be used for streaming}}
{{Tip|To restore to default value use [[engineStreamingRestoreMemorySize]]}}
{{Important Note|'''This function is meant for advanced users only, as it can lead to stability issues'''. Using a very high value might result in more crashes, while using a value too low might lead to frequent pop-in [and due to the way MTA works micro-stutter as well]}}
==Syntax==
<syntaxhighlight lang="lua">
nil engineStreamingSetMemorySize( number sizeBytes )
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:setMemorySize|memorySize|engineStreamingGetMemorySize}}

===Required Arguments===
*'''sizeBytes ''': The maximum amount of RAM [in bytes] that can be used for streaming. Must be a positive non-zero number.

==Example==
This example adds a command that can be used to change the streaming memory size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("ssms", function(_, sizeMB)
if tonumber(sizeMB) then
outputChatbox("The maximum streaming memory available has been changed from " .. math.floor(engineGetStreamingMemorySize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
engineStreamingSetMemorySize(tonumber(sizeMB) * 1024 * 1024) -- Convert MB to Bytes
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21946|}}

==See Also==
{{Engine functions}}

EngineStreamingSetMemorySize

2023-08-25T23:10:07Z

Pirulax:

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21946|Sets the maximum amount of RAM [in bytes] that can be used for streaming}}
{{Tip|To restore to the default value use [[engineStreamingRestoreMemorySize]]}}
{{Important Note|'''This function is meant for advanced users only, as it can lead to stability issues'''. Using a very high value might result in more crashes, while using a value too low might lead to frequent pop-in [and due to the way MTA works micro-stutter as well]}}
==Syntax==
<syntaxhighlight lang="lua">
nil engineStreamingSetMemorySize( number sizeBytes )
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:setMemorySize|memorySize|engineStreamingGetMemorySize}}

===Required Arguments===
*'''sizeBytes ''': The maximum amount of RAM [in bytes] that can be used for streaming. Must be a positive non-zero number.

==Example==
This example adds a command that can be used to change the streaming memory size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("ssms", function(_, sizeMB)
if tonumber(sizeMB) then
outputChatbox("The maximum streaming memory available has been changed from " .. math.floor(engineGetStreamingMemorySize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
engineStreamingSetMemorySize(tonumber(sizeMB) * 1024 * 1024) -- Convert MB to Bytes
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21946|}}

==See Also==
{{Engine functions}}

EngineStreamingSetMemorySize

2023-08-25T23:09:10Z

Pirulax: /* Example */

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21946|Sets the maximum amount of RAM [in bytes] that can be used for streaming}}
{{Tip|To restore to the default value use [[engineStreamingRestoreMemorySize]]}}
{{Important Note|**This function is meant for advanced users only, as it can lead to stability issues**. Using a very high value might result in more crashes, while using a value too low might lead to frequent pop-in [and due to the way MTA works micro-stutter as well]}}
==Syntax==
<syntaxhighlight lang="lua">
nil engineStreamingSetMemorySize( number sizeBytes )
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:setMemorySize|memorySize|engineStreamingGetMemorySize}}

===Required Arguments===
*'''sizeBytes ''': The maximum amount of RAM [in bytes] that can be used for streaming. Must be a positive non-zero number.

==Example==
This example adds a command that can be used to change the streaming memory size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("ssms", function(_, sizeMB)
if tonumber(sizeMB) then
outputChatbox("The maximum streaming memory available has been changed from " .. math.floor(engineGetStreamingMemorySize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
engineStreamingSetMemorySize(tonumber(sizeMB) * 1024 * 1024) -- Convert MB to Bytes
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21946|}}

==See Also==
{{Engine functions}}

EngineStreamingSetMemorySize

2023-08-25T23:08:56Z

Pirulax:

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21946|Sets the maximum amount of RAM [in bytes] that can be used for streaming}}
{{Tip|To restore to the default value use [[engineStreamingRestoreMemorySize]]}}
{{Important Note|**This function is meant for advanced users only, as it can lead to stability issues**. Using a very high value might result in more crashes, while using a value too low might lead to frequent pop-in [and due to the way MTA works micro-stutter as well]}}
==Syntax==
<syntaxhighlight lang="lua">
nil engineStreamingSetMemorySize( number sizeBytes )
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:setMemorySize|memorySize|engineStreamingGetMemorySize}}

===Required Arguments===
*'''sizeBytes ''': The maximum amount of RAM [in bytes] that can be used for streaming. Must be a positive non-zero number.

==Example==
This example sets the memory size to 512 MB.
<syntaxhighlight lang="lua">
addCommandHandler("cap", function(_, sizeMB)
if tonumber(sizeMB) then
outputChatbox("The maximum streaming memory available has been changed from " .. math.floor(engineGetStreamingMemorySize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
engineStreamingSetMemorySize(tonumber(sizeMB) * 1024 * 1024) -- Convert MB to Bytes
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21946|}}

==See Also==
{{Engine functions}}

EngineStreamingGetMemorySize

2023-08-25T23:08:25Z

Pirulax: Created page with "__NOTOC__ {{Client function}} {{New feature/item|3.0160|1.6.0|21946|Gets the maximum amount of RAM [in bytes] that can be used for streaming}} ==Syntax== <syntaxhighlight lang="lua"> number engineStreamingGetMemorySize() </syntaxhighlight> {{OOP||EngineStreaming:getMemorySize|memorySize|engineStreamingSetMemorySize}} ==Returns== The maximum amount of RAM [in bytes] that can be used for streaming. It is always a non-zero positive number. ==Example== This example add..."

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21946|Gets the maximum amount of RAM [in bytes] that can be used for streaming}}
==Syntax==
<syntaxhighlight lang="lua">
number engineStreamingGetMemorySize()
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:getMemorySize|memorySize|engineStreamingSetMemorySize}}

==Returns==
The maximum amount of RAM [in bytes] that can be used for streaming. It is always a non-zero positive number.

==Example==
This example adds a command that can be used to change the streaming memory size, and display the previous value.
<syntaxhighlight lang="lua">
addCommandHandler("ssms", function(_, sizeMB)
if tonumber(sizeMB) then
outputChatbox("The maximum streaming memory available has been changed from " .. math.floor(engineGetStreamingMemorySize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
engineStreamingSetMemorySize(tonumber(sizeMB) * 1024 * 1024) -- Convert MB to Bytes
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21946|}}

==See Also==
{{Engine functions}}

EngineStreamingSetMemorySize

2023-08-25T23:02:32Z

Pirulax: Created page with "__NOTOC__ {{Client function}} {{New feature/item|3.0160|1.6.0|21946|Sets the maximum amount of [in bytes] that can be used for streaming}} {{Tip|To restore to the default value use engineStreamingRestoreMemorySize}} {{Important Note|**This function is meant for advanced users only, as it can lead to stability issues**. Using a very high value might result in more crashes, while using a value too low might lead to frequent pop-in [and due to the way MTA works micro-st..."

__NOTOC__
{{Client function}}
{{New feature/item|3.0160|1.6.0|21946|Sets the maximum amount of [in bytes] that can be used for streaming}}
{{Tip|To restore to the default value use [[engineStreamingRestoreMemorySize]]}}
{{Important Note|**This function is meant for advanced users only, as it can lead to stability issues**. Using a very high value might result in more crashes, while using a value too low might lead to frequent pop-in [and due to the way MTA works micro-stutter as well]}}
==Syntax==
<syntaxhighlight lang="lua">
nil engineStreamingSetMemorySize( number sizeBytes )
</syntaxhighlight>
{{OOP||[[EngineStreaming]]:setMemorySize|memorySize|engineStreamingGetMemorySize}}

===Required Arguments===
*'''sizeBytes ''': The maximum amount of RAM [in bytes] that can be used for streaming. Must be a positive non-zero number.

==Example==
This example sets the memory size to 512 MB.
<syntaxhighlight lang="lua">
addCommandHandler("cap", function(_, sizeMB)
if tonumber(sizeMB) then
outputChatbox("The maximum streaming memory available has been changed from " .. math.floor(engineGetStreamingMemorySize() / 1024 / 1024) .. " MB to " .. sizeMB .. " MB")
engineStreamingSetMemorySize(tonumber(sizeMB) * 1024 * 1024) -- Convert MB to Bytes
else
outputChatbox("Please enter a numeric value!")
end
end, false, false)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.6.0-9.21946|}}

==See Also==
{{Engine functions}}

EngineStreaming

2023-08-25T22:50:59Z

Pirulax: Created page with "Static class used for manipulating the GTA:SA streaming engine."

Static class used for manipulating the GTA:SA streaming engine.

Compiling MTASA

2022-12-04T22:48:04Z

Pirulax: Add mirror 2 (Also, someone please move the hashes into a spoiler)

In order to successfully build Multi Theft Auto from source, it is necessary to perform a number of steps, which we will explain below.

Please read the instructions carefully and do not skip parts of it, if you have no experience.

== Prerequisites ==

Compiling the Multi Theft Auto client is only supported on Windows 10.

Make sure you have the following software and SDKs installed:

=== Visual Studio 2022 ===
[[File:Visual_Studio_Community.PNG|right|150px|link=https://www.visualstudio.com/vs/]]
# '''[https://visualstudio.microsoft.com/vs/ Download Microsoft Visual Studio 2022]''' - make sure you get the Community Edition, that one is free.
# On the installation checklist, [[:File:VsFoundationClasses.png|make sure you tick these 2 items]]:
## ''Desktop development with C++''
## Optional component ''C++ MFC for latest v143 build tools (x86 & x64)''

If you don't enable MFC, you will get the following error: <code>cannot open include file 'afxres.h'</code>.

If you've made a mistake, you can run the ''Visual Studio Installer'' app to modify your current installation. There is no need to uninstall and reinstall.

=== Microsoft DirectX SDK ===
[[File:DirectX_SDK.jpg|right|150px|link=http://web.archive.org/web/20200804044856/https://www.microsoft.com/en-us/download/details.aspx?id=23549]]
'''Download Microsoft DirectX SDK (August 2009) (DXSDK_Aug09.exe):'''
* [https://archive.org/download/dxsdk_aug09/DXSDK_Aug09.exe Mirror 1]
* [https://mega.nz/file/pQJCiAJY#jBcYT6ZP4DMBpnm12BLRto9EQ-RjjpP3BWkSPanpvLI Mirror 2]

{| class="wikitable" style="margin-top: 0px; width: 70%; word-break: break-all;"
|+ File verification
|- style="vertical-align:bottom;"
! colspan="2" | Algorithm and variant
! Hash
|- style="text-align:center;vertical-align:center;"
| rowspan="6" | '''{{nowrap|SHA-3}}''' || ''SHA3-224'' || 8bfcdc03518d7edd34689534fd4d21291469ff2f2eb10437ad648c58
|- style="text-align:center;vertical-align:center;"
| ''SHA3-256'' || 45bf3e08da3b3636ddb4f4a74243430f8d65759c074c0d79756ef810c4701c5a
|- style="text-align:center;vertical-align:center;"
| ''SHA3-384'' || b358e529963d6f5fd7f8bd4b530fb18f6a2e6a442009a54e981b2f9967589ed48150af310f283640d56f9b60d41100c9
|- style="text-align:center;vertical-align:center;"
| ''SHA3-512'' || 43522187053af744250059ef69c0f3083cecd1157fe56daac16b9497ebc6fb5b525875144e42898367c55f757cffd3526f37074d544470578602a5a944a45a75
|- style="text-align:center;vertical-align:center;"
| ''SHAKE128'' || 2a7c81bde9e867cbb5ef00b72ad8de66a3ee64c1d59f16465fa712479b6a84d28a02cc5ed08afa1d51e72011657453dbd4656cc9340d32e18179c39d03982dfc35c8f0c2a5c99e11dc74d0e23ed21b1e55f19c809a5a152bde39a2d46fcd12421f373f2d691ade1b57faf6c2ab7aded5a7d174f1f1c77127c0d6a1523b4775c569c5e1b4efa2da4bf2f708a96707a709e245a7f507382e69a81777919c90e95a091c0b699ce7f517
|- style="text-align:center;vertical-align:center;"
| ''SHAKE256'' || 9c100dac5245a61774f3a2752bf9e941bdcd5654b18035155161c63b20936dfc9bd7334feb9a6fe9a99a65491161083b39ac3bd578e2cf4f90cba3c786e9924fa0611f65a725331b77b63e7c8b552e1637bc77531ba0f2c9cac72115b28e523929ede4e5b246a0755e8d5c4089d94bf16627fb08672cfffa523bba3d976489a0eec60d3c6a96ca2b
|- style="text-align:center;vertical-align:center;"
| rowspan="6" | '''{{nowrap|SHA-2}}''' || ''SHA-224'' || a3a74b89cccfe314b79418d5598aac5e94800221e5d945c74f15c004
|- style="text-align:center;vertical-align:center;"
| ''SHA-256'' || 4ab1de69312f10f6b41310a5218d80c478bbd823bc0f86627318d690b128fb9f
|- style="text-align:center;vertical-align:center;"
| ''SHA-384'' || 254ed29c6ad2cadc6f013d2d51c0ac78a6bbe236a2c94ca99610eba8b2c1200d1a62c445ca9ee51bb09354875d5eca8a
|- style="text-align:center;vertical-align:center;"
| ''SHA-512'' || style="width: 60%;" | 736393c0dfa32221e229890f87eb330174d70dd2a02fa0cace303816d3e7a10a332a44129748de39665d1b339e627d6028c2080268f7afdd5240c447fec8ff0b
|- style="text-align:center;vertical-align:center;"
| ''SHA-512/224'' || 7e23d9ba916000782a17e23abf48e25237f45590cfe767aed9d79f10
|- style="text-align:center;vertical-align:center;"
| ''SHA-512/256'' || 0c833a56046fe7e4213fcb1862c730acf313d1b8f60b51eebf64dc3e79730c1c
|- style="text-align:center;vertical-align:center;"
| colspan="2" | '''MD5''' || 66e5379ecf46b014688779621bcc677c
|- style="text-align:center;vertical-align:center;"
| colspan="2" | '''{{nowrap|SHA-1}}''' || 5b9b969ed7b6cf5534bb7350e44c09b3573b0e71
|- style="text-align:center;vertical-align:center;"
| colspan="2" | '''{{nowrap|CRC32}}''' || e9f5c61d
|}

'''NOTE:''' Restart your computer after installing ''Microsoft DirectX SDK'', because otherwise the environment variable '''DXSDK_DIR''' won't be available yet. After restarting it re-run '''create-projects.bat'''

'''Cant find d3dx9.h'''<br>
Add the '''$(DXSDK_DIR)Include;''' to the VC++ Directories in DirectX9GuiRenderer, GUI and Client Core projects.
You can find the VC++ Directories list by selecting a project, then pressing the shortcut ALT + ENTER (without the +), then under the 'Configuration properties' you can find 'VC++ Directories', and in there you can find the 'Include Directories' field, click on it and add ''';$(DXSDK_DIR)Include;''' at the end of it.
'''Note: You need to do the same thing in Release mode as well'''

'''Cant find d3dx9.lib'''<br>
Do do same as in the error above, but instead of ''';$(DXSDK_DIR)Include;''' you must add ''';$(DXSDK_DIR)Lib/x86;''' to the '''Library directories''' field
'''Note: You need to do the same thing in Release mode as well'''

'''S1023 Error'''<br>
[https://support.microsoft.com/en-us/kb/2728613 "S1023" error when you install the DirectX SDK (June 2010)]<br style="clear:both">

'''Cannot open source file "xxx.h" after upgrading to Visual Studio 2022'''<br>
If you've just upgraded to Visual Studio 2022 and were working on MTA using a previous version, you may receive errors about header files not being found (stdio.h, stddef.h, etc) when building the project.

Make sure you have the latest Windows 10 SDK installed (via the Visual Studio Installer) and restart your PC.

If that doesn't work - close Visual Studio, go into the `Build` folder (where your mtasa-blue is located) and delete the `.vs` folder. Start Visual Studio and everything should be fixed.

=== Git Client ===
[[File:Git_logo.png|left|32px|link=https://git-scm.com/]]

If you would like to contribute to MTA, you should install Git. This will allow you to collaborate with us by creating branches and pushing to your own fork. If you are not comfortable with the command line, we recommend you to download and install [https://desktop.github.com/ GitHub Desktop].

If you only want to compile the source code and are not interested in contributing to MTA, you can download the source directly (see below).

== Getting the latest source code ==

To get the latest code, you will have to download the latest copy of our Git repository.<br>
We recommend cloning the repository in your Git client because you can pull any updates from there easily.

* '''Repository:''' [https://github.com/multitheftauto/mtasa-blue multitheftauto/mtasa-blue]
* '''.zip:''' [https://github.com/multitheftauto/mtasa-blue/archive/master.zip master.zip]
* '''.tar.gz:''' [https://github.com/multitheftauto/mtasa-blue/archive/master.tar.gz master.tar.gz]

== Compiling the code ==
# Execute the script '''win-create-projects.bat'''
# Open the solution file '''MTASA.sln''' in the '''Build''' directory
# If you are asked to upgrade the project, click '''Cancel'''
# Select '''Debug''' - '''Win32''' configuration in Visual Studio, then press Build > Build Solution... (may take some minutes)
# Execute the script '''win-install-data.bat'''

= Running the software =

== Running the client ==

You can start your client in the '''Bin''' directory. You might find there a ''Multi Theft Auto.exe'' and/or ''Multi Theft Auto_d.exe'' executable. The ''_d'' suffix indicates a debug build of the software.<br>
Furthermore, you can also run your client inside the debugger from Visual Studio if you want to investigate a stack trace or set breakpoints in interesting code regions (read more in the section Debugging below).

== Running the dedicated server ==

If you already have run step 5 (''Install resources'') in ''Compiling the code'' to install resources then you can go to ''Starting the server''.

=== Installing the latest resources ===
If you want to run the Multi Theft Auto dedicated server, you will have to install the required resources. These are required because they implement the most basic functionality (e.g. spawning players) in order to play.

Our official resources repository is [https://github.com/multitheftauto/mtasa-resources hosted on GitHub]. You can download the latest resources from there or [http://mirror.mtasa.com/mtasa/resources/ download a zipped version]. Make sure that you have the latest resources package.

=== Starting the server ===
To run the server, open the ''MTA Server.exe'' executable in the '''Bin/server''' directory. The ''_d'' suffix indicates a debug build of the software.<br>
You can also run the debug build ''MTA Server_d.exe'' with the Visual Studio Debugger (as of writing, you can do that by right-clicking on the Server's Launcher project and selecting ''Start a local instance'' in the ''Debugger'' menu), but you can also attach to a running debug build MTA server (see more in the section Debugging below).

== Debugging ==
If you already compiled the code in the '''Debug''' configuration then continue reading, if not, then go up to ''Compiling the code'' and follow the steps for a ''Debug'' build.<br>
You can either launch MTA yourself and attach any debugger you want to use (also applies to the Visual Studio debugger) or you start a local debugging session in Visual Studio.<br>
[[File:Local_Windows_Debugger.PNG]]

=== How to enable breakpoints ===
If you choose to run MTA with Visual Studio then you should also attach the debugger to the executable '''gta_sa.exe''' (press ''CTRL + ALT + P'' in Visual Studio) - otherwise, your
breakpoints will not work for anything besides the MTA Launcher project.<br>
[[File:Attach_to_Process.png|600px]]

=== Extending timeout duration ===
When you use breakpoints during debugging, you may get kicked by the server due to timeout, because the client is frozen. To prevent this, create the '''timeout.longtime''' file in your ''Bin/server/'' directory.
The content of the file is the new timeout duration in seconds, so make sure you type a huge number in there. If you keep the file empty, the timeout will be set to 120 seconds.

=== ReAttach for Visual Studio ===
You can use [https://marketplace.visualstudio.com/items?itemName=ErlandR.ReAttach ReAttach] to re-attach the debugger to the '''gta_sa.exe''' executable whenever you start your local debugger in Visual Studio.<br>
[[File:ReAttach_to_GTASA.PNG]]

= Getting involved =
Please see our [[Coding guidelines]] for information on the coding practice.

= Additional information =
If you need more information, try our [https://github.com/multitheftauto/mtasa-blue/issues bug tracker] or [https://discord.com/invite/mtasa Discord].

= Errors =
== CL38 error. [netc_d.dll not found] ==
Solution: Delete '''Multi Theft Auto_d.exe''' and hit compile again.

== After cloning the repository, it doesn't compile the project ==
Solution: Execute '''win-create-projects.bat''' in main directory.

== CL17 Load field. Please ensure that the latest data files have been installed correctly ==
Solution: Execute '''win-install-data.bat''' in main directory.

== ERROR: Loading network library (net_d.dll) failed! ==
Solution: Execute '''win-install-data.bat''' in main directory.

[[en:Compiling MTASA]]
[[hu:Compiling MTASA]]
[[pt-br:Compilando o MTASA]]
[[ru:Compiling MTASA]]
[[Category: Development]]

DxCreateTexture

2022-02-04T00:00:21Z

Pirulax: Add tip to pre-convert textures using dxtex texconv

{{Client function}}
__NOTOC__
This function creates a [[texture]] element that can be used in the dxDraw functions.
{{Important Note|This function uses significant process RAM, make sure you don't load a lot of textures, because you'll run out of memory and crash MTA on your gaming PC beyond the technical limit of 3.5 GB (weak PC users much earlier). Besides that, don't make the common mistake of causing a memory leak by not destroying textures (causing dxTextures to pile up) when they should no longer display per your script, which causes FPS lag and crashes all over MTA due to so many scripters missing it}}
{{Note|The times shown at the right of the page are only the time needed to add the thing to the draw queue, its not the actual time it takes to draw them.}}
{{Tip|It is recommended to pre-convert textures to whatever format you want to load them as. ARGB should be PNG, all other formats are self explanatory. By doing this you can load textures on the fly without any hickups (Note: There might still be some if the user has a slow HHD). See [https://github.com/microsoft/DirectXTex/releases DirectXTex texconv tool]. }}
[[Image:Screenshot_27.png|frame|A speedtest showing the performance of a texture created with various settings of textureFormat.[Mipmaps = true][textureEdge = "wrap"]]]
[[Image:DxCreateTexture_mipmaps_false.png |frame|A speedtest showing the performance of a texture created with various settings of textureFormat.[Mipmaps = false][textureEdge = "wrap"]]]

It is possible to use dxCreateTexture to load cubemaps and volume textures, but these will only be useable as inputs for a shader. The Microsoft utility [http://nightly.mtasa.com/files/shaders/DxTex.zip DxTex] can view and change cubemaps and volume textures. DxTex can also convert standard textures into DXT1/3/5 compressed .dds which should reduce file sizes.
==Syntax==
<syntaxhighlight lang="lua">
element dxCreateTexture ( string pixels / string filepath [, string textureFormat = "argb", bool mipmaps = true, string textureEdge = "wrap" ] )
</syntaxhighlight>
<syntaxhighlight lang="lua">
element dxCreateTexture ( int width, int height [, string textureFormat = "argb", string textureEdge = "wrap", string textureType = "2d", int depth = 1 ] )
</syntaxhighlight>
{{OOP||[[Texture|DxTexture]]}}
===Required Arguments===
*'''filepath:''' The filepath of the image. (.bmp, .dds, .jpg, .png, and .tga images are supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring.
or
*'''pixels:''' [[Texture_pixels|Pixels]] containing image data. ('plain', 'jpeg' or 'png' pixels can be used here)
or
*'''width:''' Desired width, preferably power of two (16, 32, 64 etc.), maximum is 16384
*'''height :''' Desired height, preferably power of two (16, 32, 64 etc.), maximum is 16384

===Optional Arguments===
{{OptionalArg}}
*'''textureFormat :''' A string representing the desired texture format, which can be one of:
**'''"argb"''' : ARGB uncompressed 32 bit color (default).
**'''"dxt1"''' : DXT1 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT1 .dds). Uses 8 times less video memory than ARGB and '''can speed up drawing'''. Quality not as good as ARGB. '''It supports alpha blending, but it can only be on or off, that is: either 0 or 255.'''
**'''"dxt3"''' : DXT3 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT3 .dds). Uses 4 times less video memory than ARGB and '''can speed up drawing'''. Quality slightly better than DXT1 and supports crisp alpha blending.
**'''"dxt5"''' : DXT5 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT5 .dds). Uses 4 times less video memory than ARGB and '''can speed up drawing'''. Quality slightly better than DXT1 and supports smooth alpha blending.
*'''mipmaps :''' True to create a mip-map chain so the texture looks good when drawn at various sizes.
*'''textureEdge :''' A string representing the desired texture edge handling, which can be one of:
**'''"wrap"''' : Wrap the texture at the edges (default)
**'''"clamp"''' : Clamp the texture at the edges. This may help avoid edge artifacts.
**'''"mirror"''' : Mirror the texture at the edges.
*'''textureType :''' A string representing the desired texture type, which can be one of:
**'''"2d"''' : Standard texture (default)
**'''"3d"''' : Volume texture
**'''"cube"''' : Cube map
*'''depth:''' Desired number of slices when creating a volume texture

==Returns==
Returns a [[texture]] if successful, ''false'' if invalid arguments were passed to the function.

==Example==
<syntaxhighlight lang="lua">
addEventHandler( "onClientRender", root,
function()
if myImage then
dxDrawImage( 100, 350, 300, 350, myImage )
end
end
)

-- Use 'toggle' command to switch image on and off
addCommandHandler( "toggle",
function()
if not myImage then
myImage = dxCreateTexture( "moonpig.png" ) -- Create texture
else
destroyElement( myImage ) -- Destroy texture
myImage = nil
end
end
)
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04021|Added textureType and depth argument}}
{{ChangelogItem|1.3.0-9.04035|Added textureEdge argument}}

==See Also==
{{Drawing_functions}}

[[hu:dxCreateTexture]]

AddEventHandler

2021-04-05T17:27:34Z

Pirulax: Modify my previous important note to point to the code instead of giving a confusing description of the problem

__NOTOC__
{{Server client function}}
{{Important Note|Do '''NOT''' use the same name for your handler function as the event name, as this can lead to confusion if multiple handler functions are used}}
This function will add an [[event]] handler. An event handler is a function that will be called when the event it's attached to is triggered. See [[event system]] for more information on how the event system works.
{{Important Note|See code for this note below}}

Event handlers are functions that are called when a particular event happens. Each event specifies a specific set of variables that are passed to the event handler and can be read by your function. The following global variables are available for use in handler functions:
*'''source''': the element that triggered the event
*'''this''': the element that the event handler is attached to
*'''sourceResource''': the resource that triggered the event
*'''sourceResourceRoot''': the root element of the resource that triggered the event
*'''client''': the client that triggered the event using [[triggerServerEvent]]. Not set if the event was not triggered from a client.
{{New_feature|3|1.0|
*'''eventName''': the name of the event which triggered the handler function.
}}

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

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

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

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

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

==Example==
<section name="Code for important note above" class="Important" show="true">
This code might not work as you expect: The handler added here won't be called until the next time the event is triggered. On the other hand, removing events works as expected.
<syntaxhighlight lang="lua">
addEvent("eventName")
addEventHandler("eventName", root, function()
print("Existing called")
addEventHandler("eventName", root, function()
print("newly added called")
end)
end)
-- first time calling the event
triggerEvent("eventName", root) -- prints "Existing called"
-- second time - now both handlers are called
triggerEvent("eventName", root) -- prints "Existing called", "newly added called"
</syntaxhighlight>
</section>

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

addEventHandler( "onPlayerSpawn", root, onPlayerSpawnHandler ) -- root is a predefined global variable for getRootElement()
</syntaxhighlight>
</section>

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

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

AddEventHandler

2021-03-30T21:21:24Z

Pirulax:

__NOTOC__
{{Server client function}}
{{Important Note|Do '''NOT''' use the same name for your handler function as the event name, as this can lead to confusion if multiple handler functions are used}}
This function will add an [[event]] handler. An event handler is a function that will be called when the event it's attached to is triggered. See [[event system]] for more information on how the event system works.
{{Important Note|Adding handler functions to the same event and element as the handler function isn't supported. (The handler won't be called until the next time the event is triggered). On the other hand, removing events works as expected. See code piece below. }}

Event handlers are functions that are called when a particular event happens. Each event specifies a specific set of variables that are passed to the event handler and can be read by your function. The following global variables are available for use in handler functions:
*'''source''': the element that triggered the event
*'''this''': the element that the event handler is attached to
*'''sourceResource''': the resource that triggered the event
*'''sourceResourceRoot''': the root element of the resource that triggered the event
*'''client''': the client that triggered the event using [[triggerServerEvent]]. Not set if the event was not triggered from a client.
{{New_feature|3|1.0|
*'''eventName''': the name of the event which triggered the handler function.
}}

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

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

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

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

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

==Example==
<section name="Code for important note above" class="Important" show="true">
This code might not work as you expect: The handler added here won't be called until the next time the event is triggered. On the other hand, removing events works as expected.
<syntaxhighlight lang="lua">
addEvent("eventName")
addEventHandler("eventName", root, function()
print("Existing called")
addEventHandler("eventName", root, function()
print("newly added called")
end)
end)
-- first time calling the event
triggerEvent("eventName", root) -- prints "Existing called"
-- second time - now both handlers are called
triggerEvent("eventName", root) -- prints "Existing called", "newly added called"
</syntaxhighlight>
</section>

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

addEventHandler( "onPlayerSpawn", root, onPlayerSpawnHandler ) -- root is a predefined global variable for getRootElement()
</syntaxhighlight>
</section>

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

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

AddEventHandler

2021-03-30T21:20:54Z

Pirulax:

__NOTOC__
{{Server client function}}
{{Important Note|Do '''NOT''' use the same name for your handler function as the event name, as this can lead to confusion if multiple handler functions are used}}
This function will add an [[event]] handler. An event handler is a function that will be called when the event it's attached to is triggered. See [[event system]] for more information on how the event system works.
{{Important Note|Adding handler functions to the same event and element as the handler function isn't supported. (The handler won't be called until the next time the event is triggered). See code piece below.}}

Event handlers are functions that are called when a particular event happens. Each event specifies a specific set of variables that are passed to the event handler and can be read by your function. The following global variables are available for use in handler functions:
*'''source''': the element that triggered the event
*'''this''': the element that the event handler is attached to
*'''sourceResource''': the resource that triggered the event
*'''sourceResourceRoot''': the root element of the resource that triggered the event
*'''client''': the client that triggered the event using [[triggerServerEvent]]. Not set if the event was not triggered from a client.
{{New_feature|3|1.0|
*'''eventName''': the name of the event which triggered the handler function.
}}

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

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

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

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

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

==Example==
<section name="Code for important note above" class="Important" show="true">
This code might not work as you expect: The handler added here won't be called until the next time the event is triggered. On the other hand, removing events works as expected.
<syntaxhighlight lang="lua">
addEvent("eventName")
addEventHandler("eventName", root, function()
print("Existing called")
addEventHandler("eventName", root, function()
print("newly added called")
end)
end)
-- first time calling the event
triggerEvent("eventName", root) -- prints "Existing called"
-- second time - now both handlers are called
triggerEvent("eventName", root) -- prints "Existing called", "newly added called"
</syntaxhighlight>
</section>

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

addEventHandler( "onPlayerSpawn", root, onPlayerSpawnHandler ) -- root is a predefined global variable for getRootElement()
</syntaxhighlight>
</section>

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

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

AddEventHandler

2021-03-30T21:20:02Z

Pirulax: Add important note regarding event triggering behaviour

__NOTOC__
{{Server client function}}
{{Important Note|Do '''NOT''' use the same name for your handler function as the event name, as this can lead to confusion if multiple handler functions are used}}
This function will add an [[event]] handler. An event handler is a function that will be called when the event it's attached to is triggered. See [[event system]] for more information on how the event system works.
{{Important Note|Adding handler functions to the same event and element as the handler function isn't supported. (The handler won't be called until the next time the event is triggered). See code piece below.}}

Event handlers are functions that are called when a particular event happens. Each event specifies a specific set of variables that are passed to the event handler and can be read by your function. The following global variables are available for use in handler functions:
*'''source''': the element that triggered the event
*'''this''': the element that the event handler is attached to
*'''sourceResource''': the resource that triggered the event
*'''sourceResourceRoot''': the root element of the resource that triggered the event
*'''client''': the client that triggered the event using [[triggerServerEvent]]. Not set if the event was not triggered from a client.
{{New_feature|3|1.0|
*'''eventName''': the name of the event which triggered the handler function.
}}

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

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

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

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

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

==Example==
<section name="Code for important note above" class="Important" show="true">
This code might not work as you expect: The handler added here won't be called until the next time the event is triggered.
<syntaxhighlight lang="lua">
addEvent("eventName")
addEventHandler("eventName", root, function()
print("Existing called")
addEventHandler("eventName", root, function()
print("newly added called")
end)
end)
-- first time calling the event
triggerEvent("eventName", root) -- prints "Existing called"
-- second time - now both handlers are called
triggerEvent("eventName", root) -- prints "Existing called", "newly added called"
</syntaxhighlight>
</section>

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

addEventHandler( "onPlayerSpawn", root, onPlayerSpawnHandler ) -- root is a predefined global variable for getRootElement()
</syntaxhighlight>
</section>

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

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

ToJSON

2021-03-24T15:58:57Z

Pirulax: Add important note: keys will be truncated to 255 characters

__NOTOC__
{{Server client function}}
This function converts a '''single''' value (preferably a Lua table) into a [[JSON]] encoded string. You can use this to store the data and then load it again using [[fromJSON]].

{{Important Note|Due to tehnical limitations (partly of json-c) the stringified keys will be truncated to the first 255 characters}}

==Syntax==

<syntaxhighlight lang="lua">
string toJSON ( var value [, bool compact = false ][, string prettyType = "none" ] )
</syntaxhighlight>

===Required Arguments===
*'''var:''' An argument of any type. Arguments that are elements will be stored as element IDs that are liable to change between sessions. As such, do not save elements across sessions as you will get unpredictable results.

===Optional Arguments===
{{OptionalArg}}
{{New feature/item|3.0150|1.5||
*'''compact:''' a [[boolean]] representing whether the string will contain whitespaces. To remove whitespaces from JSON string, use ''true''. String will contain whitespaces per default.
}}
{{New feature/item|3.0154|1.5.3|8046|
*'''prettyType:''' a type [[string]] from below:
** none
** spaces
** tabs
}}

===Returns===
Returns a JSON formatted string.

==Example==
This example shows how you can encode an array. The string json should equal ''"[ { "1": "dogs", "mouse": "food", "cat": "hungry", "birds": 4 } ]" after executed.
<syntaxhighlight lang="lua">
local json = toJSON ( { "dogs", cat = "hungry", mouse = "food", birds = 4 } )
</syntaxhighlight>

==Requirements==
{{Requirements|1.0|1.1.1-9.03316|}}

==See Also==
{{Server_functions}}

[[ru:toJSON]]

AddVehicleUpgrade

2021-03-19T21:24:46Z

Pirulax: Add documentation for "all" upgrade

__NOTOC__
{{Server client function}}
This function adds an upgrade to a [[vehicle]], e.g. nitrous, hydraulics.

==Syntax==
<syntaxhighlight lang="lua">bool addVehicleUpgrade ( vehicle theVehicle, string/int upgrade )</syntaxhighlight>
{{OOP||[[vehicle]]:addUpgrade}}
===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]]'') or "'''all"''' to add all 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}}

SetElementData

2021-03-07T23:06:30Z

Pirulax: Key length is actually maximum 128, not 31 characters

{{Server client function}}
__NOTOC__
This function stores [[element data]] under a certain key, attached to an element. Element data set using this is then synced with all clients and the server. The data can contain server created elements, but you should avoid passing data that is not able to be synced such as xmlnodes, acls, aclgroups etc.

As element data is synced to all clients, it can generate a lot of network traffic and be heavy on performance. Events are much more efficient for sending data from a client to the server only, or from the server to a specific client. <br/>
Usage of element data should be disencouraged where your goal can be achieved with events like above, and [[table|tables]] for storing and retrieving data.

{{Tip|A simple and efficient way to make a variable known to the server and clients is to use setElementData on the [[root]] element.}}
{{Note|See [[Script security]] for tips on preventing cheaters when using events and element data}}
{{Note|For performance reasons, never use setElementData in events that fire often (like [[onClientRender]]) without further optimization or conditions. In fact, using element data in general can take such a toll on performance that not using it unless strictly neccesary (e.g use alternatives such as storing data in tables) is recommended.}}.

{{New items|5.0157|1.5.7-9.20477|A subscription mode has been introduced for [[setElementData]] serverside. When setting data in subscription mode, only clients that are added through [[addElementDataSubscriber]] will receive the data, which is good for performance.
Note this mode only works when setting element data serverside. Setting data clientside still sends the update to all clients if 'synchronize' is set to true.
}}

==Syntax==

<syntaxhighlight lang="lua">
bool setElementData ( element theElement, string key, var value [, bool synchronize = true ] )
</syntaxhighlight>
{{OOP||[[element]]:setData||getElementData}}

===Required Arguments===
*'''theElement:''' The [[element]] you wish to attach the data to.
*'''key:''' The key you wish to store the data under. (Maximum 128 characters.)
*'''value:''' The value you wish to store. See [[element data]] for a list of acceptable datatypes.

===Optional Arguments===
*'''synchronize:''' Determines whether or not the data will be synchronized with the clients(server-side variation) or server(client-side variation)

===Returns===
Returns ''true'' if the data was set succesfully, ''false'' otherwise.

{{New items|5.0157|1.5.7-9.20477|
==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool setElementData ( element theElement, string key, var value [, var syncMode="broadcast"] )
</syntaxhighlight>
{{OOP||[[element]]:setData||getElementData}}

===Required Arguments===
*'''theElement:''' The [[element]] you wish to attach the data to.
*'''key:''' The key you wish to store the data under. (Maximum 31 characters.)
*'''value:''' The value you wish to store. See [[element data]] for a list of acceptable datatypes.

===Optional Arguments===
*'''syncMode:''' Synchronisation mode.
**''"broadcast"'' - Synchronise to all clients (default behavior). You can also parse ''true'' for this option.
**''"local"'' - Don't synchronise. You can also parse ''false'' for this option.
**''"subscribe"'' - Only synchronise to specific clients. See [[addElementDataSubscriber]] and [[removeElementDataSubscriber]].
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool setElementData ( element theElement, string key, var value [, bool synchronize = true ] )
</syntaxhighlight>
{{OOP||[[element]]:setData||getElementData}}

===Required Arguments===
*'''theElement:''' The [[element]] you wish to attach the data to.
*'''key:''' The key you wish to store the data under. (Maximum 31 characters.)
*'''value:''' The value you wish to store. See [[element data]] for a list of acceptable datatypes.

===Optional Arguments===
*'''synchronize:''' Determines whether or not the data will be synchronized with the server.
</section>

===Returns===
Returns ''true'' if the data was set succesfully, ''false'' otherwise.
}}

===Issues===
{{Issues|
{{Issue|7389|[Fixed in 1.3.5-7389] Problem with floating numbers}}
}}

==Example==
<section name="Server" class="server" show="true">
This example allows a player to add a custom tag onto their nickname, and also reverts it back to normal if they wish.
<syntaxhighlight lang="lua">
function addPlayerCustomTag ( thePlayer, command, newTag )
--Let's make sure the newTag param has been entered...
if ( newTag ) then
--Grab their current playername for saving.
local sPlayerNickname = getPlayerName ( thePlayer )
--Create their new nickname with their tag
local sNewPlayerNickname = newTag .. " " .. sPlayerNickname

--Let's first load the element data, see if it's there already
--The reason for this is that if a player were to do /addtag twice,
--the tag would be prepended a second time
local sOldNick = getElementData( thePlayer, "tempdata.originalnick" )
if ( sOldNick == false ) then
--Save their orignal nickname in their element data
setElementData ( thePlayer, "tempdata.originalnick", sPlayerNickname )
end

--Set their new nickname globally
setPlayerName ( thePlayer, sNewPlayerNickname )

--Tell them it's done
outputChatBox ( "Your new nickname has been set, to put it back to its original state you can use /deltag", thePlayer )
else
--The newTag param was not entered, give an error message
outputChatBox ( "/addtag - Incorrect syntax, Correct: /addtag <newtag>", thePlayer )
end
end
addCommandHandler ( "addtag", addPlayerCustomTag )

function removePlayerCustomTag ( thePlayer, command )
--We first need to check that they have already used /addtag, let's do that now
local sOldNick = getElementData( thePlayer, "tempdata.originalnick" )
if ( sOldNick ) then
--Great, they have a tag added, let's reset them

--First we will want to reset the element data back to its default (that being false)
setElementData ( thePlayer, "tempdata.originalnick", false )

--Now set the client name back
setPlayerName( thePlayer, sOldNick )

--Notify them
outputChatBox ( "Your old nickname has been set", thePlayer )
end
end
addCommandHandler ( "deltag", removePlayerCustomTag )
</syntaxhighlight>
</section>
[[tr:setElementData]]

==See Also==
[[pt-br:SetElementData]]
{{Element_functions}}

GetTickCount

2021-02-04T14:04:13Z

Pirulax:

__NOTOC__
{{Server client function}}
This function returns amount of time that your system has been running in milliseconds. By comparing two values of [[getTickCount]], you can determine how much time has passed (in milliseconds) between two events. This could be used to determine how efficient your code is, or to time how long a player takes to complete a task.

{{Server client function}}{{Important Note|The value returned by this function client-side may not be reliable if a client is maliciously modifying their operating system speed.}}

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

===Returns===
Returns an integer containing the number of milliseconds since the system the server is running on started. This has the potential to wrap-around.

==Example==
The below code is a good example on how to implement basic anti-spam protection for a command, for which using getTickCount is better than the regular timer functions.
<syntaxhighlight lang="lua">
local spam = {}

function setSkin(player, cmd, skin)
if spam[player] and getTickCount() - spam[player] < 4000 then
return outputChatBox("You cannot change skin that often!", player, 255, 0, 0)
end

skin = skin and tonumber(skin)

if getElementModel(player) == skin or isPedDead(player) then
return
end

if skin and skin <= 99999 then -- what do we know about dynamic ped ID range?
setElementModel(player, skin)
spam[player] = getTickCount()
else
outputChatBox("Invalid skin ID!", player, 255, 0, 0)
end
end
addCommandHandler("skin", setSkin)

function cleanUp()
if spam[source] then
spam[source] = nil
end
end
addEventHandler("onPlayerQuit", root, cleanUp)
</syntaxhighlight>

This example will start a timer displayed at the top of the screen displayed every frame. You can log any specific moment in time by outputting the currentCount variable.

<syntaxhighlight lang="lua">screenX,screenY = guiGetScreenSize()
function startTheClock ()

if not systemUpTime then
systemUpTime = getTickCount() --Store the system tick count, this will be 0 for us
end

currentCount = getTickCount()

dxDrawRectangle (screenX *.40, screenY * .09, 250, 50, tocolor(0,0,0,150))
dxDrawText (currentCount - systemUpTime, screenX * .48, screenY * .1, screenX, screenY, tocolor(255,255,255), 2)
end
addEventHandler ("onClientRender", root, startTheClock)
</syntaxhighlight>

==See Also==
{{Utility functions}}
[[ru:GetTickCount]]

DxSetShaderValue

2021-02-04T14:00:10Z

Pirulax: /* Example */

{{Client function}}
__NOTOC__
This sets a named parameter for a [[shader]] element

{{Important Note|It's enough to set the texture only once if it's a render target}}

==Syntax==
<syntaxhighlight lang="lua">
bool dxSetShaderValue ( element theShader, string parameterName, mixed value )
</syntaxhighlight>
{{OOP||[[shader]]:setValue}}

===Required Arguments===
*'''theShader:''' The shader element whose parameter is to be changed
*'''parameterName:''' The name of parameter
*'''value:''' The value to set, which can be a [[texture]], a bool, a number or a list of numbers('''max 16 floats(numbers)''')

===Returns===
Returns ''true'' if the shader element's parameter was successfully changed, ''false'' otherwise.

==Example==
<syntaxhighlight lang="lua">
myShader = dxCreateShader( "hello.fx" )
myTexture = dxCreateTexture( "man.png" )
dxSetShaderValue( myShader, "texture0", myTexture ) -- Set a texture
dxSetShaderValue( myShader, "bShowThing", true ) -- Set a bool
dxSetShaderValue( myShader, "speed", 2.4 ) -- Set a float
dxSetShaderValue( myShader, "positionOfCheese", 100, 200, 300 ) -- Set a list of numbers, with max 16 numbers. Btw, this is a float: 3.4. This can be used to fill an array in HLSL.
</syntaxhighlight>

==See Also==
{{Drawing_functions}}

[[hu:dxSetShaderValue]]

GetElementsWithinRange

2020-12-29T01:15:04Z

Pirulax: Correct circle to sphere

{{Server client function}}
__NOTOC__
{{New feature/item|3.0156|1.5.5|13823|This function is used to retrieve a list of all elements of specified type within a range of 3D coordinates.}}
{{Note|
* This function doesn't verify whether elements are in the same dimension and interior, additional checks could be implemented manually if they are needed.
* This function checks if elements are in a box, not in a sphere.
* Z argument isn't in use currently, but make your scripts like it is for future compatibility reasons.
* This function doesn't work with elements which is created by createElement.}}

==Syntax==
<syntaxhighlight lang="lua">
table getElementsWithinRange ( float x, float y, float z, float range [, string elemType = "" ] )
</syntaxhighlight>
{{OOP| |[[Element]].getWithinRange}}
===Required Arguments===
*'''x:''' the x coordinate at which to retrieve elements
*'''y:''' the y coordinate at which to retrieve elements
*'''z:''' the z coordinate at which to retrieve elements
*'''range:''' the range at the coordinates in which to retrieve elements

===Optional Arguments===
*'''elemType:''' The type of element you want a list of. This can be any element type, such as:
**'''"player":''' A player connected to the server
**'''"ped":''' A ped
**'''"vehicle":''' A vehicle
**'''"object":''' An object
**'''"pickup":''' A pickup
**'''"marker":''' A marker

===Returns===
Returns a [[table]] containing all the elements of the specified type within range. Returns an empty [[table]] if there are no elements within range. Returns ''false'' if the arguments are invalid.

==Example==
This example allows admins to destroy all vehicles in close proximity.
<syntaxhighlight lang="lua">
function deleteNearbyVehicles(p)
local acc = getPlayerAccount(p)
if not isGuestAccount(acc) and isObjectInACLGroup("user."..getAccountName(acc), aclGetGroup("Admin")) then
local x, y, z = getElementPosition(p)
local nearbyVehicles = getElementsWithinRange(x, y, z, 300, "vehicle")
for i,v in ipairs(nearbyVehicles) do
if v and isElement(v) then
destroyElement(v)
end
end
end
end
addCommandHandler ("delnearvehs", deleteNearbyVehicles)
</syntaxhighlight>

==Example==
This example retrieves a table of players within range of the 3D coordinates and prints their name to the chat.
<syntaxhighlight lang="lua">
local players = getElementsWithinRange( 0, 0, 3, 20, "player" ) -- get all player elements within 20 units of 0, 0, 3
for _, player in pairs( players ) do -- use a generic for loop to step through each player
outputChatBox( getPlayerName( player ) .. " is within range" ) -- print their name to the chat
end
</syntaxhighlight>

==See Also==
{{Element_functions}}

CreateVehicle

2020-12-04T08:17:07Z

Pirulax: Fix previous edit

__NOTOC__
{{Server client function}}{{Note|Vehicles (and other elements) created client-side are only seen by the client that created them, aren't synced and players cannot enter them. They are essentially for display only.}}
{{Note|Due to how GTA works, creating a lot of vehicles in the same place will cause lag. The more geometries and unique textures has model the bigger the lag is. Even a lot of default vehicles will cause lag if in the same place.}}
This function creates a vehicle at the specified location.

Its worth nothing that the position of the vehicle is the center point of the vehicle, not its base. As such, you need to ensure that the z value (vertical axis) is some height above the ground. You can find the exact height using the client side function [[getElementDistanceFromCentreOfMassToBaseOfModel]], or you can estimate it yourself and just spawn the vehicle so it drops to the ground.

==Syntax==
<syntaxhighlight lang="lua">
vehicle createVehicle ( int model, float x, float y, float z [, float rx, float ry, float rz, string numberplate, bool bDirection, int variant1, int variant2 ] )
</syntaxhighlight>
{{OOP||[[Vehicle]]||}}

===Required Arguments===
* '''model''': The [[Vehicle IDs|vehicle ID]] of the vehicle being created.
* '''x''': A floating point number representing the X coordinate on the map.
* '''y''': A floating point number representing the Y coordinate on the map.
* '''z''': A floating point number representing the Z coordinate on the map.

===Optional Arguments===
{{OptionalArg}}
* '''rx''': A floating point number representing the rotation about the X axis in degrees.
* '''ry''': A floating point number representing the rotation about the Y axis in degrees.
* '''rz''': A floating point number representing the rotation about the Z axis in degrees.
* '''numberplate''': A string that will go on the number plate of the vehicle (max 8 characters).
* '''bDirection''' ''(serverside only)'': Placeholder [[boolean]] which provides backward compatibility with some scripts. It never had any effect, but it is read by the code. It is recommended to ignore this argument, passing ''false'' or the ''variant1'' argument in its place.
{{New feature/item|3.0120|1.2||
* '''variant1''': An integer for the first vehicle variant. See [[vehicle variants]].
* '''variant2''': An integer for the second vehicle variant. See [[vehicle variants]].
}}

===Returns===
Returns the [[vehicle]] element that was created. Returns ''false'' if the arguments are incorrect, or if the vehicle limit of 65535 is exceeded.

==Using trains==
Trains are created using the createVehicle function. They are placed at the nearest point of the GTASA train pathing (they usually are railroad tracks) from their spawning point.

==Example==

<section name="Example 1: Server" class="server" show="true">
This example creates a 'vehicle spawner' marker that gives the player a vehicle as soon they step into it.
<syntaxhighlight lang="lua">
local vehMark = createMarker(-2426.34106, -639.12714, 132.93631,"cylinder")

function vehicleSpawner(hitElement,matchingDimension)
if getElementType(hitElement) == "player" then
if getPedOccupiedVehicle(hitElement) == false then
local x,y,z = getElementPosition(hitElement)
local veh = createVehicle(551, x,y,z)
warpPedIntoVehicle(hitElement,veh)
end
end
end
addEventHandler("onMarkerHit",vehMark,vehicleSpawner)
</syntaxhighlight>
</section>

<section name="Example 2: Server" class="server" show="true">
This example creates a vehicle five units to the right of a player when they type ''createvehicle'' and its name in the console:
<syntaxhighlight lang="lua">
local distance = 5 --units

-- define our handler (we'll take a variable number of parameters where the name goes, because there are vehicle names with more than one word)
function consoleCreateVehicle ( sourcePlayer, commandName, ... )
-- if a player triggered it, not the admin,
if ( sourcePlayer ) then
-- calculate the position of the vehicle based on the player's position and rotation:
local x, y, z = getElementPosition ( sourcePlayer ) -- get the player's position
local rotZ = getElementRotation ( sourcePlayer ) -- get the player's rotation around the Z axis in degrees
x = x + ( ( math.cos ( math.rad ( rotZ ) ) ) * distance ) -- calculate the X position of the vehicle
y = y + ( ( math.sin ( math.rad ( rotZ ) ) ) * distance ) -- calculate the Y position of the vehicle

-- get the complete vehicle name by joining all passed parameters using Lua function table.concat
local vehicleName = table.concat({...}, " ")
-- get the vehicle's model ID from the name
local vehicleID = getVehicleModelFromName ( vehicleName )
-- if vehicle ID is valid,
if vehicleID then
-- create the vehicle using the information gathered above:
local newVehicle = createVehicle ( vehicleID, x, y, z, 0, 0, rotZ )
-- if vehicle creation failed, give the player a message
if not newVehicle then
outputConsole ( "Failed to create vehicle.", sourcePlayer )
end
end
end
end

-- Attach the 'consoleCreateVehicle' function to the "createvehicle" command
addCommandHandler ( "createvehicle", consoleCreateVehicle )
</syntaxhighlight>
</section>

<section name="Example 3: Server" class="server" show="false">
This script spawns a Rhino on top of one lucky individual.
<syntaxhighlight lang="lua">
function scriptCreateTank ( player, command )
local luckyBugger = getRandomPlayer() -- get a random player
local x, y, z = getElementPosition ( luckyBugger ) -- retrive the player's position
createVehicle ( 432, x, y, z + 10 ) -- create the tank 10 units above them
outputChatBox ( "You got Tank'd!", luckyBugger )
end
--Attach the 'scriptCreateTank' function to the "tank" command
addCommandHandler ( "tank", scriptCreateTank )
</syntaxhighlight>
</section>

<section name="Example 4: Server" class="server" show="false">
This example adds a ''/spveh'' command to spawn a car model in the provided coordinates. If any car created by this command gets blown up, it will respawn where it was created.
<syntaxhighlight lang="lua">
-- Do not allow the following IDs to be spawned
local forbiddenCars = { [435] = true, [441] = true, [449] = true, [450] = true, [464] = true, [465] = true, [501] = true,
[537] = true, [538] = true, [564] = true, [569] = true, [570] = true, [584] = true, [590] = true,
[591] = true, [594] = true, [606] = true, [607] = true, [608] = true, [610] = true, [611] = true }

local cmdVehRoot = createElement("commandVehicles") -- Dummy element containing the cars that this command has created
addCommandHandler("spveh",
function(player, cmd, modelID, x, y, z, platetext)
-- Check whether arguments are correct
local modelID, x, y, z = tonumber(modelID), tonumber(x), tonumber(y), tonumber(z)
if modelID and x and y and z then
-- Do not continue if we shouldn't
if forbiddenCars[modelID] then
outputChatBox("The car model you provided is not allowed.", player, 255, 0, 0)
return
end
local platetext = type(platetext) == "string" and platetext or "PRIVATE"
-- Create the actual vehicle and set it as a children of our dummy element
setElementParent(createVehicle(modelID, x, y, z, 0, 0, 0, platetext), cmdVehRoot)
-- Inform the player about what we did
outputChatBox("You have created a " .. getVehicleNameFromModel(modelID) .. " (model ID: " .. modelID .. ") at " .. table.concat({ x, y, z }, ", ") .. " with numberplate " .. platetext .. " successfully.", player, 0, 255, 0)
else
outputChatBox("Syntax: /" .. cmd .. " (modelID) (x) (y) (z) [numberplate]", player, 255, 255, 255)
end
end
)

-- If a vehicle that has been created using the command blows up, respawn it where it was created
addEventHandler("onVehicleExplode", cmdVehRoot,
function()
respawnVehicle(source)
end
)
</syntaxhighlight>
</section>

<section name="Example 5: Client" class="client" show="true">
This script spawns a Rhino on top of the local player.
<syntaxhighlight lang="lua">
function scriptCreateTank ( commandName )
local x, y, z = getElementPosition ( localPlayer ) -- retrive the player's position
createVehicle ( 432, x, y, z + 10 ) -- create the tank 10 units above them
outputChatBox ( "You got Tank'd!", 255, 0, 0)
end
--Attach the 'scriptCreateTank' function to the "tank" command
addCommandHandler ( "tank", scriptCreateTank )
</syntaxhighlight>
</section>

{{New items|3.0132|1.4|
This is an example of how this function is executed in an OOP environment.
<section name="OOP server" class="server" show="true">
This script will create an Infernus at the center (0, 0, 3) of San Andreas upon execution.
<syntaxhighlight lang="lua">
addEventHandler( "onResourceStart", resourceRoot,
function()
infernus = Vehicle(411, Vector3(0, 0, 3)); -- Create an Infernus and spawn it at the middle of SA.
infernus:setColor(0, 0, 0); -- Set its color to black.
infernus.damageProof = true; -- Make it damage proof
end
)

addCommandHandler( "blowinfernus",
function(p)
if not infernus.blown then -- Check if the Infernus is blown up or not.
infernus:blow();
else -- Ouch, it's blown up, let's output an error to the player.
outputChatBox( "The Infernus has already been blown up by you.", p, 255, 0, 0, false );
end
end)
</syntaxhighlight>
</section>
}}

==See Also==

{{Vehicle functions}}
[[de:createVehicle]]
[[pl:createVehicle]]
[[ru:CreateVehicle]]
[[pt-br:CreateVehicle]]

CreateVehicle

2020-12-04T08:16:38Z

Pirulax: Added a note regarding lag

__NOTOC__
{{Server client function}}{{Note|Vehicles (and other elements) created client-side are only seen by the client that created them, aren't synced and players cannot enter them. They are essentially for display only.}}
{{Note|Due to how GTA works, creating a lot of vehicles in the same place will cause lag. The more geometries and unique textures has model the bigger the lag is. Even a lot of default vehicles will cause lag if in the same place.}
This function creates a vehicle at the specified location.

Its worth nothing that the position of the vehicle is the center point of the vehicle, not its base. As such, you need to ensure that the z value (vertical axis) is some height above the ground. You can find the exact height using the client side function [[getElementDistanceFromCentreOfMassToBaseOfModel]], or you can estimate it yourself and just spawn the vehicle so it drops to the ground.

==Syntax==
<syntaxhighlight lang="lua">
vehicle createVehicle ( int model, float x, float y, float z [, float rx, float ry, float rz, string numberplate, bool bDirection, int variant1, int variant2 ] )
</syntaxhighlight>
{{OOP||[[Vehicle]]||}}

===Required Arguments===
* '''model''': The [[Vehicle IDs|vehicle ID]] of the vehicle being created.
* '''x''': A floating point number representing the X coordinate on the map.
* '''y''': A floating point number representing the Y coordinate on the map.
* '''z''': A floating point number representing the Z coordinate on the map.

===Optional Arguments===
{{OptionalArg}}
* '''rx''': A floating point number representing the rotation about the X axis in degrees.
* '''ry''': A floating point number representing the rotation about the Y axis in degrees.
* '''rz''': A floating point number representing the rotation about the Z axis in degrees.
* '''numberplate''': A string that will go on the number plate of the vehicle (max 8 characters).
* '''bDirection''' ''(serverside only)'': Placeholder [[boolean]] which provides backward compatibility with some scripts. It never had any effect, but it is read by the code. It is recommended to ignore this argument, passing ''false'' or the ''variant1'' argument in its place.
{{New feature/item|3.0120|1.2||
* '''variant1''': An integer for the first vehicle variant. See [[vehicle variants]].
* '''variant2''': An integer for the second vehicle variant. See [[vehicle variants]].
}}

===Returns===
Returns the [[vehicle]] element that was created. Returns ''false'' if the arguments are incorrect, or if the vehicle limit of 65535 is exceeded.

==Using trains==
Trains are created using the createVehicle function. They are placed at the nearest point of the GTASA train pathing (they usually are railroad tracks) from their spawning point.

==Example==

<section name="Example 1: Server" class="server" show="true">
This example creates a 'vehicle spawner' marker that gives the player a vehicle as soon they step into it.
<syntaxhighlight lang="lua">
local vehMark = createMarker(-2426.34106, -639.12714, 132.93631,"cylinder")

function vehicleSpawner(hitElement,matchingDimension)
if getElementType(hitElement) == "player" then
if getPedOccupiedVehicle(hitElement) == false then
local x,y,z = getElementPosition(hitElement)
local veh = createVehicle(551, x,y,z)
warpPedIntoVehicle(hitElement,veh)
end
end
end
addEventHandler("onMarkerHit",vehMark,vehicleSpawner)
</syntaxhighlight>
</section>

<section name="Example 2: Server" class="server" show="true">
This example creates a vehicle five units to the right of a player when they type ''createvehicle'' and its name in the console:
<syntaxhighlight lang="lua">
local distance = 5 --units

-- define our handler (we'll take a variable number of parameters where the name goes, because there are vehicle names with more than one word)
function consoleCreateVehicle ( sourcePlayer, commandName, ... )
-- if a player triggered it, not the admin,
if ( sourcePlayer ) then
-- calculate the position of the vehicle based on the player's position and rotation:
local x, y, z = getElementPosition ( sourcePlayer ) -- get the player's position
local rotZ = getElementRotation ( sourcePlayer ) -- get the player's rotation around the Z axis in degrees
x = x + ( ( math.cos ( math.rad ( rotZ ) ) ) * distance ) -- calculate the X position of the vehicle
y = y + ( ( math.sin ( math.rad ( rotZ ) ) ) * distance ) -- calculate the Y position of the vehicle

-- get the complete vehicle name by joining all passed parameters using Lua function table.concat
local vehicleName = table.concat({...}, " ")
-- get the vehicle's model ID from the name
local vehicleID = getVehicleModelFromName ( vehicleName )
-- if vehicle ID is valid,
if vehicleID then
-- create the vehicle using the information gathered above:
local newVehicle = createVehicle ( vehicleID, x, y, z, 0, 0, rotZ )
-- if vehicle creation failed, give the player a message
if not newVehicle then
outputConsole ( "Failed to create vehicle.", sourcePlayer )
end
end
end
end

-- Attach the 'consoleCreateVehicle' function to the "createvehicle" command
addCommandHandler ( "createvehicle", consoleCreateVehicle )
</syntaxhighlight>
</section>

<section name="Example 3: Server" class="server" show="false">
This script spawns a Rhino on top of one lucky individual.
<syntaxhighlight lang="lua">
function scriptCreateTank ( player, command )
local luckyBugger = getRandomPlayer() -- get a random player
local x, y, z = getElementPosition ( luckyBugger ) -- retrive the player's position
createVehicle ( 432, x, y, z + 10 ) -- create the tank 10 units above them
outputChatBox ( "You got Tank'd!", luckyBugger )
end
--Attach the 'scriptCreateTank' function to the "tank" command
addCommandHandler ( "tank", scriptCreateTank )
</syntaxhighlight>
</section>

<section name="Example 4: Server" class="server" show="false">
This example adds a ''/spveh'' command to spawn a car model in the provided coordinates. If any car created by this command gets blown up, it will respawn where it was created.
<syntaxhighlight lang="lua">
-- Do not allow the following IDs to be spawned
local forbiddenCars = { [435] = true, [441] = true, [449] = true, [450] = true, [464] = true, [465] = true, [501] = true,
[537] = true, [538] = true, [564] = true, [569] = true, [570] = true, [584] = true, [590] = true,
[591] = true, [594] = true, [606] = true, [607] = true, [608] = true, [610] = true, [611] = true }

local cmdVehRoot = createElement("commandVehicles") -- Dummy element containing the cars that this command has created
addCommandHandler("spveh",
function(player, cmd, modelID, x, y, z, platetext)
-- Check whether arguments are correct
local modelID, x, y, z = tonumber(modelID), tonumber(x), tonumber(y), tonumber(z)
if modelID and x and y and z then
-- Do not continue if we shouldn't
if forbiddenCars[modelID] then
outputChatBox("The car model you provided is not allowed.", player, 255, 0, 0)
return
end
local platetext = type(platetext) == "string" and platetext or "PRIVATE"
-- Create the actual vehicle and set it as a children of our dummy element
setElementParent(createVehicle(modelID, x, y, z, 0, 0, 0, platetext), cmdVehRoot)
-- Inform the player about what we did
outputChatBox("You have created a " .. getVehicleNameFromModel(modelID) .. " (model ID: " .. modelID .. ") at " .. table.concat({ x, y, z }, ", ") .. " with numberplate " .. platetext .. " successfully.", player, 0, 255, 0)
else
outputChatBox("Syntax: /" .. cmd .. " (modelID) (x) (y) (z) [numberplate]", player, 255, 255, 255)
end
end
)

-- If a vehicle that has been created using the command blows up, respawn it where it was created
addEventHandler("onVehicleExplode", cmdVehRoot,
function()
respawnVehicle(source)
end
)
</syntaxhighlight>
</section>

<section name="Example 5: Client" class="client" show="true">
This script spawns a Rhino on top of the local player.
<syntaxhighlight lang="lua">
function scriptCreateTank ( commandName )
local x, y, z = getElementPosition ( localPlayer ) -- retrive the player's position
createVehicle ( 432, x, y, z + 10 ) -- create the tank 10 units above them
outputChatBox ( "You got Tank'd!", 255, 0, 0)
end
--Attach the 'scriptCreateTank' function to the "tank" command
addCommandHandler ( "tank", scriptCreateTank )
</syntaxhighlight>
</section>

{{New items|3.0132|1.4|
This is an example of how this function is executed in an OOP environment.
<section name="OOP server" class="server" show="true">
This script will create an Infernus at the center (0, 0, 3) of San Andreas upon execution.
<syntaxhighlight lang="lua">
addEventHandler( "onResourceStart", resourceRoot,
function()
infernus = Vehicle(411, Vector3(0, 0, 3)); -- Create an Infernus and spawn it at the middle of SA.
infernus:setColor(0, 0, 0); -- Set its color to black.
infernus.damageProof = true; -- Make it damage proof
end
)

addCommandHandler( "blowinfernus",
function(p)
if not infernus.blown then -- Check if the Infernus is blown up or not.
infernus:blow();
else -- Ouch, it's blown up, let's output an error to the player.
outputChatBox( "The Infernus has already been blown up by you.", p, 255, 0, 0, false );
end
end)
</syntaxhighlight>
</section>
}}

==See Also==

{{Vehicle functions}}
[[de:createVehicle]]
[[pl:createVehicle]]
[[ru:CreateVehicle]]
[[pt-br:CreateVehicle]]

Vehicle Components

2020-12-02T12:09:43Z

Pirulax: Corrected misc_a description

This page aims to provide an overview of vehicle components. The list is currently incomplete.
<br>
{{Note|Changing wheel position on Z axis doesn't work.}}
<br>
{|class="wikitable" style="text-align:center; margin: 1em auto 1em auto;"
|-
! width="150" scope="col" style="background:#8f8f8f;"| Component Name
! width="300" scope="col" style="background:#8f8f8f;"| Description
|-
|style="background:#cfcfcf;"|boot_dummy
|style="background:#cfcfcf;"|Trunk door
|-
|style="background:#cfcfcf;"|ug_nitro
|style="background:#cfcfcf;"|Nitro (tuning part)
|-
|style="background:#cfcfcf;"|wheel_rf_dummy
|style="background:#cfcfcf;"|Right Front Wheel
|-
|style="background:#cfcfcf;"|wheel_lf_dummy
|style="background:#cfcfcf;"|Left Front Wheel
|-
|style="background:#cfcfcf;"|wheel_rb_dummy
|style="background:#cfcfcf;"|Right Back Wheel
|-
|style="background:#cfcfcf;"|wheel_lb_dummy
|style="background:#cfcfcf;"|Left Back Wheel
|-
|style="background:#cfcfcf;"|chassis
|style="background:#cfcfcf;"|Chassis
|-
|style="background:#cfcfcf;"|chassis_vlo
|style="background:#cfcfcf;"|Chassis (lod)[Can't be hid]
|-
|style="background:#cfcfcf;"|ug_roof
|style="background:#cfcfcf;"|Roof [Can't be hid]
|-
|style="background:#cfcfcf;"|door_rf_dummy
|style="background:#cfcfcf;"|Right Front Door
|-
|style="background:#cfcfcf;"|door_lf_dummy
|style="background:#cfcfcf;"|Left Front Door
|-
|style="background:#cfcfcf;"|door_rr_dummy
|style="background:#cfcfcf;"|Right Back Door
|-
|style="background:#cfcfcf;"|door_lr_dummy
|style="background:#cfcfcf;"|Left Back Door
|-
|style="background:#cfcfcf;"|bonnet_dummy
|style="background:#cfcfcf;"|Hood
|-
|style="background:#cfcfcf;"|ug_wing_right
|style="background:#cfcfcf;"|Right wing (tuning part) [Can't be hid]
|-
|style="background:#cfcfcf;"|bump_front_dummy
|style="background:#cfcfcf;"|Front bumper
|-
|style="background:#cfcfcf;"|bump_rear_dummy
|style="background:#cfcfcf;"|Back bumper
|-
|style="background:#cfcfcf;"|windscreen_dummy
|style="background:#cfcfcf;"|Windscreen
|-
|-
|style="background:#cfcfcf;"|misc_a
|style="background:#cfcfcf;"|Tow bar position on models: 514, 515, 403, 591, 552, 485, 583, 606, 607, 608.
|-
|style="background:#cfcfcf;"|ug_wing_left
|style="background:#cfcfcf;"|Leftwing (tuning part) [Can't be hid]
|-
|style="background:#cfcfcf;"|exhaust_ok
|style="background:#cfcfcf;"|Exhausts
|}

==Related scripting functions==
*[[setVehicleComponentVisible]]
*[[setVehicleComponentPosition]]
*[[setVehicleComponentRotation]]
*[[setVehicleComponentScale]]
<br>
*[[resetVehicleComponentPosition]]
*[[resetVehicleComponentRotation]]
*[[resetVehicleComponentScale]]
<br>
*[[getVehicleComponents]]
*[[getVehicleComponentVisible]]
*[[getVehicleComponentScale]]
*[[getVehicleComponentRotation]]
*[[getVehicleComponentPosition]]

==Vehicle functions==
{{Client_vehicle_functions}}

Vehicle Components

2020-12-02T11:55:58Z

Pirulax: Add misc_a component

This page aims to provide an overview of vehicle components. The list is currently incomplete.
<br>
{{Note|Changing wheel position on Z axis doesn't work.}}
<br>
{|class="wikitable" style="text-align:center; margin: 1em auto 1em auto;"
|-
! width="150" scope="col" style="background:#8f8f8f;"| Component Name
! width="300" scope="col" style="background:#8f8f8f;"| Description
|-
|style="background:#cfcfcf;"|boot_dummy
|style="background:#cfcfcf;"|Trunk door
|-
|style="background:#cfcfcf;"|ug_nitro
|style="background:#cfcfcf;"|Nitro (tuning part)
|-
|style="background:#cfcfcf;"|wheel_rf_dummy
|style="background:#cfcfcf;"|Right Front Wheel
|-
|style="background:#cfcfcf;"|wheel_lf_dummy
|style="background:#cfcfcf;"|Left Front Wheel
|-
|style="background:#cfcfcf;"|wheel_rb_dummy
|style="background:#cfcfcf;"|Right Back Wheel
|-
|style="background:#cfcfcf;"|wheel_lb_dummy
|style="background:#cfcfcf;"|Left Back Wheel
|-
|style="background:#cfcfcf;"|chassis
|style="background:#cfcfcf;"|Chassis
|-
|style="background:#cfcfcf;"|chassis_vlo
|style="background:#cfcfcf;"|Chassis (lod)[Can't be hid]
|-
|style="background:#cfcfcf;"|ug_roof
|style="background:#cfcfcf;"|Roof [Can't be hid]
|-
|style="background:#cfcfcf;"|door_rf_dummy
|style="background:#cfcfcf;"|Right Front Door
|-
|style="background:#cfcfcf;"|door_lf_dummy
|style="background:#cfcfcf;"|Left Front Door
|-
|style="background:#cfcfcf;"|door_rr_dummy
|style="background:#cfcfcf;"|Right Back Door
|-
|style="background:#cfcfcf;"|door_lr_dummy
|style="background:#cfcfcf;"|Left Back Door
|-
|style="background:#cfcfcf;"|bonnet_dummy
|style="background:#cfcfcf;"|Hood
|-
|style="background:#cfcfcf;"|ug_wing_right
|style="background:#cfcfcf;"|Right wing (tuning part) [Can't be hid]
|-
|style="background:#cfcfcf;"|bump_front_dummy
|style="background:#cfcfcf;"|Front bumper
|-
|style="background:#cfcfcf;"|bump_rear_dummy
|style="background:#cfcfcf;"|Back bumper
|-
|style="background:#cfcfcf;"|windscreen_dummy
|style="background:#cfcfcf;"|Windscreen
|-
|-
|style="background:#cfcfcf;"|misc_a
|style="background:#cfcfcf;"|Tow bar position. By default it exists on model: 514, 515, 403, 591, 552, 485, 583, 606, 607, 608.
|-
|style="background:#cfcfcf;"|ug_wing_left
|style="background:#cfcfcf;"|Leftwing (tuning part) [Can't be hid]
|-
|style="background:#cfcfcf;"|exhaust_ok
|style="background:#cfcfcf;"|Exhausts
|}

==Related scripting functions==
*[[setVehicleComponentVisible]]
*[[setVehicleComponentPosition]]
*[[setVehicleComponentRotation]]
*[[setVehicleComponentScale]]
<br>
*[[resetVehicleComponentPosition]]
*[[resetVehicleComponentRotation]]
*[[resetVehicleComponentScale]]
<br>
*[[getVehicleComponents]]
*[[getVehicleComponentVisible]]
*[[getVehicleComponentScale]]
*[[getVehicleComponentRotation]]
*[[getVehicleComponentPosition]]

==Vehicle functions==
{{Client_vehicle_functions}}

EngineRequestModel

2020-11-19T00:50:10Z

Pirulax: parentID is an optional argument

__NOTOC__
{{Client function}}
{{New feature/item|3.0158|1.5.7|20147|This function is used to assign the next available model ID to a certain element type. After release 1.5.8-20716 this function supports "vehicle" and "object" too.}}
{{note|IMPORTANT:
*before release 1.5.8-20716 this must be "ped".
}}
==Syntax==
<syntaxhighlight lang="lua">
int engineRequestModel ( str elementType )
</syntaxhighlight>
<syntaxhighlight lang="lua">
int engineRequestModel( "vehicle", [int parentID] )
</syntaxhighlight>
===Required Arguments===
*'''elementType''': "ped", "vehicle" and "object".

===Optional Arguments===
*'''parentID''': The [[Vehicle IDs|vehicle ID]] of the vehicle being allocated. '''(By default this is: 1337 - objects, 400 - vehicles, 7 or PSYCHO for peds)'''

===Returns===
{{New feature/item|3.0158|1.5.7|20147| Returns an ''integer'' of the model ID that was available to be assigned to the element type, ''false'' if no free model ID available or invalid element type.}}
Do not rely on the model numbers returned being consistent across multiple clients or multiple runs of resources. There is no guarantee for the order of the numbers or that the same numbers will always correspond to the same element type. Any patterns are coincidental

==Example==
This example creates a ped and then gives you the opportunity to change its model. If the resource stops, then the IDs allocated will be deallocated. Use ''/cap'' for creating the ped and ''/sap'' to skin the ped. You will need some skins added to a folder and to the meta.xml for ''/sap'' to work.
<syntaxhighlight lang="lua">
local peds = {}
function createAllocatedPed()
local x, y, z = getElementPosition(localPlayer)
local id = engineRequestModel("ped")
peds[id] = createPed(id, x+0.5, y, z+0.5)
outputChatBox("New ped with ID "..id.." created.")
end
addCommandHandler("cap", createAllocatedPed, false, false)

function skinAllocatedPeds()
local txd, dff;
for id,ped in pairs(peds) do
if fileExists("skins/" .. id .. ".txd") and fileExists("skins/" .. id .. ".dff") then
txd = engineLoadTXD("skins/" .. id .. ".txd")
engineImportTXD(txd, id)
dff = engineLoadDFF("skins/" .. id .. ".dff")
engineReplaceModel(dff, id)
outputChatBox("Model ID "..id.." changed correctly.")
else
outputChatBox("Model ID "..id.." couldn't change. REASON: skins/" .. id .. ".txd or skins/" .. id .. ".dff does not exist.")
end
end
end
addCommandHandler("sap", skinAllocatedPeds, false, false)

function onStop()
for id,ped in pairs(peds) do
engineFreeModel(id)
end
end
addEventHandler("onClientResourceStop", resourceRoot, onStop)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.5.7-9.20147|}}

==See Also==
{{Engine functions}}

EngineGetModelTextures

2020-11-12T19:48:17Z

Pirulax: Undo revision 67736 by Pirulax (talk)

__NOTOC__
{{Client function}}
{{New feature/item|3.0158|1.5.7|20416|This function allows you to get the textures of any model.}}

==Syntax==
<syntaxhighlight lang="lua">table engineGetModelTextures( string/int modelName/modelID [, string/table textureNames ] )</syntaxhighlight>
===Required Arguments===
*'''model''': either the model ID or model name.

===Optional Arguments===
*'''textureNames''': Only return textures with specified name(s). You can provide a single string or a table of strings. Wildcard matching e.g. "ro?ds*" can be used.

===Returns===
Returns a table of texture elements [textureName, texture], '''false''' otherwise.

==Example==
<section name="Client" class="client" show="true">
Get the textures for model ID 3722 and draw them with dxDrawImage.
<syntaxhighlight lang="lua">
function init()
textures = engineGetModelTextures(3722)
addEventHandler("onClientRender", root, render)
end
addEventHandler("onClientResourceStart", resourceRoot, init)

function render()
local offset = 0
for name,texture in pairs(textures) do
local size = dxGetPixelsSize(dxGetTexturePixels(texture))
dxDrawImage(0+offset, 0, size, size, texture)
offset = offset + size
end
end
</syntaxhighlight>
</section>

==Requirements==
{{Requirements|n/a|1.5.7-9.20416|}}
==See Also==
{{Engine_functions}}

EngineGetModelTextures

2020-11-12T19:39:37Z

Pirulax: Add note that the return value structure is differente than stated (according to the source code)

__NOTOC__
{{Client function}}
{{New feature/item|3.0158|1.5.7|20416|This function allows you to get the textures of any model.}}

==Syntax==
<syntaxhighlight lang="lua">table engineGetModelTextures( string/int modelName/modelID [, string/table textureNames ] )</syntaxhighlight>
===Required Arguments===
*'''model''': either the model ID or model name.

===Optional Arguments===
*'''textureNames''': Only return textures with specified name(s). You can provide a single string or a table of strings. Wildcard matching e.g. "ro?ds*" can be used.

===Returns===
Returns a table of texture elements [textureName, texture], '''false''' otherwise. </br>
'''Note: According to the [https://github.com/multitheftauto/mtasa-blue/blob/bafbae00cdcca392f10ffc9f450ed45e019253c4/Client/mods/deathmatch/logic/luadefs/CLuaEngineDefs.cpp#L1192 source code] the actual structure is: t[texture] = textureName'''

==Example==
<section name="Client" class="client" show="true">
Get the textures for model ID 3722 and draw them with dxDrawImage.
<syntaxhighlight lang="lua">
function init()
textures = engineGetModelTextures(3722)
addEventHandler("onClientRender", root, render)
end
addEventHandler("onClientResourceStart", resourceRoot, init)

function render()
local offset = 0
for name,texture in pairs(textures) do
local size = dxGetPixelsSize(dxGetTexturePixels(texture))
dxDrawImage(0+offset, 0, size, size, texture)
offset = offset + size
end
end
</syntaxhighlight>
</section>

==Requirements==
{{Requirements|n/a|1.5.7-9.20416|}}
==See Also==
{{Engine_functions}}

AbortRemoteRequest

2020-10-16T21:26:39Z

Pirulax: /* Example */

{{Server client function}}
__NOTOC__
{{New feature/item|3.0158|1.5.7|20307|
Aborts a [[FetchRemote|fetchRemote]] or [[CallRemote|callRemote]] request.
}}
==Syntax==
<syntaxhighlight lang="lua">
bool abortRemoteRequest( request theRequest )
</syntaxhighlight>

===Required Arguments===
* '''theRequest''': returned from [[FetchRemote|fetchRemote]], [[CallRemote|callRemote]] or [[GetRemoteRequests|getRemoteRequests]]

==Returns==
Returns true on success, false when invalid request was provided

==Example==
This example aborts all requests.
<syntaxhighlight lang="lua">
function CMD_abortRequests()
local requests = getRemoteRequests()

for _, request in ipairs(requests) do
abortRemoteRequest(request)
end
end

addCommandHandler("abortrequests", CMD_abortRequests)
</syntaxhighlight>

{{Requirements|1.5.7-9.20307|1.5.7-9.20307}}

==See Also==
{{Resource functions}}

AbortRemoteRequest

2020-10-16T21:24:58Z

Pirulax: Undo revision 67561 by Pirulax (talk)

{{Server client function}}
__NOTOC__
{{New feature/item|3.0158|1.5.7|20307|
Aborts a [[FetchRemote|fetchRemote]] or [[CallRemote|callRemote]] request.
}}
==Syntax==
<syntaxhighlight lang="lua">
bool abortRemoteRequest( request theRequest )
</syntaxhighlight>

===Required Arguments===
* '''theRequest''': returned from [[FetchRemote|fetchRemote]], [[CallRemote|callRemote]] or [[GetRemoteRequests|getRemoteRequests]]

==Returns==
Returns true on success, false when invalid request was provided

==Example==
this example aborts all pending requests of currently running resource.
<syntaxhighlight lang="lua">
function CMD_abortRequests()
local requests = getRemoteRequests()

for _, request in ipairs(requests) do
abortRemoteRequest(request)
end
end

addCommandHandler("abortrequests", CMD_abortRequests)
</syntaxhighlight>

{{Requirements|1.5.7-9.20307|1.5.7-9.20307}}

==See Also==
{{Resource functions}}

AbortRemoteRequest

2020-10-16T21:23:52Z

Pirulax: Fix the example - make the description match what the code actually does..

{{Server client function}}
__NOTOC__
{{New feature/item|3.0158|1.5.7|20307|
Aborts a [[FetchRemote|fetchRemote]] or [[CallRemote|callRemote]] request.
}}
==Syntax==
<syntaxhighlight lang="lua">
bool abortRemoteRequest( request theRequest )
</syntaxhighlight>

===Required Arguments===
* '''theRequest''': returned from [[FetchRemote|fetchRemote]], [[CallRemote|callRemote]] or [[GetRemoteRequests|getRemoteRequests]]

==Returns==
Returns true on success, false when invalid request was provided

==Example==
this example aborts all pending requests of currently running resource.
<syntaxhighlight lang="lua">
function CMD_abortRequests()
local requests = getRemoteRequests(getThisResource())

for _, request in ipairs(requests) do
abortRemoteRequest(request)
end
end

addCommandHandler("abortrequests", CMD_abortRequests)
</syntaxhighlight>

{{Requirements|1.5.7-9.20307|1.5.7-9.20307}}

==See Also==
{{Resource functions}}