Movie Overlays

The movie overlay player provides an interface for scripts to play movies in a created uicomponent. The player functionality allows scripts to specify properties of the uicomponent player and the movie itself, allowing fine control over playback. Through this interface the script can control the size and position of the movie on-screen, how the movie fades in and out and what to do when the movie completes or is skipped, for example. The script may also set a mask image, which can be used to blend the edges of the movie to transparent during playback for a pleasing visual effect.

A movie overlay player may be created with movie_overlay:new, and then optionally configured with the function calls listed in this documentation. Once configured, movie playback may be started by calling movie_overlay:start.

The movie overlay interface provides some functions for configuring the player, however other configuration calls may be made to it beyond those listed here. If any call is made to the player which it doesn not recognise then those are passed through to the underlying player uicomponent. This means that any function call provided by the uicomponent library may be made to a movie overlay object.

The player uicomponent is created the first time a call is made which is to be passed through to it, or when movie_overlay:start is called. If there is a delay between the creation/configuration of the player and the start of playback then be aware that the uicomponent will exist. It is set to be invisible and non-interactive so it should not affect the game.

If a movie_overlay is not configured before playback is started then the default style is applied using movie_overlay:set_style, setting the movie to be fullscreen.

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

Creation

movie_overlay:new(string name, string movie path)

Creates and returns a new movie overlay player object.

Parameters:

1

string

Unique name for this movie overlay object

2

string

Path to movie file, starting from the Movies folder in working data. The file extension should be omitted.

Returns:

  1. movie_overlay movie overlay object

Example - Play the Warhammer intro movie, filename data/Movies/startup_movie_03.ca_vp8:

mo_wh_intro = movie_overlay:new("warhammer_intro", "startup_movie_03");    -- path starts from Movies

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 72

Back to top

Usage

Once a handle to a movie_overlay object is obtained then functions may be called on it to query or modify its state in the following form.

Example - Specification:

<object_name>:<function_name>(<args>)

Example - Creation and Usage:

local mo_chaos_invasion = movie_overlay:new("warhammer_intro", "warhammer/chs_invasion");
mo_chaos_invasion:set_centre_mask_image();
mo_chaos_invasion:PropagatePriority(500);        -- function provided by uicomponent interface
Back to top

Configuration

movie_overlay:move_to(number x, number y)

Sets the position of the uicomponent by calling uicomponent:MoveTo, setting the uicomponent to be unmoveable afterwards. The uicomponent is created at this point if it doesn't already exist.
If a movie_overlay is not configured before playback is started then the default style is applied using movie_overlay:set_style, setting the movie to be fullscreen.

Parameters:

1

number

X screen co-ordinate in pixels.

2

number

Y screen co-ordinate in pixels.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 192

movie_overlay:resize(number width, number height)

Resizes the uicomponent, by calling uicomponent:Resize. The uicomponent is created at this point if it doesn't already exist.
If a movie_overlay is not configured before playback is started then the default style is applied using movie_overlay:set_style, setting the movie to be fullscreen.

Parameters:

1

number

Width in pixels.

2

number

Height in pixels.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 215

movie_overlay:set_skippable([boolean skippable])

Sets whether this movie should be skippable with the ESC key. Movies are skippable by default - use this function to disable this behaviour.

Parameters:

1

boolean

optional, default value=true

skippable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 243

movie_overlay:set_end_callback(function callback)

Sets a callback to be called when the movie ends or is skipped. If a hide animation is set, this callback gets called as the hide animation starts. To set a callback when the hide animation completes, use movie_overlay:set_destroy_callback.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 255

movie_overlay:set_skip_callback(function callback)

Sets a callback to be called when the movie is skipped. If a hide animation is set, this callback gets called as the hide animation starts, before the end callback if one has been set with movie_overlay:set_end_callback.

Parameters:

1

function

callback

Returns:

  1. nil

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

movie_overlay:set_destroy_callback(function callback)

Sets a callback to call when the player uicomponent is destroyed. This will only get called if this movie overlay player destroys itself, not if something else destroys it.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 281

movie_overlay:set_hide_on_end(boolean destroy on end)

