Multi Theft Auto: Wiki - User contributions [en]

SetPedStat

2025-12-22T00:14:59Z

Danilo: /* Examples */

{{Shared function}}
{{Needs_Checking|
*Things like infinite run, fire proof CJ, 150 armor have special activation flags. They need a way to be triggered on/off.
}}

__NOTOC__
This function allows you to set the value of a specific statistic for a [[ped]]. '''Visual stats (FAT and BODY_MUSCLE) can only be used on the CJ skin''', they have no effect on other skins. When this function is used client-side, it can only be used on client-side created peds.

==Syntax==
<syntaxhighlight lang="lua">
bool setPedStat ( ped thePed, int stat, float value )
</syntaxhighlight>

===Required Arguments===
*'''thePed''': the [[ped]] whose statistic you want to modify.
*'''stat''': the stat ID.
{{Stats}}

*'''value''': the new value of the stat. It must be between 0 and 1000.

===Returns===
Returns ''true'' if the statistic was changed succesfully. Returns ''false'' if an invalid player is specified, if the stat ID/value is out of acceptable range or if the FAT or BODY_MUSCLE stats are used on non-CJ players.

==Examples==
This example allows a player to type the command 'beefcake' to change his player's BODY_MUSCLE stat (#23) to the maximum value of 1000. This will result in him looking really muscular.
<syntaxhighlight lang="lua">function changeBodyStrength(thePlayer, commandName)
-- Output whether the setPlayerStat was successful in changing the BODY_MUSCLE STAT
if setPedStat(thePlayer, 23, 1000) then
outputChatBox("Your player looks really muscular")
else
outputChatBox("Failed to make your player look muscular.")
end
end
addCommandHandler("beefcake", changeBodyStrength)
</syntaxhighlight>

This example adds a ''/upgradeskills'' command to give the player who types it the maximum skill with every weapon and maximum health.
<syntaxhighlight lang="lua">
--[[

Skills to upgrade:

24 = Max Player Health
69 = Weapon Type Pistol Skill
70 = Weapon Type Pistol Silenced Skill
71 = Weapon Type Desert Eagle Skill
72 = Weapon Type Shotgun Skill
73 = Weapon Type Sawn off Shotgun Skill
74 = Weapon Type Spas 12 Shotgun Skill
76 = Weapon Type MP5 Skill
77 = Weapon Type AK47 Skill
78 = Weapon Type M4 Skill
79 = Weapon Type Sniper Rifle Skill

--]]

addCommandHandler("upgradeskills", function(thePlayer)
-- Set every stat to 1000 (the maximum value)
for _, stat in ipairs({24, 69, 70, 71, 72, 73, 74, 76, 77, 78, 79}) do
setPedStat(thePlayer, stat, 1000)
outputChatBox("Your game stats upgraded to maximum!", thePlayer, 0, 255, 0, false)
end
-- Set player health to the maximum, as changing the stat keeps the current one
if (isPedDead(thePlayer) ~= true) then
setElementHealth(thePlayer, 200)
-- Tell the player what we did
outputChatBox("And your health upgraded to maximum!", thePlayer, 0, 255, 0, false)
else
outputChatBox("Your health can't be restored because you are already dead!", thePlayer, 0, 255, 0, false)
end
end)
</syntaxhighlight>

==See Also==
{{Ped functions}}
[[ru:setPedStat]]

SetPedStat

2025-12-22T00:14:14Z

Danilo:

{{Shared function}}
{{Needs_Checking|
*Things like infinite run, fire proof CJ, 150 armor have special activation flags. They need a way to be triggered on/off.
}}

__NOTOC__
This function allows you to set the value of a specific statistic for a [[ped]]. '''Visual stats (FAT and BODY_MUSCLE) can only be used on the CJ skin''', they have no effect on other skins. When this function is used client-side, it can only be used on client-side created peds.

==Syntax==
<syntaxhighlight lang="lua">
bool setPedStat ( ped thePed, int stat, float value )
</syntaxhighlight>

===Required Arguments===
*'''thePed''': the [[ped]] whose statistic you want to modify.
*'''stat''': the stat ID.
{{Stats}}

*'''value''': the new value of the stat. It must be between 0 and 1000.

===Returns===
Returns ''true'' if the statistic was changed succesfully. Returns ''false'' if an invalid player is specified, if the stat ID/value is out of acceptable range or if the FAT or BODY_MUSCLE stats are used on non-CJ players.

==Examples==
This example allows a player to type the command 'beefcake' to change his player's BODY_MUSCLE stat (#23) to the maximum value of 1000. This will result in him looking really muscular.
<syntaxhighlight lang="lua">function changeBodyStrength(thePlayer, commandName)
-- Output whether the setPlayerStat was successful in changing the BODY_MUSCLE STAT
if setPedStat(thePlayer, 23, 1000) then
outputChatBox("Your player looks really muscular")
else
outputChatBox("Failed to make your player look muscular.")
end
end
addCommandHandler("beefcake", changeBodyStrength)
</syntaxhighlight>

This example adds a ''/upgradeskills'' command to give the player who types it the maximum skill with every weapon and maximum health.
<syntaxhighlight lang="lua">
--[[

Skills to upgrade:

24 = Max Player Health
69 = Weapon Type Pistol Skill
70 = Weapon Type Pistol Silenced Skill
71 = Weapon Type Desert Eagle Skill
72 = Weapon Type Shotgun Skill
73 = Weapon Type Sawn off Shotgun Skill
74 = Weapon Type Spas 12 Shotgun Skill
76 = Weapon Type MP5 Skill
77 = Weapon Type AK47 Skill
78 = Weapon Type M4 Skill
79 = Weapon Type Sniper Rifle Skill

--]] addCommandHandler("upgradeskills", function(thePlayer)
-- Set every stat to 1000 (the maximum value)
for _, stat in ipairs({24, 69, 70, 71, 72, 73, 74, 76, 77, 78, 79}) do
setPedStat(thePlayer, stat, 1000)
outputChatBox("Your game stats upgraded to maximum!", thePlayer, 0, 255, 0, false)
end
-- Set player health to the maximum, as changing the stat keeps the current one
if (isPedDead(thePlayer) ~= true) then
setElementHealth(thePlayer, 200)
-- Tell the player what we did
outputChatBox("And your health upgraded to maximum!", thePlayer, 0, 255, 0, false)
else
outputChatBox("Your health can't be restored because you are already dead!", thePlayer, 0, 255, 0, false)
end
end)
</syntaxhighlight>

==See Also==
{{Ped functions}}
[[ru:setPedStat]]

SetPedStat

2025-12-22T00:06:00Z

Danilo: fix example

{{Shared function}}
{{Needs_Checking|
*Things like infinite run, fire proof CJ, 150 armor have special activation flags. They need a way to be triggered on/off.
}}

__NOTOC__
This function allows you to set the value of a specific statistic for a [[ped]]. '''Visual stats (FAT and BODY_MUSCLE) can only be used on the CJ skin''', they have no effect on other skins. When this function is used client-side, it can only be used on client-side created peds.

==Syntax==
<syntaxhighlight lang="lua">
bool setPedStat ( ped thePed, int stat, float value )
</syntaxhighlight>

===Required Arguments===
*'''thePed''': the [[ped]] whose statistic you want to modify.
*'''stat''': the stat ID.
{{Stats}}

*'''value''': the new value of the stat. It must be between 0 and 1000.

===Returns===
Returns ''true'' if the statistic was changed succesfully. Returns ''false'' if an invalid player is specified, if the stat ID/value is out of acceptable range or if the FAT or BODY_MUSCLE stats are used on non-CJ players.

==Examples==
This example allows a player to type the command 'beefcake' to change his player's BODY_MUSCLE stat (#23) to the maximum value of 1000. This will result in him looking really muscular.
<syntaxhighlight lang="lua">function changeBodyStrength(thePlayer, commandName)
-- Output whether the setPlayerStat was successful in changing the BODY_MUSCLE STAT
if setPedStat(thePlayer, 23, 1000) then
outputChatBox("Your player looks really muscular")
else
outputChatBox("Failed to make your player look muscular.")
end
end
addCommandHandler("beefcake", changeBodyStrength)
</syntaxhighlight>

This example adds a ''/upgradeskills'' command to give the player who types it the maximum skill with every weapon and maximum health.
<syntaxhighlight lang="lua">
--[[

Skills to upgrade:

24 = Max Player Health
69 = Weapon Type Pistol Skill
70 = Weapon Type Pistol Silenced Skill
71 = Weapon Type Desert Eagle Skill
72 = Weapon Type Shotgun Skill
73 = Weapon Type Sawn off Shotgun Skill
74 = Weapon Type Spas 12 Shotgun Skill
76 = Weapon Type MP5 Skill
77 = Weapon Type AK47 Skill
78 = Weapon Type M4 Skill
79 = Weapon Type Sniper Rifle Skill

--]]

addCommandHandler("upgradeskills", function(thePlayer)
-- Set every stat to 1000 (the maximum value)
for _, stat in ipairs({ 24, 69, 70, 71, 72, 73, 74, 76, 77, 78, 79 }) do
setPedStat(thePlayer, stat, 1000)
outputChatBox("Your game stats upgraded to maximum!", thePlayer, 0, 255, 0, false)
end
-- Set player health to the maximum, as changing the stat keeps the current one
if (isPedDead (thePlayer) ~= true) then
setElementHealth(thePlayer, 200)
-- Tell the player what we did
outputChatBox("And your health upgraded to maximum!", thePlayer, 0, 255, 0, false)
else
outputChatBox("Your health can't be restored because you are already dead!", thePlayer, 0, 255, 0, false)
end
end)
</syntaxhighlight>

==See Also==
{{Ped functions}}
[[ru:setPedStat]]

Byte2human

2025-09-23T03:17:07Z

Danilo:

__NOTOC__
{{Useful Function}}
This function lets you transform a number of bytes into a human readable unit.

==Syntax==
<syntaxhighlight lang="lua">
string byte2human ( int bytes )
</syntaxhighlight>

===Required Arguments===
*'''bytes:''' The value which you want to get the human readable version.

===Returns===
Returns a string which shows the number transformed into a human-friendly string.

