# Audio Engine — музыка, звуковые эффекты и эмбиент

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

Это общий мод-движок, которым пользуются меню и игры. Сам по себе Audio Engine вы обычно не открываете и не настраиваете: игра снабжает его аудиофайлами и просит их проиграть.

![Три канала воспроизведения: плейлисты сцены питают Музыку, звуковые эффекты действий — Звуки, фоновый цикл сцены — Окружение. У каждого канала своя громкость и переключатель.](assets/audio-channels.png)

## Что вы слышите

- **Музыка:** треки поставляет плейлист сцены. Плеер выбирает следующий трек, когда кончается текущий, и старается не ставить предыдущий, если есть из чего выбрать. Список из одного трека повторяет его.
- **Звуки:** короткие эффекты вроде щелчков интерфейса или боевых действий. Эффекты из разных звуковых категорий могут звучать одновременно; новый эффект той же категории сменяет предыдущий.
- **Эмбиент:** фоновый звук места, например атмосфера бара из Town Pack. Одновременно играет один фоновый поток и повторяется, пока его не остановят или не заменят.

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

## Как настроить звук

Откройте **Настройки → Звук** в меню. Три строки — **Звуки**, **Музыка** и **Окружение**. У каждой свой переключатель и свой ползунок громкости. Изменения сохраняются на ходу.

![Вкладка «Звук» в настройках: строки «Звуки», «Музыка» и «Окружение», у каждой переключатель вкл/выкл и ползунок громкости. Здесь музыка убавлена до 1%, а звуки и окружение стоят на 100%.](assets/sound-settings.png)

Например, убавьте **Музыку**, чтобы лучше слышать реплики и звуковые эффекты интерфейса, не трогая **Звуки**. Выключите **Окружение**, если хотите слушать только саундтрек без фонового цикла.

Сама панель настроек — от мода Menu; Audio Engine применяет эти предпочтения к воспроизведению и не добавляет ещё одно окно звуковых настроек.

## Где используется

- Общий фронтенд загружает Audio Engine для главного меню и настроек — даже когда игра не запущена.
- Music Pack поставляет тему меню и общие плейлисты исследования и боя; их проигрывает Audio Engine.
- В шаблоне новеллы сцена бара запрашивает `bar/bar_ambient` — его даёт Town Pack.
- Сюжет и боевые системы по ходу игры запрашивают эффекты или меняют активный музыкальный контекст.

**Audio Engine и Music Pack делают разное.** Audio Engine отвечает за воспроизведение, Music Pack — за конкретный саундтрек и плейлисты. Автор может взять Audio Engine и с другим звуковым содержимым.

## Авторам игр: добавить саундтрек

Добавьте `audio_base>=1` к уже существующему списку `depends` в манифесте контентного мода. Установите мод и включите его в коллекцию нужной игры: установленный контентный мод сам по себе не попадает во все игры.

```jsonc
// Добавьте к уже существующему списку зависимостей в манифесте:
"depends": ["audio_base>=1"]
```

Музыку кладите в `music/`, а звуковые эффекты и фоновые циклы — в `sounds/`. Для новых примеров используйте Ogg Vorbis (`.ogg`) — именно в этом формате идут поставляемые саундтрек и эмбиент бара.

```filestree
my_audio_content/
├── manifest.json
├── music/
│   ├── evening_theme.ogg
│   └── playlists/
│       └── my_scene.json
└── sounds/
    └── my_room/
        └── ambience.ogg
```

Пример `music/playlists/my_scene.json`:

```json
{
  "Scene": "my_scene",
  "Musics": [
    {
      "MusicType": "Ambient",
      "MusicNames": ["evening_theme"]
    }
  ]
}
```

`Scene` должен совпадать с логическим именем сцены. Имена треков указываются относительно `music/`, без расширения. Сохраняйте написание, регистр и пробелы в точности как в имени ресурса.

Здесь `MusicType: "Ambient"` означает исследовательскую **музыку**. Он не отправляет трек на отдельный канал эмбиента.

## Авторам игр: дать сцене фоновый цикл

Задайте `defaultAmbient` в описании сцены — путь к звуковому ресурсу относительно `sounds/`, без расширения:

```json
{
  "name": "my_scene",
  "defaultAmbient": "my_room/ambience"
}
```

Этот фрагмент показывает звуковые поля; остальные нужные сцене поля сохраните. Сцена с пустым `defaultAmbient` останавливает фоновый цикл предыдущей сцены.

Настоящий пример — сцена `my_novel_bar` из шаблона новеллы: она использует `defaultAmbient: "bar/bar_ambient"` со звуком, который поставляет Town Pack. Чтобы задействовать этот ресурс в своём моде, тоже нужна зависимость от его владельца, `town_pack`.

## Смена сцен, бои и переопределения

- Если у сцены нет пригодного плейлиста, Audio Engine ищет общий плейлист `default`. Музыка появится, только если под рукой есть подходящее звуковое содержимое.
- Когда у сцены есть свой плейлист, он не дополняется недостающими типами музыки из `default`. Включите в него тип, который нужен музыкальному контексту сцены.
- При смене сцены текущий трек может продолжить играть, если он есть и в новом плейлисте, а тип музыки не изменился.
- Входя в бой, движок может запомнить исследовательский трек и его позицию; возвращение к исследованию пытается их восстановить. Это поведение живого проигрывания, а не гарантия, что загрузка сохранения вернёт точную музыкальную секунду.
- Для одной сцены и одного типа музыки мод, загруженный позже, заменяет список треков более раннего. Списки не складываются. Ресурсы с одинаковым относительным именем тоже может переопределить поздний мод.

Для боевого музыкального контекста используйте блок **Combat**. Произвольное имя блока не создаёт ни нового контекста, ни нового ползунка в настройках.

## Если что-то молчит

1. Проверьте нужный переключатель и громкость в **Настройки → Звук**. Музыка, звуки и эмбиент независимы.
2. Проверьте, что для выбранной игры загружены Audio Engine и нужные контентные моды. В Audio Engine нет треков Music Pack и цикла бара Town Pack.
3. Для музыки проверьте имя сцены, нужный блок `Ambient` или `Combat` и каждое имя трека. Запись в плейлисте не создаёт и не скачивает аудиофайл.
4. Для эмбиента проверьте `defaultAmbient` и ресурс в `sounds/`. Если прошлый цикл остановился, проверьте, не пустое ли поле в новой сцене.
5. Проверьте моды, загруженные позже: они могут заменить блок плейлиста или звуковой ресурс. Загляните в лог игры на предмет отсутствующих файлов и ошибок разбора плейлистов.

В руководстве описан поддерживаемый путь Ogg Vorbis. У движка есть и загрузка WAV, но текущий загрузчик не читает метаданные WAV-контейнера; не считайте, что любой экспортированный WAV поведёт себя правильно. Сомневаетесь — конвертируйте новый контент в Ogg Vorbis. MP3 текущая аудиофабрика не поддерживает.