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을 더하세요. 모드를 설치하고 대상 게임의 컬렉션에 넣는 일도 잊지 마세요. 설치된 콘텐츠 모드가 모든 게임에 저절로 들어가지는 않습니다.

// manifest의 기존 의존성 목록에 추가:
"depends": ["audio_base>=1"]

음악은 music/ 아래에, 효과음과 환경 루프는 sounds/ 아래에 둡니다. 새 예제에는 Ogg Vorbis(.ogg)를 쓰세요. 함께 제공되는 사운드트랙과 선술집 환경음이 이 형식입니다.

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

music/playlists/my_scene.json의 예:

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

Scene은 장면의 논리 이름과 일치해야 합니다. 곡 이름은 music/ 기준 상대 경로이고 확장자는 붙이지 않습니다. 리소스 이름의 철자, 대소문자, 공백을 그대로 지키세요.

여기서 MusicType: "Ambient"는 탐험 음악을 뜻합니다. 이 곡이 별도의 환경음 채널로 보내지는 게 아닙니다.

게임 제작자를 위해: 장면에 환경 루프 주기

장면 정의의 defaultAmbient를 sounds/ 기준 상대 경로의 소리 리소스로, 확장자 없이 지정합니다:

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

이 조각은 소리 관련 필드를 보여 줄 뿐입니다. 장면에 필요한 다른 필드는 그대로 두세요. defaultAmbient가 빈 장면은 이전 장면의 환경 루프를 멈춥니다.

실제 예는 소설 템플릿의 my_novel_bar 장면입니다. defaultAmbient: "bar/bar_ambient"을 쓰고, 소리는 Town Pack이 공급합니다. 그 자원을 자기 모드에서 재활용하려면 소유자인 town_pack에 대한 의존성도 필요합니다.

장면 전환, 전투, 덮어쓰기

장면에 쓸 만한 플레이리스트가 없으면 Audio Engine은 공용 default 플레이리스트를 찾습니다. 음악이 나오는 건 알맞은 오디오 콘텐츠가 있을 때뿐입니다.
장면 전용 플레이리스트가 있으면 빠진 음악 유형을 default로 채우지 않습니다. 그 장면의 음악 컨텍스트가 필요로 하는 버킷을 담아 두세요.
장면이 바뀔 때 현재 곡이 새 목록에도 있고 음악 유형이 그대로라면 계속 흐를 수 있습니다.
전투에 들어갈 때 탐험 곡과 그 위치를 저장하고, 탐험으로 돌아오면 복원을 시도합니다. 이는 실시간 재생 동작이지, 저장 파일을 불러올 때 정확한 음악 시점까지 돌아간다는 보장이 아닙니다.
같은 장면과 음악 유형에는 나중에 로드된 모드가 앞선 곡 목록을 대체합니다. 목록은 합쳐지지 않습니다. 상대 이름이 같은 리소스 파일 역시 뒤에 로드된 모드에게 덮어씌워질 수 있습니다.

전투 음악 컨텍스트에는 Combat 버킷을 쓰세요. 아무 버킷 이름을 만든다고 해서 새 컨텍스트나 설정 슬라이더가 생기지는 않습니다.

소리가 나지 않을 때

설정 → 소리에서 해당 토글과 음량을 확인하세요. 음악, 효과음, 환경음은 서로 독립적입니다.
선택한 게임에 Audio Engine과 필요한 콘텐츠 모드가 로드되어 있는지 확인하세요. Audio Engine에는 Music Pack의 곡도 Town Pack의 선술집 루프도 들어 있지 않습니다.
음악이라면 장면 이름, 필요한 Ambient 또는 Combat 버킷, 모든 곡 이름을 확인하세요. 플레이리스트 참조만으로 오디오 파일이 만들어지거나 내려받아지지 않습니다.
환경음이라면 defaultAmbient와 sounds/ 아래의 리소스를 확인하세요. 이전 루프가 멈췄다면 새 장면에서 그 필드가 비어 있는지도 보세요.
플레이리스트 버킷이나 오디오 리소스를 대체할 수 있는 뒤에 로드되는 모드를 확인하세요. 게임 로그에 빠진 오디오 파일이나 플레이리스트 해석 오류가 없는지도 보세요.

이 안내서는 지원되는 Ogg Vorbis 경로를 다룹니다. 엔진에는 WAV 불러오기 경로도 있지만, 현재 로더는 WAV 컨테이너 메타데이터를 살피지 않습니다. 내보낸 WAV가 모두 올바르게 동작한다고 가정하지 마세요. 확실치 않으면 새 콘텐츠를 Ogg Vorbis로 변환하세요. MP3는 현재 오디오 팩토리가 지원하지 않습니다.

8.1 KiB Raw Blame History