==Code==
<section name="Server/Client-Side Script" class="both" show="true">
<syntaxhighlight lang="lua">
function byte2human(bytes, si)
local threshold = si and 1000 or 1024
if (math.abs(bytes) < threshold) then
return bytes .. " B"
end
local units =
si and {"KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"}
or {"KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB"}
local unitIndex = 0
repeat
bytes = bytes / threshold
unitIndex = unitIndex + 1
until not (math.abs(bytes) >= threshold and unitIndex < #units)
return math.round(bytes, 2) .. " " .. units[unitIndex]
end

function math.round(num, decimals)
decimals = math.pow(10, decimals or 0)
num = num * decimals
if num >= 0 then num = math.floor(num + 0.5) else num = math.ceil(num - 0.5) end
return num / decimals
end
</syntaxhighlight>
</section>

'''Author: Renkon'''
(based on http://stackoverflow.com/a/14919494/2980812)

==See Also==
{{Useful_Functions}}

EngineImageGetFiles

2025-09-15T02:39:05Z

Danilo: fix example

__NOTOC__
{{Client function}}

{{New feature/item|4|1.6.0|21695|This function gets the list of files from an IMG container.}}

==Syntax==
<syntaxhighlight lang="lua">
table engineImageGetFiles ( img imgArchive )
</syntaxhighlight>

{{OOP||[[img]]:getFiles|files}}
===Required Arguments===
* '''imgArchive''': The [[IMG]] file handler you want to get files from.

===Returns===
Returns array table with files in the [[IMG]] element if successfull, false otherwise.

==Example==

You could use the following code:
<syntaxhighlight lang="lua">
local img = engineLoadIMG( "file.img" )
local filesInArchive = engineImageGetFiles( img )

outputChatBox("'file.img' contains files:")
for fileId = 1, #filesInArchive do
outputChatBox(fileId .. ": " .. filesInArchive[fileId])
end
</syntaxhighlight>

==See Also==
{{Engine_functions}}

Template:Useful Functions

2023-11-23T03:22:26Z

Danilo: move to table functions

__NOTOC__
=== Table functions ===
*[[addTableChangeHandler]] » This function monitors the changes of a table.
*[[getKeyFromValueInTable]] » This function returns the key of the specified value in a table.
*[[getTableFromSql]] » This functionality is used to obtain saved tables using the function ([https://wiki.multitheftauto.com/wiki/SetTableToSql SetTableToSql ]).
*[[isValueInTable]] » This function returns true if the value exists in the table, false if the value does not exist in the table.
*[[pairsByKeys]] » This function sort pairs table.
*[[rangeToTable]] » This function converts a string range to a table containing number values.
*[[setTableProtected]] » This function protects a table and makes it read-only.
*[[setTableToSql]] » This function is used to save the table in the database (sql).
*[[Sort_Functions]] » These functions are able to sort your tables by a key.
*[[table.compare]] » This function checks whether two given tables are equal.
*[[table.copy]] » This function copies a whole table and all the tables in that table.
*[[table.deepmerge]] » This function deep merges two tables. Every nested table will be correspondingly merged.
*[[table.element]] » This function returns a new table with only userdata content.
*[[table.flip]] » This function returns the table from the last value to the first value, such as reflection.
*[[table.fromString]] » This function converts string to a table.
*[[table.getRandomRows]] » This function returns random rows from table.
*[[table.map]] » This function goes through a table and replaces every field with the return of the passed function, where the field's value is passed as first argument and optionally more arguments.
*[[table.merge]] » This function merges two or more tables together.
*[[table.random]] » This function retrieves a random value from a table.
*[[table.removeValue]] » This function removes a specified value from a table.
*[[table.size]] » This function returns the absolute size of a table.

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

=== Account functions ===
*[[getPlayerFromAccountName]] » This function is used to obtain a player by the name of his account.

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

=== Colshape functions ===
*[[createGarageColShape]] » This function creates a collision shape from the specified garage.

=== Cursor functions ===
*[[getCursorMovedOn]] » This function checks in which way the cursor is currently moving.
*[[setCursorCenteredOnRectangle]] » This functions will center the cursor inside a rectangle.

=== Drawing functions ===
*[[dxDrawAnimWindow]] » This function draws an animated 2D window on the screen.
*[[dxDrawBorderedRectangle]] » This is a function that will create a bordered rectangle.
*[[dxDrawBorderedText]] » This is a function that will create a bordered text.
*[[dxDrawDashedLine]] » This function draws a line with dashes.
*[[dxDrawEditbox]] » This function draws a edit box across the screen - rendered for one frame. This should be used in conjunction with '''onClientRender''' in order to display continuously.
*[[dxDrawGifImage]] » This function simulates the effect of a GIF image by using image sprites in 2D.
*[[dxDrawImage3D]] » This function draws a 3D image in GTA world.
*[[dxDrawImageOnElement]] » This function draws an image on any element.
*[[dxDrawLinedRectangle]] » This is a function that will create a rectangle outline with dx lines.
*[[dxDrawLoading]] » This function draws a loading bar on the screen.
*[[dxDrawOctagon3D]] » This function creates a 3D Octagon
*[[dxDrawPolygon]] » This function draws a custom polygon on the screen.
*[[dxDrawProgressBar]] » This function simulates a progress bar drawed using DirectDraw.
*[[dxDrawRectangle3D]] » This function draws a 3D rectangle in GTA world.
*[[dxDrawRectangleOnPlayer]] » This function draws a 3D rectangle above the player.
*[[dxDrawRing]] » This function draws a ring with dx lines.
*[[dxDrawRombo]] » This function creates a Rhombus.
*[[dxDrawSprite]] » This function draw a sprite in the 3D world.
*[[dxDrawTextOnElement]] » This function draws a text on any element.
*[[dxDrawTextOnRectangle]] » Esta funcion crea un rectangle con un texto dentro.
*[[dxDrawTriangle]] » This is a function that will create a triangle with dx lines.
*[[dxFade]] » This function fade-in or fade-out any dxDraw by gradually changing its alpha value.
*[[dxGetFontSizeFromHeight]] » This function calculates the font size from given height.
*[[dxGetRealFontHeight]] » This function calculates the height of a font.
*[[getScreenStartPositionFromBox]] » This function helps with getting the correct position for your dx-effects.
*[[wordWrap]] » This function breaks a long string into a table of separate lines limited to a specific length in pixels, for drawing separately.
*[[CreateRectangle3D]] » This is a function that will create a 3d rectangle on the player screen.
*[[DxDrawBordered3DLine]] »This function creates a bordered area with 3D dx lines.

=== Effects functions ===
*[[attachEffect]] » This function allows you attach an effect to an element.
*[[setScreenFlash]] » This function will make the screen flash(like a screenshot).

=== Element functions ===
*[[autoAttach]] » This function attaches one element into another at the same position and rotation they are.
*[[attachElementToBone]] » This function allows you to attach an element to ped bone accurately using new bone functions.
*[[getElementDirectionCardialPoint]] » This function returns the direction of the element according to the ''wind rose''.
*[[getElementSpeed]] » This function returns the specified element's speed in m/s, km/h or mph.
*[[getElementUsingData]] » This function returns table elements that contains the elements data with the given key and value.
*[[getElementZoneFullName]] » This function allows you to retrieve the zone full name of a element.
*[[getElementsInDimension]] » This function returns a table of elements that are in the specified dimension.
*[[getElementsWithinMarker]] » This function returns a table of elements that are within a marker's collision shape.
*[[getNearestElement]] » This function returns the nearest element (of a specific type) to a player.
*[[isElementInAir]] » This function checks if an element is in air or not.
*[[isElementInPhotograph]] » This function checks if an element is in the player's camera picture area.
*[[isElementInRange]] » This function allows you to check if an element's range to a main point is within the maximum range.
*[[isElementMoving]] » This function checks if an element is moving.
*[[isElementPlayer]] » This function checks whether the element is a player or not.
*[[isElementWithinAColShape]] » This function checks if an element is within a collision shape element.
*[[multi_check]] » This function checks one element to many, handy and clean.
*[[setElementSpeed]] » This function allows you to set the speed of an element in kph or mph units.
*[[getPositionInFrontOfElement]] » This function returns position in provided distance away from element, including element's rotation.

=== Events ===
*[[onClientPlayerTimeChange]] » This code implements an event that is triggered when the player's real time change.
*[[onPlayerZoneChange]] » This code implements an event that is triggered when the player enters a new area on the map.
*[[onVehicleWeaponFire]] » This code implements an event that is triggered when a player in a vehicle fires a vehicle's weapon.

=== Input functions ===
*[[bindControlKeys]] » This function allows you to bind each key bound to a control individually. Doing this bypasses a little MTA restriction.
*[[getBoundControls]] » This function returns a table of control names that are bound to the specified key.
*[[unbindControlKeys]] » This function allows you to unbind each key bound to a control individually. Use this function with [[bindControlKeys]].
*[[isCommandHandlerAdded]] » This function allows you to check if a command is added or not in the respective resource.

=== Data functions ===
*[[byte2human]] » This function converts an integer (number of bytes) into a human-readable unit.
*[[capitalize]] » This function capitalizes a given string.
*[[convertDate]] » This function converts date to another look.
*[[convertServerTickToTimeStamp]] » This function converts server ticks to a unix timestamp.
*[[convertTextToSpeech]] » This function converts the provided text to a speech in the provided language which players can hear.
*[[findRotation3D]] » This function takes two sets of XYZ coordinates. It returns the 3D direction from point A to point B.
*[[findRotation]] » This function takes two points and returns the direction from point A to point B.
*[[formatDate]] » This function formats a date on the basis of a format string and returns it.
*[[formatNumber]] » This function formats large numbers by adding commas.
*[[generateRandomASCIIString]] » This function returns a random string which uses ASCII characters. 
*[[generateString]] » This function generates a random string with any characters.
*[[getAge]] » This function calculates the age of a given birthday.
*[[getDistanceBetweenElements]] » Returns the distance between two elements.
*[[getDistanceBetweenPointAndSegment2D]] » This function takes point coordinates and line (a segment) starting and ending coordinates. It returns the shortest distance between the point and the line.
*[[getEasterDate]] » This function returns easter date monthday and month for a given year.
*[[getElementRelatedAngle]] » This function returns the related angle between one element to another. This is useful to check which side an element is to another.
*[[getFreeDimension]] » This function get free dimension.
*[[getOffsetFromXYZ]] » This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.
*[[getPointFromDistanceRotation]] » This function finds a point based on a starting point, direction and distance.
*[[getRealMonth]] » This function returns the current month name
*[[getRGColorFromPercentage]] »This function returns two integers representing red and green colors according to the specified percentage.
*[[getScreenRotationFromWorldPosition]] » This function returns a screen relative rotation to a world position.
*[[getTimestamp]] » This function returns the UNIX timestamp of a specified date and time.
*[[gradientString]] » This function transforms a string in a new coloured gradient string.
*[[hex2rgb]] » This function convert hex to rgb.
*[[hexColorToRGB]] » This function convert hex string/number to RGBA values.
*[[isLeapYear]] » This function returns a boolean representing if a given year is a leap year.
*[[isValidMail]] » This function checks whether a provided e-mail string is valid.
*[[removeHex]] » This function is used to remove hexadecimal numbers (colors, for example) from strings.
*[[RGBToHex]] » This function returns a string representing the color in hexadecimal.
*[[RGBToHSV]] » This function convert RGB to HSV color space.
*[[RGBToDecimal]] » This function convert RGB to Decimal color.
*[[secondsToTimeDesc]] » This function converts a plain seconds-integer into a user-friendly time description.
*[[string.count]] » This function counts the amount of occurences of a string in a string.
*[[string.explode]] » This function splits a string at a given separator pattern and returns a table with the pieces.
*[[string.insert]] » This function inserts a string within another string at a given position.
*[[splitMultiple]] » This function improves the split function so that multiple characters can be used as the split at character.
*[[switch]] » This function allows the value of a variable or expression to control the flow of program execution via a multiway branch.
*[[tocolor2rgba]] » This function convert tocolor to rgba.
*[[toHex]] » This function converts a decimal number to a hexadecimal number, as a fix to be used client-side.
*[[var dump]] » This function outputs information about one or more variables using outputConsole.
*[[wavelengthToRGBA]] » This function converts a physical wavelength of light to a RGBA color.

=== GUI functions ===
*[[centerWindow]] » This function centers a CEGUI window element responsively in any resolution.
*[[guiMoveElement]] » This function moves guiElement by/like using moveObject.
*[[guiSetStaticImageMovable]] » This function allows you to move a static image like a gui window.
*[[isMouseOnGUICloseButton]] » This function allows you to check whether the mouse cursor/pointer is within a gui-window's native close button.
*[[isMouseOnGuiElement]] » This function allows you to check whether or not your mouse is over a specific gui element, this is especially useful if the gui element has a parent. 
=====Comboboxes=====
*[[guiComboBoxAdjustHeight]] » This function adjusts a CEGUI combobox element to have the correct height.

=====Gridlists=====
*[[convertGridListToText]] » This function converts grid list contents to text.
*[[getGridListRowIndexFromText]] » This function returns the GridList row index from the specified text.
*[[guiGridListAddPlayers]] » This function add all online players to a grid list.
*[[guiGridListGetColumnIDFromTitle]] » This function gets a gridlist's column ID from the column title.
*[[guiGridListGetSelectedText]] » This function returns a string containing the inner text of a selected gridlist item.
*[[guiGridListSetColumnNonSortable]] » This function makes a gridlist column become non-sortable.
*[[isTextInGridList]] » This function checks if some text exist or not in the GridList.

=====Labels=====
*[[guiLabelAddEffect]] » This function add an effects to the gui-label like (shadow, outline).

=== Marker functions ===
*[[createMarkerAttachedTo]] » This function creates a marker that is attached to an element.

=== Math functions ===
*[[math.clamp]] » This function returns the number between range of numbers or it's minimum or maximum.
*[[math.getBezierPoint]] » Get N-th order bezier point.
*[[math.hypot]] » This function returns the Hypotenuse of the triangle given by sides x and y.
*[[math.isPointInPolygon]] » Check if point is inside polygon or not.
*[[math.lerp]] » Get val between two integer.
*[[math.percent]] » This function returns a percentage from two number values.
*[[math.polygonArea]] » Compute area of any polygon.
*[[math.randomDiff]] » Generates a pseudo-random integer that's always different from the last random number generated.
*[[math.rotVecToEulerAngle]] » Rotation Vector To Euler Angle
*[[math.round]] » Rounds a number whereas the number of decimals to keep and the method may be set.
*[[mathNumber]] » This function is a workaround for the client-side floating-point precision of 24-bits.
*[[reMap]] » Re-maps a number from one range to another.
*[[Math.percentProgress|math.percentProgress]] » Returns a percentage progress from two specific values.
*[[math.average]] » This function returns the simple arithmetic mean of multiple numbers.

=== Map functions ===
*[[assignLod]] » This function lets you conveniently generate and apply a LOD model to a mapping object.
*[[getWorldPositionFromMapPosition]] » This function converts an F11 map position to world position.

=== Ped functions ===
*[[getAlivePlayersInTeam]] » This function returns a table of the alive players in a team.
*[[getGuestPlayers]] » This function gets a players not login or players Guest .
*[[getOnlineAdmins]] » This function returns a table of all logged-in administrators.
*[[getPedEyesPosition]] » This function allows you to get peds eyes position.
*[[getPedGender]] » This function allows you to get peds their gender.
*[[getPedMaxHealth]] » This function returns a pedestrians's maximum health by converting it from their maximum health stat.
*[[getPedMaxOxygenLevel]] » This function returns a ped's maximum oxygen level by converting it from their maximum underwater stamina stat.
*[[getPedWeaponSkill]] » This function returns a ped's corresponding weapon skill level name.
*[[getPedHitBone]] » This function gets the approximate number of the bone where the ped is hit.
*[[getPlayerFromNamePart]] » This function returns a player from partial name.
*[[getPlayerFromSerial]] » This function returns a player from their serial.
*[[getPlayersByData]] » This function returns a table of players that have the specified data name.
*[[getPlayersInPhotograph]] » This function returns a table of all players in photograph.
*[[getPlayersInVehicles]] » This function returns a table of the players insides vehicles from a specified dimension.
*[[isPedAiming]]» This function checks if a pedestrian is aiming their weapon.
*[[isPedAimingNearPed]] » This is similar to isPedAiming but uses a colshape to be more precise.
*[[isPedDiving]] » This feature checks that pedestrian is diving in the water.
*[[isPedDrivingVehicle]] » This function checks if a specified pedestrian is driving a vehicle.
*[[isPedNearbyWall]] » This function checks if player/ped is nearby a objects like buildings or walls.
*[[isPlayerInTeam]] » This function checks if a player is in a specified team.
*[[setPedAttack]] » This function will make a ped attack a specified target.
*[[setPedFollow]] » This function will make a ped follow a specified target.
*[[getPlayerNameFromID]] » This function will get the player name from the ID element data.

=== Player functions ===
*[[countPlayersInRange]] » This function returns the number of players that are within a certain range of the specified coordinates.
*[[getPlayerPreviousAndNextWeapon]] » This function returns the player previous and next weapon.
*[[getPlayersInRange]] » This function make a table of players within certain range.
*[[isPlayerActuallyInVehicle]] » This function checks if a player is actually in a vehicle instead of just in the process of entering.
*[[isPlayerHitByVehicle]] » This function cancels event when a element is hit by a vehicle.

=== Resource functions ===
*[[getFilesInResourceFolder]] » This function gets a list of files that are inside a folder of a resource.
*[[getResourceScripts]] » This function returns a table of the resource scripts.
*[[getResourceSettings]] » This function returns a table of the resource settings.
*[[getResourceSize]] » This function returns the size of a specified resource in kB(kilobyte)
*[[refreshResource]] » This function refreshes your resource if you changed any of the files
*[[setResourcePriority]] » This function set resource download priority group.

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

=== Browser functions ===
*[[playVideo]] » This function plays a video on the screen.

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

=== Vehicle functions ===
*[[findEmptyCarSeat]] » This function finds you the first empty seat in a vehicle.
*[[getNearestVehicle]] » This function gets the nearest vehicle to the specified player in a specified distance.
*[[getRandomVehicle]] » This function gets a random vehicle.
*[[getValidVehicleModels]] » This function returns a table of all valid vehicle models.
*[[getVehiclesCountByType]] » This function returns the amount of vehicles by the given type as an integer value.
*[[getVehicleTurnVelocityCenterOfMass]]» This function gets a vehicle's turn velocity relative to the vehicle's center or mass.
*[[isVehicleDoubleExhaust]] » This function checks is exhaust vehicle double.
*[[isVehicleEmpty]] » This function checks whether a vehicle is empty.
*[[isVehicleOccupied]] » This function checks if a specified vehicle is occupied.
*[[isVehicleOnRoof]] » This function checks whether vehicle is on roof.
*[[isVehicleOnFire]] » This function checks if the vehicle is on fire or not.
*[[isVehicleReversing]] » This function checks if a specified vehicle is moving backwards.
*[[isVehicleUpgraded]] » This function checks is vehicle upgraded by upgrade ID.
*[[setVehicleGravityPoint]] » This function sets a vehicle's gravity in the direction of a 3 dimensional coordinate with the strength specified.
*[[setVehicleTurnVelocityCenterOfMass]] » This function sets a vehicle's turn velocity relative to the vehicle's center or mass.
*[[setVehicleHandlingFromText]] » This function sets a vehicle's handling from text.
*[[setVehicleWheelModel]] » This function changes the wheel model of the informed vehicle.

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

=== Object functions ===
*[[getDynamicDoorObjectOpenRatio]] » This function tells you how open a dynamic door is in a range from 0 to 1.
*[[isElementObject]] » This function tells you if an element is an object or no.

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

=== Engine functions ===
*[[engineGetCOLsFromLibrary]] » This function gets the collision data from the col library.
*[[engineLoadIMGContainer]] » This function loads the IMG container.

=== Utility ===
*[[animate]] » This function allows you to use interpolateBetween without render event and easily used.
*[[callClientFunction]] » This function allows you to call any client-side function from the server's side.
*[[callServerFunction]] » This function allows you to call any server-side function from the client's side.
*[[check]] » This function checks if its arguments are of the right type and calls the error-function if one is not.
*[[checkPassiveTimer]] » This function allows you to use passive timers in your conditions. For example you want to prevent players repeatedly using a command.
*[[coroutine.resume]] » This function applies a fix for hidden coroutine error messages.
*[[compact]] » This function create table containing variables and their values.
*[[fingerprint]] » This function calculates a fingerprint unique to each computer.
*[[getBanFromName]] » This functions returns the ban of the given playername.
*[[getCurrentFPS]] » This function returns the frames per second at which GTA: SA is running.
*[[getSkinNameFromID]] » This function returns the name of the skin from the given id.
*[[IfElse]] » This function returns one of two values based on a boolean expression.
*[[isCharInString]] » This shared function allows you to check if a char specified is in a string value.
*[[isLastExecuteInTimer]] » This function check if the execute is the last execute in the timer.
*[[isMouseInCircle]] » This function checks if a cursor position is in circular area or not.
*[[isMouseInPosition]] » This function allows you to check whether the mouse cursor/pointer is within a rectangular position.
*[[iterElements]] » This function returns ''a time-saving'' iterator for your for-loops.
*[[PlotTrajectoryAtTime]] » Calculate projectile/water trajectory.
*[[preprocessor]] » This function allow you to use gcc macros.
*[[vector3:compare]] » This method checks whether two vectors match, with optional precision.
*[[svgCreateRoundedRectangle]] » This function creates a rectangle with rounded edges.
*[[debounce]] » This function is removing unwanted input noise.

<noinclude>[[Category:Useful Functions]]</noinclude>

Modules/FileSystem/translator/scanDir

2023-11-14T21:28:04Z

Danilo: fix code example

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function loops through all translator filesystem entries that are captured by the wildcard and the directory specifier. The wildcard is glob-style and supports '''*''' and '''?''' modifiers. The scan can be made recursive to enter every directory it finds, so that files and folders of a whole directory tree are captured. This function is used to process filesystem objects inside of directories without having to add the filenames into a configuration file. This greatly increases flexibility when processing files. Other than [[MTA:Eir/FileSystem/translator/scanDirEx|scanDirEx]], this function returns a table of directories and files.

==Syntax==
<syntaxhighlight lang="lua">
table translator:scanDir ( string dirPath, string wildcard, bool recursive )
</syntaxhighlight>

==Arguments==
*'''dirPath:''' a path to the directory the scan shall take place or start in
*'''wildcard:''' glob-style wild-card for filename matching; every filename that matches the wild-card is returned
*'''recursive:''' a boolean that specifies whether the whole directory tree at dirPath should be included into the scan

==Returns==
This function returns a table consisting of all directories and all matching file entries which were found during the scan. It returns '''false''' if '''dirPath''' is an invalid path specifier for the translator.

==Example==
<section name="Client" class="client" show="true">
This snippet outputs the count of directories and files in a specified directory relative to the resource instance root.
<syntaxhighlight lang="lua">
-- Attempt to get a handle to the FileSystem module namespace.
local fsys = createFilesystemInterface();

-- Get a handle to the resource instance directory.
local resRoot = fsys.createTranslator( "mods/deathmatch/resources/" .. getResourceName(resource) .. "/" );

-- Function that returns whether the given path is a directory path.
local function isDirectoryPath( path )
local lastChar = string.sub( path, #path, #path );

return ( lastChar == "/" ) or ( lastChar == "\\" );
end

local function getFilesystemObjectCounts( path )
local fileCount = 0;
local dirCount = 0;

-- Get a list of all fs objects.
local fsObjects =
resRoot:scanDir(
path, -- scan anywhere the script wants us to
"*", -- include all files
false -- scan the specified directory only
);

-- Loop through all object names to set up the counts.
-- An object can either be a directory or a file.
for m,n in ipairs(fsObjects) do
if ( isDirectoryPath( n ) ) then
dirCount = dirCount + 1;
else
fileCount = fileCount + 1;
end
end

-- Return the counts.
return fileCount, dirCount;
end

-- Output the filesystem object counts for the resource instance root.
local fileCount, dirCount = getFilesystemObjectCounts( "/" );

outputChatBox( "found " .. fileCount .. " files and " .. dirCount .. " directories in the resource folder root." );
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

IsVehicleOnFire

2023-11-02T21:28:34Z

Danilo:

{{Useful Function}}
<lowercasetitle></lowercasetitle>
__NOTOC__
This function checks if the vehicle is on fire.

==Syntax==
<syntaxhighlight lang="lua">bool isVehicleOnFire(vehicle theVehicle)</syntaxhighlight>

===Required Arguments===
* '''vehicle''': vehicle element.

==Code==
<section name="Function source" class="both" show="true">
<syntaxhighlight lang="lua">
function isVehicleOnFire(elementVehicle)
if elementVehicle and getElementType(elementVehicle) == "vehicle" then
local vHealth = getElementHealth(elementVehicle)
return vHealth < 250
end
return false
end
</syntaxhighlight>
</section>

==See Also==
{{Useful_Functions}}

Talk:IsPlayerACLAdmin

2023-07-11T18:47:03Z

Danilo: Created page with "isPlayerInACL Is enough for ACL groups checks. Adding too specific functions is not what we want."

[[isPlayerInACL]] Is enough for ACL groups checks. Adding too specific functions is not what we want.

Famous crash offsets and their meaning

2023-01-28T01:28:33Z

Danilo: /* Resolving crashes related to custom models */

<big>This wiki page contains the reason for many well-known MTA crashes that you may experience. Use CTRL + F and search for your Crash Offset to find the relevant entry.</big>

Example crash dialog info:
<syntaxhighlight lang="xml">
Version = 1.5.6-release-14664.0.000
Time = Mon Oct 8 12:20:00 2018
Module = C:\Program Files (x86)\Rockstar Games\GTA San Andreas\gta_sa.exe
Code = 0xC0000005
Offset = 0x003C91CC

EAX=0F77A3C8 EBX=0F77A3B8 ECX=0177FAA0 EDX=00139700 ESI=00000000
EDI=00000001 EBP=0177FC50 ESP=0177FA80 EIP=007C91CC FLG=00210202
CS=0023 DS=002B SS=002B ES=002B FS=0053 GS=002B
</syntaxhighlight>

(Note: always use the "Offset" value from the crash dialog to identify your crash and match it up with those listed on this wiki page)

'''Most MTA crashes are caused by something that the user is able to resolve because it depends on their system, choice of server or game mods.'''
This page seeks to be helpful for the aforementioned reason; you'll know where to look for when you get a certain type of crash.

For further advice on resolving issues, scroll down to the bottom of this page.

 
==Module = gta_sa.exe or proxy_sa.exe==
{| class="wikitable"
|-
!Offset(s)
!Meaning
|-
|<syntaxhighlight lang="lua">0x00134134</syntaxhighlight>
|Bad model or corrupted GTA3.img. Use unmodded GTA install to check, or incase of server mods, ask server owner to identify and replace the corrupt mod.
Note for server owners and modellers: if you open the crash dump (.dmp) as text with notepad and search for keyword `CEntity_GetBoundRect - No collision for model` you can often identify the bad model ID.
|-
|<syntaxhighlight lang="lua">0x00348CF4</syntaxhighlight>
|Caused by s0beit d3d9.dll
|-
|<syntaxhighlight lang="lua">
0x003F0C37
0x003F0BF7
</syntaxhighlight>
|Bad vehicle model. Use unmodded GTA install to check, or incase of server mods, ask server owner to identify and replace the corrupt mod.
|-
|<syntaxhighlight lang="lua">
0x003C91CC
0x003C920C
</syntaxhighlight>
|Out of video memory. This can happen on servers with unoptimized mods and (faulty) scripts that abuse video memory, or even when you have a powerful graphics card in case the stuff on a server is extremely unoptimized so that it starts hitting GTA limits. If you have a powerful graphics card and more players suffer from this crash type, inform the server owner of this problem as it probably means their scripters & designers don't know what they are doing. More information is available at these forum links: [https://forum.mtasa.com/topic/85094-mta-crashing/ here] and [https://forum.mtasa.com/topic/127677-c-r-a-s-h-i-n-g/ here (example case)]
|-
|-
|<syntaxhighlight lang="lua">0x00357DEC</syntaxhighlight>
|Out of video memory (probably).
|-
|<syntaxhighlight lang="lua">0x003F5A3A</syntaxhighlight>
|Memory crash, usually happens on heavily unoptimized servers. It can be a result of either out of video memory or reaching technical limits of RAM usage, but more often a combination of both.. hence it's put as "heavily unoptimized servers". Contact the server owner and ask for optimization, or find other servers to play on.
|-
|-
|<syntaxhighlight lang="lua">0x004A1ED4</syntaxhighlight>
|Out of system memory (RAM)
|-
|-
|-
|<syntaxhighlight lang="lua">
0x011630F8
0x011630FE
0x01162FE3
0x011630F2
</syntaxhighlight>
|This crash is a result of problems with collision models. It might be due to unoptimized collisions that your PC (or MTA's technical limits, due to bad server mods) cannot handle, or due to corrupt collision models. We still don't know a lot about all of the circumstances related to this crash. Our first advise would be to ensure that your GTA is unmodded, and otherwise to ask server owner to identify and resolve issues with bad/unoptimized collision models.
|-
|<syntaxhighlight lang="lua">0x00137D6E</syntaxhighlight>
|Out of system memory (RAM). This co-incides with loading collisions; the risk to get this crash is high when joining a mod-heavy server with a weak PC and small amount of memory.
To resolve this crash, mind the servers you're playing on (optimization) or get a faster PC. Sub-type of "Running out of memory": most often a direct result of running out of address space, so upgrading to 64-bit Windows installation might solve it
|-
|<syntaxhighlight lang="lua">0x0014F406</syntaxhighlight>
|Possibly "Running out of memory": a direct result of running out of address space, so upgrading to 64-bit Windows installation might solve it.
|-
|<syntaxhighlight lang="lua">0x00171A10</syntaxhighlight>
|Sometimes when joining a server, maybe related to bad server mods.
|-
|-
|<syntaxhighlight lang="lua">0x000C9F98</syntaxhighlight>
|Possibly bad skin model or texture (clothes mods for multi-clump skins such as CJ).
Use unmodded GTA install to check or incase of server mods, ask server owner to identify and disable mods on such skins, or any resource manipulating clothes or ped accesoires.
|-
|-
|<syntaxhighlight lang="lua">0x00349B7B</syntaxhighlight>
|Bad skin model. Use unmodded GTA install to check or incase of server mods, ask server owner to identify and replace the corrupt skin mod.
Information for modellers & server owners: corruption in the anim hierarchy in ped's skin DFF or bones configuration
|-
|-
|<syntaxhighlight lang="lua">0x00165096</syntaxhighlight>
|Bad model (containing a corrupt collision model). Use unmodded GTA install to check or incase of server mods, ask server owner to identify and replace the corrupt mod.
Information for modellers & server owners: corruption in one or multiple col spheres (or their radius) within the DFF model.
|-
|<syntaxhighlight lang="lua">0x001D6E6A</syntaxhighlight>
|Either out of video memory, or bad model/texture.
Information for modellers & server owners: in case the culprit is a model, then corruption is in "prelit" (Night colors) structure of the model. Ask your modeller to recreate prelit data.
|-
|-
|<syntaxhighlight lang="lua">
0x000DFE92
0x000DFF90
</syntaxhighlight>
|Bad sound mods or faulty audio driver/device. Use unmodded GTA install to check, or update your audio drivers.
The problem is often known to be entirely missing or emptied/corrupted audio files (such as in \Rockstar Games\GTA San Andreas\audio > SFX or other subfolder), so you may alternatively be able to restore a targeted backup.

Do not use 'compressed' GTA re-packs for this reason of cut-out audio files.
|-
|-
|-
|<syntaxhighlight lang="lua">0x000CFCD6</syntaxhighlight>
|Allocation failure as a result of (re-)connecting to servers after a lengthy playing session on a server with bad practise in their scripts (abusing RAM and anim functions).
This crash may be 'fixed' (averted) by MTA in future, we're working on it! It's related to anims in memory and clearing them.
|-
|-
|<syntaxhighlight lang="lua">
0x00771848
</syntaxhighlight>
|Crash because of issue with GTA data files (MTA fails to open them which could mean they are corrupted/modded & incompatible or missing)
Use unmodded GTA install to check
|-
|<syntaxhighlight lang="lua">
0x001B6B2F
</syntaxhighlight>
|Crash because of issue with DATA\DEFAULT.DAT or DATA\CARCOLS.DAT file in your GTA installation folder (may be missing or modded/corrupted).
Use unmodded GTA install to check
|-
|<syntaxhighlight lang="lua">
0x003EC9DA
</syntaxhighlight>
|Crash possibly because of issue with ANIM\PED.IFP file in your GTA installation folder (may be missing or modded/corrupted).
Use unmodded GTA install to check
|-
|-
|-
|<syntaxhighlight lang="lua">
0x003F18CF
0x003F190F
</syntaxhighlight>
|Bad model. Use unmodded GTA install to check or in case of server mods, ask server owner to identify and replace the corrupt mod.
This crash has been averted (fixed by MTA), but due to technical limitations will still occur for Windows XP users. 
Information for modellers & server owners: due to the nature of corruption, the model introduces a risk to crash, it could happen at any given moment while nearby.
|-
|<syntaxhighlight lang="lua">
0x0019BD39
</syntaxhighlight>
|Bad model. Use unmodded GTA install to check or in case of server mods, ask server owner to identify and replace the corrupt mod.
This crash usually occurs when you fire a weapon while the corrupt model is streamed in (physically nearby).
|-
|<syntaxhighlight lang="lua">
0x000C9691
</syntaxhighlight>
|Bad or missing vehicle model. This usually happens when you deleted a model from your GTA3.img without restoring the original or putting another model in its place. Or when the DFF isn't a valid model file at all.
Restore GTA3.img or use unmodded GTA install to check, and if that doesn't work then ask server owner to identify and replace the corrupt mod, since it can also still be a bad model (or a dodgy script, that, tell them this: deals with vehicle types, variants, upgrades etc, in an improper way)
|-
|<syntaxhighlight lang="lua">
0x0000F67C
0x0000F663
</syntaxhighlight>
|Custom models which are not working with volumetric shadows. Fix models or disable volumetric shadows in Settings->Video.
|-
|<syntaxhighlight lang="lua">0x00423FD0</syntaxhighlight>
|Bad GTA mods or corrupted GTA3.img. Re-install GTA (with a clean and original version) to solve this crash. Note: known crash for common pirated copies & torrents of GTA, due to missing, bad or corrupted .dat, .col and .ipl files (pre-installed mods). MTA only supports the original, legally purchased version of GTA.
|-
|<syntaxhighlight lang="lua">0x000A2CF3</syntaxhighlight>
|Corrupted, missing or modded GTA San Andreas\models > '''effects.fxp''' file. If restoring that file to original doesn't fix the crash, use unmodded GTA as it can also be due to related GTA data files (ones that have to do with effects).
|-
|<syntaxhighlight lang="lua">
0x001A49D4
</syntaxhighlight>
|Bad mod (custom player.img in GTA San Andreas\models). Restore player.img to original or use unmodded GTA.
Note: this crash can also be triggered when a player with CJ model (or CJ clothes) appears on your screen, on a server you're playing on. Your custom player.img cannot handle that and will cause a crash.
|}

==Resolving out-of-memory crashes==
If you're experiencing crashes that, according to the table of common crashes, are related to any sort of running out of memory, then we advise you to;

- Mind the type of servers you're playing on, especially in combination with how powerful your PC is. There's lots of bloated, mod-heavy servers out there in MTA that demand the better of your PC and may also abuse memory through inefficient scripts besides custom mods (or even with the lack thereof).

We could write a book about the real cause (which is that such servers have bad scripters, or those that don't know what optimization is, and that they add everything, including bloated models and textures, without reviewing it) but we won't do that here.

If you have a slow or older generation PC, then we advise you to avoid certain "fancy" servers with huge resource downloads and such.

- Install 64-bits version of Windows rather than x86 (32-bit)

'''If you still want to play on servers that may easily get upper hand on your system, then;'''

- Upgrade your PC's hardware for enhanced performance; consider replacing the videocard with one suitable for gaming, or adding additional system memory (RAM). Re-installing Windows can sometimes also help a bunch if your OS in general is slow and not well-maintained. Alternatively, perform some mainentance (consult someone with tech experience, or make a start by updating drivers and running various junk cleaners & renowned PC performance optimization tools)

- Follow the instructions listed at [https://forum.mtasa.com/topic/78081-32-bit-windows-crashing/ https://forum.mtasa.com/topic/78081-32-bit-windows-crashing/]

- Remove any mods to your GTA installation (preferably re-install) because mods may take up video memory and RAM, enough to cause your high memory usage and subsequent crashes.
Also you should definately try lowering streaming memory, by going into Settings->Advanced->Streaming memory-> and setting it to Min.

Remember that GTA is an old game, and MTA places a lot of power in the hands of scripters (to mess up with a lack of optimization). Even if you have a high amount of RAM (for example 8gb, 16gb) you can't expect it to all be usable.. old games have technical limits and limited address space. Server scripters can do really cool and insanely realistic stuff while using far below 3.6GB RAM (the absolute technical limit in SA), but only as long they have scripters and modellers/designers that know about optimization. Strictly taken, no server, no matter how modded or beautiful.. should need to use above 2GB of RAM. Most decent servers use between 800MB - 1.6GB anyways. If you wish to learn more about this subject or are a server owner that wants to realize their mistakes, please join the MTA discord at https://discord.gg/mtasa and go to the #general channel, then open that channel's pinned post about optimization ecosystem problems (written by Dutchman101).

Please note that in general, '''any crash''' with exception code '''0xE06D7363''' (on an MTA module, and not gta_sa.exe like this wiki page is focussed on) is also a memory-related issue, and comes back to the memory abuse by servers and mods described above.

==Resolving crashes related to custom models==
If you're experiencing crashes that, according to the table of common crashes, are related to corrupt custom models, then we advise you to re-install GTA from the original game source (DVD or Steam, so no pre-modded repacks) or restore targeted file back-ups in case you understand which (type of) model may cause the crash.

In case you're only experiencing the crashes while playing on a certain server, there's a high chance that server is loading custom server models, and then we recommend you to contact the server owner so they can investigate and potentially identify & replace the corrupted model to stop the crashes. Until they take successful action, on that server you can try to avoid physically facing the mod you believe results in a crash (like not spawning said vehicle or using said skin).
Let us remind you of the chance that the bad model is in your GTA3.img, but by coincidence you never physically come near that model on other servers, and the server you're crashing the most on happens to force usage of that model ID upon you (like as regularly used vehicle or skin); therefore it cannot be ruled out that it's possibly still your client mod, despite you only crashing on a single server, and it's worth at least re-installing your GTA to try it out.

If you are a server owner and wouldn't prefer letting go of your beloved (corrupt) model, then you can ask an experienced modeller to try fix the corruption by modifying/revising it.
The alternative of crashing many players, potentially resulting in player loss for your server, isn't fine either way. For this reason, keeping a sharp eye on trends of players reporting (or shouting) that they crashed, and following up with them to get the crash details (to try match them up to model crashes from the table on this wiki page), may be a good idea.

Adding upgradable components (named "ug_upgradename") outside of chassis_dummy, will cause crashes once the vehicle has the respective upgrade component spawned.

[[ru:Famous crash offsets and their meaning]]
[[pt-br:Crashs famosos e seu significado ]]

Famous crash offsets and their meaning

2023-01-28T01:27:27Z

Danilo: /* Module = gta_sa.exe or proxy_sa.exe */

<big>This wiki page contains the reason for many well-known MTA crashes that you may experience. Use CTRL + F and search for your Crash Offset to find the relevant entry.</big>

Example crash dialog info:
<syntaxhighlight lang="xml">
Version = 1.5.6-release-14664.0.000
Time = Mon Oct 8 12:20:00 2018
Module = C:\Program Files (x86)\Rockstar Games\GTA San Andreas\gta_sa.exe
Code = 0xC0000005
Offset = 0x003C91CC

EAX=0F77A3C8 EBX=0F77A3B8 ECX=0177FAA0 EDX=00139700 ESI=00000000
EDI=00000001 EBP=0177FC50 ESP=0177FA80 EIP=007C91CC FLG=00210202
CS=0023 DS=002B SS=002B ES=002B FS=0053 GS=002B
</syntaxhighlight>

(Note: always use the "Offset" value from the crash dialog to identify your crash and match it up with those listed on this wiki page)

'''Most MTA crashes are caused by something that the user is able to resolve because it depends on their system, choice of server or game mods.'''
This page seeks to be helpful for the aforementioned reason; you'll know where to look for when you get a certain type of crash.

For further advice on resolving issues, scroll down to the bottom of this page.

 
==Module = gta_sa.exe or proxy_sa.exe==
{| class="wikitable"
|-
!Offset(s)
!Meaning
|-
|<syntaxhighlight lang="lua">0x00134134</syntaxhighlight>
|Bad model or corrupted GTA3.img. Use unmodded GTA install to check, or incase of server mods, ask server owner to identify and replace the corrupt mod.
Note for server owners and modellers: if you open the crash dump (.dmp) as text with notepad and search for keyword `CEntity_GetBoundRect - No collision for model` you can often identify the bad model ID.
|-
|<syntaxhighlight lang="lua">0x00348CF4</syntaxhighlight>
|Caused by s0beit d3d9.dll
|-
|<syntaxhighlight lang="lua">
0x003F0C37
0x003F0BF7
</syntaxhighlight>
|Bad vehicle model. Use unmodded GTA install to check, or incase of server mods, ask server owner to identify and replace the corrupt mod.
|-
|<syntaxhighlight lang="lua">
0x003C91CC
0x003C920C
</syntaxhighlight>
|Out of video memory. This can happen on servers with unoptimized mods and (faulty) scripts that abuse video memory, or even when you have a powerful graphics card in case the stuff on a server is extremely unoptimized so that it starts hitting GTA limits. If you have a powerful graphics card and more players suffer from this crash type, inform the server owner of this problem as it probably means their scripters & designers don't know what they are doing. More information is available at these forum links: [https://forum.mtasa.com/topic/85094-mta-crashing/ here] and [https://forum.mtasa.com/topic/127677-c-r-a-s-h-i-n-g/ here (example case)]
|-
|-
|<syntaxhighlight lang="lua">0x00357DEC</syntaxhighlight>
|Out of video memory (probably).
|-
|<syntaxhighlight lang="lua">0x003F5A3A</syntaxhighlight>
|Memory crash, usually happens on heavily unoptimized servers. It can be a result of either out of video memory or reaching technical limits of RAM usage, but more often a combination of both.. hence it's put as "heavily unoptimized servers". Contact the server owner and ask for optimization, or find other servers to play on.
|-
|-
|<syntaxhighlight lang="lua">0x004A1ED4</syntaxhighlight>
|Out of system memory (RAM)
|-
|-
|-
|<syntaxhighlight lang="lua">
0x011630F8
0x011630FE
0x01162FE3
0x011630F2
</syntaxhighlight>
|This crash is a result of problems with collision models. It might be due to unoptimized collisions that your PC (or MTA's technical limits, due to bad server mods) cannot handle, or due to corrupt collision models. We still don't know a lot about all of the circumstances related to this crash. Our first advise would be to ensure that your GTA is unmodded, and otherwise to ask server owner to identify and resolve issues with bad/unoptimized collision models.
|-
|<syntaxhighlight lang="lua">0x00137D6E</syntaxhighlight>
|Out of system memory (RAM). This co-incides with loading collisions; the risk to get this crash is high when joining a mod-heavy server with a weak PC and small amount of memory.
To resolve this crash, mind the servers you're playing on (optimization) or get a faster PC. Sub-type of "Running out of memory": most often a direct result of running out of address space, so upgrading to 64-bit Windows installation might solve it
|-
|<syntaxhighlight lang="lua">0x0014F406</syntaxhighlight>
|Possibly "Running out of memory": a direct result of running out of address space, so upgrading to 64-bit Windows installation might solve it.
|-
|<syntaxhighlight lang="lua">0x00171A10</syntaxhighlight>
|Sometimes when joining a server, maybe related to bad server mods.
|-
|-
|<syntaxhighlight lang="lua">0x000C9F98</syntaxhighlight>
|Possibly bad skin model or texture (clothes mods for multi-clump skins such as CJ).
Use unmodded GTA install to check or incase of server mods, ask server owner to identify and disable mods on such skins, or any resource manipulating clothes or ped accesoires.
|-
|-
|<syntaxhighlight lang="lua">0x00349B7B</syntaxhighlight>
|Bad skin model. Use unmodded GTA install to check or incase of server mods, ask server owner to identify and replace the corrupt skin mod.
Information for modellers & server owners: corruption in the anim hierarchy in ped's skin DFF or bones configuration
|-
|-
|<syntaxhighlight lang="lua">0x00165096</syntaxhighlight>
|Bad model (containing a corrupt collision model). Use unmodded GTA install to check or incase of server mods, ask server owner to identify and replace the corrupt mod.
Information for modellers & server owners: corruption in one or multiple col spheres (or their radius) within the DFF model.
|-
|<syntaxhighlight lang="lua">0x001D6E6A</syntaxhighlight>
|Either out of video memory, or bad model/texture.
Information for modellers & server owners: in case the culprit is a model, then corruption is in "prelit" (Night colors) structure of the model. Ask your modeller to recreate prelit data.
|-
|-
|<syntaxhighlight lang="lua">
0x000DFE92
0x000DFF90
</syntaxhighlight>
|Bad sound mods or faulty audio driver/device. Use unmodded GTA install to check, or update your audio drivers.
The problem is often known to be entirely missing or emptied/corrupted audio files (such as in \Rockstar Games\GTA San Andreas\audio > SFX or other subfolder), so you may alternatively be able to restore a targeted backup.

Do not use 'compressed' GTA re-packs for this reason of cut-out audio files.
|-
|-
|-
|<syntaxhighlight lang="lua">0x000CFCD6</syntaxhighlight>
|Allocation failure as a result of (re-)connecting to servers after a lengthy playing session on a server with bad practise in their scripts (abusing RAM and anim functions).
This crash may be 'fixed' (averted) by MTA in future, we're working on it! It's related to anims in memory and clearing them.
|-
|-
|<syntaxhighlight lang="lua">
0x00771848
</syntaxhighlight>
|Crash because of issue with GTA data files (MTA fails to open them which could mean they are corrupted/modded & incompatible or missing)
Use unmodded GTA install to check
|-
|<syntaxhighlight lang="lua">
0x001B6B2F
</syntaxhighlight>
|Crash because of issue with DATA\DEFAULT.DAT or DATA\CARCOLS.DAT file in your GTA installation folder (may be missing or modded/corrupted).
Use unmodded GTA install to check
|-
|<syntaxhighlight lang="lua">
0x003EC9DA
</syntaxhighlight>
|Crash possibly because of issue with ANIM\PED.IFP file in your GTA installation folder (may be missing or modded/corrupted).
Use unmodded GTA install to check
|-
|-
|-
|<syntaxhighlight lang="lua">
0x003F18CF
0x003F190F
</syntaxhighlight>
|Bad model. Use unmodded GTA install to check or in case of server mods, ask server owner to identify and replace the corrupt mod.
This crash has been averted (fixed by MTA), but due to technical limitations will still occur for Windows XP users. 
Information for modellers & server owners: due to the nature of corruption, the model introduces a risk to crash, it could happen at any given moment while nearby.
|-
|<syntaxhighlight lang="lua">
0x0019BD39
</syntaxhighlight>
|Bad model. Use unmodded GTA install to check or in case of server mods, ask server owner to identify and replace the corrupt mod.
This crash usually occurs when you fire a weapon while the corrupt model is streamed in (physically nearby).
|-
|<syntaxhighlight lang="lua">
0x000C9691
</syntaxhighlight>
|Bad or missing vehicle model. This usually happens when you deleted a model from your GTA3.img without restoring the original or putting another model in its place. Or when the DFF isn't a valid model file at all.
Restore GTA3.img or use unmodded GTA install to check, and if that doesn't work then ask server owner to identify and replace the corrupt mod, since it can also still be a bad model (or a dodgy script, that, tell them this: deals with vehicle types, variants, upgrades etc, in an improper way)
|-
|<syntaxhighlight lang="lua">
0x0000F67C
0x0000F663
</syntaxhighlight>
|Custom models which are not working with volumetric shadows. Fix models or disable volumetric shadows in Settings->Video.
|-
|<syntaxhighlight lang="lua">0x00423FD0</syntaxhighlight>
|Bad GTA mods or corrupted GTA3.img. Re-install GTA (with a clean and original version) to solve this crash. Note: known crash for common pirated copies & torrents of GTA, due to missing, bad or corrupted .dat, .col and .ipl files (pre-installed mods). MTA only supports the original, legally purchased version of GTA.
|-
|<syntaxhighlight lang="lua">0x000A2CF3</syntaxhighlight>
|Corrupted, missing or modded GTA San Andreas\models > '''effects.fxp''' file. If restoring that file to original doesn't fix the crash, use unmodded GTA as it can also be due to related GTA data files (ones that have to do with effects).
|-
|<syntaxhighlight lang="lua">
0x001A49D4
</syntaxhighlight>
|Bad mod (custom player.img in GTA San Andreas\models). Restore player.img to original or use unmodded GTA.
Note: this crash can also be triggered when a player with CJ model (or CJ clothes) appears on your screen, on a server you're playing on. Your custom player.img cannot handle that and will cause a crash.
|}

==Resolving out-of-memory crashes==
If you're experiencing crashes that, according to the table of common crashes, are related to any sort of running out of memory, then we advise you to;

- Mind the type of servers you're playing on, especially in combination with how powerful your PC is. There's lots of bloated, mod-heavy servers out there in MTA that demand the better of your PC and may also abuse memory through inefficient scripts besides custom mods (or even with the lack thereof).

We could write a book about the real cause (which is that such servers have bad scripters, or those that don't know what optimization is, and that they add everything, including bloated models and textures, without reviewing it) but we won't do that here.

If you have a slow or older generation PC, then we advise you to avoid certain "fancy" servers with huge resource downloads and such.

- Install 64-bits version of Windows rather than x86 (32-bit)

'''If you still want to play on servers that may easily get upper hand on your system, then;'''

- Upgrade your PC's hardware for enhanced performance; consider replacing the videocard with one suitable for gaming, or adding additional system memory (RAM). Re-installing Windows can sometimes also help a bunch if your OS in general is slow and not well-maintained. Alternatively, perform some mainentance (consult someone with tech experience, or make a start by updating drivers and running various junk cleaners & renowned PC performance optimization tools)

- Follow the instructions listed at [https://forum.mtasa.com/topic/78081-32-bit-windows-crashing/ https://forum.mtasa.com/topic/78081-32-bit-windows-crashing/]

- Remove any mods to your GTA installation (preferably re-install) because mods may take up video memory and RAM, enough to cause your high memory usage and subsequent crashes.
Also you should definately try lowering streaming memory, by going into Settings->Advanced->Streaming memory-> and setting it to Min.

Remember that GTA is an old game, and MTA places a lot of power in the hands of scripters (to mess up with a lack of optimization). Even if you have a high amount of RAM (for example 8gb, 16gb) you can't expect it to all be usable.. old games have technical limits and limited address space. Server scripters can do really cool and insanely realistic stuff while using far below 3.6GB RAM (the absolute technical limit in SA), but only as long they have scripters and modellers/designers that know about optimization. Strictly taken, no server, no matter how modded or beautiful.. should need to use above 2GB of RAM. Most decent servers use between 800MB - 1.6GB anyways. If you wish to learn more about this subject or are a server owner that wants to realize their mistakes, please join the MTA discord at https://discord.gg/mtasa and go to the #general channel, then open that channel's pinned post about optimization ecosystem problems (written by Dutchman101).

Please note that in general, '''any crash''' with exception code '''0xE06D7363''' (on an MTA module, and not gta_sa.exe like this wiki page is focussed on) is also a memory-related issue, and comes back to the memory abuse by servers and mods described above.

==Resolving crashes related to custom models==
If you're experiencing crashes that, according to the table of common crashes, are related to corrupt custom models, then we advise you to re-install GTA from the original game source (DVD or Steam, so no pre-modded repacks) or restore targetted file back-ups in case you understand which (type of) model may cause the crash.

In case you're only experiencing the crashes while playing on a certain server, there's a high chance that server is loading custom server models, and then we recommend you to contact the server owner so they can investigate and potentially identify & replace the corrupted model to stop the crashes. Until they take successful action, on that server you can try to avoid physically facing the mod you believe results in a crash (like not spawning said vehicle or using said skin).
Let us remind you of the chance that the bad model is in your GTA3.img, but by coincidence you never physically come near that model on other servers, and the server you're crashing the most on happens to force usage of that model ID upon you (like as regularly used vehicle or skin); therefore it cannot be ruled out that it's possibly still your client mod, despite you only crashing on a single server, and it's worth at least re-installing your GTA to try it out.

If you are a server owner and wouldn't prefer letting go of your beloved (corrupt) model, then you can ask an experienced modeller to try fix the corruption by modifying/revising it.
The alternative of crashing many players, potentially resulting in player loss for your server, isn't fine either way. For this reason, keeping a sharp eye on trends of players reporting (or shouting) that they crashed, and following up with them to get the crash details (to try match them up to model crashes from the table on this wiki page), may be a good idea.

Adding upgradable components (named "ug_upgradename") outside of chassis_dummy, will cause crashes once the vehicle has the respective upgrade component spawned.

[[ru:Famous crash offsets and their meaning]]
[[pt-br:Crashs famosos e seu significado ]]

Talk:IsVehicleOnFire

2022-10-03T02:21:58Z

Danilo: Blanked the page

IsVehicleOnFire

2022-10-03T02:19:54Z

Danilo: /* Author */

IsVehicleOnFire

2022-10-03T02:08:08Z

Danilo: Improve function in order to work as meant

Talk:IsVehicleOnFire

2022-09-27T01:58:09Z

Danilo: Created page with "Things to fix in this code: 1 - Function's return can be improved; it will only return false/true if the code executes the if statements 2 - < 300 Is not the actual value the vehicle starts going on fire"

Things to fix in this code:
1 - Function's return can be improved; it will only return false/true if the code executes the if statements
2 - < 300 Is not the actual value the vehicle starts going on fire

GetRealTime

2022-08-26T22:36:00Z

Danilo: format the string to two digits with a proper programming standard

__NOTOC__
{{Server client function}}
This function gets the server or client (if used client sided it returns time as set on client's computer) real time and returns it in a table. If you want to get the in-game time (shown on GTA's clock) use [[getTime]].

==Syntax==
<syntaxhighlight lang="lua">table getRealTime( [ int seconds = current, bool localTime = true ] )</syntaxhighlight>

===Optional Arguments===
*'''seconds:''' A count in seconds from the year 1970. Useful for storing points in time, or for retrieving time information for [[getBanTime]]. The valid range of this argument is 0 to 32,000,000,000
{{New feature/item|3.0141|1.4.1|6976|
*'''localTime:''' Set to ''true'' to adjust for the locally set timezone.
}}

===Returns===
Returns a ''table'' of substrings with different time format or ''false'' if the '''seconds''' argument is out of range.

{| border="2" cellpadding="2" cellspacing="0" style="margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse; font-size: 95%;"
|'''Member'''
|'''Meaning'''
|'''Range'''
|-
|second
|seconds after the minute
|0-61*
|-
|minute
|minutes after the hour
|0-59
|-
|hour
|hours since midnight
|0-23
|-
|monthday
|day of the month
|1-31
|-
|month
|months since January
|0-11
|-
|year
|years since 1900
|-
|weekday
|days since Sunday
|0-6
|-
|yearday
|days since January 1
|0-365
|-
|isdst
|Daylight Saving Time flag
|-
|timestamp
|seconds since 1970 (Ignoring set timezone)
|
|}
''* second'' is generally 0-59. Extra range to accommodate for leap seconds in certain systems.

==Remarks==
The '''seconds''' parameter can be left out entirely while still using the '''localTime''' parameter. To achieve that simply pass the boolean localTime parameter as first argument where you would otherwise pass the '''seconds''' parameter. This way you can retrieve a current timepoint that is not denoted in local time.

==Example==
This example adds 'showtime' like the default MTA 'time' command:
<syntaxhighlight lang="lua">
function showtime ()
local time = getRealTime()
local hours = time.hour
local minutes = time.minute
local seconds = time.second

-- use string.format to keep it 2 digits. eg 1 will be converted to 01
outputChatBox ( string.format("Local Time: %02d:%02d:%02d", hours, minutes, seconds) )
end
addCommandHandler("showtime", showtime)
</syntaxhighlight>

Example with year, month, monthday using string.format:
<syntaxhighlight lang="lua">
function showtime ()
local time = getRealTime()
local hours = time.hour
local minutes = time.minute
local seconds = time.second

local monthday = time.monthday
local month = time.month
local year = time.year

local formattedTime = string.format("%04d-%02d-%02d %02d:%02d:%02d", year + 1900, month + 1, monthday, hours, minutes, seconds)
outputChatBox ( "Local Time: ".. formattedTime )
end
addCommandHandler("showtime", showtime)
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.4.0-9.06976|Added localTime argument}}

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

IsPlayerInACL

2022-07-03T21:11:08Z

Danilo: /* Code */

{{Useful Function}}
__NOTOC__
This function returns true if the player is in the ACL group, false if otherwise. 

==Syntax==
<syntaxhighlight lang="lua">bool isPlayerInACL ( player thePlayer, string ACLGroup )</syntaxhighlight>

===Required Arguments===
* '''thePlayer''': The player element that you want to check
* '''ACLGroup''': The name of the ACL group that you want to check

'''Important Note''': This function will only work on the server-side.

===Returns===
Returns true if the player's account is in the ACL, false if otherwise.

==Code==
<section name="Function source" class="server" show="true">
<syntaxhighlight lang="lua">
function isPlayerInACL(player, acl)
if isElement(player) and getElementType(player) == "player" and aclGetGroup(acl or "") then
local account = getPlayerAccount(player)

return isObjectInACLGroup( "user.".. getAccountName(account), aclGetGroup(acl) )
end
return false
end
</syntaxhighlight>
</section>

==Example==
This is an example of the function.
<syntaxhighlight lang="lua">function checkAccess(thePlayer)
if isPlayerInACL(thePlayer, "Console") then
outputChatBox("Access Granted!")
else
outputChatBox("Access Denied!")
end
end
addCommandHandler("myaccess", checkAccess)</syntaxhighlight>
 
xXMADEXx 

==See Also==
{{Useful_Functions}}

[[RU:IsPlayerInACL]]

Modules/FileSystem/translator/open

2022-01-24T02:04:14Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function opens a link to a file instance on a given Eir FileSystem translator. Using a file link you can write and/or receive data from filesystems.

==Syntax==
<syntaxhighlight lang="lua">
file, string translator:open ( string filePath, string fileMode )
</syntaxhighlight>

==Arguments==
*'''filePath:''' the path to the file that should be opened
*'''fileMode:''' an ANSI file mode descriptor (can be 'w', 'r' or 'a', with 'b' and/or '+' appended)

==Returns==
This function returns the '''FileSystem file''' class that can be used to retrieve or store data persistently. Returns '''false''' if the file failed to open and the '''reason of failure as string'''.

===Failure reasons===
* unknown error
* path out of scope
* invalid parameters
* resources exhausted
* access denied
* not found
* already exists

==Example==
<section name="Server" class="server" show="true">
This snippet lists information about the registered MTA server modules. This information can be retrieved through a command.
<syntaxhighlight lang="lua">
-- The table that will contain all module information.
local moduleInfo = {};

-- Attempt to get a handle to the FileSystem module namespace.
local fsys = createFilesystemInterface();

-- Could fail if the server restrictions are set tight.
if not ( fsys ) then
outputDebugString( "could not get a handle to the FileSystem module namespace" );
return false;
end

local function moduleFileIterator( filePath )
-- Create an entry for this module.
local moduleName = fsys.root:relPath( filePath );
local moduleStats = fsys.root:stat( filePath );

local entry = {
name = moduleName,
stats = moduleStats
};

-- Add the entry into the registry.
table.insert( moduleInfo, entry );
end

-- Loop through all server modules.
fsys.root:chdir( "mods/deathmatch/modules/" );
fsys.root:scanDirEx( "", "*", nil, moduleFileIterator, false );

-- Function to get a module into by name.
local function getModuleByName( name )
for m,n in ipairs( moduleInfo ) do
if ( n.name == name ) then
return n;
end
end

return false;
end

-- Command to request server module information.
addCommandHandler( "modules",
function(player, moduleName)
-- Output module information to the player.
local module = getModuleByName( moduleName );

if not ( module ) then
outputChatBox( "could not find module named " .. tostring( moduleName ), player );
return false;
end

-- Output it.
outputChatBox( "module-name: " .. module.name );
outputChatBox( "module-size: " .. module.stats.size );

-- todo: add more info about the module.
end
);
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

{{:Modules/FileSystem/file/functions}}

Modules/FileSystem/createTranslator

2022-01-24T02:01:00Z

Danilo:

Modules/FileSystem/getDoBufferAllRaw

2022-01-23T04:03:17Z

Danilo:

<pageclass class="#e36242" subcaption="Namespace function"></pageclass>
__NOTOC__
This function returns the value of the buffering-policy for newly created raw-file handles.

==Syntax==
<syntaxhighlight lang="lua">
bool fsnamespace.getDoBufferAllRaw()
</syntaxhighlight>

==Returns==
This function returns true if the buffering-policy is enabled, false otherwise.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/namespace/functions}}

Modules/FileSystem/setDoBufferAllRaw

2022-01-23T04:02:29Z

Danilo:

<pageclass class="#e36242" subcaption="Namespace function"></pageclass>
__NOTOC__
This function changes the raw-file buffering policy of newly created file streams. If the buffering-policy is enabled then each newly created file stream is wrapped inside of a custom FileSystem buffering handle. File stream modifications that are close to each other are batched together for optimizational purposes.

==Syntax==
<syntaxhighlight lang="lua">
void fsnamespace.setDoBufferAllRaw( bool enabled )
</syntaxhighlight>

==Arguments==
*'''enabled''': new value for the buffering-policy

==Returns==
This function does return nil.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/namespace/functions}}

Modules/FileSystem/type

2022-01-23T04:02:02Z

Danilo:

<pageclass class="#e36242" subcaption="Namespace function"></pageclass>
__NOTOC__
This function returns the type of the given Eir FileSystem object.

==Syntax==
<syntaxhighlight lang="lua">
string fsnamespace.type( userdata obj )
</syntaxhighlight>

==Arguments==
*'''obj''': the Eir FileSystem object to retrieve the type from

==Returns==
This function returns the type string of the queried object, false if not successful. For destroyed objects the return value is always false.

===Possible Return Values===
*file
*file-translator

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/namespace/functions}}

Modules/FileSystem/topointer

2022-01-23T04:01:24Z

Danilo:

<pageclass class="#e36242" subcaption="Namespace function"></pageclass>
__NOTOC__
This function returns the light-userdata representation of the object. This is the direct pointer into the Eir FileSystem module handle.

==Syntax==
<syntaxhighlight lang="lua">
light-userdata fsnamespace.topointer( userdata obj )
</syntaxhighlight>

==Arguments==
*'''obj''': the userdata of the Eir FileSystem Lua environment

==Returns==
This function returns the light-userdata value of the internal object, false if not successful.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/namespace/functions}}

Modules/FileSystem/streamCompare

2022-01-23T04:00:41Z

Danilo:

<pageclass class="#e36242" subcaption="Namespace function"></pageclass>
__NOTOC__
This function compares the bytes of two streams for equality. The comparison starts from the current file seek and finishes at the end of the respective file stream. If the read count of either stream does not match the other, then this function fails.

==Syntax==
<syntaxhighlight lang="lua">
bool fsnamespace.streamCompare( file left, file right )
</syntaxhighlight>

==Arguments==
*'''left''': first file for equality comparison
*'''right''': second file for equality comparison

==Returns==
This function returns true if the data stream was equal, false otherwise.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/namespace/functions}}