Sets whether the overlay should try and hide or destroy itself when it ends. Set this to false if some other process will destroy it.

Parameters:

1

boolean

destroy on end

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 294

movie_overlay:set_should_loop([boolean loop])

Sets the movie to loop. By default, the movie plays only once.

Parameters:

1

boolean

optional, default value=true

loop

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 306

movie_overlay:set_play_movie_audio([boolean play audio])

Sets whether the movie audio should play or not. Movie audio plays by default - use this function to disable it.

Parameters:

1

boolean

optional, default value=true

play audio

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 318

movie_overlay:set_freeze_game_rendering([boolean should freeze])

Sets whether the game should continue to render while the movie is being played. Game rendering stops during movie playback by default - use this function to enable it.

Parameters:

1

boolean

optional, default value=true

should freeze

Returns:

  1. nil

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

movie_overlay:set_steal_user_input([boolean should steal])

Sets whether user input should be stolen by script while the movie is being played. The script establishes an ESC key listener to handle movie skipping if this is set.

Parameters:

1

boolean

optional, default value=true

should steal

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 342

movie_overlay:set_stop_game_audio([boolean stop audio])

Sets whether the game audio should stop playing while the movie is being played. By default game audio is stopped/disabled during movie playback - use this function to enable it.

Parameters:

1

boolean

optional, default value=true

stop audio

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 354

movie_overlay:set_resize_uicomponent_to_fit([boolean should freeze])

Sets whether the uicomponent should resize itself to match the dimensions of the movie. This behaviour is disabled by default - use this function to enable it.

Parameters:

1

boolean

optional, default value=true

should freeze

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 366

movie_overlay:force_movie_track(number movie track)

Forces the movie overlay to use a particular track. If this track is already occupied the previous video will be stopped. Supported track values are 0-3. If no movie track is forced, the system will pick track 2 or 3, depending on which is currently free.

Parameters:

1

number

movie track

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 378

Back to top

Frame Callbacks

Callbacks can be registered to be called on certain frames or timestamps during the movie playback using the functions in this section.

movie_overlay:add_frame_callback(function callback, number frame number)

Adds a callback to be called when the movie reaches a specified frame. The frame can be specified as a positive number or as a negative number, in which case that number of frames from the end of the movie is considered the trigger frame.

Parameters:

1

function

callback

2

number

frame number

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 407

movie_overlay:add_timestamp_callback(function callback, number timestamp)

Adds a callback to be called when the movie reaches a specified timestamp, in seconds. The time can be specified as a positive number or as a negative number, in which case the timestamp is counted backwards from the end of the movie.

Parameters:

1

function

callback

2

number

timestamp

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 425

Back to top

Animations

The functions described in this section can be used to set custom show and hide animations for the player uicomponent. The animations should also be added to the movie overlay uicomponent in the UI editor.

movie_overlay:set_show_animation(string animation name, [number duration override])

Sets the uicomponent animation that should be triggered when the movie starts playing. By default an animation called "show" is triggered - use this function to set a different animation. A blank string may be supplied to play no animation as the movie starts.
An optional animation duration in seconds may also be supplied. If set, this causes the player to set the frame time of the last frame of the animation to the supplied duration.

Parameters:

1

string

animation name

2

number

optional, default value=nil

duration override

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 453

movie_overlay:set_hide_animation(string animation name, [number duration override])

Sets the uicomponent animation that should be triggered when the movie ends. This animation is played when the movie ends naturally, either because playback has finished or the specified movie duration has elapsed. It is also played if the movie is skipped and no skip animation has been set. By default this animation is called "hide" - use this function to set a different animation. A blank string may be supplied to play no animation.
An optional animation duration in seconds may also be supplied. If set, this causes the player to set the frame time of the last frame of the animation to the supplied duration.
Any new hide animation should also be set to destroy the overlay uicomponent on completion.

Parameters:

1

string

animation name

2

number

optional, default value=nil

duration override

Returns:

  1. nil

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

movie_overlay:set_skip_animation(string animation name, [number duration override])

