Audio System Guide

This document explains how to use the AudioSystem in your engine. The system uses NAudio to load and play sound files with volume control and proper resource management.

The AudioSystem is a singleton that manages sound playback:

• Auto-initializes - No manual setup required

• Name-based - Sounds are registered by logical name, not file paths

• Volume control - Each sound can have its own volume

• Multi-playback - Same sound can play multiple times simultaneously

• Auto-cleanup - Resources are disposed when playback stops

Core Functions

Load Sound Register a sound file with a logical name:

// Load a sound file
audioSystem.Load("Jump", "sounds/jump.wav");
audioSystem.Load("Explosion", "sounds/explosion.mp3");
audioSystem.Load("BackgroundMusic", "music/main_theme.mp3");

Parameters:

• name - Logical identifier for the sound

• filePath - Path to the audio file

Constraints:

• Name cannot be null or whitespace

• File path cannot be null or whitespace

Play Sound

Play a registered sound:

// Play at default volume (1.0)
audioSystem.Play("Jump");

// Play with custom volume
audioSystem.Play("Explosion", volume: 0.5f);
audioSystem.Play("BackgroundMusic", volume: 0.8f);

Parameters:

• name - The logical name of the sound

• volume - Volume multiplier (0.0f to 1.0f)

Stop Sound

Stop all instances of a specific sound:

// Stop a specific sound
audioSystem.Stop("Jump");

// Or stop with immediate effect (waits for cleanup)
audioSystem.Stop("Explosion");

Stop All Sounds

Stop every sound currently playing:

// Stop all audio
audioSystem.StopAll();

Usage Examples

Basic Sound Playback

// Initialize audio system (auto-creates singleton)
AudioSystem audioSystem = AudioSystem.Instance;

// Load sounds
audioSystem.Load("Jump", "sounds/jump.wav");
audioSystem.Load("Explosion", "sounds/explosion.wav");
audioSystem.Load("Shooting", "sounds/shoot.wav");

// Play sounds in your game loop
void OnPlayerJump()
{
    audioSystem.Play("Jump");
}

void OnEnemyDeath()
{
    audioSystem.Play("Explosion", volume: 1.0f);
}

Volume Management

// Low volume for background music
audioSystem.Play("BackgroundMusic", volume: 0.3f);

// Full volume for important sounds
audioSystem.Play("Explosion", volume: 1.0f);

// Mute a sound temporarily
audioSystem.Play("Shooting", volume: 0.0f);

// Fade in (progressive volume increase)
void FadeInSound(float progress)
{
    var currentVolume = progress * 1.0f;
    audioSystem.Play("Music", volume: currentVolume);
}

Multiple Simultaneous Playbacks

The system supports multiple concurrent instances of the same sound:

// Player jumps multiple times
void OnJump1()
{
    audioSystem.Play("Jump");
}

void OnJump2()
{
    audioSystem.Play("Jump");
}

// Both play simultaneously until each completes

Stop Specific Instance

// Stop a sound that's currently playing
void OnPauseGame()
{
    audioSystem.Stop("BackgroundMusic");
}

void OnResumeGame()
{
    audioSystem.Play("BackgroundMusic", volume: 0.8f);
}

Audio integration with Game Events

public class Game : MonoBehaviour
{
    private AudioSystem audioSystem;

    public void Awake()
    {
        audioSystem = AudioSystem.Instance;

        // Pre-load all sounds
        audioSystem.Load("Jump", "sounds/jump.wav");
        audioSystem.Load("Shoot", "sounds/shoot.wav");
        audioSystem.Load("PowerUp", "sounds/powerup.wav");

        // Set music volume
        audioSystem.Play("BackgroundMusic", volume: 0.5f);
    }

    public void OnPlayerJump()
    {
        audioSystem.Play("Jump");
    }

    public void OnGameOver()
    {
        audioSystem.Stop("BackgroundMusic");
        audioSystem.Play("GameOverMusic", volume: 0.6f);
    }
}

Error Handling

try
{
    audioSystem.Play("Jump");
}
catch (KeyNotFoundException ex)
{
    Console.WriteLine($"Sound not loaded: {ex.Message}");
}

Summary

• Auto-initializes - Use AudioSystem.Instance for singleton access

• Load sounds with Load(name, filePath)

• Play sounds with Play(name, volume)

• Stop sounds with Stop(name)

• Stop all with StopAll()

• Volume control - Each playback has its own volume setting

• Multi-playback - Same sound can play multiple times

• Auto-cleanup - Resources disposed automatically on playback end

The AudioSystem provides a simple, efficient way to manage sound playback in your game!