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

Загрузка ресурсов — фундаментальный этап в создании игры. Часто недостаточно просто дождаться окончания всей очереди загрузки. Что, если вам нужно мгновенно показать фоновое изображение, как только оно станет доступно, не дожидаясь остальных ассетов? Или запустить специфичную анимацию для конкретного спрайта? Механизм событий Phaser Loader даёт вам такой точный контроль. В этой статье мы разберём, как использовать событие `filecomplete` с ключом ресурса для выполнения кода сразу после загрузки одного конкретного файла.

Версия 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.image('taikodrummaster', 'assets/pics/taikodrummaster.jpg');

        this.load.image('sukasuka-chtholly', 'assets/pics/sukasuka-chtholly.png');

        this.load.on('filecomplete-image-taikodrummaster', this.addImage, this);
    }

    addImage (key, file)
    {
        this.add.image(400, 300, key);
    }
}

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

const game = new Phaser.Game(config);

Суть события `filecomplete`

Класс Phaser.Loader.LoaderPlugin является мощным менеджером загрузки. Помимо общего события complete, которое срабатывает после загрузки всей очереди, он предоставляет более детализированные события. Событие filecomplete генерируется каждый раз, когда загрузка любого отдельного файла успешно завершена.

Однако, чтобы отреагировать на загрузку конкретного ресурса, можно использовать специальную форму этого события, где в его имени указан тип и ключ файла. Это позволяет привязать обработчик к моменту готовности определённого изображения, аудиофайла или JSON-данных.

Анатомия именованного события

Имя события формируется по шаблону: filecomplete-[TYPE]-[KEY]. В нашем примере загружаются два изображения с ключами taikodrummaster и sukasuka-chtholly. Для первого изображения мы регистрируем обработчик.

Ключевые параметры: - TYPE: Тип загружаемого файла (например, image, audio, json). - KEY: Уникальный строковый ключ, который вы присвоили ресурсу в методе загрузки (например, в this.load.image('taikodrummaster', ...)).

Таким образом, полное имя события для нашего фонового изображения будет filecomplete-image-taikodrummaster.

this.load.on('filecomplete-image-taikodrummaster', this.addImage, this);

В этой строке this.load.on регистрирует функцию this.addImage как обработчик для указанного события. Третий параметр (this) задаёт контекст, в котором будет вызвана функция-обработчик (в данном случае — текущая сцена).

Обработчик события и его аргументы

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

addImage (key, file) {
    this.add.image(400, 300, key);
}

Обработчик получает два аргумента: 1. key (string): Ключ загруженного ресурса. В нашем случае это будет 'taikodrummaster'. 2. file (Phaser.Loader.File): Объект файла, содержащий более детальную информацию о загруженном ресурсе (URL, данные и т.д.). В простейшем случае, как здесь, достаточно ключа.

Внутри функции мы используем ключ для создания и отображения изображения на сцене с помощью this.add.image(400, 300, key). Это поместит картинку в центр экрана (координаты X=400, Y=300 при размере холста 800x600).

Почему это полезно на практике?

Использование именованных событий filecomplete — это паттерн для оптимизации восприятия и логики игры.

- **Прогрессивное отображение**: Вы можете показать основной фон или интерфейс моментально, создавая у игрока ощущение быстрой загрузки, пока в фоне подгружаются остальные ресурсы (например, персонажи или эффекты). - **Зависимая загрузка**: Некоторые ресурсы могут зависеть от других. Например, вы можете дождаться загрузки JSON-файла с конфигурацией атласа (filecomplete-json-atlasData), и только затем начать загрузку самого изображения атласа, указав в его конфиге полученные данные. - **Инициализация объектов**: Можно сразу создать и настроить игровой объект, связанный с загруженным ресурсом, не откладывая это до общего события complete.

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

Событие filecomplete с ключом — это точный инструмент для управления потоком загрузки в Phaser. Оно позволяет реагировать на готовность каждого ресурса индивидуально, что открывает возможности для создания более динамичного и отзывчивого процесса загрузки, а также для реализации сложных цепочек зависимостей между ассетами. **Идеи для экспериментов:** 1. Загрузите фон и игровую музыку, запустив их воспроизведение по отдельным событиям filecomplete, чтобы создать атмосферу ещё до появления всех спрайтов. 2. Создайте цепочку: дождитесь загрузки JSON с данными анимации (filecomplete-json-animData), затем в его обработчике загрузите соответствующий спрайтшит и настройте анимацию с помощью полученных данных. 3. Реализуйте кастомный прогресс-бар, который обновляет отдельные сегменты по событиям загрузки ключевых ресурсов, а не просто показывает общий процент.