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 Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
Back to top

Creation

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 2219

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

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 2237

sound_effect:play3D([battle_vector position])

Instructs the sound effect to play. A sound event must have previously been loaded with 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 2267

sound_effect:playVO(battle_unit unit)

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

Parameters:

1

battle_unit

unit

Returns:

  1. nil

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

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

Returns:

  1. nil

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

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 2320

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:

  1. boolean is valid

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

Last updated 12/08/2022 11:56:59