Campaign Cutscenes

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

See also the Camera Movement functions on the campaign manager, which allow the camera to be scrolled within a cutscene without having to manually set up a campaign cutscene object.

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

Creation

campaign_cutscene:new(string name, [number duration], [function end callback], [bool send_metrics_data])

Creates a cutscene object. A cutscene must be given a unique string name, a length in seconds and optionally an end callback.

Parameters:

1

string

Unique name for the cutscene.

2

number

optional, default value=nil

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

3

function

optional, default value=nil

End callback.

4

bool

optional, default value=nil

Send performance data to metrics.

Returns:

  1. campaign_cutscene cutscene object

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 95

campaign_cutscene:new_from_cindyscene(
  string name,
  [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

function

optional, default value=nil

End callback.

3

string

Cindy scene path.

4

number

optional, default value=0

Blend in time, in seconds.

5

number

optional, default value=10

Blend out time, in seconds.

Returns:

  1. campaign_cutscene cutscene object

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 149

Back to top

Usage

Once a cutscene object has been created with campaign_cutscene:new, functions on it may be called using the following form.

Example - Specification:

<cutscene_object>:<function_name>(<args>)

Example - Creation and Usage:

local cutscene_intro = campaign_cutscene:new(
    "intro",
    48,
    function() intro_cutscene_has_ended() end
)
cutscene_intro:set_debug(true)                -- calling a function on the object once created
Back to top

Debug

campaign_cutscene:set_debug([boolean set debug])
Sets the cutscene into debug mode for more output.

Parameters:

1

boolean

optional, default value=true

set debug

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 239

campaign_cutscene:set_debug_all([boolean set debug])
Sets all campaign cutscenes into debug mode for more output.

Parameters:

1

boolean

optional, default value=true

set debug

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 251

Back to top

Configuration and Querying

campaign_cutscene:set_skippable([boolean set skippable], [function skip callback])
Sets whether the cutscene should be skippable or not, and also allows the optional specification of a callback to be called if the cutscene is skipped. Note that if a skip callback and end callback are both set, both will be called (in that order).

Parameters:

1

boolean

optional, default value=true

set skippable

2

function

optional, default value=nil

skip callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 272

campaign_cutscene:set_dismiss_advice_on_end([boolean dismiss advice])
Sets whether the dismiss the advisor at the end of the cutscene. By default the advisor is skipped - use this function to disable this behaviour.

Parameters:

1

boolean

optional, default value=true

dismiss advice

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 289

campaign_cutscene:set_use_cinematic_borders([boolean show borders])
Sets the cutscene to show cinematic borders whilst playing, or not. Cutscenes by default will show cinematic borders - use this function to disable this behaviour.

Parameters:

1

boolean

optional, default value=true

show borders

Returns:

  1. nil

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

campaign_cutscene:set_restore_ui([boolean restore ui])
Tells the cutscene whether to restore the ui when it ends, or not. Cutscenes by default will restore the ui - use this function to disable this behaviour. This is useful in highly specific circumstances.

Parameters:

1

boolean

optional, default value=true

restore ui

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 313

campaign_cutscene:set_disable_settlement_labels([boolean disable labels])
Tells the cutscene whether to show settlement labels while playing or not. Cutscenes by default will hide settlement labels - use this function to disable this behaviour.

Parameters:

1

boolean

optional, default value=true

disable labels

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 325

campaign_cutscene:set_neighbouring_regions_visible([boolean disable labels])
Tells the cutscene whether to make neighbouring regions visible or not. Cutscenes by default will not do this - use this function to enable this behaviour if required. The 'neighbouring' regions in this case are those regions adjacent to the regions currently unshrouded.
Setting this property to true also enables the shroud.

Parameters:

1

boolean

optional, default value=true

disable labels

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 337

campaign_cutscene:set_disable_shroud([boolean disable shroud])
Tells the cutscene whether to show the shroud during playback, or not. By default the shroud is displayed - use this function to disable it if required.

Parameters:

1

boolean

optional, default value=true

disable shroud

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 351

campaign_cutscene:set_restore_shroud([boolean restore shroud])
Tells the cutscene whether to restore the shroud after completion to the state it was in before the cutscene started, or not. By default the shroud is restored - use this function to disable this behaviour if required.

Parameters:

1

boolean

optional, default value=true

restore shroud

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 364

campaign_cutscene:set_show_advisor_close_button_on_end([boolean show advisor close button])

Tells the cutscene whether to show the advisor close button after the cutscene is finished or not. By default the close button is not shown - use this function to show the button at the end of the cutscene.

Parameters:

1

boolean

optional, default value=true

show advisor close button

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 376

campaign_cutscene:set_intro_cutscene([boolean is intro cutscene])

Tells the cutscene system that this cutscene is a faction intro cutscene. Intro cutscenes inform the campaign manager when they start and stop, and also trigger an additional "ScriptEventCampaignIntroCutsceneCompleted" event when the cutscene completes.

Parameters:

1

boolean

optional, default value=true

is intro cutscene

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 388

campaign_cutscene:is_intro_cutscene()
Returns whether this cutscene has been set to be an intro cutscene.

Returns:

  1. boolean is intro cutscene

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 400

campaign_cutscene:set_end_callback(function end callback)
Sets the cutscene end callback. This replaces any end callback previously set (e.g. with campaign_cutscene:new).

Parameters:

1

function

end callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 408

campaign_cutscene:prepend_end_cutscene(function callback)

Adds the specified callback to the start of the existing end-callback, without overwriting the existing end-callback's contents. If there is no end-callback yet, this cutscene's end-callback will simply be set to the one provided.

Parameters:

1

function

callback to prepend to the existing end-callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 421

campaign_cutscene:has_end_callback()
Returns true if the cutscene has an end callback specified, false otherwise.

Returns:

  1. boolean has end callback

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 440

campaign_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_campaign_cutscene.lua, line 448

campaign_cutscene:set_fade_on_skip(
  [boolean fade to black],
  [number fade to picture time],
  [number fade to picture delay]
)

Sets whether the cutscene should immediately fade to black, and then optionally fade back to picture (after an optional delay), or not. By default the cutscene system will fade to black immediately if the cutscene is skipped, then wait a second, then fade to picture after a second. Use this function to change this behaviour.

Parameters:

1

boolean

optional, default value=true

Fade to black immediately on skip.

2

number

optional, default value=1

Time in seconds over which the cutscene will fade back to picture. If a negative number is supplied, or no fade to black is set, then no fade to picture is performed.

3

number

optional, default value=1

Time in seconds after the cutscene is skipped between the fade to black and the subsequent fade back to picture.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 460

campaign_cutscene:set_skip_camera([number x], [number y], [number d], [number b], [number h])
Sets a position at which the game camera is repositioned to if the cutscene is skipped. The reposition happens behind a fade to black so the player does not see it.
If no position is supplied, the cutscene system takes the current position of the game camera as the skip camera position.
Note that this reposition will not happen if the cutscene is not skipped.

Parameters:

1

number

optional, default value=nil

x co-ordinate. If no co-ordinates are set here the function takes the camera position at the moment the function is called.

2

number

optional, default value=nil

y co-ordinate.

3

number

optional, default value=nil

d co-ordinate.

4

number

optional, default value=nil

b co-ordinate.

5

number

optional, default value=nil

h co-ordinate.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 490

campaign_cutscene:set_restore_camera(number time, [number x], [number y], [number d], [number b], [number h])
Sets co-ordinates to which the game camera is restored when the cutscene ends. If a restore camera position is specified, the camera is scrolled to that position at the end of the cutscene over the supplied time in seconds. This is useful when it's desired to return the camera to the position it started the cutscene at when the cutscene finishes, or to a different position.
If no co-ordinates are supplied, the cutscene system takes the current position of the game camera as the restore camera position.
Note that if a skip camera position is set with campaign_cutscene:set_skip_camera, and the cutscene is skipped, the camera will be skipped and not restored. If the cutscene is skipped, has no skip camera position but has a restore camera position set, the camera will be immediately repositioned at the restore camera position while the screen is faded to black.

Parameters:

1

number

Time in seconds over which to scroll the camera.

2

number

optional, default value=nil

x co-ordinate. If no co-ordinates are set here the function takes the camera position at the moment the function is called.

3

number

optional, default value=nil

y co-ordinate.

4

number

optional, default value=nil

d co-ordinate.

5

number

optional, default value=nil

b co-ordinate.

6

number

optional, default value=nil

h co-ordinate.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 549

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

Returns:

  1. boolean is active

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 619

campaign_cutscene:steal_input_immediately()
Instructs the cutscene to steal input immediately, before campaign_cutscene:start() is called. This is useful for campaign intro cutscenes as there's a short window of opportunity for the player to interact with the game as the loading screen is fading out, before the cutscene starts.
Note that cutscenes don't steal input when debug mode is set with campaign_cutscene:set_debug or campaign_cutscene:set_debug_all, which affects this command too.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 627

campaign_cutscene:set_music_trigger_argument(string music_trigger_argument)
Sets the cutscene music trigger argument to be passed to the music system when the cutscene starts

Parameters:

1

string

A uniquely identifying name for the cutscene relevant to the music system

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 637

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 657

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

campaign_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_campaign_cutscene.lua, line 678

Back to top

Subtitles

campaign_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 campaign_cutscene:action.

Parameters:

1

boolean

optional, default value=true

should show

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 711

Back to top

Enqueuing Actions

Actions are the events that happen in a cutscene while the cutscene is running. Examples include camera movements and the playing of advice, subtitles, and potentially composite scenes. A cutscene must be loaded with actions before it is started.

campaign_cutscene:action(function callback, number delay)
Registers a new action with the cutscene. The action is supplied a function callback, which is called at the appropriate time after the cutscene has been started (assuming the cutscene is not skipped beforehand).

Parameters:

1

function

Action callback to call.

2

number

Delay in seconds after the cutscene starts before calling this action callback (or after the preceeding action, if in relative mode).

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 748

campaign_cutscene:action_set_camera_position(number delay, table camera_coords)

Set the camera position. When using this, it's best to wait a fraction of a second before enacting other camera movements, as the action is not instant and can be overriden by other camera actions.

Parameters:

1

number

The delay in seconds.

2

table

The coordinates to move the camera to. List of numbers as defined in Camera Movement.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 798

campaign_cutscene:action_scroll_camera_to_position(
  number delay,
  number scroll duration,
  boolean correct_endpoint,
  table camera_coords
)

Scroll the camera from its current location to the specified location.

Parameters:

1

number

The delay in seconds.

2

number

How long it takes, in seconds, for the camera to reach its new coordinate.

3

boolean

Correct endpoint. If true, the game will adjust the final position of the camera so that it's a valid camera position for the game. Set to true if control is being released back to the player after this camera movement finishes.

4

table

The coordinates to scroll the camera to. List of numbers as defined in Camera Movement.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 812

campaign_cutscene:action_show_advice(number delay, string advice key)

Display some advice.

Parameters:

1

number

The delay in seconds.

2

string

Advice thread key.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 828

campaign_cutscene:action_override_ui_visibility(number delay, ... ui overrides)

Disable or enable the UI of the specified string keys, as defined in campaign_ui_manager.

Parameters:

1

number

The delay in seconds.

2

...

A variable number of UI override arguments to enable or disable. UI overrides may be specified as multiple string arguments or a single table of strings.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 842

campaign_cutscene:action_fade_scene(number delay, number brightness, number duration)

Fades the scene to black or back to picture over a specified period.

Parameters:

1

number

The delay in seconds.

2

number

Brightness, as a unary value. Supply a value of 0 to fade to black, supply a value of 1 to fade to picture, or supply a value in between to transition to a partially-faded picture.

3

number

Duration of the fade effect in seconds.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 865

campaign_cutscene:action_end_cutscene(number delay)

Sets a listener to end the cutscene at the specified delay. This will also update the cutscene's internal duration.

Parameters:

1

number

The delay in seconds.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 880

Back to top

Starting

campaign_cutscene:start()
Starts the cutscene.

Returns:

  1. boolean cutscene was started successfully

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 927

Back to top

During Playback

campaign_cutscene:wait_for_advisor([number delay])
This function, when called, causes the cutscene to repeatedly stall while the advisor is still speaking and only allow the cutscene to progress once the advisor has finished. If the cutscene contains multiple lines of advice that are played one after the other, this function can be used to ensure that each item of advice only triggers once the previous item has finished playing, so they don't speak over the top of each other. This is useful when laying out multiple items of advice in a cutscene where the length of advice items cannot be known in different languages - a localised version of an advice item in German, for example, might be many seconds longer than the equivalent in English.
If a delay argument is passed in then the call to this function is enqueued as an campaign_cutscene:action with that delay. Alternatively, it may be called with no delay within an action.

Parameters:

1

number

optional, default value=nil

Delay in seconds after the cutscene starts before invoking this function.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 1190

campaign_cutscene:cindy_playback(string path, [number blend in], [number blend out])

Immediately starts playback of a cindy scene. This is intended to be called within an campaign_cutscene:action callback. If a cindy scene is started this way, the cutscene will automatically terminate it if the cutscene is skipped.

Parameters:

1

string

cindy xml path, from the data/ folder.

2

number

optional, default value=nil

Blend in duration in seconds.

3

number

optional, default value=nil

Blend out duration in seconds.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 1216

campaign_cutscene:dismiss_advice()
Issues a call to dismiss the advice without triggering the end of the cutscene. Normally a cutscene skips when advice is dismissed - use this function during an campaign_cutscene:action to circumvent this behaviour.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 1235

Back to top

Skipping

campaign_cutscene:skip()
This function is called internally when the cutscene has been skipped by the player. Additionally, it may be called by external scripts to force the running cutscene to skip.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_campaign_cutscene.lua, line 1271

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