Adding Cutscenes

Guide for building cutscenes on the Redmew scenario

Summary

Redmew scenario has custom cutscene controller which itself is built on top of APIs provided by factorio. This enhances the player experience some of the features are...

• Ability to script scenes in sequence with textual prompts that support a given locale.
• A GUI to move forward/backward through various scenes or skip the cutscene all together.
• Dynamically focus on objects while the cutscene is running.
• Cutscenes that span across multiple surfaces.
• Cutscenes run for one player will not affect the other.

Introduction

There are two files that are directly related to cutscenes in Redmew.

• /features/cutscene/cutscene_controller.lua
• /features/cutscene/rendering.lua

Here are some of the Factorio API's used (For advance devs as much of this has been encapsulated).

• jump_to_cutscene_waypoint
• exit_cutscene
• set_controller
• on_cutscene_waypoint_reached

rendering.lua

Functions are self-explanatory and are based on LuaRendering

cutscene_controller.lua - Exposed functions

toggle_gui(tick, player, gui, initial_delay, clear)

Toggles the scenario-specific GUI for a given player. Requires a custom GUI like that of Diggy's.

Parameters

• tick :: unit: The in-game tick at which the cutscene GUI is toggled visible/invisible.
• player :: table: The player for the which the GUI is toggled.
• gui :: table: Scenario specific GUI.
• initial_delay :: unit: Delay in ticks.
• clear :: string: Name of the custom GUI to toggle

play_sound(tick, player, path, times, delay, initial_delay)

Play in-game sounds.

Parameters

• tick :: unit: The in-game tick at which the sound is played.
• player :: table: The player for the which the sound is played to.
• path :: string: File path of the in game sound API.
• times :: unit(optional): Number of times to play the sound.
• delay :: unit(optional): Delay between times the sound is played in ticks <= 20.
• initial_delay :: unit(optional): Delay in ticks before the sound is first played.

register_cutscene_function(identifier, waypoints, func, terminate_func)

Used to register your scripted cutscene function before it is run.

Parameters

• identifier :: string: Unique name for your cutscene functions.
• waypoints :: table: The waypoint for each scene.
• func :: any: The fuction representing the scripted scenes.
• terminate_func :: any: The fuction that is run after a cutscene ends.

register_running_cutscene(player_index, identifier, final_transition_time)

Used to initiate a registered cutscene.

Parameters

• player_index :: unit: Player index.
• identifier :: string: Unique name for your cutscene functions.
• final_transition_time :: unit (optional): The amount of ticks to wait after a cutscene ends. This time is used to pan the camera back to the players location. Default: 60 ticks.

inject_waypoint(player_index, waypoint, waypoint_index, override)

Dynamic insertion of waypoints at runtime. Used to pan the camera to locations on a map during runtime. (Not recommended to be used as there is a risk of breaking the cutscene when the backward/forward buttons are pressed erratically and too quickly)

Parameters

• player_index :: unit: Player index.
• waypoint :: table: A single waypoint table.
• waypoint_index :: unit: The index at which the waypoint is to be inserted.
• override :: boolean (optional): If set to true the waypoint is overridden at the given index. Default: false.

terminate_cutscene(player_index, ticks,skip_btn_flag)

The function that is run after the scripted cutscene function has finished.

Parameters

• player_index :: unit: Player index.
• ticks :: unit: Ticks to wait before the cutscene is terminated.
• skip_btn_flag :: boolean(optional): Provided Internal flag if it is true then the player has either pressed the "skip cutscene" button or has terminated the cutscene by leaving game mid cutscene. Mandatory use for multi-surface cutscene - If true perform functions that are run to open Redmew welcome menu. It can also be used to perform different functions per surface depending on which surface the player presses the skip button.

register_rendering_id(player_index, tick, render_id)

Used in conjunction with "features.cutscene.rendering" to run graphical rendereing like text, shapes, etc. on specific scenes.

Parameters

• player_index :: unit: Player index.
• tick :: unit: The tick to run the rendering at.
• render_id :: any: The render to run as defined in "features.cutscene.rendering".

register_replay(identifier, final_transition_time)

The function that is associated with an identifier is initiated when /replay command is run by a user. Useful for a multi-surface cutscene and you want a cutscene to begin on a different surface from that which was run initially.

Parameters

• identifier :: string: Unique name for your cutscene functions.
• final_transition_time :: unit(optional): The number of ticks to wait after a cutscene ends. This time is used to pan the camera back to the player's location. Default: 60 ticks.

goTo(player_index, waypoint_index)

Pan the camera of a specified player on a given surface to the pre-defined waypoint. The player must already be in a cutscene.

Parameters

• player_index :: unit: Player Index.
• waypoint_index :: unit: The index of the pre-defined waypoint.

waypoints table structure

local waypoints_outpost = {
    {
        -- Index 1
        position = {x = 0, y = 0},
        transition_time = 90,
        time_to_wait = 375 * 2,
        zoom = 0.5
    },
    {
        -- Index 2
        position = {x = 0, y = -10},
        transition_time = 120,
        time_to_wait = 375 * 2,
        zoom = 1.5
    }
}

Parameters

• position :: position: Standard factorio position {x,y}
• transition_time :: unit: Time taken in ticks to transition to the next waypoint.
• time_to_wiat :: unit: The duration of time spent on that particular waypoint.
• zoom :: unit: The zoom level of the world.

Anatomy of a cutscene

1. 	Customizations of the rendering functions.

2. 	cutscene_function - Use Cases to script individual scenes.
	waypoints table
	start_cutscene_function
	terminate_cutscene

Note: Repeat No. 2 for a multi-surface cutscene.

3. 	Cutscene.register_cutscene(identifier, waypoints, func, terminate_func)

Note: Register all individual cutscenes.

function Public.register_replay(identifier, final_transition_time)

Note: Include this function if you want /replay to be enabled.

4.	Initialize the cutscene in your scenario.
        on_init()
        on_load()

Other things to consider and FAQ.

If replay function is registered; make sure to print this line to intimate the player about restarting the cutscene at all the possible ends of your cutscene.

player.print({'crashsite.replay_cutscene', '/replay'}, Color.yellow)

For a multi-surface cutscene, it is important to generate your new surface in your scenario file before teleporting to it.

on_init()

        game.create_surface('cutscene', default_map_gen_settings)
	game.surfaces.cutscene.always_day = true
        game.surfaces.cutscene.request_to_generate_chunks({0,0}, 2)
        game.surfaces.cutscene.force_generate_chunk_requests()
        cutscene_outpost() --fuctions that build structures on your new surface
        Cutscene.on_init()

on_load()

        Cutscene.on_load() --Just run the cutscene as the surface has already been generated

Some other properties

• /replay cannot be run when a player is waiting to respawn.
• In case of a multi-surface cutscene if a player dies during an active cutscene further cutscenes will seize and run terminate_function of the cutscene in which the player died.
• Some elements in rendering.lua are linked to the zoom level defined in the waypoints table.

Note: The above points can be circumvented by writing your own custom code into your scenario. Requires good understanding of cutscene_controller.lua

Examples

At the time of writing this doc, there are two scenarios in which the cutscenes are implemented - Diggy and Crashsite. When making any cutscene these two should be used as a reference. Diggy implementation has a single surface cutscene and Crashsite has a dual surface cutscene.