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

Встроенные возможности Phaser 3 обширны, но иногда для уникальных механик или сложной визуализации нужны собственные инструменты. Scene Plugin (плагин сцены) позволяет инкапсулировать логику и повторно использовать её в разных сценах. В этой статье разберем, как загрузить и использовать кастомный плагин сцены, чтобы расширить функционал вашей игры без хака кода. Это полезно для создания систем частиц, процедурной генерации или сложных анимаций, которые должны быть доступны в контексте конкретной сцены.

Версия 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.scenePlugin('FractalPlugin', 'assets/loader-tests/FractalScenePlugin.js', 'fractalPlugin', 'fractals');
    }

    create ()
    {
        const image = this.fractals.create(400, 300, 256, 256);

        image.setScale(2);
    }
}

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

let game = new Phaser.Game(config);

Что такое Scene Plugin?

Scene Plugin — это пользовательский JavaScript-класс, который при загрузке становится частью экземпляра сцены (this). В отличие от глобальных плагинов игры, он живёт и работает только в рамках своей сцены. Это идеально для функционала, который требуется не везде, например, для управления уникальным UI или генерации спецэффектов.

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

Загрузка плагина в `preload()`

Загрузка происходит в методе preload() сцены с помощью менеджера this.load. Ключевой метод здесь — load.scenePlugin().

this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
this.load.scenePlugin('FractalPlugin', 'assets/loader-tests/FractalScenePlugin.js', 'fractalPlugin', 'fractals');

Разберем параметры вызова load.scenePlugin: 1. **Ключ загрузки ('FractalPlugin')**: Внутренний идентификатор для менеджера загрузки. 2. **URL файла ('assets/loader-tests/FractalScenePlugin.js')**: Путь к JS-файлу с кодом плагина. Базовый URL задаётся через setBaseURL. 3. **Системный ключ ('fractalPlugin')**: Имя, под которым плагин будет зарегистрирован в системе плагинов сцены (обычно используется фреймворком). 4. **Ключ доступа на сцене ('fractals')**: **Самое важное!** После успешной загрузки экземпляр плагина будет доступен в сцене как this.fractals.

Использование плагина в `create()`

После завершения загрузки в методе create() мы можем обращаться к плагину через заданное свойство (this.fractals) и вызывать его методы.

const image = this.fractals.create(400, 300, 256, 256);
image.setScale(2);

В данном коде: - this.fractals.create(400, 300, 256, 256) — вызов метода create нашего плагина. Судя по аргументам (x, y, width, height), он создает и возвращает игровой объект (вероятно, Image), представляющий фрактал. - image.setScale(2) — стандартный метод Phaser для масштабирования полученного объекта. Это доказывает, что плагин интегрируется в экосистему и возвращает совместимые объекты.

Конфигурация игры и сцена

Конфигурация игры стандартна и просто указывает на наш класс Example как на стартовую сцену.

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

let game = new Phaser.Game(config);

Никакой специальной настройки для плагинов сцены здесь не требуется. Вся магия происходит внутри сцены в методе preload.

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

Использование Scene Plugin — это мощный паттерн для структурирования кода в Phaser 3. Он позволяет выносить специализированную логику в отдельные модули, делая сцены чище и повышая переиспользуемость кода. Для экспериментов попробуйте

  1. Создать простой плагин, добавляющий на сцену кастомный текст или счётчик
  2. Загрузить два разных плагина в одну сцену
  3. Использовать плагин для управления состоянием мини-игры внутри основной сцены