TriggerServerEvent

This function triggers an event previously registered on the server. 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. 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. Elements of the Vector or Matrix classes cannot be passed!

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.

[[{{{image}}}|link=|]]	Important Note: You should use the global variable client server-side instead of passing the localPlayer by parameter or source. Otherwise event faking (passing another player instead of the localPlayer) would be possible. For more information see: Script security article.

[[{{{image}}}|link=|]]	Note: 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.

[[{{{image}}}|link=|]]

Note: To save server CPU, you should avoid setting theElement to the root element where possible - it should be used as a last resort (rather questionable thing to do, limited to very specific tasks, if any). Using localPlayer is preferred and highly advisable. resourceRoot can also be used as alternative choice, if addEventHandler is bound to root element, or to resourceRoot when there is need to restrict event to single certain resource.

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 or a client side element was a parameter.

Example

This example shows how you can pass some data from client to server.

Click to collapse [-]

Client

function sendTestData()
    local dataToSend = "Hello, world!"
    triggerServerEvent("onServerSendTestData", resourceRoot, dataToSend)
end
addCommandHandler("data", sendTestData)

Click to collapse [-]

Server

function onServerSendTestData(sentData)
    if (not client) then -- 'client' points to the player who triggered the event, and should be used as security measure (in order to prevent player faking)
      return false -- if this variable doesn't exists at the moment (for unknown reason, or it was the server who triggered this event), stop code execution
    end
    if (source ~= resourceRoot) then
      return false
    end
    local chatMessage = "Data sent from client: "..sentData
    outputChatBox(chatMessage, client) -- output data sent from client-side
end
addEvent("onServerSendTestData", true) -- 2nd argument should be set to true, in order to be triggered from counter side (in this case client-side)
addEventHandler("onServerSendTestData", resourceRoot, onServerSendTestData)

When the command data is executed (by typing it in the player's console or in chat: /data), sendTestData function is called. This triggers the server-side event onServerSendTestData with the string "Hello, world!". This event is then handled by function on server-side which displays the message.

See Also

• triggerLatentServerEvent
• triggerServerEvent


• Shared
• addEvent
• addEventHandler
• cancelEvent
• cancelLatentEvent
• getEventHandlers
• getLatentEventHandles
• getLatentEventStatus
• removeEventHandler
• triggerEvent
• wasEventCancelled