Audio

Chapter contract

miniaudio behind a small facade: init, SoundCategory buses, spatial vs non-spatial play, listener = camera, volume product, handle lifecycle. Aligned with audio_system.hpp.

Initialize / shutdown

AudioSystem::initialize

If already initialized, return true
new ma_engine + ma_engine_config_init
ma_engine_init — on failure log code and return false
Store unique_ptr with custom deleter → ma_engine_uninit
m_initialized = true

Shutdown stops sounds, clears map, resets engine. Uninitialized play APIs return INVALID_SOUND_HANDLE (0).

SoundCategory buses

Enum	Index	Use
`SoundCategory::SFX`	0	One-shots
`SoundCategory::Music`	1	Looping score
`SoundCategory::Ambient`	2	Spatial beds

Helpers: soundCategoryName, isValidSoundCategory. Convenience: playSfx, playMusic (loop default true), playAmbientAt.

playSound workflow

Non-spatial

Guard path + initialized
ma_sound_init_from_file
ma_sound_set_spatialization_enabled(false)
Loop flag; volume; start
Insert into handle map; return handle

playSoundAt workflow

Spatial

Init from file; enable spatialization
Set position; min distance 1; max 50; inverse attenuation model
Loop/volume; start; store handle
Update with setSoundPosition if emitter moves

Listener sync

setListenerPosition(pos, forward, up) → ma_engine_listener_set_* on listener 0. Call every frame from camera. Godot host docs: synced automatically.

Why camera = ears

Spatial audio without matching viewpoint feels “wrong room” even when emitter coordinates are correct.

Volume product

g=g_{\mathrm{master}}\cdot g_{\mathrm{SoundCategory}}\cdot g_{\mathrm{voice}}\in[0,1]

Clamped buses let users mute Music without killing SFX.

Handles & bulk ops

SoundHandle = uint32; 0 invalid. stop/pause/resume/setVolume/isPlaying/activeSoundCount. Bulk: stop category, pause category, stop all. Facade never returns raw ma_sound* — deleters live in .cpp with full miniaudio types (header only forward-declares).

Design

Forward-declare ma_engine

miniaudio header is huge; keep includes out of engine-wide headers.

audio_system.hppSoundCategory · API

audio_system.cppma_* calls

docs/audio.mdHost/GDScript

tests/audio/*Unit tests

Design units in this module

Each card is a focused design page (what / how / why + sources). Full tree: Sitemap.

system

AudioSystem facade

Init, categories, handles, 3D, volumes.