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

• Narrative Events
•   Creation
•     new
•   Usage
•   Querying
•     is_running
•     has_triggered_this_campaign
•     has_been_seen_in_advice_history
•   Scripted Objectives
•     add_new_objective
•     add_condition
•     add_payload
•     set_mission_issuer
•     get_mission_manager
•   Payload Inheritance
•     add_narrative_event_payload_inheritance
•   Scripted Messages
•     add_message_on_issued
•     add_message_on_mission_completed
•   Trigger Callbacks
•     set_trigger_callback
•   Narrative Event Categories
•     set_category
•   Intervention Priority
•     set_priority
•   Camera Scrolling
•     set_camera_scroll_target_callback
•   Preconditions
•     add_precondition
•     remove_precondition
•   Advice Preconditions
•     add_advice_precondition
•     remove_advice_precondition
•   Trigger Conditions
•     add_trigger_condition
•     remove_trigger_condition
•   Force No Intervention
•     set_force_no_intervention
•   Intervention Configuration
•     add_intervention_configuration_callback
•   Starting
•     start
• Narrative Queries
•   Creation
•     new
•   Usage
•   Starting
•     start
•   Deferring
•     defer
•     retrigger
• Narrative Triggers
•   Deferred Triggering
•   Start and Cancel Messages
•   Creation
•     new
•   Usage
•   Querying
•     has_triggered_this_campaign
•   Configuration
•     add_monitor_event
•     add_monitor_message
•     
  set_should_setup_cancel_listeners_with_start_lis...set_should_setup_cancel_listeners_with_start_listeners
•     add_start_callback
•     add_stop_callback
•   Starting
•     start
•   Manipulation
•     trigger_message
•     force_main_trigger

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

Narrative Events

For an overview of the narrative events system see the narrative topic page.

Narrative events package a mission with some advice or narrative content, wrapped in an intervention. They are designed to aid the creation of early-game missions, which commonly have to show a mission with some advice and occasionally a camera movement. They can also be used as a container to deliver other content like cutscenes, fullscreen movies etc.

Once created, a narrative event may be associated with one or more a number of trigger messages that determine when it should trigger. See the Trigger Conditions section for more information. Preconditions may be also be set which the narrative event must pass before it can trigger - see Preconditions. Preconditions can fire script messages when they fail.

On-issued and on-mission-completed script messages may be specified - see the Scripted Messages section. Script messages may be triggered when a) the narrative event object triggers its mission/advice and b) when the mission is completed. The intention is that these may be listened for by other narrative objects, so that the completion or triggering of one leads to the triggering of another.

Once set up, the listeners associated with a narrative event must be started with narrative_event:start.

By default, narrative events will attempt to reduce the intrusiveness of advice, including not delivering the advice at all, if it's detected that the advice has been delivered before. This typically occurs when the player is experiencing the same narrative event on subsequent campaign playthroughs. See the Narrative Event Categories section for more information.

Narrative events may be declared and supported in multiplayer mode, but their content delivery will not be wrapped in an intervention and no advice will be shown.

Narrative events output diagnostic information on the Lua - Narrative console spool.

Loaded in Campaign
Loaded in Battle
Loaded in Frontend

Narrative events create persistent mission_manager objects internally. Due to this, narrative events need to be created before the first tick occurs - see the section in the mission manager documentation on Persistence for more information.

A narrative event object is created and returned by calling narrative_event:new. Once created, functions on a narrative_event may be called in the form showed below.

Example - Specification:

Example - Creation and Usage:

If a mission key was specified in narrative_event:new then this mission type can be customised using the functions in this section. These call the equivalent functions on the internally-created mission manager. Alternatively, the internal mission manager may be directly accessed with narrative_event:get_mission_manager, at which point function calls may be made to it to customise the mission to be delivered.

If no mission key was specified to narrative_event:new then no mision manager will have been generated, and these functions will produce errors and return false.

Narrative events may be set to inherit mission reward payloads from other narrative events, if that other narrative event has not yet triggered by the time the first does. This is to allow chains of narrative missions set up where individual missions can be bypassed without the player losing out on the reward that mission would bring.

Consider two narrative events that encapsulate missions, one to recruit an agent and another to use an agent against an enemy target. Neither has yet triggered. The agent-action mission, which triggers when an agent is recruited, would naturally lead on from the first, but not in all cases - the player may be gifted an agent from an incident or other scripted event. By setting the agent-action mission to inherit the rewards of the recruit-agent mission, the rewards of the now-redundant recruit-agent mission will be rolled in to the agent-action mission, meaning the player is not penalised for having inadvertantly skipped a mission before it can trigger.

