Sound Manager

Abstract

Sound Manager 는 AudioSource 를 직접 들고 다니지 않게 해 주는 모듈입니다. "이 주소의 소리를, 이 그룹으로, 여기서 틀어 줘" 한 줄이면 클립 로드·빈 AudioSource 찾기·재생·끝난 뒤 정리를 대신 합니다. 핵심 개념은 둘 — 그룹(볼륨을 함께 조절하는 묶음)과 에이전트(그 그룹이 동시에 낼 수 있는 소리의 수)입니다.

Unity 기본 방식과 비교

하고 싶은 일	Unity 기본	Sound Manager
효과음 한 번	오브젝트마다 AudioSource • 클립 참조 + PlayOneShot	PlaySound("PlayerHurt", "Soundeffects", position)
효과음 볼륨 일괄 조절	모든 AudioSource 를 찾아 돌거나 믹서 구성	그룹의 Volume 하나
동시 재생 수 제한	직접 구현	그룹의 에이전트 수 + 우선순위
배경음 페이드 전환	코루틴으로 볼륨 보간	FadeInSeconds, StopSound(id, fadeOutSeconds)
씬에 흩어진 클립 참조	프리팹마다 인스펙터에 연결	주소 문자열만. 클립은 필요할 때 로드

ToyboxNightmare 에서의 실제 사용

효과음 재생을 한 함수로 모았습니다.

public static class GameSound
{
    public static void PlaySfx(string assetName, Vector3 worldPosition)
    {
        if (string.IsNullOrEmpty(assetName)) return;

        SoundComponent sound = GameEntry.GetComponent<SoundComponent>();
        if (sound == null) return;

        sound.PlaySound(assetName, SoundTable.SfxGroup, worldPosition);
    }
}

// 쓰는 쪽
GameSound.PlaySfx("ZomBunnyDeath", transform.position);

복사

"소리가 안 나는 것이 게임을 멈출 이유는 되지 않는다"는 원칙으로, 주소가 비었거나 사운드 시스템이 없으면 조용히 넘어갑니다.

그룹	에이전트 수	용도
Music	1	배경음 (한 번에 한 곡)
Soundeffects	8	피격·사망 효과음. 동시에 8개까지 겹친다

예제가 모든 소리를 Sound Manager 로 보내는 것은 아닙니다. 번개 발사음이나 착탄음처럼 이펙트 프리팹에 이미 AudioSource 로 들어 있는 소리는 그대로 둡니다. 파티클과 한 덩어리로 만들어진 연출이라 떼어 내면 프리팹 단위로 조정할 수 없기 때문입니다. Sound Manager 를 거치는 것은 프리팹에 없는 게임플레이 사운드(피격, 사망)입니다. "전부 프레임워크로"가 아니라 경계를 정하는 것이 실무입니다.

에이전트가 다 찼을 때

8개가 모두 재생 중인데 9번째 소리가 오면:

•

새 소리의 우선순위가 더 높으면 가장 우선순위 낮은 소리를 끊고 그 자리에서 재생한다

•

같으면 가장 오래된 소리를 끊는다 (그룹의 Avoid Being Replaced By Same Priority 가 켜져 있으면 끊지 않고 새 소리를 버린다)

•

낮으면 새 소리를 버리고 PlaySoundFailure 이벤트가 온다

탄막 게임처럼 효과음이 쏟아지는 장르에서는 "플레이어 피격음" 같은 중요한 소리에 높은 우선순위를 줘서 묻히지 않게 합니다.

확장 — 배경음 넣기

private const float MusicFadeSeconds = 2f;

PlaySoundParams musicParams = PlaySoundParams.Create();
musicParams.Loop = true;
musicParams.FadeInSeconds = MusicFadeSeconds;

mMusicId = sound.PlaySound("BattleTheme", SoundTable.MusicGroup, musicParams);

// 곡을 바꿀 때
sound.StopSound(mMusicId, MusicFadeSeconds);

복사

엔티티에 붙어 따라다니는 소리(엔진음, 발소리)는 PlaySound(asset, group, bindingEntity) 를 씁니다. 엔티티가 움직이면 소리 위치도 따라가고, 엔티티가 회수되면 소리도 함께 멎습니다.

