Detailed Description

The PowerQuest Audio System. Provides convenient, 2d specific audio functionality, using audio cues.

Functions are accessable from Quest Scripts using 'Audio.' From other scripts, use the static functions from 'SystemAudio.'

Features:

This is an audio cue based system. You create an AudioCue in your project, set up which clips it plays and data like volume, pitch, etc. Then you play that "Cue".
Cues can be added to SystemAudio so that you can play them by name. Then it's as simple as calling Audio.Play("gunshot");
Cues have a lot of controls for randomisation so common sounds don't get repetive: set min/max pitch, a list of clips to randomly choose from, and even string multiple cues together with random delays
Type based volume control: Flag cues with a type (eg SoundEffect, Music, Dialog), and then set those volumes seperately
Simple functions for playing music and an ambient loop and crossfading between them
Stop/Pause/Modify volume/pitch/pan, etc of currently playing sounds by their cue name, or the AudioHandle returned from the Play Function. eg: Audio.GetHandle("gunshot").pitch = 0.5f, Audio.Stop("gunshot");
Ducking of music when playing dialog
Simple 2d falloff and stereo control: Some basic controls set how sounds get quieter, and move left/right based on their position relative to the camera
Automatic pooling system for efficiency
Save/Restore audio state

Inherits SingletonAuto< SystemAudio >.

Inherited by Audio.

Properties
static AudioHandle	MusicHandle `[get]`

static float	FalloffDistanceMultiplier `[get, set]`
	A multiplier on the falloff distance for volume/panning. Useful when you want to bring it in close, or expand it outwards temporarily. More...

static bool	ShouldRestartMusicIfAlreadyPlaying `[get]`
	Flag to set whether playing the same music cue again will restart it, or leave the old one playing. More...

AudioMixerGroup	NarratorMixerGroup `[get]`

Static Public Member Functions
static void	SetVolume (AudioCue.eAudioType type, float volume)
	Sets the volume (from 0.0 to 1.0) for audio of a particular type (eg: Sound effects, Music, Dialog) More...

static float	GetVolume (AudioCue.eAudioType type)
	Retrieves the volume for audio of a particular type (eg: Sound effects, Music, Dialog) More...

static AudioCue	GetCue (string cueName)
	Retrieves a sound cue by name. More...

static bool	IsPlaying (string cueName)
	Returns true if the cue is currently playing, otherwise false. More...

static AudioHandle	Play (string cueName, Transform emmitter=null)
	Play a cue by name. This is the main way to play sounds. If emmitter is set, the sound will falloff/pan as it goes off camera. More...

static AudioHandle	Play (AudioCue cue, Transform emitter=null, float volumeMult=1, float pitchMult=1, float fromTime=0, float withStartDelay=0)
	Play the specified cue with extended options. If emmitter is set, the sound will falloff/pan as it goes off camera. Can also set volume and pitch overrides, and override the start time of the cue. More...

static AudioHandle	Play (AudioCue cue, ref List< AudioHandle > handles, Transform emmitter=null, float volumeMult=1, float pitchMult=1, float fromTime=0, float withStartDelay=0)
	Advanced Play function with extended options, and returning a list of all handles started (for when multiple are started). If emmitter is set, the sound will falloff/pan as it goes off camera. Can also set volume and pitch overrides, and override the start time of the cue. More...

static AudioHandle	Play (AudioClip clip, int type=(int) AudioCue.eAudioType.Sound, Transform emmitter=null, float volume=1, float pitch=1, bool loop=false, AudioMixerGroup mixerGroup=null)
	Plays a specific audio clip rather than an audio cue. More...

static void	Pause (AudioHandle handle)
	Pauses the specified sound by it's handle. More...

static void	UnPause (AudioHandle handle)
	Resumes the specified sound by it's handle. More...

static void	Pause (string cueName)
	Pauses the specified sound by it's cue name. More...

static void	UnPause (string cueName)
	Resumes the specified sound by it's cue name. More...

static AudioHandle	GetHandle (string cueName)
	Gets a playing AudioHandle by its cue name. More...

static AudioHandle[]	GetHandles (string cueName)
	Gets any currently playing AudioHandles by their cue name. More...

static void	Stop (string cueName, float overTime=0)
	Stops the specified sound by it's cue name. More...

