Getting Started with Events

Introduction

Events are the core scripting system for RAGE:MP. They are registered upon your request and triggered in a certain situation, For example, PlayerEnterCheckpoint triggers when a player enters a checkpoint, so the event is automatically triggered and returns for you the Player that entered the checkpoint and the Checkpoint that he entered.

Events system

In-order to use the events you need to register the event into the events tree using addEvent.
There are 2 types of Events:

• Built in events
• Custom events

Built in events

They are events provided by RAGE:MP to be auto-triggered in a certain situation as we mentioned in the beginning (a Player entering a Checkpoint).

These are listed on the following pages:

• Server-side events
• Client-side events

Custom events

They are events build for you to control/call them anytime you want and in any situation you create for the Player.

Using events

Registering an event

You always have to register an event to the events tree before using it anywhere.

Registering it is pretty simple, but you have to keep in mind in which area it'll be called.

if your event will be for server-side use only then you can register it the way you want.

Server-Side

mp.events.add('eventName', (arg1, arg2, etc.) => {
// code
});

if your event will be called from client-side and you registered it in server-side. You have to add player argument as a main first argument because client-side delivers the localPlayer with your data, so you can know which player is it.

Server-Side

mp.events.add('eventName', (player, arg1, arg2, etc.) => {
// code
});

In CEF you're not allowed to register any events. You can only call the functions that are registered in your CEF.

Calling methods

It is pretty important to know how to call your events on each side, or you'll be totally lost in your development. We made it easier for you with the following calling methods, so you can know how the events calling system is working.

// calls server-side local events / calls client-side local events
mp.events.call('eventName', args);

/*
* Calls client-side event from server-side.
* Notice: arguments must be inside an array.
*/
player.call('eventName', [arg1, arg2]);

/*
* Makes server's all players call their client-side.
* Notice: arguments must be inside an array.
*/
mp.players.call('eventName', [arg1, arg2]);

/*
* Makes server-side call filtered player's client-side. 
* For example this filters player with name '''WeirdNewbie''' to call his client-side.
* Notice: arguments must be inside an array.
*/
mp.players.call(mp.players.toArray().filter((_player) => _player.name == 'WeirdNewbie'), 'eventName', [args]);

// Makes client-side call server-side event
mp.events.callRemote('eventName', args);

// Makes client-side call a function registered in CEF
browser.execute(´javascriptFunction('${variable1}','${variable2}');´);

/*
* Makes CEF call a event in client-side.
* Notice: You can't communicate between CEF and server-side
*/
mp.trigger('eventName', args);

Cancelling events

There are 2 ways to cancel a event:

• Pausing it for future use.
• Removing it from events tree.

Pausing

In-order to pause a event you are required to use a special function to add that event (mp.Event).
A small example of how to use it:

Server-Side

let ev = new mp.Event("playerDeath", (player, reason, killer) =>
{
    mp.players.broadcast('First blood!');
    ev.destroy(); // this event handler will be not called anymore since it's destroyed
});
// ev.enable(); due to this line the event will be re-enabled.
// ev.destroy(); due to this line the event is never going to be executed if we call this before it

Removing

Here are all the methods to remove events:

Shared

// Remove specified handler of specified event
function playerJoinHandler(player)
{

}

mp.events.add("playerJoin", playerJoinHandler);
mp.events.remove("playerJoin", playerJoinHandler);

// Remove handler(s) specified event(s)
mp.events.remove("playerJoin");
mp.events.remove(["playerJoin", "playerQuit"]);

// Reset whole event tree.
mp.events.reset();

// Get all handlers of specified event
mp.events.getAllOf("playerJoin").forEach(_ev => _ev(null));