Sound Extensions

SoundExtensions provides a comprehensive set of extension methods for sound playback, making common sound operations more intuitive and expressive.

---

Overview

Feature	Description
One-Shot Playback	Play a sound with a single call
Play and Forget	Auto-dispose when playback completes
Pitch Variation	Random pitch variation for natural variety
Fluent Configuration	Chain configuration methods on sound instances
Collection Playback	Play all or random sounds from a collection

---

Sound Playback

PlayOneShot

Plays the sound as a one-shot instance.

var sound = AssetManager.Instance.Load<Sound>("explosion.wav");

// Basic playback
var instance = sound.PlayOneShot();

// With custom settings
var instance = sound.PlayOneShot(
    volume: 0.8f,
    pan: -0.5f,      // Left channel
    pitch: 1.2f,      // Higher pitch
    category: SoundCategory.SFX
);

PlayAndForget

Plays the sound and automatically disposes it when playback completes.

// Plays and auto-disposes
sound.PlayAndForget();

// With custom settings
sound.PlayAndForget(
    volume: 0.8f,
    pan: 0f,
    pitch: 1f,
    category: SoundCategory.SFX
);

PlayWithPitchVariation

Plays the sound with random pitch variation for natural variety.

// Play with ±10% pitch variation
sound.PlayWithPitchVariation();

// Play with ±15% pitch variation
sound.PlayWithPitchVariation(
    pitchRange: 0.15f,
    volume: 0.8f,
    pan: 0f,
    category: SoundCategory.SFX
);

---

Fluent Configuration

WithVolume

Sets the volume of the sound instance.

sound.CreateInstance()
    .WithVolume(0.8f)
    .Play();

WithPan

Sets the pan of the sound instance.

sound.CreateInstance()
    .WithPan(-0.5f)  // Left channel
    .Play();

WithPitch

Sets the pitch of the sound instance.

sound.CreateInstance()
    .WithPitch(1.2f)  // Higher pitch
    .Play();

WithLooping

Sets whether the sound instance should loop.

sound.CreateInstance()
    .WithLooping(true)
    .Play();

PlayWith

Sets the volume, pan, and pitch, then plays the sound.

sound.CreateInstance()
    .PlayWith(
        volume: 0.8f,
        pan: -0.5f,
        pitch: 1.2f
    );

---

Stop and Dispose

StopAndDispose

Stops the sound instance and disposes it.

var instance = sound.PlayOneShot();

// Later...
instance.StopAndDispose();

---

Collection Playback

PlayAll

Plays all sounds in the collection as one-shot instances.

var sounds = new[] { sound1, sound2, sound3 };

var instances = sounds.PlayAll(
    volume: 0.7f,
    pan: 0f,
    pitch: 1f
);

PlayAllAndForget

Plays all sounds in the collection and automatically disposes them when playback completes.

var sounds = new[] { sound1, sound2, sound3 };

sounds.PlayAllAndForget(
    volume: 0.7f,
    pan: 0f,
    pitch: 1f
);

PlayRandom

Plays a random sound from the collection.

var sounds = new[] { footstep1, footstep2, footstep3, footstep4 };

var instance = sounds.PlayRandom(
    volume: 0.7f,
    pan: 0f,
    pitch: 1f
);

PlayRandomWithVariation

Plays a random sound from the collection with random pitch variation.

var sounds = new[] { footstep1, footstep2, footstep3, footstep4 };

var instance = sounds.PlayRandomWithVariation(
    pitchRange: 0.12f,
    volume: 0.7f,
    pan: 0f
);

PlayRandomAndForget

Plays a random sound from the collection and automatically disposes it when playback completes.

var sounds = new[] { footstep1, footstep2, footstep3, footstep4 };

sounds.PlayRandomAndForget(
    volume: 0.7f,
    pan: 0f,
    pitch: 1f
);

PlayRandomWithVariationAndForget

Plays a random sound from the collection with random pitch variation and automatically disposes it when playback completes.

var sounds = new[] { footstep1, footstep2, footstep3, footstep4 };

sounds.PlayRandomWithVariationAndForget(
    pitchRange: 0.12f,
    volume: 0.7f,
    pan: 0f
);

---

Examples

Footstep Sounds

public void PlayFootstep()
{
    // Register footstep sounds once
    SoundHelper.RegisterSoundGroup("footsteps",
        _footstep1, _footstep2, _footstep3, _footstep4
    );
    
    // Play a random footstep with variation
    var instance = SoundHelper.PlayFromGroup(
        "footsteps",
        volume: 0.6f,
        pan: 0f,
        pitch: 1f,
        category: SoundCategory.SFX,
        withVariation: true,
        pitchRange: 0.1f
    );
}

Weapon Sounds

public void PlayWeaponSound(Vect2 playerPos, Vect2 enemyPos)
{
    float pan = Math.Clamp((enemyPos.X - playerPos.X) / 500f, -1f, 1f);
    
    _weaponSound.PlayOneShot(
        volume: 0.9f,
        pan: pan,
        pitch: SoundHelper.RandomPitch(0.05f),
        category: SoundCategory.SFX
    );
}

Ambient Sounds Collection

private Sound[] _ambientSounds;

public void InitializeAmbientSounds()
{
    _ambientSounds = new[]
    {
        AssetManager.Instance.Load<Sound>("ambient/birds.ogg"),
        AssetManager.Instance.Load<Sound>("ambient/wind.ogg"),
        AssetManager.Instance.Load<Sound>("ambient/water.ogg")
    };
}

public void PlayRandomAmbient()
{
    // Play a random ambient sound
    var instance = _ambientSounds.PlayRandom(
        volume: 0.3f,
        pan: 0f,
        pitch: 1f
    );
    
    // Auto-dispose when done
    instance.SoundCompleted += (_, _) => instance.Dispose();
}

Fluent UI Sounds

public void OnButtonHover()
{
    _buttonHoverSound.CreateInstance()
        .WithVolume(0.5f)
        .WithPitch(SoundHelper.RandomPitch(0.05f))
        .Play();
}

public void OnButtonClick()
{
    _buttonClickSound.CreateInstance()
        .WithVolume(0.7f)
        .PlayWith(0.7f, 0f, 1f);
}

---

Summary

Method	Description
PlayOneShot	Plays a sound as a one-shot instance
PlayAndForget	Plays and auto-disposes when done
PlayWithPitchVariation	Plays with random pitch variation
WithVolume	Sets the volume (fluent)
WithPan	Sets the pan (fluent)
WithPitch	Sets the pitch (fluent)
WithLooping	Sets looping (fluent)
PlayWith	Sets volume, pan, pitch and plays
StopAndDispose	Stops and disposes an instance
PlayAll	Plays all sounds in a collection
PlayAllAndForget	Plays all and auto-disposes
PlayRandom	Plays a random sound from a collection
PlayRandomWithVariation	Plays random with pitch variation
PlayRandomAndForget	Plays random and auto-disposes
PlayRandomWithVariationAndForget	Plays random with variation and auto-disposes

---

Back to Home