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

• Mission Managers
•   Different Methods of Specifying Objectives
•   Persistence
•   Creation
•     new
•   Usage
•   Global Configuration Options
•     set_should_cancel_before_issuing
•     set_should_whitelist
•     set_show_mission
•     set_victory_mission
•   Startup Callbacks
•     add_first_time_trigger_callback
•     add_each_time_trigger_callback
•   Constructing From Strings
•     add_new_objective
•     add_condition
•     add_payload
•     add_payload_from_mission_manager
•     add_failure_payload
•     add_heading
•     add_description
•     set_turn_limit
•     set_chapter
•     set_mission_issuer
•     set_position
•     set_victory_type
•   Scripted Objectives
•     add_new_scripted_objective
•     add_scripted_objective_success_condition
•     add_scripted_objective_failure_condition
•     force_scripted_objective_success
•     force_scripted_objective_failure
•     update_scripted_objective_text
•   Persistent Values
•     set_persistent_value
•     get_persistent_value
•   Sourcing Objectives from Database
•     set_is_mission_in_db
•     set_is_incident_in_db
•     set_is_dilemma_in_db
•   Querying
•     has_been_triggered
•     is_active
•     is_completed
•   Resetting
•     reset
•   Triggering
•     trigger
•     cancel_dismiss_callback_listeners

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

Mission Managers

Mission managers can be used to set up and manage scripted missions issued to the player. It isn't necessary to set up a mission manager in order to trigger a scripted mission, but they provide certain benefits:

• Success, failure, cancellation and nearing-expiry callbacks may be registered with the mission manager, which calls these when the mission reaches a certain state.
• Missions in the game may be triggered from a mission string - the mission manager offers easy methods to construct such a string.
• Missions may be set up with scripted objectives - success and/or fail conditions that are triggered by script, allowing mission completion conditions to be implemented of arbitrary complexity, or that aren't supported natively by the game. Mission managers provide a framework for allowing this to be set up relatively easily.
• Mission managers may be set up with first time and each time startup callbacks (see mission_manager:add_first_time_trigger_callback and mission_manager:add_each_time_trigger_callback for more details) allowing other scripts to be started while the mission is running.

Mission managers can also be used to trigger incidents and dilemmas.

Loaded in Campaign
Loaded in Battle
Loaded in Frontend

Most missions are only composed of one individual objective, but more than one is supported (chapter missions tend to have more). The objectives that make up a mission may be specified in one of three ways:

• A mission may be constructed from a mission string. Refer to the section on Constructing From Strings to see how to do this.
  • Mission objectives may be scripted, which means that it is the responsibility of script to monitor completion/failure conditions and notify the game. Scripted objectives may be set up using the functions in the Scripted Objectives section. Scripted objectives are constructed internally from a mission string and as such can't be combined with mission records from the database or missions.txt file (see following points).
• A mission may build its objectives from records in the database (see the cdir_events_mission_option_junctions table). To set a mission to build its objectives from the database set it to trigger from the database with mission_manager:set_is_mission_in_db, mission_manager:set_is_incident_in_db or mission_manager:set_is_dilemma_in_db and do not add any text objectives (see mission_manager:add_new_objective).
• Mission strings may also be baked into the missions.txt file that accompanies each campaign. This is the default option, but arguably the least desirable and flexible.

If a mission manager has been set up to use certain features then it is classified as persistent. Persistent mission managers have script values that are saved into the savegame so the mission manager can know whether to start certain listeners when a saved game is loaded. As such, persistent mission managers must be declared and set up prior to the first tick.

Features that set a mission manager to be persistent are:

• Any success, failure, cancellation or nearing-expiry callbacks.
• Any Scripted Objectives.
• Any Persistent Values.
• One or more each-time startup callbacks added with mission_manager:add_each_time_trigger_callback.

Mission managers that are not persistent are "fire and forget", meaning they can be discarded once triggered. The underlying campaign model will remember that a mission has been triggered, the script mission manager does not need to be re-established if the game is reloaded.

Once a mission_manager object has been created with mission_manager:new, functions on it may be called in the form showed below.

Example - Specification:

Example - Creation and Usage:

The functions in this section apply changes to the behaviour of the mission manager regardless of the type of mission being triggered.

Mission managers provide a mode where the mission being triggered is constructed from a string. Example of such strings can be found in the missions.txt found in data/campaigns/<campaign_name>/ for some campaigns. The main advantage of constructing missions from strings is that their initial setup may be dynamically constructed depending on game conditions at the time.

If new objectives are added with mission_manager:add_new_objective then the mission manager will be set to construct its mission with a string. It will subsequently attempt to construct the mission specification string when the mission is later triggered, with only the properties set in the missions table remaining immutable. The functions in this section are used to tell the mission manager what to put in the mission construction string.

mission_manager:add_new_objective is called to add a new objective to the mission. The first objective added is the primary objective; any further objectives added are treated as secondary/bonus objectives. Objective configuration functions such as mission_manager:add_condition and mission_manager:add_payload act on the most recently-added objective, so the ordering of these setup functions is important. At the very least at least one objective and one payload should be set using the functions below before the mission manager is triggered.

Missions may contain scripted objectives, where the script is responsible for their monitoring and completion. Scripted objectives are constructed from strings, and set the mission manager into a mode where it will construct all its objectives in this way. As such they cannot be used in combination with objectives from the database or from the missions.txt file.

A scripted objective may be added to the mission manager with mission_manager:add_new_scripted_objective, which sets some display text and an initial success monitor - some script which determines when the mission has been succeeded. Once a scripted objective has been added, additional success or failure monitors may be added with mission_manager:add_scripted_objective_success_condition and mission_manager:add_scripted_objective_failure_condition.

Scripted objectives may also be forceably succeeded or failed by external scripts calling mission_manager:force_scripted_objective_success or mission_manager:force_scripted_objective_failure, and their displayed text may be updated with mission_manager:update_scripted_objective_text.

If multiple scripted objectives are to be added they may optionally be individually named by giving them a script key. This allows individual target objectives to be specified when calling mission_manager:add_scripted_objective_success_condition, mission_manager:add_scripted_objective_failure_condition, mission_manager:force_scripted_objective_success or mission_manager:force_scripted_objective_failure, which will otherwise just target the first scripted objective in the mission.

As mentioned in the section on Persistence, setting a scripted objective forces the mission manager to be persistent, which means it must have a unique key and must be set up somewhere in the root of the script so that it's declared by the time the first tick happens after loading.

Persistent values may be stored and retrieved on a persistent mission manager. The mission manager will save those to the savegame and keep them available for client scripts to query even after the game has been reloaded. This can be useful if values important to the mission manager's working are only determined at the time that the mission manager is triggered, and can't be known when the mission manager is declared. For example, a Scripted Objectives mission to build x number of temples, where x is the number of temples held by a rival faction at the time the mission is issued, would need to store x in the savegame in order to re-establish the mission manager with the correct success conditions.

For example, a mission manager may establish its scripted conditions within a callback passed to mission_manager:add_each_time_trigger_callback which uses persistent values that are first generated when the mission is first triggered.o

Example:

If the mission manager is not set to generate its objectives from strings then it will fall back to one of two sources - from the missions.txt file which accompanies the campaign data or from database records. By default, the missions.txt file is used as the source of the mission - use mission_manager:set_is_mission_in_db, mission_manager:set_is_incident_in_db or mission_manager:set_is_dilemma_in_db to have the mission manager construct its mission objectives from the database instead. Doing this will require that records are present in various tables such as cdir_events_mission_option_junctions to allow the mission to fire (different but equivalent tables are used if the mission is actually an incident or a dilemma).