Compare commits
6
Commits
v1.0.0
..
918cc1f2b9
| Author | SHA1 | Date | |
|---|---|---|---|
 cthangover
|
918cc1f2b9 | ||
|
cthangover
|
7b0a57fea7 | ||
|
cthangover
|
09b6d437e5 | ||
 iisaev
|
610b6cff76 | ||
|
cthangoverandClaude Opus 5.5
|
83c0039d52 | ||
|
cthangover
|
11a386a16b |
No files matched your search
@@ -12,6 +12,7 @@ obj/
|
||||
gen/
|
||||
obj/
|
||||
bin/
|
||||
art_sources/
|
||||
|
||||
*.tres~
|
||||
*.tscn~
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 90 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
+110
@@ -0,0 +1,110 @@
|
||||
# Audio Engine — music, sound effects and ambience
|
||||
|
||||
Audio Engine makes the game sound alive: music follows the current scene, effects respond to actions, and an ambient loop can set the mood of a location. These layers have separate volume controls, so you can lower the soundtrack while keeping interface clicks and environmental sounds audible.
|
||||
|
||||
It is a shared engine mod used by the menu and games. You normally do not open or operate Audio Engine itself: the game supplies audio files and asks it to play them.
|
||||
|
||||
|
||||
|
||||
## What you hear
|
||||
|
||||
- **Music:** a scene's playlist supplies tracks. The player chooses another track when one ends, avoiding the immediately previous track when another choice exists. A one-track list repeats that track.
|
||||
- **Sounds:** short effects such as interface clicks or battle actions. Effects in different sound categories can overlap; a new effect in the same category replaces the previous one.
|
||||
- **Ambience:** a location's background sound, such as the bar atmosphere from Town Pack. One ambient stream plays at a time and repeats until it is stopped or replaced.
|
||||
|
||||
Music and ambience are different even when both play in the background. A location can have an exploration soundtrack on the Music channel and a separate room or outdoor loop on Ambience.
|
||||
|
||||
## Adjust the sound
|
||||
|
||||
Open **Settings → Sound** in the menu. The three rows are **Sounds**, **Music** and **Ambience**. Each has an enabled toggle and its own volume slider. Changes are saved as you make them.
|
||||
|
||||
|
||||
|
||||
For example, lower **Music** to hear dialogue-related or interface effects more clearly without lowering **Sounds**. Turn off **Ambience** if you want the soundtrack without the environmental loop.
|
||||
|
||||
The settings panel is supplied by the Menu mod; Audio Engine applies these preferences to playback. It does not add another sound-settings window.
|
||||
|
||||
## Where it is used
|
||||
|
||||
- The shared frontend loads Audio Engine for the main menu and settings, including when no game is running.
|
||||
- Music Pack supplies the menu theme and shared exploration/combat playlists; Audio Engine plays them.
|
||||
- In the novel template, the bar scene requests `bar/bar_ambient`, supplied by Town Pack.
|
||||
- Story and battle systems request effects or change the active music context as the game progresses.
|
||||
|
||||
**Audio Engine and Music Pack serve different purposes.** Audio Engine provides playback. Music Pack provides a particular soundtrack and playlists. An author can use Audio Engine with other audio content instead.
|
||||
|
||||
## For game authors: add a soundtrack
|
||||
|
||||
Add `audio_base>=1` to your content mod's existing `depends` list. Install and include the mod in the intended game's collection as well: an installed content mod is not automatically part of every game.
|
||||
|
||||
```jsonc
|
||||
// Add to the manifest's existing dependency list:
|
||||
"depends": ["audio_base>=1"]
|
||||
```
|
||||
|
||||
Place music under `music/` and sound effects or ambient loops under `sounds/`. Use Ogg Vorbis (`.ogg`) for new examples; it is the format used by the supplied soundtrack and bar ambience.
|
||||
|
||||
```filestree
|
||||
my_audio_content/
|
||||
├── manifest.json
|
||||
├── music/
|
||||
│ ├── evening_theme.ogg
|
||||
│ └── playlists/
|
||||
│ └── my_scene.json
|
||||
└── sounds/
|
||||
└── my_room/
|
||||
└── ambience.ogg
|
||||
```
|
||||
|
||||
An example `music/playlists/my_scene.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"Scene": "my_scene",
|
||||
"Musics": [
|
||||
{
|
||||
"MusicType": "Ambient",
|
||||
"MusicNames": ["evening_theme"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`Scene` must match the scene's logical name. Track names are relative to `music/`, without the file extension. Preserve the spelling, case and spaces of the actual resource name.
|
||||
|
||||
Here, `MusicType: "Ambient"` means exploration **music**. It does not send the track to the separate Ambience channel.
|
||||
|
||||
## For game authors: give a scene an ambient loop
|
||||
|
||||
Set `defaultAmbient` in your scene definition to a sound resource relative to `sounds/`, without its extension:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my_scene",
|
||||
"defaultAmbient": "my_room/ambience"
|
||||
}
|
||||
```
|
||||
|
||||
This fragment illustrates the sound-related fields; keep the other fields your scene needs. A scene with an empty `defaultAmbient` stops the previous scene's ambient loop.
|
||||
|
||||
A real example is the novel template's `my_novel_bar` scene: it uses `defaultAmbient: "bar/bar_ambient"` with the audio supplied by Town Pack. Reusing that asset in your own mod also requires a dependency on its owner, `town_pack`.
|
||||
|
||||
## Scene changes, battles and overrides
|
||||
|
||||
- If a scene has no usable playlist, Audio Engine looks for the shared `default` playlist. This only produces music when matching audio content is available.
|
||||
- When a scene-specific playlist exists, it is not filled out with missing music types from `default`. Include the bucket needed by that scene's music context.
|
||||
- On a scene change, the current track can continue if it is still in the new playlist and the music type is unchanged.
|
||||
- Entering combat can save the exploration track and its position; returning to exploration attempts to restore them. This is live playback behaviour, not a guarantee that loading a saved game restores the exact musical timestamp.
|
||||
- For the same scene and music type, a later-loaded mod replaces the earlier track list. The lists are not appended together. Resource files with the same relative name can also be overridden by a later-loaded mod.
|
||||
|
||||
Use the **Combat** bucket for the combat music context. Adding an arbitrary bucket name does not create a new context or a new settings slider.
|
||||
|
||||
## If something is silent
|
||||
|
||||
1. Check the corresponding enabled toggle and volume in **Settings → Sound**. Music, Sounds and Ambience are independent.
|
||||
2. Check that Audio Engine and the required content mods are loaded for the selected game. Audio Engine does not contain Music Pack's tracks or Town Pack's bar loop.
|
||||
3. For music, check the scene name, the required `Ambient` or `Combat` bucket, and every track name. A playlist reference does not create or download an audio file.
|
||||
4. For ambience, check `defaultAmbient` and the resource under `sounds/`. Check for an empty field in the new scene if a previous loop stops.
|
||||
5. Check later mods that may replace a playlist bucket or an audio resource. Check the game log for missing audio files or playlist parsing errors.
|
||||
|
||||
The guide uses the supported Ogg Vorbis path. The engine also has a WAV loading path, but the current loader does not inspect WAV container metadata; do not assume every exported WAV will behave correctly. Convert new content to Ogg Vorbis when in doubt. MP3 is not supported by the current audio factory.
|
||||
+110
@@ -0,0 +1,110 @@
|
||||
# Audio Engine — música, efectos de sonido y ambiente
|
||||
|
||||
Audio Engine da vida sonora al juego: la música sigue la escena actual, los efectos responden a las acciones y un bucle de ambiente pone el tono del lugar. Estas capas tienen controles de volumen separados, así que puedes bajar la banda sonora sin apagar los clics de la interfaz ni los sonidos del entorno.
|
||||
|
||||
Es un mod de motor compartido que usan el menú y los juegos. Normalmente no abres ni manejas Audio Engine directamente: el juego le aporta archivos de audio y le pide reproducirlos.
|
||||
|
||||
|
||||
|
||||
## Lo que oyes
|
||||
|
||||
- **Música:** una lista de la escena aporta las pistas. El reproductor elige otra pista cuando la actual termina y evita repetir la anterior si hay otra opción. Una lista de una sola pista la repite.
|
||||
- **Sonidos:** efectos cortos como los clics de la interfaz o las acciones de combate. Los efectos de categorías distintas pueden sonar a la vez; un efecto nuevo de la misma categoría sustituye al anterior.
|
||||
- **Ambiente:** el sonido de fondo de un lugar, como la atmósfera del bar de Town Pack. Solo suena un flujo de ambiente cada vez, y se repite hasta que se detiene o se sustituye.
|
||||
|
||||
Música y ambiente son cosas distintas aunque ambos suenen de fondo. Un lugar puede tener una banda sonora de exploración en el canal de Música y un bucle aparte de interior o exterior en Ambiente.
|
||||
|
||||
## Ajusta el sonido
|
||||
|
||||
Abre **Ajustes → Sonido** en el menú. Las tres filas son **Sonidos**, **Música** y **Ambiente**. Cada una tiene su interruptor y su deslizador de volumen. Los cambios se guardan al hacerlos.
|
||||
|
||||
|
||||
|
||||
Por ejemplo, baja **Música** para oír mejor los efectos de los diálogos o de la interfaz sin tocar **Sonidos**. Apaga **Ambiente** si quieres la banda sonora sin el bucle del entorno.
|
||||
|
||||
El panel de ajustes lo aporta el mod Menu; Audio Engine aplica esas preferencias a la reproducción. No añade otra ventana de ajustes de sonido.
|
||||
|
||||
## Dónde se usa
|
||||
|
||||
- El frontend compartido carga Audio Engine para el menú principal y los ajustes, incluso sin ningún juego en marcha.
|
||||
- Music Pack aporta el tema del menú y las listas compartidas de exploración y combate; Audio Engine las reproduce.
|
||||
- En la plantilla de novela, la escena del bar pide `bar/bar_ambient`, aportado por Town Pack.
|
||||
- Los sistemas de historia y de combate piden efectos o cambian el contexto musical según avanza el juego.
|
||||
|
||||
**Audio Engine y Music Pack sirven para cosas distintas.** Audio Engine da la reproducción; Music Pack, una banda sonora concreta y sus listas. Un autor puede usar Audio Engine con otro contenido de audio.
|
||||
|
||||
## Para autores de juegos: añadir una banda sonora
|
||||
|
||||
Añade `audio_base>=1` a la lista `depends` ya existente en el manifiesto de tu mod de contenido. Instala e incluye el mod en la colección del juego correspondiente: un mod de contenido instalado no forma parte automáticamente de todos los juegos.
|
||||
|
||||
```jsonc
|
||||
// Añádelo a la lista de dependencias ya existente del manifiesto:
|
||||
"depends": ["audio_base>=1"]
|
||||
```
|
||||
|
||||
Coloca la música bajo `music/` y los efectos o bucles de ambiente bajo `sounds/`. Para ejemplos nuevos usa Ogg Vorbis (`.ogg`): es el formato de la banda sonora y del ambiente del bar que vienen de serie.
|
||||
|
||||
```filestree
|
||||
my_audio_content/
|
||||
├── manifest.json
|
||||
├── music/
|
||||
│ ├── evening_theme.ogg
|
||||
│ └── playlists/
|
||||
│ └── my_scene.json
|
||||
└── sounds/
|
||||
└── my_room/
|
||||
└── ambience.ogg
|
||||
```
|
||||
|
||||
Un ejemplo de `music/playlists/my_scene.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"Scene": "my_scene",
|
||||
"Musics": [
|
||||
{
|
||||
"MusicType": "Ambient",
|
||||
"MusicNames": ["evening_theme"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`Scene` debe coincidir con el nombre lógico de la escena. Los nombres de pistas son relativos a `music/`, sin la extensión. Respeta la escritura, las mayúsculas y los espacios exactos del nombre del recurso.
|
||||
|
||||
Aquí, `MusicType: "Ambient"` significa **música** de exploración. No envía la pista al canal de Ambiente aparte.
|
||||
|
||||
## Para autores de juegos: dar ambiente a una escena
|
||||
|
||||
Pon `defaultAmbient` en la definición de tu escena con un recurso de sonido relativo a `sounds/`, sin su extensión:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my_scene",
|
||||
"defaultAmbient": "my_room/ambience"
|
||||
}
|
||||
```
|
||||
|
||||
Este fragmento ilustra los campos relacionados con el sonido; conserva los demás campos que tu escena necesite. Una escena con `defaultAmbient` vacío detiene el bucle de ambiente de la escena anterior.
|
||||
|
||||
Un ejemplo real es la escena `my_novel_bar` de la plantilla de novela: usa `defaultAmbient: "bar/bar_ambient"` con el audio aportado por Town Pack. Reutilizar ese recurso en tu propio mod también exige depender de su dueño, `town_pack`.
|
||||
|
||||
## Cambios de escena, combates y sustituciones
|
||||
|
||||
- Si una escena no tiene lista utilizable, Audio Engine busca la lista compartida `default`. Esto solo produce música cuando hay contenido de audio que coincida.
|
||||
- Cuando existe una lista específica de la escena, no se rellena con los tipos de música que falten tomados de `default`. Incluye el bloque que necesite el contexto musical de esa escena.
|
||||
- Al cambiar de escena, la pista actual puede continuar si sigue en la nueva lista y el tipo de música no cambia.
|
||||
- Al entrar en combate se puede guardar la pista de exploración y su posición; al volver a la exploración se intenta restaurarlas. Es un comportamiento de reproducción en vivo, no la garantía de que cargar una partida restablezca el segundo musical exacto.
|
||||
- Para la misma escena y tipo de música, un mod cargado más tarde sustituye la lista anterior. Las listas no se concatenan. Los recursos con el mismo nombre relativo también pueden ser sustituidos por un mod posterior.
|
||||
|
||||
Usa el bloque **Combat** para el contexto musical de combate. Añadir un nombre de bloque arbitrario no crea un contexto nuevo ni un deslizador nuevo en los ajustes.
|
||||
|
||||
## Si algo suena mudo
|
||||
|
||||
1. Revisa el interruptor y el volumen correspondientes en **Ajustes → Sonido**. Música, Sonidos y Ambiente son independientes.
|
||||
2. Comprueba que Audio Engine y los mods de contenido necesarios están cargados para el juego elegido. Audio Engine no contiene las pistas de Music Pack ni el bucle del bar de Town Pack.
|
||||
3. Para la música, revisa el nombre de la escena, el bloque `Ambient` o `Combat` necesario y cada nombre de pista. Una referencia en una lista no crea ni descarga un archivo de audio.
|
||||
4. Para el ambiente, revisa `defaultAmbient` y el recurso bajo `sounds/`. Comprueba si hay un campo vacío en la nueva escena cuando un bucle anterior se detiene.
|
||||
5. Revisa los mods posteriores que puedan sustituir un bloque de una lista o un recurso de audio. Mira el registro del juego por si faltan archivos de audio o hay errores al interpretar listas.
|
||||
|
||||
La guía usa la vía admitida de Ogg Vorbis. El motor también tiene una vía de carga WAV, pero el cargador actual no inspecciona los metadatos del contenedor WAV; no des por hecho que cualquier WAV exportado se comporte bien. Ante la duda, convierte el contenido nuevo a Ogg Vorbis. La fábrica de audio actual no admite MP3.
|
||||
+110
@@ -0,0 +1,110 @@
|
||||
# Audio Engine — 音楽、効果音、環境音
|
||||
|
||||
Audio Engine はゲームに音の生命を吹き込みます。音楽は現在のシーンに付き従い、効果音はアクションに応じ、環境音のループが場所の空気を作ります。これらのレイヤーは音量調整が別々なので、インターフェースのクリックや環境の音を聞こえたまま、サウンドトラックだけを絞れます。
|
||||
|
||||
メニューとゲームが使う共有エンジン MOD です。通常あなたが Audio Engine 自体を開いたり操作したりすることはありません。ゲームがオーディオファイルを提供し、再生を頼む側です。
|
||||
|
||||
|
||||
|
||||
## 聞こえるもの
|
||||
|
||||
- **音楽:** シーンのプレイリストが曲を供給します。曲が終わるとプレイヤーが次を選び、ほかに選択肢があれば直前の曲は避けます。一曲だけのリストはその曲を繰り返します。
|
||||
- **効果音:** インターフェースのクリックや戦闘アクションのような短い効果音です。別々の音カテゴリーの効果音は重ねられます。同じカテゴリーの新しい効果音は前のものを置き換えます。
|
||||
- **環境音:** 場所の背景音。たとえば Town Pack の酒場の雰囲気です。環境音のストリームは一度に一本だけ流れ、止めるか置き換えるまで繰り返します。
|
||||
|
||||
音楽と環境音は、両方とも背景で鳴っていても別物です。場所によっては、音楽チャンネルで探索のサウンドトラックを流しつつ、環境音では別の室内や屋外のループを鳴らせます。
|
||||
|
||||
## 音を調整する
|
||||
|
||||
メニューで **設定 → サウンド** を開きます。三つの行は **効果音**、**音楽**、**環境音**。それぞれにオン/オフのトグルと音量スライダーがあります。変更はその場で保存されます。
|
||||
|
||||
|
||||
|
||||
たとえば **音楽** を絞れば、**効果音** を下げずに会話まわりやインターフェースの効果音を聞き取りやすくなります。サウンドトラックだけにしたいなら **環境音** を切ってください。
|
||||
|
||||
設定パネルは Menu MOD の提供物で、Audio Engine はその設定を再生に反映するだけです。別の音設定ウィンドウを足したりはしません。
|
||||
|
||||
## どこで使われているか
|
||||
|
||||
- 共有フロントエンドは、ゲームが動いていなくても、メインメニューと設定のために Audio Engine を読み込みます。
|
||||
- Music Pack はメニューのテーマと共有の探索・戦闘プレイリストを提供し、Audio Engine がそれを再生します。
|
||||
- ノベルテンプレートでは、酒場のシーンが `bar/bar_ambient` を要求します。提供するのは Town Pack です。
|
||||
- ストーリーと戦闘のシステムは、ゲームの進行に合わせて効果音を要求したり、音楽のコンテキストを切り替えたりします。
|
||||
|
||||
**Audio Engine と Music Pack は役割が違います。** Audio Engine は再生を担い、Music Pack は特定のサウンドトラックとプレイリストを担います。作者は Audio Engine を別のオーディオコンテンツと組み合わせてもかまいません。
|
||||
|
||||
## ゲーム作者向け:サウンドトラックを足す
|
||||
|
||||
コンテンツ MOD の既存の `depends` リストに `audio_base>=1` を加えます。さらに MOD をインストールし、対象ゲームのコレクションに含めてください。インストール済みのコンテンツ MOD がすべてのゲームに自動で入るわけではありません。
|
||||
|
||||
```jsonc
|
||||
// manifest の既存の依存リストに追加:
|
||||
"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 が提供します。その資産を自分の MOD で再利用する場合も、所有者である `town_pack` への依存が必要です。
|
||||
|
||||
## シーンの切り替え、戦闘、上書き
|
||||
|
||||
- シーンに使えるプレイリストがない場合、Audio Engine は共有の `default` プレイリストを探します。曲が出るのは、対応するオーディオコンテンツがあるときだけです。
|
||||
- シーン専用のプレイリストがある場合、足りない音楽タイプを `default` で補うことはしません。そのシーンの音楽コンテキストが必要とするバケットを入れてください。
|
||||
- シーンが切り替わるとき、新しいプレイリストに曲が残っていて音楽タイプが変わらなければ、現在の曲はそのまま続きます。
|
||||
- 戦闘に入るとき、探索の曲とその位置を保存し、探索へ戻るときに復元を試みます。これは再生中の挙動であって、セーブのロードが正確な曲のタイムスタンプを復元する保証ではありません。
|
||||
- 同じシーンと音楽タイプでは、後から読み込まれた MOD が前の曲リストを置き換えます。リストは連結されません。相対名が同じリソースファイルも、後の MOD に上書きされ得ます。
|
||||
|
||||
戦闘の音楽コンテキストには **Combat** バケットを使ってください。任意のバケット名を足しても、新しいコンテキストも設定スライダーも生まれません。
|
||||
|
||||
## 音がしないとき
|
||||
|
||||
1. **設定 → サウンド** で当該のトグルと音量を確認します。音楽・効果音・環境音は互いに独立です。
|
||||
2. 選んだゲームに Audio Engine と必要なコンテンツ MOD が読み込まれているか確認します。Audio Engine は Music Pack の曲も Town Pack の酒場ループも含みません。
|
||||
3. 音楽なら、シーン名、必要な `Ambient` か `Combat` バケット、そして全曲名を確認します。プレイリストの参照はオーディオファイルを作りもダウンロードもしません。
|
||||
4. 環境音なら、`defaultAmbient` と `sounds/` の下のリソースを確認します。前のループが止まったなら、新しいシーンでその欄が空ではないか見てください。
|
||||
5. プレイリストのバケットや音リソースを置き換え得る、後から読み込まれる MOD を確認します。ゲームログに、無い音ファイルやプレイリストの解釈エラーが出ていないかも見てください。
|
||||
|
||||
このガイドは対応済みの Ogg Vorbis の経路を使っています。エンジンには WAV の読み込み経路もありますが、現在のローダーは WAV コンテナーのメタデータを検査しません。書き出した WAV がすべて正しく振る舞うとは考えないでください。迷ったら新しいコンテンツは Ogg Vorbis へ変換を。MP3 は現在のオーディオファクトリーが対応していません。
|
||||
+110
@@ -0,0 +1,110 @@
|
||||
# Audio Engine — 음악, 효과음, 환경음
|
||||
|
||||
Audio Engine은 게임에 소리의 생기를 불어넣습니다. 음악은 현재 장면을 따라가고, 효과음은 행동에 반응하며, 환경음 루프가 장소의 분위기를 깔아 줍니다. 이 층들은 음량 조절이 따로따로라, 인터페이스 클릭과 환경 소리는 들리는 채로 사운드트랙만 줄일 수 있습니다.
|
||||
|
||||
메뉴와 게임이 함께 쓰는 공유 엔진 모드입니다. 보통 Audio Engine 자체를 열거나 다룰 일은 없습니다. 게임이 오디오 파일을 제공하고 재생을 부탁하는 쪽입니다.
|
||||
|
||||
|
||||
|
||||
## 들리는 것들
|
||||
|
||||
- **음악:** 장면의 플레이리스트가 곡을 공급합니다. 한 곡이 끝나면 플레이어가 다음 곡을 고르고, 다른 선택지가 있으면 방금 전 곡은 피합니다. 곡이 하나뿐인 목록은 그 곡을 반복합니다.
|
||||
- **효과음:** 인터페이스 클릭이나 전투 행동 같은 짧은 효과입니다. 서로 다른 소리 범주의 효과는 겹쳐 재생될 수 있습니다. 같은 범주의 새 효과는 이전 것을 대신합니다.
|
||||
- **환경음:** 장소의 배경 소리. 이를테면 Town Pack의 선술집 분위기입니다. 환경음 스트림은 한 번에 하나만 재생되며, 멈추거나 교체될 때까지 반복됩니다.
|
||||
|
||||
음악과 환경음은 둘 다 배경에서 흘러도 다른 것입니다. 한 장소가 음악 채널에서 탐험 사운드트랙을 틀면서 환경음으로는 별개의 실내·실외 루프를 틀 수 있습니다.
|
||||
|
||||
## 소리 조절하기
|
||||
|
||||
메뉴에서 **설정 → 소리**를 엽니다. 세 행은 **효과음**, **음악**, **환경음**입니다. 각 행마다 켜기 토글과 고유의 음량 슬라이더가 있습니다. 변경은 하는 즉시 저장됩니다.
|
||||
|
||||
|
||||
|
||||
예컨대 **음악**을 줄이면 **효과음**을 건드리지 않고도 대화 관련이나 인터페이스 효과를 더 또렷이 들을 수 있습니다. 사운드트랙만 원하면 **환경음**을 끄세요.
|
||||
|
||||
설정 패널은 Menu 모드가 제공하고, Audio Engine은 그 설정을 재생에 적용할 뿐입니다. 소리 설정 창을 하나 더 만들지는 않습니다.
|
||||
|
||||
## 어디에 쓰이나
|
||||
|
||||
- 공유 프런트엔드는 게임이 실행 중이 아니어도 메인 메뉴와 설정을 위해 Audio Engine을 불러옵니다.
|
||||
- Music Pack은 메뉴 테마와 공용 탐험·전투 플레이리스트를 공급하고, Audio Engine이 재생합니다.
|
||||
- 소설 템플릿에서는 선술집 장면이 `bar/bar_ambient`을 요청하며, 이를 Town Pack이 공급합니다.
|
||||
- 이야기와 전투 시스템은 게임이 진행됨에 따라 효과를 요청하거나 음악 컨텍스트를 바꿉니다.
|
||||
|
||||
**Audio Engine과 Music Pack은 역할이 다릅니다.** Audio Engine은 재생을, Music Pack은 특정 사운드트랙과 플레이리스트를 맡습니다. 제작자는 Audio Engine을 다른 오디오 콘텐츠와 써도 됩니다.
|
||||
|
||||
## 게임 제작자를 위해: 사운드트랙 추가하기
|
||||
|
||||
콘텐츠 모드의 기존 `depends` 목록에 `audio_base>=1`을 더하세요. 모드를 설치하고 대상 게임의 컬렉션에 넣는 일도 잊지 마세요. 설치된 콘텐츠 모드가 모든 게임에 저절로 들어가지는 않습니다.
|
||||
|
||||
```jsonc
|
||||
// manifest의 기존 의존성 목록에 추가:
|
||||
"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는 현재 오디오 팩토리가 지원하지 않습니다.
|
||||
+110
@@ -0,0 +1,110 @@
|
||||
# Audio Engine — музыка, звуковые эффекты и эмбиент
|
||||
|
||||
Audio Engine заставляет игру звучать: музыка следует за текущей сценой, эффекты отвечают на действия, а зацикленный эмбиент задаёт настроение месту. У этих слоёв отдельные регуляторы громкости, поэтому саундтрек можно сделать тише, не глуша щелчки интерфейса и звуки окружения.
|
||||
|
||||
Это общий мод-движок, которым пользуются меню и игры. Сам по себе Audio Engine вы обычно не открываете и не настраиваете: игра снабжает его аудиофайлами и просит их проиграть.
|
||||
|
||||
|
||||
|
||||
## Что вы слышите
|
||||
|
||||
- **Музыка:** треки поставляет плейлист сцены. Плеер выбирает следующий трек, когда кончается текущий, и старается не ставить предыдущий, если есть из чего выбрать. Список из одного трека повторяет его.
|
||||
- **Звуки:** короткие эффекты вроде щелчков интерфейса или боевых действий. Эффекты из разных звуковых категорий могут звучать одновременно; новый эффект той же категории сменяет предыдущий.
|
||||
- **Эмбиент:** фоновый звук места, например атмосфера бара из Town Pack. Одновременно играет один фоновый поток и повторяется, пока его не остановят или не заменят.
|
||||
|
||||
Музыка и эмбиент различаются, даже когда оба играют фоном. У локации может быть исследовательский саундтрек на канале музыки и отдельный комнатный или уличный цикл на эмбиенте.
|
||||
|
||||
## Как настроить звук
|
||||
|
||||
Откройте **Настройки → Звук** в меню. Три строки — **Звуки**, **Музыка** и **Окружение**. У каждой свой переключатель и свой ползунок громкости. Изменения сохраняются на ходу.
|
||||
|
||||
|
||||
|
||||
Например, убавьте **Музыку**, чтобы лучше слышать реплики и звуковые эффекты интерфейса, не трогая **Звуки**. Выключите **Окружение**, если хотите слушать только саундтрек без фонового цикла.
|
||||
|
||||
Сама панель настроек — от мода 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 текущая аудиофабрика не поддерживает.
|
||||
+110
@@ -0,0 +1,110 @@
|
||||
# Audio Engine — nhạc, hiệu ứng âm thanh và âm nền
|
||||
|
||||
Audio Engine khiến game có hơi thở âm thanh: nhạc đi theo cảnh hiện tại, hiệu ứng phản hồi hành động, còn một vòng lặp âm nền đặt tông cho địa điểm. Các lớp này có thanh âm lượng riêng, nên bạn có thể hạ nhạc nền mà vẫn nghe rõ tiếng bấm giao diện và âm thanh môi trường.
|
||||
|
||||
Đây là mod engine dùng chung cho menu và các game. Thông thường bạn không mở hay vận hành Audio Engine trực tiếp: game cung cấp tệp âm thanh cho nó và nhờ nó phát.
|
||||
|
||||
|
||||
|
||||
## Bạn nghe được gì
|
||||
|
||||
- **Nhạc:** playlist của cảnh cung cấp các bài hát. Khi một bài kết thúc, trình phát chọn bài khác và tránh lặp lại bài vừa phát nếu còn lựa chọn khác. Danh sách chỉ có một bài thì lặp lại bài đó.
|
||||
- **Hiệu ứng:** những âm ngắn như tiếng bấm giao diện hay hành động chiến đấu. Hiệu ứng thuộc các nhãn âm khác nhau có thể chồng lên nhau; hiệu ứng mới cùng nhãn sẽ thay thế hiệu ứng trước.
|
||||
- **Âm nền:** âm thanh nền của một địa điểm, ví dụ không khí quán rượu từ Town Pack. Cùng một lúc chỉ phát một luồng âm nền và lặp lại cho tới khi bị dừng hay thay thế.
|
||||
|
||||
Nhạc và âm nền là hai thứ khác nhau dù cả hai đều phát nền. Một địa điểm có thể có nhạc khám phá trên kênh Nhạc cùng lúc với một vòng lặp phòng hay ngoài trời riêng trên Âm nền.
|
||||
|
||||
## Chỉnh âm thanh
|
||||
|
||||
Mở **Cài đặt → Âm thanh** trong menu. Ba hàng là **Hiệu ứng âm thanh**, **Nhạc** và **Âm nền**. Mỗi hàng có cờ bật và thanh trượt âm lượng riêng. Thay đổi được lưu ngay khi bạn thực hiện.
|
||||
|
||||
|
||||
|
||||
Ví dụ, hạ **Nhạc** xuống để nghe rõ hiệu ứng gắn với hội thoại hay giao diện mà không đụng vào **Hiệu ứng âm thanh**. Tắt **Âm nền** nếu chỉ muốn nhạc không kèm vòng lặp môi trường.
|
||||
|
||||
Bảng cài đặt do mod Menu cung cấp; Audio Engine áp các tùy chọn đó vào việc phát. Nó không thêm một cửa sổ cài đặt âm thanh nào khác.
|
||||
|
||||
## Được dùng ở đâu
|
||||
|
||||
- Frontend dùng chung nạp Audio Engine cho menu chính và cài đặt, kể cả khi không có game nào đang chạy.
|
||||
- Music Pack cung cấp chủ đề menu và các playlist khám phá/chiến đấu dùng chung; Audio Engine phát chúng.
|
||||
- Trong mẫu tiểu thuyết, cảnh quán rượu yêu cầu `bar/bar_ambient`, do Town Pack cung cấp.
|
||||
- Hệ thống cốt truyện và chiến đấu theo tiến trình game mà yêu cầu hiệu ứng hay đổi ngữ cảnh nhạc đang dùng.
|
||||
|
||||
**Audio Engine và Music Pack có mục đích khác nhau.** Audio Engine lo phần phát; Music Pack lo một soundtrack cụ thể và các playlist. Tác giả hoàn toàn có thể dùng Audio Engine với nội dung âm thanh khác.
|
||||
|
||||
## Cho tác giả game: thêm soundtrack
|
||||
|
||||
Thêm `audio_base>=1` vào danh sách `depends` sẵn có trong manifest của mod nội dung. Đồng thời cài mod và đưa nó vào bộ sưu tập của game định nhắm tới: mod nội dung đã cài không tự động thuộc về mọi game.
|
||||
|
||||
```jsonc
|
||||
// Thêm vào danh sách phụ thuộc sẵn có của manifest:
|
||||
"depends": ["audio_base>=1"]
|
||||
```
|
||||
|
||||
Đặt nhạc dưới `music/`, còn hiệu ứng hay vòng lặp âm nền dưới `sounds/`. Với ví dụ mới hãy dùng Ogg Vorbis (`.ogg`); soundtrack và âm quán rượu kèm sẵn đều ở định dạng này.
|
||||
|
||||
```filestree
|
||||
my_audio_content/
|
||||
├── manifest.json
|
||||
├── music/
|
||||
│ ├── evening_theme.ogg
|
||||
│ └── playlists/
|
||||
│ └── my_scene.json
|
||||
└── sounds/
|
||||
└── my_room/
|
||||
└── ambience.ogg
|
||||
```
|
||||
|
||||
Một ví dụ `music/playlists/my_scene.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"Scene": "my_scene",
|
||||
"Musics": [
|
||||
{
|
||||
"MusicType": "Ambient",
|
||||
"MusicNames": ["evening_theme"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`Scene` phải khớp với tên logic của cảnh. Tên bài hát tính tương đối từ `music/`, không kèm phần mở rộng. Giữ nguyên chính tả, chữ hoa chữ thường và khoảng cách đúng như tên tài nguyên.
|
||||
|
||||
Ở đây `MusicType: "Ambient"` nghĩa là **nhạc** khám phá. Nó không đẩy bài hát sang kênh Âm nền riêng biệt.
|
||||
|
||||
## Cho tác giả game: cho cảnh một vòng lặp âm nền
|
||||
|
||||
Đặt `defaultAmbient` trong định nghĩa cảnh thành một tài nguyên âm thanh tính tương đối từ `sounds/`, không kèm phần mở rộng:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my_scene",
|
||||
"defaultAmbient": "my_room/ambience"
|
||||
}
|
||||
```
|
||||
|
||||
Đoạn này minh họa các trường liên quan tới âm thanh; hãy giữ lại những trường khác mà cảnh của bạn cần. Một cảnh có `defaultAmbient` rỗng sẽ dừng vòng lặp âm nền của cảnh trước.
|
||||
|
||||
Một ví dụ thật là cảnh `my_novel_bar` trong mẫu tiểu thuyết: nó dùng `defaultAmbient: "bar/bar_ambient"` với âm thanh do Town Pack cung cấp. Dùng lại tài nguyên đó trong mod của bạn cũng đòi hỏi phụ thuộc vào chủ nhân của nó, `town_pack`.
|
||||
|
||||
## Đổi cảnh, chiến đấu và ghi đè
|
||||
|
||||
- Nếu cảnh không có playlist dùng được, Audio Engine sẽ tìm playlist dùng chung `default`. Điều này chỉ sinh ra nhạc khi có nội dung âm thanh tương ứng.
|
||||
- Khi cảnh đã có playlist riêng, nó không được lấp đầy các loại nhạc còn thiếu từ `default`. Hãy đưa vào nhãn mà ngữ cảnh nhạc của cảnh đó cần.
|
||||
- Khi đổi cảnh, bài đang phát có thể tiếp tục nếu nó vẫn nằm trong playlist mới và loại nhạc không đổi.
|
||||
- Vào chiến đấu có thể lưu bài khám phá và vị trí phát của nó; khi trở lại khám phá sẽ cố khôi phục chúng. Đây là hành vi phát trực tiếp, không phải cam kết rằng tải bản lưu sẽ trở về đúng thời điểm nhạc.
|
||||
- Với cùng cảnh và loại nhạc, mod nạp sau sẽ thay thế danh sách bài của mod nạp trước. Các danh sách không được ghép lại. Tệp tài nguyên trùng tên tương đối cũng có thể bị mod nạp sau ghi đè.
|
||||
|
||||
Dùng nhãn **Combat** cho ngữ cảnh nhạc chiến đấu. Tự đặt một tên nhãn nào đó không tạo ra ngữ cảnh mới hay thanh trượt cài đặt mới.
|
||||
|
||||
## Nếu im lặng
|
||||
|
||||
1. Kiểm tra cờ bật và âm lượng tương ứng trong **Cài đặt → Âm thanh**. Nhạc, Hiệu ứng và Âm nền độc lập với nhau.
|
||||
2. Kiểm tra rằng Audio Engine và các mod nội dung cần thiết đã được nạp cho game đã chọn. Audio Engine không chứa các bài của Music Pack hay vòng lặp quán rượu của Town Pack.
|
||||
3. Với nhạc, kiểm tra tên cảnh, nhãn `Ambient` hay `Combat` cần dùng, và từng tên bài. Một tham chiếu trong playlist không tạo hay tải tệp âm thanh.
|
||||
4. Với âm nền, kiểm tra `defaultAmbient` và tài nguyên dưới `sounds/`. Nếu vòng lặp trước dừng lại, kiểm tra trường đó trong cảnh mới có rỗng không.
|
||||
5. Kiểm tra các mod nạp sau có thể thay nhãn playlist hay tài nguyên âm thanh. Xem nhật ký game để tìm tệp âm thiếu hay lỗi phân tích playlist.
|
||||
|
||||
Cẩm nang này dùng đường Ogg Vorbis được hỗ trợ. Engine còn có đường nạp WAV, nhưng bộ nạp hiện tại không đọc siêu dữ liệu vùng chứa WAV; đừng cho rằng mọi WAV xuất ra đều chạy đúng. Khi phân vân, hãy chuyển nội dung mới sang Ogg Vorbis. MP3 không được bộ tạo âm thanh hiện tại hỗ trợ.
|
||||
+110
@@ -0,0 +1,110 @@
|
||||
# Audio Engine — 音乐、音效与环境音
|
||||
|
||||
Audio Engine 让游戏有了声音的活力：音乐跟随当前场景，音效响应操作，一段环境音循环则烘托一个地点的氛围。这几层音轨各有独立的音量控制，因此可以把配乐调低，同时保留界面点击声和环境声响。
|
||||
|
||||
它是一个由菜单和游戏共用的引擎模组。通常你不需要直接打开或操作 Audio Engine：游戏向它提供音频文件并请它播放。
|
||||
|
||||
|
||||
|
||||
## 你会听到什么
|
||||
|
||||
- **音乐：** 场景的播放列表提供曲目。当前曲目播完后，播放器会挑选下一首，并在有其他选择时避开刚放过的那首。只有一首曲子的列表会循环它。
|
||||
- **音效：** 界面点击、战斗动作之类的短促效果。不同音效类别可以同时叠放；同一类别里的新音效会取代上一个。
|
||||
- **环境音：** 一个地点的背景声，例如来自 Town Pack 的酒馆氛围。同一时刻只播放一路环境音，并循环直到被停止或替换。
|
||||
|
||||
音乐和环境音是两回事，即使两者都在背景播放。一个地点可以在音乐频道放探索配乐，同时在环境音频道放另一路室内或户外循环。
|
||||
|
||||
## 调节声音
|
||||
|
||||
在菜单打开**设置 → 声音**。三行分别是**音效**、**音乐**和**环境音**。每行都有开关和自己的音量滑块。改动即时保存。
|
||||
|
||||
|
||||
|
||||
例如，把**音乐**调低就能更清楚地听清对话相关或界面的音效，而不用动**音效**。想只要配乐、不要环境循环，就关掉**环境音**。
|
||||
|
||||
设置面板由 Menu 模组提供；Audio Engine 负责把这些偏好应用到播放上，自己不会再加一个声音设置窗口。
|
||||
|
||||
## 用在哪里
|
||||
|
||||
- 共享前端为主菜单和设置加载 Audio Engine，即使没有任何游戏在运行。
|
||||
- Music Pack 提供菜单主题和共享的探索、战斗播放列表；由 Audio Engine 播放。
|
||||
- 在小说模板里，酒馆场景请求 `bar/bar_ambient`，由 Town Pack 提供。
|
||||
- 剧情和战斗系统随游戏进程请求音效或切换当前的音乐上下文。
|
||||
|
||||
**Audio Engine 与 Music Pack 分工不同。** Audio Engine 负责播放，Music Pack 提供特定的配乐和播放列表。作者也完全可以把 Audio Engine 搭配其他音频内容使用。
|
||||
|
||||
## 给游戏作者：添加配乐
|
||||
|
||||
在内容模组已有的 `depends` 列表里加上 `audio_base>=1`。同时安装该模组并把它放进目标游戏的合集：内容模组装好了并不会自动进入每一款游戏。
|
||||
|
||||
```jsonc
|
||||
// 加到 manifest 已有的依赖列表里：
|
||||
"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。
|
||||
@@ -1,2 +1,2 @@
|
||||
mod_audio_base_name = Audio Engine
|
||||
mod_audio_base_desc = Engine audio subsystem: IAudioService implementation (Music/SFX/Ambient buses), the auto-advancing music player and the audio factories (music, sounds, playlists).
|
||||
mod_audio_base_desc = Audio engine: scene music, sound effects and ambience on separate buses with their own volume, and a music player that follows the current scene.
|
||||
@@ -0,0 +1,2 @@
|
||||
mod_audio_base_name = Motor de audio
|
||||
mod_audio_base_desc = Motor de audio: música de escena, efectos de sonido y ambiente en buses separados con su propio volumen, y un reproductor que sigue la escena actual.
|
||||
@@ -0,0 +1,2 @@
|
||||
mod_audio_base_name = オーディオエンジン
|
||||
mod_audio_base_desc = オーディオエンジン:シーン音楽・効果音・環境音をそれぞれ独立した音量のバスで鳴らし、現在のシーンに合わせて曲を進める音楽プレーヤー。
|
||||
@@ -0,0 +1,2 @@
|
||||
mod_audio_base_name = 오디오 엔진
|
||||
mod_audio_base_desc = 오디오 엔진: 장면 음악, 효과음, 환경음이 각자 음량을 가진 별개 버스로 재생되고, 음악 플레이어가 현재 장면을 따릅니다.
|
||||
@@ -1,2 +1,2 @@
|
||||
mod_audio_base_name = Аудиодвижок
|
||||
mod_audio_base_desc = Звуковая подсистема движка: реализация IAudioService (шины Music/SFX/Ambient), музыкальный плеер с автопродвижением и фабрики аудио (музыка, звуки, плейлисты).
|
||||
mod_audio_base_desc = Аудиодвижок: музыка сцены, звуковые эффекты и эмбиент на отдельных шинах со своей громкостью, и музыкальный плеер, который следует за текущей сценой.
|
||||
@@ -0,0 +1,2 @@
|
||||
mod_audio_base_name = Engine âm thanh
|
||||
mod_audio_base_desc = Engine âm thanh: nhạc theo cảnh, hiệu ứng âm thanh và âm nền trên các bus riêng có âm lượng riêng, cùng trình phát nhạc bám theo cảnh hiện tại.
|
||||
@@ -0,0 +1,2 @@
|
||||
mod_audio_base_name = 音频引擎
|
||||
mod_audio_base_desc = 音频引擎：场景音乐、音效和环境音走各自独立、音量分开的总线，音乐播放器跟随当前场景。
|
||||
+1
-1
@@ -3,7 +3,7 @@
|
||||
"name": "Audio Engine",
|
||||
"version": "1.0.0",
|
||||
"author": "ct",
|
||||
"description": "Engine audio subsystem: IAudioService implementation (Music/SFX/Ambient buses), the auto-advancing music player and the audio factories (music, sounds, playlists). Replaces the former Core/Audio autoloads — the AudioModInitializer adds nodes named AudioService and MusicPlayer to the scene tree root on the boot Scenes phase, so /root/AudioService keeps resolving.",
|
||||
"description": "Audio engine: scene music, sound effects and ambience on separate buses with their own volume, and a music player that follows the current scene.",
|
||||
"category": "engine, library",
|
||||
"sources": [
|
||||
"src/**/*.cs"
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 85 KiB After Width: | Height: | Size: 160 KiB |
@@ -49,8 +49,8 @@ namespace Cthangover.Mods.Audio
|
||||
// setting up autoload children, so a direct AddChild is rejected.
|
||||
// Deferred calls run in FIFO order, which keeps AudioService ahead
|
||||
// of MusicPlayerBehaviour — its OnReady resolves AudioService.
|
||||
root.CallDeferred("add_child", new AudioService { Name = "AudioService" });
|
||||
root.CallDeferred("add_child", new MusicPlayerBehaviour { Name = "MusicPlayer" });
|
||||
ModRoot.AddDeferred(new AudioService { Name = "AudioService" });
|
||||
ModRoot.AddDeferred(new MusicPlayerBehaviour { Name = "MusicPlayer" });
|
||||
}
|
||||
|
||||
private static void EnsureEventSubscriptions()
|
||||
|
||||
@@ -52,6 +52,7 @@ namespace Cthangover.Mods.Audio
|
||||
/// <summary>Creates the three audio buses (Music/SFX/Ambient) if missing, the music and ambient players, and applies saved settings.</summary>
|
||||
protected override void OnReady()
|
||||
{
|
||||
ApplicationExit.Preparing += PrepareExit;
|
||||
AddToGroup("AudioService");
|
||||
SetupBuses();
|
||||
SetupMusicPlayer();
|
||||
@@ -77,6 +78,39 @@ namespace Cthangover.Mods.Audio
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Stops and detaches streams while the audio server still exists, including pooled sound players.</summary>
|
||||
protected override void OnExitTree()
|
||||
{
|
||||
ApplicationExit.Preparing -= PrepareExit;
|
||||
ReleasePlayer(musicPlayer);
|
||||
ReleasePlayer(ambientPlayer);
|
||||
foreach (var player in soundPlayers.Values) ReleasePlayer(player);
|
||||
soundPlayers.Clear();
|
||||
musicPlayer = null;
|
||||
ambientPlayer = null;
|
||||
}
|
||||
|
||||
private async System.Threading.Tasks.Task PrepareExit(SceneTree tree)
|
||||
{
|
||||
SetProcess(false);
|
||||
ambientPlayer.Finished -= OnAmbientFinished;
|
||||
ReleasePlayer(musicPlayer);
|
||||
ReleasePlayer(ambientPlayer);
|
||||
foreach (var player in soundPlayers.Values) ReleasePlayer(player);
|
||||
// Stop is queued to the mixer. Keep the main loop alive for its fade
|
||||
// and deferred playback destruction before SceneTree.Quit shuts the server down.
|
||||
var deadline = Godot.Time.GetTicksMsec() + 150;
|
||||
while (Godot.Time.GetTicksMsec() < deadline)
|
||||
await ToSignal(tree, SceneTree.SignalName.ProcessFrame);
|
||||
}
|
||||
|
||||
private static void ReleasePlayer(AudioStreamPlayer player)
|
||||
{
|
||||
if (!IsInstanceValid(player)) return;
|
||||
player.Stop();
|
||||
player.Stream = null;
|
||||
}
|
||||
|
||||
private int lastSoundsVolume = -1;
|
||||
private int lastMusicsVolume = -1;
|
||||
private int lastAmbientVolume = -1;
|
||||
|
||||
@@ -46,6 +46,33 @@ namespace Cthangover.Mods.Audio
|
||||
/// </summary>
|
||||
public bool IsCanAutoPlay { get; set; } = true;
|
||||
|
||||
/// <summary>Releases the pending fade and player reference when the audio mod leaves the tree.</summary>
|
||||
protected override void OnExitTree()
|
||||
{
|
||||
ApplicationExit.Preparing -= PrepareExit;
|
||||
StopForExit();
|
||||
}
|
||||
|
||||
private System.Threading.Tasks.Task PrepareExit(SceneTree tree)
|
||||
{
|
||||
StopForExit();
|
||||
return System.Threading.Tasks.Task.CompletedTask;
|
||||
}
|
||||
|
||||
private void StopForExit()
|
||||
{
|
||||
IsCanAutoPlay = false;
|
||||
SetProcess(false);
|
||||
if (IsInstanceValid(fadeTween)) fadeTween.Kill();
|
||||
fadeTween = null;
|
||||
if (IsInstanceValid(audioPlayer))
|
||||
{
|
||||
audioPlayer.Stop();
|
||||
audioPlayer.Stream = null;
|
||||
}
|
||||
audioPlayer = null;
|
||||
}
|
||||
|
||||
private Tween fadeTween;
|
||||
private bool playlistsInited;
|
||||
private double autoAdvanceCooldown;
|
||||
@@ -53,6 +80,7 @@ namespace Cthangover.Mods.Audio
|
||||
/// <summary>Registers in the <c>music_player</c> group and locates the AudioService music player.</summary>
|
||||
protected override void OnReady()
|
||||
{
|
||||
ApplicationExit.Preparing += PrepareExit;
|
||||
AddToGroup("music_player");
|
||||
TryFindAudioPlayer();
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user