Battle Cutscenes

The battle cutscene library provides an interface for the relatively easy creation and setup of scripted cutscenes in battle. A cutscene object is first declared with cutscene:new, configured with the variety of configuration commands available, loaded with actions (things that happen within the cutscene) using repeated calls to cutscene:action, and finally started with cutscene:start to start the visual cutscene itself. Each battle cutscene object represents an individual cutscene.

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

Creation

cutscene:new(string name, object unit controller, [number duration], [function end callback])

Creates a cutscene object. A cutscene must be given a string name, an object granting control over the player's army (to allow it to be taken away during the cutscene), a length, and, optionally, a function to call when the cutscene finishes.

Parameters:

1

string

Name for cutscene.

2

object

Either a unitcontroller with control over the player's army, or a script_units collection containing all of the player's units.

3

number

optional, default value=nil

Cutscene duration in milliseconds. If nil or 0 is specified then the cutscene will be set to not end, and will only finish when skipped by the player or ended by an external process

4

function

optional, default value=nil

End callback. A callback is usually specified here, although not always.

Returns:

  1. cutscene cutscene object

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 105

cutscene:new_from_cindyscene(
  string name,
  object unit controller,
  [function end callback],
  string cindy scene,
  [number blend in],
  [number blend out]
)

Creates a cutscene object that is bound to a cindyscene. When started, the scripted cutscene will automatically start the cindyscene, and will terminate when the cindyscene ends.

Parameters:

1

string

Unique name for the cutscene.

2

object

Either a battle_unitcontroller with control over the player's army, or a script_units collection containing all of the player's units.

3

function

optional, default value=nil

End callback.

4

string

Cindy scene path.

5

number

optional, default value=0

Blend in time, in seconds.

6

number

optional, default value=10

Blend out time, in seconds.

Returns:

  1. cutscene cutscene object

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 161

Back to top

Debug

cutscene:set_debug([boolean set debug], [boolean Hide UI in debug mode.])
Sets the cutscene into debug mode for more output. Setting debug mode on a cutscene also allows the camera to be moved during cutscene playback, and keeps the UI visible.

Parameters:

1

boolean

optional, default value=true

Set cutscene into debug mode.

2

boolean

optional, default value=false

Hide UI in debug mode.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 229

cutscene:enable_debug_timestamps([boolean enable timestamps])
Instructs the cutscene to print a debug timestamp every model tick. This can be useful when trying to set up timings for cutscene events.

Parameters:

1

boolean

optional, default value=true

enable timestamps

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 244

Back to top

Cinematic Triggers

A cindy scene can be configured to send events to script, for which listeners may be established that call script functions. The function cutscene:add_cinematic_trigger_listener may be used to establish such a listener. This mechanism allows cinematic artists to more tightly control the timing of events in the cindy scene.

cutscene:add_cinematic_trigger_listener(string id, function callback)

Registers a new cinematic trigger listener. When the cindy scene triggers a script event with the supplied id in script, the supplied function is called.

Parameters:

1

string

Cinematic trigger id. This should match the an id of a cinematic event triggered from a cindy scene played during this cutscene.

2

function

Callback to call.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 268

Back to top

Enqueuing Actions

By adding actions to a cutscene it is instructed to perform operations at certain times after the cutscene is started. It is through cutscene actions that the narrative events in the cutscene are brought into being.

cutscene:action(function action callback, number action time, [boolean is terminator])

Adds an action to the cutscene. Specify a function callback to be called, and a time after the start of the cutscene to call it in ms. If relative mode has been set with cutscene:set_relative_mode then the specified time should instead be relative to the previously-enqueued action.

Parameters:

1

function

Action callback.

2

number

Action time in ms. This can be 0, but cannot be greater than the length of the cutscene.

3

boolean

optional, default value=true

If true, no actions will be called after this one.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 301

Back to top

Playing/Waiting for Sounds

cutscene:play_sound(battle_sound_effect sound)
Instructs the cutscene to play a sound. This sound is registered to the cutscene, so that it can query its status later and also stop it if the cutscene is skipped.

Parameters:

1

battle_sound_effect

sound

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 372

