addEventHandler | Multi Theft Auto: Wiki Skip to content
Multi Theft Auto: Wiki

addEventHandler

Client-side
Server-side
Shared

This function will add an event handler. An event handler is a function that will be called when the event it's attached to is triggered. See event system for more information on how the event system works.

Note
  • You shouldn't re-use the same name for your handler function as the event name - if multiple handler functions are used, as this can lead to confusion. On the same note, for multiple reasons, it isn't a good idea to export the same functions that you use locally as remote event handlers.
  • See Event Source Element for a descriptive visualization of the event system handling an event trigger.
  • Due to the additional set of global variables, the event-trigger specific variables it is NOT a good idea to use the same function locally as well as directly as an event handler. Event handlers often make use of the source element variable which would often find no use in generic functions. Inside of server-side remote event handlers it is important to add protections against exploits due to unexpected client event triggers or network-based load situations while generic functions, due to being part of a controlled call-stack, do not in general face the same issues. It is recommended to adapt a good-natured distancing principle between code meant to run from local logic in separation to code meant to run from remote logic.
Important
  • See Script security for how-to prevent cheaters from abusing event system.
  • Anything bound to a specific element will be run before other handlers that are bound to something higher in the element tree (like root) This means that high+10 bound to root won't trigger before normal bound directly to an element.

Syntax 

​bool addEventHandler ( ​string eventName, ​element attachedTo, ​function handlerFunction(), [ ​bool propagate = true, ​string priority = "normal" ] )
Required Arguments
  • eventName: The name of the event you want to attach the handler function to. Note: The maximum allowed length is 100 ASCII characters (that is, English letters and numerals)
  • attachedTo: The element you wish to attach the handler to. The handler will only be called when the event it is attached to is triggered for this element, or one of its children. Often, this can be the root element (meaning the handler will be called when the event is triggered for any element).
  • handlerFunction(): The handler function you wish to call when the event is triggered. This function will be passed all of the event's parameters as arguments, but it isn't required that it takes all of them.
Optional Arguments

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

  • propagate (default: true): A boolean representing whether the handler will be triggered if the event was propagated down or up the element tree (starting from the source), and not triggered directly on attachedTo (that is, handlers attached with this argument set to false will only be triggered if source == this ). In GUI events you will probably want to set this to false .
  • priority (default: "normal"): A string representing the trigger order priority relative to other event handlers of the same name. Possible values are:
    • high
    • normal
    • low

Returns

  • bool: result

Returns true if the event handler was attached successfully. otherwise false if the specified event could not be found or any parameters were invalid.

Code Examples

shared

This serverside example sends a message to everyone in the server when a player spawns.

-- define our handler function
function onPlayerSpawnHandler()
    -- get the player's name, source is the player because he was spawned
    local playerName = getPlayerName(source)
    -- output in the chat box that they've spawned
    outputChatBox(playerName .. " has spawned!")
end
addEventHandler("onPlayerSpawn", root, onPlayerSpawnHandler) -- root is a predefined global variable for getRootElement()

See Also

Event Functions
Reference