{{:Modules/FileSystem/file/functions}}

Modules/FileSystem/pathToFilename

2022-01-23T04:00:13Z

Danilo:

<pageclass class="#e36242" subcaption="Namespace function"></pageclass>
__NOTOC__
This function returns the filename and the directory portions of a filepath, separated into two strings.

==Syntax==
<syntaxhighlight lang="lua">
string, string fsnamespace.pathToFilename( string path, bool includeExtention )
</syntaxhighlight>

==Arguments==
*'''path''': the file path to extract from
*'''includeExtention''': if true then the filename extention is included in the result

==Returns==
This function returns the filename and directory of the provided file path.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/namespace/functions}}

Modules/FileSystem/copyStreamCount

2022-01-23T03:59:50Z

Danilo:

<pageclass class="#e36242" subcaption="Namespace function"></pageclass>
__NOTOC__
This function copies data starting from a source file stream into a specified destination stream. The copy of data is performed starting from the source file seek. The copy is only performed up to a specified count of bytes.

Read operations on the file streams advance the seek pointers. Thus the seek pointers stay changed after the function has completed.

==Syntax==
<syntaxhighlight lang="lua">
bool fsnamespace.copyStreamCount( file src, file dst, int count )
</syntaxhighlight>

==Arguments==
*'''src''': source of the copy operation, starting from the seek pointer
*'''dst''': target of the copy operation, starting from the seek pointer
*'''count''': the amount of bytes to copy (has to be above 0)