If the narrative event being inherited from has already triggered then those rewards are not inherited. Should one narrative event inherit the rewards of another, that second narrative event will shut down and be unable to trigger.

Narrative events will not show advice, or not scroll the camera despite a scroll target being set with narrative_event:set_camera_scroll_target_callback, if they reason that the player has seen the content enough times before. They do this to avoid irritating the player with too much advice and too many intrusive camera movements for content that they're familiar with. The category of a scripted event and the advice level (high/low/minimal) set by the player is used to make this judgement and determine whether:

1. Advice should be played and the camera scrolled.
2. Advice should be played with no camera movement.
3. No advice or camera movement should be played.

In all cases the mission associated with the narrative event is triggered, if one was set up.

Value	Description
NARRATIVE_EVENT_CATEGORY_ADVICE_MANDATORY	Sets that the advice associated with this narrative event is mandatory and will always be played, including camera movements, even if the advice level is set to minimal. Only in multiplayer mode or if an advice precondition fails will the advice not be shown in this case. Use this setting sparingly.
NARRATIVE_EVENT_CATEGORY_ADVICE_HIGH_PRIORITY	Sets that the advice associated with this narrative event is high-priority. The only circumstance in which a narrative event of this category would not show its advice would be if the advice level was set to minimal.
NARRATIVE_EVENT_CATEGORY_ADVICE_SPECIFIC_TO_FACTION	Sets that the advice is normal priority, but that the advice shown is specific to the faction currently being played and not associated with the same narrative event but for different factions.
NARRATIVE_EVENT_CATEGORY_ADVICE_SHARED	Sets that the advice is normal priority and is shared amongst many different factions for which this narrative event triggers (e.g. a particular early game mission shared between many different playable factions).

The values listed in the table above are defined in script as constants. The default narrative event category is NARRATIVE_EVENT_CATEGORY_ADVICE_SHARED.

Should the narrative event trigger with an intervention, the priority for that intervention will determine the sort order of interventions that want to trigger at that same time. The priority for each narrative event intervention is determined from the category (see Narrative Event Categories), with mandatory and high-priority narrative events triggering before narrative events set with other categories. Alternatively, the priority may be overridden directly with narrative_event:set_priority.

A scroll-camera target may be set with narrative_event:set_camera_scroll_target_callback. This specifies a target region, character or position to which the camera is scrolled when the mission and advice are shown.

If the narrative event has been seen before in the advice history, it may decide not to scroll the camera even when a scroll-camera target has been set. See the Narrative Event Categories section for more information.

Precondition checks may be added to a narrative event that it has to pass in order to trigger successfully. Once added, each precondition is checked when the narrative event is started and also when the narrative event attempts to trigger.

Preconditions can be added with a name, which allows them to removed again if configuration is handled by multiple separate scripts that set a default behaviour for a particular narrative event and then customise that default.

Advice precondition checks may be added to suppress the advice registered to the narrative event under certain conditions. Should an advice precondition fail when the narrative event is triggered, the advice will not be shown. The narrative event and its associated mission will still trigger, however.

Trigger messages must be added to a narrative event. A narrative event will only trigger when a trigger message is received. One or more trigger messages may be added with narrative_event:add_trigger_condition.

If no trigger conditions are added to a narrative event the only way it can trigger is by specifying it must trigger immediately when calling narrative_event:start.

Some narrative events may not wish an intervention to trigger at all, even in singleplayer. These narrative events would typically not display any information to the player and would be a hidden part of a greater sequence e.g. they might just set a value in the savegame or advice history and return. narrative_event:set_force_no_intervention can be used to force a narrative event to not bother creeating an intervention.

Some narrative events may wish to configure the intervention that is created internally. This can be done by setting a configuration callback with narrative_event:add_intervention_configuration_callback. This could be used to allow the intervention to play before a battle sequence has been completed or when a fullscreen panel is showing, for example.

---

Narrative Queries

For an overview of the narrative events system see the narrative topic page.

Narrative queries represent decision points within a narrative structure. When triggered, a narrative query will run a supplied function query and may trigger script messages depending upon the result. Other narrative objects listening for those messages can then act upon the result of the query. See the page about the script_messager for more information about script messages (they are different-but-equivalent to script events).

All the data associated with a narrative query is supplied to it when it's constructed. Of particular note is the query records data structure - see the documentation of narrative_query:new for more information.

