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

В этой статье разберем, как эффективно работать со спрайтовыми листами (spritesheet) в Phaser 3. Вы научитесь загружать набор кадров анимации и превращать его в плавную циклическую анимацию прямо в игре. Этот подход — основа для создания взрывов, эффектов, оживления персонажей и других динамичных элементов, позволяя оптимизировать ресурсы и управлять анимациями через централизованную систему 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.spritesheet({
            key: 'explosion',
            url: 'assets/sprites/explosion.png',
            frameConfig: { frameWidth: 64, frameHeight: 64, endFrame: 23 }
        });
    }

    create ()
    {
        const config = {
            key: 'explodeAnimation',
            frames: this.anims.generateFrameNumbers('explosion', { start: 0, end: 23, first: 23 }),
            frameRate: 20,
            repeat: -1
        };

        this.anims.create(config);

        this.add.sprite(400, 300, 'explosion').play('explodeAnimation');
    }
}

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

const game = new Phaser.Game(config);

Настройка базового URL и загрузка spritesheet

На этапе preload мы подготавливаем все необходимые ресурсы. Сначала задаем базовый URL для загрузчиков, что удобно, если ваши ассеты хранятся в одном месте. Затем загружаем spritesheet, используя объектный синтаксис.

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

Этот метод указывает корневую папку для всех последующих загрузок, избавляя от необходимости писать полные пути.

this.load.spritesheet({
    key: 'explosion',
    url: 'assets/sprites/explosion.png',
    frameConfig: { frameWidth: 64, frameHeight: 64, endFrame: 23 }
});

Здесь key — это уникальное имя, по которому мы будем обращаться к листу. url — путь к изображению относительно базового URL. В frameConfig задаются размеры одного кадра (frameWidth, frameHeight) и общее количество кадров (endFrame). Phaser автоматически разрежет изображение на сетку из кадров.

Создание анимации из загруженных кадров

После загрузки ресурсов в методе create мы создаем анимацию. Сначала генерируем массив кадров из нашего spritesheet, а затем регистрируем анимацию в менеджере анимаций сцены.

const config = {
    key: 'explodeAnimation',
    frames: this.anims.generateFrameNumbers('explosion', { start: 0, end: 23, first: 23 }),
    frameRate: 20,
    repeat: -1
};

key — уникальное имя анимации. frames создаются с помощью this.anims.generateFrameNumbers. Первый аргумент — ключ spritesheet ('explosion'), второй — объект с параметрами: start и end определяют диапазон кадров, first задает кадр, который будет показан до старта анимации (здесь это последний кадр). frameRate — скорость проигрывания в кадрах в секунду. repeat: -1 означает бесконечное повторение.

this.anims.create(config);

Метод this.anims.create регистрирует конфигурацию анимации в глобальном менеджере анимаций игры. После этого анимацию можно использовать для любого спрайта.

Создание спрайта и запуск анимации

Теперь создадим визуальный объект — спрайт — и назначим ему созданную анимацию.

this.add.sprite(400, 300, 'explosion').play('explodeAnimation');

this.add.sprite создает новый спрайт в координатах (400, 300) с текстурой 'explosion' (первый кадр из spritesheet). Затем методом play мы запускаем на этом спрайте анимацию с ключом 'explodeAnimation'. Спрайт начнет циклически проигрывать кадры взрыва с заданной скоростью.

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

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

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

const game = new Phaser.Game(config);

type определяет рендерер (WebGL или Canvas). width и height задают размеры игрового холста. parent — это ID HTML-элемента, в который будет встроен canvas. scene указывает класс сцены, которая будет запущена сразу после инициализации игры. Создание экземпляра Phaser.Game запускает весь жизненный цикл.

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

Вы освоили базовый, но мощный пайплайн работы с анимациями в Phaser: загрузка spritesheet, создание анимации и ее применение к спрайту. Для экспериментов попробуйте изменить параметры frameRate и repeat, создайте несколько анимаций из одного spritesheet или используйте this.anims.generateFrameNames для работы с атласами, где у кадров есть имена. Также можно управлять анимацией через методы stop, pause и слушать события её завершения.