==Returns==
This function returns true if the copy operation has completed successfully, false otherwise.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/namespace/functions}}

{{:Modules/FileSystem/file/functions}}

Modules/FileSystem/copyStream

2022-01-23T03:58:50Z

Danilo:

<pageclass class="#e36242" subcaption="Namespace function"></pageclass>
__NOTOC__
This function copies data starting from a source file stream into a specified destination stream. The copy of data is performed starting from the source file seek.

Read operations on the file streams advance the seek pointers. Thus the seek pointers stay changed after the function has completed.

==Syntax==
<syntaxhighlight lang="lua">
bool fsnamespace.copyStream( file src, file dst )
</syntaxhighlight>

==Arguments==
*'''src''': source of the copy operation, starting from the seek pointer
*'''dst''': target of the copy operation, starting from the seek pointer

==Returns==
This function returns true if the copy operation has completed successfully, false otherwise.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/namespace/functions}}

{{:Modules/FileSystem/file/functions}}

Modules/FileSystem/copyFile

2022-01-23T03:58:16Z

Danilo:

<pageclass class="#e36242" subcaption="Namespace function"></pageclass>
__NOTOC__
This function copies files between two translators.

==Syntax==
<syntaxhighlight lang="lua">
bool fsnamespace.copyFile( translator srcTrans, string srcPath, translator dstTrans, string dstPath )
</syntaxhighlight>

