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

Использование сторонних библиотек или собственных плагинов — мощный способ расширить функционал вашей игры без переписывания ядра. Phaser 3 предоставляет удобный API для загрузки и подключения плагинов прямо из метода `preload`. В этой статье мы разберем, как загрузить JavaScript-плагин и использовать его методы в сцене, что особенно полезно для интеграции инструментов генерации контента, аналитики или специфичной игровой логики.

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

Живой запуск

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

Исходный код


class Example extends Phaser.Scene
{
    preload ()
    {
        this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
        this.load.plugin('RandomNamePlugin', 'assets/loader-tests/RandomNamePlugin.js', true);
    }

    create ()
    {
        let plugin = this.plugins.get('RandomNamePlugin');

        let names = plugin.getNames(10);

        this.add.text(10, 10, names, { font: '16px Courier', fill: '#00ff00' });
    }
}

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

let game = new Phaser.Game(config);

Настройка базового URL и загрузка плагина

Вся подготовка происходит в методе preload(). Первым делом мы указываем базовый URL для всех последующих запросов к ресурсам. Это удобно, если ваши ассеты и плагины хранятся на удаленном сервере или CDN.

Затем мы используем метод this.load.plugin() для загрузки самого плагина. Этот метод принимает три ключевых аргумента.

this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
this.load.plugin('RandomNamePlugin', 'assets/loader-tests/RandomNamePlugin.js', true);

- 'RandomNamePlugin' — это ключ, под которым плагин будет зарегистрирован в менеджере плагинов. Вы будете использовать его для получения экземпляра. - 'assets/loader-tests/RandomNamePlugin.js' — путь к JS-файлу плагина относительно базового URL. - true — флаг, указывающий, что плагин должен быть загружен и запущен немедленно.

Получение плагина и вызов его методов

После того как сцена перейдет в состояние create(), все загруженные ресурсы, включая плагины, будут готовы к использованию. Чтобы получить доступ к функционалу плагина, нужно запросить его экземпляр у менеджера плагинов сцены.

Менеджер плагинов доступен через this.plugins. Используя ключ, заданный при загрузке, мы получаем экземпляр класса плагина.

let plugin = this.plugins.get('RandomNamePlugin');

Теперь plugin — это объект, предоставляющий API загруженного плагина. В нашем примере плагин имеет метод getNames(), который, судя по контексту, генерирует список имен. Мы вызываем его, передавая нужное количество имен.

let names = plugin.getNames(10);

Результат работы плагина — данные, которые мы можем использовать в игре. В данном случае это строка или массив имен, которые мы отобразим на экране.

Отображение результата работы плагина

Чтобы визуализировать результат, мы используем текстовый объект Phaser. Метод this.add.text() создает и добавляет текст на дисплейный список сцены.

Мы передаем результат вызова plugin.getNames(10) прямо в качестве текстовой строки.

this.add.text(10, 10, names, { font: '16px Courier', fill: '#00ff00' });

- 10, 10 — координаты X и Y для позиционирования текста. - names — данные, полученные от плагина. - { font: '16px Courier', fill: '#00ff00' } — стиль текста. В данном случае это зеленый моноширинный шрифт размером 16 пикселей.

Структура конфигурации игры

Весь описанный функционал работает внутри стандартной конфигурации Phaser Game. Здесь нет специфичных для плагинов настроек — вся магия происходит на уровне сцены.

Конфиг создает экземпляр игры с автоматическим выбором рендерера (WebGL или Canvas) и указывает на нашу сцену Example.

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

let game = new Phaser.Game(config);

Как только игра будет создана, запустится сцена Example, начнется загрузка плагина и, после ее завершения, выполнится логика метода create().

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

Загрузка плагинов через this.load.plugin() — это прямой и эффективный способ модульного расширения вашей игры. Вы можете выносить в плагины системы диалогов, генераторы процедурного контента, интеграции с социальными функциями или сложные математические вычисления. Для экспериментов попробуйте

  1. Загрузить плагин с локального сервера, изменив setBaseURL
  2. Написать свой простой плагин, который, например, возвращает случайные цитаты или цвета
  3. Использовать плагин для предварительного расчета данных (например, карты уровня) перед созданием игрового мира