cutscene:play_vo(battle_sound_effect sound, script_unit target sunit)
Instructs the cutscene to play a sound at a specified script_unit in 3D space. This sound is registered to the cutscene, so that it can query its status later and also stop it if the cutscene is skipped.

Parameters:

1

battle_sound_effect

sound

2

script_unit

target sunit

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 387

cutscene:wait_for_advisor()
Instructs a running cutscene to stall its progress until the advisor has finished speaking. This is designed to be called during a cutscene action to prevent one item of advice from colliding with another piece of advice, sound, or other event that it shouldn't overlap with. Since the length of an item of advice varies from language to language, it's sensible to insert wait_for_advisor calls into a cutscene script before starting subsequent advice.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 404

cutscene:wait_for_vo()
Instructs a running cutscene to stall its progress until any sounds started with cutscene:play_sound or cutscene:play_vo have finished. This is designed to be called during a cutscene action to prevent one sound from colliding with another sound or event that it shouldn't overlap with. Since the length of a localised sound varies from language to language, it's sensible to insert wait_for_vo calls into a cutscene script before starting subsequent sounds.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 411

Back to top

Querying

cutscene:subtitles()
Returns a subtitles object stored internally by the cutscene.

Returns:

  1. subtitles

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 430

cutscene:camera()
Returns a camera object stored internally by the cutscene.

Returns:

  1. camera

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 438

cutscene:length()
Returns the cutscene length in ms

Returns:

  1. number length in ms

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 446

cutscene:is_playing_sound()
Returns true if any of the sounds the cutscene has been told to play with cutscene:play_sound or cutscene:play_vo are still playing, false otherwise.

Returns:

  1. boolean is playing sound

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 454

cutscene:is_playing_camera()
Returns true if a scripted camera movement is currently happening, false otherwise.

Returns:

  1. boolean camera moving

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 470

cutscene:is_any_cutscene_running()
Returns true if this or any other scripted cutscene is currently running, false otherwise.

Returns:

  1. boolean any cutscene running

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 478

cutscene:is_active()
Returns true if this cutscene is currently running, false otherwise.

Returns:

  1. boolean this cutscene running

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 486

Back to top

Skipping Parameters

cutscene:set_skippable(boolean skippable, [function skip callback])
Sets the cutscene to be skippable, and optionally also sets a function to be called when the player skips the cutscene.

Parameters:

1

boolean

2

function

optional, default value=nil

skip callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 507

cutscene:set_skip_camera(vector camera position, vector camera target)
Sets a position/target to immediately reposition the camera at if the cutscene is skipped. This supercedes any Restore Camera if set.

Parameters:

1

vector

camera position

2

vector

camera target

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 526

Back to top

Restore Camera

cutscene:set_restore_cam(number move time, [vector override position], [vector override target])
Instructs the cutscene to restore the camera to either the position it occupied when the cutscene started, or a different position/target entirely. Note that if a skip camera/target has been set with cutscene:set_skip_camera and the cutscene is skipped, those positions will supercede these.

Parameters:

1

number

Time over which to restore the camera in ms. Setting 0 would result in the camera cutting, setting 1000 would result in the camera panning over 1 second, and so on.

2

vector

optional, default value=nil

Override camera position. Supply a position here to set a specific restore camera position, or leave blank to use the position of the camera at the start of the cutscene.

3

vector

optional, default value=nil

Override camera target. Must be specified if a camera position is specified.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 566

Back to top

Post Cutscene Fade Time

The post-cutscene fade time instructs the cutscene to fade the camera from black to picture after it ends or is skipped. This is used to achieve a smooth transition back to picture if the cutscene faded to black as it ended.

cutscene:set_post_cutscene_fade_time(number duration, [number duration])
Sets a duration for the post-cutscene fade time, in seconds.
If a negative fade time is specified, then the cutscene will fade to black when it ends/is skipped and will never fade back to picture. This is useful for outro cutscenes where no fade back to picture is desired. Battle scripts can later fade back to picture themselves if desired.

Parameters:

1

number

New post-cutscene fade-time. Note that unlike the majority of battle durations, camera durations (such as this) are specified in seconds.

2

number

optional, default value=0

New post-cutscene fade-time delay. If specified, this delays the fade-in effect. Unlike the first parameter it is set in ms.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 617

Back to top

Music