static void	Stop (AudioHandle handle, float overTime=0, float afterDelay=0)
	Stops the specified sound by it's handle. More...

static AudioHandle	PlayMusic (string cueName, float fadeTime=0)
	Play a music track using the cue name, with optional crossfade time. More...

static AudioHandle	PlayMusic (string cueName, float fadeOutTime, float fadeInTime)
	Play a music track using the cue name, with seperate fade out and fade in times. More...

static AudioHandle	PlayMusic (AudioCue cue, float fadeTime=0)
	Play a music cue, with optional crossfade time. More...

static AudioHandle	PlayMusic (AudioCue cue, float fadeOutTime, float fadeInTime)
	Play a music cue, with seperate fade out and fade in times. More...

static AudioSource	PlayMusicSynced (string name, float fadeTime, float volumeOverride=0)
	Play a music track using the cue name, Crossfades beteween two music tracks, attempting to keep them synced (assumes identical length/tempo/etc). Optional volume multiplier. More...

static AudioSource	PlayMusicSynced (AudioCue cue, float fadeTime, float volumeOverride=0)
	Crossfades beteween two music tracks, attempting to keep them synced (assumes identical length/tempo/etc). Optional volume multiplier. More...

static void	StopMusic (float fadeTime=0, float afterDelay=0)
	Stops the currently playing music, with optional fade out time. More...

static void	PlayAmbientSound (string name, float fadeTime=0.4f)
	Plays an ambient sound by it's cue name, with optional fade time. Sound cue is assumed to be looping. More...

static void	PlayAmbientSound (string name, float fadeoutTime, float fadeInTime)
	Plays an ambient sound by it's cue name, with seperate fade out and fade in times. Sound cue is assumed to be looping. More...

static void	StopAmbientSound (float overTime=0.4f)
	Stops the current ambient sound cue, with optional fade time. More...

static void	UpdateCustomFalloff (string cueName, Vector2 soundPos, Vector2 listenerPos, float closeDist, float farDist, float farVol=0, float closeVol=1, float farPan=0.7f)
	Sets a sound's volume and stereo pan based on distance to it. Use this function when you want sounds to be louder when standing near them, and quieter as you walk away. The function should be placed in your room's Update() function. eg. ~~~ void Update() More...

static float	ToDecibel (float linear)

static float	FromDecibel (float dB)

Public Member Functions
float	GetVolume (AudioHandle source)
	Gets the base volume of a particular sound effect (usually use the AudioHandle for this) More...

void	SetVolume (AudioHandle source, float volume)
	Sets the base volume of a particular sound effect (usually use the AudioHandle for this) More...

float	GetPan (AudioHandle source)
	Gets the base pan of a particular sound effect (usually use the AudioHandle for this) More...

void	SetPan (AudioHandle source, float pan)
	Sets the base pan of a particular sound effect (usually use the AudioHandle for this) More...

bool	StopHandleInternal (AudioHandle handle, float overTime=0, float afterDelay=0)

bool	GetAnyMusicPlaying ()

float	GetCueVolume (AudioCue cue, AudioClip specificClip=null)
	Advanced function to retrieve a cue's default volume. More...

void	PauseAllSounds (bool alsoPauseMusic=false)
	Advanced function that pauses all sounds (used when pausing game) More...

void	ResumeAllSounds ()
	Advanced function that resumes all paused sounds (used when pausing game) More...

AudioHandle	GetActiveMusicHandle ()
	Advanced function for retrieving the active music handle. More...

bool	GetIsActiveMusic (AudioCue cue)
	Advanced function returns true if the passed cue is the active music. More...

bool	EditorAddCue (AudioCue cue)
	Editor function for adding an audio cue to the list of cues playable by name. Primarily used by editor. Returns true if added, false if it already existed. More...

List< AudioCue >	EditorGetAudioCues ()
	Editor function for retrieving all audio cues. More...

