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:set_first_time_startup_callback and mission_manager:set_each_time_startup_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 campaign
Back to top

Different Methods of Specifying Objectives

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.

Back to top

Persistence

If a mission manager has been set up with a success, failure, cancellation or nearing-expiry callback with mission_manager:new, or if it has been set up with one or more Scripted Objectives with mission_manager:add_new_scripted_objective, then it is classified as persistent. Persistent mission managers must have unique names, and must be declared and set up in the root of the script somewhere, as they are restarted when the script loads from a savegame.

Additionally, a mission manager will need to be set up in the root of the script somewhere if an each-time-startup callback needs to be called - see mission_manager:set_each_time_startup_callback.

Back to top

Creation

mission_manager:new(
  string faction name,
  string mission key,
  [function success callback],
  [function failure callback],
  [function cancellation callback],
  [function nearing-expiry callback]
)
Creates a mission manager object. A faction name for the mission recipient and a mission key must be specified at the very least. The mission key must match a record in the missions table, which must be present in all cases.
A mission success callback, a mission failure callback, a mission cancellation callback and a mission nearing-expiry callback may optionally also be specified. Setting any of these also sets the mission to be persistent, which creates extra requirements for how the mission manager is declared - see the section above on Persistence.

Parameters:

1

string

Name of faction that will be receiving this mission.

2

string

Key corresponding to a record in the missions table.

3

function

optional, default value=nil

Callback to call if the mission is successfully completed. Setting this makes the mission manager persistent.

4

function

optional, default value=nil

Callback to call if the mission is failed. Setting this makes the mission manager persistent.

5

function

optional, default value=nil

Callback to call if the mission is cancelled. Setting this makes the mission manager persistent.

6

function

optional, default value=nil

Callback to call if the mission is nearing expiry. Setting this makes the mission manager persistent.

Returns:

  1. mission_manager Mission manager object

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 77

Back to top

Usage

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:

<mission_manager_object>:<function_name>(<args>)

Example - Creation and Usage:

local mm_emp_05 = mission_manager:new("wh_main_emp_empire", "wh_empire_mission_05");

-- calling a function on the object once created
mm_emp_05:set_first_time_startup_callback(function() out("mm_emp_05 starting") end)
Back to top

Global Configuration Options

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

mission_manager:set_should_cancel_before_issuing([boolean cancel before issuing])
When it goes to trigger the mission manager will, if the mission is persistent (see Persistence), issue a call to cancel any mission with the key specified in mission_manager:new before issuing its mission. This behaviour can be disabled, or enabled for non-persistent missions, by calling this function.

Parameters:

1

boolean

optional, default value=true

cancel before issuing

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 204

mission_manager:set_should_whitelist([boolean should whitelist])
When it goes to trigger the mission manager will, by default, add the relevant mission/dilemma/incident type to the event whitelist so that it triggers even if event messages are currently suppressed (see campaign_manager:suppress_all_event_feed_messages). Use this function to disable this behaviour, if required.

Parameters:

1

boolean

optional, default value=true

should whitelist

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 216

Back to top

Startup Callbacks

mission_manager:set_first_time_startup_callback(function callback)
Specifies a callback to call, one time, when the mission is first triggered. This can be used to set up other scripts or game objects for this mission.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 241

mission_manager:set_each_time_startup_callback(function callback)
Specifies a callback to call each time the script is started while this mission is active - after the mission is first triggered and before it's completed. This can be used to set up other scripts or game objects for this mission each time the script is loaded. If registered, this callback is also called when the mission is first triggered, albeit after any callback registered with mission_manager:set_first_time_startup_callback.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 254

Back to top

Constructing From Strings

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.

mission_manager:add_new_objective(string objective type)
Adds a new objective type to the mission specification, and also sets the mission manager to construct its mission from a string.
Multiple objectives may be added to a mission with this function. The first shall be the primary objective of the mission, while subsequent additions shall be set up as secondary objectives.

Parameters:

1

string

objective type

Returns:

  1. nil

Example:

mm:add_new_objective("CONSTRUCT_N_BUILDINGS_FROM")

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 284

mission_manager:add_condition(string condition)
Adds a condition to the objective last added with mission_manager:add_new_objective. Multiple conditions are commonly added - each objective type has different mandatory and optional conditions.

Parameters:

1

string

condition

Returns:

  1. nil

Example:

mm:add_condition("total 1")
mm:add_condition("building_level wh_main_emp_port_2")

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 307

