О чем этот пример
При разработке игр часто требуется загружать множество ресурсов: изображения, звуки, данные. Phaser 3 предоставляет мощную систему загрузки, включая поддержку файловых пакетов (asset packs). Использование пакетов позволяет организовать загрузку ресурсов структурированно, управлять зависимостями и упростить процесс предзагрузки. В этой статье мы разберем, как создать и загрузить пакет с аудиофайлом и спрайтом, а затем воспроизвести музыку в игре, используя Web Audio API. Это особенно полезно для проектов с большим количеством медиафайлов, где важна четкая организация и производительность.
Версия Phaser: код и демо в этой статье рассчитаны на Phaser 3.90.0.
Живой запуск
Ниже встроен рабочий билд примера. Оригинальный источник: GitHub.
Исходный код
class Example extends Phaser.Scene
{
FilePackObject = {
pack: {
files: [
{
type: 'audio',
key: 'theme',
url: [
'assets/audio/oedipus_wizball_highscore.ogg',
'assets/audio/oedipus_wizball_highscore.mp3'
]
},
{
type: 'image',
key: 'wizball',
url: 'assets/sprites/wizball.png'
}
]
},
meta: {
generated: '1401380327373',
app: 'Phaser 3 Asset Packer',
url: 'https://phaser.io',
version: '1.0',
copyright: 'Photon Storm Ltd. 2021'
}
};
preload ()
{
this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
this.load.pack('pack1', this.FilePackObject);
}
create ()
{
this.add.image(400, 300, 'wizball').setScale(4);
const music = this.sound.add('theme');
music.play();
}
}
const config = {
type: Phaser.AUTO,
parent: 'phaser-example',
width: 800,
height: 600,
pixelArt: true,
scene: Example
};
const game = new Phaser.Game(config);
Что такое файловый пакет (Asset Pack) в Phaser?
Файловый пакет — это JSON-объект, который описывает набор ресурсов для загрузки в игре. Он может включать аудио, изображения, атласы, данные и другие типы файлов. Пакеты упрощают управление ассетами, особенно когда у вас десятки или сотни файлов. Вместо вызова this.load.image или this.load.audio для каждого ресурса отдельно, вы определяете их все в одном месте.
В примере пакет содержит два файла: аудиофайл с музыкой (в форматах OGG и MP3 для кросс-браузерной совместимости) и изображение спрайта. Phaser автоматически выберет подходящий аудиоформат в зависимости от браузера. Пакет также включает метаданные, такие как информация о генерации и авторские права, но они необязательны для работы.
Структура класса и определение пакета
В коде примера класс Example расширяет Phaser.Scene. Внутри класса определяется объект FilePackObject, который представляет собой файловый пакет. Обратите внимание: пакет задается как свойство класса, что удобно для хранения конфигурации в одном месте.
FilePackObject = {
pack: {
files: [
{
type: 'audio',
key: 'theme',
url: [
'assets/audio/oedipus_wizball_highscore.ogg',
'assets/audio/oedipus_wizball_highscore.mp3'
]
},
{
type: 'image',
key: 'wizball',
url: 'assets/sprites/wizball.png'
}
]
},
meta: {
generated: '1401380327373',
app: 'Phaser 3 Asset Packer',
url: 'https://phaser.io',
version: '1.0',
copyright: 'Photon Storm Ltd. 2021'
}
};Ключевые поля в пакете:
- type: тип ресурса (например, 'audio' или 'image').
- key: уникальный идентификатор, по которому ресурс будет доступен в коде.
- url: путь к файлу или массив путей для альтернативных форматов (как у аудио).
Метаданные (meta) не влияют на загрузку и используются для информации.
Загрузка пакета в методе preload
В методе preload сцены происходит загрузка ресурсов. Сначала устанавливается базовый URL с помощью this.load.setBaseURL, чтобы не указывать полные пути в каждом url пакета. Затем пакет загружается через this.load.pack.
preload ()
{
this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
this.load.pack('pack1', this.FilePackObject);
}Метод `this.load.pack` принимает два аргумента:
1. Ключ пакета (`'pack1'`) — произвольная строка для идентификации пакета (может быть полезно, если пакетов несколько).
2. Объект пакета (`this.FilePackObject`) — структура, определенная ранее.Phaser автоматически обработает все файлы из пакета и загрузит их. Для аудио он выберет первый поддерживаемый формат из массива url.
Создание сцены и воспроизведение аудио
После загрузки ресурсов в методе create мы можем их использовать. Сначала добавляется изображение спрайта 'wizball' на сцену с помощью this.add.image. Затем создается аудиообъект через this.sound.add и воспроизводится.
create ()
{
this.add.image(400, 300, 'wizball').setScale(4);
const music = this.sound.add('theme');
music.play();
}Здесь:
- `this.add.image(400, 300, 'wizball')` — создает спрайт в центре экрана (координаты 400x300) с ключом `'wizball'` из пакета. Метод `setScale(4)` увеличивает спрайт в 4 раза.
- `this.sound.add('theme')` — создает экземпляр аудио, используя ключ `'theme'` из пакета. Это не начинает воспроизведение.
- `music.play()` — запускает воспроизведение аудио. По умолчанию используется Web Audio API, если браузер его поддерживает.Конфигурация игры и запуск
Конфигурационный объект config определяет основные параметры игры, такие как тип рендерера, размеры холста и сцену. Затем создается экземпляр игры Phaser.Game.
const config = {
type: Phaser.AUTO,
parent: 'phaser-example',
width: 800,
height: 600,
pixelArt: true,
scene: Example
};
const game = new Phaser.Game(config);Параметры конфигурации:
- type: Phaser.AUTO — автоматический выбор рендерера (WebGL или Canvas).
- parent: 'phaser-example' — ID HTML-элемента, в который будет встроен холст игры.
- width и height — размеры игрового поля в пикселях.
- pixelArt: true — включает специальную фильтрацию для пиксель-арт графики, чтобы сохранить четкость спрайтов.
- scene: Example — основная сцена игры, использует наш класс.
После создания объекта game Phaser автоматически запускает жизненный цикл сцены, включая preload и create.
Что попробовать дальше
Использование файловых пакетов в Phaser 3 — это эффективный способ организации ресурсов в играх. Он позволяет загружать аудио, изображения и другие файлы из единой структуры, улучшая читаемость кода и управление ассетами. В рассмотренном примере мы загрузили музыку и спрайт, а затем воспроизвели аудио через Web Audio API. Для экспериментов попробуйте:
1. Добавить больше ресурсов в пакет, например, атласы спрайтов или JSON-данные.
2. Управлять воспроизведением аудио: добавить паузу, регулировку громкости или цикличность через параметры music.play({ loop: true }).
3. Использовать несколько пакетов для разделения ресурсов по уровням игры.
4. Динамически загружать пакеты в зависимости от действий игрока, используя this.load.pack в других методах сцены.