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

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

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

Живой запуск

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

Исходный код


class TestPlugin extends Phaser.Plugins.BasePlugin {

    constructor (pluginManager)
    {
        super(pluginManager);
    }

    wibble ()
    {
        console.log('hello');
    }

}

var config = {
    type: Phaser.AUTO,
    parent: 'phaser-example',
    width: 800,
    height: 600,
    plugins: {
        global: [
            { key: 'TestPlugin', plugin: TestPlugin, start: false, mapping: 'test' }
        ]
    },
    scene: {
        preload: preload,
        create: create
    }
};

var game = new Phaser.Game(config);

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

function create ()
{
    this.test.wibble();
}

Что такое глобальный плагин?

Глобальный плагин в Phaser — это класс, который регистрируется на уровне игры и становится доступным во всех её сценах. Это не часть сцены, а отдельный модуль, "вшитый" в экземпляр Phaser.Game. Его ключевое преимущество — единая точка инициализации и глобальная доступность.

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

plugins: {
    global: [
        { key: 'TestPlugin', plugin: TestPlugin, start: false, mapping: 'test' }
    ]
}

Создаём класс плагина

Класс плагина должен наследоваться от базового класса Phaser.Plugins.BasePlugin. Конструктор обязан вызывать super(pluginManager), передавая менеджер плагинов. Это обязательное требование для корректной интеграции с системой плагинов Phaser.

Внутри класса вы определяете свои методы. В нашем примере это метод wibble, который просто выводит сообщение в консоль. На этом этапе вы можете инициализировать внутреннее состояние плагина, подписываться на системные события игры или настраивать необходимые ресурсы.

class TestPlugin extends Phaser.Plugins.BasePlugin {
    constructor (pluginManager) {
        super(pluginManager);
    }

    wibble () {
        console.log('hello');
    }
}

Регистрация плагина в конфиге игры

Чтобы движок узнал о вашем плагине, его нужно добавить в конфигурацию при создании экземпляра Phaser.Game. Это делается в секции plugins.global. Каждый плагин описывается объектом с несколькими важными свойствами.

Свойство key — это внутренний уникальный идентификатор плагина в системе. plugin — ссылка на сам класс. Параметр start управляет автоматическим вызовом метода start плагина после его создания (в нашем случае он отключён). Самый важный параметр — mapping. Именно это имя ('test') будет использоваться для доступа к API плагина из сцены через this.test.

var config = {
    // ... другие настройки ...
    plugins: {
        global: [
            { key: 'TestPlugin', plugin: TestPlugin, start: false, mapping: 'test' }
        ]
    }
};

Использование плагина в сцене

После регистрации плагин становится доступен в любой сцене игры. Доступ к нему осуществляется через то самое свойство, которое было задано в параметре mapping. В нашем случае это this.test.

В коде сцены create мы просто вызываем метод wibble() нашего плагина. Обратите внимание: плагин доступен сразу, не требуется никакой дополнительной инициализации внутри сцены. Это и есть главная цель глобальных плагинов — предоставить готовый сервис в любом месте кода.

function create ()
{
    // Вызываем метод нашего глобального плагина
    this.test.wibble(); // В консоли появится 'hello'
}

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

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

  1. Добавить в плагин метод, который создаёт спрайт в заданных координатах
  2. Реализовать плагин-счётчик очков с методами для добавления, сброса и получения значения
  3. Создать плагин, который в методе start подписывается на событие step игры и выводит FPS