Sound Effects
The sound effect interface allows scripts to play a sound at either a 3D position in the world or at no position (in which case the sound appears to come from the camera e.g. narrated voiceover). A sound effect object is created by calling sound_effect:new, then associated with a sound event (sound file) with sound_effect:load, and then played at a specified battle_vector position in the world with sound_effect:play3D. Each battle_sound_effect object represents an individual sound effect.
Some functions exist in the script library that provide shorthand creation and playing of sound effects. See the functions listed in the Sound section of the script library documentation. It may be preferable to use those functions that the functions listed below.
| Loaded in Campaign |
|
| Loaded in Battle |
|
| Loaded in Frontend |
|
-
sound_effect:new() -
Creates a new
battle_sound_effectobject.Returns:
battle_sound_effect
Once a handle to a sound effect object is obtained, functions may be called on it to query or modify its state in the following form.
Example - Specification:
<object_name>:<function_name>(<args>)
Example - Creation and Usage:
local sfx_01 = battle_sound_effect:new()
sfx_01:load("test_sound_event") -- calling a function on the object once created
-
sound_effect:load(sound event namestring) -
Associates a specified sound event with this
battle_sound_effectobject. Sound events are created in the sound system editor - see the audio team for more information.Parameters:
1
sound event name
Returns:
nil
-
sound_effect:set_cinematic() -
Sets this object as a cinematic only sound event
Returns:
nil
-
sound_effect:set_vo() -
Sets this object as a VO sound
Returns:
nil
-
sound_effect:play3D([positionbattle_vector]) -
Instructs the sound effect to play. A sound event must have previously been loaded with
sound_effect:load.Parameters:
1
optional, default value=
nilPosition at which to play the sound in the world. If no position is supplied the sound will not appear from a position but will play from behind the camera (which is useful for narration).
Returns:
nil
-
sound_effect:playVO(unitbattle_unit) -
Instructs the sound effect to play as unit voiceover, coming from the position of the unit.
Parameters:
1
unit
Returns:
nil
-
sound_effect:stop() -
Stops the sound effect if it's currently playing.
Returns:
nil
-
sound_effect:is_playing() -
Returns whether the sound effect is currently playing or not.
Returns:
boolean
-
sound_effect:is_valid() -
Returns whether the sound effect is currently valid. An invalid sound effect is one that hasn't had a valid sound event associated with it with
sound_effect:load.Returns:
boolean