Add mod documentation in seven languages

docs/ru.md

@@ -0,0 +1,110 @@
+# 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 текущая аудиофабрика не поддерживает.