Getting Started with Entity variables

From RAGE Multiplayer Wiki
Jump to navigation Jump to search

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:

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 whether 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 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.

Server-Side
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.
        }
    }
});

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: addDataHandler triggers on all clients when one entity updates its synced variable, so make sure to specify your scope if its per player operation.

Client-Side
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;
    }
});

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.

Server-Side
mp.events.add('playerReady', (player) => {
  player.whatever = 'something'; // that initializes an object property to player that can be used serverside only
});


Client-Side
  mp.gui.chat.push('Scope Test: ' mp.players.local.whatever); // Displays: "Scope Test: undefined"

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