Getting Started with Events

RAGE:MP Documentation

Events System

Events are the backbone of scripting in RAGE:MP. This page explains what they are, how to register them, how communication works between server, client, and CEF, and how to manage them cleanly.

Core Idea

Events react to things

Built-in events react automatically. Custom events react when you trigger them.

Communication

Know your direction

Server, client, and CEF do not all communicate the same way.

Rule

Register first

An event must be registered before you can use or trigger it.

Introduction

Events are the core scripting system for RAGE:MP.

They are registered by you and triggered when a specific action or situation happens.

For example, PlayerEnterCheckpoint is triggered when a player enters a checkpoint. That event gives you:

• the Player that entered it
• the Checkpoint that was entered

Event Types

Type 1

Built-in Events

These are provided by RAGE:MP and are triggered automatically in certain situations.

Examples:

• player entering a checkpoint
• player quitting
• player spawning

Lists:

• Server-side events
  
• Client-side events

Type 2

Custom Events

These are created by you and can be triggered whenever you want.

Use them to:

• connect systems together
• trigger your own gameplay logic
• send data between layers
• create reusable scripting flows

Registering Events

Important: You must register an event before using it anywhere.

Server-side Event

A normal server-side event can be registered like this:

Server-Side

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

Client → Server Event

If the event is triggered from client-side but registered on server-side, the first argument must be player.

This happens because the client sends the local player together with the event data, allowing the server to know who triggered it.

Server-Side

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

CEF Notes

CEF behaves differently

• CEF cannot communicate directly with server-side
• CEF mainly communicates with client-side
• Older documentation often describes CEF more restrictively, but newer support exists in later versions

In version 1.1:

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) (alias to mp.trigger)
Added: Client-side: Browser.call(eventName, arguments...)

Calling Events

Tip: Most event confusion comes from not knowing which side is calling which side.

Local

Same Side

Use this when you call an event on the same side it exists on.

Syntax

JavaScript Syntax

mp.events.call('eventName', args);

Remote

Server → Client

The server tells one player or multiple players to execute a client-side event.

Single player

JavaScript Syntax

player.call('eventName', [arg1, arg2]);

All players

JavaScript Syntax

mp.players.call('eventName', [arg1, arg2]);

Filtered players

JavaScript Syntax

mp.players.call(
    mp.players.toArray().filter((_player) => _player.name == 'WeirdNewbie'),
    'eventName',
    [args]
);

Remote

Client → Server

Use this when the client wants to trigger a server-side event.

Syntax

JavaScript Syntax

mp.events.callRemote('eventName', args);

Bridge

Client ↔ CEF

CEF does not directly talk to server-side. It goes through the client.

Client → CEF

JavaScript Syntax

mbrowser.execute(`javascriptFunction('${variable1}', '${variable2}');`);

CEF → Client

JavaScript Syntax

mp.trigger('eventName', args);

Example Flow

Server command triggering a client effect

In this example, a player uses a server command, and the server tells that player's client to start a screen effect.

Server-side

Server-Side

mp.events.addCommand('effect', (player, fullText, effect) => {
    player.call('startEffectEvent', [effect]);
});

Client-side

Client-Side

mp.events.add('startEffectEvent', (effect) => {
    mp.game.graphics.startScreenEffect(effect, 10000, false);
});

Cancelling and Managing Events

Method 1

Pause / Destroy

To control an event instance directly, you can use mp.Event.

Server-Side

let ev = new mp.Event("playerDeath", (player, reason, killer) =>
{
    mp.players.broadcast('First blood!');
    ev.destroy(); // this event handler will not be called anymore
});

// ev.destroy(); // destroy it before it can execute again

Method 2

Remove from Tree

You can remove a specific handler, remove all handlers for an event, remove multiple events, or reset the whole tree.

Shared

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

}

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

// Remove handler(s) of 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));

Quick Reference

Cheat Sheet

Action	Method
Register local event	mp.events.add(...)
Call local event	mp.events.call(...)
Client to server	mp.events.callRemote(...)
Server to one client	player.call(...)
Server to all clients	mp.players.call(...)
CEF to client	mp.trigger(...)
Client to CEF	browser.execute(...)
Remove event	mp.events.remove(...)
Reset all events	mp.events.reset()

Summary

• Events are the foundation of scripting in RAGE:MP
• Built-in events are automatic, custom events are created by you
• Always register events before using them
• Server, client, and CEF each have different communication rules
• You can disable, destroy, remove, or reset events when needed

See also

• Getting Started With Server
• Getting Started with Server development
• Getting Started with Server-side commands
• Getting Started with Client-side
• Getting Started with Events
• Getting Started with Entity variables