Sets the uicomponent that should be triggered when the movie is skipped. By default this animation is called "hide" - use this function to set a different animation. A blank string may be supplied to play no animation.
An optional animation duration in seconds may also be supplied. If set, this causes the player to set the frame time of the last frame of the animation to the supplied duration.

Parameters:

1

string

animation name

2

number

optional, default value=nil

duration override

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 504

Back to top

Mask Images

The functions described in this section each set a mask image for the movie overlay. The transparency value of each pixel in this image is mapped onto the movie, allowing control over the opacity of each movie pixel during playback. This allows the edges of the movie to be blended to transparent, for example.

Several pre-defined mask images have already been created, or another mask image may be specified. By default, a fully-opaque mask image is used so no blending/transparency is seen during playback.

movie_overlay:set_mask_image(string mask image path)

Sets a path to a mask image for the movie overlay. This image should be in png format. The path is specified from the working data folder.
Calling this function creates the movie player uicomponent if it has not already been created.

Parameters:

1

string

mask image path

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 541

movie_overlay:set_opaque_mask_image()
Sets a mask image of ui/skins/default/mask_movie_unmasked.png. This mask image is fully opaque.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 563

movie_overlay:set_top_left_mask_image()
Sets a mask image of ui/skins/default/mask_movie_top_left.png. This mask image is intended to be used on movies shown in the top-left corner of the screen, blending to transparent to the bottom and right.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 570

movie_overlay:set_top_right_mask_image()
Sets a mask image of ui/skins/default/mask_movie_top_right.png. This mask image is intended to be used on movies shown in the top-right corner of the screen, blending to transparent to the bottom and left.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 577

movie_overlay:set_bottom_left_mask_image()
Sets a mask image of ui/skins/default/mask_movie_bottom_left.png. This mask image is intended to be used on movies shown in the bottom-left corner of the screen, blending to transparent to the top and right.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 584

movie_overlay:set_bottom_right_mask_image()
Sets a mask image of ui/skins/default/mask_movie_bottom_right.png. This mask image is intended to be used on movies shown in the bottom-right corner of the screen, blending to transparent to the top and left.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 591

movie_overlay:set_centre_mask_image()
Sets a mask image of ui/skins/default/mask_movie_centre.png. This mask image is intended to be used in a central position on the screen, blending to transparent along all four edges.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 598

Back to top

Styles

Movie overlay styles combine multiple settings into one function call. If it's desired to play multiple movies in the same manner it may be sensible to set up a style to avoid configuring each movie overlay object the same way.

movie_overlay:set_style(string style name)

Sets a style. Currently recognised styles:
Style NameDescription
fullscreenSets the movie to be fullscreen and to block rendering update.
defaultThe default style sets the movie to be fullscreen.

Parameters:

1

string

style name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 618

Back to top

Starting and Stopping

movie_overlay:start()
Starts playback of the movie

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 734

movie_overlay:is_playing()
Returns whether this movie is currently playing.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 963

movie_overlay:skip()
Causes this movie to skip during playback. This is mainly for internal use but can be called externally.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 970

Windowed Movie Player

The windowed movie player provides a shorthand interface for playing movies in a window, with a close button. It is of most use for playing movies underneath the advisor, for which the constructor windowed_movie_player:new_from_advisor should be used. However, it may be used in other contexts, for which the more general purpose constructor windowed_movie_player:new is used.

The windowed movie player makes heavy use of the movie_overlay system for movie playback.

Back to top

Creation

windowed_movie_player:new(string name, string movie path, number aspect ratio, [uicomponent ui_root])

Creates and returns a new windowed movie player object. If creating a windowed movie player docked underneath the advisor, the constructor windowed_movie_player:new_from_advisor should be used instead.

Parameters:

1

string

Unique name for this windowed movie object

2

string

Path to movie file, starting from the Movies folder in working data. The file extension should be omitted.

3

number

Movie aspect ratio. This should be the width divided by the height.

4

uicomponent

optional, default value=ui_root

Parent uicomponent, to which the windowed movie player should be attached.

Returns:

  1. windowed_movie_player windowed movie player object

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1131

windowed_movie_player:new_from_advisor(string name, string movie path, number aspect ratio)

