TriggerClientEvent: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
 
(35 intermediate revisions by 17 users not shown)
Line 1: Line 1:
__NOTOC__
<!--{{Needs_Checking|Something needs to be said about the steps required to help keep an event inside a resource. i.e. Setting 'theElement' to resourceRoot here, and setting the matching event handler's 'attachedTo' also to resourceRoot.}}
<!-- Describe in plain english what this function does. Don't go into details, just give an overview -->
-->__NOTOC__
This fake function is for use with blah & blah and does blahblahblabhalbhl
{{Server function}}
This function triggers an event previously registered on a client. This is the primary means of passing information between the server and the client. Clients have a similar [[triggerServerEvent]] function that can do the reverse. You can treat this function as if it was an asynchronous function call, using [[triggerServerEvent]] to pass back any returned information if necessary.
 
Almost any data types can be passed as expected, including [[element]]s and complex nested [[table]]s. Non-element MTA data types like xmlNodes or resource pointers will not be able to be passed as they do not necessarily have a valid representation on the client.
 
Events are sent reliably, so clients will receive them, but there may be (but shouldn't be) a significant delay before they are received. You should take this into account when using them.
 
Keep in mind the bandwidth issues when using events - don't pass a large list of arguments unless you really need to. '''It is marginally more efficient to pass one large event than two smaller ones'''.
{{Important Note | Non-element MTA data types like xmlNodes or resource pointers will not be able to be passed as they do not necessarily have a valid representation on the client.}}
{{Note | It is marginally more efficient to pass one large event than two smaller ones}}


==Syntax==  
==Syntax==  
<!-- NOTE: don't use 'special' names for variable names, e.g. you shouldn't be writing things like 'player player, vehicle vehicle', instead write something like 'player thePlayer, vehicle vehicleToGetInto'. This is less confusing and prevents the syntax highlighting being odd -->
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool triggerClientEvent ( [player triggerFor = rootElement], string name, element theElement, [arguments...] )
bool triggerClientEvent ( [ table/element sendTo = getRootElement(), ] string name, element sourceElement [, arguments... ] )
</syntaxhighlight>  
</syntaxhighlight>  
{{OOP||[[player]]:triggerEvent||}}


===Required Arguments===  
===Required Arguments===  
<!-- List each argument one per line. This should be the argument's name as in the argument list above, NOT the argument's data type -->
*'''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]].
*'''argumentName:''' description
*'''sourceElement:''' The element that is the [[Event system#Event handlers|source]] of the event.
{{Note|To save client CPU, you should avoid setting '''sourceElement''' to the [[root element]] where possible. Using [[GetThisResource|resourceRoot]] is usually sufficient if the event is handled by the same resource on the client.}}


<!-- Only include this section below if there are optional arguments -->
===Optional Arguments===  
===Optional Arguments===  
{{OptionalArg}}  
{{OptionalArg}}  
*'''argumentName2:''' description
*'''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.
*'''argumentName3:''' description
*'''arguments...:''' A list of arguments to trigger with the event. You can pass any lua data type (except functions). You can also pass [[element]]s.


===Returns===
===Returns===
<!-- Make this descriptive. Explain what cases will return false. If you're unsure, add a tag to it so we can check -->
Returns ''true'' if the event trigger has been sent, ''false'' if invalid arguments were specified.
Returns ''true'' if blah, ''false'' otherwise.


==Example==  
==Example==  
<!-- Explain what the example is in a single sentance -->
===Example 1===
This example does...
This example shows how you can pass a simple "Hello World" message from the server to the all the clients using an event.
<!-- Add the code below, an emphasis should be on making it clear, not optimized. You could provide two versions if you wish, one clear and well commented, the other optimized -->
 
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function greetingHandler ( message )
    outputChatBox ( "The server says: " .. message )
end
addEvent( "onGreeting", true )
addEventHandler( "onGreeting", localPlayer, greetingHandler )
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
--This line does...
function greetingCommand ( playerSource, commandName )
blabhalbalhb --abababa
    triggerClientEvent ( playerSource, "onGreeting", playerSource, "Hello World!" )
--This line does this...
end
mooo
addCommandHandler ( "greet", greetingCommand )
</syntaxhighlight>
</syntaxhighlight>
</section>
When the command "greet" is executed (by typing it in the server console or the player's console), the server's ''greetingCommand'' function is called. This triggers the client side event ''onGreeting'' with the string ''"Hello World!"''. This event is then handled by the ''greetingHandler'' function client side which then displays the message.
===Example 2===
This example shows how you can pass a simple "Hello World" message from the server to '''a single''' client using an event.
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
function greetingHandler ( message )
    outputChatBox ( "The server says: " .. message )
end
addEvent( "onGreeting", true )
addEventHandler( "onGreeting", localPlayer, greetingHandler )
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function greetingCommandOne ( playerSource, commandName, playerName )
    if playerName then
        local thePlayer = getPlayerFromName ( playerName )
        if thePlayer then
            triggerClientEvent ( thePlayer, "onGreeting", thePlayer, "Hello World!" )
        else
            -- invalid player name specified
        end
    else
        -- No player name specified
    end
end
addCommandHandler ( "greet_one", greetingCommandOne )
</syntaxhighlight>
</section>
This works like the first example except an extra ''thePlayer'' argument is specified for triggerClientEvent.
==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==
<!-- Change FunctionArea to the area that this function is in on the main function list page, e.g. Server, Player, Vehicle etc -->
{{Event functions}}
{{FunctionArea_functions}}
[[ru:triggerClientEvent]]
[[Category:Incomplete]] -- leave this unless you complete the function

Revision as of 19:58, 6 August 2018

This function triggers an event previously registered on a client. This is the primary means of passing information between the server and the client. Clients have a similar triggerServerEvent function that can do the reverse. You can treat this function as if it was an asynchronous function call, using triggerServerEvent to pass back any returned information if necessary.

Almost any data types can be passed as expected, including elements and complex nested tables. Non-element MTA data types like xmlNodes or resource pointers will not be able to be passed as they do not necessarily have a valid representation on the client.

Events are sent reliably, so clients will receive them, but there may be (but shouldn't be) a significant delay before they are received. You should take this into account when using them.

Keep in mind the bandwidth issues when using events - don't pass a large list of arguments unless you really need to. It is marginally more efficient to pass one large event than two smaller ones.

[[{{{image}}}|link=|]] Important Note: Non-element MTA data types like xmlNodes or resource pointers will not be able to be passed as they do not necessarily have a valid representation on the client.
[[{{{image}}}|link=|]] Note: It is marginally more efficient to pass one large event than two smaller ones

Syntax

bool triggerClientEvent ( [ table/element sendTo = getRootElement(), ] string name, element sourceElement [, arguments... ] )

OOP Syntax Help! I don't understand this!

Method: player:triggerEvent(...)


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.
  • sourceElement: The element that is the source of the event.
[[{{{image}}}|link=|]] Note: To save client CPU, you should avoid setting sourceElement to the root element where possible. Using resourceRoot is usually sufficient if the event is handled by the same resource on the client.

Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use. For more information on optional arguments, see 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.
  • arguments...: A list of arguments to trigger with the event. You can pass any lua data type (except functions). You can also pass elements.

Returns

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

Example

Example 1

This example shows how you can pass a simple "Hello World" message from the server to the all the clients using an event.

Click to collapse [-]
Client
function greetingHandler ( message )
    outputChatBox ( "The server says: " .. message )
end
addEvent( "onGreeting", true )
addEventHandler( "onGreeting", localPlayer, greetingHandler )
Click to collapse [-]
Server
function greetingCommand ( playerSource, commandName )
    triggerClientEvent ( playerSource, "onGreeting", playerSource, "Hello World!" )
end
addCommandHandler ( "greet", greetingCommand )

When the command "greet" is executed (by typing it in the server console or the player's console), the server's greetingCommand function is called. This triggers the client side event onGreeting with the string "Hello World!". This event is then handled by the greetingHandler function client side which then displays the message.

Example 2

This example shows how you can pass a simple "Hello World" message from the server to a single client using an event.

Click to collapse [-]
Client
function greetingHandler ( message )
    outputChatBox ( "The server says: " .. message )
end
addEvent( "onGreeting", true )
addEventHandler( "onGreeting", localPlayer, greetingHandler )
Click to collapse [-]
Server
function greetingCommandOne ( playerSource, commandName, playerName )
    if playerName then
        local thePlayer = getPlayerFromName ( playerName )
        if thePlayer then
            triggerClientEvent ( thePlayer, "onGreeting", thePlayer, "Hello World!" )
        else
            -- invalid player name specified
        end
    else
        -- No player name specified
    end 
end
addCommandHandler ( "greet_one", greetingCommandOne )

This works like the first example except an extra thePlayer argument is specified for triggerClientEvent.

Changelog

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

See Also