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

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

Версия 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.path = 'assets/pics/';

        // this.load.image([
        //     { key: 'sukasuka-chtholly' },
        //     { key: 'taikodrummaster', extension: 'jpg' }
        // ]);

        // this.load.image('taikodrummaster', 'assets/pics/taikodrummaster.jpg');

        // this.load.image({ key: 'taikodrummaster', file: 'assets/pics/taikodrummaster.jpg' });

        // this.load.image({ key: 'taikodrummaster', file: 'assets/pics/taikodrummaster.jpg' });

        // this.load.image({ key: 'sukasuka-chtholly' });

        //  Default extension is png, so specify a new one:
        // this.load.image({ key: 'taikodrummaster', extension: 'jpg' });
    }

    create ()
    {
        this.add.image(400, 300, 'taikodrummaster');
        this.add.image(400, 500, 'sukasuka-chtholly');
    }
}

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

const game = new Phaser.Game(config);

Сцена preload и базовая загрузка

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

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

this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');

После установки базового пути можно загружать изображения. Самый распространенный способ — использовать метод this.load.image(), передав ему ключ (уникальное имя для ссылки в коде) и путь к файлу.

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

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

Как только изображения загружены в preload(), они становятся доступны в текстурах игры. Для их отображения на сцене используется метод this.add.image() в методе create().

Метод принимает координаты X, Y и ключ изображения, который был задан при загрузке. Именно по этому ключу Phaser находит нужную текстуру в своем кэше.

this.add.image(400, 300, 'taikodrummaster');
this.add.image(400, 500, 'sukasuka-chtholly');

Важно помнить, что точка привязки (anchor) у изображения по умолчанию находится в его центре. Поэтому в данном примере координаты (400, 300) указывают на размещение центра первой картинки в указанной точке сцены.

Альтернативные способы загрузки (разбираем закомментированный код)

Пример содержит несколько закомментированных альтернатив, которые демонстрируют гибкость API загрузчика Phaser.

**1. Загрузка массива объектов:** Вместо нескольких вызовов можно передать массив объектов с описанием каждого ресурса. Это удобно для структурирования кода.

// this.load.path = 'assets/pics/';
// this.load.image([
//     { key: 'sukasuka-chtholly' },
//     { key: 'taikodrummaster', extension: 'jpg' }
// ]);

Обратите внимание на строку this.load.path. Она устанавливает общий путь для всех последующих загрузок в рамках текущего вызова. Также в объекте для taikodrummaster явно указано расширение .jpg, так как по умолчанию Loader ожидает .png.

**2. Загрузка через объект конфигурации:** Метод image() может принимать и один объект конфигурации. Это полезно для явного указания полного пути или переопределения расширения файла.

// this.load.image({ key: 'taikodrummaster', file: 'assets/pics/taikodrummaster.jpg' });
// this.load.image({ key: 'sukasuka-chtholly' }); // Будет искать .png по пути из setBaseURL
// this.load.image({ key: 'taikodrummaster', extension: 'jpg' }); // Будет искать .jpg по пути из setBaseURL

Последняя строка особенно показательна: если для ресурса taikodrummaster уже был задан ключ ранее (например, в массиве), а теперь нужно указать другое расширение, можно вызвать метод снова, передав только ключ и новое расширение. Loader обновит данные для существующего ключа.

Конфигурация игры и запуск

Весь процесс инициируется созданием объекта Phaser.Game. В его конфигурации обязательно указывается сцена, которая будет использоваться. В данном случае это наш класс Example.

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

const game = new Phaser.Game(config);

Ключевые параметры: - type: Определяет рендерер (WebGL или Canvas). Phaser.AUTO позволяет движку выбрать лучший из доступных. - width / height: Размер игрового поля (canvas). - parent: ID HTML-элемента, в который будет встроен canvas. Если элемента с таким ID нет, canvas будет добавлен в тело документа. - scene: Класс главной сцены или массив классов сцен для автоматического переключения.

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

Phaser предоставляет несколько эргономичных способов загрузки изображений, от простых вызовов до конфигурационных объектов. Используйте setBaseURL или path для чистоты кода, а загрузку массива — для удобства управления большим количеством ресурсов. Для экспериментов попробуйте

  1. Загрузить спрайтшит вместо отдельного изображения, используя this.load.spritesheet
  2. Динамически менять путь path для загрузки ресурсов из разных папок
  3. Использовать событие 'filecomplete' загрузчика, чтобы выполнять код сразу после загрузки конкретного файла