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

Когда игра разрастается, управлять десятками изображений, звуков и данных по отдельности становится неудобно. Phaser предлагает мощный инструмент — загрузку через JSON-пакеты (packs). Это позволяет декларативно описать все ресурсы в одном файле, централизовать их конфигурацию и легко менять пути или настройки. В этой статье мы разберем, как настроить базовый URL, загрузить пакет и корректно использовать ассеты из него в сцене.

Версия 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.pack('pack1', 'assets/loader-tests/pack1.json');
    }

    create ()
    {
        this.add.image(400, 300, 'taikodrummaster');
        this.add.image(900, 300, 'TEST2.donuts');
        this.add.image(400, 500, 'sukasuka-chtholly');
        this.add.image(180, 300, 'TEST2.ayu');
    }
}

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

const game = new Phaser.Game(config);

Что такое загрузчик и пакеты в Phaser

Загрузчик (this.load) в Phaser отвечает за предварительную загрузку всех внешних ресурсов: изображений, аудио, атласов, данных. Метод .pack() позволяет загрузить специальный JSON-файл, который описывает целую группу таких ресурсов. Это похоже на манифест или инвентарь, где перечислено, что нужно загрузить и под какими ключами это будет доступно в кэше. Такой подход улучшает структуру проекта и отделяет конфигурацию данных от логики загрузки.

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

Настройка базового пути и загрузка пакета

Перед загрузкой любого файла важно указать, откуда его брать. Метод setBaseURL устанавливает корневую часть пути для всех последующих загрузок в этой сцене. Это избавляет от необходимости прописывать полные URL для каждого ресурса.

Затем мы вызываем load.pack, передавая два аргумента: ключ пакета (произвольная строка для идентификации) и путь к JSON-файлу относительно базового URL.

this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
this.load.pack('pack1', 'assets/loader-tests/pack1.json');

После выполнения этих строк в preload загрузчик автоматически запросит указанный JSON, проанализирует его и начнет загружать все ресурсы, описанные внутри. Загрузка происходит асинхронно, и сцена перейдет к методу create только когда все ресурсы из пакета будут готовы.

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

Все ассеты, описанные в пакете, после успешной загрузки помещаются в глобальный кэш. Для их использования нужно знать их ключи (прописанные в JSON-файле). В примере используются ключи 'taikodrummaster', 'TEST2.donuts', 'sukasuka-chtholly' и 'TEST2.ayu'.

Метод this.add.image создает игровой объект — изображение. Первые два аргумента — это координаты X и Y на экране, третий аргумент — ключ текстуры в кэше.

this.add.image(400, 300, 'taikodrummaster');
this.add.image(900, 300, 'TEST2.donuts');
this.add.image(400, 500, 'sukasuka-chtholly');
this.add.image(180, 300, 'TEST2.ayu');

Обратите внимание, что ключи могут содержать точки (например, 'TEST2.donuts'). Это допустимо и часто используется для организации пространства имен, например, чтобы группировать ассеты по темам или наборам. Phaser корректно находит такие текстуры в кэше.

Структура конфигурационного JSON-пакета

Хотя в примере не показано содержимое pack1.json, важно понимать его типичную структуру. Это массив объектов, где каждый объект описывает один ресурс или группу.

Пример структуры пакета:

[
    {
        "type": "image",
        "key": "taikodrummaster",
        "url": "assets/taikodrummaster.png"
    },
    {
        "type": "atlas",
        "key": "TEST2",
        "textureURL": "assets/TEST2.png",
        "atlasURL": "assets/TEST2.json"
    }
]

В этом примере первый элемент загружает обычное изображение. Второй элемент загружает текстуру и JSON-атлас (набор спрайтов) под общим ключом 'TEST2'. Именно поэтому в коде сцены мы можем обращаться к отдельным кадрам атласа через точку: 'TEST2.donuts' и 'TEST2.ayu'. Тип (type) может быть разным: image, atlas, audio, json, spritesheet и другие.

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

Использование JSON-пакетов — это профессиональный подход к управлению ресурсами в Phaser. Он делает код чище, а процесс добавления новых ассетов — более контролируемым. Для экспериментов попробуйте: создать свой JSON-пакет с локальными изображениями, организовать вложенную структуру ключей (например, 'environment.trees.oak'), или динамически подгружать разные пакеты в зависимости от уровня игры. Это откроет путь к созданию хорошо структурированных и масштабируемых проектов.