TriggerLatentClientEvent: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
(7 intermediate revisions by 5 users not shown)
Line 1: Line 1:
__NOTOC__
__NOTOC__
{{Server function}}
{{Server function}}
This function is the same as [[triggerClientEvent ]] except the transmission rate of the data contained in the arguments can be limited.
This function is the same as [[triggerClientEvent ]] except the transmission rate of the data contained in the arguments can be limited
and other network traffic is not blocked while the data is being transferred.
{{Note|You should avoid triggering events on the [[root element]] unless you really need to. Doing this triggers the event on every element in the [[element_tree | element tree]], which is potentially very CPU intensive. Use as specific (i.e. low down the tree) element as you can.}}


==Syntax==  
==Syntax==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool triggerLatentClientEvent ( [element sendTo=getRootElement(),] string name, [int bandwidth=50000,] [bool persist=false,] element theElement, [arguments...] )
bool triggerLatentClientEvent ( [table/element sendTo=getRootElement(),] string name, [int bandwidth=50000,] [bool persist=false,] element theElement, [arguments...] )
</syntaxhighlight>  
</syntaxhighlight>  


Line 13: Line 15:


===Optional Arguments===  
===Optional Arguments===  
*'''sendTo:''' The event will be sent to all [[player]]s that are children of the specified element. By default this is the root element, and hence the event is sent to all players. If you specify a single player it will just be sent to that player.
*'''sendTo:''' The event will be sent to all [[player]]s that are children of the specified element. By default this is the root element, and hence the event is sent to all players. If you specify a single player it will just be sent to that player. This argument can also be a table of player elements.
*'''bandwidth:''' The bytes per second rate to send the data contained in the arguments.
*'''bandwidth:''' The bytes per second rate to send the data contained in the arguments.
*'''persist:''' A bool indicating whether the transmission should be allowed to continue even after the resource that triggered it has since stopped.
*'''persist:''' A bool indicating whether the transmission should be allowed to continue even after the resource that triggered it has since stopped.
Line 20: Line 22:
===Returns===
===Returns===
Returns ''true'' if the event trigger has been sent, ''false'' if invalid arguments were specified.
Returns ''true'' if the event trigger has been sent, ''false'' if invalid arguments were specified.
===triggerClientEvent vs triggerLatentClientEvent test by DreTaX===
I used a simple outputChatBox test, and devtools to see the performance results.
Using triggerClientEvent will immediately launch all the data to the client, and will end faster
however when using triggerLatentClientEvent, the server needs an unnoticeable (really small) amount of time to launch
up the event in to a thread. This gives benefits to your server, because as stated above, using latent event the server resource uses 0% CPU (Doesn't hold the main thread back),
but when using the normal trigger It gave me a 15% CPU usage.
Putting both of these in a loop will provide you sufficient understanding.
<syntaxhighlight lang="lua">
for i = 1, 10000 do
  --trigger the event to client side using one of the functions.
end
</syntaxhighlight>
I suggest using latent event instead to ensure your server won't hold back to any sync struggles.


==Example==  
==Example==  
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
addEvent("onClientReadFile",true)
addEventHandler("onClientReadFile",root,function(data)
local file = fileCreate("text.txt") --Save "data" into "text.txt"
fileWrite(file,data)
fileClose(file)
end)
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
  --TODO
if fileExists("text.txt") then
file = fileOpen("test.txt") --Open a file (you can create it yourself).
local data = fileRead(file,100*1024*1024) --Max 100 MB
fileClose(file) --Close File
triggerLatentClientEvent("onClientReadFile",5000,false,root,data) --trigger - Avoid triggering to root element (Read note above)
end
</syntaxhighlight>
</syntaxhighlight>
</section>


==Requirements==
==Requirements==
{{Requirements|1.3.0-9.03772|n/a|}}
{{Requirements|1.3.0-9.03772|n/a|}}
==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04570|Added option to use a list of player elements for the 'sendTo' argument}}


==See Also==
==See Also==
{{Event functions}}
{{Event functions}}

Revision as of 17:37, 30 August 2018

This function is the same as triggerClientEvent except the transmission rate of the data contained in the arguments can be limited and other network traffic is not blocked while the data is being transferred.

[[{{{image}}}|link=|]] Note: You should avoid triggering events on the root element unless you really need to. Doing this triggers the event on every element in the element tree, which is potentially very CPU intensive. Use as specific (i.e. low down the tree) element as you can.

Syntax

bool triggerLatentClientEvent ( [table/element sendTo=getRootElement(),] string name, [int bandwidth=50000,] [bool persist=false,] element theElement, [arguments...] )

Required Arguments

  • name: The name of the event to trigger client side. You should register this event with addEvent and add at least one event handler using addEventHandler.
  • theElement: The element that is the source of the event. This could be another player, or if this isn't relevant, use the root element.

Optional Arguments

  • sendTo: The event will be sent to all players that are children of the specified element. By default this is the root element, and hence the event is sent to all players. If you specify a single player it will just be sent to that player. This argument can also be a table of player elements.
  • bandwidth: The bytes per second rate to send the data contained in the arguments.
  • persist: A bool indicating whether the transmission should be allowed to continue even after the resource that triggered it has since stopped.
  • arguments...: A list of arguments to trigger with the event. You can pass any lua data type (except functions). You can also pass elements. The total amount of data should not exceed 100MB.

Returns

Returns true if the event trigger has been sent, false if invalid arguments were specified.

triggerClientEvent vs triggerLatentClientEvent test by DreTaX

I used a simple outputChatBox test, and devtools to see the performance results. Using triggerClientEvent will immediately launch all the data to the client, and will end faster however when using triggerLatentClientEvent, the server needs an unnoticeable (really small) amount of time to launch up the event in to a thread. This gives benefits to your server, because as stated above, using latent event the server resource uses 0% CPU (Doesn't hold the main thread back), but when using the normal trigger It gave me a 15% CPU usage. Putting both of these in a loop will provide you sufficient understanding.

for i = 1, 10000 do
   --trigger the event to client side using one of the functions.
end

I suggest using latent event instead to ensure your server won't hold back to any sync struggles.

Example

Click to collapse [-]
Client
addEvent("onClientReadFile",true)
addEventHandler("onClientReadFile",root,function(data)
	local file = fileCreate("text.txt")					--Save "data" into "text.txt"
	fileWrite(file,data)
	fileClose(file)
end)
Click to collapse [-]
Server
if fileExists("text.txt") then
	file = fileOpen("test.txt")						--Open a file (you can create it yourself).
	local data = fileRead(file,100*1024*1024)				--Max 100 MB
	fileClose(file)								--Close File
	triggerLatentClientEvent("onClientReadFile",5000,false,root,data)	--trigger - Avoid triggering to root element (Read note above)
end

Requirements

Minimum server version 1.3.0-9.03772
Minimum client version n/a

Note: Using this feature requires the resource to have the above minimum version declared in the meta.xml <min_mta_version> section. e.g. <min_mta_version server="1.3.0-9.03772" />

Changelog

Version Description
1.3.0-9.04570 Added option to use a list of player elements for the 'sendTo' argument

See Also