Navigable Tours

A navigable tour is a particular type of scripted_tour which provides a control panel to the player, allowing them to rewind back and forth between tour sections. The player may also exit the tour at any time from the control panel provided.

Navigable tours are built on top of the functionality that scripted tours provide, and extend and wrap the scripted tour interface. One crucial difference is that actions are associated with a navigable tour through an intermediate navigable_tour_section objects. Once created, actions are added to navigable_tour_section objects and then they are registered with the parent navigable tour with navigable_tour:add_navigable_section. Actions cannot be directly added to a navigable tour, asides from start and end actions.

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

Navigable Tours and Scripted Tours

When created, a navigable tour creates a scripted_tour object and stores it internally. Calls made to the navigable tour object that the navigable tour interface does not provide are automatically passed through to the internal scripted tour object. An exception to this is scripted_tour:action - this is explicitly overridden by the navigable tour interface and will throw a script error if called.

Back to top

At A Glance

A navigable tour is declared with navigable_tour:new. A name and a function to call when the tour ends (or is skipped) must be specified here, as well as an optional tour name as a full localisation key.

Once the tour is created, separately-created navigable_tour_section objects may be assigned to it with navigable_tour:add_navigable_section. These objects contain the underlying actions that are ultimately played - much of the complexity of setting up a narrative tour comes from setting up the sections.

Startup and finishing actions may be added to the navigable tour with navigable_tour:start_action and navigable_tour:end_action. These are played when the tour starts or ends.

Once configured with sections, a tour may be started with navigable_tour:start.

Back to top

Creation

navigable_tour:new(string name, [function end callback], [string tour title])

Creates and returns a navigable tour object. Each navigable tour must be given a unique string name and, optionally, an end callback which will be called when the scripted tour ends or is skipped.
An optional tour title may also be supplied as a full [table]_[field]_[key]-style localised key. If supplied, the title of the navigable tour control panel will be set to the localised text specified by the key.

Parameters:

1

string

Unique name for the scripted tour.

2

function

optional, default value=nil

End callback.

3

string

optional, default value=nil

Full localisation key to use for navigable tour title.

Returns:

  1. navigable_tour navigable tour

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 1181

Back to top

Usage

Once a navigable_tour object has been created with navigable_tour:new, functions on it may be called in the form showed below. Any functions that are not recognised on the navigable tour are passed through to the scripted_tour object created internally.

Example - Specification:

<scripted_tour_object>:<function_name>(<args>)

Example - Creation and Usage:

local nt_siege_defence = navigable_tour:new(
    "siege_battle_defence",                                                                        -- unique name
    end_siege_battle_defence_tour,                                                                -- end callback
    "ui_text_replacements_localised_text_wh3_main_battle_scripted_tour_siege_defence_name"        -- title
);

-- calling a function on the object once created
nt_siege_defence:set_allow_camera_movement(true);

-- calling a function on the underlying scripted tour
-- (the function call is passed through automatically)
nt_siege_defence:add_validation_rule(
    function()
        return core:is_battle()
    end,
    "random_localisation_strings_string_scripted_tour_invalid_not_battle"
);
Back to top

Configuration

navigable_tour:set_tour_controls_above_infotext([boolean tour controls above infotext])

Sets the tour controls to appear above the infotext panel in the top-left of the screen. The tour controls panel will also be stretched horizontally to be the same width as the infotext panel.
If false is supplied as an argument then the tour controls revert back to being underneath the infotext panel.

Parameters:

1

boolean

optional, default value=true

tour controls above infotext

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 1270

navigable_tour:set_interval_before_tour_controls_visible(number interval)

Sets the interval at the start of the tour before the tour controls are animated to visible. By default this value is set to 1 second. This value should be set in seconds in campaign, and milliseconds elsewhere.

Parameters:

1

number

interval

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 1345

navigable_tour:set_start_first_section_automatically([boolean should start automatically])

Sets the scripted tour to start the first section automatically or not. By default, the first section is started automatically. Disable this behaviour with this function if the start action sequence is not of a predetermined length, such as a cutscene that must be dismissed.
If the first section is not started automatically then it must be started manually with navigable_tour:start_next_section.

Parameters:

1

boolean

optional, default value=true

should start automatically

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 1357

Back to top

Start and End Actions

Navigable tours contain start and end sequences, to which action callbacks may be added using the functions in this section. These sequences can be zero-length and don't have to contain any actions.

The starting sequence is played as the tour is started, and can be used to set up the tour or play a one-time intro sequence. The main tour sequences will start when the start action with the longest interval is called.

The end sequence is played as the tour is exited and can be used to play an outro or clean up after the tour. The tour will fully exit when the end action with the longest interval is called.

navigable_tour:start_action(function action, [number action time])

Adds an action to the navigable tour's starting sequence.

Parameters:

1

function

Action callback.

2

number

optional, default value=0

Interval after the start of the tour at which to trigger the action. This should be given in seconds in campaign, and milliseconds otherwise.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 1387

navigable_tour:end_action(function action, function action time)

Adds an action to the navigable tour's ending sequence.

Parameters:

1

function

Action callback.

2

function

Interval after the start of the tour at which to trigger the action. This should be given in seconds in campaign, and milliseconds otherwise.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 1421

Back to top

Main Construction

