View source for Getting Started with Entity variables

== 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, but don't worry synced entity variables are only writable server-side so 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 is 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.