Phaser.js: всё об играх и разработке

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

При создании сцены в Phaser есть возможность указать критически важные ресурсы, которые должны быть загружены ещё до вызова стандартного метода `preload`. Это особенно полезно для загрузки конфигурационных JSON-файлов, шрифтов или минимального набора ассетов, необходимых для работы самого прелоадера. Такой подход позволяет сделать процесс загрузки более структурированным и избежать ситуаций, когда прелоадеру не хватает его собственных изображений.

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

Живой запуск

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

Исходный код

//  Files specified in the Scene config files payload
//  will be loaded in *before* the Scene is started,
//  meaning they're available before even the Scene.preload function (if set) is called

//  This is perfect for loading in small JSON config files for example,
//  or a tiny amount of preloader assets that the preloader itself needs to use.
class Example extends Phaser.Scene
{
    constructor ()
    {
        super({
            pack: {
                files: [
                    { type: 'image', key: 'sonic', url: 'assets/sprites/sonic_havok_sanity.png' },
                    { type: 'atlas', key: 'megaset', textureURL: 'assets/atlas/megaset-0.png', atlasURL: 'assets/atlas/megaset-0.json'}
                ]
            }
        });
    }

    preload ()
    {
        this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
        //  You can still preload other assets too
        this.load.image('face', 'assets/pics/bw-face.png');
    }

    create ()
    {
        this.add.image(400, 300, 'face');
        this.add.image(400, 300, 'sonic');

        const atlasTexture = this.textures.get('megaset');

        const frames = atlasTexture.getFrameNames();

        for (let i = 0; i < frames.length; i++)
        {
            const x = Phaser.Math.Between(0, 800);
            const y = Phaser.Math.Between(0, 600);

            this.add.image(x, y, 'megaset', frames[i]);
        }
    }
}


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

const game = new Phaser.Game(gameConfig);

Что такое payload в конфиге сцены?

При создании класса сцены в конструктор можно передать объект конфигурации. Одно из его свойств — pack. Внутри pack.files описывается массив файлов, которые движок начнёт загружать в момент инстанцирования сцены, то есть очень рано.

Эти файлы становятся доступны в кэше раньше, чем запустится метод preload() вашей сцены. Это ключевое отличие от стандартного потока загрузки.

Как объявить payload-файлы

Файлы указываются прямо в конструкторе класса сцены. Каждый элемент массива — объект с полями, определяющими тип, ключ и путь к ресурсу.

constructor ()
{
    super({
        pack: {
            files: [
                { type: 'image', key: 'sonic', url: 'assets/sprites/sonic.png' },
                { type: 'atlas', key: 'megaset', textureURL: 'assets/atlas/megaset-0.png', atlasURL: 'assets/atlas/megaset-0.json'}
            ]
        }
    });
}

В примере мы объявляем одно изображение (type: 'image') и один атлас (type: 'atlas'). Для атласа, как обычно, нужны два URL: для текстуры (изображения) и для данных (JSON-файла).

Сочетание с обычной загрузкой в preload

Метод preload() сцены выполняется уже после того, как payload-файлы загружены. В нём вы можете, как и всегда, устанавливать базовый URL и подгружать остальные ресурсы проекта. Payload-ресурсы к этому моменту уже готовы к использованию.

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

Использование загруженных ресурсов в create

В методе create() все ресурсы — и из payload, и из preload — доступны одинаково. Вы можете обращаться к ним по их ключам через стандартные методы, например, this.add.image. Для работы с атласом можно получить текстуру через this.textures.get() и перебрать его кадры.

create ()
{
    // Использование изображения, загруженного в payload
    this.add.image(400, 300, 'sonic');

    // Использование изображения, загруженного в preload
    this.add.image(400, 300, 'face');

    // Работа с атласом из payload
    const atlasTexture = this.textures.get('megaset');
    const frames = atlasTexture.getFrameNames();

    for (let i = 0; i < frames.length; i++)
    {
        const x = Phaser.Math.Between(0, 800);
        const y = Phaser.Math.Between(0, 600);
        this.add.image(x, y, 'megaset', frames[i]);
    }
}

Код в цикле случайным образом расставляет на сцене все спрайты из атласа megaset, демонстрируя, что анимационные данные из payload-файла корректно загрузились и распарсились.

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

Использование files payload в конфигурации сцены — это мощный инструмент для управления порядком загрузки. Он идеально подходит для загрузки критичных для старта сцены ресурсов, таких как конфиги, шрифты или ассеты для экрана загрузки. Попробуйте использовать этот подход для загрузки JSON-файла с настройками игры или небольшого набора UI-иконок, которые должны отобразиться мгновенно.