Interface IAudioSystem

Namespace

Framework.Systems.Audio

Assembly

Assembly-CSharp.dll

Audio System 단일 진입점 계약. Gameplay 개발자는 이 인터페이스만 알면 된다.

public interface IAudioSystem

Remarks

[API 사용 레벨] Level 1 (필수): PlayBGMAsync / PlaySFXAsync / SetVolume Level 2 (중급): StopBGMAsync / CrossFadeBGMAsync / PlayUI* / GetVolume Level 3 (고급): PlaySFXControlledAsync — IAudioHandle 로 개별 제어

[규칙] AudioClip 키는 AudioKeys 상수 사용. 매직 스트링 금지. [규칙] 볼륨 저장은 SettingsSystem 책임. AudioSystem 에서 직접 저장 금지. [규칙] Addressables 직접 호출 금지. IAssetSystem 경유.

Methods

GetVolume(AudioChannel)

현재 채널 볼륨을 반환한다 (0~1). SettingsSystem 에서 볼륨 복원 시 현재 값 조회에 사용.

float GetVolume(AudioChannel channel)

Parameters

channel AudioChannel

Returns

float

PlayBGMAsync(string, float, float, CancellationToken)

BGM 을 재생한다. 현재 재생 중인 BGM 이 없으면 FadeIn, 있으면 자동 CrossFade 처리. fadeIn / crossFadeDuration 을 0 으로 설정하면 즉시 전환.

UniTask PlayBGMAsync(string key, float fadeIn = 0.5, float crossFadeDuration = 1, CancellationToken ct = default)

Parameters

key string

Addressables 키. AudioKeys 상수 사용 권장.

fadeIn float

재생 시작 FadeIn 시간(초). 현재 BGM 없을 때 적용.

crossFadeDuration float

기존 BGM 이 있을 때 CrossFade 시간(초). 0 이면 즉시 교체.

ct CancellationToken

Returns

UniTask

PlaySFXAsync(string, CancellationToken)

SFX 를 재생한다. Pool 에서 AudioSource 를 꺼내 사용. 동시 재생 가능. 재생 후 제어가 필요하지 않은 일반적인 경우에 사용한다. 개별 제어(Stop/Pitch/Volume)가 필요하면 PlaySFXControlledAsync(string, CancellationToken) 사용.

UniTask PlaySFXAsync(string key, CancellationToken ct = default)

Parameters

key string

ct CancellationToken

Returns

UniTask

PlaySFXControlledAsync(string, CancellationToken)

SFX 를 재생하고 제어 핸들을 반환한다. Stop / Pause / SetPitch / SetVolume 등 개별 제어가 필요한 경우에 사용. 일반 재생은 PlaySFXAsync(string, CancellationToken) 를 사용한다.

UniTask<IAudioHandle> PlaySFXControlledAsync(string key, CancellationToken ct = default)

Parameters

key string

ct CancellationToken

Returns

UniTask<IAudioHandle>

PlayUICancel()

취소 버튼 사운드.

void PlayUICancel()

PlayUIClick()

버튼 클릭 사운드. Audio/UI/Click Addressable 키 사용.

void PlayUIClick()

PlayUIClose()

팝업/화면 닫힘 사운드.

void PlayUIClose()

PlayUIConfirm()

확인 버튼 사운드.

void PlayUIConfirm()

PlayUIControlledAsync(string, CancellationToken)

UI 사운드를 재생하고 제어 핸들을 반환한다. 고급 제어가 필요한 경우에만 사용.

UniTask<IAudioHandle> PlayUIControlledAsync(string key, CancellationToken ct = default)

Parameters

key string

ct CancellationToken

Returns

UniTask<IAudioHandle>

PlayUIOpen()

팝업/화면 열림 사운드.

void PlayUIOpen()

SetVolume(AudioChannel, float)

채널 볼륨을 설정한다. AudioMixer Exposed Parameter 를 dB 로 변환해 적용.

void SetVolume(AudioChannel channel, float volume)

Parameters

channel AudioChannel

대상 채널.

volume float

0~1 범위. 0 은 무음, 1 은 최대.

StopBGMAsync(float, CancellationToken)

현재 BGM 을 정지한다. fadeOut = 0 이면 즉시 정지.

UniTask StopBGMAsync(float fadeOut = 0.5, CancellationToken ct = default)

Parameters

fadeOut float

ct CancellationToken

Returns

UniTask