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
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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 66

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 125

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 200

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 212

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 233

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 250

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 262

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 274

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 286

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 298

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 310

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 324

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 337

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 349

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 362

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 370

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 382

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 441

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

Returns:

  1. boolean is active

defined in ../working_data/script/_lib/lib_campaign_cutscene.lua, line 511

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 519

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 543

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 578

Back to top

Starting

campaign_cutscene:start()
Starts the cutscene.

Returns:

  1. nil

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

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 815

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 836

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 851

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 ../working_data/script/_lib/lib_campaign_cutscene.lua, line 887

Last updated 25/08/2021 12:07:49