JS Переменные сущностей (Entity Variables)

[Lev Angel]

Переменные сущностей это пользовательские данные связанные с определенной сущностью (игроком, npc, транспортом и т. п.). Они могут быть локальными или глобальными (доступными для всех клиентов на сервере).

Для работы с ними есть 3 метода:

Entity::getVariable - RAGE Multiplayer Wiki

wiki.rage.mp

Entity::setVariable - RAGE Multiplayer Wiki

wiki.rage.mp

Events::addDataHandler - RAGE Multiplayer Wiki

wiki.rage.mp

Синхронизированные переменные (Synced entity variables)
Синхронизированные переменные сущностей это данные привязанные к сущности глобально и все клиенты могут их прочитать. Синхронизированные переменные могут быть записаны только на стороне сервера, что значит что никто на стороне клиента их не сможет перезаписать.

Предположим вам нужна табличка со списком всех игроков на сервере, которая будет обновляться каждые 3 секунды и будет выводить деньги, пинг, работу и т. п. Чтобы поддерживать актуальность, вам обязательно нужно использовать синхронизированные переменные для отображения обновленных значений, поскольку, например, игрок совершил транзакцию, тогда его денежные средства обновляются на стороне сервера, а затем в таблице данные тоже должны автоматически обновиться локально у каждого клиента.

Пример
Мы сделаем небольшой пример. Выведем деньги игрока в HUD используя синхронизированные переменные.
Сначала настроим серверную часть и API для управления деньгами.
На стороне сервера мы сделаем два обработчика событий которые будут снимать/добавлять деньги игроку и обновлять их значение в синхронизированной переменной cash.

mp.events.add({
    'playerReady': (player) => {
        if (player) {
            /*
             * При входе игрока ставим деньги в 0
             * Также можно выгружать начальное значение из базы данных.
             * player.data.cash = 0 тоже сработает
             */
            player.setVariable('cash', 0);
            // player.data.cash = 0
        }
    },
    'withdraw': (player, amount) => {
        let currentMoney = player.getVariable('cash'); // Получаем текущее значение переменной cash из объекта игрока
        if (currentMoney && currentMoney >= 0 && amount > 0) {
            currentMoney += amount;
            player.setVariable('cash', currentMoney); // обновляем значение
        }
    },
    'deposit': (player, amount) => {
        let currentMoney = player.getVariable('cash');
        if (currentMoney && currentMoney >= 0 && currentMoney >= amount) {
            currentMoney -= amount;
            player.setVariable('cash', currentMoney);
        }
    }
});

Теперь на стороне клиента сделаем небольшой HUD для вывода количества денег у игрока.

const localPlayer = mp.players.local;
let currentMoney;

mp.events.add('render', () => {
    if (currentMoney) { // Выводим деньги в HUD только если задано значение в currentMoney
        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) => { // Срабатываем когда на сервере меняется значение в переменной cash у одного из объектов
    if (entity && entity.remoteId === localPlayer.remoteId && newCash !== oldCash) { // Проверяем чтобы данные в переменной были обновлены для локального игрока
        currentMoney = newCash;
    }
});

Примечание: addDataHandler срабатывает на всех клиентах когда для любой сущности обновляются ее синхронизированные переменные, это нужно учитывать и в примере выше мы делаем проверку, чтобы обновить данные в hud только у того игрока у которого поменялось значение cash.


Локальные переменные сущностей
Также можно задавать локальные переменные для объекта либо на сервере, либо на клиенте. Такие переменные не синхронизируются и остаются только на той стороне, где они были объявлены.
Например, объявим переменную на сервере

mp.events.add('playerReady', (player) => {
  player.whatever = 'something';
})

На клиенте эта переменная будет недоступна

mp.gui.chat.push('Scope Test: ' mp.players.local.whatever); // Выведет: "Scope Test: undefined"

Также если мы объявим подобным образом переменную на одном клиенте, то она будет недоступна на других клиентах и на сервере.


Переменные сущности удаляются вместе с ней, когда объект уже недоступен. Например, когда игрок пере заходит или выходит в сервера.

Источник: Getting_Started_with_Entity_variables​