Генерация фреймов: generateFrameNumbers, generateFrameNames

В Phaser фреймы спрайтовых атласов и спрайт-листов являются основой для анимаций. Для удобного создания последовательностей анимаций используется генерация фреймов с помощью методов generateFrameNumbers и generateFrameNames. Они позволяют быстро получить массив фреймов, который затем применяется при создании анимаций через anims.create.

generateFrameNumbers

Метод generateFrameNumbers применяется для спрайт-листов (spritesheet), когда все кадры пронумерованы целыми числами. Основной синтаксис:

this.anims.generateFrameNumbers(key, config);

Параметры:

  • key — строка, идентификатор спрайт-листа, зарегистрированного через this.load.spritesheet.

  • config — объект с настройками генерации фреймов:

    • start (число) — индекс первого фрейма.
    • end (число) — индекс последнего фрейма.
    • first (число, опционально) — индекс фрейма, который будет использоваться первым в анимации.
    • frames (массив, альтернативно) — конкретный список фреймов, если требуется нестандартная последовательность.

Пример использования:

this.load.spritesheet('player', 'assets/player.png', { frameWidth: 32, frameHeight: 48 });

const walkFrames = this.anims.generateFrameNumbers('player', { start: 0, end: 5 });

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

В этом примере создается анимация ходьбы, используя фреймы с 0 по 5 из спрайт-листа player. Метод возвращает массив объектов фреймов в формате:

[{ key: 'player', frame: 0 }, { key: 'player', frame: 1 }, ...]

Этот массив полностью совместим с конфигурацией анимаций Phaser.

generateFrameNames

Метод generateFrameNames предназначен для атласов (texture atlas) и позволяет генерировать фреймы по имени, если фреймы имеют последовательную нумерацию в именах. Часто применяется при работе с .json атласами, где каждый кадр имеет уникальное имя, например: explosion_01, explosion_02, …, explosion_10.

Синтаксис:

this.anims.generateFrameNames(key, config);

Параметры:

  • key — строка, идентификатор загруженного атласа (this.load.atlas).

  • config — объект конфигурации:

    • start — номер первого фрейма.
    • end — номер последнего фрейма.
    • prefix — строка, добавляемая перед номером фрейма.
    • suffix — строка, добавляемая после номера фрейма (например, .png).
    • zeroPad — количество цифр в номере, с ведущими нулями.
    • frames — массив конкретных фреймов, если требуется нестандартная последовательность.

Пример использования:

this.load.atlas('explosion', 'assets/explosion.png', 'assets/explosion.json');

const explosionFrames = this.anims.generateFrameNames('explosion', {
    start: 1,
    end: 10,
    prefix: 'explosion_',
    zeroPad: 2
});

this.anims.create({
    key: 'explode',
    frames: explosionFrames,
    frameRate: 15,
    hideOnComplete: true
});

В этом примере будут сгенерированы фреймы: explosion_01, explosion_02, …, explosion_10. Метод возвращает массив объектов вида:

[{ key: 'explosion', frame: 'explosion_01' }, ...]

Отличия generateFrameNumbers и generateFrameNames

Характеристика generateFrameNumbers generateFrameNames
Используемый ресурс Spritesheet Texture Atlas
Ссылка на фреймы По индексу По имени
Поддержка нумерации start–end индексы start–end с префиксом, суффиксом, zeroPad
Результат Массив объектов { key, frame } Массив объектов { key, frame } с именами

Настройки нумерации и кастомные последовательности

Оба метода поддерживают генерацию нестандартных последовательностей:

const customFrames = this.anims.generateFrameNumbers('player', { frames: [0, 2, 4, 3, 1] });

или для имен:

const selectedFrames = this.anims.generateFrameNames('explosion', {
    frames: ['explosion_01', 'explosion_03', 'explosion_07']
});

Это полезно для анимаций, где кадры идут в произвольном порядке или требуется «скачок» между фреймами.

Использование с anims.create

Сгенерированные массивы фреймов можно использовать напрямую при создании анимаций:

this.anims.create({
    key: 'jump',
    frames: this.anims.generateFrameNumbers('player', { start: 6, end: 8 }),
    frameRate: 12,
    repeat: 0
});

Для атласов:

this.anims.create({
    key: 'coin_spin',
    frames: this.anims.generateFrameNames('coins', {
        start: 1,
        end: 6,
        prefix: 'coin_',
        zeroPad: 2
    }),
    frameRate: 10,
    repeat: -1
});

Практические рекомендации

  • Spritesheet всегда удобнее использовать с generateFrameNumbers.
  • Texture Atlas рекомендуется использовать с generateFrameNames для гибкой работы с именами кадров.
  • ZeroPad полезен при нумерации файлов с ведущими нулями, чтобы правильно сопоставить имена кадров.
  • Для кастомных анимаций удобнее указывать массив frames, а не только диапазон.

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

Оглавление