mission_manager:add_payload(string payload)
Adds a payload (reward) to the objective last added with mission_manager:add_new_objective. Many different payload types exists - the following list is pulled from code: faction_pooled_resource_transaction, add_mercenary_to_faction_pool, adjust_loyalty_for_faction, province_slaves_change, faction_slaves_change, money, influence, honour, grant_unit, grant_agent, effect_bundle, rebellion, demolish_chain, damage_buildings, damage_character, building_restriction, unit_restriction, issue_mission, and game_victory. Each has a different parameter requirement - see existing examples or a programmer for more information.

Parameters:

1

string

payload

Returns:

  1. nil

Example - Adding money as a mission reward:

mm:add_payload("money 1000")

Example - Adding a pooled resource as a mission reward:

mm:add_payload("faction_pooled_resource_transaction{resource dwf_oathgold;factor wh2_main_resource_factor_missions;amount 10;}")

Example - Adding influence as a mission reward:

mm:add_payload("influence 5")

Example - Adding effect bundle as a mission reward:

mm:add_payload("effect_bundle{bundle_key wh_dlc06_bundle_eight_peaks_recapture;turns 0;}")

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 327

mission_manager:add_failure_payload(string payload)
Adds a payload (on mission faiure) to the objective last added with mission_manager:add_new_objective. Many different payload types exists - the following list is pulled from code: faction_pooled_resource_transaction, add_mercenary_to_faction_pool, adjust_loyalty_for_faction, province_slaves_change, faction_slaves_change, money, influence, honour, grant_unit, grant_agent, effect_bundle, rebellion, demolish_chain, damage_buildings, damage_character, building_restriction, unit_restriction, issue_mission, and game_victory. Each has a different parameter requirement - see existing examples or a programmer for more information.

Parameters:

1

string

payload

Returns:

  1. nil

Example - Taking away money as a mission failure:

mm:add_failure_payload("money -1000")

Example - Taking away a pooled resource as a mission failure:

mm:add_failure_payload("faction_pooled_resource_transaction{resource dwf_oathgold;factor wh2_main_resource_factor_missions;amount -10;}")

Example - Decreasing influence as a mission failure:

mm:add_failure_payload("influence -5")

Example - Adding effect bundle as a mission failure:

mm:add_failure_payload("effect_bundle{bundle_key wh_dlc06_bundle_eight_peaks_recapture;turns 0;}")

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 352

mission_manager:add_heading(string heading key)
Adds a heading key override for the objective last added with mission_manager:add_new_objective. This should be supplied as a string in the full localised text format [table]_[field]_[record].

Parameters:

1

string

heading key

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 377

mission_manager:add_description(string description key)
Adds a description key override for the objective last added with mission_manager:add_new_objective. This should be supplied as a string in the full localised text format [table]_[field]_[record].

Parameters:

1

string

description key

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 395

mission_manager:set_turn_limit(number turn limit)
Sets a turn limit for the entire mission. This is optional.

Parameters:

1

number

turn limit

Returns:

  1. nil

Example - Mission expires in 5 turns:

mm:set_turn_limit(5)

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 413

mission_manager:set_chapter(number chapter number)
Sets this mission to be a particular chapter mission, which affects how it is displayed and categorised on the UI.

Parameters:

1

number

chapter number

Returns:

  1. nil

Example - Mission is first chapter mission:

mm:set_chapter(1)

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 428

mission_manager:set_mission_issuer(string mission issuer)
Sets an issuer for this mission, which determines some aspects of the mission's presentation. By default this is set to "CLAN_ELDERS", but use this function to change this. A list of valid mission issuers can be found in the mission_issuers table.

Parameters:

1

string

mission issuer

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 443

Back to top

Scripted Objectives

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.

mission_manager:add_new_scripted_objective(
  string display text,
  string event,
  function condition,
  [string script name]
)
Adds a new scripted objective, along with some text to display, a completion event and condition to monitor. An optional script name for this objective may also be specified, which can be useful if there is more than one objective.

Parameters:

1

string

Display text for this objective. This should be supplied as a full localisation key, i.e. [table]_[field]_[key].

2

string

Script event name of mission success condition.

3

function

A function that returns a boolean value when called. The function will be passed the context of the event specified in the second parameter. Alternatively, if no conditional test needs to be performed then true may be supplied in place of a function block.

While the mission is active the mission manager listens for the event specified in the second parameter. When it is received, the condition specified here is called. If it returns true, or if true was specified in place of a condition function, the mission objective is marked as being successfully completed.

4

string

optional, default value=nil

Script name for this objective. If specified, this allows calls to 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 to target this objective (they target the first objective by default).

Returns:

  1. nil

Example:

An example scripted objective that is completed when the player researches a technology.
mm:add_new_scripted_objective(
    "mission_text_text_research_technology_mission_objective",
    "ResearchCompleted",
    function(context)
        return context:faction():name() == cm:get_local_faction_name();
    end;
);

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 474

