Battle Documentation

Scripting Homepage

Search

Search battle only




Game Areas

• Campaign Index
• > Battle Index
• Frontend Index

On this page

Key

Loaded in Campaign
Loaded in Battle
Loaded in Frontend

• Scripted Tours
•   At A Glance
•   Creation
•     new
•   Usage
•   Validation
•     add_validation_rule
•     add_validation_context_change_listener
•     is_currently_valid
•   Enqueuing Actions
•     action
•     append_action
•   Fullscreen Highlight
•     add_fullscreen_highlight
•     set_fullscreen_highlight_delay
•     set_fullscreen_highlight_padding
•     
  set_allow_fullscreen_highlight_window_interactio...set_allow_fullscreen_highlight_window_interaction
•     show_fullscreen_highlight
•   Skip Button
•     get_skip_button_container
•     set_show_skip_button
•     add_skip_action
•     remove_skip_action
•     clear_skip_actions
•     show_skip_button
•     move_skip_button
•   Misc Configuration
•     set_should_hide_text_pointers_on_completion
•     set_should_dismiss_advice_on_completion
•     set_allow_camera_movement
•   Starting and Stopping
•     start
•     skip
•     complete_sequence
•     complete

Battle Topics

• Battle Index
• Battle Hierarchy
• Lua Language
• Scripted Events

Game Code Interfaces

• Battle
• Alliances
• Alliance
• Armies
• Army
• Units
• Unit
• Unitcontroller
• AI Planners
• Assault Equipment
• Building
• Buildings
• Camera
• Capture Location
• Composite Scenes System
• Debug Drawing
• reinforcements Reinforcements
• Sound Effects
• Subtitles
• Toggle System
• Vector
• Common
• ScriptedValueRegistry
• UIComponents

Script Interfaces

• Battle Manager
• Core
• Advice Manager
• Battle UI Manager
• Convex Areas
• Battle Cutscenes
• Generated Battle
• Global
• Infotext Manager
• Movie Overlays
• Navigable Tours
• Objectives Manager
• Script AI Planner
• Script Messager
• Script Unit
• > Scripted Tours
• Text Pointers
• Timer Manager
• Topic Leader
• Validate

Data Interfaces

• Scripted Tour Helpers

Scripted Tours

A scripted tour is a linear section of scripted gameplay where the script locks all player interaction with the game barring the minimum necessary for the player to perform a series of actions, generally with a fullscreen highlight to focus the players attention on one portion of the screen. This is most commonly used for tutorial scripting - the actions in this case would be the player acknowledging advice and text_pointer objects and clicking on UI items as they are instructed to. This scripted_tour class allows a scripted tour (or a scripted tour segment, as multiple tour objects may be strung together to form what the player might call a single 'scripted tour') to be set up relatively easily.

As an example, a scripted tour may be triggered when the player first gains a character skill point. Normal interaction is stopped at this point, with the script showing a sequence of advice to the player and compelling them to perform a series of steps (dismissing advice and/or clicking on highlighted ui buttons). Once the player has performed that series of steps then control is released back to them.

An example screenshot of a scripted tour:

This scripted tour mechanism provides a relatively easy interface to establish a fullscreen highlight around a portion of the user interface to better highlight to the player what section of the screen they should be looking at. With a fullscreen highlight visible the scripted tour mechanism also supports displaying a skip button, allowing the player to skip through tour content.

If a scripted tour is intended to be shown during live campaign gameplay then it's strongly recommended to always trigger it from within an intervention in order to control the flow of events around the tour that is triggering. Scripted tours may be triggered in battle and the frontend, but are primarily intended for use in campaign.

Action callbacks may be added to a scripted tour along with a time offset at which they should be called with scripted_tour:action. These actions are called at the supplied times when the tour is started. Multiple 'sequences' of actions may be specified for a single scripted tour, as a given tour will often have to wait for an indeterminate period for a player response before continuing - the actions that come after the player response would be laid out in a different sequence to those coming before.

Once constructed, a tour (or a particular sequence within the tour) may be started with scripted_tour:start.

When a scripted tour finishes it will trigger the script event ScriptEventScriptedTourCompleted, with the scripted tour name as the context string.

Loaded in Campaign
Loaded in Battle
Loaded in Frontend

Each scripted tour must be declared with scripted_tour:new. A name and a function to call when the tour ends (or is skipped) must be specified here.

Once declared, actions may be added to the tour with scripted_tour:action. Each action is a function to be called at some timed interval after the tour has started. It is through actions that events during the tour occur, such advice being displayed and buttons being highlighted. By specifying a sequence name when declaring actions, an action may be added to a specific action sequence within the tour. Action sequences may be used to group actions together. It's common that a scripted tour is made of several short segments of actions that commences when the player makes a certain input.

