punkfuncgames/audio-module

AudioModule Reference

Package: com.punkfuncgames.audio | Define: PUNKFUNC_AUDIO Location: Packages/com.punkfuncgames.audio/Runtime/PunkFuncGames.Audio/ Namespace: PunkFuncGames.Audio

Services

ISFXService

• PlaySFX(string id, float volumeScale = 1f)
• PlaySFXAtPosition(string id, Vector3 position, float volumeScale = 1f)

IMusicService

• ReadOnlyReactiveProperty<bool> IsMusicPlaying
• UniTask PlayMusicAsync(string id, float crossfadeDuration = 1f, bool loop = true, ct)
• UniTask StopMusicAsync(float fadeOutDuration = 1f, ct)
• PauseMusic(), ResumeMusic()

IVolumeService

• ReadOnlyReactiveProperty<float> MasterVolume, MusicVolume, SFXVolume
• SetVolume(AudioChannel channel, float volume) — clamped 0-1
• float GetVolume(AudioChannel channel)

AudioChannel Enum

Master, Music, SFX, Voice, Ambient

Implementation: AudioService

Single service implements all 3 interfaces. Optional dependency: AudioSettings ScriptableObject.

• Creates [AudioService] root (DontDestroyOnLoad) with 2 music sources (A/B crossfade) + SFX pool
• Dual music sources for seamless crossfading via linear interpolation
• SFX pool size configurable (default 16), max concurrent sounds (default 32)
• Volume → dB conversion: Mathf.Log10(volume) * 20f (0 → -80dB)
• Pitch randomization support per SoundData

AudioEventHandler : IAsyncStartable

Bridges MessagePipe events to AudioService:

• PlaySFXRequest → PlaySFX/PlaySFXAtPosition
• PlayMusicRequest → PlayMusicAsync
• GamePausedEvent → PauseMusic
• GameResumedEvent → ResumeMusic

Configuration (Config + Data Pattern)

AudioSettings (ScriptableObject, "PunkFuncGames/Audio Settings"):

• Thin wrapper: public AudioSettingsData data;
• Access fields via _settings.data.fieldName

AudioSettingsData ([Serializable] public struct, camelCase fields):

• mainMixer, masterVolumeParam, musicVolumeParam, sfxVolumeParam
• defaultMasterVolume (1.0), defaultMusicVolume (0.7), defaultSFXVolume (1.0)
• sfxPoolSize, maxConcurrentSounds
• List<SoundData> sounds, List<MusicData> music

SoundData ([Serializable] public struct): id, clip, volume, pitch, randomizePitch, pitchVariation, loop, spatialBlend MusicData ([Serializable] public struct): id, clip, volume, bpm, loop

Extension methods provide any logic previously on the ScriptableObject.

Events (Request structs for MessagePipe)

| Event | Key Fields | |-------|------------| | PlaySFXRequest | SoundId, Volume, Position? | | PlayMusicRequest | MusicId, CrossfadeDuration, Loop |

Installer

AudioInstaller.Install(builder, options, audioSettings);
// Registers: AudioService as EntryPoint (ISFXService, IMusicService, IVolumeService)
// Registers: AudioSettings via RegisterInstance (if non-null)
// Registers: AudioEventHandler as EntryPoint
// Events: PlaySFXRequest, PlayMusicRequest brokers

Third parameter AudioSettings settings = null is optional. When provided, the settings ScriptableObject is registered via RegisterInstance.

Usage Pattern

// Direct service call
_sfxService.PlaySFX("ButtonClick");
_sfxService.PlaySFXAtPosition("Explosion", transform.position);
await _musicService.PlayMusicAsync("BattleTheme", crossfadeDuration: 2f);

// Via MessagePipe (decoupled)
_sfxPublisher.Publish(new PlaySFXRequest("Coin", volume: 0.8f));
_musicPublisher.Publish(new PlayMusicRequest("MenuMusic", crossfadeDuration: 1.5f));

// Volume binding
_volumeService.MasterVolume
    .Subscribe(vol => _masterSlider.value = vol)
    .AddTo(_disposables);