Campaign Documentation

Scripting Homepage

Search

Search campaign only




Game Areas

• > Campaign Index
• Battle Index
• Frontend Index

On this page

Key

Loaded in Battle
Loaded in Campaign
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 Events and Callbacks
•     set_event_on_triggered
•     set_event_on_mission_completed
•     set_trigger_callback
•   Narrative Event Categories
•     set_category
•   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
•   Starting
•     start

Campaign Topics

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

Game Code Pages

• CampaignUI
• Cinematics
• Effect
• Episodic Scripting
• ScriptedValueRegistry
• UIComponents

Script Pages

• Campaign Manager
• Core
• Campaign Cutscenes
• Campaign Interface
• Campaign UI Manager
• Chapter Missions
• Convex Areas
• Global
• Infotext Manager
• Interventions
• Invasion Manager
• Mission Managers
• > Narrative Events
• Objectives Manager
• Random Army Manager
• Script Messager
• Text Pointers

Narrative Events

Narrative events are a method for easy packaging of a mission with some advice or narrative content, wrapped in an intervention. They are mainly intended for use in early-game missions, which commonly have to show a mission with some advice and occasionally a camera movement, but they can be used for other purposes.

Once created, a narrative event may be associated with a number of trigger events (and optional conditions) that determine when it should trigger. See the Trigger Conditions section for more information. Preconditions may be also be set which narrative event must pass before it can trigger - see Preconditions.

On-issued and on-mission-completed script events may be specified - see the Scripted Events and Callbacks section. These script events are triggered when the narrative event object triggers its mission/advice and when the mission is completed. The intention is that these may be used by client scripts to easily daisychain narrative events together, 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.

Loaded in Campaign

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 encapsulates 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.

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 conditions must be added to a narrative event to allow it to trigger. One or more trigger conditions 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.