Multi Theft Auto: Wiki - User contributions [en]

SetElementLighting

2025-01-06T09:24:25Z

Yeleha:

{{Client function}}
__NOTOC__
{{New feature/item|3.0161|1.6.0|22862|This function changes the lighting value for the specified [[element]]. This can be a [[player]], [[ped]], [[vehicle]], [[object]], [[Element/Weapon|weapon]].}}

{{Note|Lighting is calculated in real-time every frame. Therefore, to correctly override the lighting, you should use this function in combination with the [[onClientPedsProcessed]] event, not only for peds, but also for vehicles and objects.}}

==Syntax==
<syntaxhighlight lang="lua">
bool setElementLighting ( element theElement, float lighting )
</syntaxhighlight>
{{OOP||[[element]]:setLighting|lighting|getElementLighting}}

===Required Arguments===
*'''theElement:''' The [[element]] whose lighting you want to change.
*'''lighting:''' The lighting value that you want to set.

===Returns===
Returns true if the function was successful, false otherwise. This function can fail if called right after element creation.

==Example==
This example sets the lighting value of all players and vehicles to 10
<syntaxhighlight lang="lua">addEventHandler("onClientPedsProcessed",root,function()
for _, v in pairs(getElementsByType('player')) do
setElementLighting(v, 10)
end
for _, v in pairs(getElementsByType('vehicle')) do
setElementLighting(v, 10)
end
end)</syntaxhighlight>
This example sets the lighting value to 10 only for our player, while keeping other players at the default value.
<syntaxhighlight lang="lua">addEventHandler("onClientPedsProcessed",root,function()
setElementLighting(localPlayer, 10)
end)</syntaxhighlight>

==See Also==
{{Client element functions}}

SetElementLighting

2025-01-06T09:22:42Z

Yeleha: /* Example */

{{Client function}}
__NOTOC__
{{New feature/item|3.0161|1.6.0|22862|This function changes the lighting value for the specified [[element]]. This can be a [[player]], [[ped]], [[vehicle]], [[object]], [[Element/Weapon|weapon]].}}

{{Note|Lighting is calculated in real-time every frame. Therefore, to correctly override the lighting, you should use this function in combination with the [[onClientPedsProcessed]] event, not only for peds, but also for vehicles and objects.}}

==Syntax==
<syntaxhighlight lang="lua">
bool setElementLighting ( element theElement, float lighting )
</syntaxhighlight>
{{OOP||[[element]]:setLighting|lighting|getElementLighting}}

===Required Arguments===
*'''theElement:''' The [[element]] whose lighting you want to change.
*'''lighting:''' The lighting value that you want to set.

===Returns===
Returns true if the function was successful, false otherwise. This function can fail if called right after element creation.

==Example==
<syntaxhighlight lang="lua">addEventHandler("onClientPedsProcessed",root,function()
for _, v in pairs(getElementsByType('player')) do -- All players lighting set to 10
setElementLighting(v, 10)
end
for _, v in pairs(getElementsByType('vehicle')) do -- All vehicles lighting set to 10
setElementLighting(v, 10)
end
end)</syntaxhighlight>

<syntaxhighlight lang="lua">addEventHandler("onClientPedsProcessed",root,function()
setElementLighting(localPlayer, 10) -- Set the lighting value of our player to 10
end)</syntaxhighlight>

==See Also==
{{Client element functions}}

Server Browser Rules

2025-01-05T13:15:16Z

Yeleha: Add the Slovak language

