This function plays any sound asset through an emitter, with any changes to the emitter's gain, position, pitch or velocity affecting how the user hears the final sound being played.
NOTE An Audio Playback Ended event is triggered for the sound when it stops playing.
You provide the emitter index to use, the Sound Asset to be played and then specify whether the sound is to loop or not. Next you can assign a priority, which is then used to determine how sounds are dealt with when the number of sounds playing is over the limit set by the function audio_channel_num(). Lower priority sounds will be stopped in favour of higher priority sounds, and the priority value can be any real number (the actual value is arbitrary, and can be from 0 to 1 or 0 to 100, as GameMaker will prioritise them the same). Note that when dealing with priority, the higher the number the higher the priority, such that a sound with priority 100 will be favoured over a sound with priority 1.
This function will also return a unique index for the sound being played, which can be stored in a variable so you can later pause it or stop it. This means that if you have multiple instances of the same sound playing at any one time, you can target just one instance of that sound using the audio functions.
There are four optional arguments that allow you to change the Audio Properties of the sound being played at the instance/voice level:
... [gain], [offset], [pitch], [listener_mask]
They are applied to the sound immediately. This fixes the issues you would face when calling a separate function to change any of these values, which could cause an undesired delay in the change.
These properties are multiplied by their corresponding value of the sound asset. See Audio Properties Overview for a full overview.
NOTE To change the value of any of these properties after playback of a sound has been started, see audio_sound_gain for gain, audio_sound_set_track_position for offset, audio_sound_pitch for pitch and audio_sound_set_listener_mask for listener mask.
audio_play_sound_on(emitter, sound, loop, priority, [gain], [offset], [pitch], [listener_mask]);
| Argument | Type | Description |
|---|---|---|
| emitter | Audio Emitter ID | The index of the emitter to use. |
| sound | Sound Asset | The index of the sound to use. |
| loop | Boolean | Flags the sound as looping or not. |
| priority | Real | Set the channel priority for the sound. |
| gain | Real | OPTIONAL The gain of the sound instance (defaults to 1). |
| offset | Real | OPTIONAL The time (in seconds) to start playing. Values beyond the end of the sound are clamped to its length. The default value is the asset-level offset, this value overrides it when provided. |
| pitch | Real | OPTIONAL The pitch multiplier (defaults to 1). |
| listener_mask | Real | OPTIONAL The bitmask data to set for the sound. On the HTML5 target this will have no effect as the target does not support more than one listener. |
if (global.SFX)
{
audio_play_sound_on(s_emit, snd_Explode, false, 1);
}
The above code checks the global variable "SFX" and if it returns true then the sound indexed in the variable "snd_Explode" will be played through the emitter indexed in the variable "s_emit" with a low priority and no looping.
if (hit == true)
{
audio_play_sound_on(s_emit, snd_Hit, false, 1, 1.3);
}
The above code checks if the instance executing the code was hit. If true it plays the sound "snd_Hit" through the emitter "s_emit" with a slightly higher gain of 1.3. The gain set here is multiplied by the emitter's gain to get the final gain at which the sound is played.