Multi Theft Auto: Wiki - User contributions [en]

SetCameraFieldOfView

2025-07-24T01:08:59Z

Botder:

__NOTOC__
{{client function}}
{{New feature/item|3.0151|1.5.1|7397|This function sets the field of view of the ''dynamic camera'' - this is the field of view of the ''non-fixed camera'' - yes, the camera that the user can control whilst on foot or in a vehicle. The higher the field of view angle, the more you will be able to see to your sides.}}
{{Note|This function omits (but doesn't override) the user game option in '''''Settings -> Video -> FOV'''''}}
{{Note|It doesn't affect the FOV for the following camera modes: 1) Player aiming 2) Vehicle front bumper camera 3) Fixed camera}}
==Syntax==
<syntaxhighlight lang="lua">
bool setCameraFieldOfView ( string cameraMode, float fieldOfView [, bool instant = false ] )
</syntaxhighlight>
{{OOP||Camera.setFieldOfView||getCameraFieldOfView}}

===Required Arguments===
'''Note:''' after 100, some unexpected things may happen to the camera, particularly in vehicles, use carefully!
*'''cameraMode:''' the camera mode to set the field of view of:
** "player": whilst walking/running
** "vehicle": whilst in vehicle
** "vehicle_max": the max the field of view can go to when the vehicle is moving at a high speed (must be higher than "vehicle")
*'''fieldOfView:''' The field of view angle, 0 to 179.

===Optional arguments===
{{OptionalArg}}
{{New feature/item|3.0161|1.6.0|23300|
*'''instant''': If set to ''true'', the value is applied immediately, without delay (does not work with "vehicle_max").
}}

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

==Example==
In this example, the field of view for 'player walking/running' is set to 20 when the player joins.

<syntaxhighlight lang="lua">
function setCameraFOVOnResStart()
setCameraFieldOfView("player",20)
end
addEventHandler("onClientResourceStart", resourceRoot, setCameraFOVOnResStart)</syntaxhighlight>

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

[[hu:setCameraFieldOfView]]
[[RO:setCameraFieldOfView]]

Template:File functions

2025-07-23T18:58:51Z

Botder:

<ul>
<li>[[fileClose]]</li>
<li>[[fileCopy]]</li>
<li>[[fileCreate]]</li>
<li>[[fileDelete]]</li>
<li>[[fileExists]]</li>
<li>[[fileFlush]]</li>
{{New items|3.0161|1.6.0|
<li>[[fileGetContents]]</li>
|21938}}
{{New items|3.0161|1.6.0|
<li>[[fileGetHash]]</li>
|23289}}
<li>[[fileGetPath]]</li>
<li>[[fileGetPos]]</li>
<li>[[fileGetSize]]</li>
<li>[[fileIsEOF]]</li>
<li>[[fileOpen]]</li>
<li>[[fileRead]]</li>
<li>[[fileRename]]</li>
<li>[[fileSetPos]]</li>
<li>[[fileWrite]]</li>
</ul>

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

Template:File functions

2025-07-23T18:58:05Z

Botder:

<ul>
<li>[[fileClose]]</li>
<li>[[fileCopy]]</li>
<li>[[fileCreate]]</li>
<li>[[fileDelete]]</li>
<li>[[fileExists]]</li>
<li>[[fileFlush]]</li>
{{New items|3.0161|1.6.0|
<li>[[fileGetContents]]</li>
|21938}}
<li>[[fileGetPath]]</li>
<li>[[fileGetPos]]</li>
<li>[[fileGetSize]]</li>
{{New items|3.0161|1.6.0|
<li>[[fileGetHash]]</li>
|23289}}
<li>[[fileIsEOF]]</li>
<li>[[fileOpen]]</li>
<li>[[fileRead]]</li>
<li>[[fileRename]]</li>
<li>[[fileSetPos]]</li>
<li>[[fileWrite]]</li>
</ul>

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

FileGetHash

2025-07-23T18:48:35Z

Botder: Created page with "__NOTOC__ {{Server client function}} {{Added feature/item|1.6.1|1.6.0|23289| This function returns a hash of the entire file in the specified algorithm. This function ''does not'' move the file pointer/position. Beware though, there will always be a minuscule period of time between checking the hash and loading the contents of the file, which can be abused by a potential attacker to modify the contents. }} ==Syntax== <syntaxhighlight lang="lua"> nil|string fileGetHash..."

__NOTOC__
{{Server client function}}

{{Added feature/item|1.6.1|1.6.0|23289|
This function returns a hash of the entire file in the specified algorithm. This function ''does not'' move the file pointer/position. Beware though, there will always be a minuscule period of time between checking the hash and loading the contents of the file, which can be abused by a potential attacker to modify the contents.
}}

==Syntax==
<syntaxhighlight lang="lua">
nil|string fileGetHash ( file theFile, string algorithm [, table options ] )
</syntaxhighlight>
{{OOP||[[file]]:getHash}}

===Required Arguments===
*'''theFile:''' A handle to the file you wish to get the hash from. Use [[fileOpen]] to obtain this handle.
*'''algorithm''': A string which must be one of these: "md5", "sha1", "sha224", "sha256", "sha384", "sha512", "hmac"

===Optional arguments===
{{OptionalArg}}
*'''options''': A table with options and other necessary data for the algorithm, as detailed below.

===Options for each algorithm===
* ''hmac'' ([https://en.wikipedia.org/wiki/HMAC HMAC])
** '''key''': a key to encode the input with.
** '''algorithm''': a string which must be one of these: "md5", "sha1", "sha224", "sha256", "sha384", "sha512".

===Returns===
Returns the hash of the entire file on success, and ''nil'' on failure.

==Example==
This example opens the code.lua file, computes the hash with every algorithm, and then displays them.
<syntaxhighlight lang="lua">
local handle = fileOpen("code.lua", true)
local hashMD5 = fileGetHash(handle, "md5")
local hashSHA1 = fileGetHash(handle, "sha1")
local hashSHA224 = fileGetHash(handle, "sha224")
local hashSHA256 = fileGetHash(handle, "sha256")
local hashSHA384 = fileGetHash(handle, "sha384")
local hashSHA512 = fileGetHash(handle, "sha512")
local hashHMAC = fileGetHash(handle, "hmac", { algorithm = "sha256", key = "blue apple tree" })
fileClose(handle)

iprint("MD5", hashMD5)
iprint("SHA1", hashSHA1)
iprint("SHA224", hashSHA224)
iprint("SHA256", hashSHA256)
iprint("SHA384", hashSHA384)
iprint("SHA512", hashSHA512)
iprint("HMAC-SHA256", hashHMAC )
</syntaxhighlight>

==See Also==
{{File functions}}

Lua compilation API

2025-05-26T18:44:34Z

Botder:

This page is a guide for Lua compilation API.

==Syntax==
<syntaxhighlight>
POST "https://luac.mtasa.com/index.php"
</syntaxhighlight>

==Parameters==
*'''luasource:''' type '''file''' the file content
*'''compile:''' type '''value''' set to 1 to enable compilation
*'''debug:''' type '''value''' set to 1 to enable debug information
*'''obfuscate:''' type '''value'''
**Set to 1 to enable some obfuscation
**Set to 2 to enable more obfuscation (From 1.5.2-9.07903)
**Set to 3 to enable even more obfuscation (From 1.5.6-9.18728)

==Examples==
===Linux example using curl===
<syntaxhighlight lang="bash">
FROM="example.lua"
TO="compiled.lua"
curl -s -X POST -F compile=1 -F debug=0 -F obfuscate=3 -F luasource=@$FROM https://luac.mtasa.com/ > $TO
</syntaxhighlight>
===Linux example using luac replacement===
<syntaxhighlight lang="bash">
luac_mta -e3 -o compiled.lua example.lua
if [ $? -ne 0 ]; then
echo "Error"
fi
</syntaxhighlight>
Need luac_mta (R13 2019-07-12) for [//luac.mtasa.com/files/linux/x86/luac_mta Linux 32 bit] or [//luac.mtasa.com/files/linux/x64/luac_mta Linux 64 bit]

===Windows batch file example using curl===
<syntaxhighlight lang="batch">
set FROM="example.lua"
set TO="compiled.lua"
curl.exe -s -X POST -F compile=1 -F debug=0 -F obfuscate=3 -F luasource=@%FROM% https://luac.mtasa.com/ > %TO%
</syntaxhighlight>
Get [https://curl.se/windows/latest.cgi?p=win64-mingw.zip curl for win64]
(Original from https://curl.haxx.se/download.html)

===Windows example using luac.exe replacement===
<syntaxhighlight lang="batch">
luac_mta.exe -e3 -o compiled.lua example.lua
IF NOT ERRORLEVEL 1 goto lp1
echo "Error"
:lp1
</syntaxhighlight>
Get [//luac.mtasa.com/files/windows/x86/luac_mta.exe luac_mta.exe] (R12 2019-07-12) '''only x86'''
===Lua example===
<syntaxhighlight lang="lua">
-- This example allows you to compile all resource scripts by using /compilelua command.

local compileEnabled = 1
local debugLevel = 0
local obfuscateLevel = 3
local apiCodes = {
["ERROR Nothing to do - Please select compile and/or obfuscate"] = true,
["ERROR Could not compile file"] = true,
["ERROR Could not read file"] = true,
["ERROR Already compiled"] = true,
["ERROR Already encrypted"] = true,
}

local function loadScriptsFromMeta()
local metaFile = xmlLoadFile("meta.xml")

if not metaFile then
outputDebugString("[LUAC]: Failed to load scripts from meta.", 4, 255, 127, 0)

return false
end

local metaChildren = xmlNodeGetChildren(metaFile)
local scriptsTable = {}

for nodeID = 1, #metaChildren do
local metaNode = metaChildren[nodeID]
local fileSrc = xmlNodeGetAttribute(metaNode, "src")

if fileSrc then
local luaScript = string.find(fileSrc, ".lua")

if luaScript then
scriptsTable[#scriptsTable + 1] = fileSrc
end
end
end

xmlUnloadFile(metaFile)

return scriptsTable
end

local function loadResourceScript(pPath)
local scriptExists = fileExists(pPath)

if not scriptExists then
outputDebugString("[LUAC]: '"..pPath.."' doesn't exists.", 4, 255, 127, 0)

return false
end

local scriptHandler = fileOpen(pPath)

if not scriptHandler then
outputDebugString("[LUAC]: '"..pPath.."' failed to open.", 4, 255, 127, 0)

return false
end

local scriptSize = fileGetSize(scriptHandler)
local scriptRaw = fileRead(scriptHandler, scriptSize)

fileClose(scriptHandler)

return scriptRaw
end

local function onScriptCompile(pCompiledLUA, pErrors, pScript)
local compileSuccess = pErrors == 0

if not compileSuccess then
outputDebugString("[LUAC]: '"..pScript.."' failed to compile.", 4, 255, 127, 0)

return false
end

local compileError = apiCodes[pCompiledLUA]

if compileError then
outputDebugString("[LUAC]: '"..pScript.."' failed to compile - "..pCompiledLUA, 4, 255, 127, 0)

return false
end

local compiledScript = fileCreate("luac/"..pScript)

if not compiledScript then
outputDebugString("[LUAC]: '"..pScript.."' failed to create.", 4, 255, 127, 0)

return false
end

fileWrite(compiledScript, pCompiledLUA)
fileClose(compiledScript)

outputDebugString("[LUAC]: '"..pScript.."' compiled successfully.", 4, 255, 127, 0)

return true
end

function compileLuaScripts(pPlayer)
local fetchURL = string.format("https://luac.mtasa.com/?compile=%i&debug=%i&obfuscate=%i", compileEnabled, debugLevel, obfuscateLevel)
local resourceScripts = loadScriptsFromMeta()
local postData = true

for scriptID = 1, #resourceScripts do
local scriptPath = resourceScripts[scriptID]
local scriptRaw = loadResourceScript(scriptPath)

fetchRemote(fetchURL, onScriptCompile, scriptRaw, postData, scriptPath)
end
end
addCommandHandler("compilelua", compileLuaScripts)
</syntaxhighlight>

===Python example===
<syntaxhighlight lang="python">
import requests

url_raw = 'luac.mtasa.com'
url = f'https://{url_raw}'
url_file = f'{url}/index.php'

newLine = '\r\n'
boundary = '------WebKitFormBoundary'
boundaryLine = f'{boundary}{newLine}'

headers = {
'Host': url_raw,
'Origin': url,
'Referer': url_file,
'Content-Type': f'multipart/form-data; boundary={boundary[2:]}',
}

fileContent = 'print("Hello, World!")'
fileName = 'main.lua'
docompile = 1
obfuscateLevel = 3
debug = 1

def req() -> requests.Response:
payload = [
[
f'Content-Disposition: form-data; name="luasource"; filename="{fileName}"'.encode('utf-8'),
b'Content-Type: application/octet-stream',
f'{newLine}{fileContent}'.encode('utf-8')
],
[
b'Content-Disposition: form-data; name="compile"',
f'{newLine}{docompile}'.encode('utf-8')
],
[
b'Content-Disposition: form-data; name="obfuscate"',
f'{newLine}{obfuscateLevel}'.encode('utf-8')
],
[
b'Content-Disposition: form-data; name="debug"',
f'{newLine}{debug}'.encode('utf-8')
],
[
b'Content-Disposition: form-data; name="Submit"',
f'{newLine}Submit'.encode('utf-8')
]
]

data = boundaryLine
for c in payload:
for cc in c:
data += cc.decode('utf-8') + '\r\n'
data += boundaryLine

return requests.post(url_file, headers=headers, data=data)

if __name__ == '__main__':
fileName = input('Filename (with extension): ')
with open(fileName, 'r+') as f:
fileContent = f.read()
obfuscateLevel = int(input('Obfuscate level [0-3]: '))
_docompile = input('Compile [true/false]: ').lower()
if _docompile == 'true' or _docompile == 't' or _docompile == '1':
docompile = '1'
else:
docompile = '0'
_debug = input('Debug [true/false]: ').lower()
if _debug == 'true' or _debug == 't' or _debug == '1':
debug = '1'
else:
debug = '0'

try:
content = req().content
if content == b'ERROR Could not compile file':
print('Could not compile file!')
exit(1)

with open(fileName, 'wb+') as f:
f.write(content)
print('Done!')
except Exception as e:
print('An error occured:', e)
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|2014-08-10|''encrypt'' has been renamed to ''obfuscate''. ''blockdecompile'' has been removed.}}

Lua compilation API

2025-05-26T18:32:49Z

Botder:

This page is a guide for Lua compilation API.

==Syntax==
<syntaxhighlight>
POST "http://luac.mtasa.com/index.php"
</syntaxhighlight>

==Parameters==
*'''luasource:''' type '''file''' the file content
*'''compile:''' type '''value''' set to 1 to enable compilation
*'''debug:''' type '''value''' set to 1 to enable debug information
*'''obfuscate:''' type '''value'''
**Set to 1 to enable some obfuscation
**Set to 2 to enable more obfuscation (From 1.5.2-9.07903)
**Set to 3 to enable even more obfuscation (From 1.5.6-9.18728)

==Examples==
===Linux example using curl===
<syntaxhighlight lang="bash">
FROM="example.lua"
TO="compiled.lua"
curl -s -X POST -F compile=1 -F debug=0 -F obfuscate=3 -F luasource=@$FROM http://luac.mtasa.com/ > $TO
</syntaxhighlight>
===Linux example using luac replacement===
<syntaxhighlight lang="bash">
luac_mta -e3 -o compiled.lua example.lua
if [ $? -ne 0 ]; then
echo "Error"
fi
</syntaxhighlight>
Need luac_mta (R13 2019-07-12) for [//luac.mtasa.com/files/linux/x86/luac_mta Linux 32 bit] or [//luac.mtasa.com/files/linux/x64/luac_mta Linux 64 bit]

===Windows batch file example using curl===
<syntaxhighlight lang="batch">
set FROM="example.lua"
set TO="compiled.lua"
curl.exe -s -X POST -F compile=1 -F debug=0 -F obfuscate=3 -F luasource=@%FROM% http://luac.mtasa.com/ > %TO%
</syntaxhighlight>
Get [https://curl.se/windows/latest.cgi?p=win64-mingw.zip curl for win64]
(Original from http://curl.haxx.se/download.html)

===Windows example using luac.exe replacement===
<syntaxhighlight lang="batch">
luac_mta.exe -e3 -o compiled.lua example.lua
IF NOT ERRORLEVEL 1 goto lp1
echo "Error"
:lp1
</syntaxhighlight>
Get [//luac.mtasa.com/files/windows/x86/luac_mta.exe luac_mta.exe] (R12 2019-07-12) '''only x86'''
===Lua example===
<syntaxhighlight lang="lua">
-- This example allows you to compile all resource scripts by using /compilelua command.

local compileEnabled = 1
local debugLevel = 0
local obfuscateLevel = 3
local apiCodes = {
["ERROR Nothing to do - Please select compile and/or obfuscate"] = true,
["ERROR Could not compile file"] = true,
["ERROR Could not read file"] = true,
["ERROR Already compiled"] = true,
["ERROR Already encrypted"] = true,
}

local function loadScriptsFromMeta()
local metaFile = xmlLoadFile("meta.xml")

if not metaFile then
outputDebugString("[LUAC]: Failed to load scripts from meta.", 4, 255, 127, 0)

return false
end

local metaChildren = xmlNodeGetChildren(metaFile)
local scriptsTable = {}

for nodeID = 1, #metaChildren do
local metaNode = metaChildren[nodeID]
local fileSrc = xmlNodeGetAttribute(metaNode, "src")

if fileSrc then
local luaScript = string.find(fileSrc, ".lua")

if luaScript then
scriptsTable[#scriptsTable + 1] = fileSrc
end
end
end

xmlUnloadFile(metaFile)

return scriptsTable
end

local function loadResourceScript(pPath)
local scriptExists = fileExists(pPath)

if not scriptExists then
outputDebugString("[LUAC]: '"..pPath.."' doesn't exists.", 4, 255, 127, 0)

return false
end

local scriptHandler = fileOpen(pPath)

if not scriptHandler then
outputDebugString("[LUAC]: '"..pPath.."' failed to open.", 4, 255, 127, 0)

return false
end

local scriptSize = fileGetSize(scriptHandler)
local scriptRaw = fileRead(scriptHandler, scriptSize)

fileClose(scriptHandler)

return scriptRaw
end

local function onScriptCompile(pCompiledLUA, pErrors, pScript)
local compileSuccess = pErrors == 0

if not compileSuccess then
outputDebugString("[LUAC]: '"..pScript.."' failed to compile.", 4, 255, 127, 0)

return false
end

local compileError = apiCodes[pCompiledLUA]

if compileError then
outputDebugString("[LUAC]: '"..pScript.."' failed to compile - "..pCompiledLUA, 4, 255, 127, 0)

return false
end

local compiledScript = fileCreate("luac/"..pScript)

if not compiledScript then
outputDebugString("[LUAC]: '"..pScript.."' failed to create.", 4, 255, 127, 0)

return false
end

fileWrite(compiledScript, pCompiledLUA)
fileClose(compiledScript)

outputDebugString("[LUAC]: '"..pScript.."' compiled successfully.", 4, 255, 127, 0)

return true
end

function compileLuaScripts(pPlayer)
local fetchURL = string.format("https://luac.mtasa.com/?compile=%i&debug=%i&obfuscate=%i", compileEnabled, debugLevel, obfuscateLevel)
local resourceScripts = loadScriptsFromMeta()
local postData = true

for scriptID = 1, #resourceScripts do
local scriptPath = resourceScripts[scriptID]
local scriptRaw = loadResourceScript(scriptPath)

fetchRemote(fetchURL, onScriptCompile, scriptRaw, postData, scriptPath)
end
end
addCommandHandler("compilelua", compileLuaScripts)
</syntaxhighlight>

===Python example===
<syntaxhighlight lang="python">
import requests

url_raw = 'luac.mtasa.com'
url = f'https://{url_raw}'
url_file = f'{url}/index.php'

newLine = '\r\n'
boundary = '------WebKitFormBoundary'
boundaryLine = f'{boundary}{newLine}'

headers = {
'Host': url_raw,
'Origin': url,
'Referer': url_file,
'Content-Type': f'multipart/form-data; boundary={boundary[2:]}',
}

fileContent = 'print("Hello, World!")'
fileName = 'main.lua'
docompile = 1
obfuscateLevel = 3
debug = 1

def req() -> requests.Response:
payload = [
[
f'Content-Disposition: form-data; name="luasource"; filename="{fileName}"'.encode('utf-8'),
b'Content-Type: application/octet-stream',
f'{newLine}{fileContent}'.encode('utf-8')
],
[
b'Content-Disposition: form-data; name="compile"',
f'{newLine}{docompile}'.encode('utf-8')
],
[
b'Content-Disposition: form-data; name="obfuscate"',
f'{newLine}{obfuscateLevel}'.encode('utf-8')
],
[
b'Content-Disposition: form-data; name="debug"',
f'{newLine}{debug}'.encode('utf-8')
],
[
b'Content-Disposition: form-data; name="Submit"',
f'{newLine}Submit'.encode('utf-8')
]
]

data = boundaryLine
for c in payload:
for cc in c:
data += cc.decode('utf-8') + '\r\n'
data += boundaryLine

return requests.post(url_file, headers=headers, data=data)

if __name__ == '__main__':
fileName = input('Filename (with extension): ')
with open(fileName, 'r+') as f:
fileContent = f.read()
obfuscateLevel = int(input('Obfuscate level [0-3]: '))
_docompile = input('Compile [true/false]: ').lower()
if _docompile == 'true' or _docompile == 't' or _docompile == '1':
docompile = '1'
else:
docompile = '0'
_debug = input('Debug [true/false]: ').lower()
if _debug == 'true' or _debug == 't' or _debug == '1':
debug = '1'
else:
debug = '0'

try:
content = req().content
if content == b'ERROR Could not compile file':
print('Could not compile file!')
exit(1)

with open(fileName, 'wb+') as f:
f.write(content)
print('Done!')
except Exception as e:
print('An error occured:', e)
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|2014-08-10|''encrypt'' has been renamed to ''obfuscate''. ''blockdecompile'' has been removed.}}

GetServerIp

2025-01-08T20:07:57Z

Botder:

__NOTOC__
{{Client function}}
{{New feature/item|3.0161|1.6.0|22890|This function returns the IP of the server the client is currently connected to.}}
{{Note|On server-side there is the [[getServerIpFromMasterServer]] function, which might return the server IP under certain conditions.You should consider using a third-party service via [[fetchServerIp]] ''(not an MTA function)'' if the previous function is unreliable for you.}}

==Syntax==
<syntaxhighlight lang="lua">
string getServerIp ( [ bool includePort = false ] )
</syntaxhighlight>

===Optional Arguments===
*'''includePort:''' If set to ''true'', the string will include the port of the server at the end of the string, after a colon (:) character.

===Returns===
A string containing the remote address of the server the client is currently connected to.

==Example==
This example creates a console command that outputs the server's IP to the chatbox.
<syntaxhighlight lang="lua">
function outputServerIp()
outputChatBox("You are currently connected to ".. getServerIp(true))
end

addCommandHandler("serverIp", outputServerIp)
</syntaxhighlight>

==See Also==
{{Utility_functions|client}}

GetServerIp

2025-01-08T20:05:16Z

Botder:

__NOTOC__
{{Client function}}
{{New feature/item|3.0161|1.6.0|22890|This function returns the IP of the server the client is currently connected to.}}
{{Note|On server-side there is the [[getServerIpFromMasterServer]] function, which might return the server IP under certain conditions.You should consider using a third-party service via [[fetchServerIp]] ''(not an MTA function)'' if the previous function is unreliable for you.}}

==Syntax==
<syntaxhighlight lang="lua">
string getServerIp ( [ bool includePort = false ] )
</syntaxhighlight>

==Example==
This example creates a console command that outputs the server's IP to the chatbox.
<syntaxhighlight lang="lua">
function outputServerIp()
outputChatBox("You are currently connected to ".. getServerIp(true))
end

addCommandHandler("serverIp", outputServerIp)
</syntaxhighlight>

==See Also==
{{Utility_functions|client}}

FetchServerIp

2025-01-08T19:55:38Z

Botder: Created page with "{{Useful_Function}} <lowercasetitle/> __NOTOC__ This function returns the server ip as reported by a third-party service. ==Syntax== <syntaxhighlight lang="lua"> string fetchServerIp ( ) </syntaxhighlight> ==Code== <section name="Server" class="server" show="true"> <syntaxhighlight lang="lua"> SERVER_IP = "127.0.0.1" function fetchServerIp() return SERVER_IP end fetchRemote("http://checkip.dyndns.com/", function (response) if response ~= "ERROR" then..."

{{Useful_Function}}
<lowercasetitle/>
__NOTOC__
This function returns the server ip as reported by a third-party service.

==Syntax==
<syntaxhighlight lang="lua">
string fetchServerIp ( )
</syntaxhighlight>

==Code==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
SERVER_IP = "127.0.0.1"

function fetchServerIp()
return SERVER_IP
end

fetchRemote("http://checkip.dyndns.com/",
function (response)
if response ~= "ERROR" then
SERVER_IP = response:match("<body>Current IP Address: (.-)</body>") or "127.0.0.1"
end
end
)
</syntaxhighlight>
</section>

==Example==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
outputServerLog("Public server IP: " .. fetchServerIp())
</syntaxhighlight>
</section>

==See Also==
{{Useful_Functions}}

GetServerIp

2025-01-08T19:50:54Z

Botder: Removed redirect to GetServerConfigSetting#Example

{{Useful_Function}}
<lowercasetitle/>
__NOTOC__
This function gets the server ip.

==Syntax==
<syntaxhighlight lang="lua">string getServerIp ( )</syntaxhighlight>

==Code==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">

function getServerIp()
return getServerConfigSetting ("serverip")
end
</syntaxhighlight>
</section>
or
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
SERVER_IP = "127.0.0.1"

function getServerIp()
return SERVER_IP
end

fetchRemote("http://checkip.dyndns.com/",
function (response)
if response ~= "ERROR" then
SERVER_IP = response:match("<body>Current IP Address: (.-)</body>") or "127.0.0.1"
end
end
)
</syntaxhighlight>
</section>

==Example==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
outputServerLog("Public server IP: " .. getServerIp())
</syntaxhighlight>
</section>

==Credits==
* '''Author:''' MJNONFIK
* '''Edited by:''' CastiaL

==See Also==
{{Useful_Functions}}

GetServerIpFromMasterServer

2025-01-08T19:47:33Z

Botder:

__NOTOC__
{{Server function}}
{{New feature/item|3.0161|1.6.0|22890|This function returns the remote address as reported by the first master server that provides this value.}}
{{Note|It might take a while until the master server responds to the query sent out by the server, which in turn means that this function will not return any IP until the information has been received.}}
{{Note|On client-side there is the [[getServerIp]] function, in case you need the remote address of the currently connected server.}}
{{Note|If you want to retrieve the server IP address from the server configuration, then you should use <code>getServerConfigSetting("serverip")</code>, but this might yield only <code>"auto"</code> if the default value was used.}}

==Syntax==
<syntaxhighlight lang="lua">
string getServerIpFromMasterServer ( )
</syntaxhighlight>

===Returns===
A string containing the remote address of the server as reported, once it's available.

==Example==
This example creates a console command that outputs the server's IP to the chatbox.
<syntaxhighlight lang="lua">
function outputServerIp()
outputChatBox(getServerIpFromMasterServer())
end

addCommandHandler("serverIp", outputServerIp)
</syntaxhighlight>

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

GetServerIpFromMasterServer

2025-01-08T19:45:59Z

Botder: Created page with "__NOTOC__ {{Server function}} {{New feature/item|3.0161|1.6.0|22890|This function returns the remote address as reported by the first master server that provides this value.}} {{Note|It might take a while until the master server responds to the query sent out by the server, which in turn means that this function will not return any IP until the information has been received.}} {{Note|On client-side there is the getServerIp function, in case you need the remote addre..."

__NOTOC__
{{Server function}}
{{New feature/item|3.0161|1.6.0|22890|This function returns the remote address as reported by the first master server that provides this value.}}
{{Note|It might take a while until the master server responds to the query sent out by the server, which in turn means that this function will not return any IP until the information has been received.}}
{{Note|On client-side there is the [[getServerIp]] function, in case you need the remote address of the currently connected server.}}

==Syntax==
<syntaxhighlight lang="lua">
string getServerIpFromMasterServer ( )
</syntaxhighlight>

===Returns===
A string containing the remote address of the server as reported, once it's available.

==Example==
This example creates a console command that outputs the server's IP to the chatbox.
<syntaxhighlight lang="lua">
function outputServerIp()
outputChatBox(getServerIpFromMasterServer())
end

addCommandHandler("serverIp", outputServerIp)
</syntaxhighlight>

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

Template:Server functions

2025-01-08T19:35:23Z

Botder:

<ul>
<li>[[getMaxPlayers]]</li>
<li>[[getServerConfigSetting]]</li>
<li>[[getServerHttpPort]]</li>
{{New items|3.0161|1.6.0|
<li>[[getServerIpFromMasterServer]]</li>
|22890}}
<li>[[getServerName]]</li>
<li>[[getServerPassword]]</li>
<li>[[getServerPort]]</li>
<li>[[isGlitchEnabled]]</li>
<li>[[setGlitchEnabled]]</li>
<li>[[setMaxPlayers]]</li>
<li>[[setServerConfigSetting]]</li>
<li>[[setServerPassword]]</li>
<li>[[shutdown]]</li>
</ul>

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

Template:Utility functions

2025-01-08T19:33:08Z

Botder:

<includeonly>
<ul>
{{#if: {{{1|}}}
| {{#ifeq: {{lc:{{{1}}}}} | client
|

<li>[[createTrayNotification]]</li>
<li>[[downloadFile]]</li>
<li>[[getDevelopmentMode]]</li>
<li>[[getKeyboardLayout]]</li>
<li>[[getLocalization]]</li>
{{New items|3.0161|1.6.0|
<li>[[getServerIp]]</li>
|22890}}
<li>[[isShowCollisionsEnabled]]</li>
<li>[[isShowSoundEnabled]]</li>
<li>[[isTransferBoxAlwaysVisible]]</li>
<li>[[isTransferBoxVisible]]</li>
<li>[[isTrayNotificationEnabled]]</li>
<li>[[setClipboard]]</li>
<li>[[setDevelopmentMode]]</li>
<li>[[setTransferBoxVisible]]</li>
<li>[[setWindowFlashing]]</li>
<li>[[showCol]]</li>
<li>[[showSound]]</li>
| {{#ifeq: {{lc:{{{1}}}}} | server
|

<li>[[setServerConfigSetting]]</li>
<li>[[getServerConfigSetting]]</li>
}}
}}

<li style="list-style: none; margin-left: -1.6em;">'''Shared'''</li>
}}


<li>[[addDebugHook]]</li>
<li>[[base64Decode]]</li>
<li>[[base64Encode]]</li>
<li>[[debugSleep]]</li>
<li>[[decodeString]]</li>
<li>[[encodeString]]</li>
<li>[[fromJSON]]</li>
<li>[[generateKeyPair]]</li>
<li>[[getColorFromString]]</li>
<li>[[getDevelopmentMode]]</li>
<li>[[getDistanceBetweenPoints2D]]</li>
<li>[[getDistanceBetweenPoints3D]]</li>
<li>[[getEasingValue]]</li>
<li>[[getNetworkStats]]</li>
<li>[[getNetworkUsageData]]</li>
<li>[[getPerformanceStats]]</li>
<li>[[getRealTime]]</li>
<li>[[getTickCount]]</li>
<li>[[getTimerDetails]]</li>
<li>[[getTimers]]</li>
<li>[[getFPSLimit]]</li>
<li>[[getUserdataType]]</li>
<li>[[getVersion]]</li>
<li>[[gettok]]</li>
<li>[[isTransferBoxVisible]]</li>
<li>[[setTransferBoxVisible]]</li>
<li>[[hash]]</li>
<li>[[inspect]]</li>
<li>[[interpolateBetween]]</li>
<li>[[iprint]]</li>
<li>[[isOOPEnabled]]</li>
<li>[[isTimer]]</li>
{{New items|3.0161|1.6.0|
<li>[[isTimerPaused]]</li>
<li>[[setTimerPaused]]</li>
|22701}}
<li>[[killTimer]]</li>
<li>[[md5]]</li>
<li>[[passwordHash]]</li>
<li>[[passwordVerify]]</li>
<li>[[pregFind]]</li>
<li>[[pregMatch]]</li>
<li>[[pregReplace]]</li>
<li>[[removeDebugHook]]</li>
<li>[[resetTimer]]</li>
<li>[[setDevelopmentMode]]</li>
<li>[[setFPSLimit]]</li>
<li>[[setTimer]]</li>
<li>[[ref]]</li>
<li>[[deref]]</li>
<li>[[sha256]]</li>
<li>[[split]]</li>
<li>[[teaDecode]]</li>
<li>[[teaEncode]]</li>
<li>[[toJSON]]</li>
<li>[[tocolor]]</li>
<li>[[getProcessMemoryStats]]</li>
<li>[[utfChar]]</li>
<li>[[utfCode]]</li>
<li>[[utfLen]]</li>
<li>[[utfSeek]]</li>
<li>[[utfSub]]</li>
</ul>
{{Bit_functions}}
</includeonly>

<noinclude>
{{Functions list info}}
[[Category:Functions templates]]</noinclude>

Resource Web Access

2024-08-25T14:32:30Z

Botder: Add new-feature-item wrapper for router

The Multi Theft Auto Server provides a web interface that resources can use in a variety of ways. This document's purpose is to explain what these ways are and how to go about using them.
{{Note|If you are looking for a tutorial on how to use the in-game web browser and create websites using CEF, please visit [[CEF_Tutorial|CEF Tutorial]] instead.}}

==Overview==
There are three key parts that make up this system.
* '''Pages:''' The ability to serve any http items (specified the meta.xml) as a page or file.
* '''Calls:''' The ability to call any exported http functions (specified in the meta.xml).
{{New feature/item|3.0161|1.6.0|22639|* '''Router:''' Use a designated http function to route requests within a resource manually (overriding the two parts above).}}

==Pages==
===Specifying a file in the meta===
You can specify in your resource's meta file that certain files are accessible through the web server. To do this, you add a line:
<syntaxhighlight lang="xml">
<html src="filename.ext" />
</syntaxhighlight>
You can then access this file from your web browser by visiting: http://host:port/resourcename/filename.ext 
For example, on a locally hosted server using default http port with webmap started: http://127.0.0.1:22005/webmap/map.htm

===Binary files===
Despite the misleading name, files specified using the html node can be of any type. If they are binary files (like images, zip files) then you need to specify this in the meta file, by adding ''raw="true"'' to the ''html'' node. This means that the files are not preprocessed before being sent to the web browser.

For example:
<syntaxhighlight lang="xml">
<html src="image.gif" raw="true" />
</syntaxhighlight>

===Parsed files===
If a file is not specified in the metafile as "raw", then it is passed through a pre-processor before it is returned to the client. This pre-processor works much like PHP or ASP but uses Lua. You can embed standard MTA scripts within HTML pages, controlling the output. Almost all standard MTA functions work, plus a number of special [[Template:HTTP functions|HTTP Functions]], such as [[httpWrite]], a function that outputs text to the buffer.

For example:
<syntaxhighlight lang="html4strict">
<html>
<body>
This resource is called <* httpWrite( getResourceName(getThisResource()) ) *>
</body>
<html>
</syntaxhighlight>

There is a shorthand (in common with PHP and ASP) for this code, meaning that you can also write the above code as:

<syntaxhighlight lang="html4strict">
<html>
<body>
This resource is called <* = getResourceName(getThisResource()) *>
</body>
<html>
</syntaxhighlight>

Aside from HTTP functions, embedded Lua has access to the following environment variables that contain information about how the page was requested:
* table '''requestHeaders''': This is a table containing all the headers that were requested with the page. You can set returned headers using [[httpSetResponseHeader]].
* table '''form''': This is a table containing all the form data submitted to the page using HTTP POST combined with any variables passed in the querystring with HTTP GET.
* table '''cookies''': This is a table of all the cookies. You can modify cookies using [[httpSetResponseCookie]].
* string '''hostname''': This is a string containing the IP address or hostname that requested the page.
* string '''url''': This is the URL of the page.
* account '''user''': This is the account of the current user.
{{New feature/item|3.0159|1.5.8|20828|
* string '''requestBody''': This is the request body.
* string '''method''': This is the request method.
}}

It's important to note that parsed files are run in a separate virtual machine from the rest of your resource's code. As such, if you want to call a function in your resource's main code, you need to export the function and use the [[call]] function from your parsed file.

==Calls==
You can specify that certain exported functions in your resource are able to be called from the HTTP interface. All the SDKs (listed below) allow you to call these functions from a remote location.

To specify an exported http-accessible function, add the following to your meta.xml file:
<syntaxhighlight lang="xml">
<export function='functionName' http='true' />
</syntaxhighlight>

You can code your function just as you would any normal function, returning as many values as you want, including tables and resources and most important elements. You ''cannot'' however return other 'userdata' values such as [[xmlnode|xmlnodes]] or functions.

===Protocol===
{{Note|You don't need to know this unless you're writing your own HTTP request code. You can just use one of the [[#SDK|SDKs listed below]].}}

Calls are done by requesting ''<nowiki>http://<your IP>:<your port>/<resource_name>/call/<exported_function_name></nowiki>'' using HTTP POST. The body of the request should be a JSON array of the arguments for the function.

The request will return a JSON array of the value(s) returned from the function as the HTTP response.

The server supports HTTP Basic authentication and you can configure access via the ACL and the built-in accounts system.

===Calls from the HTTP web interface===
Using calls is probably easiest from the web interface and can be done almost seamlessly.

First, add this to your meta.xml file:
<syntaxhighlight lang="xml">
<include resource="ajax" />
</syntaxhighlight>

Secondly, add the following to the <head> section of the page you want to call from:
<syntaxhighlight lang="lua">
<* = exports.ajax:start(getResourceName(getThisResource())) *>
</syntaxhighlight>

Finally, you can create a javascript block on your page and call your functions almost as if they were local. The only difference is that the calls are asynchronous - you should specify a callback function as the last argument for your call. This is called when the function returns.

Here's a simple example.

'''meta.xml'''
<syntaxhighlight lang="xml">
<meta>
<include resource="ajax" />
<script src='code.lua' />
<html src='page.htm' default='true' />
<export function='showChatMessage' http='true' />
</meta>
</syntaxhighlight>

'''code.lua'''
<syntaxhighlight lang="lua">
function showChatMessage ( message )
outputChatBox ( message )
return 5;
end
</syntaxhighlight>

'''page.htm'''
<syntaxhighlight lang="html4strict">
<html>
<head>
<* = exports.ajax:start(getResourceName(getThisResource())) *>
<script type='text/javascript'>
function say() {
var message = document.getElementById('message')
showChatMessage ( message.value,
function ( number ) {
// the function has been called and returned something
message.value = "The function returned " + number;
}
);
}
</script>
</head>
<body>
<input type='text' id='message' /><input type='button' value='say' onclick='say();' />
</body>
</html>
</syntaxhighlight>

You can see (fairly complex) examples of how this can be done in the resources ''resourcebrowser'', ''resourcemanager'' and ''webadmin''.

==Router==
{{New feature/item|3.0161|1.6.0|22639|
A router is a function that overrides both the function call mechanism and basic web server functionality, to allow a scripter to personalize the routing and client-response for each resource separately. For example, this allows a scripter to write an '''api''' named resource with a router function, that can serve any sort of information in a RESTy fashion. You may also take this further, and name the resource '''v1''' (or '''v2'''...) for easy API versioning. You can spin up and down the different resources as you wish, and users of your API can continue using an older version this way.
}}

===How to setup a router function===
A router function has to be specified in the meta.xml (see example below). You can name the function however you like, there are no restrictions, as long as the function can be found in the global Lua scope in your scripts. '''Note:''' You can have only one router function.
<syntaxhighlight lang="xml">
<export function="httpRouter" http="true" router="true" />
</syntaxhighlight>

Then you have to specify the function in any Lua script:
<syntaxhighlight lang="lua">
function httpRouter(request)
return 200 -- see below for a more complex return value
end
</syntaxhighlight>

===Request===
This section describes all the fields, that can be found in the '''request''' table passed to the router function for every call. The descriptions below use the following example URL:

<code>http://127.0.0.1:22005/api/vehicles/123?meow=true</code> ('''api''' is the resource name)

{| class="prettytable" style="width:100%;text-align:left;"
|-
! Field || Type || Description
|-
| <code>account</code> || [[Account]] || An account that was used for this request (can be a [[isGuestAccount|guest account]]).
|-
| <code>method</code> || [[string]] || One of the following: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT, PATCH, *
|-
| <code>path</code> || [[string]] || The requested path within your resource: <code>"/vehicles/123"</code>
|-
| <code>absolute_path</code> || [[string]] || The absolute path from the URL: <code>"/api/vehicles/123?meow=true"</code>
|-
| <code>hostname</code> || [[string]] || The hostname of the web server: <code>"127.0.0.1"</code>
|-
| <code>port</code> || [[integer]] || The client port used by the web server: <code>56758</code> (can be anything, but never 22005)
|-
| <code>body</code> || [[string]] || The body portion of the request sent by the client
|-
| <code>query</code> || [[table]] || A key-value table (with [[string]] keys and values) with the path's query fields (only query)
|-
| <code>formData</code> || [[table]] || A key-value table (with [[string]] keys and values) with the request form data (both query and body fields)
|-
| <code>cookies</code> || [[table]] || A key-value table (with [[string]] keys and values) with the request cookies
|-
| <code>headers</code> || [[table]] || A key-value table (with [[string]] keys and values) with the request headers (like User-Agent)
|}

===Response===
This section describes all the possible variants, that can be returned by the router function. There are three variants in total:
* Return literally nothing: response will use http status code ''200'' and an empty body.
* Return an [[integer]]: response will convert the number to an http status code and use an empty body.
* Return a table: response will be filled with the fields from the table (defaults to http status code ''200'' and empty body, if not overriden by a table field).

====Response table fields====

{| class="prettytable" style="width:100%;text-align:left;"
|-
! Field || Type || Description
|-
| <code>status</code> || [[integer]] || A number that will be converted to an http status code.
|-
| <code>body</code> || [[string]] || A string that will be used for the response body.
|-
| <code>headers</code> || [[table]] || A key-value table (with [[string]] keys and values) that will be written to the header section of the response.
|-
| <code>cookies</code> || [[table]] || A table with simple [[string]] key and value entries, or any-type key with [[table]] values (key is not used), entries. Check the examples below, if it's unclear.
|}

===Examples===
<syntaxhighlight lang="lua">
function httpRouter(request)
-- HTTP status code 200 & empty body
end
</syntaxhighlight>

<syntaxhighlight lang="lua">
function httpRouter(request)
return 404 --< HTTP status code & empty body
end
</syntaxhighlight>

<syntaxhighlight lang="lua">
function httpRouter(request)
return {
status = 404,
body = "not found",
}
end
</syntaxhighlight>

<syntaxhighlight lang="lua">
function httpRouter(request)
return {
status = 505,
body = "foo",
cookies = {
foo = "1234",
{
name = "bar", -- Cookie name must always be a lowercase "name" key
value = "6666", -- Cookie value must always be a lowercase "value" key
Version = "2", -- Any other cookie field can use any case
}
},
headers = {
["content-type"] = "text/html",
["etag"] = "c561c68d0ba92bbeb8b0f612a9199f722e3a621a",
["access-control-allow-origin"] = "*",
["x-custom-header"] = "MTA server",
}
}
end
</syntaxhighlight>

==Securing the web interface==
The [[ACL]] has a number of rights that can affect what files can be accessed.
{{Deprecated feature|3.0139|1.3.1|
* general.http: If disabled, none of the HTTP files can be accessed (except by game clients)
** '''Important Note''': ''If 'general.http' is enabled, HTTP access to all resources (for that ACL) is enabled by default. To disable HTTP access you have to explicitly block access to resources that contain exported HTTP functions.''
** '''Important Note''': ''If 'general.http' is enabled on an ACL which has a user with no password (i.e. user.* or user.guest or user.http_guest), it is essential that you explicitly block access to resources that contain exported HTTP functions.''
* resource.'''ResourceName''': If disabled, none of the files in the resource can be accessed
* resource.'''ResourceName'''.file.'''FileName''': If disabled, the file named cannot be accessed
* resource.'''ResourceName'''.function.'''FunctionName''': If disabled, the function cannot be called
These work as with other ACL rights - you can disable them for normal users and just enable them for Admin users, or any other group of users you wish.
}}
{{New_feature|3.0139|1.3.1|
* '''resource.ResourceName.http''': If enabled, the resource will be accessible from http://server_ip:22005/ResourceName/
This works as with other ACL rights - You can enable it just for Admin users, or any other group of users you wish.
}}

==SDK==
There are a number of so-called 'SDKs' available that allow you to interface with the server from other programming languages. With these, you could (in theory) write whole gamemodes. In practice, this is probably a bad idea, but it is useful for statistics and administration. The PHP SDK is the most developed version. Feel free to modify or create your own SDKs - if you do please send us a copy.

* [[JavaSDK|Java SDK]]
* [[Javascript SDK]]
* [https://www.npmjs.com/package/mtasa Node.js SDK]
* [https://crates.io/crates/mta-sdk Rust SDK]
* [https://pypi.org/project/MTA-SDK-Python/ Python SDK]
* [[Perl SDK]]
* [[PHP SDK]]
* [[CSharp SDK|C# SDK]]

==See Also==
[[callRemote]] - Allows game servers to call functions on PHP pages (with the PHP SDK) and on other game servers.
[[Category:Scripting Concepts]]

[[en:Resource Web Access]]
[[fr:Ressource Acces Internet]]
[[hu:Resource Web Access]]
[[pt-br:Acesso_web_via_recursos]]
[[ru:Resource Web Access]]

[[Category:Tutorials]]

Resource Web Access

2024-08-24T19:37:26Z

Botder:

The Multi Theft Auto Server provides a web interface that resources can use in a variety of ways. This document's purpose is to explain what these ways are and how to go about using them.
{{Note|If you are looking for a tutorial on how to use the in-game web browser and create websites using CEF, please visit [[CEF_Tutorial|CEF Tutorial]] instead.}}

==Overview==
There are three key parts that make up this system.
* '''Pages:''' The ability to serve any http items (specified the meta.xml) as a page or file.
* '''Calls:''' The ability to call any exported http functions (specified in the meta.xml).
* '''Router:''' Use a designated http function to route requests within a resource manually (overriding the two parts above).

==Pages==
===Specifying a file in the meta===
You can specify in your resource's meta file that certain files are accessible through the web server. To do this, you add a line:
<syntaxhighlight lang="xml">
<html src="filename.ext" />
</syntaxhighlight>
You can then access this file from your web browser by visiting: http://host:port/resourcename/filename.ext 
For example, on a locally hosted server using default http port with webmap started: http://127.0.0.1:22005/webmap/map.htm

===Binary files===
Despite the misleading name, files specified using the html node can be of any type. If they are binary files (like images, zip files) then you need to specify this in the meta file, by adding ''raw="true"'' to the ''html'' node. This means that the files are not preprocessed before being sent to the web browser.

For example:
<syntaxhighlight lang="xml">
<html src="image.gif" raw="true" />
</syntaxhighlight>

===Parsed files===
If a file is not specified in the metafile as "raw", then it is passed through a pre-processor before it is returned to the client. This pre-processor works much like PHP or ASP but uses Lua. You can embed standard MTA scripts within HTML pages, controlling the output. Almost all standard MTA functions work, plus a number of special [[Template:HTTP functions|HTTP Functions]], such as [[httpWrite]], a function that outputs text to the buffer.

For example:
<syntaxhighlight lang="html4strict">
<html>
<body>
This resource is called <* httpWrite( getResourceName(getThisResource()) ) *>
</body>
<html>
</syntaxhighlight>

There is a shorthand (in common with PHP and ASP) for this code, meaning that you can also write the above code as:

<syntaxhighlight lang="html4strict">
<html>
<body>
This resource is called <* = getResourceName(getThisResource()) *>
</body>
<html>
</syntaxhighlight>

Aside from HTTP functions, embedded Lua has access to the following environment variables that contain information about how the page was requested:
* table '''requestHeaders''': This is a table containing all the headers that were requested with the page. You can set returned headers using [[httpSetResponseHeader]].
* table '''form''': This is a table containing all the form data submitted to the page using HTTP POST combined with any variables passed in the querystring with HTTP GET.
* table '''cookies''': This is a table of all the cookies. You can modify cookies using [[httpSetResponseCookie]].
* string '''hostname''': This is a string containing the IP address or hostname that requested the page.
* string '''url''': This is the URL of the page.
* account '''user''': This is the account of the current user.
{{New feature/item|3.0159|1.5.8|20828|
* string '''requestBody''': This is the request body.
* string '''method''': This is the request method.
}}

It's important to note that parsed files are run in a separate virtual machine from the rest of your resource's code. As such, if you want to call a function in your resource's main code, you need to export the function and use the [[call]] function from your parsed file.

==Calls==
You can specify that certain exported functions in your resource are able to be called from the HTTP interface. All the SDKs (listed below) allow you to call these functions from a remote location.

To specify an exported http-accessible function, add the following to your meta.xml file:
<syntaxhighlight lang="xml">
<export function='functionName' http='true' />
</syntaxhighlight>

You can code your function just as you would any normal function, returning as many values as you want, including tables and resources and most important elements. You ''cannot'' however return other 'userdata' values such as [[xmlnode|xmlnodes]] or functions.

===Protocol===
{{Note|You don't need to know this unless you're writing your own HTTP request code. You can just use one of the [[#SDK|SDKs listed below]].}}

Calls are done by requesting ''<nowiki>http://<your IP>:<your port>/<resource_name>/call/<exported_function_name></nowiki>'' using HTTP POST. The body of the request should be a JSON array of the arguments for the function.

The request will return a JSON array of the value(s) returned from the function as the HTTP response.

The server supports HTTP Basic authentication and you can configure access via the ACL and the built-in accounts system.

===Calls from the HTTP web interface===
Using calls is probably easiest from the web interface and can be done almost seamlessly.

First, add this to your meta.xml file:
<syntaxhighlight lang="xml">
<include resource="ajax" />
</syntaxhighlight>

Secondly, add the following to the <head> section of the page you want to call from:
<syntaxhighlight lang="lua">
<* = exports.ajax:start(getResourceName(getThisResource())) *>
</syntaxhighlight>

Finally, you can create a javascript block on your page and call your functions almost as if they were local. The only difference is that the calls are asynchronous - you should specify a callback function as the last argument for your call. This is called when the function returns.

Here's a simple example.

'''meta.xml'''
<syntaxhighlight lang="xml">
<meta>
<include resource="ajax" />
<script src='code.lua' />
<html src='page.htm' default='true' />
<export function='showChatMessage' http='true' />
</meta>
</syntaxhighlight>

'''code.lua'''
<syntaxhighlight lang="lua">
function showChatMessage ( message )
outputChatBox ( message )
return 5;
end
</syntaxhighlight>

'''page.htm'''
<syntaxhighlight lang="html4strict">
<html>
<head>
<* = exports.ajax:start(getResourceName(getThisResource())) *>
<script type='text/javascript'>
function say() {
var message = document.getElementById('message')
showChatMessage ( message.value,
function ( number ) {
// the function has been called and returned something
message.value = "The function returned " + number;
}
);
}
</script>
</head>
<body>
<input type='text' id='message' /><input type='button' value='say' onclick='say();' />
</body>
</html>
</syntaxhighlight>

You can see (fairly complex) examples of how this can be done in the resources ''resourcebrowser'', ''resourcemanager'' and ''webadmin''.

==Router==
A router is a function that overrides both the function call mechanism and basic web server functionality, to allow a scripter to personalize the routing and client-response for each resource separately. For example, this allows a scripter to write an '''api''' named resource with a router function, that can serve any sort of information in a RESTy fashion. You may also take this further, and name the resource '''v1''' (or '''v2'''...) for easy API versioning. You can spin up and down the different resources as you wish, and users of your API can continue using an older version this way.

===How to setup a router function===
A router function has to be specified in the meta.xml (see example below). You can name the function however you like, there are no restrictions, as long as the function can be found in the global Lua scope in your scripts. '''Note:''' You can have only one router function.
<syntaxhighlight lang="xml">
<export function="httpRouter" http="true" router="true" />
</syntaxhighlight>

Then you have to specify the function in any Lua script:
<syntaxhighlight lang="lua">
function httpRouter(request)
return 200 -- see below for a more complex return value
end
</syntaxhighlight>

===Request===
This section describes all the fields, that can be found in the '''request''' table passed to the router function for every call. The descriptions below use the following example URL:

<code>http://127.0.0.1:22005/api/vehicles/123?meow=true</code> ('''api''' is the resource name)

{| class="prettytable" style="width:100%;text-align:left;"
|-
! Field || Type || Description
|-
| <code>account</code> || [[Account]] || An account that was used for this request (can be a [[isGuestAccount|guest account]]).
|-
| <code>method</code> || [[string]] || One of the following: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT, PATCH, *
|-
| <code>path</code> || [[string]] || The requested path within your resource: <code>"/vehicles/123"</code>
|-
| <code>absolute_path</code> || [[string]] || The absolute path from the URL: <code>"/api/vehicles/123?meow=true"</code>
|-
| <code>hostname</code> || [[string]] || The hostname of the web server: <code>"127.0.0.1"</code>
|-
| <code>port</code> || [[integer]] || The client port used by the web server: <code>56758</code> (can be anything, but never 22005)
|-
| <code>body</code> || [[string]] || The body portion of the request sent by the client
|-
| <code>query</code> || [[table]] || A key-value table (with [[string]] keys and values) with the path's query fields (only query)
|-
| <code>formData</code> || [[table]] || A key-value table (with [[string]] keys and values) with the request form data (both query and body fields)
|-
| <code>cookies</code> || [[table]] || A key-value table (with [[string]] keys and values) with the request cookies
|-
| <code>headers</code> || [[table]] || A key-value table (with [[string]] keys and values) with the request headers (like User-Agent)
|}

===Response===
This section describes all the possible variants, that can be returned by the router function. There are three variants in total:
* Return literally nothing: response will use http status code ''200'' and an empty body.
* Return an [[integer]]: response will convert the number to an http status code and use an empty body.
* Return a table: response will be filled with the fields from the table (defaults to http status code ''200'' and empty body, if not overriden by a table field).

====Response table fields====

{| class="prettytable" style="width:100%;text-align:left;"
|-
! Field || Type || Description
|-
| <code>status</code> || [[integer]] || A number that will be converted to an http status code.
|-
| <code>body</code> || [[string]] || A string that will be used for the response body.
|-
| <code>headers</code> || [[table]] || A key-value table (with [[string]] keys and values) that will be written to the header section of the response.
|-
| <code>cookies</code> || [[table]] || A table with simple [[string]] key and value entries, or any-type key with [[table]] values (key is not used), entries. Check the examples below, if it's unclear.
|}

===Examples===
<syntaxhighlight lang="lua">
function httpRouter(request)
-- HTTP status code 200 & empty body
end
</syntaxhighlight>

<syntaxhighlight lang="lua">
function httpRouter(request)
return 404 --< HTTP status code & empty body
end
</syntaxhighlight>

<syntaxhighlight lang="lua">
function httpRouter(request)
return {
status = 404,
body = "not found",
}
end
</syntaxhighlight>

<syntaxhighlight lang="lua">
function httpRouter(request)
return {
status = 505,
body = "foo",
cookies = {
foo = "1234",
{
name = "bar", -- Cookie name must always be a lowercase "name" key
value = "6666", -- Cookie value must always be a lowercase "value" key
Version = "2", -- Any other cookie field can use any case
}
},
headers = {
["content-type"] = "text/html",
["etag"] = "c561c68d0ba92bbeb8b0f612a9199f722e3a621a",
["access-control-allow-origin"] = "*",
["x-custom-header"] = "MTA server",
}
}
end
</syntaxhighlight>

==Securing the web interface==
The [[ACL]] has a number of rights that can affect what files can be accessed.
{{Deprecated feature|3.0139|1.3.1|
* general.http: If disabled, none of the HTTP files can be accessed (except by game clients)
** '''Important Note''': ''If 'general.http' is enabled, HTTP access to all resources (for that ACL) is enabled by default. To disable HTTP access you have to explicitly block access to resources that contain exported HTTP functions.''
** '''Important Note''': ''If 'general.http' is enabled on an ACL which has a user with no password (i.e. user.* or user.guest or user.http_guest), it is essential that you explicitly block access to resources that contain exported HTTP functions.''
* resource.'''ResourceName''': If disabled, none of the files in the resource can be accessed
* resource.'''ResourceName'''.file.'''FileName''': If disabled, the file named cannot be accessed
* resource.'''ResourceName'''.function.'''FunctionName''': If disabled, the function cannot be called
These work as with other ACL rights - you can disable them for normal users and just enable them for Admin users, or any other group of users you wish.
}}
{{New_feature|3.0139|1.3.1|
* '''resource.ResourceName.http''': If enabled, the resource will be accessible from http://server_ip:22005/ResourceName/
This works as with other ACL rights - You can enable it just for Admin users, or any other group of users you wish.
}}

==SDK==
There are a number of so-called 'SDKs' available that allow you to interface with the server from other programming languages. With these, you could (in theory) write whole gamemodes. In practice, this is probably a bad idea, but it is useful for statistics and administration. The PHP SDK is the most developed version. Feel free to modify or create your own SDKs - if you do please send us a copy.

* [[JavaSDK|Java SDK]]
* [[Javascript SDK]]
* [https://www.npmjs.com/package/mtasa Node.js SDK]
* [https://crates.io/crates/mta-sdk Rust SDK]
* [https://pypi.org/project/MTA-SDK-Python/ Python SDK]
* [[Perl SDK]]
* [[PHP SDK]]
* [[CSharp SDK|C# SDK]]

==See Also==
[[callRemote]] - Allows game servers to call functions on PHP pages (with the PHP SDK) and on other game servers.
[[Category:Scripting Concepts]]

[[en:Resource Web Access]]
[[fr:Ressource Acces Internet]]
[[hu:Resource Web Access]]
[[pt-br:Acesso_web_via_recursos]]
[[ru:Resource Web Access]]

[[Category:Tutorials]]

Resource Web Access

2024-08-24T19:36:27Z

Botder:

The Multi Theft Auto Server provides a web interface that resources can use in a variety of ways. This document's purpose is to explain what these ways are and how to go about using them.
{{Note|If you are looking for a tutorial on how to use the in-game web browser and create websites using CEF, please visit [[CEF_Tutorial|CEF Tutorial]] instead.}}

==Overview==
There are three key parts that make up this system.
* '''Pages:''' The ability to serve any http items (specified the meta.xml) as a page or file.
* '''Calls:''' The ability to call any exported http functions (specified in the meta.xml).
* '''Router:''' Use a designated http function to route requests within a resource manually (overriding the two parts above).

==Pages==
===Specifying a file in the meta===
You can specify in your resource's meta file that certain files are accessible through the web server. To do this, you add a line:
<syntaxhighlight lang="xml">
<html src="filename.ext" />
</syntaxhighlight>
You can then access this file from your web browser by visiting: http://host:port/resourcename/filename.ext 
For example, on a locally hosted server using default http port with webmap started: http://127.0.0.1:22005/webmap/map.htm

===Binary files===
Despite the misleading name, files specified using the html node can be of any type. If they are binary files (like images, zip files) then you need to specify this in the meta file, by adding ''raw="true"'' to the ''html'' node. This means that the files are not preprocessed before being sent to the web browser.

For example:
<syntaxhighlight lang="xml">
<html src="image.gif" raw="true" />
</syntaxhighlight>

===Parsed files===
If a file is not specified in the metafile as "raw", then it is passed through a pre-processor before it is returned to the client. This pre-processor works much like PHP or ASP but uses Lua. You can embed standard MTA scripts within HTML pages, controlling the output. Almost all standard MTA functions work, plus a number of special [[Template:HTTP functions|HTTP Functions]], such as [[httpWrite]], a function that outputs text to the buffer.

For example:
<syntaxhighlight lang="html4strict">
<html>
<body>
This resource is called <* httpWrite( getResourceName(getThisResource()) ) *>
</body>
<html>
</syntaxhighlight>

There is a shorthand (in common with PHP and ASP) for this code, meaning that you can also write the above code as:

<syntaxhighlight lang="html4strict">
<html>
<body>
This resource is called <* = getResourceName(getThisResource()) *>
</body>
<html>
</syntaxhighlight>

Aside from HTTP functions, embedded Lua has access to the following environment variables that contain information about how the page was requested:
* table '''requestHeaders''': This is a table containing all the headers that were requested with the page. You can set returned headers using [[httpSetResponseHeader]].
* table '''form''': This is a table containing all the form data submitted to the page using HTTP POST combined with any variables passed in the querystring with HTTP GET.
* table '''cookies''': This is a table of all the cookies. You can modify cookies using [[httpSetResponseCookie]].
* string '''hostname''': This is a string containing the IP address or hostname that requested the page.
* string '''url''': This is the URL of the page.
* account '''user''': This is the account of the current user.
{{New feature/item|3.0159|1.5.8|20828|
* string '''requestBody''': This is the request body.
* string '''method''': This is the request method.
}}

It's important to note that parsed files are run in a separate virtual machine from the rest of your resource's code. As such, if you want to call a function in your resource's main code, you need to export the function and use the [[call]] function from your parsed file.

==Calls==
You can specify that certain exported functions in your resource are able to be called from the HTTP interface. All the SDKs (listed below) allow you to call these functions from a remote location.

To specify an exported http-accessible function, add the following to your meta.xml file:
<syntaxhighlight lang="xml">
<export function='functionName' http='true' />
</syntaxhighlight>

You can code your function just as you would any normal function, returning as many values as you want, including tables and resources and most important elements. You ''cannot'' however return other 'userdata' values such as [[xmlnode|xmlnodes]] or functions.

===Protocol===
{{Note|You don't need to know this unless you're writing your own HTTP request code. You can just use one of the [[#SDK|SDKs listed below]].}}

Calls are done by requesting ''<nowiki>http://<your IP>:<your port>/<resource_name>/call/<exported_function_name></nowiki>'' using HTTP POST. The body of the request should be a JSON array of the arguments for the function.

The request will return a JSON array of the value(s) returned from the function as the HTTP response.

The server supports HTTP Basic authentication and you can configure access via the ACL and the built-in accounts system.

===Calls from the HTTP web interface===
Using calls is probably easiest from the web interface and can be done almost seamlessly.

First, add this to your meta.xml file:
<syntaxhighlight lang="xml">
<include resource="ajax" />
</syntaxhighlight>

Secondly, add the following to the <head> section of the page you want to call from:
<syntaxhighlight lang="lua">
<* = exports.ajax:start(getResourceName(getThisResource())) *>
</syntaxhighlight>

Finally, you can create a javascript block on your page and call your functions almost as if they were local. The only difference is that the calls are asynchronous - you should specify a callback function as the last argument for your call. This is called when the function returns.

Here's a simple example.

'''meta.xml'''
<syntaxhighlight lang="xml">
<meta>
<include resource="ajax" />
<script src='code.lua' />
<html src='page.htm' default='true' />
<export function='showChatMessage' http='true' />
</meta>
</syntaxhighlight>

'''code.lua'''
<syntaxhighlight lang="lua">
function showChatMessage ( message )
outputChatBox ( message )
return 5;
end
</syntaxhighlight>

'''page.htm'''
<syntaxhighlight lang="html4strict">
<html>
<head>
<* = exports.ajax:start(getResourceName(getThisResource())) *>
<script type='text/javascript'>
function say() {
var message = document.getElementById('message')
showChatMessage ( message.value,
function ( number ) {
// the function has been called and returned something
message.value = "The function returned " + number;
}
);
}
</script>
</head>
<body>
<input type='text' id='message' /><input type='button' value='say' onclick='say();' />
</body>
</html>
</syntaxhighlight>

You can see (fairly complex) examples of how this can be done in the resources ''resourcebrowser'', ''resourcemanager'' and ''webadmin''.

==Router==
A router is a function that overrides both the function call mechanism and basic web server functionality, to allow a scripter to personalize the routing and client-response for each resource separately. For example, this allows a scripter to write an '''api''' named resource with a router function, that can serve any sort of information in a RESTy fashion. You may also take this further, and name the resource '''v1''' (or '''v2'''...) for easy API versioning. You can spin up and down the different resources as you wish, and users of your API can continue using an older version this way.

===How to setup a router function===
A router function has to be specified in the meta.xml (see example below). You can name the function however you like, there are no restrictions, as long as the function can be found in the global Lua scope in your scripts. '''Note:''' You can have only one router function.
<syntaxhighlight lang="xml">
<export function="httpRouter" http="true" router="true" />
</syntaxhighlight>

Then you have to specify the function in any Lua script:
<syntaxhighlight lang="lua">
function httpRouter(request)
return 200 -- see below for a more complex return value
end
</syntaxhighlight>

===Request===
This section describes all the fields, that can be found in the '''request''' table passed to the router function for every call. The descriptions below use the following example URL for the descriptions:

<code>http://127.0.0.1:22005/api/vehicles/123?meow=true</code> ('''api''' is the resource name)

{| class="prettytable" style="width:100%;text-align:left;"
|-
! Field || Type || Description
|-
| <code>account</code> || [[Account]] || An account that was used for this request (can be a [[isGuestAccount|guest account]]).
|-
| <code>method</code> || [[string]] || One of the following: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT, PATCH, *
|-
| <code>path</code> || [[string]] || The requested path within your resource: <code>"/vehicles/123"</code>
|-
| <code>absolute_path</code> || [[string]] || The absolute path from the URL: <code>"/api/vehicles/123?meow=true"</code>
|-
| <code>hostname</code> || [[string]] || The hostname of the web server: <code>"127.0.0.1"</code>
|-
| <code>port</code> || [[integer]] || The client port used by the web server: <code>56758</code> (can be anything, but never 22005)
|-
| <code>body</code> || [[string]] || The body portion of the request sent by the client
|-
| <code>query</code> || [[table]] || A key-value table (with [[string]] keys and values) with the path's query fields (only query)
|-
| <code>formData</code> || [[table]] || A key-value table (with [[string]] keys and values) with the request form data (both query and body fields)
|-
| <code>cookies</code> || [[table]] || A key-value table (with [[string]] keys and values) with the request cookies
|-
| <code>headers</code> || [[table]] || A key-value table (with [[string]] keys and values) with the request headers (like User-Agent)
|}

===Response===
This section describes all the possible variants, that can be returned by the router function. There are three variants in total:
* Return literally nothing: response will use http status code ''200'' and an empty body.
* Return an [[integer]]: response will convert the number to an http status code and use an empty body.
* Return a table: response will be filled with the fields from the table (defaults to http status code ''200'' and empty body, if not overriden by a table field).

====Response table fields====

{| class="prettytable" style="width:100%;text-align:left;"
|-
! Field || Type || Description
|-
| <code>status</code> || [[integer]] || A number that will be converted to an http status code.
|-
| <code>body</code> || [[string]] || A string that will be used for the response body.
|-
| <code>headers</code> || [[table]] || A key-value table (with [[string]] keys and values) that will be written to the header section of the response.
|-
| <code>cookies</code> || [[table]] || A table with simple [[string]] key and value entries, or any-type key with [[table]] values (key is not used), entries. Check the examples below, if it's unclear.
|}

===Examples===
<syntaxhighlight lang="lua">
function httpRouter(request)
-- HTTP status code 200 & empty body
end
</syntaxhighlight>

<syntaxhighlight lang="lua">
function httpRouter(request)
return 404 --< HTTP status code & empty body
end
</syntaxhighlight>

<syntaxhighlight lang="lua">
function httpRouter(request)
return {
status = 404,
body = "not found",
}
end
</syntaxhighlight>

<syntaxhighlight lang="lua">
function httpRouter(request)
return {
status = 505,
body = "foo",
cookies = {
foo = "1234",
{
name = "bar", -- Cookie name must always be a lowercase "name" key
value = "6666", -- Cookie value must always be a lowercase "value" key
Version = "2", -- Any other cookie field can use any case
}
},
headers = {
["content-type"] = "text/html",
["etag"] = "c561c68d0ba92bbeb8b0f612a9199f722e3a621a",
["access-control-allow-origin"] = "*",
["x-custom-header"] = "MTA server",
}
}
end
</syntaxhighlight>

==Securing the web interface==
The [[ACL]] has a number of rights that can affect what files can be accessed.
{{Deprecated feature|3.0139|1.3.1|
* general.http: If disabled, none of the HTTP files can be accessed (except by game clients)
** '''Important Note''': ''If 'general.http' is enabled, HTTP access to all resources (for that ACL) is enabled by default. To disable HTTP access you have to explicitly block access to resources that contain exported HTTP functions.''
** '''Important Note''': ''If 'general.http' is enabled on an ACL which has a user with no password (i.e. user.* or user.guest or user.http_guest), it is essential that you explicitly block access to resources that contain exported HTTP functions.''
* resource.'''ResourceName''': If disabled, none of the files in the resource can be accessed
* resource.'''ResourceName'''.file.'''FileName''': If disabled, the file named cannot be accessed
* resource.'''ResourceName'''.function.'''FunctionName''': If disabled, the function cannot be called
These work as with other ACL rights - you can disable them for normal users and just enable them for Admin users, or any other group of users you wish.
}}
{{New_feature|3.0139|1.3.1|
* '''resource.ResourceName.http''': If enabled, the resource will be accessible from http://server_ip:22005/ResourceName/
This works as with other ACL rights - You can enable it just for Admin users, or any other group of users you wish.
}}

==SDK==
There are a number of so-called 'SDKs' available that allow you to interface with the server from other programming languages. With these, you could (in theory) write whole gamemodes. In practice, this is probably a bad idea, but it is useful for statistics and administration. The PHP SDK is the most developed version. Feel free to modify or create your own SDKs - if you do please send us a copy.

* [[JavaSDK|Java SDK]]
* [[Javascript SDK]]
* [https://www.npmjs.com/package/mtasa Node.js SDK]
* [https://crates.io/crates/mta-sdk Rust SDK]
* [https://pypi.org/project/MTA-SDK-Python/ Python SDK]
* [[Perl SDK]]
* [[PHP SDK]]
* [[CSharp SDK|C# SDK]]

==See Also==
[[callRemote]] - Allows game servers to call functions on PHP pages (with the PHP SDK) and on other game servers.
[[Category:Scripting Concepts]]

[[en:Resource Web Access]]
[[fr:Ressource Acces Internet]]
[[hu:Resource Web Access]]
[[pt-br:Acesso_web_via_recursos]]
[[ru:Resource Web Access]]

[[Category:Tutorials]]

Resource Web Access

2024-08-24T19:34:23Z

Botder: Add HTTP router function information

The Multi Theft Auto Server provides a web interface that resources can use in a variety of ways. This document's purpose is to explain what these ways are and how to go about using them.
{{Note|If you are looking for a tutorial on how to use the in-game web browser and create websites using CEF, please visit [[CEF_Tutorial|CEF Tutorial]] instead.}}

==Overview==
There are three key parts that make up this system.
* '''Pages:''' The ability to serve any http items (specified the meta.xml) as a page or file.
* '''Calls:''' The ability to call any exported http functions (specified in the meta.xml).
* '''Router:''' Use a designated http function to route requests within a resource manually (overriding the two parts above).

==Pages==
===Specifying a file in the meta===
You can specify in your resource's meta file that certain files are accessible through the web server. To do this, you add a line:
<syntaxhighlight lang="xml">
<html src="filename.ext" />
</syntaxhighlight>
You can then access this file from your web browser by visiting: http://host:port/resourcename/filename.ext 
For example, on a locally hosted server using default http port with webmap started: http://127.0.0.1:22005/webmap/map.htm

===Binary files===
Despite the misleading name, files specified using the html node can be of any type. If they are binary files (like images, zip files) then you need to specify this in the meta file, by adding ''raw="true"'' to the ''html'' node. This means that the files are not preprocessed before being sent to the web browser.

For example:
<syntaxhighlight lang="xml">
<html src="image.gif" raw="true" />
</syntaxhighlight>

===Parsed files===
If a file is not specified in the metafile as "raw", then it is passed through a pre-processor before it is returned to the client. This pre-processor works much like PHP or ASP but uses Lua. You can embed standard MTA scripts within HTML pages, controlling the output. Almost all standard MTA functions work, plus a number of special [[Template:HTTP functions|HTTP Functions]], such as [[httpWrite]], a function that outputs text to the buffer.

For example:
<syntaxhighlight lang="html4strict">
<html>
<body>
This resource is called <* httpWrite( getResourceName(getThisResource()) ) *>
</body>
<html>
</syntaxhighlight>

There is a shorthand (in common with PHP and ASP) for this code, meaning that you can also write the above code as:

<syntaxhighlight lang="html4strict">
<html>
<body>
This resource is called <* = getResourceName(getThisResource()) *>
</body>
<html>
</syntaxhighlight>

Aside from HTTP functions, embedded Lua has access to the following environment variables that contain information about how the page was requested:
* table '''requestHeaders''': This is a table containing all the headers that were requested with the page. You can set returned headers using [[httpSetResponseHeader]].
* table '''form''': This is a table containing all the form data submitted to the page using HTTP POST combined with any variables passed in the querystring with HTTP GET.
* table '''cookies''': This is a table of all the cookies. You can modify cookies using [[httpSetResponseCookie]].
* string '''hostname''': This is a string containing the IP address or hostname that requested the page.
* string '''url''': This is the URL of the page.
* account '''user''': This is the account of the current user.
{{New feature/item|3.0159|1.5.8|20828|
* string '''requestBody''': This is the request body.
* string '''method''': This is the request method.
}}

It's important to note that parsed files are run in a separate virtual machine from the rest of your resource's code. As such, if you want to call a function in your resource's main code, you need to export the function and use the [[call]] function from your parsed file.

==Calls==
You can specify that certain exported functions in your resource are able to be called from the HTTP interface. All the SDKs (listed below) allow you to call these functions from a remote location.

To specify an exported http-accessible function, add the following to your meta.xml file:
<syntaxhighlight lang="xml">
<export function='functionName' http='true' />
</syntaxhighlight>

You can code your function just as you would any normal function, returning as many values as you want, including tables and resources and most important elements. You ''cannot'' however return other 'userdata' values such as [[xmlnode|xmlnodes]] or functions.

===Protocol===
{{Note|You don't need to know this unless you're writing your own HTTP request code. You can just use one of the [[#SDK|SDKs listed below]].}}

Calls are done by requesting ''<nowiki>http://<your IP>:<your port>/<resource_name>/call/<exported_function_name></nowiki>'' using HTTP POST. The body of the request should be a JSON array of the arguments for the function.

The request will return a JSON array of the value(s) returned from the function as the HTTP response.

The server supports HTTP Basic authentication and you can configure access via the ACL and the built-in accounts system.

===Calls from the HTTP web interface===
Using calls is probably easiest from the web interface and can be done almost seamlessly.

First, add this to your meta.xml file:
<syntaxhighlight lang="xml">
<include resource="ajax" />
</syntaxhighlight>

Secondly, add the following to the <head> section of the page you want to call from:
<syntaxhighlight lang="lua">
<* = exports.ajax:start(getResourceName(getThisResource())) *>
</syntaxhighlight>

Finally, you can create a javascript block on your page and call your functions almost as if they were local. The only difference is that the calls are asynchronous - you should specify a callback function as the last argument for your call. This is called when the function returns.

Here's a simple example.

'''meta.xml'''
<syntaxhighlight lang="xml">
<meta>
<include resource="ajax" />
<script src='code.lua' />
<html src='page.htm' default='true' />
<export function='showChatMessage' http='true' />
</meta>
</syntaxhighlight>

'''code.lua'''
<syntaxhighlight lang="lua">
function showChatMessage ( message )
outputChatBox ( message )
return 5;
end
</syntaxhighlight>

'''page.htm'''
<syntaxhighlight lang="html4strict">
<html>
<head>
<* = exports.ajax:start(getResourceName(getThisResource())) *>
<script type='text/javascript'>
function say() {
var message = document.getElementById('message')
showChatMessage ( message.value,
function ( number ) {
// the function has been called and returned something
message.value = "The function returned " + number;
}
);
}
</script>
</head>
<body>
<input type='text' id='message' /><input type='button' value='say' onclick='say();' />
</body>
</html>
</syntaxhighlight>

You can see (fairly complex) examples of how this can be done in the resources ''resourcebrowser'', ''resourcemanager'' and ''webadmin''.

==Router==
A router is a function that overrides both the function call mechanism and basic web server functionality, to allow a scripter to personalize the routing and client-response for a single resource. For example, this allows a scripter to write an '''api''' named resource with a router function, that can serve any sort of information in a RESTy fashion. You may also take this further, and name the resource '''v1''' (or '''v2'''...) for easy API versioning. You can spin up and down the different resources as you wish, and users of your API can continue using an older version this way.

===How to setup a router function===
A router function has to be specified in the meta.xml (see example below). You can name the function however you like, there are no restrictions, as long as the function can be found in the global Lua scope in your scripts. '''Note:''' You can have only one router function.
<syntaxhighlight lang="xml">
<export function="httpRouter" http="true" router="true" />
</syntaxhighlight>

Then you have to specify the function in any Lua script:
<syntaxhighlight lang="lua">
function httpRouter(request)
return 200 -- see below for a more complex return value
end
</syntaxhighlight>

===Request===
This section describes all the fields, that can be found in the '''request''' table passed to the router function for every call. The descriptions below use the following example URL for the descriptions:

<code>http://127.0.0.1:22005/api/vehicles/123?meow=true</code> ('''api''' is the resource name)

{| class="prettytable" style="width:100%;text-align:left;"
|-
! Field || Type || Description
|-
| <code>account</code> || [[Account]] || An account that was used for this request (can be a [[isGuestAccount|guest account]]).
|-
| <code>method</code> || [[string]] || One of the following: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT, PATCH, *
|-
| <code>path</code> || [[string]] || The requested path within your resource: <code>"/vehicles/123"</code>
|-
| <code>absolute_path</code> || [[string]] || The absolute path from the URL: <code>"/api/vehicles/123?meow=true"</code>
|-
| <code>hostname</code> || [[string]] || The hostname of the web server: <code>"127.0.0.1"</code>
|-
| <code>port</code> || [[integer]] || The client port used by the web server: <code>56758</code> (can be anything, but never 22005)
|-
| <code>body</code> || [[string]] || The body portion of the request sent by the client
|-
| <code>query</code> || [[table]] || A key-value table (with [[string]] keys and values) with the path's query fields (only query)
|-
| <code>formData</code> || [[table]] || A key-value table (with [[string]] keys and values) with the request form data (both query and body fields)
|-
| <code>cookies</code> || [[table]] || A key-value table (with [[string]] keys and values) with the request cookies
|-
| <code>headers</code> || [[table]] || A key-value table (with [[string]] keys and values) with the request headers (like User-Agent)
|}

===Response===
This section describes all the possible variants, that can be returned by the router function. There are three variants in total:
* Return literally nothing: response will use http status code ''200'' and an empty body.
* Return an [[integer]]: response will convert the number to an http status code and use an empty body.
* Return a table: response will be filled with the fields from the table (defaults to http status code ''200'' and empty body, if not overriden by a table field).

====Response table fields====

{| class="prettytable" style="width:100%;text-align:left;"
|-
! Field || Type || Description
|-
| <code>status</code> || [[integer]] || A number that will be converted to an http status code.
|-
| <code>body</code> || [[string]] || A string that will be used for the response body.
|-
| <code>headers</code> || [[table]] || A key-value table (with [[string]] keys and values) that will be written to the header section of the response.
|-
| <code>cookies</code> || [[table]] || A table with simple [[string]] key and value entries, or any-type key with [[table]] values (key is not used), entries. Check the examples below, if it's unclear.
|}

===Examples===
<syntaxhighlight lang="lua">
function httpRouter(request)
-- HTTP status code 200 & empty body
end
</syntaxhighlight>

<syntaxhighlight lang="lua">
function httpRouter(request)
return 404 --< HTTP status code & empty body
end
</syntaxhighlight>

<syntaxhighlight lang="lua">
function httpRouter(request)
return {
status = 404,
body = "not found",
}
end
</syntaxhighlight>

<syntaxhighlight lang="lua">
function httpRouter(request)
return {
status = 505,
body = "foo",
cookies = {
foo = "1234",
{
name = "bar", -- Cookie name must always be a lowercase "name" key
value = "6666", -- Cookie value must always be a lowercase "value" key
Version = "2", -- Any other cookie field can use any case
}
},
headers = {
["content-type"] = "text/html",
["etag"] = "c561c68d0ba92bbeb8b0f612a9199f722e3a621a",
["access-control-allow-origin"] = "*",
["x-custom-header"] = "MTA server",
}
}
end
</syntaxhighlight>

==Securing the web interface==
The [[ACL]] has a number of rights that can affect what files can be accessed.
{{Deprecated feature|3.0139|1.3.1|
* general.http: If disabled, none of the HTTP files can be accessed (except by game clients)
** '''Important Note''': ''If 'general.http' is enabled, HTTP access to all resources (for that ACL) is enabled by default. To disable HTTP access you have to explicitly block access to resources that contain exported HTTP functions.''
** '''Important Note''': ''If 'general.http' is enabled on an ACL which has a user with no password (i.e. user.* or user.guest or user.http_guest), it is essential that you explicitly block access to resources that contain exported HTTP functions.''
* resource.'''ResourceName''': If disabled, none of the files in the resource can be accessed
* resource.'''ResourceName'''.file.'''FileName''': If disabled, the file named cannot be accessed
* resource.'''ResourceName'''.function.'''FunctionName''': If disabled, the function cannot be called
These work as with other ACL rights - you can disable them for normal users and just enable them for Admin users, or any other group of users you wish.
}}
{{New_feature|3.0139|1.3.1|
* '''resource.ResourceName.http''': If enabled, the resource will be accessible from http://server_ip:22005/ResourceName/
This works as with other ACL rights - You can enable it just for Admin users, or any other group of users you wish.
}}

==SDK==
There are a number of so-called 'SDKs' available that allow you to interface with the server from other programming languages. With these, you could (in theory) write whole gamemodes. In practice, this is probably a bad idea, but it is useful for statistics and administration. The PHP SDK is the most developed version. Feel free to modify or create your own SDKs - if you do please send us a copy.

* [[JavaSDK|Java SDK]]
* [[Javascript SDK]]
* [https://www.npmjs.com/package/mtasa Node.js SDK]
* [https://crates.io/crates/mta-sdk Rust SDK]
* [https://pypi.org/project/MTA-SDK-Python/ Python SDK]
* [[Perl SDK]]
* [[PHP SDK]]
* [[CSharp SDK|C# SDK]]

==See Also==
[[callRemote]] - Allows game servers to call functions on PHP pages (with the PHP SDK) and on other game servers.
[[Category:Scripting Concepts]]

[[en:Resource Web Access]]
[[fr:Ressource Acces Internet]]
[[hu:Resource Web Access]]
[[pt-br:Acesso_web_via_recursos]]
[[ru:Resource Web Access]]

[[Category:Tutorials]]

DbConnect

2024-06-06T18:51:26Z

Botder:

__NOTOC__
{{Server function}}
This function opens a connection to a database and returns an element that can be used with [[dbQuery]]. To disconnect use [[destroyElement]].
{{Note|Connecting and disconnecting many times can have a performance impact on the server. For optimal performance it is recommended that you use dbConnect only once when the resource starts, and share the connection element with the whole script.}}
{{Note|If you use MySQL 8 or newer, you should add this line to mysqld.cnf '''<nowiki>default-authentication-plugin=mysql_native_password</nowiki>''' in the case where you're unable to authenticate with your MySQL server.}}
==Syntax==
<syntaxhighlight lang="lua">
element dbConnect ( string databaseType, string host [, string username = "", string password = "", string options = "" ] )
</syntaxhighlight>
{{OOP||[[Connection]]}}
===Required Arguments===
*'''databaseType:''' The type of database. This can be either ''sqlite'' or ''mysql''
*'''host:''' The target to connect to. The format of this depends on the database type.
** For SQLite it is a [[filepath]] to a SQLite database file. If the filepath starts with ":/" then the server's global databases directory is used. The file will be created if it does not exist.
** For MySQL it is a list of key=value pairs separated by semicolons. Supported keys are:
*** '''dbname''': Name of the database to use e.g. ''dbname=test''
*** '''host''': Host address e.g. ''host=127.0.0.1''
*** '''port''': Host port e.g. ''port=1234'' (optional, defaults to standard MySQL port if not used)
*** '''unix_socket''': Unix socket or named pipe to use (optional)
***'''charset''': Communicate with the server using a character which is different from the default e.g. ''charset<nowiki>=</nowiki>utf8'' (optional)

===Optional Arguments===
*'''username:''' Usually required for MySQL, ignored by SQLite
*'''password:''' Usually required for MySQL, ignored by SQLite
*'''options :''' List of key=value pairs separated by semicolons. Supported keys are:
**'''share''' which can be set to 0 or 1. (Default value for SQLite is "share=1", for MySQL is "share=0"). When set to 1, the connection is shared and will be used by other calls to dbConnect with the same host string. This is usually a good thing for SQLite connections, but not so good for MySQL unless care is taken.
**'''batch''' which can be set to 0 or 1. (Default is "batch=1"). When set to 1, queries called in the same frame are automatically batched together which can significantly speed up inserts/updates. The downside is you lose control of the feature that is used to achieve batching (For SQLite it is transactions, for MySQL it is autocommit mode). Therefore, if you use transactions, lock tables or control autocommit yourself, you may want to disable this feature.
**'''autoreconnect''' which can be set to 0 or 1. (Default value "autoreconnect=1"). When set to 1, dropped connections will automatically be reconnected. Note that session variables (incl. SET NAMES), user variables, table locks and temporary tables will be reset because of the reconnection. So if you use these fancy features, you will need to turn autoreconnect off and cope with dropped connections some other way.
**'''log''' which can be set to 0 or 1. (Default value "log<nowiki>=</nowiki>1"). When set to 0, activity from this connection will not be recorded in the [[Server_Commands#debugdb|database debug log file]].
**'''tag''' (Default value "tag<nowiki>=</nowiki>script"). A string which helps identify activity from this connection in the [[Server_Commands#debugdb|database debug log file]].
**'''suppress''' A comma separated list of error codes to ignore. (eg. "suppress<nowiki>=</nowiki>1062,1169").
**'''multi_statements''' Enable multiple statements (separated by a semi-colon) in one query. Use [[dbPrepareString]] when building a multiple statement query to reduce SQL injection risks.
**'''queue''' Name of the queue to use. (Default value for SQLite is "sqlite", for MySQL default is the host string from the '''host''' argument). Asynchronous database queries in the same queue are processed in order, one at a time. Any name can be used.
**'''use_ssl''' which can be set to 0 or 1. (Default value is 0), ignored by SQLite
{{New feature/item|3.0161|1.6.0|22497|'''get_server_public_key''' which can be set to 0 or 1. (Default value is 1), ignored by SQLite. When set to 1, this enables the client to request from the server the public key required for RSA key pair-based password exchange. This option applies to clients that authenticate with the <code>caching_sha2_password</code> authentication plugin.}}

===Returns===
Returns a database connection element unless there are problems, in which case it return ''false''.

==Remarks==
Under certain platforms, for example on Unix-based OSes like Linux, using this function could fail with a debug warning containing "[Could not connect]" accompanied by a prior debug error explaining the problem. In that case you should check the [[Server Manual]] to see if you have missed any recommended (best-effort) steps for server set-up.

==Example==
This example opens a connection to a SQLite database file in the current resource
<syntaxhighlight lang="lua">
test_db = dbConnect( "sqlite", "file.db" )
</syntaxhighlight>

This example opens a connection to a SQLite database file in another resource
<syntaxhighlight lang="lua">
test_db = dbConnect( "sqlite", ":resname/file.db" )
</syntaxhighlight>

This example opens a connection to a SQLite database file in the global databases directory
<syntaxhighlight lang="lua">
test_db = dbConnect( "sqlite", ":/file.db" )
</syntaxhighlight>

This example opens a connection to a SQLite database file in a sub directory of the global databases directory
<syntaxhighlight lang="lua">
test_db = dbConnect( "sqlite", ":/example/sub/dir/file.db" )
</syntaxhighlight>

This example opens a connection to a MySQL database called 'frank' at server ip 1.2.3.4 using utf8 character set and allows the connection to be shared. Note that changing the database or other connection dependent settings affect all connections that are shared.
<syntaxhighlight lang="lua">
test_db = dbConnect( "mysql", "dbname=frank;host=1.2.3.4;charset=utf8", "username", "password", "share=1" )
</syntaxhighlight>

This example opens a connection to a SQLite database is disallows sharing of the connection
<syntaxhighlight lang="lua">
test_db = dbConnect( "sqlite", "file.db", "", "", "share=0" )
</syntaxhighlight>

This example output debug message, if the connection with SQLite database was established or not
<syntaxhighlight lang="lua">
test_db = dbConnect( "sqlite", "file.db" )

if test_db then
outputDebugString( "Connection with database was successfully established." )
else
outputDebugString( "Connection with database couldn't be established." )
end
</syntaxhighlight>

The folowing example shows how you could approach a common resource for database operations with exported functions ('''query''' and '''execute'''):

<syntaxhighlight lang="lua">
function connect()
DBConnection = dbConnect( "mysql", "dbname=DBNAME;host=HOST;charset=utf8", "USERNAME", "PASSWORD" )
if (not DBConnection) then
outputDebugString("Error: Failed to establish connection to the MySQL database server")
else
outputDebugString("Success: Connected to the MySQL database server")
end
end

addEventHandler("onResourceStart",resourceRoot, connect)

function query(...)
local queryHandle = dbQuery(DBConnection, ...)
if (not queryHandle) then
return nil
end
local rows = dbPoll(queryHandle, -1)
return rows
end

function execute(...)
local queryHandle = dbQuery(DBConnection, ...)
local result, numRows = dbPoll(queryHandle, -1)
return numRows
end

function getDBConnection()
return DBConnection
end
</syntaxhighlight>

==Requirements==
{{Requirements|1.1.1-9.03328|n/a}}

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.1-9.04817|Added options 'log', 'tag' and 'suppress'}}
{{ChangelogItem|1.3.5-9.06386|Added option 'charset'}}
{{ChangelogItem|1.5.2-9.07972|Added option 'multi_statements'}}
{{ChangelogItem|1.5.4-9.11138|Added option 'queue'}}
{{ChangelogItem|1.6.0-9.22396|Added option 'use_ssl'}}
{{ChangelogItem|1.6.0-9.22497|Added option 'get_server_public_key'}}

==See Also==
{{SQL_functions}}

[[ru:dbConnect]]

How you can help

2023-08-16T14:58:58Z

Botder: Reverted edits by TheRealSadra (talk) to last revision by Maurice

__NOTOC__
Multi Theft Auto has loads of areas in which you can help us. In turn, we'll be more than happy to help you get started with any ideas you have, help test them and - if they're good enough - release them to the whole community. This page outlines the key areas you could do something in, of course, there are many things we've not thought of, so think outside the box!

==Coding for MTA:SA==
* Become a patch contributor by sending [https://github.com/multitheftauto/mtasa-blue/pulls pull requests] to MTA, containing requested features or bugfixes. ([https://github.com/multitheftauto/mtasa-blue/blob/master/CONTRIBUTING.md#contributors-guide Coding guidelines])
* Translate MTA:SA to your native language on Crowdin at https://multitheftauto.crowdin.com/

==Scripting==
* Become a contributor to MTA's official resources by sending [https://github.com/multitheftauto/mtasa-resources/pulls pull requests] to our resources repository
* Create and [https://community.multitheftauto.com/ publish] a gamemode or useful script
**[[Scripting Introduction]]
**[https://www.lua.org/pil/index.html "Programming in Lua" Manual]
* Make a general purpose resource that provides useful functions to other resources.

==Mapping==
* Create and [https://community.multitheftauto.com/ publish] a map for an existing gamemode, with the map editor.
**[[Resource:Editor|Map Editor Manual]]

==Web development==
* Create your own system for statistics - using the [[PHP SDK]] as a basis. Join the [https://discord.com/invite/mtasa MTA Discord] (or [https://discord.gg/GNN6PRtTnu development Discord]) for help.

==Documentation==
Before you make changes check out: [[Help:Editing Guidelines|Editing Guidelines]] and [[Help:MTA Wiki Specific Templates|Specific Templates]]
* Finish documentation for [[:Category:Incomplete|Incomplete functions]] - ask in #mta.scripting if you're not sure of something.
* Add examples to [[:Category:Needs Example|functions & events missing examples]] - please '''test''' them, and again, ask if you need help.
* Review and verify [[:Category:Needs Checking|pages that need checking]] - make sure highlighted issues are solved before removing pages from the category.
* Expand the pages that explain [[:Category:Scripting_Concepts|MTA core concepts]].
* Write [https://forum.multitheftauto.com/forum/123-tutorials/ tutorials] to help new people.
* Translate the wiki pages so people from other countries can get started in MTA too.
* Create documentation for undocumented functions and events [[Undocumented Items]]
* Keep 'changes in' [current work-in-progress: https://wiki.multitheftauto.com/wiki/Changes_in_1.6] for future releases updated.

==Quality Assurance==
* [https://github.com/multitheftauto/mtasa-blue/issues Report issues] with the mod, make sure to do a search on the already reported issues first.
* Test and confirm existing reported issues.
* Use the newest build of MTA to detect and report new bugs, by going to 'Settings', 'Advanced', 'Update build type' and choosing 'Nightly' or get it regularly [https://nightly.multitheftauto.com/ from here].
* Any bugs which are related to a scripting function / event and present in the main release (rather than nightlies), document that bug by adding a [https://wiki.multitheftauto.com/wiki/Help:MTA_Wiki_Specific_Templates warning] to the wiki page to save other scripters a lot of time.

==Specific tasks==
* Create a fuzzer to check for crashes in our scripting functions.

==Grant==
You can donate to MTA:SA [https://multitheftauto.com/donate/manage.php here]

[[ar:كيف_يمكنك_المساعدة]]
[[en:How you can help]]
[[ru:How you can help]]
[[pl:Jak możesz pomóc]]
[[uk:How you can help]]
[[es:Cómo puedes ayudar]]
[[hu:How you can help]]
[[tr:Nasıl yardımcı olabilirsiniz]]
[[pt-br:Como você pode ajudar]]

Template:File functions

2023-08-07T20:55:54Z

Botder:

<ul>
<li>[[fileClose]]</li>
<li>[[fileCopy]]</li>
<li>[[fileCreate]]</li>
<li>[[fileDelete]]</li>
<li>[[fileExists]]</li>
<li>[[fileFlush]]</li>
{{New items|3.0161|1.6.0|
<li>[[fileGetContents]]</li>
|21938}}
{{New items|3.0153|1.5.3|
<li>[[fileGetPath]]</li>
|7446}}
<li>[[fileGetPos]]</li>
<li>[[fileGetSize]]</li>
<li>[[fileIsEOF]]</li>
<li>[[fileOpen]]</li>
<li>[[fileRead]]</li>
<li>[[fileRename]]</li>
<li>[[fileSetPos]]</li>
<li>[[fileWrite]]</li>
</ul>

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

FileGetContents

2023-08-07T20:54:29Z

Botder:

__NOTOC__
{{Server client function}}

{{Added feature/item|1.6.1|1.6.0|21938|
Reads the entire contents of the file, optionally verifies the read contents by computing and comparing the checksum with the expected one, and returns the content as string. The file cursor position is not modified by calls to this function.
}}

Please note that even if you enable SD #22 and #23 on your server, you are not protected from user attacks, which can happen after verification of the file, but before you read the contents of such verified file. This function enables you to safely read the contents of a meta.xml-listed file on both client and server.

==Syntax==
<syntaxhighlight lang="lua">
nil|string fileGetContents ( file theFile [ , bool verifyContents = true ] )
</syntaxhighlight>
{{OOP||[[file]]:getContents}}

===Required Arguments===
*'''theFile:''' A handle to the file you wish to get the contents from. Use [[fileOpen]] to obtain this handle.
*'''verifyContents:''' Set to true, to compare the computed and the expected checksum of the file content

===Returns===
Returns the bytes that were read from the file, but only if verification was disabled or if the checksum comparison succeeded. On failure, this function returns ''nil''.

==Example==
This example opens the file test.txt and outputs its contents to the console.
<syntaxhighlight lang="lua">
local handle = fileOpen("code.lua", true)
local buffer = fileGetContents(handle) -- code.lua must be listed in meta.xml (for example as <file> for this example)
fileClose(handle)

if buffer then
loadstring(buffer)()
end
</syntaxhighlight>

==See Also==
{{File functions}}

FileGetContents

2023-08-07T20:06:02Z

Botder:

__NOTOC__
{{Server client function}}

{{Added feature/item|1.6.1|1.6.0|21933|
Reads the entire contents of the file, optionally verifies the read contents by computing and comparing the checksum with the expected one, and returns the content as string. The file cursor position is not modified by calls to this function.
}}

Please note that even if you enable SD #22 and #23 on your server, you are not protected from user attacks, which can happen after verification of the file, but before you read the contents of such verified file. This function enables you to safely read the contents of a meta.xml-listed file on both client and server.

==Syntax==
<syntaxhighlight lang="lua">
nil|string fileGetContents ( file theFile [ , bool verifyContents = true ] )
</syntaxhighlight>
{{OOP||[[file]]:getContents}}

===Required Arguments===
*'''theFile:''' A handle to the file you wish to get the contents from. Use [[fileOpen]] to obtain this handle.
*'''verifyContents:''' Set to true, to compare the computed and the expected checksum of the file content

===Returns===
Returns the bytes that were read from the file, but only if verification was disabled or if the checksum comparison succeeded. On failure, this function returns ''nil''.

==Example==
This example opens the file test.txt and outputs its contents to the console.
<syntaxhighlight lang="lua">
local handle = fileOpen("code.lua", true)
local buffer = fileGetContents(handle) -- code.lua must be listed in meta.xml (for example as <file> for this example)
fileClose(handle)

if buffer then
loadstring(buffer)()
end
</syntaxhighlight>

==See Also==
{{File functions}}

FileGetContents

2023-08-07T20:04:44Z

Botder:

__NOTOC__
{{Server client function}}

{{Added feature/item|1.6.1|1.6.0|21933|
Reads the entire contents of the file '''starting from the current file position''', optionally verifies the read contents by computing and comparing the checksum with the expected one, and returns the content as string.
}}

Please note that even if you enable SD #22 and #23 on your server, you are not protected from user attacks, which can happen after verification of the file, but before you read the contents of such verified file. This function enables you to safely read the contents of a meta.xml-listed file on both client and server.

==Syntax==
<syntaxhighlight lang="lua">
nil|string fileGetContents ( file theFile [ , bool verifyContents = true ] )
</syntaxhighlight>
{{OOP||[[file]]:getContents}}

===Required Arguments===
*'''theFile:''' A handle to the file you wish to get the contents from. Use [[fileOpen]] to obtain this handle.
*'''verifyContents:''' Set to true, to compare the computed and the expected checksum of the file content

===Returns===
Returns the bytes that were read from the file, but only if verification was disabled or if the checksum comparison succeeded. On failure, this function returns ''nil''.

==Example==
This example opens the file test.txt and outputs its contents to the console.
<syntaxhighlight lang="lua">
local handle = fileOpen("code.lua", true)
local buffer = fileGetContents(handle) -- code.lua must be listed in meta.xml (for example as <file> for this example)
fileClose(handle)

if buffer then
loadstring(buffer)()
end
</syntaxhighlight>

==See Also==
{{File functions}}

FileGetContents

2023-08-07T19:18:24Z

Botder:

__NOTOC__
{{Server client function}}

{{Added feature/item|1.6.1|1.6.0|21932|
Reads the entire contents of the file '''starting from the current file position''', optionally verifies the read contents by computing and comparing the checksum with the expected one, and returns the content as string.
}}

Please note that even if you enable SD #22 and #23 on your server, you are not protected from user attacks, which can happen after verification of the file, but before you read the contents of such verified file. This function enables you to safely read the contents of a meta.xml-listed file on both client and server.

==Syntax==
<syntaxhighlight lang="lua">
nil|string fileGetContents ( file theFile [ , bool verifyContents = true ] )
</syntaxhighlight>
{{OOP||[[file]]:getContents}}

===Required Arguments===
*'''theFile:''' A handle to the file you wish to get the contents from. Use [[fileOpen]] to obtain this handle.
*'''verifyContents:''' Set to true, to compare the computed and the expected checksum of the file content

===Returns===
Returns the bytes that were read from the file, but only if verification was disabled or if the checksum comparison succeeded. On failure, this function returns ''nil''.

==Example==
This example opens the file test.txt and outputs its contents to the console.
<syntaxhighlight lang="lua">
local handle = fileOpen("code.lua", true)
local buffer = fileGetContents(handle) -- code.lua must be listed in meta.xml (for example as <file> for this example)
fileClose(handle)

if buffer then
loadstring(buffer)()
end
</syntaxhighlight>

==See Also==
{{File functions}}

FileGetContents

2023-08-07T19:16:30Z

Botder: Created page with "__NOTOC__ {{Server client function}} Reads the entire contents of the file '''starting from the current file position''', optionally verifies the read contents by computing and comparing the checksum with the expected one, and returns the content as string. Please note that even if you enable SD #22 and #23 on your server, you are not protected from user attacks, which can happen after verification of the file, but before you read the contents of such verified file. Th..."

__NOTOC__
{{Server client function}}

Reads the entire contents of the file '''starting from the current file position''', optionally verifies the read contents by computing and comparing the checksum with the expected one, and returns the content as string.

Please note that even if you enable SD #22 and #23 on your server, you are not protected from user attacks, which can happen after verification of the file, but before you read the contents of such verified file. This function enables you to safely read the contents of a meta.xml-listed file on both client and server.

==Syntax==
<syntaxhighlight lang="lua">
nil|string fileGetContents ( file theFile [ , bool verifyContents = true ] )
</syntaxhighlight>
{{OOP||[[file]]:getContents}}

===Required Arguments===
*'''theFile:''' A handle to the file you wish to get the contents from. Use [[fileOpen]] to obtain this handle.
*'''verifyContents:''' Set to true, to compare the computed and the expected checksum of the file content

===Returns===
Returns the bytes that were read from the file, but only if verification was disabled or if the checksum comparison succeeded. On failure, this function returns ''nil''.

==Example==
This example opens the file test.txt and outputs its contents to the console.
<syntaxhighlight lang="lua">
local handle = fileOpen("code.lua", true)
local buffer = fileGetContents(handle) -- code.lua must be listed in meta.xml (for example as <file> for this example)
fileClose(handle)

if buffer then
loadstring(buffer)()
end
</syntaxhighlight>

==See Also==
{{File functions}}

OnExplosion

2023-07-30T13:20:18Z

Botder:

__NOTOC__
{{Server event}}
{{Added feature/item|1.6.1|1.6.0|21914|This event is triggered every time an explosion is created either by server-side [[createExplosion]], or reported by [[player]].}}
==Parameters==
<syntaxhighlight lang="lua">
float x, float y, float z, int theType
</syntaxhighlight>
*'''x:''' X coordinate of where the explosion was created
*'''y:''' Y coordinate of where the explosion was created
*'''z:''' Z coordinate of where the explosion was created
*'''theType:''' the type of explosion created, values are:
{{Explosions}}
==Source==
The [[event system#Event source|source]] of this event is the [[player]] who notified server about explosion, or [[root]] if explosion was created without specifying creator in [[createExplosion]].

===Canceling===
If this event is [[Event system #Canceling|canceled]], the explosion will not occur.

==Example==
This example outputs information about occuring explosion.
<syntaxhighlight lang="lua">
local explosionTypes = {
[0] = "Grenade",
[1] = "Molotov",
[2] = "Rocket",
[3] = "Rocket Weak",
[4] = "Car",
[5] = "Car Quick",
[6] = "Boat",
[7] = "Heli",
[8] = "Mine",
[9] = "Object",
[10] = "Tank Grenade",
[11] = "Small",
[12] = "Tiny",
}

function onExplosion(explosionX, explosionY, explosionZ, explosionType)
local explosionPos = (explosionX..", "..explosionY..", "..explosionZ)
local explosionTypeName = explosionTypes[explosionType]
local explosionSource = inspect(source)

local debugMsg = (explosionTypeName.." explosion has occured at "..explosionPos.." (source: "..explosionSource..")")
local debugMsgLevel = 4
local debugMsgR = 255
local debugMsgG = 127
local debugMsgB = 0

outputDebugString(debugMsg, debugMsgLevel, debugMsgR, debugMsgG, debugMsgB)
end
addEventHandler("onExplosion", root, onExplosion)
</syntaxhighlight>

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

Template:Server events

2023-07-30T13:19:12Z

Botder:

*[[onBan]]
*[[onChatMessage]]
*[[onDebugMessage]]
{{Added feature/item|1.6.1|1.6.0|21914|
*[[onExplosion]]
}}
*[[onSettingChange]]
*[[onUnban]]
<noinclude>[[Category:Events templates]]</noinclude>

Template:Next Stable Version

2023-07-30T13:18:52Z

Botder: Bump next stable version

{{#ifeq:{{{1|}}}|full|Error!|1.6.1}}

Template:Current Stable Version

2023-07-30T13:18:40Z

Botder: Bump stable version

{{#ifeq:{{{1|}}}|full|Error!|1.6.0}}

User:Botder

2023-06-28T15:28:37Z

Botder:

{{MTA Developer}}

== Contact ==
*Discord: '''botder''' (before: '''botder#1218''')
*[https://github.com/botder GitHub Profile]
*[https://forum.mtasa.com/profile/40389-botder/ Forum Profile]

EncodeString

2023-03-21T22:50:56Z

Botder: Add RSA example

__NOTOC__
{{Shared function}}
{{New feature/item|3.0156|1.5.5|11849|
This function encodes a [[string]] using the specified algorithm. The counterpart of this function is [[decodeString]].
}}

{{Tip|If it doesn't matter which algorithm you use for the encoding, keep in mind that ''aes128'' uses hardware acceleration so it may outperform the ''tea'' algorithm on most processors.}}

==Syntax==
<syntaxhighlight lang="lua">
string encodeString ( string algorithm, string input, table options [, function callback ] )
</syntaxhighlight>

===Required Arguments===
*'''algorithm:''' The algorithm to use.
*'''input:''' The input to encode.
*'''options:''' A [[table]] with options and other necessary data for the algorithm, as detailed below.

===Options for each algorithm===
* ''tea'' ([https://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm Tiny Encryption Algorithm])
** '''key''': a key to encode the input with.
{{Added feature/item|1.5.9|1.5.8|20898|
* ''aes128'' ([https://en.wikipedia.org/wiki/Advanced_Encryption_Standard Advanced Encryption Standard] in CTR mode)
** '''key''': a key to encode the input with (must be 16 characters long).
|20898}}
{{Added feature/item|1.5.9|1.5.8|21055|
* ''rsa'' ([https://en.wikipedia.org/wiki/RSA_(cryptosystem) Rivest-Shamir-Adleman] in OAEP with SHA-1 mode)
** '''key''': a public key to encode the input. (use [[generateKeyPair]] to create a new private and public key)
|21055}}

===Optional Arguments===
*'''callback:''' providing a callback will run this function asynchronously, the arguments to the callback are the same as the returned values below.
===Returns for each algorithm===
* ''tea''
** '''encodedString''': the encoded string if successful, ''false'' otherwise. If a callback was provided, ''true'' is returned immediately, and the encoded string is passed as an argument to the callback.
{{New items|3.0159|1.5.8|
* ''aes128''
** '''encodedString''': the encoded string if successful, ''false'' otherwise. If a callback was provided, ''true'' is returned immediately, and the encoded string is passed as an argument to the callback.
** '''iv''' ([https://en.wikipedia.org/wiki/Initialization_vector Initialization vector]): this is a string generated by the encryption algorithm that is needed to decrypt the message by [[decodeString]]. If a callback was provided, ''true'' is returned immediately, and the ''iv'' is passed as an argument to the callback.
|20898}}
{{New items|3.0159|1.5.8|
* ''rsa''
** '''encodedString''': the encoded string if successful, ''false'' otherwise. If a callback was provided, ''true'' is returned immediately, and the encoded string is passed as an argument to the callback.
|21055}}

==Examples==

<section name="Server" class="server" show="true">
Adds an ''/encode'' command in which you can provide an algorithm, key and data to encode. Below is the example provided as both server-side and client-side variations.
<syntaxhighlight lang="lua">
addCommandHandler("encode",
function(player, _, algorithm, key, ...)
if algorithm and key then
local text = table.concat({...}, " ")
if type(text) == "string" and text ~= "" then
local encoded = encodeString(algorithm, text, { key = key })
if encoded then
outputChatBox("The result of " .. algorithm .. " encoding is: " .. encoded, player)
else
outputChatBox("Failed to encode. Make sure that all arguments are valid.", player, 255, 0, 0)
end
else
outputChatBox("Please specify text in the command.", player, 255, 0, 0)
end
else
outputChatBox("Invalid algorithm and/or key.", player, 255, 0, 0)
end
end
)
</syntaxhighlight>

This example shows you how to use the RSA encryption with a simple string message.
<syntaxhighlight lang="lua">
local private, public = generateKeyPair("rsa", { size = 2048 })

local input = "Hello, world!"
local encrypted = encodeString("rsa", input, { key = public })
local decrypted = decodeString("rsa", encrypted, { key = private })

outputServerLog("RSA test: ".. tostring(input == decrypted))
</syntaxhighlight>
</section>

==See Also==
{{Utility functions}}

Template:Utility functions

2022-11-03T14:14:58Z

Botder:

*[[addDebugHook]]
*[[base64Decode]]
*[[base64Encode]]
{{Bit_functions}}
*[[debugSleep]]
{{New items|3.0156|1.5.5|
*[[decodeString]]
|11849}}
*[[deref]]
{{New items|3.0156|1.5.5|
*[[encodeString]]
|11849}}
*[[fromJSON]]

{{Added feature/item|1.6.0|1.5.9|21055|
*[[generateKeyPair]]
}}
*[[getColorFromString]]
*[[getDevelopmentMode]]
*[[getDistanceBetweenPoints2D]]
*[[getDistanceBetweenPoints3D]]
*[[getEasingValue]]
*[[getFPSLimit]]
*[[getNetworkStats]]
*[[getNetworkUsageData]]
*[[getPerformanceStats]]

{{Added feature/item|1.6.0|1.5.9|21389|
*[[getProcessMemoryStats]]
}}
*[[getRealTime]]
*[[getServerConfigSetting]]
*[[getTickCount]]
*[[getTimerDetails]]
*[[getTimers]]
*[[gettok]]
*[[getUserdataType]]
*[[getVersion]]
*[[hash]]
*[[inspect]]
*[[interpolateBetween]]
*[[iprint]]
*[[isOOPEnabled]]
*[[isTimer]]
*[[killTimer]]
*[[md5]]
*[[passwordHash]]
*[[passwordVerify]]
*[[pregFind]]
*[[pregMatch]]
*[[pregReplace]]
*[[removeDebugHook]]
*[[ref]]
*[[resetTimer]]
*[[setDevelopmentMode]]
*[[setFPSLimit]]
*[[setServerConfigSetting]]
*[[setTimer]]
*[[sha256]]
*[[split]]
*[[teaDecode]]
*[[teaEncode]]
{{New items|3.0156|1.5.5|
*[[tocolor]]
|13977}}
*[[toJSON]]
*[[utfChar]]
*[[utfCode]]
*[[utfLen]]
*[[utfSeek]]
*[[utfSub]]

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

GetProcessMemoryStats

2022-11-03T14:12:09Z

Botder: Created page with "__NOTOC__ {{Shared function}} {{Added feature/item|1.6.0|1.5.9|21389|This function returns a breakdown of the process memory usage. The reported numbers are always byte units and these numbers can be '''inaccurate'''.}} ==Syntax== <syntaxhighlight lang="lua"> table|nil getProcessMemoryStats ( ) </syntaxhighlight> ==Returns== Returns a table if successful, otherwise returns '''nil''' {| class="wikitable" style="cellpadding: 10px;" |- ! Property || Description |- | <c..."

__NOTOC__
{{Shared function}}
{{Added feature/item|1.6.0|1.5.9|21389|This function returns a breakdown of the process memory usage. The reported numbers are always byte units and these numbers can be '''inaccurate'''.}}

==Syntax==
<syntaxhighlight lang="lua">
table|nil getProcessMemoryStats ( )
</syntaxhighlight>

==Returns==
Returns a table if successful, otherwise returns '''nil'''

{| class="wikitable" style="cellpadding: 10px;"
|-
! Property || Description
|-
| <code>virtual</code> || total program size
|-
| <code>resident</code> || resident set size (memory in physical space/ram, also known as ''working set'')
|-
| <code>shared</code> || size of resident shared memory (shared with other processes)
|-
| <code>private</code> || size of resident private memory (only for this process)
|}

'''Note:''' Resident set size should be roughly <code>shared</code> + <code>private</code> from the table.

==Example==
This example will output the memory usage by the server process to the console every 5 minutes.

<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
setTimer(function()
local div = 1024^2

local pmem = getProcessMemoryStats()

if pmem then
outputServerLog(("[SYS] %.2f MiB rss:%.2f MiB shr:%.2f MiB prv:%.2f MiB"):format(
pmem.virtual / div,
pmem.resident / div,
pmem.shared / div,
pmem.private / div
))
end
end, 5 * 60000, 0)
</syntaxhighlight>
</section>

==See Also==
{{Utility functions}}

EngineReplaceModel

2022-11-03T13:27:33Z

Botder:

__NOTOC__
{{Client function}}

This function replaces the given model ID with the model contained in a DFF file loaded by [[engineLoadDFF]]. This function supports [[vehicle|vehicles]], [[object|objects]], [[ped|peds]] and [[player|players]] but not CJ clothing and body parts.

{{Deprecated feature|3.0111|1.1.1|This function does not support ped and weapon models.}}

To replace weapon models you must use their object IDs, not weapon IDs. There is a weapon model list available at [[weapons]].
{{Note|
* Please note the loading order that is used in the examples as other orders can cause collisions, textures or the DFF not to load due to technical limitations.
* Default GTA map objects behave inconsistently when using this function on them. If you want to replace models in the original GTA map, use one of the [[EngineReplaceModel notes|methods shown here]].
* A raw data DFF element can only be used once, because the underlying memory for the model is released after replacement.
* If the replacement model is broken and the original model is not loaded/streamed-in at the time of replacement, this function will succeed and you won't see any error message, neither when the model replacement fails once the original model starts to load/stream-in.}}

==Syntax==
<syntaxhighlight lang="lua">
bool engineReplaceModel ( dff theModel, int modelID [, bool alphaTransparency = false ] )
</syntaxhighlight>
{{OOP||[[DFF|dff]]:replace}}
===Required Arguments===
*'''theModel:''' The model to replace the given model ID with
*'''modelID:''' The model it to replace the model of

===Optional Arguments===
*'''alphaTransparency:''' Set to true if model uses semi-transparent textures, e.g. windows. This will ensure other objects behind the semi-transparent textures are rendered correctly. (Can slightly impact performance, so only set when required)

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

==Example==
<section name="Client" class="client" show="true">
This example allows you to replace single or many models (with ability to toggle TXD filtering/DFF alpha transparency) - by using [[table]]. Do not forget to add those file paths to [[meta.xml]]
<syntaxhighlight lang="lua">
function onClientResourceStartReplaceModels()
local modelsToReplace = {
{ -- replace object
colFile = "object.col",
txdFile = "object.txd",
dffFile = "object.dff",
modelID = 1337,
alphaTransparency = false,
filteringEnabled = true,
},
{ -- replace vehicle
colFile = false, -- if .col is not present set to false/nil
txdFile = "vehicle.txd",
dffFile = "vehicle.dff",
modelID = 434,
alphaTransparency = false,
filteringEnabled = true,
},
}

for assetID = 1, #modelsToReplace do
local modelData = modelsToReplace[assetID]
local modelCol = modelData.colFile
local modelTxd = modelData.txdFile
local modelDff = modelData.dffFile
local modelID = modelData.modelID

if modelCol then
local colData = engineLoadCOL(modelCol)

if colData then
engineReplaceCOL(colData, modelID)
end
end

if modelTxd then
local filteringEnabled = modelData.filteringEnabled
local txdData = engineLoadTXD(modelTxd, filteringEnabled)

if txdData then
engineImportTXD(txdData, modelID)
end
end

if modelDff then
local dffData = engineLoadDFF(modelDff)

if dffData then
local alphaTransparency = modelData.alphaTransparency

engineReplaceModel(dffData, modelID, alphaTransparency)
end
end
end
end
addEventHandler("onClientResourceStart", resourceRoot, onClientResourceStartReplaceModels)
</syntaxhighlight>
</section>

==See Also==
{{Engine_functions}}

How you can help

2022-11-03T13:16:07Z

Botder: Reverted edits by Absolwent (talk) to last revision by Lopez

__NOTOC__
Multi Theft Auto has loads of areas in which you can help us. In turn, we'll be more than happy to help you get started with any ideas you have, help test them and - if they're good enough - release them to the whole community. This page outlines the key areas you could do something in, of course, there are many things we've not thought of, so think outside the box!

==Coding for MTA:SA==
* Become a patch contributor by sending [https://github.com/multitheftauto/mtasa-blue/pulls pull requests] to MTA, containing requested features or bugfixes. ([https://github.com/multitheftauto/mtasa-blue/blob/master/CONTRIBUTING.md#contributors-guide Coding guidelines])
* Translate MTA:SA to your native language - https://translate.multitheftauto.com/

==Scripting==
* Become a contributor to MTA's official resources by sending [https://github.com/multitheftauto/mtasa-resources/pulls pull requests] to our resources repository
* Create and [https://community.mtasa.com/ publish] a gamemode or useful script
**[[Scripting Introduction]]
**[https://www.lua.org/pil/index.html "Programming in Lua" Manual]
* Make a general purpose resource that provides useful functions to other resources.

==Mapping==
* Create and [https://community.mtasa.com/ publish] a map for an existing gamemode, with the map editor.
**[[Resource:Editor|Map Editor Manual]]

==Web development==
* Create your own system for statistics - using the [[PHP SDK]] as a basis. Join the [https://discord.gg/RygaCSD MTA discord] (or [https://discord.gg/GNN6PRtTnu development discord]) for help.

==Documentation==
Before you make changes check out: [[Help:Editing Guidelines|Editing Guidelines]] and [[Help:MTA Wiki Specific Templates|Specific Templates]]
* Finish documentation for [[:Category:Incomplete|Incomplete functions]] - ask in #mta.scripting if you're not sure of something.
* Add examples to [[:Category:Needs Example|functions & events missing examples]] - please '''test''' them, and again, ask if you need help.
* Review and verify [[:Category:Needs Checking|pages that need checking]] - make sure highlighted issues are solved before removing pages from the category.
* Expand the pages that explain [[:Category:Scripting_Concepts|MTA core concepts]].
* Write [https://forum.mtasa.com/forum/123-tutorials/ tutorials] to help new people.
* Translate the wiki pages so people from other countries can get started in MTA too.
* Create documentation for undocumented functions and events [[Undocumented Items]]
* Keep 'changes in' [current work-in-progress: https://wiki.multitheftauto.com/wiki/Changes_in_1.6] for future releases updated.

==Quality Assurance==
* [https://github.com/multitheftauto/mtasa-blue/issues Report issues] with the mod, make sure to do a search on the already reported issues first.
* Test and confirm existing reported issues.
* Use the newest build of MTA to detect and report new bugs, by going to 'Settings', 'Advanced', 'Update build type' and choosing 'Nightly' or get it regularly [https://nightly.mtasa.com/ from here].
* Any bugs which are related to a scripting function / event and present in the main release (rather than nightlies), document that bug by adding a [https://wiki.multitheftauto.com/wiki/Help:MTA_Wiki_Specific_Templates warning] to the wiki page to save other scripters a lot of time.

==Specific tasks==
* Create a fuzzer to check for crashes in our scripting functions.

==Grant==
You can donate to MTA:SA [https://mtasa.com/donate/manage.php here]

[[ar:كيف_يمكنك_المساعدة]]
[[en:How you can help]]
[[ru:How you can help]]
[[pl:Jak możesz pomóc]]
[[uk:How you can help]]
[[es:Cómo puedes ayudar]]
[[hu:How you can help]]
[[tr:Nasıl yardımcı olabilirsiniz]]
[[pt-br:Como você pode ajudar]]

Strona główna

2022-11-03T13:15:56Z

Botder: Reverted edits by Absolwent (talk) to last revision by Tracer

{| width="100%" cellspacing="0" cellpadding="0"
| colspan="2" |
<div style="/*border: 1px solid #D8D8D8;*/ padding-left: 15px; padding-right: 15px; height: 100%;">
[[File:Mtalogo.png|left|100px|link=http://wiki.multitheftauto.com/]]'''Witaj na polskiej wiki [[PL/Multi Theft Auto|Multi Theft Auto]].''' Znajdziesz tutaj wiele informacji na temat korzystania z Multi Theft Auto.

Jest wiele [[PL/How you can help|rzeczy które możesz zrobić]], aby pomóc nam w rozwijaniu MTA - stworzyć mapę, tryb gry, pomóc w dokumentowaniu funkcji, napisać przykładowy kod, napisać poradnik lub po prostu grać w MTA i zgłaszać błędy, które znajdziesz.

Jeśli masz jakieś pytania bądź problemy związane z pisaniem skryptów, zapytaj nas na [[PL/IRC Channel|kanale IRC]].
 [ Przestań się bawić ze sobą ]
</div>
|}
{| width="100%" cellspacing="0" cellpadding="0"
| colspan="2" |
|-
|width="50%" style="vertical-align:top;" |<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px; background: #FFFCF2;">
<div style="float:right; width: 32px;">[[File:Input-gaming.png‎|link=]]</div>
<h3>Graj</h3>
<div style="background: #FFEEAA; border: 1px solid #FFCD19;">
[[File:Go-down.png|link=http://mtasa.com/]] ''' [http://mtasa.com/ Pobierz Multi Theft Auto: San Andreas {{Current Version|full}}]'''</div>
* [[PL/Where to buy GTASA|Gdzie kupić GTASA]] [[Image:Plflag.png|Artykuł w języku polskim]]
* [[PL/Client Manual|Obsługa klienta]] [[Image:Plflag.png|Artykuł w języku polskim]]

* [[Changes_in_{{padleft:|5|{{Current Version|full}}}}|Zmiany w {{padleft:|5|{{Current Version|full}}}}]] [[Image:usen.gif|Artykuł w języku angielskim]]
* [[PL/Known_Issues_-_FAQ|Znane problemy]] [[Image:Plflag.png|Artykuł w języku polskim]] / [[Image:usen.gif|Artykuł w języku angielskim]]
* [[PL/Migracja_z_MTA:Race_do_MTA:SA_1.0.x|Migracja z MTA:Race do MTA:SA {{padleft:|3|{{Current Version|full}}}}]] [[Image:Plflag.png|Artykuł w języku polskim]]
* [[PL/Server Manual|Obsługa serwera]] [[Image:Plflag.png|Artykuł w języku polskim]]
* [[Map manager|Menadżer map]] [[Image:usen.gif|Artykuł w języku angielskim]]

<h3>Edytor map</h3>
*[[PL/Resource:Editor|Instrukcja]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Resource:Editor/EDF|Edytor Właściwości Mapy]] [[Image:Plflag.png|Artykuł w języku polskim]] / [[Image:usen.gif|Artykuł w języku angielskim]]
*[[Resource:Editor/Plugins|Pluginy]] [[Image:usen.gif|Artykuł w języku angielskim]]
*[[PL/Resource:Editor#FAQ|Najczęściej zadawane pytania]] [[Image:Plflag.png|Artykuł w języku polskim]]
</div>
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;">
<div style="float:right; width: 32px;">[[File:Package-x-generic.png‎|link=]]</div>
<h3>Bazy danych</h3>
Ta sekcja opisuje wszystkie możliwości Lua umożliwiane przez MTA lub zasoby.
* [[PL/Category:Resource|Katalog zasobów]] - Musisz je poznać, aby tworzyć właściwe skrypty
* [[PL/Client side scripts|Skrypty po stronie klienta]] [[Image:Plflag.png|Artykuł w języku polskim]]
* [[Moduły]] [[Image:Plflag.png|Artykuł w języku polskim]]
</div>

<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;">
<div style="float:right; width: 32px;">[[File:Applications-development.png‎‎‎|link=]]</div>
<h3>Rozwijanie Multi Theft Auto</h3>
[[File:Go-down.png|link=http://nightly.mtasa.com/]] [http://nightly.mtasa.com/ Nightly builds]
* [[Compiling_MTASA|Kompilacja MTASA na Windows]] [[Image:usen.gif|Artykuł w języku angielskim]]
* [[Building_MTASA_Server_on_GNU_Linux|Kompilacja MTASA na GNU/Linux]] [[Image:usen.gif|Artykuł w języku angielskim]]
* [[Coding guidelines|Wytyczne dot. pisania kodu]] [[Image:usen.gif|Artykuł w języku angielskim]]
* [https://github.com/multitheftauto/mtasa-blue Repozytorium Github]
* [[Roadmap]] [[Image:usen.gif|Artykuł w języku angielskim]]
* [http://bugs.mtasa.com/ Bugtracker]
* [[Branches|Branże]] [[Image:usen.gif|Artykuł w języku angielskim]]
</div>
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;">
<div style="float:right; width: 32px;">[[File:Applications-office.png|link=]]</div>
<h3>Polskie Wiki - jak możesz pomóc?</h3>
* Pomóż tłumaczyć hasła, przy których jest angielska flaga
* Twórz hasła, które istnieją w angielskiej wiki, a których u nas brakuje
** Staraj się, aby nowe artykuły miały takie same nazwy (angielskie), a jedynie poprzedzane były przedrostkiem PL/ - przykład: [[PL/Character_Skins]]
* Zwołaj znajomych, informuj na forach, niech inni dowiedzą się o takiej możliwości!
* Jeśli nie masz pomysłu na edycję, wykonaj coś z [[PL/Todo|tej listy]]. Możesz ją także rozbudować.
</div>

<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;">
<div style="float:right; width: 32px;">[[File:Internet-group-chat.png‎|link=]]</div>
<h3>Społeczność</h3>
* [http://forum.multitheftauto.com/ Forum]
* Discord: [https://forum.mtasa.com/topic/95008-multi-theft-autos-official-discord-server/ Oficjalny serwer Discord MTA]
* IRC: [irc://irc.multitheftauto.com/mta irc.multitheftauto.com #mta]
* [http://community.mtasa.com/ MTA Community] - dodaj lub pobierz skrypty
* [http://twitter.com/#!/MTAQA/ Twitter] - [http://www.youtube.com/user/MTAQA Youtube] - [http://plus.google.com/102014133442331779727/ Google+] - [http://www.moddb.com/mods/multi-theft-auto-san-andreas ModDB]
</div>

| width="50%" style="vertical-align:top;" |

<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;">
<div style="float:right; width: 32px;">[[File:Accessories-text-editor.png|link=]]</div>
<h3>Skryptowanie</h3>
* [[Wstęp do pisania skryptów]] [[Image:Plflag.png|Artykuł w języku polskim]]
* [[Wstęp do pisania skryptów GUI]] [[Image:Plflag.png|Artykuł w języku polskim]]
* [[Debugging|Poradnik debugowania]] [[Image:usen.gif|Artykuł w języku angielskim]] - Jak znaleźć błędy w swoich skryptach
* [[PL/Zasoby|Wstęp do zasobów]] [[Image:Plflag.png|Artykuł w języku angielskim]]
** [[Resource Web Access|Dostęp WWW do zasobów]] [[Image:usen.gif|Artykuł w języku angielskim]] - Jak pisać strony WWW z wykorzystaniem zasobów
** [[:Category:Resource|Katalog zasobów]] [[Image:usen.gif|Artykuł w języku angielskim]]
** [[PL/Meta.xml|Meta.xml]] [[Image:Plflag.png|Artykuł w języku polskim]] - każdy zasób jest definiowany przez plik meta
** [[ACL]] [[Image:usen.gif|Artykuł w języku angielskim]] - Access Control List, który jest niezbędny, aby skrypty działały
* [[Writing_Gamemodes|Pisanie gamemodów]] [[Image:usen.gif|Artykuł w języku angielskim]]
* [[Przydatne Funkcje]] [[Image:Plflag.png|Artykuł w polskim]]
Linki na fora
* [https://forum.mtasa.com/forum/71-scripting/ Forum na temat skryptowania]
* [https://forum.mtasa.com/forum/123-tutorials/ Forum z poradnikami do skryptowania]
* [https://forum.mtasa.com/topic/24702-mtasa-wiki-offline-copies-online-mirrors/ Kopie Wiki]
<div style="float:right; width: 32px;">[[File:start-here.png|link=]]</div>
<h3>Pomoc dotycząca LUA</h3>
Strony zaprojektowane, by pomóc Ci zrozumieć język LUA.
*[http://www.lua.org/pil/index.html "Programming in Lua" Manual]
**[http://www.lua.org/manual/5.1/#index Internal Lua functions reference]
*[http://lua-users.org/wiki/TutorialDirectory Lua Wiki]
*[http://nixstaller.sourceforge.net/manual/0.5.1/nixstaller_10.html A general guide to Lua from Nixstaller]
</div>

<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px; background:#F2F2FF;">
<div style="float:right; width: 32px;">[[File:Preferences-system.png|link=]]</div>
<h3>Odwołania</h3>
* [[PL/Funkcje po stronie klienta|Funkcje po stronie klienta]] [[Image:Plflag.png|Artykuł w języku polskim]]
* [[PL/Client Scripting Events|Zdarzenia po stronie klienta]] [[Image:Plflag.png|Artykuł w języku polskim]]
* [[PL/Server Scripting Functions|Funkcje po stronie serwera]] [[Image:Plflag.png|Artykuł w języku polskim]]
* [[Server Scripting Events|Zdarzenia po stronie serwera]] [[Image:usen.gif|Artykuł w języku angielskim]]

* [[PL/MTA Classes|Klasy MTA]] [[Image:Plflag.png|Artykuł w języku polskim]] / [[Image:usen.gif|Artykuł w języku angielskim]] -- Szczegółowe opisy wszystkich typów MTA
** [[PL/Element|Elementy MTA]] [[Image:Plflag.png|Artykuł w języku angielskim]] / [[Element tree|Drzewo elementów]] [[Image:usen.gif|Artykuł w języku angielskim]]
</div>
<div style="border: 1px solid #D8D8D8; padding:4px 8px 8px 8px; margin:10px;">
<div style="float:right; width: 32px;">[[File:System-file-manager.png|link=]]</div>
<h3>[[PL/Id|Listy ID]]</h3>
*[[PL/Animations|Animacje]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Character Skins|Skiny postaci]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/CJ_Clothes|Ubrania]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Garage|Garaże]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Interior IDs|Interiory]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Material IDs|Materiały]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Projectiles|Pociski]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Radar Blips|Znaczniki]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Sounds|Dźwięki]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Vehicle IDs|Pojazdy]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Vehicle Colors|Kolory pojazdów]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Vehicle Upgrades|Modyfikacje pojazdów]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Vehicle variants|Warianty pojazdów]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Vehicle component manipulation|Manipulowanie komponentami pojazdów]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Weapons|Bronie]] [[Image:Plflag.png|Artykuł w języku polskim]]
*[[PL/Weather|Pogoda]] [[Image:Plflag.png|Artykuł w języku polskim]] / [[Image:usen.gif|Artykuł w języku angielskim]]
</div>
<div style="padding:4px 8px 8px 8px; margin:10px;">
[[File:Osi symbol.png|75px|link=http://opensource.org/|left]]
'''Multi Theft Auto''' jest '''Otwartym Oprogramowaniem'''.
 To znaczy, że każdy może pomóc w byciu Multi Theft Auto lepszym!
</div>
|-
| colspan="2" |
|}
{| width="100%" cellspacing="0" cellpadding="0"
| colspan="2" |
<div style="padding-left: 15px; padding-right: 15px;" class="plainlinks">
[[File:MTALogo_8ball.png|left|85px|link=Archive]]
<ul style="list-style: none; width: 200px; float: left;">
<li>'''O [[PL/Multi Theft Auto|Multi Theft Auto]]'''</li>
<li>[[PL/Archive|Archiwum]]</li>
<li>[[Press Coverage|MTA w mediach]]</li>
<li>[http://code.google.com/p/mtasa-blue/people/list Developerzy]</li>
</ul>
<ul style="list-style: none; width: 200px; float: left;">
<li>'''Multi Theft Auto 0.5'''</li>
<li>[[PL/Archive#Multi_Theft_Auto_0.5|Pobierz]]</li>
<li>[[MTA 0.5r2 Known Issues|Zauważone problemy]]</li>
</ul>
<ul style="list-style: none; width: 200px; float: left;">
<li>'''Statystyki Wiki'''</li>
<li>{{NUMBEROFARTICLES}} artykuły</li>
<li>{{NUMBEROFPAGES}} strony</li>
<li>{{NUMBEROFFILES}} pliki</li>
</ul>
<ul style="list-style: none; width: 240px; float: left;">
<li>{{NUMBEROFEDITS}} edycji</li>
<li>{{NUMBEROFADMINS}} administratorów</li>
<li>{{NUMBEROFUSERS}} zarejestrowanych użytkowników</li>
<li>{{NUMBEROFACTIVEUSERS}} aktywnych użytkowników</li>
</ul>
</div>
|}

__NOTOC__
__NOEDITSECTION__
{{Languages list|pl}}

RU/Shared Scripting Functions

2022-07-10T15:21:18Z

Botder: Add XML translations

<pageclass class="both"></pageclass>
{{RU/Adding_Pages_to_Categories_and_Templates}}
На этой странице перечислены все '''shared''' скриптовые функции, которые были реализованы и доступны как собственные функции из мода Deathmatch.

Для получения дополнительных функций посмотрите [[Useful_Functions|страницу полезных функций]].
__TOC__

==Функции ввода==
{{Shared_input_functions}}

==Функции взрыва==
{{Shared_explosion_functions}}

==Функции воды==
{{RU/Shared_water_functions}}

==Функции вывода==
{{Shared_output_functions}}

==Функции звука==
{{Shared_sound_functions}}

==Функции игрока==
{{Shared_player_functions}}

==Функции камеры==
{{Shared_camera_functions}}

==Функции коллизии==
{{Shared_collision_shape_functions}}

==Функции курсора==
{{Shared_cursor_functions}}

==Функции маркера==
{{Shared_marker_functions}}

==Функции матрицы==
{{Shared_matrix_functions}}

==Функции меток на радаре==
{{Shared_blip_functions}}

==Функции мира==
{{Shared_world_functions}}

==Функции объекта==
{{Shared_object_functions}}

==Функции оружия==
{{RU/Shared_weapon_functions}}

==Функции пешехода (NPC)==
{{Shared_ped_functions}}

==Функции пикапа==
{{Shared_pickup_functions}}

==Функции ресурса==
{{RU/Shared_resource_functions}}

==Функции сервера==
{{Shared_server_functions}}

==Функции снаряда==
{{Shared_projectile_functions}}

==Функции события==
{{RU/Shared_event_functions}}

==Функции тела и одежды==
{{Shared_clothes_and_body_functions}}

==Функции территории радара==
{{Shared_radar_functions}}

==Функции транспорта==
{{Shared_vehicle_functions}}

==Функции утилит==
{{Shared_utility_functions}}

==Файловые функции==
{{Shared_file_functions}}

==Функции элемента==
{{RU/Shared_element_functions}}

==Функции UTF-8==
{{Shared_utf8_functions}}

==Функции XML==
{{RU/Shared_XML_functions}}

[[en:Shared Scripting Functions]]

Shared Scripting Functions

2022-07-10T15:19:16Z

Botder: Undo last two edits

<pageclass class="both"></pageclass>
{{Adding_Pages_to_Categories_and_Templates}}
This page lists all the '''shared''' scripting functions that have been implemented and are available as native functions from the Deathmatch mod. To request a function or event, use [[Requested Functions and Events]]

For more functions, check the [[Useful_Functions|useful functions page]].
__TOC__

==Element functions==
{{Shared_element_functions}}

==Ped functions==
{{Shared_ped_functions}}

==Player functions==
{{Shared_player_functions}}

==Weapon functions==
{{Shared_weapon_functions}}

==Sound functions==
{{Shared_sound_functions}}

==Blip functions==
{{Shared_blip_functions}}

==Camera functions==
{{Shared_camera_functions}}

==Clothes and body functions==
{{Shared_clothes_and_body_functions}}

==Collision shape functions==
{{Shared_collision_shape_functions}}

==Cursor functions==
{{Shared_cursor_functions}}

==Event functions==
{{Shared_event_functions}}

==Explosion functions==
{{Shared_explosion_functions}}

==File functions==
{{Shared_file_functions}}

==Input functions==
{{Shared_input_functions}}

==Marker functions==
{{Shared_marker_functions}}

==Matrix functions==
{{Shared_matrix_functions}}

==Object functions==
{{Shared_object_functions}}

==Output functions==
{{Shared_output_functions}}

==Pickup functions==
{{Shared_pickup_functions}}

==Projectile functions==
{{Shared_projectile_functions}}

==Radar functions==
{{Shared_radar_functions}}

==Resource functions==
{{Shared_resource_functions}}

==Server functions==
{{Shared_server_functions}}

==Utility functions==
{{Shared_utility_functions}}

==UTF8 Library==
{{Shared_utf8_functions}}

==Vehicle functions==
{{Shared_vehicle_functions}}

==Water functions==
{{Shared_water_functions}}

==World functions==
{{Shared_world_functions}}

==XML functions==
{{Shared_xml_functions}}

[[ru:Shared Scripting Functions]]

Template:Useful Functions

2022-07-01T18:36:20Z

Botder: /* Gridlists */

__NOTOC__
=== Table functions ===
*[[addTableChangeHandler]] » This function monitors the changes of 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.empty]] » This function checks whether a table is empty.
*[[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.
*[[table.toString]] » This function converts table to a string.

=== ACL functions ===
*[[aclGroupClone]] » This function clone a group to another group with/without ACLs and/or objects.
*[[getAccountsRanks]] » This function is used to detect the account name groups and put them in the chat.
*[[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.

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

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

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

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

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

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

=== Data functions ===
*[[byte2human]] » This function converts an integer (number of bytes) into a human-readable unit.
*[[capitalize]] » This function capitalizes a given string.
*[[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.
*[[getFreeDimension]] » This function get free dimension.
*[[getKeyFromValueInTable]] » This function returns the key of the specified value in a table.
*[[getOffsetFromXYZ]] » This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.
*[[getPointFromDistanceRotation]] » This function finds a point based on a starting point, direction and distance.
*[[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.
*[[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 ===
*[[getAlivePlayers (Client)|getAlivePlayers]] » This function returns a table of the alive players client-side.
*[[getAlivePlayersInTeam]] » This function returns a table of the alive players in a team.
*[[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.
*[[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.
*[[isPlayerHitByVehicle]]» This function cancels event when a element is hit by a vehicle.
*[[warpToPlayer]]» This function make player warp to another player.

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

=== 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 r
epeatedly 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.
*[[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.
*[[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.

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

Template:Useful Functions

2022-07-01T18:27:10Z

Botder:

__NOTOC__
=== Table functions ===
*[[addTableChangeHandler]] » This function monitors the changes of 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.empty]] » This function checks whether a table is empty.
*[[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.
*[[table.toString]] » This function converts table to a string.

=== ACL functions ===
*[[aclGroupClone]] » This function clone a group to another group with/without ACLs and/or objects.
*[[getAccountsRanks]] » This function is used to detect the account name groups and put them in the chat.
*[[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.

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

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

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

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

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

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

=== Data functions ===
*[[byte2human]] » This function converts an integer (number of bytes) into a human-readable unit.
*[[capitalize]] » This function capitalizes a given string.
*[[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.
*[[getFreeDimension]] » This function get free dimension.
*[[getKeyFromValueInTable]] » This function returns the key of the specified value in a table.
*[[getOffsetFromXYZ]] » This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.
*[[getPointFromDistanceRotation]] » This function finds a point based on a starting point, direction and distance.
*[[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.
*[[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.
*[[guiGridListSetColumnsFixedWidth]] » This function makes a gridlist have all its columns fixed width.
*[[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 ===
*[[getAlivePlayers (Client)|getAlivePlayers]] » This function returns a table of the alive players client-side.
*[[getAlivePlayersInTeam]] » This function returns a table of the alive players in a team.
*[[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.
*[[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.
*[[isPlayerHitByVehicle]]» This function cancels event when a element is hit by a vehicle.
*[[warpToPlayer]]» This function make player warp to another player.

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

=== 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 r
epeatedly 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.
*[[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.
*[[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.

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

GetDistanceBetweenElements

2022-07-01T18:26:25Z

Botder:

{{Useful Function}}

Function to obtain the distance between one element and another.

<lowercasetitle/>

==Syntax==
<syntaxhighlight lang="lua">int getDistanceBetweenElements(element arg1, element arg2)</syntaxhighlight>

===Required Arguments===
* '''arg1''': first element.
* '''arg2''': second element.

===Returns===
Returns the distance between two elements.

==Code==
<section name="Client/Server - side" class="both" show="true">
<syntaxhighlight lang="lua">
function getDistanceBetweenElements(arg1, arg2)
local element1 = Vector3(getElementPosition( arg1 ))
local element2 = Vector3(getElementPosition( arg2 ))
local distance = getDistanceBetweenPoints3D( element1,element2 )
return distance
end
</syntaxhighlight>
</section>

==See Also==
{{Useful_Functions}}

File:Visual Studio Community.PNG

2021-12-07T21:09:27Z

Botder: Botder uploaded a new version of File:Visual Studio Community.PNG

Compiling MTASA

2021-12-07T21:08:31Z

Botder: Visual Studio 2022 update

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

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

== Prerequisites ==

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

Make sure you have the following software and SDKs installed:

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

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

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

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

{| class="wikitable" style="margin-top: 0px; width: 70%; word-break: break-all;"
|+ File verification
|- style="vertical-align:bottom;"
! colspan="2" | Algorithm and variant
! Hash
! Hash file
|- style="text-align:center;vertical-align:center;"
| rowspan="6" | '''{{nowrap|SHA-3}}''' || ''SHA3-224'' || 8bfcdc03518d7edd34689534fd4d21291469ff2f2eb10437ad648c58 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-224 DXSDK_Aug09.exe.sha3-224]
|- style="text-align:center;vertical-align:center;"
| ''SHA3-256'' || 45bf3e08da3b3636ddb4f4a74243430f8d65759c074c0d79756ef810c4701c5a || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-256 DXSDK_Aug09.exe.sha3-256]
|- style="text-align:center;vertical-align:center;"
| ''SHA3-384'' || b358e529963d6f5fd7f8bd4b530fb18f6a2e6a442009a54e981b2f9967589ed48150af310f283640d56f9b60d41100c9 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-384 DXSDK_Aug09.exe.sha3-384]
|- style="text-align:center;vertical-align:center;"
| ''SHA3-512'' || 43522187053af744250059ef69c0f3083cecd1157fe56daac16b9497ebc6fb5b525875144e42898367c55f757cffd3526f37074d544470578602a5a944a45a75 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-512 DXSDK_Aug09.exe.sha3-512]
|- style="text-align:center;vertical-align:center;"
| ''SHAKE128'' || 2a7c81bde9e867cbb5ef00b72ad8de66a3ee64c1d59f16465fa712479b6a84d28a02cc5ed08afa1d51e72011657453dbd4656cc9340d32e18179c39d03982dfc35c8f0c2a5c99e11dc74d0e23ed21b1e55f19c809a5a152bde39a2d46fcd12421f373f2d691ade1b57faf6c2ab7aded5a7d174f1f1c77127c0d6a1523b4775c569c5e1b4efa2da4bf2f708a96707a709e245a7f507382e69a81777919c90e95a091c0b699ce7f517 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-128000 DXSDK_Aug09.exe.sha3-128000]
|- style="text-align:center;vertical-align:center;"
| ''SHAKE256'' || 9c100dac5245a61774f3a2752bf9e941bdcd5654b18035155161c63b20936dfc9bd7334feb9a6fe9a99a65491161083b39ac3bd578e2cf4f90cba3c786e9924fa0611f65a725331b77b63e7c8b552e1637bc77531ba0f2c9cac72115b28e523929ede4e5b246a0755e8d5c4089d94bf16627fb08672cfffa523bba3d976489a0eec60d3c6a96ca2b || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha3-256000 DXSDK_Aug09.exe.sha3-256000]
|- style="text-align:center;vertical-align:center;"
| rowspan="6" | '''{{nowrap|SHA-2}}''' || ''SHA-224'' || a3a74b89cccfe314b79418d5598aac5e94800221e5d945c74f15c004 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-224 DXSDK_Aug09.exe.sha2-224]
|- style="text-align:center;vertical-align:center;"
| ''SHA-256'' || 4ab1de69312f10f6b41310a5218d80c478bbd823bc0f86627318d690b128fb9f || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-256 DXSDK_Aug09.exe.sha2-256]
|- style="text-align:center;vertical-align:center;"
| ''SHA-384'' || 254ed29c6ad2cadc6f013d2d51c0ac78a6bbe236a2c94ca99610eba8b2c1200d1a62c445ca9ee51bb09354875d5eca8a || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-384 DXSDK_Aug09.exe.sha2-384]
|- style="text-align:center;vertical-align:center;"
| ''SHA-512'' || style="width: 60%;" | 736393c0dfa32221e229890f87eb330174d70dd2a02fa0cace303816d3e7a10a332a44129748de39665d1b339e627d6028c2080268f7afdd5240c447fec8ff0b || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-512 DXSDK_Aug09.exe.sha2-512]
|- style="text-align:center;vertical-align:center;"
| ''SHA-512/224'' || 7e23d9ba916000782a17e23abf48e25237f45590cfe767aed9d79f10 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-512224 DXSDK_Aug09.exe.sha2-512224]
|- style="text-align:center;vertical-align:center;"
| ''SHA-512/256'' || 0c833a56046fe7e4213fcb1862c730acf313d1b8f60b51eebf64dc3e79730c1c || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha2-512256 DXSDK_Aug09.exe.sha2-512256]
|- style="text-align:center;vertical-align:center;"
| colspan="2" | '''MD5''' || 66e5379ecf46b014688779621bcc677c || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.md5 DXSDK_Aug09.exe.md5]
|- style="text-align:center;vertical-align:center;"
| colspan="2" | '''{{nowrap|SHA-1}}''' || 5b9b969ed7b6cf5534bb7350e44c09b3573b0e71 || [https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sha1 DXSDK_Aug09.exe.sha1]
|}
CRC32 e9f5c61d ([https://assets.mtasa.com/DXSDK/DXSDK_Aug09.exe.sfv DXSDK_Aug09.exe.sfv]) 

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

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

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

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

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

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

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

== Getting the latest source code ==

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

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

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

= Running the software =

== Running the client ==

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

== Running the dedicated server ==

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

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

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

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

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

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

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

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

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

= Additional information =
If you need more information, try our [http://bugs.mtasa.com/ bug tracker] or [irc://irc.multitheftauto.com IRC channel].

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

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

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

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

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

File:VsFoundationClasses.png

2021-12-07T21:08:05Z

Botder: Botder uploaded a new version of File:VsFoundationClasses.png

File:Skinid106.jpg

2021-10-21T01:44:54Z

Botder: Botder reverted File:Skinid106.jpg to an old version

User:ZJK

2021-10-13T17:32:13Z

Botder: Botder moved page User:ZJK to User:Djebzer: Automatically moved page while renaming the user "ZJK" to "Djebzer"

#REDIRECT [[User:Djebzer]]

Talk:SetPedBleeding

2021-09-03T12:01:42Z

Botder: Created page with "--~~~~ @Hydra The example overall wasn't good."

--[[User:Botder|Botder]] ([[User talk:Botder|talk]]) 12:01, 3 September 2021 (UTC)
@Hydra
The example overall wasn't good.

SetPedBleeding

2021-09-03T11:59:17Z

Botder: Reverted edits by Hydra (talk) to last revision by StrixG

{{Client function}}
__NOTOC__
{{New feature/item|3.0159|1.5.8|20935|This function allows you to set [[player|player's]] or [[ped|ped's]] bleeding effect.}}
==Syntax==
<syntaxhighlight lang="lua">bool setPedBleeding( ped thePed, bool bleeding ) </syntaxhighlight>
{{OOP||[[ped]]:setBleeding|bleeding|isPedBleeding}}

===Required Arguments===
*'''thePed:''' the player or ped whose bleeding effect you want to set of.
*'''bleeding:''' boolean specifying whether the player or ped is bleeding or not.

===Returns===
Returns ''true'' if the bleeding state was successfully set, ''error'' is raised otherwise.

==Example==
{{Example}}

==Requirements==
{{Requirements|n/a|1.5.8-9.20935|}}

==See Also==
{{Client ped functions}}

IsPedBleeding

2021-09-03T11:57:47Z

Botder: We can see your name in the page history

{{Client function}}
__NOTOC__
{{New feature/item|3.0159|1.5.8|20935|This function gets the state of a [[player|player's]] or [[ped|ped's]] bleeding effect.}}
==Syntax==
<syntaxhighlight lang="lua">bool isPedBleeding( ped thePed ) </syntaxhighlight>
{{OOP||[[ped]]:isBleeding|bleeding|setPedBleeding}}

===Required Arguments===
*'''thePed:''' the player or ped whose bleeding effect state you want to get.

===Returns===
Returns ''true'' if the player or ped is bleeding, ''false'' otherwise.

==Example==
<syntaxhighlight lang="lua">
function checkBleeding()
if isPedBleeding(localPlayer) then
outputChatBox("The ped is bleeding")
else
outputChatBox("The ped is not bleeding")
end
end
addCommandHandler("cBleed", checkBleeding)
</syntaxhighlight>

==Requirements==
{{Requirements|n/a|1.5.8-9.20935|}}

==See Also==
{{Client ped functions}}