О чем этот пример

В Phaser каждый игровой объект может хранить собственные данные — от имени персонажа до количества золота. Но что, если изменение этих данных должно мгновенно влиять на игру: обновлять интерфейс, ограничивать значения или запускать анимации? Именно для этого в движке есть Data Manager и события `changedata`. Эта система позволяет создавать реактивные связи между состоянием объекта и логикой игры, что особенно полезно для RPG, инвентарей или систем прогресса. В этой статье разберем, как привязать кастомные данные к спрайту и настроить слушателей на их изменение. Вы научитесь создавать умные объекты, которые сами следят за своими параметрами и реагируют на их обновление.

Версия Phaser: код и демо в этой статье рассчитаны на Phaser 3.90.0.

Живой запуск

Ниже встроен рабочий билд примера. Оригинальный источник: GitHub.

Исходный код


class Example extends Phaser.Scene
{
    constructor ()
    {
        super();
    }

    preload ()
    {
        this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
        this.load.image('gem', 'assets/sprites/gem.png');
    }

    create ()
    {
        const text = this.add.text(350, 250, '', { font: '16px Courier', fill: '#00ff00' });
        const gem = this.add.image(300, 300, 'gem');

        //  Store some data about this Gem:
        gem.setDataEnabled();

        gem.data.set('name', 'Red Gem Stone');
        gem.data.set('level', 2);
        gem.data.set('owner', 'Link');
        gem.data.set('gold', 50);

        text.setText([
            'Name: ' + gem.data.get('name'),
            'Level: ' + gem.data.get('level'),
            'Value: ' + gem.data.get('gold') + ' gold',
            'Owner: ' + gem.data.get('owner')
        ]);

        //  Whenever the 'gold' property is updated we call this function AFTER the change has happened:
        gem.on('changedata-gold', function (gameObject, value) {
            if (value > 500)
            {
                gameObject.data.values.gold = 500;
            }
            else
            {
                text.setText([
                    'Name: ' + gem.data.get('name'),
                    'Level: ' + gem.data.get('level'),
                    'Value: ' + gem.data.get('gold') + ' gold',
                    'Owner: ' + gem.data.get('owner')
                ]);
            }
        });

        //  Change the 'value' property when the mouse is clicked
        this.input.on('pointerdown', function () {
            gem.data.values.gold += 100;
        });
    }
}

const config = {
    type: Phaser.WEBGL,
    parent: 'phaser-example',
    width: 800,
    height: 600,
    scene: Example
};

const game = new Phaser.Game(config);

Включаем и наполняем Data Manager

Phaser предоставляет встроенный менеджер данных для любого игрового объекта (спрайта, изображения, текста). Сначала его нужно активировать, а затем наполнить произвольными парами «ключ-значение». Это похоже на присвоение свойств, но с важным бонусом — возможностью отслеживать изменения.

gem.setDataEnabled();

// Записываем данные в объект
gem.data.set('name', 'Red Gem Stone');
gem.data.set('level', 2);
gem.data.set('owner', 'Link');
gem.data.set('gold', 50);

Метод setDataEnabled() включает Data Manager для объекта gem. После этого через gem.data.set() мы сохраняем четыре произвольных параметра: название, уровень, владельца и количество золота. Эти данные хранятся отдельно от стандартных свойств спрайта (вроде `x,y`) и не влияют на его отрисовку, пока мы сами не решим их использовать.

Отображение данных в интерфейсе

Сохраненные данные можно в любой момент получить через gem.data.get() и отобразить, например, в текстовом поле. Это основа для создания панелей характеристик, инвентаря или диалоговых окон.

const text = this.add.text(350, 250, '', { font: '16px Courier', fill: '#00ff00' });

text.setText([
    'Name: ' + gem.data.get('name'),
    'Level: ' + gem.data.get('level'),
    'Value: ' + gem.data.get('gold') + ' gold',
    'Owner: ' + gem.data.get('owner')
]);

Мы создаем объект text и формируем массив строк, каждая из которых получает значение из Data Manager. Теперь при запуске игры на экране будет отображаться информация о нашем драгоценном камне. Однако это статическое отображение — при изменении данных текст не обновится автоматически. Для этого нужны события.

Слушаем изменения с помощью changedata

Сила Data Manager раскрывается при использовании событий. Вы можете подписаться на изменение любого конкретного поля данных. Событие changedata-<key> срабатывает каждый раз, когда значение по ключу <key> модифицируется.

gem.on('changedata-gold', function (gameObject, value) {
    if (value > 500)
    {
        gameObject.data.values.gold = 500;
    }
    else
    {
        text.setText([
            'Name: ' + gem.data.get('name'),
            'Level: ' + gem.data.get('level'),
            'Value: ' + gem.data.get('gold') + ' gold',
            'Owner: ' + gem.data.get('owner')
        ]);
    }
});

Здесь мы добавляем слушателя на событие changedata-gold. Внутри функции-обработчика доступны два параметра: изменяемый игровой объект (gameObject) и новое значение (value). Код проверяет, не превысило ли золото лимит в 500 единиц. Если превысило — значение принудительно сбрасывается до 500. В противном случае текст на экране обновляется, отражая текущее состояние. Обратите внимание: для принудительного присвоения используется прямой доступ к gameObject.data.values.gold. Это предотвращает повторный вызов события и зацикливание.

Инициируем изменение данных

Чтобы событие сработало, данные нужно изменить. В примере это происходит по клику мыши. Прямое изменение значения в data.values автоматически вызывает связанное событие changedata.

this.input.on('pointerdown', function () {
    gem.data.values.gold += 100;
});

При каждом клике количество золота у камня увеличивается на 100. Это изменение триггерит событие changedata-gold, которое мы обработали ранее. Таким образом, интерфейс обновляется, а значение золота никогда не превысит 500, благодаря валидации внутри слушателя события. Этот паттерн позволяет централизовать логику валидации и реакции на изменения в одном месте.

Что попробовать дальше

Data Manager и события changedata в Phaser — это мощный дуэт для создания реактивных игровых систем. Вы можете привязывать к объектам любые данные и мгновенно реагировать на их изменение: обновлять HUD, включать ачивки, менять поведение противников или активировать диалоги. Для экспериментов попробуйте

  1. Добавить к объекту больше типов данных (например, health и maxHealth) и связать их с полоской жизни
  2. Создать событие changedata для поля owner и реализовать смену владельца предмета с визуальным эффектом
  3. Использовать setData() для массовой установки значений и getData() для получения всех данных разом