Skip to content

Audio

Jump to bottom
Xander Grabowski edited this page Jun 18, 2025 · 4 revisions

FieldDay.Audio

Last Updated June 18 2025

This informal implementation guide is a work in progress for engineers to use the FDL Core SFX/Audio Manager framework. Much of the audio system is modeled after Wwise.

Table of Contents

Basic Usage

The audio system is stored in the FieldDay.Audio namespace. You'll need to add the statement using FieldDay.Audio; to the top of any scripts using it.

Sfx

This is the public API class of the audio system. This class provides a comprehensive set of methods for playing, stopping, querying, and modifying audio clips, sources, and mix states. The class is designed to be used throughout the game to trigger and control sound effects in a flexible and centralized manner. Queues up audio playback commands, which the system batches to play at a later time. change playing events or set mix states.

Example Usage:

// Play a sound effect by event ID
Sfx.Play(EventIds.MySound);

// Play a sound effect at a specific transform with custom arguments
Sfx.Play(EventIds.MySound, myTransform, new SfxPlayArgs { Volume = 0.5f, Pitch = 1.2f });

// Stop a sound effect immediately
Sfx.Stop(myAudioHandle);

// Stop a sound effect with a fade-out
Sfx.Stop(myAudioHandle, 0.5f);

// Stop all sounds with a specific tag
Sfx.StopAllWithTag(EventIds.MyTag);

// Set the volume of a specific sound
Sfx.SetVolume(myAudioHandle, 0.5f, 0.2f);

// Pause a sound
Sfx.SetPaused(myAudioHandle, true);

// Seek to 2 seconds into the sound
Sfx.Seek(myAudioHandle, 2.0f);

Supporting Types

SfxPlayArgs Struct A struct used to pass optional playback arguments:

  • Volume: Playback volume.
  • Pitch: Playback pitch.
  • Delay: Delay before playback starts.
  • Pan: Stereo pan.

Voice

An instantiated version of an AudioEvent which contains a reference to a Handle and an AudioSource.

AudioHandle

Unique ID instance to a playing instance of an AudioEvent - i.e. a Voice. Assigned when the AudioEvent is played, and used to access it later. Can be tagged for easy access/control.

  • PlayDetached plays an SFX from a position, not following the transform if it moves.
  • PlayFrom interfaces with a default Unity AudioSource.
    • The audio system ensures that an AudioHandle is created, and automatically stops anything playing from that AudioSource.
  • WasAudible determines if an AudioHandle was audible (not paused, volume above zero, etc) last frame.
  • Seek, Mute, Pause, Stop etc. find a given Audio Handle and target
  • SetMixState manually activates a given MixState, accessed with a mixStateId stored in an AssetPack.
    • SetMixStateEnabled sets the MixState instantly to 1 or 0, using the default envelope defined in the MixState.
    • SetMixStateTarget interpolates to a given value using the default envelope defined in the MixState.

AudioEvent

Binding between a name and a set of playback samples. Collects multiple samples (sound files) with a list of playback parameters. These each have a “base” and a min/max modifier for randomization. Often preloaded at the load time.

  • Randomize Start Time useful for loops that will be stopping and starting - so that it’s not obvious.

AudioBus

Groups under which audio plays. For example, “Ambience,” and “VO.” Each Audio Bus connects back to a Master Bus through parents. Hierarchical

Buses must be created & loaded upfront. They cannot be added and removed during runtime.

[master] Bus

Ducking Mixes specify an Audio Mix State to activate when any audio events play through this bus.

AudioEmitterProfile

Determine how an Audio Event plays out spatially. The current implemented Modes are:

  • 3D/World
    • Spatial sounds, located in worldspace. Includes rolloff with
  • Fixed
    • Non-spatial, play at the same level regardless of listener position.

Effects

  • Doppler, Reverb Zones

Note: A default Emitter can be created for simple audio events

AudioMixState

Captures a certain set of parameter modifications to apply to buses. For example, a “VO Duck” Audio Mix State can change the volume, pitch, and filter of different audio states when activated.

Envelopes determine the transition between mix states.

Audio Mix States can be activated by Ducking Mixes on an Audio Bus. Whenever any events play through the bus or its children, the Audio Mix State is activated.

ECS Components

SfxLoop

Plays a looped AudioEvent.

SfxNode

Plays a given AudioEvent from the given Transform position, including some config parameters. Track Position

ScriptSfxNode

Using the Field Day Audio Library

Soundscapes

Soundscapes are not included in FDL Core, but they are a useful inclusion for any given game. A Soundscape unites multiple loops and oneshots to create a group of sounds.

Soundscapes should give each instance of an AudioEvent that they play (i.e. a Voice, accessed by an AudioHandle) a unique tag, so they can be accessed as a group later on.

Debug Menu

Found under Engine -> Audio

image

Includes options to:

  • Display Voices - Shows the voice's AudioClip name. “L” at the end indicates that the audio is looping.
  • Display Buses
  • Display Mixes

Clone this wiki locally