The event system is a fundamental part of MTA scripting. It works closely with the element tree to allow scripts to respond to things that happen in the game — for example, when a player enters a marker or clicks an element. Every event has a source element: the element where the event originated.

Event Handlers

To react to events, you attach event handlers to elements using addEventHandler. Once attached, your handler will respond to events triggered by:

• The element itself
• Its parent elements (and their parents, recursively)
• Its child elements (and their children, recursively)

Because of this, attaching a handler to the root element will catch every event in the entire element tree. However, this is rarely needed — you should generally attach handlers to the most specific element possible. For example, if you only care when a player enters a certain marker, just attach your handler to that marker.

Handler Context Variables

Every event handler automatically receives some useful variables:

• source: The element where the event originated.
• this: The element the handler is attached to.
• eventName: The name of the triggered event.

On the server side, there's an extra variable:

• client: The client that triggered the event with triggerServerEvent, if applicable.

Read the Script security article for more information on how to use events securely and effectively.

Event Propagation

Events propagate through the element tree: they start at the source element, and then bubble up to parent elements and down to children. This has some implications:

• Triggering an event on the root element will also trigger it on every element in the tree — usually not recommended.
• Handlers on the root element will catch every event — use this only when necessary.
• You can attach a handler to your resource's root element to catch all events from elements your resource created.
• You can create "dummy" elements to act as containers for groups of child elements and attach your handler to the dummy.
• You can define dummy elements in a .map file (e.g. a "flag") and dynamically create "real" objects as their children. This allows one resource to manage the representation (e.g. the object model) while another handles game logic. For example, a map resource can define the flag, and a gamemode resource can listen for capture events on it.

Event Parameters

Event handlers also receive specific parameters depending on the event. For example, the onClientGUIClick event provides the following parameters:

string button, string state, int absoluteX, int absoluteY

When writing a handler, be sure to check the documentation to see what arguments are passed for each event — they vary from one event to another.

Built-in Events

MTA provides a wide range of built-in events, which are listed here:

• Client Scripting Events
• Server Scripting Events

Custom Events

You can define and trigger your own custom events to communicate between different parts of your code — or even different resources. To define a custom event, use addEvent. You can then trigger it using triggerEvent.

For instance, in a Capture the Flag game mode, you could trigger an onFlagCaptured event when a player captures a flag:

1. Attach a handler to the onMarkerHit event.
2. Check if the player has the flag.
3. If yes, trigger the custom onFlagCaptured event.

This allows other resources to react to your event however they want.

Canceling Events

You can cancel certain events using cancelEvent. This stops the default action from occurring. For example:

• Canceling onPickupUse stops the player from picking up the item.
• Canceling onVehicleStartEnter stops the player from entering the vehicle.

To check if an event has already been canceled, use wasEventCancelled.

Note: Canceling an event does not stop other event handlers from being triggered.