cutscene:set_music(string music event, number fade in, number fade out)
Sets a music sound event to play during the cutscene.

Parameters:

1

string

Music event name.

2

number

Fade in time in ms.

3

number

Fade out time in ms.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 652

cutscene:set_music_resume_auto_playback(boolean set auto playback)
Sets the sound system to return to automatically selecting music events after the cutscene ends. Only takes effect if a custom music track has been set with cutscene:set_music.

Parameters:

1

boolean

set auto playback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 688

Back to top

Relative Mode

cutscene:set_relative_mode()
Sets relative mode for enqueuing actions on the cutscene. With relative mode enabled, the time specified for each action is relative to the previously-added action, rather than absolute from the start of the cutscene. Relative mode is disabled by default.
Relative mode must be set before any actions are enqueued with cutscene:action.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 715

Back to top

Ambush Mode

cutscene:set_is_ambush([boolean is ambush], [boolean teleport units on end])
Sets up the cutscene as an intro cutscene of an ambush battle. This must be set if the cutscene is being shown over an ambush scene.

Parameters:

1

boolean

optional, default value=true

Set to true to enable ambush behaviour.

2

boolean

optional, default value=false

Set to true to teleport the ambushed units to the end of their ambush path once the cutscene ends.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 742

Back to top

Miscellaneous Setup

cutscene:set_battle_speed(number battle speed)

Sets the battle speed to use while the cutscene is running. By default this value is 1, so the cutscene plays at normal battle speed.

Parameters:

1

number

battle speed

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 782

cutscene:set_should_restore_battle_speed([boolean should restore])

Sets whether the cutscene should restore battle speed to that set prior to the cutscene starting. By default this behaviour is enabled.

Parameters:

1

boolean

optional, default value=true

should restore

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 795

cutscene:set_should_disable_unit_ids([boolean disable unit ids])
Sets whether unit ID uicomponents should be disabled during the cutscene. By default they are disabled, but by supplying false as an argument this function can be used to make them display.

Parameters:

1

boolean

optional, default value=true

disable unit ids

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 807

cutscene:suppress_unit_voices([boolean suppress voices])
Sets whether to suppress unit voices during the cutscene duration. By default they are disabled - enabling them (by supplying false as an argument) will cause units to audibly respond to orders given during the cutscene.

Parameters:

1

boolean

optional, default value=true

suppress voices

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 819

cutscene:set_should_enable_cinematic_camera([boolean enable cinematic camera])
Sets whether to enable the cinematic camera during the cutscene. By default it is enabled, but it can be disabled by supplying false as an argument to this function. The cinematic camera allows the camera to clip through terrain, so disable cinematic camera in circumstances where the path of the camera cannot be guaranteed (e.g. panning from a position relative to a unit to a fixed position, if there's a risk there'll be a hill in the way).

Parameters:

1

boolean

optional, default value=true

enable cinematic camera

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 836

cutscene:set_wait_for_advisor_on_end([boolean wait for advisor])
Sets whether to wait for the advisor to finish before ending the cutscene. This is akin to calling cutscene:wait_for_advisor at the end of the cutscene - the termination of the cutscene is delayed until the advisor has finished speaking. By default, cutscenes do not wait for the advisor to finish before ending.

Parameters:

1

boolean

optional, default value=true

wait for advisor

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 848

cutscene:set_wait_for_vo_on_end([boolean wait for sounds])
Sets whether to wait for any sounds registered with cutscene:play_sound or cutscene:play_vo to finish before ending the cutscene. This is akin to calling cutscene:wait_for_vo at the end of the cutscene - the termination of the cutscene is delayed until all registered sounds have finished playing. By default, cutscenes do not wait for registered sounds to finish before ending.

Parameters:

1

boolean

optional, default value=true

wait for sounds

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 860

cutscene:set_close_advisor_on_end([boolean should close advisor])
Sets whether to close the advisor at the end of the cutscene. By default this behaviour is enabled (so the advisor closes), supply false as an argument to disable it.

Parameters:

1

boolean

optional, default value=true

should close advisor

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 872

cutscene:set_close_advisor_on_start([boolean should close advisor])
Sets whether to close the advisor when the cutscene begins. By default this behaviour is enabled, supply false as an argument to disable it.

Parameters:

1

boolean

