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

Метод `this.load.image()` в Phaser чаще всего используют, передавая два строковых аргумента: ключ и 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.image({
            key: 'taikodrummaster',
            url: 'assets/pics/taikodrummaster.jpg'
        });
    }

    create ()
    {
        this.add.image(400, 300, 'taikodrummaster');
    }
}

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

const game = new Phaser.Game(config);

Классический vs. объектный синтаксис

Чаще всего изображение загружают, передавая два отдельных аргумента: ключ (идентификатор для последующего использования) и путь к файлу.

// Классический способ
this.load.image('logo', 'assets/images/logo.png');

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

// Способ через объект конфигурации
this.load.image({
    key: 'logo',
    url: 'assets/images/logo.png'
});

Оба вызова делают одно и то же: добавляют файл в очередь загрузки. Но второй вариант структурирует данные, делая их явными.

Разбор примера из исходника

Рассмотрим предоставленный пример. В методе preload() сцены происходит настройка и загрузка.

preload ()
{
    this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
    this.load.image({
        key: 'taikodrummaster',
        url: 'assets/pics/taikodrummaster.jpg'
    });
}

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

Затем вызывается this.load.image(). Обратите внимание, что в него передается не два аргумента, а один — объект со свойствами key и url. Phaser "распаковывает" этот объект и использует значения свойств как параметры для загрузки. Ключ 'taikodrummaster' будет использоваться для доступа к загруженному изображению в коде, например, в методе create().

create ()
{
    this.add.image(400, 300, 'taikodrummaster');
}

Здесь изображение создается на сцене по ранее зарегистрированному ключу. Координаты (400, 300) — это центр изображения на холсте размером 800x600.

Преимущества объектного подхода

Зачем же использовать объект, если можно обойтись двумя строками? Есть несколько практических причин.

**1. Читаемость и самодокументируемость кода.** Свойства объекта key и url явно указывают на свое назначение. Это особенно полезно для новичков или при ревью кода.

**2. Масштабируемость.** API Phaser для загрузки через объект поддерживает больше свойств, чем key и url. Например, для изображений со спрайтшитом можно добавить frameConfig, а для нормальных карт (normalMap) — соответствующее свойство. Когда вы используете объект, добавление нового параметра не ломает сигнатуру метода.

// Пример с дополнительными параметрами (если бы они были нужны в этом случае)
this.load.image({
    key: 'robot',
    url: 'assets/sprites/robot.png',
    // normalMap: 'assets/sprites/robot_n.png' // Пример возможного расширения
});

**3. Согласованность API.** Многие другие методы загрузки в Phaser (например, this.load.atlas) также используют объектный синтаксис. Использование одного стиля во всем проекте делает код более единообразным и предсказуемым.

Практическое применение и стиль

Выбор между синтаксисами — это вопрос стиля и требований проекта.

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

this.load.image('player', 'sprites/player.png');
this.load.image('bullet', 'sprites/bullet.png');

Переходите на объектный синтаксис, когда: * Ваш код должен быть максимально понятным. * Вы загружаете ресурсы с дополнительными параметрами. * Вы хотите держать конфигурацию ресурса в отдельном объекте или файле, что удобно для управления большим количеством ассетов.

const assetsToLoad = {
    images: [
        { key: 'background', url: 'bg/forest.jpg' },
        { key: 'uiButton', url: 'ui/button.png' }
    ]
};

// В preload()
assetsToLoad.images.forEach(imgConfig => this.load.image(imgConfig));

Такой подход отлично масштабируется для больших игр.

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

Загрузка изображений через объект конфигурации — это мощный и элегантный паттерн в Phaser, который выходит за рамки простого синтаксического сахара. Он повышает читаемость кода, готовит его к легкому добавлению новых параметров и поддерживает единый стиль с другими методами загрузки. **Идеи для экспериментов:** 1. Создайте отдельный модуль или JSON-файл, где в виде массива объектов описаны все ресурсы игры, и организуйте их цикличную загрузку в preload(). 2. Изучите документацию Phaser, чтобы узнать, какие еще свойства (помимо key и url) можно передать в объект конфигурации для this.load.image() (например, для работы с normalMap). 3. Попробуйте применить объектный синтаксис для загрузки других типов ресурсов, таких как this.load.atlas() или this.load.audioSprite(), чтобы почувствовать согласованность API.