audio_play_sound_ext

This function plays any sound asset in your game using any combination of parameters.

NOTE An Audio Playback Ended event is triggered for the sound when it stops playing.

The function takes its parameters as a struct. Depending on the parameters that you provide, the function behaves like audio_play_sound, audio_play_sound_at or audio_play_sound_on. The only key that is strictly required in the struct is the sound key.

The full list of keys is as follows:

sound (Sound Asset or Audio Queue ID, required)
priority (Real, optional), defaults to 0
loop (Boolean, optional), defaults to false
gain (Real, optional), defaults to 1.0
offset (Real, optional), defaults to the asset-level offset
pitch (Real, optional), defaults to 1.0
listener_mask (Real, optional), defaults to the emitter-level listener mask/global listener mask
emitter (Audio Emitter ID, optional), defaults to undefined
position (Struct, optional), defaults to undefined
- x (Real)
- y (Real)
- z (Real)
- falloff_ref (Real)
- falloff_max (Real)
- falloff_factor (Real)

Syntax:

audio_play_sound_ext(params);

Argument	Type	Description
params	Struct	A struct containing the key-value pairs for each of the parameters that you want to set. The sound key is required and takes a Sound Asset as a value.

Returns:

Sound Instance ID

Example 1: Playing a basic sound (similar to audio_play_sound)

audio_play_sound_ext({ sound: snd_ambience });

The above code plays a sound "snd_ambience". The sound instance gets a default priority of 0 and won't be looped. All other sound properties are default as they haven't been provided in the struct.

Example 2: Playing a sound on an emitter (similar to audio_play_sound_on)

var _sound_params =
{
sound: snd_shot,
priority: 20,
gain: 1.2,
pitch: 2,
emitter: em_north_entrance
};
audio_play_sound_ext(_sound_params);

The above code first creates a temporary struct _sound_params. It stores the settings to play a sound "snd_shot" with a priority of 20, a gain of 1.2 and a pitch of 2 on an existing emitter em_north_entrance. It then plays the sound with those settings using audio_play_sound_ext.

Example 3: Playing a sound at a given position in 3D audio space (similar to audio_play_sound_at)

var _sound_params =
{
sound: snd_shot,
pitch: 1.1,
position:
{
x: 100,
y: 100,
z: 20
}
};
audio_play_sound_ext(_sound_params);