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 - see cutscene:set_do_not_end.

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 102

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 167

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 224

cutscene:enable_debug_timestamps([boolean enable timestamps])
Instructs the cutscene to output a timestamp to the console every 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 239

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 263

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)
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.

Returns:

  1. nil

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

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 357

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 372

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 389

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 396

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 415

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 423

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 431

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 439

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 455

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 463

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 471

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 492

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 511

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 551

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.

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 602

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 636

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 672

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 699

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 726

Back to top

Miscellaneous Setup

cutscene:set_do_not_end([boolean do not end])
Sets the cutscene to not end naturally. A cutscene set up in this manner may only be ended by being skipped or by an external script.

Parameters:

1

boolean

optional, default value=true

do not end

Returns:

  1. nil

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

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 778

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 790

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 807

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 819

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 831

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 843

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 855

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 868

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 880

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 893

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 905

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 917

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 929

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 941

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 953

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 1000

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 1359

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 1406

cutscene:show_esc_prompt([boolean should show])
Shows or hides a "Press ESC to continue" subtitle prompt. Intended to be called during an cutscene:action.

Parameters:

1

boolean

optional, default value=false

should show

Returns:

  1. nil

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

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 1458

Last updated 8/23/2024 4:55:16 PM