이 에디션에서 다른 점 · 본문을 읽을 때 주의할 점

•

본문 "사용 방법 1~3"의 초기화·그룹 생성·에이전트 추가 코드는 코어 API 를 직접 부르는 예시입니다. 실제로는 SoundComponent 가 인스펙터 설정(그룹 이름, 에이전트 수)을 읽어 Start 에서 전부 해 줍니다. 게임 코드는 PlaySound 부터 씁니다.

•

에셋 이름 자리에 파일명("explosion.wav")이 아니라 Addressables 주소("PlayerHurt")를 넣습니다.

•

결과는 soundManager.PlaySoundSuccess += 가 아니라 EventComponent 의 PlaySoundSuccessEventArgs / PlaySoundFailureEventArgs 구독으로 받습니다. PlaySoundUpdate / PlaySoundDependencyAsset 은 이 에디션에서 발생하지 않습니다.

•

그룹 볼륨과 AudioMixer 는 별개입니다. 예제의 볼륨 슬라이더는 그룹의 Volume 이 아니라 AudioMixer 의 노출 파라미터를 직접 조절합니다(원본 Zombie Toys 의 구성을 따름). 믹서를 쓰지 않는 프로젝트라면 sound.GetSoundGroup("Soundeffects").Volume = 0.5f 한 줄이 가장 간단합니다.

•

소리마다 클립을 그때그때 로드합니다. 처음 재생할 때 한 박자 늦을 수 있으므로, 또 재생이 끝나면 클립을 반납하므로, 자주 쓰는 효과음은 로딩 화면에서 ResourceComponent.LoadAsset 으로 미리 한 번 로드해 콜백으로 받은 에셋을 쥐고 있으면(판이 끝날 때 UnloadAsset) 클립이 메모리에 남아 이후 재생에 지연이 없습니다.

•

Unity 6 에서 소리를 재생할 때마다 콘솔에 Attempting to set 'time' on an audio source that has a resource assigned that is not a clip is ignored! 경고가 찍히던 문제가 원작에 있었습니다(에이전트를 초기화하면서 클립이 없는 AudioSource 의 time 을 0 으로 되돌리기 때문). 이 에디션에서는 고쳐 두어 더 이상 나오지 않습니다.

Sound Manager 개요

Sound Manager는 게임에서 오디오 리소스를 관리·로드·재생하는 핵심 모듈입니다.

다음과 같은 기능을 제공합니다:

•

사운드를 논리적인 그룹으로 관리

•

재생 제어(재생, 정지, 일시 정지, 재개)

•

그룹 및 개별 사운드 수준에서 볼륨·음소거 제어

•

재생 우선순위 설정 및 제한 시 동작 정의

•

페이드 인·아웃 지원

•

비동기 사운드 로딩과 이벤트 알림

아키텍처

•

Game Framework 전체에서 사용하는 모듈 아키텍처 패턴을 따릅니다.

•

GameFrameworkModule을 상속받고 GameFrameworkEntry에 의해 관리됩니다.

•

사운드 리소스 로드는 Resource Manager에 의존합니다.

•

플랫폼별 구현은 Helper 인터페이스로 추상화됩니다.

핵심 구성 요소

1. Sound Group

사운드를 그룹별로 묶어 제어합니다.

•

Name: 그룹의 고유 이름

•

AvoidBeingReplacedBySamePriority: 동일 우선순위 사운드로 대체 여부

•

Mute: 그룹 전체 음소거 여부

•

Volume: 그룹 전체 볼륨(0.0~1.0)

•

SoundAgentCount: 해당 그룹의 사운드 에이전트 수

2. Sound Agent

•

실제 사운드 재생을 담당합니다.

•

각 그룹은 여러 Sound Agent를 가질 수 있으며, 이는 동시에 재생 가능한 사운드 수를 의미합니다.

•

플랫폼별 Agent Helper를 통해 생성됩니다.

사용 방법

1. 초기화

ISoundManager soundManager = GameFrameworkEntry.GetModule<ISoundManager>();
soundManager.SetResourceManager(resourceManager);
soundManager.SetSoundHelper(soundHelper);

