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

Загрузка множества отдельных аудиофайлов для каждого звука в игре может замедлить загрузку и усложнить управление. Аудио-спрайты решают эту проблему, упаковывая все звуковые эффекты и музыку в один файл с JSON-манифестом. Это ускоряет загрузку, упрощает организацию и позволяет точечно проигрывать нужные фрагменты. В этой статье мы разберем пример загрузки и воспроизведения аудио-спрайта в Phaser, объясним, как работает API, и покажем, как это использовать для фоновой музыки, звуков интерфейса и эффектов.

Версия 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.setPath('assets/audio/kyobi/');

        this.load.audioSprite('kyobi', 'kyobi.json', [
            'kyobi.ogg',
            'kyobi.mp3',
            'kyobi.m4a'
        ]);
    }

    create ()
    {
        const music = this.sound.addAudioSprite('kyobi');

        music.play('title');

        // music.play('gameOver');
        // music.play('nextLevel');

        // text.setText('Playing Dafunk - Hardcore Power (We Believe In Goa - Remix)');
    }
}

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

const game = new Phaser.Game(config);

Что такое аудио-спрайт и зачем он нужен

Аудио-спрайт — это один большой аудиофайл, содержащий все звуки проекта, и сопровождающий его JSON-файл. JSON описывает метаданные: названия звуковых фрагментов, их временные отметки начала и конца внутри основного файла.

Этот подход схож с графическими спрайтшитами. Преимущества: - **Одна HTTP-запрос** вместо десятков для загрузки всех звуков. - **Удобное управление** — все звуки находятся в одном объекте. - **Точный контроль** над воспроизведением любого фрагмента.

Phaser предоставляет встроенные методы для работы с этим форматом через Loader и Sound Manager.

Настройка пути и загрузка файлов в preload()

Первым делом в методе preload() сцены необходимо настроить базовый URL и путь к аудио-ресурсам с помощью методов setBaseURL и setPath. Это позволит не указывать полный путь для каждого файла.

Затем используется ключевой метод this.load.audioSprite(). Он принимает уникальный ключ для идентификации спрайта в кэше, путь к JSON-манифесту и массив с аудиофайлами в разных форматах для поддержки всех браузеров.

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

this.load.audioSprite('kyobi', 'kyobi.json', [
    'kyobi.ogg',
    'kyobi.mp3',
    'kyobi.m4a'
]);

Создание и воспроизведение звука в create()

После успешной загрузки в методе create() мы создаем объект аудио-спрайта. Для этого используется this.sound.addAudioSprite(), куда передается ключ, указанный при загрузке.

Полученный объект music — это экземпляр AudioSprite. Чтобы проиграть конкретный фрагмент, вызывается его метод .play() с именем звука (спрайта) в качестве аргумента. Имя берется из JSON-файла, например, 'title', 'gameOver' или 'nextLevel'.

const music = this.sound.addAudioSprite('kyobi');
music.play('title');

Вы можете раскомментировать другие строки, чтобы проигрывать разные звуки по событию в игре, например, при завершении уровня.

Структура JSON-манифеста для аудио-спрайта

Ключ к работе — правильно сформированный JSON-файл. Phaser ожидает от него конкретную структуру, которая обычно генерируется инструментами вроде аудио-спрайт-генераторов.

Основные поля: - resources: массив имен аудиофайлов. - spritemap: объект, где ключи — это имена звуков (например, 'title'), а значения — объекты с полями start (начало в секундах) и end (конец в секундах).

Пример фрагмента kyobi.json:

{
  "resources": ["kyobi.ogg", "kyobi.mp3"],
  "spritemap": {
    "title": { "start": 0, "end": 7.1 },
    "gameOver": { "start": 8, "end": 10.5 }
  }
}

Phaser использует эти метки, чтобы вырезать и воспроизвести именно нужный отрезок из большого аудиофайла.

Практические сценарии использования в играх

Аудио-спрайты особенно эффективны в определенных ситуациях: 1. **Фоновая музыка с переходами**: В одном файле можно хранить основную тему, напряженную часть для босса и победоносный джингл. Переключение между ними происходит мгновенно. 2. **Голосовые реплики персонажа**: Все реплики одного актера упаковываются в один файл. Это удобно для систем диалогов. 3. **Набор звуков интерфейса**: Звуки наведения, клика, открытия меню — все в одном месте.

Чтобы проиграть звук по событию (например, клику), просто вызовите play с нужным ключом в обработчике события.

this.input.on('pointerdown', () => {
    music.play('clickSound');
});

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

Аудио-спрайты в Phaser — это мощный инструмент для оптимизации и организации звукового сопровождения игры. Они сокращают количество сетевых запросов и упрощают код, позволяя управлять десятками звуков как единым целым. Для экспериментов попробуйте: 1. Создать свой аудио-спрайт из набора коротких звуков с помощью онлайн-генераторов. 2. Реализовать систему, где громкость фоновой музыки плавно снижается при проигрывании звука получения урона. 3. Использовать метод stop на объекте AudioSprite для немедленного прерывания любого проигрываемого фрагмента.