A fullscreen highlight can be added over one or more ui components during the tour with scripted_tour:add_fullscreen_highlight. A delay may be set so this highlight doesn't appear as soon as the tour starts with scripted_tour:set_fullscreen_highlight_delay.

The skip button can be shown or hidden with scripted_tour:show_skip_button, or moved around the screen with scripted_tour:move_skip_button. Functions to call if the scripted tour is skipped may be added with scripted_tour:add_skip_action and removed again with scripted_tour:remove_skip_action.

Once a scripted tour is declared and configured it may be started with scripted_tour:start. Supply no arguments to this function to start the main action sequence, or specify a name to start a particular action sequence.

Once a sequence is started it must be ended by calling scripted_tour:complete_sequence with the name of the sequence. All running sequences and the tour as a whole may be ended by calling scripted_tour:complete. Alternatively, the tour ends immediately if the player clicks on the skip button or if scripted_tour:skip is called. The tour must be ended by calling scripted_tour:complete or scripted_tour:skip after it has been started.

Once a scripted_tour object has been created with scripted_tour:new, functions on it may be called in the form showed below.

Example - Specification:

Example - Creation and Usage:

Validation rules may be built into a scripted tour using scripted_tour:add_validation_rule, to allow it to know when it can be triggered. Validation rules added to a scripted tour are checked when that tour is started with scripted_tour:start, and should any fail then the scripted tour will fail to trigger.

Client scripts may also ask a scripted tour whether it is currently valid to trigger by calling scripted_tour:is_currently_valid. Should the tour not currently be valid then a reason value, supplied to scripted_tour:add_validation_rule when the rule is established, is returned to the calling script. This can be used by UI scripts, for example, to determine whether to enable or disable a scripted tour button, and to customise its appearance (e.g. change the tooltip) to indicate a reason why the tour can't currently be triggered.

Furthermore, context change listeners may be added to a scripted tour with scripted_tour:add_validation_context_change_listener by which a scripted tour may listen for events that may indicate its validation state changing. Should a scripted tour detect that a context change has altered its validation state it will trigger the script event ScriptEventScriptedTourValidationStateChanged which can be listened for by scripts elsewhere.

Actions must be added to a scripted tour if it is to do anything. Action callbacks added to a tour are called by that tour once the tour is started with scripted_tour:start. Actions are added with an action time, which specifies how long the scripted tour should wait after being started before calling the action. Pending actions are cancelled when a tour is skipped or completed, so if this happens before an action is called then it will never be called.

Actions may optionally be added to a 'sequence' by specifying a string sequence name when calling scripted_tour:action. Different sequences in a scripted tour may be started by calling scripted_tour:start with the sequence name.

The scripted tour may be instructed to put a fullscreen highlight around one or more uicomponents when the tour starts. Components to highlight may be added by their path with scripted_tour:add_fullscreen_highlight. Multiple calls may be made to this function to add multiple components to highlight. The highlighting is performed with core:show_fullscreen_highlight_around_components, see documentation on that function for more information.

Should any fullscreen highlight components be added to the scripted tour then a fullscreen highlight will be placed over them when the tour starts. The creation of the fullscreen highlight may be delayed with scripted_tour:set_fullscreen_highlight_delay. Set a negative delay here to prevent the fullscreen highlight from being created automatically - in this case, external scripts may show or hide the fullscreen highlight manually with scripted_tour:show_fullscreen_highlight.

If a fullscreen highlight is visible then the scripted tour will display a skip button by default. The following functions control the visibility, on-screen position and functionality of the skip button.

The tour will be skippable with the ESC key if a skip button is shown, and won't be skippable if it isn't.

A scripted tour will do nothing until it is started with scripted_tour:start. If no argument is specified with this call then the main sequence of actions (i.e. those that were not added to a sequence) is started, otherwise the action sequence with the specified string name is started.

Once started, a scripted tour will remain active until it is skipped or until the main action sequence is completed using scripted_tour:complete. Calling this function with no arguments will complete the main action sequence (and the tour as a whole), whereas calling it with the name of a sequence will stop just that sequence. It is the responsibility of external scripts, usually those called within a scripted tour action, to complete the scripted tour.

A scripted tour may be skipped by the player clicking on the skip button (if it is shown), which calls scripted_tour:skip. Alternatively, this function may be called directly.

When a scripted tour finishes it will trigger the script event ScriptEventScriptedTourCompleted, with the scripted tour name as the context string.