Narrative System
This page provides an overview of narrative events and related objects, and how they can assist with the creation of campaign narrative. More information can be found in the documentation for narrative_event, narrative_query and narrative_trigger objects.
| Relevant in Campaign |
|
| Relevant in Battle |
|
| Relevant in Frontend |
|
The narrative event framework is a toolkit for use when producing scripted narrative content in campaign. As a player progresses through a particular campaign playthrough it’s common for them to fulfil game conditions and reach narrative checkpoints where scripted experiences such as cutscenes, fullscreen movies, dilemmas or missions occur. Historic examples include:
- The Mongol Invasion in Medieval.
- Realm Divide in Shogun 2.
- Climate change in Attile.
- The Chaos Invasion in Warhammer.
- Vortex narrative events in Warhammer 2.
Scripts such as these can get complicated to write. The narrative event framework aims to help manage these complexities.
The narrative event framework can also be used to produce other content-delivery structures, such as early-game missions and chapter missions. Early-game missions are missions that are delivered towards the start of a particular campaign playthrough, with the twin aim of a) giving the player some optional initial direction, and b) driving the player’s awareness of game features. In general, the framework can be used to help produce content which is delivered to the player mid-campaign, once, when a known set of criteria are met.
It is intended for components within the narrative event framework to chain from one to another. For example, one mission may issue when another completes, or one mission may issue two turns after a second. The communication between narrative event components is handled with script messages.
The script messages that each narrative event listens for and transmits are specified when the narrative structure is set up in campaign scripts, affording them complete customisation of the narrative flow. Chains of narrative events may be set up by using script messages to link one to the next.
Script messages are an equivalent mechanism to script events, albeit script-only and hence not cluttered with events triggered by the game. See the script_messager documentation for more information about script messages. Script events are still used by narrative triggers to start chains of narrative events (see below).
The narrative event framework contains three major types of component:
Narrative Events
Narrative events are the action points within a narrative flow where content is delivered to the player, such as a mission being issued, a cutscene being triggered, an invasion event occurring etc. Other miscellaneous objects that help control narrative flow are also classified as narrative events. Examples include narrative events that wait a specified interval in seconds or a specified number of turns before proceeding.
Each narrative event is set up to trigger its payload (e.g. mission, cutscene, climate-change event) when a particular script message is received. They may optionally trigger other script messages when they have finished issuing, or when the mission they trigger is completed. Other narrative components may be set up to listen for these script messages being triggered and act accordingly.
In singleplayer mode, narrative events issue their content within an intervention that the narrative event manages internally. Interventions are not supported in multiplayer so the content is triggered directly in this case.
The library that provides the narrative event object interface is documented here: narrative_event.
Narrative Queries
A narrative query is a decision point within a narrative flow. When a narrative query is triggered from a script message, the game state is queried and further script messages are triggered depending upon the answer.
For example, an early-game mission structure for recruiting units of a particular type might trigger a narrative query which asks the game whether the player can currently recruit that type of unit. If they can, then a message which invokes a mission to recruit the units might be issued. If they can’t, then a different message might be issued instead to invoke a mission to construct a building that allows recruitment of that unit.
The library that provides the narrative query object interface is documented here: narrative_query.
Narrative Triggers
A narrative trigger monitors actual game conditions and then triggers messages that invoke other narrative components. Narrative triggers are the start points for flows of narrative events. For example, a mission that starts a narrative chain could be triggered when the player first suffers a rebellion in their territory. This would be handled with a narrative trigger that listens for a rebellion script event, and issues a message that then gets picked up by a narrative event.
Individual narrative triggers can be set up to trigger their target message(s) immediately or within an intervention. The latter approach allows narrative triggers to wait if other interventions (e.g. game advice) are currently triggering, potentially reducing the intrusiveness of the narrative event system by spacing out the delivery of content over time.
The library that provides the narrative trigger object interface is documented here: narrative_triggers.
Instances of narrative events, queries and triggers may be assembled into a narrative chain such as that illustrated below. Key:
| Shape | Meaning |
|---|---|
| Orange squares | Narrative events |
| Blue diamonds | Narrative queries |
| Green background/orange border | Narrative triggers |
The purpose of this framework is to allow a design such as this to map directly to script in a modular fashion.
The intended structure of the script implementation is on three levels:
Library Script
The library scripts contain the underlying functionality to create narrative_event, narrative_query and narrative_trigger objects.
Narrative Templates
Templates for specific types of narrative events, queries and triggers are created in an intermediate layer in script. These templates are then invoked by client campaign scripts to create actual narrative campaign objects.
Examples of narrative templates might include:
- A narrative event that issues a mission with advice to capture any region.
- A narrative event that displays a fullscreen movie.
- A narrative event that issues a mission to assassinate a particular enemy character.
- A narrative query that checks the advice history and acts depending on whether any of a supplied list of advice has been experienced by the player before.
- A narrative query that queries the difficulty level and acts accordingly.
- A narrative trigger that triggers at the start of a supplied turn.
- A narrative trigger that triggers when any player region drops below a supplied public order value.
Client campaign scripts create narrative events, queries or templates by calling template functions that create narrative objects of the required type. When calling template functions, the client scripts supply a minimum amount of information to complete the configuration of the narrative object being created. Examples of this information include:
- A unique name for the narrative object.
- The faction key to which the narrative object applies.
- The script message(s) on which to trigger.
- The key of the movie to play, if the narrative event is playing a movie.
- The mission key to trigger, if the narrative event is issuing a mission.
- The key of any advice to issue.
- The script message(s) to trigger when the narrative event finishes issuing or the mission completes.
- What turn on which to trigger, for a narrative trigger that triggers on turn start.
The list of available template functions is documented separately from the underlying libraries here:
Campaign Scripts
The use of template functions allows campaign scripts to create narrative events without ever having to directly configure or even handle narrative event, query, or trigger objects themselves. The campaign scripts that create narrative events resemble a long list of function calls. Arranging the scripts in this manner allows chains of narrative events to be set up in a modular fashion, with relative ease, and with the flow of narrative events being clearly traceable from messages.
The following image shows the use of override and default values for most arguments passed in to each template function. Doing this allows per-faction overrides to be set up for a particular narrative event, query, or trigger. This can be useful as it’s not uncommon to want to provide customisations for specific factions to cope with their unique mechanics or narrative set up.
Any overrides for a particular faction are set in a data table for that faction (faction_data in the image shown). The call to each template factory function prefers a value from the override table for most arguments. Where these values are not set in the override table then the default is used.
The narrative event framework aims to handle most complications arising from a multiplayer game internally.
By default, narrative events wrap their content within an intervention in singleplayer mode. As interventions are not supported in multiplayer mode this means that in many cases a degradation of the content being delivered to the player will occur. For example, a mission that is delivered with a camera scroll and some advice in singleplayer mode may be issued without these embellishments in multiplayer mode, as waiting for cutscenes to finish and advice to be dismissed complicates the synchronisation of scripts across multiplayer clients.
For narrative to work in a multiplayer game each client must maintain the script state of narrative events for all player factions, including players not on the local machine. For this reason all narrative event data is declared in a central location rather than in the various faction folders, as the scripts in these folders are only loaded when the local player is that faction.
Narrative objects handle the saving and loading of their own state to and from the savegame. In common with interventions and mission managers they must be declared in the root of the script, however.
Narrative objects output diagnostic information on the Lua - Narrative console spool.