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.

Note

• 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 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

To save client 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 target element player who should receive event, if expected to be delivered to particular one) 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.

Syntax

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

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.

Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use.

• sendTo (default: getRootElement()): 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 (default: nil): A list of arguments to trigger with the event. You can pass any lua data type (except functions). You can also pass elements.

Returns

• bool: result

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

Code Examples

Example 1 Example 2 Example 3

server

-- *****************************************************************************
-- SERVER CODE
function greetingCommand(playerSource, commandName)
    triggerClientEvent(playerSource, "onGreeting", playerSource, "Hello World!")
end
addCommandHandler("greet", greetingCommand)

-- *****************************************************************************
-- CLIENT CODE
function greetingHandler(message) outputChatBox("The server says: " .. message) end
addEvent("onGreeting", true)
addEventHandler("onGreeting", localPlayer, greetingHandler)

server

-- *****************************************************************************
-- SERVER CODE
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)

-- *****************************************************************************
-- CLIENT CODE
function greetingHandler(message)
    outputChatBox("The server says: " .. message)
end
addEvent("onGreeting", true)
addEventHandler("onGreeting", localPlayer, greetingHandler)

server

-- *****************************************************************************
-- SERVER CODE
function commandFunction(source)
    triggerClientEvent(source, "toClientSide", resourceRoot, "Hello World!")
end
addCommandHandler("cool", commandFunction)

-- *****************************************************************************
-- CLIENT CODE
function nameFunction(message)
    if source == resourceRoot then
        outputChatBox(message)
    end
end
addEvent("toClientSide", true )
addEventHandler("toClientSide", resourceRoot, nameFunction)

Changelog

1.3.0-9.04570

Added option to use a list of player elements for the sendTo argument.

See Also

Event Functions

• addEvent
• addEventHandler
• cancelEvent
• cancelLatentEvent
• getCancelReason
• getEventHandlers
• getLatentEventHandles
• getLatentEventStatus
• removeEventHandler
• triggerClientEvent
• triggerEvent
• triggerLatentClientEvent
• triggerLatentServerEvent
• triggerServerEvent
• wasEventCancelled

Reference

• Scripting Functions