==Arguments==
*'''srcTrans:''' source translator for the file of origin
*'''srcPath:''' path into the source translator
*'''dstTrans:''' target translator
*'''dstPath:''' path into the target translator

==Returns==
This function returns true if the copy has succeeded, false otherwise.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/namespace/functions}}

{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/createFileIterative

2022-01-23T03:57:16Z

Danilo:

<pageclass class="#e36242" subcaption="Namespace function"></pageclass>
__NOTOC__
This function attempts to create a file with numeric iteration for filename collision avoidance. If a specific filename is taken then the algorithm will try to create the next file with increased numeric insert.

==Syntax==
<syntaxhighlight lang="lua">
file fsnamespace.createFileIterative( translator target, string prefix, string suffix, int maxIterations )
</syntaxhighlight>

==Arguments==
*'''target''': the file translator based on which to create the file
*'''prefix''': part of file path before the numeric insert
*'''suffix''': part of file path after the numeric insert (for example the file extention)
*'''maxIterations''': integral number of tries for the existing filename collisions (greater than 0)

==Returns==
This function returns a newly created file handle distinct from any other colliding one if successful, false otherwise.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/namespace/functions}}

{{:Modules/FileSystem/file/functions}}

{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/createMemoryFile

2022-01-23T03:56:29Z

Danilo:

<pageclass class="#e36242" subcaption="Namespace function"></pageclass>
__NOTOC__
This function creates a single file that is resident entirely in system memory.

==Syntax==
<syntaxhighlight lang="lua">
file fsnamespace.createMemoryFile( )
</syntaxhighlight>

==Returns==
This function returns a new file object if successful, false otherwise.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/namespace/functions}}

