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

Работа с графикой — ключевая часть разработки игр. Когда ресурсов много, их организация становится критичной. Мульти-атлас (Multi-Atlas) — это формат, который позволяет объединить несколько отдельных атласов текстур под одним ключом загрузки в Phaser. Это упрощает управление ассетами, особенно в больших проектах, где спрайты логически сгруппированы в разные файлы (например, по уровням или персонажам), но вы хотите обращаться к ним через единую систему. В этой статье мы разберем пример загрузки и отображения кадров из разных файлов атласа, используя всего один вызов `load.multiatlas`.

Версия 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.path = 'assets/atlas/';

        this.load.multiatlas('megaset', 'tp3-multi-atlas.json');
    }

    create ()
    {

        //  This frame is in the 1st atlas file (set0/data0)
        this.add.image(0, 0, 'megaset', 'snake').setOrigin(0);

        //  This frame is in the 2nd atlas file (set1/data1)
        this.add.image(0, 100, 'megaset', 'nanoha-taiken-pink').setOrigin(0);

        //  This frame is in the 3rd atlas file (set2/data2)
        // this.add.image(0, 0, 'megaset', 'hello').setOrigin(0); // trimmed
        this.add.image(300, 130, 'megaset', 'bunny').setOrigin(0); // un-trimmed

        //  This frame is in the 4th atlas file (set3/data3)
        this.add.image(64, 300, 'megaset', 'contra3').setOrigin(0);

    }
}

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

const game = new Phaser.Game(config);

Что такое мульти-атлас и зачем он нужен

Обычный атлас текстур — это один JSON-файл с данными и соответствующее ему PNG-изображение. Мульти-атлас — это JSON-файл, который выступает в роли манифеста и ссылается на несколько пар таких файлов (JSON + PNG). Phaser загружает их все, но предоставляет вам доступ через единый текстурый ключ.

Основные преимущества: * **Логическая группировка:** Вы можете разделить ассеты по папкам или наборам (например, ui.json, enemies.json, environment.json), но использовать их как единую библиотеку. * **Удобство загрузки:** Не нужно вызывать load.atlas для каждого набора. Один вызов load.multiatlas загружает всю группу. * **Совместимость:** Формат часто генерируется популярными инструментами для создания спрайт-лист, такими как TexturePacker (с опцией 'Multi-atlas').

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

В методе preload() происходит подготовка путей и загрузка мульти-атласа. Обратите внимание, что сначала задается общий базовый URL, а затем уточняющий путь для конкретных ассетов. Это гибкий подход для структурирования ресурсов.

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

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

this.load.multiatlas('megaset', 'tp3-multi-atlas.json');

После этой строки Phaser загрузит манифест tp3-multi-atlas.json, прочитает из него список пар файлов (например, set0.json + set0.png, set1.json + set1.png и т.д.) и загрузит их все, связав с ключом 'megaset'.

Создание изображений из разных источников

В методе create() мы создаем спрайты, используя загруженный мульти-атлас. Синтаксис создания изображения стандартный для Phaser: this.add.image(x, y, textureKey, frameKey). Магия в том, что кадры (frameKey) могут физически находиться в разных файлах PNG, но мы об этом даже не задумываемся, используя один текстурый ключ 'megaset'.

//  Кадр 'snake' находится в 1-м файле атласа (set0/data0)
this.add.image(0, 0, 'megaset', 'snake').setOrigin(0);

//  Кадр 'nanoha-taiken-pink' находится во 2-м файле атласа (set1/data1)
this.add.image(0, 100, 'megaset', 'nanoha-taiken-pink').setOrigin(0);

//  Кадр 'bunny' находится в 3-м файле атласа (set2/data2)
this.add.image(300, 130, 'megaset', 'bunny').setOrigin(0);

//  Кадр 'contra3' находится в 4-м файле атласа (set3/data3)
this.add.image(64, 300, 'megaset', 'contra3').setOrigin(0);

Вызов .setOrigin(0) устанавливает точку начала координат спрайта в его левый верхний угол, что удобно для точного позиционирования на экране. Важно: Phaser автоматически находит, в каком из загруженных атласов находится запрошенный кадр, и отрисовывает его.

Структура файла мульти-атласа (манифеста)

Чтобы понять, как это работает, взглянем на примерную структуру JSON-манифеста tp3-multi-atlas.json. Это не код из примера, но знание формата помогает при подготовке ассетов.

on
{
  "textures": [
    { "image": "set0.png", "json": "set0.json" },
    { "image": "set1.png", "json": "set1.json" },
    { "image": "set2.png", "json": "set2.json" },
    { "image": "set3.png", "json": "set3.json" }
  ]
}

Каждый объект в массиве textures описывает один классический атлас. Phaser загружает все указанные изображения и данные, объединяя их в единую текстуру в памяти под ключом 'megaset'. Ваши инструменты экспорта (например, TexturePacker) должны поддерживать генерацию именно такого формата файла.

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

Использование мульти-атласов в Phaser — это мощный способ организовать графические ресурсы в больших играх, сохранив при этом простоту обращения к ним. Вы получаете преимущество модульности (разные наборы спрайтов в разных файлах) и удобство единой точки доступа. **Идеи для экспериментов:** 1. Попробуйте сгенерировать мульти-атлас из своих ассетов в TexturePacker, выбрав формат экспорта 'Phaser Multi Atlas'. 2. Создайте сцену, где спрайты из разных частей мульти-атласа (например, фон, персонаж, элементы UI) анимируются независимо друг от друга. 3. Исследуйте, как работает замена или динамическая подгрузка новых мульти-атласов для реализации системы загрузки уровней 'на лету'.