mission_manager:add_scripted_objective_success_condition(
  string event,
  function condition,
  [string script name]
)
Adds a new success condition to a scripted objective. scripted objective. If a script key is specified the success condition is added to the objective with this key (assuming it exists), otherwise the success condition is added to the first scripted objective.

Parameters:

1

string

Script event name of mission success condition.

2

function

A function that returns a boolean value when called. The function will be passed the context of the event specified in the second parameter. Alternatively, if no conditional test needs to be performed then true may be supplied in place of a function block.

While the mission is active the mission manager listens for the event specified in the second parameter. When it is received, the condition specified here is called. If it returns true, or if true was specified in place of a condition function, the mission objective is marked as being successfully completed.

3

string

optional, default value=nil

Script name of the scripted objective to append this success condition to.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 529

mission_manager:add_scripted_objective_failure_condition(
  string event,
  function condition,
  [string script name]
)
Adds a new failure condition to a scripted objective. scripted objective. If a script key is specified the failure condition is added to the objective with this key (assuming it exists), otherwise the failure condition is added to the first scripted objective.

Parameters:

1

string

Script event name of mission failure condition.

2

function

A function that returns a boolean value when called. The function will be passed the context of the event specified in the second parameter. Alternatively, if no conditional test needs to be performed then true may be supplied in place of a function block.

While the mission is active the mission manager listens for the event specified in the second parameter. When it is received, the condition specified here is called. If it returns true, or if true was specified in place of a condition function, the mission objective is marked as being failed.

3

string

optional, default value=nil

Script name of the scripted objective to append this failure condition to.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 540

mission_manager:force_scripted_objective_success([string script name])
Immediately forces the success of a scripted objective. A particular scripted objective may be specified by supplying a script key, otherwise this function will target the first scripted objective in the mission manager.
This should only be called after the mission manager has been triggered.

Parameters:

1

string

optional, default value=nil

Script name of the scripted objective to force the success of.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 620

mission_manager:force_scripted_objective_failure([string script name])
Immediately forces the failure of a scripted objective. A particular scripted objective may be specified by supplying a script key, otherwise this function will target the first scripted objective in the mission manager.
This should only be called after the mission manager has been triggered.

Parameters:

1

string

optional, default value=nil

Script name of the scripted objective to force the failure of.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 629

mission_manager:update_scripted_objective_text(string display text, [string script name])
Updates the displayed objective text of a scripted objective. This can be useful if some counter needs to be updated as progress towards an objective is made. A particular scripted objective may be specified by supplying a script key, otherwise this function will target the first scripted objective in the mission manager.
This should only be called after the mission manager has been triggered.

Parameters:

1

string

Display text for this objective. This should be supplied as a full localisation key, i.e. [table]_[field]_[key].

2

string

optional, default value=nil

Script name of the scripted objective to update the key of.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 664

Back to top

Sourcing Objectives from Database

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

mission_manager:set_is_mission_in_db()
Sets that the mission objectives should be constructed from records in the game database.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 704

mission_manager:set_is_incident_in_db()
Sets that the mission objectives should be constructed from records in the game database, and that the mission is actually an incident.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 715

mission_manager:set_is_dilemma_in_db([boolean is intervention])

Sets that the mission objectives should be constructed from records in the game database, and that the mission is actually a dilemma.

Parameters:

1

boolean

optional, default value=false

Is a dilemma in an intervention. If this is set to true, the dilemma will be triggered directly using campaign_manager:trigger_dilemma_raw, which can cause softlocks when triggered from outside of an intervention. If set to false or left blank then the dilemma will be triggered in campaign_manager:trigger_dilemma which attempts to package the dilemma in an intervention.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 726

Back to top

Querying

mission_manager:has_been_triggered()
Returns true if the mission manager has been triggered in the past, false otherwise. If triggered it might not still be running, as the mission could have been completed.

Returns:

  1. boolean is started

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 757

mission_manager:is_completed()
Returns true if the mission has been completed, false otherwise. Success, failure or cancellation all count as completion.

Returns:

  1. boolean is completed

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 765

Back to top

Triggering

mission_manager:trigger([function dismiss callback], [number callback delay])
Triggers the mission, causing it to be issued.

Parameters:

1

function

optional, default value=nil

Dismiss callback. If specified, this is called when the event panel is dismissed.

2

number

optional, default value=nil

Dismiss callback delay, in seconds. If specified this introduces a delay between the event panel being dismissed and the dismiss callback being called.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 791

mission_manager:cancel_dismiss_callback_listeners()
Cancels any listeners associated with the dismiss callback added with mission_manager:trigger. Call this to prevent the mission manager responding to the event panel being closed (it will only do so if a dismiss callback was added).

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_mission_manager.lua, line 916

Last updated 07/02/21 06:39:14