Add mod documentation in seven languages

docs/ko.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을 다른 오디오 콘텐츠와 써도 됩니다.
+
+## 게임 제작자를 위해: 사운드트랙 추가하기
+
+콘텐츠 모드의 기존 `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는 현재 오디오 팩토리가 지원하지 않습니다.