{{:Modules/FileSystem/file/functions}}

Modules/FileSystem/createRAMDisk

2022-01-23T03:54:08Z

Danilo:

<pageclass class="#e36242" subcaption="Namespace function"></pageclass>
__NOTOC__
This function creates a FileSystem translator which is located entirely inside of MTA application memory, also known as RAM.

==Syntax==
<syntaxhighlight lang="lua">
translator fsnamespace.createRAMDisk( bool caseSensitive )
</syntaxhighlight>

==Arguments==
*'''caseSensitive:''' if true then all namespaces are compared case sensitively in path operations, otherwise strict character equality comparison is performed

==Returns==
This function returns a new '''FileSystem translator''' that can be used to store (temporary) files in. If the creation of the ramdisk has failed, then false is returned.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/namespace/functions}}

{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/createTranslator

2022-01-23T03:53:04Z

Danilo:

<pageclass class="#e36242" subcaption="Namespace function"></pageclass>
__NOTOC__
This function creates a FileSystem translator. A FileSystem translator represents a directory on a real or virtual filesystem. Through translators you get access to the files that reside in their directory trees. The translator returned by this function usually represents an OS filesystem directory.

==Syntax==
<syntaxhighlight lang="lua">
translator fsnamespace.createTranslator( string rootPath )
</syntaxhighlight>

==Arguments==
*'''rootPath:''' the absolute path to the directory that you want access to.

==Returns==
This function returns the '''FileSystem translator''' that grants access to files in the requested directory.

==Example==
<section name="Server" class="server" show="true">
This snippet links all directories inside of your resource instance folder using translators and lists them in a dictionary under their name.
<syntaxhighlight lang="lua">
-- Dictionary that will contain all directory links of our resource.
local dirs = {};

-- Get a handle to the FileSystem module namespace.
local fsys = createFilesystemInterface();

-- Make sure we could obtain the module namespace.
if not ( fsys ) then
outputDebugString( "could not obtain FileSystem module namespace" );
return false;
end

-- Create a translator to the resource root.
local resRoot = fsys.createTranslator( "mods/deathmatch/resources/" .. getResourceName(resource) .. "/" );

local function dirIterator( dirPath )
-- get the simple name of this directory.
-- the simple name is the path relative to resRoot without the '/'
local simpleName = resRoot.relPathRoot( dirPath );
simpleName = string.sub( simpleName, 1, #simpleName - 1 );

-- link this directory and set it into our dirs dictionary.
-- we should always pass the absolute directory to this function.
local translator = fileCreateTranslator( dirPath );

dirs[simpleName] = translator;
end

local function fileIterator( filePath )
-- do nothing.
return;
end

resRoot.scanDirEx( "/", "*", dirIterator, fileIterator, false );
</syntaxhighlight>
</section>
<section name="Client" class="client" show="false">
This snippet links all directories inside of your resource instance folder using translators and lists them in a dictionary under their name.
<syntaxhighlight lang="lua">
-- Dictionary that will contain all directory links of our resource.
local dirs = {};

-- Create a translator to the resource root.
local resRoot = fileCreateTranslator( "/" );

local function dirIterator( dirPath )
-- get the simple name of this directory.
-- the simple name is the path relative to resRoot without the '/'
local simpleName = resRoot.relPathRoot( dirPath );
simpleName = string.sub( simpleName, 1, #simpleName - 1 );

-- link this directory and set it into our dirs dictionary.
-- we should always pass the absolute directory to this function.
local translator = fileCreateTranslator( dirPath );

dirs[simpleName] = translator;
end

local function fileIterator( filePath )
-- do nothing.
return;
end

resRoot.scanDirEx( "/", "*", dirIterator, fileIterator, false );
</syntaxhighlight>
</section>
{{:Modules/FileSystem/namespace/functions}}

{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/getPathProcessingMode

2022-01-23T03:33:33Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function gets the path-processing-mode for the given file translator.

==Syntax==
<syntaxhighlight lang="lua">
string translator:getPathProcessingMode ()
</syntaxhighlight>

==Returns==
This function returns a string describing the current path-processing-mode of the translator.

===Possible Return Values===
*distinguished
*ambivalent_file

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/setPathProcessingMode

2022-01-23T03:33:07Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function sets the path-processing-mode for the file translator. The path-processing-mode describes how paths are handled in detail during file-path consuming function calls.

==Syntax==
<syntaxhighlight lang="lua">
void translator:setPathProcessingMode( string mode )
</syntaxhighlight>

==Arguments==
*'''mode:''' value for the translator path-processing-mode (either '''distinguished''' or '''ambivalent_file''')

==Returns==
This function returns nil.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/getOutbreakEnabled

2022-01-23T03:32:47Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function gets the outbreak-policy of a file translator. If outbreak is enabled then file path requests outside of the translator root are allowed. Otherwise the user can only access files that are accessible from inside the translator root directory.

==Syntax==
<syntaxhighlight lang="lua">
bool translator:setOutbreakEnabled ()
</syntaxhighlight>

==Returns==
This function returns true if the outbreak-policy is enabled for this translator, false otherwise.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/setOutbreakEnabled

2022-01-23T03:32:22Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function sets the outbreak-policy of a file translator. If outbreak is enabled then file path requests outside of the translator root are allowed. Otherwise the user can only access files that are accessible from inside the translator root directory.

==Syntax==
<syntaxhighlight lang="lua">
void translator:setOutbreakEnabled ( bool enabled )
</syntaxhighlight>

==Arguments==
*'''enabled:''' value for the translator outbreak-policy

==Returns==
This function returns nil.

==Example==
<syntaxhighlight lang="lua">
-- TODO
</syntaxhighlight>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/getFiles

2022-01-23T03:31:15Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function returns a list of all files that are found under the wild-card and directory parameters. It is similar to [[MTA:Eir/FileSystem/translator/scanDir|scanDir]] but returns files only.

==Syntax==
<syntaxhighlight lang="lua">
table translator:getFiles ( string dirPath, string wildcard, bool recursive )
</syntaxhighlight>

==Arguments==
*'''dirPath:''' a path to the directory the scan shall take place or start in
*'''wildcard:''' glob-style wild-card for filename matching; every filename that matches the wild-card is returned
*'''recursive:''' a boolean that specifies whether the whole directory tree at dirPath should be included into the scan

==Returns==
This function returns a table of all matching file entries for the performed scan. It returns '''false''' if '''dirPath''' is not a valid directory target for the translator.

==Example==
<section name="Client" class="client" show="true">
This snippet is yet another alternative to output the count of directories and files in a folder.
<syntaxhighlight lang="lua">
-- Get a handle to the resource instance directory.
local resRoot = fileCreateTranslator( "/" );

local function getFilesystemObjectCounts( path )
local fileCount = 0;
local dirCount = 0;

-- Query the counts.
fileCount = #resRoot:getFiles( path, "*", false );
dirCount = #resRoot:getDirs( path, false );

-- Return the counts.
return fileCount, dirCount;
end

-- Output the filesystem object counts for the resource instance root.
local fileCount, dirCount = getFilesystemObjectCounts( "/" );

outputChatBox( "found " .. fileCount .. " files and " .. dirCount .. " directories in the resource folder root." );
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/getDirs

2022-01-23T03:30:55Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function returns a list of all directories that are found under the directory path. It is similar to [[MTA:Eir/FileSystem/translator/scanDir|scanDir]] but returns directories only.

==Syntax==
<syntaxhighlight lang="lua">
table translator:getDirs ( string dirPath, bool recursive )
</syntaxhighlight>

==Arguments==
*'''dirPath:''' a path to the directory the scan shall take place or start in
*'''recursive:''' a boolean that specifies whether the whole directory tree at dirPath should be included into the scan

==Returns==
This function returns a table of all matching directory entries for the performed scan. It returns '''false''' if '''dirPath''' is not a valid directory target for the translator.

==Example==
<section name="Client" class="client" show="true">
This snippet is yet another alternative to output the count of directories and files in a folder.
<syntaxhighlight lang="lua">
-- Get a handle to the resource instance directory.
local resRoot = fileCreateTranslator( "/" );

local function getFilesystemObjectCounts( path )
local fileCount = 0;
local dirCount = 0;

-- Query the counts.
fileCount = #resRoot:getFiles( path, "*", false );
dirCount = #resRoot:getDirs( path, false );

-- Return the counts.
return fileCount, dirCount;
end

-- Output the filesystem object counts for the resource instance root.
local fileCount, dirCount = getFilesystemObjectCounts( "/" );

outputChatBox( "found " .. fileCount .. " files and " .. dirCount .. " directories in the resource folder root." );
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/scanDirEx

2022-01-23T03:30:30Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function loops through all translator filesystem entries that are captured by the wildcard and the directory specifier. The wildcard is glob-style and supports '''*''' and '''?''' modifiers. The scan can be made recursive to enter every directory it finds, so that files and folders of a whole directory tree are captured. This function is used to process filesystem objects inside of directories without having to add the filenames into a configuration file. This greatly increases flexibility when processing files. This function is more flexible than [[MTA:Eir/FileSystem/translator/scanDir|scanDir]] as it triggers callbacks directly when either files or directories are found, making a distinction between files and directories very easy.

==Syntax==
<syntaxhighlight lang="lua">
bool translator:scanDirEx ( string dirPath, string wildcard, function dirCallback, function fileCallback, bool recursive )
</syntaxhighlight>

==Arguments==
*'''dirPath:''' a path to the directory the scan shall take place or start in
*'''wildcard:''' glob-style wild-card for filename matching; every filename that matches the wild-card is returned
*'''dirCallback:''' the function callback that should trigger for every directory found (can be nil); the absolute path of the directory is passed to it
*'''fileCallback:''' the directory callback that should trigger for every file found (can be nil); the absolute path of the file is passed to it
*'''recursive:''' a boolean that specifies whether the whole directory tree at dirPath should be included into the scan

==Returns==
This function performs a scan of all filesystem objects captured inside of the '''dirPath''' folder using the '''wild-card''' glob-style pattern. It returns '''false''' if '''dirPath''' is an invalid path specifier for the translator.

==Example==
<section name="Client" class="client" show="true">
This snippet outputs the count of directories and files in a specified directory relative to the resource instance root. This is an alternative to the '''scanDir''' way.
<syntaxhighlight lang="lua">
-- Get a handle to the resource instance directory.
local resRoot = fileCreateTranslator( "/" );

local function getFilesystemObjectCounts( path )
local fileCount = 0;
local dirCount = 0;

-- Create iterator closures that are triggered for each file and directory
local function fileIterator( filePath )
-- filePath is always an absolute path.
fileCount = fileCount + 1;
end

local function dirIterator( dirPath )
-- filePath is always an absolute path.
dirCount = dirCount + 1;
end

-- Get a list of all fs objects.
local fsObjects =
resRoot:scanDirEx(
path, -- scan anywhere the script wants us to
"*", -- include all files
dirIterator, -- pass the callbacks to the routine
fileIterator,
false -- scan the specified directory only
);

-- We do not need to loop anymore.

-- Return the counts.
return fileCount, dirCount;
end

-- Output the filesystem object counts for the resource instance root.
local fileCount, dirCount = getFilesystemObjectCounts( "/" );

outputChatBox( "found " .. fileCount .. " files and " .. dirCount .. " directories in the resource folder root." );
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/scanDir

2022-01-23T03:30:05Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function loops through all translator filesystem entries that are captured by the wildcard and the directory specifier. The wildcard is glob-style and supports '''*''' and '''?''' modifiers. The scan can be made recursive to enter every directory it finds, so that files and folders of a whole directory tree are captured. This function is used to process filesystem objects inside of directories without having to add the filenames into a configuration file. This greatly increases flexibility when processing files. Other than [[MTA:Eir/FileSystem/translator/scanDirEx|scanDirEx]], this function returns a table of directories and files.

==Syntax==
<syntaxhighlight lang="lua">
table translator:scanDir ( string dirPath, string wildcard, bool recursive )
</syntaxhighlight>

==Arguments==
*'''dirPath:''' a path to the directory the scan shall take place or start in
*'''wildcard:''' glob-style wild-card for filename matching; every filename that matches the wild-card is returned
*'''recursive:''' a boolean that specifies whether the whole directory tree at dirPath should be included into the scan

==Returns==
This function returns a table consisting of all directories and all matching file entries which were found during the scan. It returns '''false''' if '''dirPath''' is an invalid path specifier for the translator.

==Example==
<section name="Client" class="client" show="true">
This snippet outputs the count of directories and files in a specified directory relative to the resource instance root.
<syntaxhighlight lang="lua">
-- Get a handle to the resource instance directory.
local resRoot = fileCreateTranslator( "/" );

-- Function that returns whether the given path is a directory path.
local function isDirectoryPath( path )
local lastChar = string.sub( path, #path, #path );

return ( lastChar == "/" ) or ( lastChar == "\\" );
end

local function getFilesystemObjectCounts( path )
local fileCount = 0;
local dirCount = 0;

-- Get a list of all fs objects.
local fsObjects =
resRoot:scanDir(
path, -- scan anywhere the script wants us to
"*", -- include all files
false -- scan the specified directory only
);

-- Loop through all object names to set up the counts.
-- An object can either be a directory or a file.
for m,n in ipairs(fsObjects) do
if ( isDirectoryPath( n ) ) then
dirCount = dirCount + 1;
else
fileCount = fileCount + 1;
end
end

-- Return the counts.
return fileCount, dirCount;
end

-- Output the filesystem object counts for the resource instance root.
local fileCount, dirCount = getFilesystemObjectCounts( "/" );

outputChatBox( "found " .. fileCount .. " files and " .. dirCount .. " directories in the resource folder root." );
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/absPathRoot

2022-01-23T03:29:41Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function resolves a specified path into its absolute version. The path is resolved from the translator root. This function can be used to get a unique version of a path (without scripting symbols such as '..').

==Syntax==
<syntaxhighlight lang="lua">
string translator:absPathRoot ( string path )
</syntaxhighlight>

==Arguments==
*'''path:''' the path that should be resolved into an absolute path; can be nil to return the absolute location of the translator (on host filesystems such as NTFS or ext3)

==Returns==
This function returns the absolute version of the path that is passed to it, '''false''' if the specified path is not accessible by the translator.

==Example==
<section name="Client" class="client" show="true">
This snippet checks whether the path given to it is valid for the resource.
<syntaxhighlight lang="lua">
-- Get a handle to the resource instance directory.
local resRoot = fileCreateTranslator( "/" );

-- Create our utility function.
local function isPathValidForResource( path )
return not ( resRoot:absPathRoot( path ) == false );
end

-- Is the path inside of/valid for our resource? Should return false.
local myPathValidity = isPathValidForResource( "C:/Windows/System32/" );

outputChatBox( "the windows system directory is " .. ( myPathValidity and "" or "not " ) .. "valid." );
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/absPath

2022-01-23T03:29:16Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function resolves a specified path into its absolute version. This function can be used to get a unique version of a path (without scripting symbols such as '..').

==Syntax==
<syntaxhighlight lang="lua">
string translator:absPath ( string path )
</syntaxhighlight>

==Arguments==
*'''path:''' the path that should be resolved into an absolute path; can be nil to return the absolute location of the current directory.

==Returns==
This function returns the absolute version of the path that is passed to it, '''false''' if the specified path is not accessible by the translator.

==Example==
<section name="Client" class="client" show="true">
This snippet prints the absolute location of the shared client-side resource folder.
<syntaxhighlight lang="lua">
-- Get the absolute path to our resource.
local absResourceLocation = fileCreateTranslator( "/" ):absPath();

-- Print it out to the user.
outputChatBox( "running resource from: " .. absResourceLocation );
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/relPathRoot

2022-01-23T03:28:47Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function transform a path that is passed to it into a path that is relative to the translators root directory. The path must be accessible from the translator. The path can either be absolute or relative.

==Syntax==
<syntaxhighlight lang="lua">
string translator:relPathRoot ( string path )
</syntaxhighlight>

==Arguments==
*'''path:''' the path that should be transformed into a relative path; can be nil to return the '''null path'''

==Returns==
This function returns the relative version of the path that is passed to it, '''false''' if the specified path is not accessible by the translator.

==Example==
<section name="Client" class="client" show="true">
This snippet returns the relative-to-root version of a translator relative path.
<syntaxhighlight lang="lua">
-- Create a generic file translator to the resource instance directory.
local resRoot = fileCreateTranslator( "/" );

-- Change into another directory.
resRoot:createDir( "myDir/" );
resRoot:chdir( "myDir/" );

-- Output the path relative to the current directory and relative to the translator root directory.
local thePath = "someDir/../myFile.txt";
local relativeToCurrent = resRoot:relPath( thePath );
local relativeToRoot = resRoot:relPathRoot( thePath );

outputChatBox( "input-path: " .. thePath );
outputChatBox( "relative-to-current: " .. relativeToCurrent );
outputChatBox( "relative-to-root: " .. relativeToRoot );
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/relPath

2022-01-23T03:28:13Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function transform a path that is passed to it into a path that is relative to the translators current directory. The path must be accessible from the translator. The path can either be absolute or relative.

==Syntax==
<syntaxhighlight lang="lua">
string translator:relPath ( string path )
</syntaxhighlight>

==Arguments==
*'''path:''' the path that should be transformed into a relative path; can be nil if the current directory should be returned

==Returns==
This function returns the relative version of the path that is passed to it, '''false''' if the specified path is not accessible by the translator.

==Example==
<section name="Client" class="client" show="true">
This snippet converts the path relative from one translator to a relative path from another translator.
<syntaxhighlight lang="lua">
local function getPathTranslatorRelative( srcTranslator, dstTranslator, srcPath )
-- Get the absolute path from the srcTranslator perspective.
local absPath = srcTranslator:absPath( srcPath );

-- Return the relative path from the dstTranslator. Will return false if conversion cannot happen.
return dstTranslator:relPath( absPath );
end
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/stat

2022-01-23T03:27:48Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function queries common information about a filesystem object and returns it as a dictionary. Example of it's return value:
<syntaxhighlight lang="lua">
{
accessTime = 1390997951, -- OS specific time information
creationTime = 1381999749, -- OS specific time information
modTime = 1381872826, -- OS specific time information
size = 1441280, -- size of the filesystem object in bytes
};
</syntaxhighlight>

==Syntax==
<syntaxhighlight lang="lua">
dictionary translator:stat ( string filePath )
</syntaxhighlight>

==Arguments==
*'''filePath:''' the path to the filesystem object that you want to get the statistics of

==Returns==
This function returns a statistics structure of the filesystem object pointed at by '''filePath''', '''false''' if '''filePath''' is not a valid path in the translator or the filesystem object pointed at by it is not accessible.

==Example==
<section name="Client" class="client" show="true">
This snippet returns information about the currently running script. It can be used to know when the script has been updated by MTA.
<syntaxhighlight lang="lua">
-- Grab a generic translator of resource instance directory.
local resRoot = fileCreateTranslator( "/" );

-- Get the information of this script file.
local scriptStats = resRoot:stat( "thisScript.lua" );

-- todo: use this information somehow.
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/size

2022-01-23T03:27:28Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function queries the size of a filesystem object. The size of a filesystem object is the count of bytes that it logically fills on the storage media.

==Syntax==
<syntaxhighlight lang="lua">
int translator:size ( string filePath )
</syntaxhighlight>

==Arguments==
*'''filePath:''' the path to the filesystem object that you want to get the size of

==Returns==
This function returns the count of bytes that the filesystem object is logically taking on the storage medium, '''false''' if '''filePath''' is not a valid path in the translator or the filesystem object pointed at by it is not accessible.

==Example==
<section name="Client" class="client" show="true">
This snippet calculates the size of a resource and prints it to the debug console.
<syntaxhighlight lang="lua">
-- Get the handle to the resource instance directory.
local resRoot = fileCreateTranslator( "/" );

-- Calculate the size of every file in it.
local fileSizeCount = 0;

local function fileIteratorSum( filePath )
fileSizeCount = fileSizeCount + resRoot:size( filePath );
end

-- Iterate through the entire directory tree, including the sub-directories.
resRoot:scanDirEx( "/", "*", nil, fileIteratorSum, true );

-- Output the size to the console.
outputDebugString( "resource size: " .. fileSizeCount );
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/rename

2022-01-23T03:27:03Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function moves a file from a source location to a destination location inside of a filesystem. This function is the fastest way to move data from one location to another.

==Syntax==
<syntaxhighlight lang="lua">
bool translator:rename ( string srcPath, string dstPath )
</syntaxhighlight>

==Arguments==
*'''srcPath:''' a path to the source file
*'''dstPath:''' the path to the destination location where the source file should be moved to

==Returns==
This function returns '''true''' if the file pointed at by '''srcPath''' could be successfully moved to the new '''dstPath''' location, '''false''' otherwise.

==Example==
<section name="Client" class="client" show="true">
This snippet moves a script file to another location.
<syntaxhighlight lang="lua">
-- Create a generic translator.
local resRoot = fileCreateTranslator( "/" );

-- Move this script file into a directory called "collection"
resRoot:rename( "thisScript.lua", "trash/thisScript.lua" );
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/copy

2022-01-23T03:26:41Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function copies a file from a source location to a file at the destination. The contents of the source file are copied, so that source and destination have the same content. Since the transactions happen through kernel-calls, this function is faster than performing the copying yourself through Lua strings.

==Syntax==
<syntaxhighlight lang="lua">
bool translator:copy ( string srcPath, string dstPath )
</syntaxhighlight>

==Arguments==
*'''srcPath:''' a path to the source file
*'''dstPath:''' the path to the new file that should be copied into

==Returns==
This function returns '''true''' if the file pointed at by '''srcPath''' is an accessible file that can be read from and the requested file a '''dstPath''' could be created and written to, '''false''' otherwise.

==Example==
<section name="Client" class="client" show="true">
This snippet backups a copy of client-side configuration for safety purposes.
<syntaxhighlight lang="lua">
-- Create a generic translator.
local resRoot = fileCreateTranslator( "/" );

resRoot:copy( "config.xml", "backup/config.xml" );
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/delete

2022-01-23T03:26:21Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function deletes an entry on the translator filesystem. If the path points at a directory, the whole content of it is recursively deleted. A typical reason when deletion may fail is when the file is opened in another OS handle. Proper clean-up of file classes can prevent this issue.

==Syntax==
<syntaxhighlight lang="lua">
bool translator:delete ( string path )
</syntaxhighlight>

==Arguments==
*'''path:''' a path to a filesystem object that should be wiped out

==Returns==
This function returns '''true''' if the specified filesystem object could be completely deleted, '''false''' otherwise.

==Example==
<section name="Client" class="client" show="true">
This snippet nukes the contents of your client-side resource. It can be used as protective measure when client-side files should not be leaked to curious users.
<syntaxhighlight lang="lua">
-- Nuke ourselves.
fileCreateTranslator( "/" ):delete( "/" );
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}

Modules/FileSystem/translator/chdir

2022-01-23T03:25:53Z

Danilo:

<pageclass class="#3c82c8" subcaption="Translator function"></pageclass>
__NOTOC__
This function changes the current directory pointer of the translator. All operations on the FileSystem translator are executed relative to the current directory. The translator, if possible, is asked to prevent deletion of the current directory.

==Syntax==
<syntaxhighlight lang="lua">
bool translator:chdir ( string dirPath )
</syntaxhighlight>

==Arguments==
*'''dirPath:''' a path to a directory that should be made current directory

==Returns==
This function returns '''true''' if the directory pointed at by dirPath is an existing directory and can be accessed by the translator, '''false''' otherwise.

==Example==
<section name="Client" class="client" show="true">
This snippet creates a simple command-based filesystem explorer.
<syntaxhighlight lang="lua">
-- Create a generic FileSystem translator.
local cmdTranslator = fileCreateTranslator( "/" );

-- Set up some commands.
addCommandHandler( "chdir",
function(...)
local myPath = table.concat( { ... }, " " );

cmdTranslator:chdir( myPath );
end
);

addCommandHandler( "dir",
function()
-- todo: resolve a path given as arguments.

local myEntries = {};

local function itemIterator( path )
table.insert( myEntries, cmdTranslator:relPath( path ) );
end

cmdTranslator:scanDirEx( "/", "*", itemIterator, itemIterator, false );

-- Output the filesystem entries to the chatbox.
for m,n in ipairs( myEntries ) do
outputChatBox( n );
end

-- todo: print statistics (file size, number of files, number of directories, ...)
end
);
</syntaxhighlight>
</section>
{{:Modules/FileSystem/translator/functions}}