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:
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.
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.
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.
In 1.1 version:
Added: CEF: mp.events.add(string eventName, function handler)
Added: CEF: mp.events.reset()
Added: CEF: mp.events.remove(string eventName)
Added: CEF: mp.events.call(string eventName) (псевдоним к mp.trigger)
Added: Client-side: Browser.call(eventName, arguments...)
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.
JavaScript Syntax
Calling server-side or client-side local events
Syntax
mp.events.call('eventName', args);
Calling client-side events from server-side (the server-side calls client-side)
Notice: arguments must be inside an array.
Make a player call their client-side
Syntax
player.call('eventName', [arg1, arg2]);
Examples
Example 1
With this example we'll add a server-side command that calls a client-side event that starts a screen effect on the player who types the command. As show below, once a player types /effect [effect] (for example, /effect ChopVision) it will send whatever the player typed on the first argument to the event created on the client-side ('startEffectEvent').
mp.events.addCommand('effect', (player, fullText, effect) => {
player.call('startEffectEvent', [effect]);
});
On the client-side, it will received whatever the player typed on the first argument and replace it on the effect.
mp.events.add('startEffectEvent', (effect) => {
mp.game.graphics.startScreenEffect(effect, 10000, false);
});
Make all players in the server call their client-side
Syntax
mp.players.call('eventName', [arg1, arg2]);
Make server-side call a filtered player's client-side
The example below filters a player with the name WeirdNewbie to call his client-side.
Syntax
mp.players.call(mp.players.toArray().filter((_player) => _player.name == 'WeirdNewbie'), 'eventName', [args]);
Calling server-side events from client-side (the client-side calls server-side)
Syntax
mp.events.callRemote('eventName', args);
Calling a function registered in CEF from client-side (the client-side calls CEF)
Syntax
mbrowser.execute(´javascriptFunction('${variable1}','${variable2}');´);
Calling a client-side event from CEF (the CEF calls client-side)
Notice: You can't communicate between CEF and server-side
Syntax
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:
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:
// 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));