The navigable_tour:add_navigable_section function can be used to add navigable_tour_section objects to the navigable tour. This is the intended method for building a navigable tour - actions are added to a section, and sections are added to a tour. When the navigable tour is started, the navigable tour sections are added as segments to the underlying scripted_tour object, should their preconditions pass.

navigable_tour:add_navigable_section(navigable_tour_section navigable tour section)

Adds a navigable_tour_section to the navigable tour. Navigable tour sections should be added in the order in which they should be shown in game.

Parameters:

1

navigable_tour_section

navigable tour section

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 1476

Back to top

Starting

navigable_tour:start()
Starts the navigable tour.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 1574

Back to top

Playback

The functions in this section are for use while the tour is playing.

navigable_tour:start_next_section()
Cause the navigable tour to skip to the next section. If the start actions are being played then the first section of the tour is started.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 1818

navigable_tour:start_previous_section()
Cause the navigable tour to skip to the previous section.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 1850

navigable_tour:get_scripted_tour_controls_uicomponent([boolean do not create])

Gets the scripted tour controls panel, creating it if it doesn't already exist. This is mainly for internal use but could feasibly be called externally.

Parameters:

1

boolean

optional, default value=false

Do not create - if set to true, the tour controls are not created if they do not already exist.

Returns:

  1. uicomponent tour controls

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 1895

navigable_tour:cache_and_set_scripted_tour_controls_priority()
Sets the priority to the supplied value, and caches the value previously set. The scripted tour controls priority can later be restored with restore_scripted_tour_controls_priority.
The register_topmost flag can also be set to force the scripted tour controls to topmost.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 2108

navigable_tour:restore_scripted_tour_controls_priority()
Restores the scripted tour controls priority to a value previously cached with cache_and_set_scripted_tour_controls_priority.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 2134

Navigable Tour Section

A navigable tour section is a container for action callbacks that occur during a section of a navigable_tour. A navigable tour is wrapper for a scripted_tour, and a navigable tour section represents a scripted tour segment. Declaring navigable tour sections, loading them with actions, and then adding them to a navigable tour is the route by which actions get added to a navigable tour.

Navigable tour sections can be reused between different navigable tours.

Back to top

Creation

navigable_tour_section:new(string name, [boolean activate controls])

Creates and returns a new navigable tour section.

Parameters:

1

string

name

2

boolean

optional, default value=false

Activate scripted tour controls on start of this navigable tour section. Setting this to true means that the tour next/prev buttons will be active as soon as this tour section starts. In this case navigable_tour_section:activate_tour_controls does not need to be called within a tour action.

Returns:

  1. navigable_tour_section navigable tour section

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 2221

Back to top

Configuration

navigable_tour_section:add_precondition(function callback, [opt=nil string error message)

Adds a precondition check to be called when the navigable tour is started. The supplied function will be called and, should it return nil or false, the section will not be added to the navigable tour.
If an optional error message string is added with the precondition then a script error displaying that message will be triggered should the precondition not pass.

Parameters:

1

function

Precondition callback.

2

[opt=nil

Error message to display should the precondition fail. If no error message is supplied then no error is triggered.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 2260

navigable_tour_section:action(function callback, number interval)
Adds an action to be triggered while the navigable tour section is playing. Actions are added with an interval, which is the time after the start of the section that the action should occur.

Parameters:

1

function

Callback function to call.

2

number

Interval after the navigable tour section starts at which the specified action should be triggered. This should be given in seconds in campaign, and in ms in battle and the frontend.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 2298

Back to top

Playback Controls

The functions in this section should only be called from within a callback registered to navigable_tour_section:action, so that they are only called while the navigable tour section is actively playing.

navigable_tour_section:add_skip_action(function skip action, [string action name])

Adds a skip action for this navigable tour section. Navigable tour sections should use skip callbacks to clean up after themselves. The skip action will be called when this section of the tour is skipped by the player during playback, either by navigating forwards or backwards to other tour sections or by closing the tour. Two boolean argument will be passed to the skip action function - the first, if true, indicates that the entire tour is ending, and the second, if true indicates that the tour is being skipped backwards rather than forwards.
Skip actions may be added with an optional name, by which they be later removed.
This function should only be called from within an action when the tour section is running.

Parameters:

1

function

skip action

2

string

optional, default value=nil

action name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 2365

navigable_tour_section:remove_skip_action(string action name)

Immediately removes any skip actions from this navigable tour section with the supplied name. This should only be called during an action within the tour section.

Parameters:

1

string

action name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 2397

navigable_tour_section:activate_tour_controls()
Activates the tour control panel during playback of the navigable tour section. This should only be called during an action within the tour section.
If the activate-controls flag is not set when navigable_tour_section:new is called, as is the default behaviour, then the tour controls will remain inactive until this function is called during playback. If the last action in the tour section is called and the controls are still not active then this function will be called automatically. This failsafe behaviour prevents a situation where a section is playing and the tour controls never become active, but it should probably be avoided by either calling this function directly during an action within the section or setting the appropriate flag when calling navigable_tour_section:new.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 2420

navigable_tour_section:highlight_next_button()
Highlights the next (or finish) button on the navigable tour controls during playback. This should only be called during an action within the tour section.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 2433

navigable_tour_section:is_playing()
Is this navigable tour section playing right now.

Returns:

  1. boolean is playing

defined in ../../Warhammer/working_data/script/_lib/lib_scripted_tours.lua, line 2451

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