RAGE Multiplayer Wiki - User contributions [en]

Blip::Blip

2020-09-13T13:48:32Z

Almeidowski: Research results

{{SharedFunctionJS}}

Creates a blip to display on your map & minimap.
Blips created server-side seem to be impossible to attach to the map. If you create the same blip server-side and client-side, only the second will stay attached to the map (the scale won't change if you zoom in or out).

{{JSContainer|
== Syntax ==

<pre>
mp.blips.new(sprite, position,
{
name: name,
scale: scale,
color: color,
alpha: alpha,
drawDistance: drawDistance,
shortRange: shortRange,
rotation: rotation,
dimension: dimension,
radius: radius,
});
</pre>

=== Parameters ===
*'''{{Required}}sprite''': {{RageType|Int}} ([[Blips#Blip_model|Blip sprites]])
*'''{{Required}}position''': {{RageType|Vector3}}
*'''name''': {{RageType|String}}
*'''scale''': {{RageType|Float}}: How big the blip shows on the map
*'''color''': {{RageType|Color ID}} ([[Blips#Blip_colors|Blip colors]])
*'''alpha''': {{RageType|Int}} [0:255]
*'''drawDistance''': {{RageType|Float}}
*'''shortRange''': {{RageType|Boolean}}: If it's hidden in the minimap until the player is close
*'''rotation''': {{RageType|Float}}
*'''dimension''': {{RageType|Int}}
*'''radius''': {{RageType|Float}}

== Example ==

This creates a blip at the police station. The blip is assigned to the variable '''policeBlip'''.

{{SharedCode|
<pre>
let policeBlip = mp.blips.new(60, new mp.Vector3(427.95, -981.05, 0),
{
name: 'Los Santos Police Station',
color: 3,
shortRange: true,
});
</pre>
}}
}}

== See Also ==
{{Blip_definition}}

[[Category:Blip API]]
[[Category:Shared Function]]

Getting Started with Entity variables

2020-09-08T21:27:43Z

Almeidowski: Grammar

== Getting Started ==

In this page you'll learn about how to use '''Entity''' variables. This is a list of functions that are related to the entity variables:

*'''Functions''':
**[[Entity::getVariable|getVariable]]
**[[Entity::setVariable|setVariable]]
**[[Events::addDataHandler|addDataHandler]]

== What is entity variables? ==

Entity variables are custom assigned data to a certain entity to identify it either locally or globally to all other clients on the server. You have the flexibility to choose weather to keep it private or public.

== Synced entity variables ==
Synced entity variables are custom data that are assigned to the entity globally so other clients can read these data. Synced entity variables are only writable server-side, which means no one can overwrite data from client-side.
Let's say you need to keep your scoreboard updated every 3 seconds and it displays every player's cash, ping, job, and etc. To keep things up to date you'll definitely need to use synced entity variables to display updated values since for example a player made an transaction then his cash is updated server-side, then the scoreboard should automatically update it in the next refresh call by getting each player's synced variable. There are many applications for entity synced variables and you can explore [https://rage.mp/files/category/3-scripts/ resources] to get to know more about it.

== Example ==
We'll do a short example about money HUD and how it works with entity synced variables.

Firstly we'll setup our server-side simple money API

In server-side we did a small manager that accepts withdrawal/deposit money and updates the synced entity variable of the player that requested the operation.
{{ServersideCode|
<pre>
mp.events.add({
'playerReady': (player) => {
if (player) {
/*
* Setting our start cash value by 0
* You can sync it via Database if you got one.
* player.data.cash = 0 can work too
*/
player.setVariable('cash', 0);
// player.data.cash = 0
}
},
'withdraw': (player, amount) => {
let currentMoney = player.getVariable('cash'); // Getting base cash from entity.
if (currentMoney && currentMoney >= 0 && amount > 0) {
currentMoney += amount;
player.setVariable('cash', currentMoney); // Setting base cash of entity to new value.
}
},
'deposit': (player, amount) => {
let currentMoney = player.getVariable('cash'); // Getting base cash from entity.
if (currentMoney && currentMoney >= 0 && currentMoney >= amount) {
currentMoney -= amount;
player.setVariable('cash', currentMoney); // Setting base cash of entity to new value.
}
}
});
</pre>
}}

Now on client-side we should do a small money HUD that'll display the cash and update once an operation has been made.
'''NOTE''': [[Events::addDataHandler|addDataHandler]] triggers on all clients when one entity updates its synced variable, so make sure to specify your scope if its per player operation.
{{ClientsideCode|
<pre>
const localPlayer = mp.players.local;
let currentMoney;

mp.events.add('render', () => {
if (currentMoney) { // Draws money HUD only if currentMoney is initalized
mp.game.graphics.drawText('$' + currentMoney, [0.85, 0.1], {
font: 7,
color: [133, 187, 101, 185],
scale: [0.8, 0.8],
outline: true
});
}
});

mp.events.addDataHandler('cash', (entity, newCash, oldCash) => {
if (entity && entity.remoteId === localPlayer.remoteId && newCash !== oldCash) { // Make sure the money update is for the money operation requester since addDataHandler triggers on any entity synced variable change
currentMoney = newCash;
}
});
</pre>
}}

== Local Entity variables ==
You can also set variables to entities for local scope like on server-side or client-side only to help protect sensitive data from public if needed.
{{ServersideCode|
<pre>
mp.events.add('playerReady', (player) => {
player.whatever = 'something'; // that initializes an object property to player that can be used serverside only
});
</pre>
}}

{{ClientsideCode|
<pre>
mp.gui.chat.push('Scope Test: ' mp.players.local.whatever); // Displays: "Scope Test: undefined"
</pre>
}}

== Final notes ==
Entity variables are destroyed once the entity is no longer available in the world. Like player reconnecting or quit or vehicle delete.

== See also ==
{{ScriptingTutorials}}

[[Category:Tutorials]]

Blip::Blip

2020-09-05T11:37:47Z

Almeidowski:

{{SharedFunctionJS}}

Creates a blip to display on your map & minimap.

{{JSContainer|
== Syntax ==

<pre>
mp.blips.new(sprite, position,
{
name: name,
scale: scale,
color: color,
alpha: alpha,
drawDistance: drawDistance,
shortRange: shortRange,
rotation: rotation,
dimension: dimension,
radius: radius,
});
</pre>

=== Parameters ===
*'''{{Required}}sprite''': {{RageType|Int}} ([[Blips#Blip_model|Blip sprites]])
*'''{{Required}}position''': {{RageType|Vector3}}
*'''name''': {{RageType|String}}
*'''scale''': {{RageType|Float}}: How big the blip shows on the map
*'''color''': {{RageType|Color ID}} ([[Blips#Blip_colors|Blip colors]])
*'''alpha''': {{RageType|Int}} [0:255]
*'''drawDistance''': {{RageType|Float}}
*'''shortRange''': {{RageType|Boolean}}: If it's hidden in the minimap until the player is close
*'''rotation''': {{RageType|Float}}
*'''dimension''': {{RageType|Int}}
*'''radius''': {{RageType|Float}}

== Example ==

This creates a blip at the police station. The blip is assigned to the variable '''policeBlip'''.

{{SharedCode|
<pre>
let policeBlip = mp.blips.new(60, new mp.Vector3(427.95, -981.05, 0),
{
name: 'Los Santos Police Station',
color: 3,
shortRange: true,
});
</pre>
}}
}}

== See Also ==
{{Blip_definition}}

[[Category:Blip API]]
[[Category:Shared Function]]

Pool::forEach

2020-09-02T11:35:09Z

Almeidowski: Adding a third and easier to understand example

This function is used for calling a function for each element in a pool.

==Syntax==
<pre>
pool.forEach(Function callingFunction);
</pre>
===Required Arguments===
*'''callingFunction:''' Function, what will be called.

==Example #1==
This example will generate text with all player nicknames.

{{ServersideCode|
<pre>
let getNicknamesText = () => {
let text = ``;
mp.players.forEach(
(player, id) => {
text = text == `` ? player.name : `${text} , ${player.name}`;
}
);
return text;
};

let blahBlah = getNicknamesText();
console.log(blahBlah != `` ? blahBlah : `Server not have players.`);
</pre>
}}

==Example #2==
This example will add a command to remove all server vehicles by forEach.
{{ServersideCode|
<pre>
mp.events.addCommand(`removeAll`,
(player) => {
mp.vehicles.forEach(
(vehicle) => {
vehicle.destroy();
}
);
mp.players.broadcast(`${player.name} DESTROY ALL CARS!`);
}
);
</pre>
}}
==Example #3==
This example will teleport a player that types the command /port to the player whose name he writes as 1st argument.
{{ServersideCode|
<pre>
mp.events.addCommand('port', (player, name) => {
mp.players.forEach(_player => {
if(_player.name === name)
player.position = _player.position;
});
});
</pre>
}}
==See Also==
{{EntityPool_function}}

Getting Started with Events

2020-08-31T16:45:07Z

Almeidowski:

== 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|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 [[Events::add|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|Server-side events]]
*[[Client-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.

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

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.

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

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.
{{JSContainer|
===Calling server-side or client-side local events===
====Syntax====
<pre>
mp.events.call('eventName', args);
</pre>
===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=====
<pre>
player.call('eventName', [arg1, arg2]);
</pre>
=====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').
{{ServersideCode|
<pre>
mp.events.addCommand('effect', (player, fullText, effect) => {
player.call('startEffectEvent', [effect]);
});
</pre>
}}
On the client-side, it will received whatever the player typed on the first argument and replace it on the effect.
{{ClientsideCode|
<pre>
mp.events.add('startEffectEvent', (effect) => {
mp.game.graphics.startScreenEffect(effect, 10000, false);
});
</pre>
}}
====Make all players in the server call their client-side====
=====Syntax=====
<pre>
mp.players.call('eventName', [arg1, arg2]);
</pre>
====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=====
<pre>
mp.players.call(mp.players.toArray().filter((_player) => _player.name == 'WeirdNewbie'), 'eventName', [args]);
</pre>
===Calling server-side events from client-side (the client-side calls server-side)===
====Syntax====
<pre>
mp.events.callRemote('eventName', args);
</pre>
===Calling a function registered in CEF from client-side (the client-side calls CEF)===
====Syntax====
<pre>
mbrowser.execute(´javascriptFunction('${variable1}','${variable2}');´);
</pre>
===Calling a client-side event from CEF (the CEF calls client-side)===
Notice: You can't communicate between CEF and server-side
====Syntax====
<pre>
mp.trigger('eventName', args);
</pre>
}}

== 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 ([[Events::Event|mp.Event]]). 
A small example of how to use it:

{{ServersideCode|
<pre>
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
</pre>
}}

=== Removing ===

Here are all the methods to remove events:

{{SharedCode|
<pre>
// 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));
</pre>
}}

== See also ==
{{ScriptingTutorials}}

[[Category:Tutorials]]

Object::Object

2020-08-30T12:18:44Z

Almeidowski:

{{SharedFunctionJS}}

Creates a new Object.

*'''[https://cdn.rage.mp/public/odb/index.html Objects gallery]'''

{{JSContainer|
==Syntax==
{{SharedCode|
<pre>
mp.objects.new(model, position,
{
rotation: rotation,
alpha: alpha,
dimension: dimension
});
</pre>
}}

==Required Arguments==
*'''model''': {{RageType|Hash}}
*'''position''': {{RageType|Vector3}}
*'''rotation''': {{RageType|Vector3}}
*'''alpha''': {{RageType|Number}}: The object's transparency.
*'''dimension''': {{RageType|Number}}

==Example==

<pre>
mp.events.addCommand('flag', (player) => {
mp.objects.new('apa_prop_flag_portugal, player.position,
{
rotation: player.rotation,
alpha: 250,
dimension: player.dimension
});
});

//Following this code, you'll create a portuguese flag (apa_prop_flag_portugal) at the players position, facing the same way the player is facing, with no transparency (250 on alpha) and at the same dimension the player is.
</pre>
}}
[[Category:Object API]]
[[Category:Shared Function]]
[[Category:TODO: Example]]

Object::Object

2020-08-30T12:13:19Z

Almeidowski:

{{SharedFunctionJS}}

Creates a new Object.

*'''[https://cdn.rage.mp/public/odb/index.html Objects gallery]'''

{{JSContainer|
==Syntax==
{{SharedCode|
<pre>
mp.objects.new(model, position,
{
rotation: rotation,
alpha: alpha,
dimension: dimension
});
</pre>
}}

==Required Arguments==
*'''model''': {{RageType|Hash}}
*'''position''': {{RageType|Vector3}}
*'''rotation''': {{RageType|Vector3}}
*'''alpha''': {{RageType|Number}}: The object's transparency.
*'''dimension''': {{RageType|Number}}

==Example==

<pre>
mp.events.addCommand('flag', (player) => {
mp.objects.new('apa_prop_flag_portugal, player.position,
{
rotation: player.rotation,
alpha: 100,
dimension: player.dimension
});
});

//Following this code, you'll create a portuguese flag (apa_prop_flag_portugal) at the players position, facing the same way the player is facing, with no transparency (100 on alphaa) and at the same dimension the player is.
</pre>
}}
[[Category:Object API]]
[[Category:Shared Function]]
[[Category:TODO: Example]]