복사

2. 사운드 그룹 생성

soundManager.AddSoundGroup("Music", musicGroupHelper);
soundManager.AddSoundGroup("SFX", true, false, 0.8f, sfxGroupHelper);

복사

3. 사운드 에이전트 추가

soundManager.AddSoundAgentHelper("Music", musicAgentHelper);
for (int i = 0; i < 10; i++)
{
    soundManager.AddSoundAgentHelper("SFX", CreateSoundAgentHelper());
}

복사

4. 사운드 재생

// 기본 재생
int serialId = soundManager.PlaySound("explosion.wav", "SFX");

// 파라미터 사용
PlaySoundParams playSoundParams = PlaySoundParams.Create();
playSoundParams.Priority = 100;
playSoundParams.Loop = true;
playSoundParams.VolumeInSoundGroup = 0.5f;
playSoundParams.FadeInSeconds = 2f;
playSoundParams.SpatialBlend = 1f;

int musicId = soundManager.PlaySound("background.mp3", "Music", playSoundParams);

복사

5. 재생 제어

soundManager.StopSound(serialId);
soundManager.StopSound(serialId, 3.0f);
soundManager.PauseSound(serialId);
soundManager.ResumeSound(serialId);
soundManager.StopAllLoadedSounds();

복사

이벤트 시스템

•

PlaySoundSuccess – 사운드가 정상적으로 재생 시작

•

PlaySoundFailure – 로드 또는 재생 실패

•

PlaySoundUpdate – 로딩 진행률 업데이트

•

PlaySoundDependencyAsset – 사운드 종속 리소스 로드 시 호출

// 코어 내부에서는 C# 이벤트로 나가지만 (아래), 게임 코드에서는 EventComponent 로 받는다
soundManager.PlaySoundSuccess += (sender, e) =>
{
    Debug.Log($"Sound {e.SerialId} ({e.SoundAssetName}) started!");
};

// 게임 코드
events.Subscribe(PlaySoundSuccessEventArgs.EventId, OnPlaySoundSuccess);
events.Subscribe(PlaySoundFailureEventArgs.EventId, OnPlaySoundFailure);

복사

리소스 시스템 연동

•

Sound Manager는 사운드 재생 요청 시 Resource Manager를 통해 리소스를 로드합니다.

•

로드 완료 후 Sound Agent를 생성해 재생을 시작합니다.

프레임워크 내 위치

•

Sound Manager는 Entity Manager, UI Manager와 함께 핵심 모듈입니다.

•

세 모듈 모두 Resource Manager에 의존하며, 그룹 기반 구조를 사용합니다.

일반 사용 사례

배경음악

soundManager.AddSoundGroup("Music", false, false, 0.8f, musicGroupHelper);
soundManager.AddSoundAgentHelper("Music", musicAgentHelper);

PlaySoundParams musicParams = PlaySoundParams.Create();
musicParams.Loop = true;
musicParams.FadeInSeconds = 2.0f;
int musicId = soundManager.PlaySound("background.mp3", "Music", musicParams);

복사

효과음

soundManager.AddSoundGroup("SFX", true, false, 1.0f, sfxGroupHelper);
for (int i = 0; i < 5; i++)
{
    soundManager.AddSoundAgentHelper("SFX", CreateSfxAgentHelper());
}

soundManager.PlaySound("explosion.wav", "SFX");
soundManager.PlaySound("footstep.wav", "SFX");

복사

UI 사운드

soundManager.AddSoundGroup("UI", false, false, 0.5f, uiSoundGroupHelper);
soundManager.AddSoundAgentHelper("UI", uiSoundAgentHelper);

soundManager.PlaySound("button_click.wav", "UI");
soundManager.PlaySound("menu_open.wav", "UI");

복사

결론

Game Framework의 Sound Manager는 그룹·에이전트 기반 오디오 시스템을 제공해, 세밀한 사운드 제어와 리소스 관리 통합을 가능하게 합니다. 이를 통해 다양한 오디오 환경에서 유연하고 강력한 재생 기능을 구현할 수 있습니다.