audio-module

Instruction file imported from 50C4L/Vortex (.cursor/rules/audio-module.mdc). Copyright stays with the author.

Audio Module

Purpose

Thin RAII wrapper over miniaudio. AudioMixer owns the engine and creates SoundInstance objects from file paths. The ECS AudioSystem manages SoundInstance pools and drives playback via AudioEventComponent (SFX) and BgmComponent (scene music).

Key Classes

API

// Mixer lifetime is managed by AudioSystem -- rarely construct directly
AudioMixer mixer;

// Create a sound (loaded asynchronously by miniaudio)
SoundInstance sfx = mixer.CreateSound( "resources/sounds/laser.wav", /*looping=*/false );
SoundInstance music = mixer.CreateSound( "resources/sounds/bgm.ogg", /*looping=*/true );

// Playback control
sfx.Play();
sfx.Stop();
sfx.Restart();   // seek to 0 + Play -- used for overlapping one-shot SFX

Key Patterns

• RAII: Both ma_engine and ma_sound are held in unique_ptr with custom deleters that call miniaudio teardown. Never manually uninit.
• Move semantics: SoundInstance is movable for storage in std::vector / ResourceStore. Copy is deleted.
• SoundPool (in AudioSystem): For SFX that can overlap (e.g. bullet fire), AudioSystem keeps a pool of SoundInstance objects and round-robins Restart() calls instead of creating new instances each time. Pools with ignore_pause = true are skipped by OnPauseChanged -- BGM uses this; looping SFX (thruster) do not.
• BGM: LoadBgm loads a 1-instance ignore_pause pool and returns a ResourceId. The scene creates a BgmComponent entity and parents it to the scene root. ProcessBgm() runs before the pause gate and reconciles playing vs pool.is_playing. Destroying the entity stops the pool via OnEntityDestroying.
• Async loading: Miniaudio loads audio data on a background thread. Play() called immediately after CreateSound() may produce silence for a frame -- this is expected.

DOs

• Use Restart() for one-shot SFX that can overlap -- cheaper than creating a new SoundInstance each time
• Store SoundInstance by value in pools (it's movable) -- don't heap-allocate unnecessarily
• Control SFX from game code via AudioEventComponent queue + AudioSystem, not by calling SoundInstance methods directly
• Control scene music via BgmComponent::playing (or destroy the entity); do not route BGM through AudioSourceComponent

DON'Ts

• Don't copy SoundInstance -- it's deleted; move it instead
• Don't call ma_engine_uninit / ma_sound_uninit manually -- RAII handles cleanup
• Don't treat looping as ignore-pause -- thruster loops and must still mute with the game
• Don't construct AudioMixer more than once -- ma_engine is a singleton-like resource