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

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

Версия Phaser: код и демо в этой статье рассчитаны на Phaser 3.90.0.

Живой запуск

Ниже встроен рабочий билд примера. Оригинальный источник: GitHub.

Исходный код


class Example extends Phaser.Scene
{
    constructor ()
    {
        super();
    }

    preload ()
    {
        this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
        this.load.atlas('zombie', 'assets/tests/zombie-no-pivot.png', 'assets/tests/zombie-no-pivot.json');
    }

    create ()
    {
        //  Here we just pass the texture atlas key to `create` and it will extract all frames
        //  from within it, numerically sorting them for the animation.
        this.anims.create({
            key: 'walk',
            frames: 'zombie',
            frameRate: 12,
            repeat: -1
        });

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

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

const game = new Phaser.Game(config);

Загрузка текстурного атласа

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

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

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

Магический метод create для анимации

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

this.anims.create({
    key: 'walk',
    frames: 'zombie',
    frameRate: 12,
    repeat: -1
});

Метод this.anims.create() регистрирует новую анимацию в менеджере анимаций игры. Ключевые параметры: - key: уникальное имя анимации для последующего обращения. - frames: если передать строку с ключом атласа, Phaser автоматически извлечет все кадры из этого атласа, отсортирует их в числовом порядке (по имени файла или индексу в JSON) и использует для анимации. - frameRate: скорость воспроизведения в кадрах в секунду. - repeat: значение -1 задает бесконечное повторение анимации.

Этот подход идеален для спрайт-листов, где кадры идут последовательно (например, zombie_0, zombie_1, zombie_2).

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

После регистрации анимации ее можно применить к любому спрайту. Создадим спрайт в центре экрана и запустим на нем анимацию 'walk'.

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

Метод this.add.sprite() создает новый спрайт с координатами (400, 300) и автоматически добавляет его на сцену. По умолчанию спрайт использует первую текстуру из атласа, но это не важно, так как анимация сразу же переопределит отображаемый кадр. Цепочный вызов .play('walk') запускает анимацию с ключом 'walk', которую мы создали ранее. Спрайт начнет циклически проигрывать кадры атласа с заданной скоростью.

Конфигурация игры и важный флаг

Для корректной работы с пиксельной графикой, как в нашем примере с зомби, необходимо правильно настроить игру. Обратите внимание на параметр pixelArt в конфигурации.

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

const game = new Phaser.Game(config);

Установка pixelArt: true включает специальную фильтрацию текстуры, которая предотвращает размытие при масштабировании. Это критически важно для игр в ретро-стиле, где каждый пиксель должен оставаться четким. Без этого флага анимация может выглядеть размытой, особенно если разрешение спрайтов не кратно разрешению экрана.

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

Использование строкового ключа атласа в свойстве frames — это мощный и лаконичный способ быстрого создания анимаций в Phaser 3. Он избавляет от рутины перечисления кадров и отлично подходит для прототипирования или работы с последовательными спрайт-листами. Для экспериментов попробуйте изменить frameRate на более высокое или низкое значение, чтобы увидеть, как меняется восприятие движения. Также можно создать несколько анимаций (например, 'idle' и 'attack') из одного атласа, используя разные ключи, и переключать их по условиям в игре.