Creates and returns a new windowed movie player object, set up to play underneath the advisor. This sets the advisor_movie_docker uicomponent to be the panel parent, and also calls windowed_movie_player:set_hide_animation_slides_off_screen_left to set custom hide animation behaviour that is appropriate for this display mode.

Parameters:

1

string

Unique name for this windowed movie object.

2

string

Path to movie file, starting from the Movies folder in working data. The file extension should be omitted.

3

number

Movie aspect ratio. This should be the width divided by the height.

Returns:

  1. windowed_movie_player windowed movie player object

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1178

windowed_movie_player:new_centred(string name, string movie path, number aspect ratio)

Creates and returns a new windowed movie player object, set up to play in the centre of the screen.

Parameters:

1

string

Unique name for this windowed movie object.

2

string

Path to movie file, starting from the Movies folder in working data. The file extension should be omitted.

3

number

Movie aspect ratio. This should be the width divided by the height.

Returns:

  1. windowed_movie_player windowed movie player object

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1200

Back to top

Usage

Once a handle to a windowed_movie_player object is obtained then functions may be called on it to query or modify its state in the following form.

Example - Specification:

<object_name>:<function_name>(<args>)

Example - Creation and Usage:

local wmp_drag_and_select = windowed_movie_player:new_from_advisor("wmp_test", "wh3_drag_and_select", 16/9);
wmp_drag_and_select:set_should_steal_esc_key_focus(true)
wmp_drag_and_select:start()
Back to top

Configuration

windowed_movie_player:set_width(number panel width in pixels)

Sets the intended panel width. By default, the panel will use the panel width set in the ui layout. The height will also be scaled, based on the aspect ratio supplied to windowed_movie_player:new.

Parameters:

1

number

panel width in pixels

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1245

windowed_movie_player:set_docking_point(number docking point)

Sets the panel docking point, which determines how the panel is docked to its parent uicomponent. Docking points are specified as integer values - a list is available in the Docking section of this documentation.

Parameters:

1

number

docking point

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1263

windowed_movie_player:set_show_animation(string animation name)

Sets an animation to play on the panel when it is showed. By default no animation is triggered. The animation must be present on the panel uicomponent.

Parameters:

1

string

animation name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1275

windowed_movie_player:set_hide_animation(string animation name)

Sets an animation to play on the panel when it is hidden. By default, an animation called "hide" is triggered. The animation must be present on the panel uicomponent.

Parameters:

1

string

animation name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1293

windowed_movie_player:set_hide_animation_slides_off_screen_left(boolean hide animation slides left)

Sets a special flag which adjusts the horizontal movement of the hide animation to match the panel width, so the animation moves the panel fully off-screen regardless of width.

Parameters:

1

boolean

hide animation slides left

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1306

windowed_movie_player:set_close_callback(function callback)

Sets a callback to call if this windowed movie player is closed. The callback is triggered at the point of closure, when the panel has yet to animate off-screen.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1318

windowed_movie_player:set_show_close_button([boolean show close button])

Sets whether the close button is shown on the windowed movie player. By default the close button is displayed, use this function to not show it if needs be.

Parameters:

1

boolean

optional, default value=true

show close button

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1331

windowed_movie_player:set_panel_hidden_callback(function callback)

Sets a callback to call when the windowed movie player is fully hidden after being closed. The supplied callback is triggered immediately prior to the panel being destroyed.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1343

windowed_movie_player:set_should_steal_esc_key_focus(boolean steal esc key focus)

Sets whether the panel should steal escape key focus and therefore close itself when the ESC key is pressed. By default the panel does respond to ESC key presses, use this function to disable this behaviour.

Parameters:

1

boolean

steal esc key focus

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1356

Back to top

Showing and Hiding

windowed_movie_player:show()
Creates and shows the panel and starts movie playback.

Returns:

  1. nil

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

windowed_movie_player:hide()
Hides and then destroys the windowed movie player if it is showing, playing an animation to do so if one has been set. This is called internally if the close button is clicked, or if the ESC key is pressed when stolen.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_movie_overlay.lua, line 1499

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