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

В разработке игр оптимизация ресурсов — ключевой фактор производительности. Использование текстурных атласов вместо множества отдельных файлов изображений уменьшает количество HTTP-запросов и улучшает производительность рендеринга. В этой статье мы разберем, как загрузить атлас в 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.atlas('atlas', 'assets/atlas/megaset-2.png', 'assets/atlas/megaset-2.json');
    }

    create ()
    {
        const i = this.add.image(400, 300, 'atlas', 'hello');

        console.log(i.width, i.height);

        console.log(i.frame);
    }
}

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

const game = new Phaser.Game(config);

Загрузка атласа: метод `preload`

Перед созданием любых игровых объектов необходимо загрузить ресурсы. В Phaser для этого используется метод preload сцены. Ключевой метод для работы с атласами — this.load.atlas. Он принимает три аргумента: ключ (уникальное имя ресурса в кеше), путь к изображению-атласу и путь к JSON-файлу с данными о расположении кадров.

this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
this.load.atlas('atlas', 'assets/atlas/megaset-2.png', 'assets/atlas/megaset-2.json');

Первая строка устанавливает базовый URL для всех загружаемых ресурсов, что удобно, если они хранятся на одном домене. Вторая — непосредственно загружает атлас. После завершения загрузки вы можете обращаться к нему по ключу 'atlas'.

Создание изображения из конкретного кадра атласа

После загрузки ресурсов в методе create мы можем создавать игровые объекты. Чтобы добавить на сцену не всё изображение атласа, а только его часть (например, конкретный спрайт), используется метод this.add.image. Важно передать ему не только ключ атласа, но и имя конкретного фрейма из JSON-данных атласа.

const i = this.add.image(400, 300, 'atlas', 'hello');

Здесь мы создаем объект Image с центром в точке (400, 300). Четвертый аргумент 'hello' — это имя кадра (frame name), которое должно быть определено в загруженном JSON-файле атласа. Если его не указать, Phaser попытается использовать всё изображение атласа целиком, что, скорее всего, приведет к неожиданному результату.

Анализ свойств созданного изображения

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

console.log(i.width, i.height);
console.log(i.frame);

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

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

Как и любой пример Phaser, наш код завершается созданием конфигурационного объекта и экземпляра игры. Конфигурация определяет основные параметры, такие как тип рендерера, размер холста и стартовую сцену.

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

const game = new Phaser.Game(config);

type: Phaser.AUTO позволяет движку автоматически выбрать между WebGL и Canvas рендерингом. parent — это ID HTML-элемента, в который будет встроен canvas игры. Класс Example, который мы описали ранее, передается как стартовая сцена.

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

Работа с отдельными кадрами из текстурного атласа — базовая, но мощная техника в Phaser. Она лежит в основе создания анимаций, интерфейсов и оптимизированных игровых миров. Для экспериментов попробуйте

  1. Загрузить другой атлас и извлечь из него различные кадры
  2. Использовать свойство i.frame.sourceSize для получения исходных размеров спрайта до обрезки
  3. Создать несколько изображений из одного и того же кадра атласа, чтобы понять работу с кешем текстур