TriggerServerEvent: Difference between revisions

Revision as of 15:25, 20 June 2007

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

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

Events are sent reliably, so the server 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.

Syntax

bool triggerServerEvent ( string event, element theElement, [arguments...] )

Required Arguments

event: The name of the event to trigger server-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

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

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

Server:

addEvent("onGreeting")
addEventHandler("onGreeting", getRootElement(), "greetingHandler")
function greetingHandler ( message )
    outputChatBox ( "The client says: " .. message )
end

Client:

addCommandHandler ( "greet", "greetingCommand" )
function greetingCommand ( source, commandName )
    triggerServerEvent ( "onGreeting", getRootElement(), "Hello World!" )
end

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

@@ Line 1: / Line 1: @@
 __NOTOC__
-<!-- Describe in plain english what this function does. Don't go into details, just give an overview -->
+This function triggers an event on servers. This is the primary means of passing information between the client and the server. Servers have a similar [[triggerClientEvent]] function that can do the reverse. You can treat this function as if it was an asynchronous function call, using [[triggerClientEvent]] to pass back any returned information if necessary.
-This fake function is for use with blah & blah and does blahblahblabhalbhl
+Almost any data types can be passed as expected, including [[elements]] and complex nested [[tables]]. Special data types like xmlNodes will not be able to be passed as they do not necessarily have a valid representation on the client.
+Events are sent reliably, so the server 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.
 ==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">
-bool triggerServerEvent ( event, element theelement, arguments ... )
+bool triggerServerEvent ( string event, element theElement, [arguments...] )
 </syntaxhighlight>
 ===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 -->
+*'''event:''' The name of the event to trigger server-side. You should register this event with [[addEvent]] and add at least one event handler using [[addEventHandler]].
-*'''argumentName:''' description
+*'''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.
-<!-- Only include this section below if there are optional arguments -->
 ===Optional Arguments===
-{{OptionalArg}}
+*'''arguments...:''' A list of arguments to trigger with the event. You can pass any lua data type (except functions). You can also pass [[elements]].
-*'''argumentName2:''' description
-*'''argumentName3:''' description
 ===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==
-<!-- Explain what the example is in a single sentance -->
+This example shows how you can pass a simple "Hello World" message from the client to the server using an event.
-This example does...
-<!-- 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 -->
+'''Server:'''
+<syntaxhighlight lang="lua">
+addEvent("onGreeting")
+addEventHandler("onGreeting", getRootElement(), "greetingHandler")
+function greetingHandler ( message )
+    outputChatBox ( "The client says: " .. message )
+end
+</syntaxhighlight>
+'''Client:'''
 <syntaxhighlight lang="lua">
---This line does...
+addCommandHandler ( "greet", "greetingCommand" )
-blabhalbalhb --abababa
+function greetingCommand ( source, commandName )
---This line does this...
+    triggerServerEvent ( "onGreeting", getRootElement(), "Hello World!" )
-mooo
+end
 </syntaxhighlight>
+When the command "greet" is executed (by typing it in the server console or the player's console), the clients ''greetingCommand'' function is called. This triggers the server-side event ''onGreeting'' with the string ''"Hello World!"''. This event is then handled by the ''greetingHandler'' function server-side which then displays the message.
 ==See Also==
-<!-- Change FunctionArea to the area that this function is in on the main function list page, e.g. Server, Player, Vehicle etc -->
 {{FunctionArea_functions}}
-[[Category:Incomplete]] -- leave this unless you complete the function