{{Warning|The system described in this article is still work-in-progress!|true}}
{{Note|Developers are working on creating a new Server Browser Interface. Check these issues on GitHub: [https://github.com/multitheftauto/mtasa-blue/issues/2104 Add banner, server description and tags #2104] [https://github.com/multitheftauto/mtasa-blue/issues/998 Revamp server browser #998] [https://github.com/multitheftauto/mtasa-blue/issues/759 Language filter/search #759]}}

==Information==

"'''Server Browser Rules'''" are ''key-value'' string pairs defined server-side.

These values are automatically transmitted/announced/broadcasted by your MTA Server using the ASE (All-Seeing Eye) protocol, when queried on the ASE UDP Port (server port + 123).

This data is to be received and parsed by MTA Clients (in the Server Browser) to display the list of online MTA servers with custom information for each server.

==Setting & Getting==

These ''rules'' can be set in your MTA Server's configuration file ([[Server_mtaserver.conf]]) using the following XML format:

<syntaxhighlight lang="xml">
<rule name="NAME_HERE" value="VALUE_HERE"/>
</syntaxhighlight>

They can also be defined and obtained using these two server-side functions:

<ul>
<li>[[setRuleValue]]</li>
<li>[[getRuleValue]]</li>
</ul>

==Expected Values==

The maximum amount of characters allowed in a rule value is '''200'''.

The Server Browser looks for the following information (optional) provided by servers:

{| class="wikitable"
! Key !! Explanation !! Accepted values || Example
|-
| '''description''' || Human-readable brief description of your server || Text || Custom cars and maps! Join various minigames from racing to drifting
|-
| '''languages''' || Comma separated list of languages that your server supports || [[#Allowed Languages|See Allowed Languages]] || en, ru, ar
|-
| '''tags''' || Comma separated list of tags that describe your server || [[#Allowed Tags|See Allowed Tags]] || freeroam, minigames, race, pvp, drifting
|-
| '''website_url''' || Website URL of your server || Valid URL starting with https:// || https://example-website.com
|-
| '''social_url_1''' || Social media URL #1 || Valid URL starting with https:// || https://discord.com/invite/example
|-
| '''social_url_2''' || Social media URL #2 || Valid URL starting with https:// || https://youtube.com/@exampleChannel
|-
| '''social_url_3''' || Social media URL #3 || Valid URL starting with https:// || https://facebook.com/examplePage
|}

==Full Example==

Below is an example configuration that you can include in '''mtaserver.conf''':

<syntaxhighlight lang="xml">
<rule name="description" value="Custom cars and maps! Join various minigames from racing to drifting" />
<rule name="languages" value="en, ru, ar" />
<rule name="tags" value="freeroam, minigames, race, pvp, drifting" />
<rule name="website_url" value="https://example-website.com" />
<rule name="social_url_1" value="https://discord.com/invite/example" />
<rule name="social_url_2" value="https://youtube.com/@exampleChannel" />
<rule name="social_url_3" value="https://facebook.com/examplePage" />
</syntaxhighlight>

==Allowed Languages==

WIP

{| class="wikitable"
! Tag !! Language !! Flag
|-
| '''en''' || English || 🇺🇸
|-
| '''pt-pt''' || European Portuguese || 🇵🇹
|-
| '''pt-br''' || Brazilian Portuguese || 🇧🇷
|-
| '''es''' || Spanish || 🇪🇸
|-
| '''fr''' || French || 🇫🇷
|-
| '''de''' || German || 🇩🇪
|-
| '''it''' || Italian || 🇮🇹
|-
| '''ru''' || Russian || 🇷🇺
|-
| '''zh''' || Chinese (Simplified) || 🇨🇳
|-
| '''zh-tw''' || Chinese (Traditional, Taiwan) || 🇹🇼
|-
| '''ja''' || Japanese || 🇯🇵
|-
| '''ko''' || Korean || 🇰🇷
|-
| '''ar''' || Arabic || 🇸🇦
|-
| '''hi''' || Hindi || 🇮🇳
|-
| '''bn''' || Bengali || 🇧🇩
|-
| '''tr''' || Turkish || 🇹🇷
|-
| '''nl''' || Dutch || 🇳🇱
|-
| '''sv''' || Swedish || 🇸🇪
|-
| '''no''' || Norwegian || 🇳🇴
|-
| '''da''' || Danish || 🇩🇰
|-
| '''fi''' || Finnish || 🇫🇮
|-
| '''pl''' || Polish || 🇵🇱
|-
| '''sk''' || Slovak || 🇸🇰
|-
| '''cs''' || Czech || 🇨🇿
|-
| '''hu''' || Hungarian || 🇭🇺
|-
| '''ro''' || Romanian || 🇷🇴
|-
| '''el''' || Greek || 🇬🇷
|-
| '''he''' || Hebrew || 🇮🇱
|-
| '''vi''' || Vietnamese || 🇻🇳
|-
| '''th''' || Thai || 🇹🇭
|-
| '''id''' || Indonesian || 🇮🇩
|}

====Allowed Tags====

WIP

==Useful Information==

<ul>
<li>[https://github.com/multitheftauto/mtasa-blue/pull/3761 github.com/multitheftauto/mtasa-blue: PR #3761]</li>
<li>[https://en.wikipedia.org/wiki/The_All-Seeing_Eye wikipedia.org: The All-Seeing Eye]</li>
<li>[https://int64.org/docs/gamestat-protocols/ase.html int64.org: All-Seeing Eye Protocol]</li>
</ul>

SetPedAnimation

2024-07-14T06:07:58Z

Yeleha: Issue fixed, removed from table.

__NOTOC__
{{Server client function}}

Sets the current [[Animations|animation]] of a [[player]] or [[ped]]. Not specifying the type of animation will automatically cancel the current one.
{{Warning|It is possible that an animation will be cancelled if you use setElementFrozen on the ped, but this does not happen all the time.}}

==Syntax==
<syntaxhighlight lang="lua">
bool setPedAnimation ( ped thePed [, string block = nil, string anim = nil, int time = -1, bool loop = true, bool updatePosition = true,
bool interruptable = true, bool freezeLastFrame = true, int blendTime = 250, bool retainPedState = false ] )
</syntaxhighlight>
{{OOP||[[ped]]:setAnimation||getPedAnimation}}

===Required Arguments===
*'''thePed:''' the [[player]] or [[ped]] you want to apply an [[Animations|animation]] to.

===Optional Arguments===
{{OptionalArg}}
*'''block:''' the [[Animations|animation]] block's name.
*'''anim:''' the name of the [[Animations|animation]] within the block.
*'''time:''' how long the animation will run for in milliseconds.
*'''loop:''' indicates whether or not the animation will loop.
*'''updatePosition:''' will change the actual coordinates of the ped according to the animation. Use this for e.g. walking animations.
*'''interruptable:''' if set to ''false'' other tasks wont be able to interupt the animation. Setting this to 'false' also gives this function more power to override other animations that are running. For example, squatting after a jump can be terminated.
*'''freezeLastFrame:''' if set to ''true'' after animation the last frame will be frozen, otherwise the animation will end and controls will return.
*'''blendTime:''' how long the animation will mixed with the previous one in milliseconds.
{{New items|3.0157|1.5.7|
*'''retainPedState:''' will restore the task which was playing before calling this function. Useful for restoring the crouch task after animation ends. This may be extended in the future to support other states/tasks.
|16632}}

===Returns===
Returns ''true'' if succesful, ''false'' otherwise.

==Examples==

<section name="Server" class="server" show="true">
This example creates a ped, rotates him, and makes him walk:
<syntaxhighlight lang="lua">
function makePed()
local thePed = createPed(56, 1, 1, 4, 315)
setPedAnimation(thePed, "ped", "WOMAN_walknorm")
end
addCommandHandler("makemyped", makePed)
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
This example makes the player sit down and stand up using the command /sit.
<syntaxhighlight lang="lua">
local playerSitState = {}

function toggleSit(thePlayer)
local playerSitting = playerSitState[thePlayer]

if (not playerSitting) then
setPedAnimation(thePlayer, "ped", "seat_down", -1, false, false, false, false)
playerSitState[thePlayer] = true -- store the player state in the table

return true
end

setPedAnimation(thePlayer) -- if you use again this command then your character stand up
playerSitState[thePlayer] = nil -- remove player sit state from table
end
addCommandHandler("sit", toggleSit)

function onPlayerQuitClearSitState()
playerSitState[source] = nil -- clear state at player quit, to prevent memory leak
end
addEventHandler("onPlayerQuit", root, onPlayerQuitClearSitState)
</syntaxhighlight>
</section>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.5.7-9.16632|Added retainPedState argument}}

==Issues==
{{Issues|
{{Issue|1110|retainPedState in setPedAnimation() does not work when latency reduction is set to 1}}
{{Issue|953|setPedAnimation() "interrupt" and "time" has no effect in certain situations}}
{{Issue|467|Ped animations don't sync for new players}}
{{Issue|463|setPedAnimation() does not work when a ped is attached and floating in air}}
{{Issue|1173|setPedAnimation() removes player jetpack}}
{{Issue|884|setPedAnimation() messes up collisions of peds inside vehicles}}
}}

==See Also==
{{Ped_functions}}
[[ru:setPedAnimation]]
[[HU:setPedAnimation]]

ToJSON

2024-07-12T09:29:07Z

Yeleha:

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

{{Important Note|Due to technical limitations (partly of json-c) the stringified keys will be truncated to the first 255 characters}}
{{ Warning| When using [[toJSON]] for submitting data using [[fetchRemote]] for example, make sure to use '''string.sub(data, 2, -2)''' to remove the brackets as many APIs will not understand the request }}
==Syntax==

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

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

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

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

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

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

==See Also==
{{Server_functions}}

[[ru:toJSON]]

FetchRemote

2024-07-12T09:28:46Z

Yeleha:

__NOTOC__
{{Server client function}}
This function allows you to post and receive data from HTTP servers. The calls are asynchronous so you do not get an immediate result from the call, instead a callback function you specify is called when the download completes.

In the case when the call fails, a string containing "ERROR" followed by an integer containing the error reason will be passed to the callback function. The reason for failure will be similar to errors found with websites - file not found, server not found and timeouts.

If you are using fetchRemote to connect to a PHP script, you can use '''file_get_contents('php://input')''' to read the '''postData''' sent from this function.
{{Note|Client side function only works with the server the player is connected to unless the domain has been accepted with [[requestBrowserDomains]]}}
{{ Warning| function won't trigger inside another fetchRemote function }}
{{ Warning| When using [[toJSON]] for submitting data, make sure to use '''string.sub(data, 2, -2)''' to remove the brackets as many APIs will not understand the request }}
==Syntax==
<syntaxhighlight lang="lua">
bool fetchRemote ( string URL, [ string queueName = "default" ], [ int connectionAttempts = 10, int connectTimeout = 10000 ], function callbackFunction, [ string postData = "", bool postIsBinary = false ], [ arguments... ] )
</syntaxhighlight>

===Required Arguments===
*'''URL:''' A full URL in the format ''<nowiki>http://hostname/path/file.ext</nowiki>''. A port can be specified with a colon followed by a port number appended to the hostname.
*'''callbackFunction:''' This is the function that should receive the data returned from the remote server. The callback argument list should be:
**'''''responseData''''' - A string containing the remote response or "ERROR" if there was a problem
**'''''error''''' - A number containing the error number or zero if there was no error. A list of possible error values are:
{{Error_codes_for_callRemote_and_fetchRemote}}
<div style="padding-left:19px;">
*'''''arguments...''''' - The arguments that were passed into fetchRemote
</div>

===Optional Arguments===
{{New items|4.0153|1.5.3-9.11270|
*'''queueName:''' Name of the queue to use. Any name can be used. If not set, the queue name is "default". Requests in the same queue are processed in order, one at a time.
}}
*'''connectionAttempts:''' Number of times to retry if the remote host does not respond. ''In the case of a non-responding remote server, each connection attempt will timeout after 10 seconds. Therefore, the default setting of 10 connection attempts means it will be 100 seconds before your script gets a callback about the error. Reducing this value to 2 for example, will decrease that period to 20 seconds''
*'''connectTimeout:''' Number of milliseconds each connection attempt will take before timing out
*'''postData:''' A string specifying any data you want to send to the remote HTTP server.
*'''postIsBinary :''' A boolean specifying if the data is text, or binary.
*'''arguments:''' Any arguments you may want to pass to the callback.

{{New items|5.0154|1.5.4-9.11342|
==Syntax==
<syntaxhighlight lang="lua">
bool fetchRemote ( string URL[, table options ], callback callbackFunction[, table callbackArguments ] )
</syntaxhighlight>

===Required Arguments===
*'''URL:''' A full URL in the format ''<nowiki>http://hostname/path/file.ext</nowiki>''. A port can be specified with a colon followed by a port number appended to the hostname.
*'''callbackFunction:''' This is the function that should receive the data returned from the remote server. The callback argument list should be:
**'''''responseData''''' - A string containing the remote response
**'''''responseInfo''''' - A table containing:
***'''''success''''' - A boolean indicating if the request was successful.
***'''''statusCode''''' - An integer status/error code
***'''''headers''''' - A table containing the HTTP response headers
**'''''arguments...''''' - The arguments that were passed into fetchRemote

===Optional Arguments===
*'''options:''' A table containing any request options:
**'''queueName:''' Name of the queue to use. Any name can be used. If not set, the queue name is "default". Requests in the same queue are processed in order, one at a time.
**'''connectionAttempts:''' Number of times to retry if the remote host does not respond. ''(Defaults to 10)''
**'''connectTimeout:''' Number of milliseconds each connection attempt will take before timing out. ''(Defaults to 10000)''
**'''postData:''' A string specifying any data you want to send to the remote HTTP server.
**'''postIsBinary :''' A boolean specifying if the data is text, or binary. ''(Defaults to false)''
**'''method:''' A string specifying the request method. ''(Defaults to GET or POST)''
**'''headers:''' A table containing HTTP request headers. ''e.g.{ Pragma="no-cache" }''
**'''maxRedirects:''' An integer limiting the number of HTTP redirections to automatically follow. ''(Defaults to 8)''
**'''username:''' A string specifying the username for protected pages.
**'''password:''' A string specifying the password for protected pages.
{{New items|5.0154|1.5.4-9.11413|
**'''formFields:''' A table containing form items to submit. (for POST method only) ''e.g.{ name="bob", email="bob@example.com" }''
}}
*'''arguments:''' A table containing arguments you may want to pass to the callback.
}}

===Returns===
{{New items|5.0154|1.5.7-9.20307|
Returns a '''''request''''' value which can be used with [[GetRemoteRequestInfo|getRemoteRequestInfo]] or [[AbortRemoteRequest|abortRemoteRequest]]
}}

==Example==
This example shows you how you can fetch an image from a web page, and transfer it to a particular client:
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">

function startImageDownload( playerToReceive )
fetchRemote ( "http://www.example.com/image.jpg", myCallback, "", false, playerToReceive )
end

function myCallback( responseData, errorCode, playerToReceive )
if errorCode == 0 then
triggerClientEvent( playerToReceive, "onClientGotImage", resourceRoot, responseData )
end
end
</syntaxhighlight>
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
addEvent( "onClientGotImage", true )
addEventHandler( "onClientGotImage", resourceRoot,
function( pixels )
if myTexture then
destroyElement( myTexture )
end
myTexture = dxCreateTexture( pixels )
end
)

addEventHandler("onClientRender", root,
function()
if myTexture then
local w,h = dxGetMaterialSize( myTexture )
dxDrawImage( 200, 100, w, h, myTexture )
end
end
)
</syntaxhighlight>
</section>
<br/>
{{New items|5.0154|1.5.4-9.11413|
Example sending email via a web service (adopted from examples on https://documentation.mailgun.com/en/latest/user_manual.html)
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
sendOptions = {
queueName = "My Mailgun queue",
connectionAttempts = 3,
connectTimeout = 5000,
formFields = {
from="Excited User <excited@samples.mailgun.org>",
to="devs@mailgun.net",
subject="Hello",
text="Testing some Mailgun awesomness!",
},
username="api",
password="key-3ax6xnjp29jd6fds4gc373sgvjxteol0",
}
fetchRemote( "https://api.mailgun.net/v3/samples.mailgun.org/messages", sendOptions, mailgunCompleteCallback )

function mailgunCompleteCallback(data, info)
outputDebugString( "mailgunComplete"
.. " success:" .. tostring(info.success)
.. " statusCode:" .. tostring(info.statusCode)
.. " data:" .. tostring(data)
)
end
</syntaxhighlight>
</section>

Changing post content on IPS forum.
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
local apiKey = "12345678123456781234567812345678" -- key from ips admin panel
local forumAddress = "https://yourForum.com"
function setPostContent(postID,content)
local sendOptions = {
queueName = "updatePost",
connectionAttempts = 1,
connectTimeout = 50,
formFields = {
post = content,
},
}
fetchRemote( forumAddress.."/api/forums/posts/"..postID.."?key="..apiKey, sendOptions, function()end)
end

setPostContent(1, "this is a first post on this forum")
</syntaxhighlight>
</section>
}}

==Requirements==
{{Requirements|1.3.0-9.03739|1.3.2|}}

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.1-9.04605|Added connectionAttempts argument}}
{{ChangelogItem|1.3.2|Added client side}}
{{ChangelogItem|1.5.3-9.11270|Added queueName argument}}
{{ChangelogItem|1.5.4-9.11342|Added alternative syntax}}
{{ChangelogItem|1.5.4-9.11413|Added formFields}}

==See Also==
{{Resource_functions}}

FetchRemote

2024-07-12T09:28:18Z

Yeleha: Warning for using toJSON in requests.

__NOTOC__
{{Server client function}}
This function allows you to post and receive data from HTTP servers. The calls are asynchronous so you do not get an immediate result from the call, instead a callback function you specify is called when the download completes.

In the case when the call fails, a string containing "ERROR" followed by an integer containing the error reason will be passed to the callback function. The reason for failure will be similar to errors found with websites - file not found, server not found and timeouts.

If you are using fetchRemote to connect to a PHP script, you can use '''file_get_contents('php://input')''' to read the '''postData''' sent from this function.
{{Note|Client side function only works with the server the player is connected to unless the domain has been accepted with [[requestBrowserDomains]]}}
{{ Warning| function won't trigger inside another fetchRemote function }}
{{ Warning| When using [[toJSON]] for submitting data, make sure to use string.sub(data, 2, -2) to remove the brackets as many APIs will not understand the request }}
==Syntax==
<syntaxhighlight lang="lua">
bool fetchRemote ( string URL, [ string queueName = "default" ], [ int connectionAttempts = 10, int connectTimeout = 10000 ], function callbackFunction, [ string postData = "", bool postIsBinary = false ], [ arguments... ] )
</syntaxhighlight>

===Required Arguments===
*'''URL:''' A full URL in the format ''<nowiki>http://hostname/path/file.ext</nowiki>''. A port can be specified with a colon followed by a port number appended to the hostname.
*'''callbackFunction:''' This is the function that should receive the data returned from the remote server. The callback argument list should be:
**'''''responseData''''' - A string containing the remote response or "ERROR" if there was a problem
**'''''error''''' - A number containing the error number or zero if there was no error. A list of possible error values are:
{{Error_codes_for_callRemote_and_fetchRemote}}
<div style="padding-left:19px;">
*'''''arguments...''''' - The arguments that were passed into fetchRemote
</div>

===Optional Arguments===
{{New items|4.0153|1.5.3-9.11270|
*'''queueName:''' Name of the queue to use. Any name can be used. If not set, the queue name is "default". Requests in the same queue are processed in order, one at a time.
}}
*'''connectionAttempts:''' Number of times to retry if the remote host does not respond. ''In the case of a non-responding remote server, each connection attempt will timeout after 10 seconds. Therefore, the default setting of 10 connection attempts means it will be 100 seconds before your script gets a callback about the error. Reducing this value to 2 for example, will decrease that period to 20 seconds''
*'''connectTimeout:''' Number of milliseconds each connection attempt will take before timing out
*'''postData:''' A string specifying any data you want to send to the remote HTTP server.
*'''postIsBinary :''' A boolean specifying if the data is text, or binary.
*'''arguments:''' Any arguments you may want to pass to the callback.

{{New items|5.0154|1.5.4-9.11342|
==Syntax==
<syntaxhighlight lang="lua">
bool fetchRemote ( string URL[, table options ], callback callbackFunction[, table callbackArguments ] )
</syntaxhighlight>

===Required Arguments===
*'''URL:''' A full URL in the format ''<nowiki>http://hostname/path/file.ext</nowiki>''. A port can be specified with a colon followed by a port number appended to the hostname.
*'''callbackFunction:''' This is the function that should receive the data returned from the remote server. The callback argument list should be:
**'''''responseData''''' - A string containing the remote response
**'''''responseInfo''''' - A table containing:
***'''''success''''' - A boolean indicating if the request was successful.
***'''''statusCode''''' - An integer status/error code
***'''''headers''''' - A table containing the HTTP response headers
**'''''arguments...''''' - The arguments that were passed into fetchRemote

===Optional Arguments===
*'''options:''' A table containing any request options:
**'''queueName:''' Name of the queue to use. Any name can be used. If not set, the queue name is "default". Requests in the same queue are processed in order, one at a time.
**'''connectionAttempts:''' Number of times to retry if the remote host does not respond. ''(Defaults to 10)''
**'''connectTimeout:''' Number of milliseconds each connection attempt will take before timing out. ''(Defaults to 10000)''
**'''postData:''' A string specifying any data you want to send to the remote HTTP server.
**'''postIsBinary :''' A boolean specifying if the data is text, or binary. ''(Defaults to false)''
**'''method:''' A string specifying the request method. ''(Defaults to GET or POST)''
**'''headers:''' A table containing HTTP request headers. ''e.g.{ Pragma="no-cache" }''
**'''maxRedirects:''' An integer limiting the number of HTTP redirections to automatically follow. ''(Defaults to 8)''
**'''username:''' A string specifying the username for protected pages.
**'''password:''' A string specifying the password for protected pages.
{{New items|5.0154|1.5.4-9.11413|
**'''formFields:''' A table containing form items to submit. (for POST method only) ''e.g.{ name="bob", email="bob@example.com" }''
}}
*'''arguments:''' A table containing arguments you may want to pass to the callback.
}}

===Returns===
{{New items|5.0154|1.5.7-9.20307|
Returns a '''''request''''' value which can be used with [[GetRemoteRequestInfo|getRemoteRequestInfo]] or [[AbortRemoteRequest|abortRemoteRequest]]
}}

==Example==
This example shows you how you can fetch an image from a web page, and transfer it to a particular client:
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">

function startImageDownload( playerToReceive )
fetchRemote ( "http://www.example.com/image.jpg", myCallback, "", false, playerToReceive )
end

function myCallback( responseData, errorCode, playerToReceive )
if errorCode == 0 then
triggerClientEvent( playerToReceive, "onClientGotImage", resourceRoot, responseData )
end
end
</syntaxhighlight>
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
addEvent( "onClientGotImage", true )
addEventHandler( "onClientGotImage", resourceRoot,
function( pixels )
if myTexture then
destroyElement( myTexture )
end
myTexture = dxCreateTexture( pixels )
end
)

addEventHandler("onClientRender", root,
function()
if myTexture then
local w,h = dxGetMaterialSize( myTexture )
dxDrawImage( 200, 100, w, h, myTexture )
end
end
)
</syntaxhighlight>
</section>
<br/>
{{New items|5.0154|1.5.4-9.11413|
Example sending email via a web service (adopted from examples on https://documentation.mailgun.com/en/latest/user_manual.html)
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
sendOptions = {
queueName = "My Mailgun queue",
connectionAttempts = 3,
connectTimeout = 5000,
formFields = {
from="Excited User <excited@samples.mailgun.org>",
to="devs@mailgun.net",
subject="Hello",
text="Testing some Mailgun awesomness!",
},
username="api",
password="key-3ax6xnjp29jd6fds4gc373sgvjxteol0",
}
fetchRemote( "https://api.mailgun.net/v3/samples.mailgun.org/messages", sendOptions, mailgunCompleteCallback )

function mailgunCompleteCallback(data, info)
outputDebugString( "mailgunComplete"
.. " success:" .. tostring(info.success)
.. " statusCode:" .. tostring(info.statusCode)
.. " data:" .. tostring(data)
)
end
</syntaxhighlight>
</section>

Changing post content on IPS forum.
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
local apiKey = "12345678123456781234567812345678" -- key from ips admin panel
local forumAddress = "https://yourForum.com"
function setPostContent(postID,content)
local sendOptions = {
queueName = "updatePost",
connectionAttempts = 1,
connectTimeout = 50,
formFields = {
post = content,
},
}
fetchRemote( forumAddress.."/api/forums/posts/"..postID.."?key="..apiKey, sendOptions, function()end)
end

setPostContent(1, "this is a first post on this forum")
</syntaxhighlight>
</section>
}}

==Requirements==
{{Requirements|1.3.0-9.03739|1.3.2|}}

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.1-9.04605|Added connectionAttempts argument}}
{{ChangelogItem|1.3.2|Added client side}}
{{ChangelogItem|1.5.3-9.11270|Added queueName argument}}
{{ChangelogItem|1.5.4-9.11342|Added alternative syntax}}
{{ChangelogItem|1.5.4-9.11413|Added formFields}}

==See Also==
{{Resource_functions}}

ToJSON

2024-07-12T08:45:09Z

Yeleha: Warning for using toJSON in requests.

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

{{Important Note|Due to technical limitations (partly of json-c) the stringified keys will be truncated to the first 255 characters}}
{{ Warning| When using [[toJSON]] for submitting data using [[fetchRemote]] for example, make sure to use string.sub(data, 2, -2) to remove the brackets as many APIs will not understand the request }}
==Syntax==

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

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

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

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

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

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

==See Also==
{{Server_functions}}

[[ru:toJSON]]