Once constructed, a narrative query is started by calling narrative_query:start. This starts its internal trigger listeners.

A narrative query triggers when it receives one of the trigger messages specified on creation (and the faction information contained in the message context matches the faction registered with the narrative query). At this point, all query functions supplied to the narrative event will be run, in order of registration. Each function will be passed the message context supplied to the narrative query as a first argument and the narrative query itself as a second. The query function can use the narrative query object to store data that other query functions that are about execute can read, if required.

For any query that passes (i.e. the query function returns true) the related pass script message is triggered. Where a query doesn't pass, and a fail message was specified in the query setup, that fail message is triggered.

Unlike narrative_event and narrative_trigger objects, narrative queries are stateless and do not save any information into the savegame. This means that any narrative query can trigger multiple times. The narrative event framework is designed so that narrative events and triggers should only be issued once, however, so this should be avoided.

Narrative queries should work as expected in multiplayer mode.

Narrative queries output diagnostic information on the Lua - Narrative console spool.

A narrative query object is created and returned by calling narrative_query:new. Once created, functions on a narrative_query may be called in the form showed below.

Example - Specification:

Example - Creation and Usage:

It may be desirable for a narrative query to not immediately return a result when it is triggered, such as if a multiplayer query is run with campaign_manager:progress_on_mp_query. narrative_query:defer may be called while is query is actively processing to instruct the query not to act on any result at that moment. At a later time narrative_query:retrigger may be called, which re-runs the query. In the interim, scripts can have prepared the information that the query needs to successfully complete.

---

Narrative Triggers

For an overview of the narrative events system see the narrative topic page.

Narrative triggers monitor game conditions in order to trigger other objects within the narrative system. All narrative events, or chains of narrative events, should ultimately be started by a narrative trigger.

One or more game script event/condition checks are registered with the narrative trigger either as it's created with narrative_trigger:new or later with narrative_trigger:add_monitor_event. When the narrative trigger is subsequently started when narrative_trigger:start is called, it starts a listener for each supplied event/condition and, if the event is received and the related condition is met, triggers one or more script messages that can start other objects in the narrative event system. Narrative triggers can also listen for script messages to know when to trigger - these can be added with narrative_trigger:add_monitor_message - although it's intended that narrative triggers should primarily listen for script events rather than messages.

Note the distinction between script messages and script events - while narrative triggers can listen for script events and messages from the game (or other scripts) to know when to trigger, the communication with other narrative objects happens exclusively with script messages. Script messages are a script-only parallel mechanism to script events, see the script_messager documentation for more information.

In most cases, all data relevant to the narrative trigger is supplied during construction, when narrative_trigger:new is called. Additional script events/conditions to monitor can be added after creation by calling narrative_trigger:add_monitor_event.

Once created, a narrative trigger will begin its monitors when narrative_trigger:start is called. Like narrative events and queries, narrative triggers are intended to only trigger once per-campaign playthrough. If a narrative trigger finds in the savegame data that it has triggered before it will not start its listeners when narrative_trigger:start is called.

Narrative triggers should work in multiplayer mode. Narrative triggers should only listen for model game events in multiplayer mode to allow scripts on different physical machines to maintain synchronicity.

Like other narrative objects, narrative triggers output diagnostic information on the Lua - Narrative console spool.

Invididual event/condition pairs can be set up to trigger immediately or not. Should an event/condition pair not be set up to trigger immediately then the narrative trigger will fire its trigger messages(s) within an intervention, which means that the message may not be triggered straight away. This can help reduce the intrusiveness of the narrative event system by spacing out the delivery of narrative events over time.

In multiplayer mode, where interventions are not supported, trigger messages are always fired immediately.

Narrative triggers may also be set up with start messages. Should one or more start message be registered then the narrative trigger will not start its main event/condition monitoring process until a start message is received from another object within the narrative event system. This can be useful in certain circumstances, for example to listen for the start of a particular faction's turn but only after another mission in the narrative event system has completed. If no start messages are specified the narrative trigger starts its main monitoring process immediately when narrative_trigger:start is called.

Cancel messages may also be set up for narrative triggers. These allow other narrative objects to cancel the trigger's main monitoring process, which can be used to stop a trigger from firing if some other condition is met within the narrative event system.

A narrative trigger object is created and returned by calling narrative_trigger:new. Once created, functions on a narrative_trigger may be called in the form showed below.

Example - Specification:

Example - Creation and Usage: