Subtitles

The subtitles object can be used to display subtitles, generally during a fullscreen cinematic of some kind where the cinematic bars are visible. The most common usage of this object is to display subtitles over the bottom cinematic bar during cindy scenes at the start of (or during) battle.

Once created, the subtitles object may be started with subtitles:begin and text may then be displayed with subtitles:set_text. Displayed text may subsequently be hidden with subtitles:clear. This is the (strongly) recommended method for using this object.

Alternatively, subtitles can be pushed onto the object with timings, prior to subtitles:begin being called, with subtitles:push_back_subtitle. Lastly, a subtitle file with built-in timings may be loaded with subtitles:read_subtitles_file.

Loaded in Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
Back to top

Creation

A subtitles object can be retrieved from a battle object by calling battle:subtitles. If the subtitles object is intended to be used to show subtitles during a cutscene, it should be noted that cutscene objects created from the script library interface already create a subtitles object which can be retrieved with cutscene:subtitles. The cutscene library also calls subtitles:begin and sets the positioning of the subtitles to be "bottom-centre".

Back to top

Usage

Once a handle to an subtitles 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 s = bm:subtitles()
s:clear()            -- calling a function on the object once created
Back to top

Audio

Displaying a subtitle does not intrinsically play any audio. Voiceover audio, if desired, must be played separately using battle_sound_effect objects.

Back to top

Alignments

The subtitles object must be aligned on-screen before any subtitles can be displayed. Valid alignment keys are as follows:

  • "top_left"

  • "top_right"

  • "top_centre"

  • "mid_left"

  • "mid_right"

  • "mid_centre"

  • "bottom_left"

  • "bottom_right"

  • "bottom_centre"

Alignment keys are used when calling subtitles:begin and subtitles:set_alignment.

Back to top

Main Methods

subtitles:begin(string alignment)

Starts the subtitles object with an alignment - this must be called before any subtitles are set with subtitles:set_text. Alternatively, if a subtitle sequence has been preloaded then that sequence is started.

Parameters:

1

string

Subtitles alignment on-screen. Valid alignment keys can be found in the Alignments section of this documentation.

Returns:

  1. nil

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

subtitles:set_text(string subtitle key)

Instructs the subtitle object to display some subtitle text on-screen, which can subsequently be hidden with subtitles:clear.

Parameters:

1

string

Subtitles key to display, corresponding to a record from the scripted_subtitles table.

Returns:

  1. nil

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

subtitles:end_subtitles()
Stops the currently active sequence. After calling this function no subtitles will be shown until subtitles:begin is called.

Returns:

  1. nil

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

subtitles:clear()
Clears any subtitles currently being displayed or queued to be displayed. This can be used to remove subtitles displayed with subtitles:set_text, or clearing/halting a subtitle sequence that was preloaded.

Returns:

  1. nil

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

subtitles:set_alignment(string alignment )

Sets the on-screen alignment of displayed subtitles. Valid alignment keys can be found in the Alignments section of this documentation.

Parameters:

1

string

alignment

Returns:

  1. nil

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

Back to top

Preloading Subtitles

subtitles:read_subtitles_file(string file path)

Loads a csv file containing subtitle information. This is an old method of loading subtitles from a file.

Parameters:

1

string

file path

Returns:

  1. nil

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

subtitles:push_back_subtitle_entry(number start time, number end time, string text)

Pushes a subtitle entry with timings to be displayed when subtitles:begin is called. The subtitle entries are pushed as plain text, meaning no localisation lookup is performed. Therefore, this function should not be called outside of development.

Parameters:

1

number

Start time in ms after subtitles:begin is called.

2

number

End time in ms after subtitles:begin is called.

3

string

Unlocalised text to display.

Returns:

  1. nil

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

subtitles:push_back_subtitle(number start time, number end time, string subtitle key)

Pushes a subtitle entry with timings to be displayed when subtitles:begin is called. The subtitle entries pushed should be keys for records in the scripted_subtitles table.

Parameters:

1

number

Start time in ms after subtitles:begin is called.

2

number

End time in ms after subtitles:begin is called.

3

string

Subtitles key to display.

Returns:

  1. nil

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

Back to top

Borders

subtitles:change_if_borders_drawn(boolean draw borders)

By default, a thin black horizontal border is drawn behind a subtitle when it is displayed. This function may be called to disable or re-enable this behaviour.

Parameters:

1

boolean

draw borders

Returns:

  1. nil

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

subtitles:change_if_top_border_drawn(boolean draw top border)

Enables or disables the display of a second thin black border at the top of the screen when subtitles are displayed. This may be useful if subtitles are being displayed at the bottom (which they generally are), without cinematic borders (which is rare, but possible), and it's desired to have a matching black border at the top of the screen. This behaviour is disabled by default - use this function to enable it.

Parameters:

1

boolean

draw top border

Returns:

  1. nil

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

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