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 battle_sound_effect:new, then associated with a sound event (sound file) with battle_sound_effect:load, and then played at a specified battle_vector position in the world with battle_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 Battle loaded in battle
Back to top

Creation

battle_sound_effect:new()
Creates a new battle_sound_effect object.

Returns:

  1. battle_sound_effect blank sound effect

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1479

Back to top

Usage

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
Back to top

Methods

battle_sound_effect:load(string sound event name)

Associates a specified sound event with this battle_sound_effect object. Sound events are created in the sound system editor - see the audio team for more information.

Parameters:

1

string

sound event name

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1497

battle_sound_effect:play3D([battle_vector position])

Instructs the sound effect to play. A sound event must have previously been loaded with battle_sound_effect:load.

Parameters:

1

battle_vector

optional, default value=nil

Position 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:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1524

battle_sound_effect:playVO(unit unit)

Instructs the sound effect to play as unit voiceover, coming from the position of the unit.

Parameters:

1

unit

unit

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1544

battle_sound_effect:stop()
Stops the sound effect if it's currently playing.

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1564

battle_sound_effect:is_playing()
Returns whether the sound effect is currently playing or not.

Returns:

  1. boolean is playing

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1577

battle_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 battle_sound_effect:load.

Returns:

  1. boolean is valid

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1593

Last updated 25/08/2021 12:07:50