bool	EditorGetAutoAddCues ()
	If set, any cues in the Audio folder will be automatically added (you don't have to click the button in the cue) More...

void	StartFadeIn (AudioHandle handle, float time)
	Starts fading in a handle. In powerquest it's usually more convenient to use `Audio.Play("MySound").FadeIn(overTime);` More...

void	StartFadeOut (AudioHandle handle, float time, bool stopOnFinish=false)
	Starts fading out a handle, optionally stopping it once faded out. In powerquest it's usually more convenient to use `Audio.Stop("MySound", overTime);. More...

void	StartFade (AudioHandle handle, float targetVolume, float time, bool stopOnFinish=false)
	Starts fading a handle to the target volume, optionally stopping it once finished. In powerquest it's usually more convenient to use `Audio.GetCue("MySound").Fade(targetVolume, overTime);` More...

Property Documentation

◆ FalloffDistanceMultiplier

float FalloffDistanceMultiplier

staticgetset

A multiplier on the falloff distance for volume/panning. Useful when you want to bring it in close, or expand it outwards temporarily.

◆ ShouldRestartMusicIfAlreadyPlaying

bool ShouldRestartMusicIfAlreadyPlaying

staticget

Flag to set whether playing the same music cue again will restart it, or leave the old one playing.

Member Function Documentation

◆ SetVolume() [1/2]

static void SetVolume	(	AudioCue.eAudioType	type,
		float	volume
	)

inlinestatic

Sets the volume (from 0.0 to 1.0) for audio of a particular type (eg: Sound effects, Music, Dialog)

◆ GetVolume() [1/2]

static float GetVolume ( AudioCue.eAudioType type )

inlinestatic

Retrieves the volume for audio of a particular type (eg: Sound effects, Music, Dialog)

◆ GetVolume() [2/2]

float GetVolume ( AudioHandle source )

inline

Gets the base volume of a particular sound effect (usually use the AudioHandle for this)

◆ SetVolume() [2/2]

void SetVolume	(	AudioHandle	source,
		float	volume
	)

inline

Sets the base volume of a particular sound effect (usually use the AudioHandle for this)

◆ GetPan()

float GetPan ( AudioHandle source )

inline

Gets the base pan of a particular sound effect (usually use the AudioHandle for this)

◆ SetPan()

void SetPan	(	AudioHandle	source,
		float	pan
	)

inline

Sets the base pan of a particular sound effect (usually use the AudioHandle for this)

◆ GetCue()

static AudioCue GetCue ( string cueName )

inlinestatic

Retrieves a sound cue by name.

◆ IsPlaying()

static bool IsPlaying ( string cueName )

inlinestatic

Returns true if the cue is currently playing, otherwise false.

◆ Play() [1/4]

static AudioHandle Play	(	string	cueName,
		Transform	emmitter = `null`
	)

inlinestatic

Play a cue by name. This is the main way to play sounds. If emmitter is set, the sound will falloff/pan as it goes off camera.

Eg: Audio.Play("DoorKnock"); Eg: Audio.Play("Gunshot", C.Gunman.Instance);

◆ Play() [2/4]

static AudioHandle Play	(	AudioCue	cue,
		Transform	emitter = `null`,
		float	volumeMult = `1`,
		float	pitchMult = `1`,
		float	fromTime = `0`,
		float	withStartDelay = `0`
	)

inlinestatic

Play the specified cue with extended options. If emmitter is set, the sound will falloff/pan as it goes off camera. Can also set volume and pitch overrides, and override the start time of the cue.

◆ Play() [3/4]

static AudioHandle Play	(	AudioCue	cue,
		ref List< AudioHandle >	handles,
		Transform	emmitter = `null`,
		float	volumeMult = `1`,
		float	pitchMult = `1`,
		float	fromTime = `0`,
		float	withStartDelay = `0`
	)

inlinestatic

Advanced Play function with extended options, and returning a list of all handles started (for when multiple are started). If emmitter is set, the sound will falloff/pan as it goes off camera. Can also set volume and pitch overrides, and override the start time of the cue.

◆ Play() [4/4]

static AudioHandle Play	(	AudioClip	clip,
		int	type = `(int)AudioCue.eAudioType.Sound`,
		Transform	emmitter = `null`,
		float	volume = `1`,
		float	pitch = `1`,
		bool	loop = `false`,
		AudioMixerGroup	mixerGroup = `null`
	)

inlinestatic

Plays a specific audio clip rather than an audio cue.

◆ Pause() [1/2]

static void Pause ( AudioHandle handle )

inlinestatic

Pauses the specified sound by it's handle.

◆ UnPause() [1/2]

static void UnPause ( AudioHandle handle )

inlinestatic

Resumes the specified sound by it's handle.

◆ Pause() [2/2]

static void Pause ( string cueName )

inlinestatic

Pauses the specified sound by it's cue name.

◆ UnPause() [2/2]

static void UnPause ( string cueName )

inlinestatic

Resumes the specified sound by it's cue name.

◆ GetHandle()

static AudioHandle GetHandle ( string cueName )

inlinestatic

Gets a playing AudioHandle by its cue name.

◆ GetHandles()

static AudioHandle[] GetHandles ( string cueName )

inlinestatic

Gets any currently playing AudioHandles by their cue name.

◆ Stop() [1/2]

static void Stop	(	string	cueName,
		float	overTime = `0`
	)

inlinestatic

Stops the specified sound by it's cue name.

◆ Stop() [2/2]

static void Stop	(	AudioHandle	handle,
		float	overTime = `0`,
		float	afterDelay = `0`
	)

inlinestatic

Stops the specified sound by it's handle.

◆ PlayMusic() [1/4]

static AudioHandle PlayMusic	(	string	cueName,
		float	fadeTime = `0`
	)

inlinestatic

Play a music track using the cue name, with optional crossfade time.

◆ PlayMusic() [2/4]

static AudioHandle PlayMusic	(	string	cueName,
		float	fadeOutTime,
		float	fadeInTime
	)

inlinestatic

Play a music track using the cue name, with seperate fade out and fade in times.

◆ PlayMusic() [3/4]

static AudioHandle PlayMusic	(	AudioCue	cue,
		float	fadeTime = `0`
	)

inlinestatic

Play a music cue, with optional crossfade time.

◆ PlayMusic() [4/4]

static AudioHandle PlayMusic	(	AudioCue	cue,
		float	fadeOutTime,
		float	fadeInTime
	)

inlinestatic

Play a music cue, with seperate fade out and fade in times.

◆ PlayMusicSynced() [1/2]

static AudioSource PlayMusicSynced	(	string	name,
		float	fadeTime,
		float	volumeOverride = `0`
	)

inlinestatic

Play a music track using the cue name, Crossfades beteween two music tracks, attempting to keep them synced (assumes identical length/tempo/etc). Optional volume multiplier.

◆ PlayMusicSynced() [2/2]

static AudioSource PlayMusicSynced	(	AudioCue	cue,
		float	fadeTime,
		float	volumeOverride = `0`
	)

inlinestatic

Crossfades beteween two music tracks, attempting to keep them synced (assumes identical length/tempo/etc). Optional volume multiplier.

◆ StopMusic()

static void StopMusic	(	float	fadeTime = `0`,
		float	afterDelay = `0`
	)

inlinestatic

Stops the currently playing music, with optional fade out time.

◆ PlayAmbientSound() [1/2]

static void PlayAmbientSound	(	string	name,
		float	fadeTime = `0.4f`
	)

inlinestatic

Plays an ambient sound by it's cue name, with optional fade time. Sound cue is assumed to be looping.

◆ PlayAmbientSound() [2/2]

static void PlayAmbientSound	(	string	name,
		float	fadeoutTime,
		float	fadeInTime
	)

inlinestatic

Plays an ambient sound by it's cue name, with seperate fade out and fade in times. Sound cue is assumed to be looping.

◆ StopAmbientSound()

static void StopAmbientSound ( float overTime = 0.4f )

inlinestatic

Stops the current ambient sound cue, with optional fade time.

◆ UpdateCustomFalloff()

static void UpdateCustomFalloff	(	string	cueName,
		Vector2	soundPos,
		Vector2	listenerPos,
		float	closeDist,
		float	farDist,
		float	farVol = `0`,
		float	closeVol = `1`,
		float	farPan = `0.7f`
	)

inlinestatic

Sets a sound's volume and stereo pan based on distance to it. Use this function when you want sounds to be louder when standing near them, and quieter as you walk away. The function should be placed in your room's Update() function. eg. ~~~ void Update()

~~~

Parameters

cueName	Cue name to fade.
soundPos	The location of the sound. Eg: `P.Fireplace.LookAtPoint`.
listenerPos	The location of the listener (usually the player). Eg: `C.Player.Position`.
closeDist	How close should the player be to the sound for it to be at maxVol. In game units.
farDist	How far should the player be from the sound for it to be at minVol. In game units.
farVol	The volume when the player is standing FAR from the sound (eg. quiet). From 0 to 1.
closeVol	The volume when the player is standing CLOSE to the sound (eg. loud). From 0 to 1.
farPan	The maximum amount to pan in stereo, when the player is FAR from the sound. From 0 to 1.

◆ GetCueVolume()

float GetCueVolume	(	AudioCue	cue,
		AudioClip	specificClip = `null`
	)

inline

Advanced function to retrieve a cue's default volume.

◆ PauseAllSounds()

void PauseAllSounds ( bool alsoPauseMusic = false )

inline

Advanced function that pauses all sounds (used when pausing game)

◆ ResumeAllSounds()

void ResumeAllSounds ( )

inline

Advanced function that resumes all paused sounds (used when pausing game)

◆ GetActiveMusicHandle()

AudioHandle GetActiveMusicHandle ( )

inline

Advanced function for retrieving the active music handle.

◆ GetIsActiveMusic()

bool GetIsActiveMusic ( AudioCue cue )

inline

Advanced function returns true if the passed cue is the active music.

◆ EditorAddCue()

bool EditorAddCue ( AudioCue cue )

inline

Editor function for adding an audio cue to the list of cues playable by name. Primarily used by editor. Returns true if added, false if it already existed.

◆ EditorGetAudioCues()

List< AudioCue > EditorGetAudioCues ( )

inline

Editor function for retrieving all audio cues.

◆ EditorGetAutoAddCues()

bool EditorGetAutoAddCues ( )

inline

If set, any cues in the Audio folder will be automatically added (you don't have to click the button in the cue)

◆ StartFadeIn()

void StartFadeIn	(	AudioHandle	handle,
		float	time
	)

inline

Starts fading in a handle. In powerquest it's usually more convenient to use Audio.Play("MySound").FadeIn(overTime);

◆ StartFadeOut()

void StartFadeOut	(	AudioHandle	handle,
		float	time,
		bool	stopOnFinish = `false`
	)

inline

Starts fading out a handle, optionally stopping it once faded out. In powerquest it's usually more convenient to use `Audio.Stop("MySound", overTime);.

◆ StartFade()

void StartFade	(	AudioHandle	handle,
		float	targetVolume,
		float	time,
		bool	stopOnFinish = `false`
	)

inline

Starts fading a handle to the target volume, optionally stopping it once finished. In powerquest it's usually more convenient to use Audio.GetCue("MySound").Fade(targetVolume, overTime);

Detailed Description

Properties

Static Public Member Functions

Public Member Functions

Property Documentation

◆ FalloffDistanceMultiplier

◆ ShouldRestartMusicIfAlreadyPlaying

Member Function Documentation

◆ SetVolume() [1/2]

◆ GetVolume() [1/2]

◆ GetVolume() [2/2]

◆ SetVolume() [2/2]

◆ GetPan()

◆ SetPan()

◆ GetCue()

◆ IsPlaying()

◆ Play() [1/4]

◆ Play() [2/4]

◆ Play() [3/4]

◆ Play() [4/4]

◆ Pause() [1/2]

◆ UnPause() [1/2]

◆ Pause() [2/2]

◆ UnPause() [2/2]

◆ GetHandle()

◆ GetHandles()

◆ Stop() [1/2]

◆ Stop() [2/2]

◆ PlayMusic() [1/4]

◆ PlayMusic() [2/4]

◆ PlayMusic() [3/4]

◆ PlayMusic() [4/4]

◆ PlayMusicSynced() [1/2]

◆ PlayMusicSynced() [2/2]

◆ StopMusic()

◆ PlayAmbientSound() [1/2]

◆ PlayAmbientSound() [2/2]

◆ StopAmbientSound()

◆ UpdateCustomFalloff()

◆ GetCueVolume()

◆ PauseAllSounds()

◆ ResumeAllSounds()

◆ GetActiveMusicHandle()

◆ GetIsActiveMusic()

◆ EditorAddCue()

◆ EditorGetAudioCues()

◆ EditorGetAutoAddCues()

◆ StartFadeIn()

◆ StartFadeOut()

◆ StartFade()