optional, default value=true

should close advisor

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 884

cutscene:enable_ui_on_end([boolean should enable ui])
Sets whether the cutscene should re-enable the UI when it finishes. By default the cutscene re-enables the UI - supply false as an argument to prevent it from doing so. This can be useful for scripts which have turned off the UI and don't want cutscenes re-enabling it.

Parameters:

1

boolean

optional, default value=true

should enable ui

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 896

cutscene:set_end_callback(function end callback)

Sets or changes the callback that is called when the cutscene is ended.

Parameters:

1

function

end callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 908

cutscene:set_call_end_callback_when_skipped([boolean should call callback])
Sets whether the cutscene should call the end callback (supplied when the cutscene is created with cutscene:new) when skipped. By default the cutscene does call this callback - supply false as an argument to prevent it from doing so.

Parameters:

1

boolean

optional, default value=true

should call callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 921

cutscene:set_should_release_players_army([boolean should call callback])
Sets whether the cutscene should release script control of the player's army when finishing. By default the cutscene does release this control - supply false as an argument to prevent it from doing so. This is useful for scripts that may want to restrict the player's control of their army and don't want cutscenes un-restricting it.

Parameters:

1

boolean

optional, default value=true

should call callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 933

cutscene:set_show_cinematic_bars([boolean show bars])
Sets whether the cutscene should show cinematic bars while playing. By default the cutscene does show cinematic bars - supply false as an argument to prevent it from doing so.

Parameters:

1

boolean

optional, default value=true

show bars

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 945

cutscene:set_should_hide_ui([boolean hide UI])
Sets whether the cutscene should show hide the UI while playing. By default the cutscene does hide the UI - supply false as an argument to prevent it from doing so.

Parameters:

1

boolean

optional, default value=true

hide UI

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 957

cutscene:set_should_restore_ui_hiding_on_end([boolean restore hiding])

Sets whether cutscene should restore any pre-existing scripted ui hiding state when the cutscene ends. By default this state is restored - supply false as an argument to prevent it from doing so.

Parameters:

1

boolean

optional, default value=true

restore hiding

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 969

cutscene:set_steal_input_focus([boolean steal input])
Sets whether the cutscene should steal input focus while playing, preventing player input. By default the cutscene does steal input - supply false as an argument to prevent it from doing so.

Parameters:

1

boolean

optional, default value=true

steal input

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 981

Back to top

Starting

cutscene:start()
Starts the cutscene. After this point it cannot be configured further.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 1028

Back to top

Subtitles

cutscene:show_custom_cutscene_subtitle(string subtitle key, string style, number duration, [boolean force])
Streams a line of subtitles. Use this method of subtitle display within an cutscene:action to animate the appearance of the supplied text over a supplied duration. Once a subtitle is shown with this function, it can later be hidden with cutscene:hide_custom_cutscene_subtitles (which is also called automatically when this function is called, to hide any subtitles already visible).
This functionality is provided by an extension to the text_pointer system. As this behaviour is controlled by script, which only updates every 1/10th second, blocks of characters may appear at the same time instead of each character individually. This system should probably be moved into code at some point.

Parameters:

1

string

Subtitle key, from the scripted_subtitles table.

2

string

Text pointer style, from the valid entries in text_pointer:set_style. "subtitle_with_frame" is in use by existing quest battles but more styles may be available.

3

number

Time the text takes to stream on-screen in ms.

4

boolean

optional, default value=false

Force display of the subtitles. Setting this to true overrides the user's subtitle preference.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 1382

cutscene:hide_custom_cutscene_subtitles([boolean hide immediately])
Hides any visible custom cutscene subtitles. The hide effect will be animated, unless true is passed in as a single argument which hides the subtitles immediately.

Parameters:

1

boolean

optional, default value=false

hide immediately

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 1429

cutscene:show_esc_prompt([boolean should show])

Shows or hides a "Press ESC to continue" subtitle prompt. It is intended that this should be called during an cutscene:action.

Parameters:

1

boolean

optional, default value=true

should show

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 1441

Back to top

Skipping

cutscene:skip()
Causes the cutscene to skip. This function is called internally when the ESC key is pressed, but it may also be called externally while the cutscene is running.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_cutscene.lua, line 1477

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