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

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, and will only finish when skipped by the player or ended by an external process - see campaign_cutscene:set_do_not_end.

3

function

optional, default value=nil

End callback.

Returns:

  1. campaign_cutscene cutscene object

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

campaign_cutscene:new_from_cindyscene(
  string name,
  [function end callback],
  string cindy scene,
  [number blend in],
  [number blend out],
  [number fade duration]
)

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. This is passed to the call to cinematics:cindy_playback when the cindyscene is started.

5

number

optional, default value=10

Blend out time, in seconds. This is passed to the call to cinematics:cindy_playback when the cindyscene is started.

6

number

optional, default value=false

Fade to picture duration, in seconds. If a number value is supplied, a fade to picture action will be performed when the cindyscene is started, over the given duration. If nil is supplied then no fade-to-picture action is performed.

Returns:

  1. campaign_cutscene cutscene object

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

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 217

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 229

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 250

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 268

campaign_cutscene:set_do_not_end([boolean do not end])
Sets the cutscene to not terminate once its duration is reached. If this is enabled, the cutscene can only be ended by being skipped or by being terminated by external script.

Parameters:

1

boolean

optional, default value=true

do not end

Returns:

  1. nil

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

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 292

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 304

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 316

campaign_cutscene:set_should_play_sound_on_cindyscene_start([boolean enable sound on cindyscene start])
Tells the cutscene whether to play a sound at the start of a cindyscene

Parameters:

1

boolean

optional, default value=true

enable sound on cindyscene start

Returns:

  1. nil

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

campaign_cutscene:set_should_play_sound_on_finish([boolean enable sound on finish])
Tells the cutscene whether to play a sound at the end of the cutscene

Parameters:

1

boolean

optional, default value=true

enable sound on finish

Returns:

  1. nil

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

campaign_cutscene:set_should_play_sound_on_skip([boolean enable sound on skip])
Tells the cutscene whether to play a sound after it is skipped

Parameters:

1

boolean

optional, default value=true

enable sound on skip

Returns:

  1. nil

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

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 364

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 377

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 389

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 402

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 410

campaign_cutscene:set_fade_on_skip(
  [boolean should fade],
  [number hold on black],
  [number fade to picture]
)

Sets whether the cutscene should immediately fade to black, and then back to picture, if the cutscene is skipped, and also the duration over which it should hold on black and fade to picture.
By default, a cutscene that is not playing a cindyscene will not perform any fade to black/back to picture, while a cutscene playing a cindyscene will instantly fade to black, hold on black for half a second, and then fade to picture over another half-second. Use this function to change any aspect of this default behaviour.
These settings will have no effect if the cutscene is not skipped.

Parameters:

1

boolean

optional, default value=true

Cutscene should cut to black and fade back to picture when skipped.

2

number

optional, default value=0.5s

Duration for which the cutscene should hold on black after being skipped, in seconds.

3

number

optional, default value=0.5s

Duration over which the cutscene should fade to picture after being skipped, in seconds.

Returns:

  1. nil

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

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 456

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 515

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 585

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 593

campaign_cutscene:set_pre_cindyscene_fade_to_black_duration(
  number fade duration,
  [number hold duration]
)

If the cutscene is playing a cindyscene using the campaign_cutscene:new_from_cindyscene constructor, the cindyscene starts as soon as the cutscene begins. Use this function to set a fade-to-black duration, and optionally a hold-on-black duration, so that the cutscene fades to black before the cindyscene begins playing.

Parameters:

1

number

Fade to black duration, in seconds.

2

number

optional, default value=0

Hold on black duration, in seconds.

Returns:

  1. nil

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

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 639

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.

Returns:

  1. nil

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

Back to top

Starting

campaign_cutscene:start()
Starts the cutscene.

Returns:

  1. nil

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

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 973

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 994

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 1010

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 1046

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