Campaign Documentation

Scripting Homepage

Search

Search campaign only




Game Areas

• > Campaign Index
• Battle Index
• Frontend Index

On this page

Key

Loaded in Campaign
Loaded in Battle
Loaded in Frontend

• Interventions
•   Usage
•   Configuration and Starting
•   Transient Interventions
•   Output
•   Creation
•     new
•   Trigger Callback
•     set_callback
•   Preconditions
•     add_precondition
•     add_advice_key_precondition
•     add_precondition_unvisited_page
•     add_player_faction_precondition
•     add_player_not_faction_precondition
•     add_player_subculture_precondition
•     add_player_not_subculture_precondition
•   Trigger Conditions
•     add_trigger_condition
•   Configuration
•     set_must_trigger
•     set_should_lock_ui
•     set_should_prevent_saving_game
•     set_reduce_pause_before_triggering
•     set_allow_when_advice_disabled
•     set_min_advice_level
•     set_player_turn_only
•     set_min_turn
•     get_min_turn
•     set_wait_for_battle_complete
•     set_wait_for_dilemma
•     set_wait_for_fullscreen_panel_dismissed
•     add_whitelist_event_type
•     set_completion_callback
•     add_cleanup_callback
•     get_turn_last_triggered
•     has_ever_triggered
•   Restart Callback
•     add_restart_callback
•   Restart on Turn Countdown
•     set_turn_countdown_restart
•     register_shared_turn_countdown_intervention
•   Taking and Ceding Priority
•     take_priority_over_intervention
•     give_priority_to_intervention
•   Starting
•     start
•   Whitelisting Events
•     whitelist_events
•   Completion
•     complete
•     cancel
•   Intervention Behaviour Wrappers
•     scroll_camera_to_character_for_intervention
•     scroll_camera_to_settlement_for_intervention
•     scroll_camera_for_intervention
•     play_advice_for_intervention

Campaign Topics

• Campaign Index
• Campaign Script Structure
• Lua Language
• Narrative System
• Scripted Events

Game Code Interfaces

• CampaignUI
• Cinematics
• Common
• Episodic Scripting
• Model Hierarchy
• ScriptedValueRegistry
• UIComponents

Script Interfaces

• Campaign Manager
• Core
• Campaign Cutscenes
• Campaign UI Manager
• Chapter Missions
• Convex Areas
• Global
• Infotext Manager
• > Interventions
• Invasion Manager
• Mission Managers
• Movie Overlays
• Narrative Events
• Navigable Tours
• Objectives Manager
• Payload String Constructor
• Random Army Manager
• Script Messager
• Scripted Tours
• Text Pointers
• Timer Manager
• Topic Leader
• Unique Table
• Validate

Data Interfaces

• Campaign Custom Starts
• Faction Intro
• Narrative
• Narrative Event Templates
• Narrative Query Templates
• Narrative Trigger Templates

Interventions

Campaign interventions offer a mechanism for script to lock the UI and the progression of the game while the player is shown or taken through a sequence of scripted events. This sequence can be as short as a few seconds to trigger some advice, or as long as a cinematic or a scripted tour of a feature. If one intervention has control of the game, no other intervention may gain control until that intervention completes.

An intervention is constructed with a unique name, a trigger function (what it calls when triggered) and a priority cost. Once constructed, one or more conditions must be added to the intervention that tell it when to trigger. The intervention starts monitoring for these conditions when intervention:start is called. Should one of these conditions be met, the intervention is enqueued for triggering, and its priority cost is considered alongside that of any other interventions that also wish to trigger at this time. The intervention that is highest priority gets to trigger first - its cost is added to a cumulative cost counter, and other interventions are queued up behind it. Once the first intervention has finished the second is started, and so on, until the list of interventions that wish to trigger is exhausted or the cumulative cost exceeds a certain value (100). The trigger monitors of any interventions that didn't get to trigger are restarted so they can trigger again in future.

By default, the state of declared interventions is saved into the savegame. The system also supports transient interventions which are not saved in to the savegame - see Transient Interventions.

Interventions are useful for delivering advice or other scripted events which demand focus, such as mid-game narrative cutscenes. Without the intervention system, there would be a risk that two such pieces of script would trigger at the same time and play simultaneously.

Loaded in Campaign
Loaded in Battle
Loaded in Frontend

An intervention may be created with intervention:new, after which functions on it may be called in the form showed below.

Example - Specification:

Example - Creation and Usage:

Once created, an intervention may optionally configured with a variety of settings (see Configuration). One or more trigger conditions can be added with intervention:add_trigger_condition. Preconditions, which are tests an intervention must pass before it's allowed to start may also be added to an intervention with intervention:add_precondition. Preconditions are checked again prior to an intervention triggering.

When set up, an intervention may be started with intervention:start. This only needs to happen once during the life-cycle of a campaign game, for an intervention that was previously started will be restarted should the script save and load. This includes interventions that have triggered and shut down, so the preconditions of each intervention must be set up to ensure that it doesn't start back up on script load unless that is desired.

Once an intervention triggers, it is imperative that it finishes, which happens when intervention:complete or intervention:cancel are called. Until one of these function is called an intervention will lock the UI and the progress of the game. However, some functions are made available that wrap common intervention templates - see the functions list in the Intervention Behaviour Wrappers section. These will automatically end the intervention at the appropriate time.

Interventions are persistent by default, which means that their details are saved into the savegame and that they are automatically re-established when the game is reloaded. Transient interventions are also supported, which are not saved into the savegame. These are intended for use for narrative events that have to pay heed to the intervention system but that are triggered in an inline fashion from other scripts.

Transient interventions can be created by setting the transient flag on the constructor function intervention:new. The campaign_manager also provides a fire-and-forget wrapper for creating transient interventions - see campaign_manager:trigger_transient_intervention.

Transient interventions, unlike persistent interventions, can share the same name (although this should be avoided if possible). Some advanced intervention functionality is not available to transient interventions, such as intervention:take_priority_over_intervention, intervention:set_turn_countdown_restart and other related functions.

The intervention system outputs extensive amount of information to the Lua - Interventions console spool.

If preconditions are added to an intervention, it will check these when it attempts to either start or trigger. If any of its preconditions return false, the intervention shuts down and will not trigger.

At least one trigger condition must have been added to an intervention with intervention:add_trigger_condition before it's started, otherwise it will never be able to trigger.

Restart events and checks are listened for if the intervention isn't running, assuming it has previously been started. If a restart callback event is received and the check returns true, then the intervention is restarted. Multiple restart callbacks may be added to one intervention.

Interventions can set to explicitly take or cede priority to another. This allows client scripts to ensure that one intervention must stop or cannot run when another is started, and for the second to notify the first when it stops so that the first can eventually start.

Call one of the functions in this section when an intervention is triggered to have it behave in a standardised manner, showing advice, infotext, a mission, optionally scrolling to a target and completing where appropriate.