Campaign Manager

The campaign manager is the main interface object in the campaign scripting environment. It wraps the primary episodic_scripting game interface that the campaign model provides to script, as well as providing a myriad of features and quality-of-life improvements in its own right. Any calls made to the campaign manager that it doesn't provide itself are passed through to the episodic_scripting interface. The is the intended route for calls to the episodic_scripting interface to be made.

Asides from the episodic_scripting interface provided through the campaign manager, and the campaign manager interface itself (documented below), the main campaign interfaces provided by code are collectively called the model hierarchy. These allow scripts to query the state of the model at any time, and are documented here.

A campaign manager object, called cm in script, is automatically created when the scripts load in campaign configuration.

Loaded in Campaign loaded in campaign
Back to top

Creation

A campaign manager is automatically created when the script libraries are loaded - see the page on campaign_script_structure - so there should be no need for client scripts to call campaign_manager:new themselves. The campaign manager object created is called cm, which client scripts can make calls on.

campaign_manager:new([string campaign name])

Creates and returns a campaign manager. If one has already been created it returns the existing campaign manager. Client scripts should not need to call this as it's already called, and a campaign manager set up, within the script libraries. However the script libraries cannot know the name of the campaign, so client scripts will need to set this using campaign_manager:set_campaign_name.

Parameters:

1

string

optional, default value=""

campaign name

Returns:

  1. campaign_manager campaign manager

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 217

Back to top

Usage

Once created, which happens automatically when the script libraries are loaded, functions on the campaign manager object may be called in the form showed below.

Example - Specification:

cm:<function_name>(<args>)

Example - Creation and Usage:

cm = campaign_manager:new()        -- object automatically set up by script libraries

-- within campaign script
cm:set_campaign_name("test_campaign")
Back to top

Campaign Name

Client scripts should set a name for the campaign using campaign_manager:set_campaign_name before making other calls. This name is used for output and for loading campaign scripts.

campaign_manager:set_campaign_name(string campaign name)

Sets the name of the campaign. This is used for some output, but is mostly used to determine the file path to the campaign script folder which is partially based on the campaign name. If the intention is to use campaign_manager:require_path_to_campaign_folder or campaign_manager:require_path_to_campaign_faction_folder to load in script files from a path based on the campaign name, then a name must be set first. The name may also be supplied to campaign_manager:new when creating the campaign manager.

Parameters:

1

string

campaign name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 499

campaign_manager:get_campaign_name()

Returns the name of the campaign.

Returns:

  1. string campaign name

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 513

Back to top

Loading Campaign Script Files

One important role of the campaign manager is to assist in the loading of script files related to the campaign. By current convention, campaign scripts are laid out in the following structure:

script/campaign/scripts related to all campaigns
script/campaign/%campaign_name%/scripts related to the current campaign
script/campaign/%campaign_name%/factions/%faction_name%/scripts related to a particular faction in the current campaign (when that faction is being played)

The functions in this section allow the paths to these script files to be derived from the campaign/faction name, and for scripts to be loaded in. campaign_manager:load_local_faction_script is the easiest method for loading in scripts related to the local faction. campaign_manager:load_global_script is a more general-purpose function to load a script with access to the global environment.

campaign_manager:get_campaign_folder()

Returns a static path to the campaign script folder (currently "data/script/campaign")

Returns:

  1. string campaign folder path

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 536

campaign_manager:require_path_to_campaign_folder()

Adds the current campaign's folder to the path, so that the lua files related to this campaign can be loaded with the require command. This function adds the root folder for this campaign based on the campaign name i.e. script/campaign/%campaign_name%/, and also the factions subfolder within this. A name for this campaign must have been set with campaign_manager:new or campaign_manager:set_campaign_name prior to calling this function.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 544

campaign_manager:require_path_to_campaign_faction_folder()

Adds the player faction's script folder for the current campaign to the lua path (script/campaign/%campaign_name%/factions/%player_faction_name%/), so that scripts related to the faction can be loaded with the require command. Unlike campaign_manager:require_path_to_campaign_folder this can only be called after the game state has been created. A name for this campaign must have been set with campaign_manager:new or campaign_manager:set_campaign_name prior to calling this function.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 558

campaign_manager:load_global_script(string script name, [boolean single player only])

This function attempts to load a lua script from all folders currently on the path, and, when loaded, sets the environment of the loaded file to match the global environment. This is used when loading scripts within a block (within if statement that is testing for the file's existence, for example) - loading the file with require would not give it access to the global environment.
Call campaign_manager:require_path_to_campaign_folder and/or campaign_manager:require_path_to_campaign_faction_folder if required to include these folders on the path before loading files with this function, if required. Alternatively, use campaign_manager:load_local_faction_script for a more automated method of loading local faction scripts.
If the script file fails to load cleanly, a script error will be thrown.

Parameters:

1

string

script name

2

boolean

optional, default value=false

single player only

Returns:

  1. nil

Example - Loading faction script:

This script snippet requires the path to the campaign faction folder, then loads the "faction_script_loader" script file, when the game is created.
cm:add_pre_first_tick_callback(
    function()    
        if cm:get_local_faction(true) then
            cm:require_path_to_campaign_faction_folder();

            if cm:load_global_script("faction_script_loader") then
                out("Faction scripts loaded");
            end;
        end;
    end
);
Faction scripts loaded

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 583

campaign_manager:load_local_faction_script(string script name appellation)

Loads a script file in the factions subfolder that corresponds to the name of the local player faction, with the supplied string appellation attached to the end of the script filename. This function is the preferred method for loading in local faction-specific script files. It calls campaign_manager:require_path_to_campaign_faction_folder internally to set up the path, and uses campaign_manager:load_global_script to perform the loading. It must not be called before the game is created.

Parameters:

1

string

script name appellation

Returns:

  1. nil

Example:

Assuming a faction named fact_example in a campaign named main_test, the following script would load in the script file script/campaigns/main_test/factions/fact_example/fact_example_start.lua.
cm:add_pre_first_tick_callback(
    function()
        cm:load_local_faction_script("_start");
    end
);

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 644

campaign_manager:load_exported_files(string filename, [string path])

Loads all lua script files with filenames that contain the supplied string from the target directory. This is used to load in exported files e.g. export_ancillaries.lua, as the asset graph system may create additional files with an extension of this name for each DLC, where needed (e.g. export_ancillaries_dlcxx.lua). The target directory is "script" by default.

Parameters:

1

string

Filename subset of script file(s) to load.

2

string

optional, default value="script"

Path of directory to load script files from, from working data. This should be supplied without leading or trailing "/" separators.

Returns:

  1. nil

Example:

Assuming a faction named fact_example in a campaign named main_test, the following script would load in the script file script/campaigns/main_test/factions/fact_example/fact_example_start.lua.

Example:

Loads all script files from the "script" folder which contain "export_triggers" as a subset of their name.
cm:load_exported_files("export_triggers")

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 691

Back to top

Loading Game

Early in the campaign loading sequence the LoadingGame event is triggered by the game code, even when starting a new game. At this time, scripts are able to load script values saved into the savegame using campaign_manager:load_named_value. These values can then be used by client scripts to set themselves into the correct state.

Functions that perform the calls to campaign_manager:load_named_value may be registered with campaign_manager:add_loading_game_callback, so that they get called when the LoadingGame event is triggered.

The counterpart function to campaign_manager:load_named_value is campaign_manager:save_named_value, which is used when the game saves to save values to the save file.

See also campaign_manager:set_saved_value and campaign_manager:get_saved_value, which can be used at any time by client scripts to read and write values that will automatically saved and loaded to the save game.

In the game loading sequence, the LoadingGame event is received before the game is created and the first tick.

Example:

cm:add_loading_game_callback(
    function(context)
        player_progression = cm:load_named_value("player_progression", 0, context);
    end
)

campaign_manager:add_loading_game_callback(function callback)

Adds a callback to be called when the LoadingGame event is received from the game. This callback will be able to load information from the savegame with campaign_manager:load_named_value. See also campaign_manager:add_saving_game_callback and campaign_manager:save_named_value to save the values that will be loaded here.
Note that it is preferable for client scripts to use this function rather than listen for the LoadingGame event themselves as it preserves the ordering of certain setup procedures.

Parameters:

1

function

Callback to call. When calling this function the campaign manager passes it a single context argument, which can then be passed through in turn to campaign_manager:load_named_value.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 798

campaign_manager:load_named_value(string value name, object default value, userdata context)

Loads a named value from the savegame. This may only be called as the game is being loaded, and must be passed the context object supplied by the LoadingGame event. Values are saved and loaded from the savegame with a string name, and the values themselves can be a boolean, a number, a string, or a table containing booleans, numbers or strings.

Parameters:

1

string

Value name. This must be unique within the savegame, and should match the name the value was saved with, with campaign_manager:save_named_value.

2

object

Default value, in case the value could not be loaded from the savegame. The default value supplied here is used to determine/must match the type of the value being loaded.

3

userdata

Context object supplied by the LoadingGame event.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 883

campaign_manager:get_saved_value(string value name)

Retrieves a value saved using the saved value system. Values saved using campaign_manager:set_saved_value are added to an internal register within the campaign manager, and are automatically saved and loaded with the game, so there is no need to register callbacks with campaign_manager:add_loading_game_callback or campaign_manager:add_saving_game_callback. Once saved with campaign_manager:set_saved_value, values can be accessed with this function.
Values are stored and accessed by a string name. Values can be booleans, numbers or strings.

Parameters:

1

string

value name

Returns:

  1. object value

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 929

campaign_manager:get_cached_value(string value name, function generator callback)

Retrieves or generates a value saved using the saved value system. When called, the function looks up a value by supplied name using campaign_manager:get_saved_value. If it exists it is returned, but if it doesn't exist a supplied function is called which generates the cached value. This value is saved with the supplied name, and also returned. A value is generated the first time this function is called, therefore, and is retrieved from the savegame on subsequent calls with the same arguments. If the supplied function doesn't return a value, a script error is triggered.

Parameters:

1

string

value name

2

function

generator callback

Returns:

  1. object value

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 939

Back to top

Saving Game

These are the complementary functions to those in the Loading Game section. When the player saves the game, the SavingGame event is triggered by the game. At this time, variables may be saved to the savegame using campaign_manager:save_named_value. Callbacks that make calls to this function may be registered with campaign_manager:add_saving_game_callback, so that they get called at the correct time.

campaign_manager:add_saving_game_callback(function callback)

Registers a callback to be called when the game is being saved. The callback can then save individual values with campaign_manager:save_named_value.

Parameters:

1

function

Callback to call. When calling this function the campaign manager passes it a single context argument, which can then be passed through in turn to campaign_manager:save_named_value.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1065

campaign_manager:add_post_saving_game_callback(function callback)

Add a callback to be called after the game has been saved. These callbacks are called last in the saving sequence, and only the first time the game is saved after they have been added.

Parameters:

1

function

Callback to call. When calling this function the campaign manager passes it a single context argument.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1078

campaign_manager:save_named_value(string value name, object value, userdata context)

Saves a named value from the savegame. This may only be called as the game is being saved, and must be passed the context object supplied by the SavingGame event. Values are saved (and loaded) from the savegame with a string name, and the values themselves can be a boolean, a number, a string, or a table containing booleans, numbers or strings.

Parameters:

1

string

Value name. This must be unique within the savegame, and will be used by campaign_manager:load_named_value later to load the value.

2

object

Value to save.

3

userdata

Context object supplied by the SavingGame event.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1153

campaign_manager:set_saved_value(string value name, object value)

Sets a value to be saved using the saved value system. Values saved using this function are added to an internal register within the campaign manager, and are automatically saved and loaded with the game, so there is no need to register callbacks with campaign_manager:add_loading_game_callback or campaign_manager:add_saving_game_callback. Once saved with this function, the value can be accessed at any time with campaign_manager:get_saved_value.
Values are stored and accessed by a string name. Values can be booleans, numbers or strings. Repeated calls to set_saved_value with the same name are legal, and will just overwrite the value of the value stored with the supplied name.

Parameters:

1

string

Value name.

2

object

Value. Can be a boolean, number or string.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1225

campaign_manager:save([function callback], [boolean lock afterwards])

Instructs the campaign game to save at the next opportunity. An optional completion callback may be supplied.

Parameters:

1

function

optional, default value=nil

Completion callback. If supplied, this is called when the save procedure is completed.

2

boolean

optional, default value=false

Lock saving functionality after saving is completed.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1262

Back to top

Game Destroyed

campaign_manager:add_game_destroyed_callback(function callback)

Registers a function to be called when the campaign is shut down or unloaded for any reason (including loading into battle). It is seldom necessary to do this.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1303

Back to top

First Tick

The FirstTickAfterWorldCreated event is triggered by the game model when loading is complete and it starts to run time forward. At this point, the game can be considered "running". The campaign manager offers a suite of functions, listed in this section, which allow registration of callbacks to get called when the first tick occurs in a variety of situations e.g. new versus loaded campaign, singleplayer versus multiplayer etc.

Callbacks registered with campaign_manager:add_pre_first_tick_callback are called before any other first-tick callbacks. Next to be called are callbacks registered for a new game with campaign_manager:add_first_tick_callback_new, campaign_manager:add_first_tick_callback_sp_new or campaign_manager:add_first_tick_callback_mp_new, which are called before each-game callbacks registered with campaign_manager:add_first_tick_callback_sp_each or campaign_manager:add_first_tick_callback_mp_each. Last to be called are global first-tick callbacks registered with campaign_manager:add_first_tick_callback.

Note that when the first tick occurs the loading screen is likely to still be on-screen, so it may be prudent to stall scripts that wish to display things on-screen with core:progress_on_loading_screen_dismissed.

campaign_manager:add_pre_first_tick_callback(function callback)

Registers a function to be called before any other first tick callbacks. Callbacks registered with this function will be called regardless of what mode the campaign is being loaded in.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1360

campaign_manager:add_first_tick_callback(function callback)

Registers a function to be called when the first tick occurs. Callbacks registered with this function will be called regardless of what mode the campaign is being loaded in.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1373

campaign_manager:add_first_tick_callback_sp_new(function callback)

Registers a function to be called when the first tick occurs in a new singleplayer game.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1386

campaign_manager:add_first_tick_callback_sp_each(function callback)

Registers a function to be called when the first tick occurs in a singleplayer game, whether new or loaded from a savegame.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1399

campaign_manager:add_first_tick_callback_mp_new(function callback)

Registers a function to be called when the first tick occurs in a new multiplayer game.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1412

campaign_manager:add_first_tick_callback_mp_each(function callback)

Registers a function to be called when the first tick occurs in a multiplayer game, whether new or loaded from a savegame.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1425

campaign_manager:add_first_tick_callback_new(function callback)

Registers a function to be called when the first tick occurs in a new game, whether singleplayer or multiplayer.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1438

Back to top

Output

campaign_manager:output_campaign_obj(object campaign object)

Prints information about certain campaign objects (characters, regions, factions or military force) to the debug console spool. Preferably don't call this - just call out(object) insead.

Parameters:

1

object

campaign object

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1604

campaign_manager:campaign_obj_to_string(object campaign object)

Returns a string summary description when passed certain campaign objects. Supported object types are character, region, faction, military force, and unit.

Parameters:

1

object

campaign object

Returns:

  1. string summary of object

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1893

Back to top

Timer Callbacks

The functions in this section provide the ability to register callbacks to call after a supplied duration. The interface provided is similar to that provided by a timer_manager in battle, but the underlying campaign timer architecture is different enough to preclude the use of a timer_manager.

campaign_manager:callback(function callback to call, number time, [string name])

Calls the supplied function after the supplied period in seconds. A string name for the callback may optionally be provided to allow the callback to be cancelled later.
If part or all of the interval is likely to elapse during the end turn sequence, consider using campaign_manager:os_clock_callback as time does not behave as expected during the end turn sequence.

Parameters:

1

function

callback to call

2

number

Time in seconds after to which to call the callback. The model ticks ten times a second so it doesn't have an effective resolution greater than this.

3

string

optional, default value=nil

Callback name. If supplied, this callback can be cancelled at a later time (before it triggers) with campaign_manager:remove_callback.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1943

campaign_manager:repeat_callback(function callback to call, number time, [string name])

Calls the supplied function repeatedly after the supplied period in seconds. A string name for the callback may optionally be provided to allow the callback to be cancelled. Cancelling the callback is the only method to stop a repeat callback, once started.

Parameters:

1

function

callback to call

2

number

Time in seconds after to which to call the callback, repeatedly. The callback will be called each time this interval elapses. The model ticks ten times a second so it doesn't have an effective resolution greater than this.

3

string

optional, default value=nil

Callback name. If supplied, this callback can be cancelled at a later time with campaign_manager:remove_callback.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1954

campaign_manager:os_clock_callback(function callback to call, number time, [string name])

Time in campaign behaves strangely during the end-turn sequence, and callbacks registered with campaign_manager:callback will tend to be called immediately rather than after the desired interval. This function works around the problem by polling the operating system clock to check that the desired duration has indeed elapsed before calling the supplied callback. It is less accurate and more expensive than campaign_manager:callback, but will produce somewhat sensible results during the end-turn sequence.

Parameters:

1

function

callback to call

2

number

Time in seconds after to which to call the callback.

3

string

optional, default value=nil

Callback name. If supplied, this callback can be cancelled at a later time with campaign_manager:remove_callback.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 1996

campaign_manager:remove_callback([string name])

Removes all pending callbacks that matches the supplied name.

Parameters:

1

string

optional, default value=nil

Callback name to remove.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2016

campaign_manager:dump_timers()

Prints information about all timers to the console debug spool.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2051

Back to top

General Querying

campaign_manager:is_multiplayer()

Returns true if the campaign is multiplayer.

Returns:

  1. boolean is multiplayer campaign

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2083

campaign_manager:is_new_game()

Returns true if the campaign is new. A campaign is "new" if it has been saved only once before - this save occurs during startpos processing.
Note that if the script fails during startpos processing, the counter will not have been saved and it's value will be 0 - in this case, the game may report that it's not new when it is. If you experience a campaign that behaves as if it's loading into a savegame when starting from fresh, it's probably because the script failed during startpos processing.

Returns:

  1. boolean is new game

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2096

campaign_manager:is_game_running()

Returns whether or not the game is loaded and time is ticking.

Returns:

  1. boolean is game started

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2110

campaign_manager:model()

Returns a handle to the game model at any time (after the game has been created). The game model is currently documented here

Returns:

  1. object model

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2118

campaign_manager:get_game_interface()

Returns a handle to the raw episodic scripting interface. Generally it's not necessary to call this function, as calls made on the campaign manager which the campaign manager doesn't itself provide are passed through to the episodic scripting interface, but a direct handle to the episodic scripting interface may be sought with this function if speed of repeated access.

Returns:

  1. object game_interface

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2131

campaign_manager:get_difficulty([boolean return as string])

Returns the current combined campaign difficulty. This is returned as an integer value by default, or a string if a single true argument is passed in.
stringnumber
easy1
normal2
hard3
very hard4
legendary5
Note that the numbers returned above are different from those returned by the combined_difficulty_level() function on the campaign model.

Parameters:

1

boolean

optional, default value=false

return as string

Returns:

  1. object difficulty integer or string

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2144

campaign_manager:get_local_faction([boolean force result])

Returns the local player faction name. This must be called after the game is created. Beware of using this in multiplayer - making changes to the model based on the identity of the local faction is a fast route to causing a desync. If called in multiplayer the function throws a script error and fails, unless true is passed in as an argument to force the result. In doing so, the calling script acknowledges the risk.

Parameters:

1

boolean

optional, default value=false

force result

Returns:

  1. string local faction name

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2200

campaign_manager:get_human_factions()

Returns a numerically-indexed table containing the string keys of all human factions within the game.

Returns:

  1. table human factions

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2219

campaign_manager:are_any_factions_human(table faction list, boolean tolerate errors)

Returns whether any factions in the supplied list are human. The faction list should be supplied as a numerically-indexed table of either faction keys or faction script objects.

Parameters:

1

table

Numerically-indexed table of string faction keys or faction script objects.

2

boolean

Sets the function to tolerate errors, where it won't throw a script error and return if any of the supplied data is incorrectly formatted.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2238

campaign_manager:whose_turn_is_it()

Returns the faction key of the faction whose turn it is currently.

Returns:

  1. string faction key

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2275

campaign_manager:is_local_players_turn()

Returns true if it's the local player's turn.

Returns:

  1. boolean is local player's turn

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2283

campaign_manager:is_processing_battle()

Returns true if a battle is currently happening on-screen. This is set to true when the pre-battle panel opens, and is set to false when the battle sequence is over and any related camera animations have finished playing.

Returns:

  1. boolean battle is happening

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2291

campaign_manager:turn_number()

Returns the turn number, including any modifier set with campaign_manager:set_turn_number_modifier

Returns:

  1. number turn number

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2299

campaign_manager:set_turn_number_modifier(number modifier)

Sets a turn number modifier. This offsets the result returned by campaign_manager:turn_number by the supplied modifier. This is useful for campaign setups which include optional additional turns (e.g. one or two turns at the start of a campaign to teach players how to play the game), but still wish to trigger events on certain absolute turns. For example, some script may wish to trigger an event on turn five of a standard campaign, but this would be turn six if a one-turn optional tutorial at the start of the campaign was played through - in this case a turn number modifier of 1 could be set if not playing through the tutorial.

Parameters:

1

number

modifier

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2307

campaign_manager:null_interface()

Returns a scripted-generated object that emulates a campaign null interface.

Returns:

  1. null_interface

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2320

campaign_manager:help_page_seen(string help page name)

Returns whether the advice history indicates that a specific help page has been viewed by the player.

Parameters:

1

string

help page name

Returns:

  1. boolean help page viewed

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2332

Back to top

Building Queries & Modification

campaign_manager:building_exists_in_province(string building key, string province key)

Returns whether the supplied building exists in the supplied province.

Parameters:

1

string

building key

2

string

province key

Returns:

  1. boolean building exist

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2354

Back to top

Character Queries & Modification

campaign_manager:get_garrison_commander_of_region(region region object)

Returns the garrison commander character of the settlement in the supplied region.

Parameters:

1

region

region object

Returns:

  1. character garrison commander

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2397

campaign_manager:get_closest_general_to_position_from_faction(
  object
faction,
  number
x,
  number
y,
  [boolean
include garrison commanders]
)

Returns the general within the supplied faction that's closest to the supplied logical co-ordinates.

Parameters:

1

object

Faction specifier. This can be a faction object or a string faction name.

2

number

Logical x co-ordinate.

3

number

Logical y co-ordinate.

4

boolean

optional, default value=false

Includes garrison commanders in the search results if set to true.

Returns:

  1. character closest character

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2432

campaign_manager:get_closest_character_to_position_from_faction(
  object
faction,
  number
x,
  number
y,
  [boolean
general characters only],
  [boolean
include garrison commanders]
)

Returns the character within the supplied faction that's closest to the supplied logical co-ordinates.

Parameters:

1

object

Faction specifier. This can be a faction object or a string faction name.

2

number

Logical x co-ordinate.

3

number

Logical y co-ordinate.

4

boolean

optional, default value=false

Restrict search results to generals.

5

boolean

optional, default value=false

Includes garrison commanders in the search results if set to true.

Returns:

  1. character closest character

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2444

campaign_manager:get_general_at_position_all_factions(number x, number y)

Returns the general character stood at the supplied position, regardless of faction. Garrison commanders are not returned.

Parameters:

1

number

Logical x co-ordinate.

2

number

Logical y co-ordinate.

Returns:

  1. character general character

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2508

campaign_manager:get_character_by_cqi(number cqi)

Returns a character by it's command queue index. If no character with the supplied cqi is found then false is returned.

Parameters:

1

number

cqi

Returns:

  1. character character

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2538

campaign_manager:get_military_force_by_cqi(number cqi)

Returns a military force by it's command queue index. If no military force with the supplied cqi is found then false is returned.

Parameters:

1

number

cqi

Returns:

  1. military_force military force

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2561

campaign_manager:get_character_by_mf_cqi(number military force cqi)

Returns the commander of a military force by the military force's command queue index. If no military force with the supplied cqi is found or it has no commander then false is returned.

Parameters:

1

number

military force cqi

Returns:

  1. character general character

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2584

campaign_manager:char_display_pos(character character)

Returns the x/y display position of the supplied character.

Parameters:

1

character

character

Returns:

  1. number x display co-ordinate
  2. number y display co-ordinate

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2599

campaign_manager:char_logical_pos(character character)

Returns the x/y logical position of the supplied character.

Parameters:

1

character

character

Returns:

  1. number x logical co-ordinate
  2. number y logical co-ordinate

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2614

campaign_manager:character_is_army_commander(character character)

Returns true if the character is a general at the head of a moveable army (not a garrison), false otherwise.

Parameters:

1

character

character

Returns:

  1. boolean is army commander

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2629

campaign_manager:char_lookup_str(object character or character cqi)

Various game interface functions lookup characters using a lookup string. This function converts a character into a lookup string that can be used by code functions to find that same character. It may also be supplied a character cqi in place of a character object.

Parameters:

1

object

character or character cqi

Returns:

  1. string lookup string

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2649

campaign_manager:char_in_owned_region(character character)

Returns true if the supplied character is in a region their faction controls, false otherwise.

Parameters:

1

character

character

Returns:

  1. boolean stood in owned region

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2667

campaign_manager:char_has_army(character character)

Returns true if the supplied character has a land army military force, false otherwise.

Parameters:

1

character

character

Returns:

  1. boolean has army

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2676

campaign_manager:char_has_navy(character character)

Returns true if the supplied character has a navy military force, false otherwise.

Parameters:

1

character

character

Returns:

  1. boolean has navy

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2685

campaign_manager:char_is_agent(character character)

Returns true if the supplied character is not a general, a colonel or a minister, false otherwise.

Parameters:

1

character

character

Returns:

  1. boolean is agent

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2694

campaign_manager:char_is_general(character character)

Returns true if the supplied character is of type 'general', false otherwise.

Parameters:

1

character

character

Returns:

  1. boolean is general

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2703

campaign_manager:char_is_victorious_general(character character)

Returns true if the supplied character is a general that has been victorious (when?), false otherwise.

Parameters:

1

character

character

Returns:

  1. boolean is victorious general

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2712

campaign_manager:char_is_defeated_general(character character)

Returns true if the supplied character is a general that has been defeated (when?), false otherwise.

Parameters:

1

character

character

Returns:

  1. boolean is defeated general

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2721

campaign_manager:char_is_general_with_army(character character)

Returns true if the supplied character is a general and has an army, false otherwise. This includes garrison commanders - to only return true if the army is mobile use campaign_manager:char_is_mobile_general_with_army.

Parameters:

1

character

character

Returns:

  1. boolean is general with army

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2730

campaign_manager:char_is_mobile_general_with_army(character character)

Returns true if the supplied character is a general, has an army, and can move around the campaign map, false otherwise.

Parameters:

1

character

character

Returns:

  1. boolean is general with army

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2739

campaign_manager:char_is_general_with_navy(character character)

Returns true if the supplied character is a general with a military force that is a navy, false otherwise.

Parameters:

1

character

character

Returns:

  1. boolean is general with navy

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2748

campaign_manager:char_is_governor(character character)

Returns true if the supplied character is the governor of a region, false otherwise.

Parameters:

1

character

character

Returns:

  1. boolean is governor

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2757

campaign_manager:char_is_in_region_list(character character, table table of region keys)

Returns true if the supplied character is currently in any region from a supplied list, false otherwise.

Parameters:

1

character

character

2

table

table of region keys

Returns:

  1. boolean is in region list

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2766

campaign_manager:get_closest_visible_character_of_subculture(string faction key, string subculture key)

Returns the closest character of the supplied subculture to the supplied faction. The subculture and faction are both specified by string key.
Use this function sparingly, as it is quite expensive.

Parameters:

1

string

faction key

2

string

subculture key

Returns:

  1. character closest visible character

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2776

campaign_manager:get_closest_character_from_faction(faction faction, number x, number y)

Returns the closest character from the supplied faction to the supplied position. This includes characters such as politicians and garrison commanders that are not extant on the map.

Parameters:

1

faction

faction

2

number

x

3

number

y

Returns:

  1. character closest character

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2827

campaign_manager:character_can_reach_character(character source character, character target character)

Returns true if the supplied source character can reach the supplied target character this turn, false otherwise. The underlying test on the model interface returns false-positives if the source character has no action points - this wrapper function works around this problem by testing the source character's action points too.

Parameters:

1

character

source character

2

character

target character

Returns:

  1. boolean can reach

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2853

campaign_manager:character_can_reach_settlement(character source character, settlement target settlement)

Returns true if the supplied source character can reach the supplied target settlement this turn, false otherwise. The underlying test on the model interface returns false-positives if the source character has no action points - this wrapper function works around this problem by testing the source character's action points too.

Parameters:

1

character

source character

2

settlement

target settlement

Returns:

  1. boolean can reach

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2873

campaign_manager:general_with_forename_exists_in_faction_with_force(
  string
faction key,
  string
forename key
)

Returns true if a general with a mobile military force exists in the supplied faction with the supplied forename. Faction and forename are specified by string key.

Parameters:

1

string

Faction key.

2

string

Forename key in the full localisation lookup format i.e. [table]_[column]_[record_key].

Returns:

  1. boolean general exists

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2893

campaign_manager:get_highest_ranked_general_for_faction(object faction)

Returns the general character in the supplied faction of the highest rank. The faction may be supplied as a faction object or may be specified by key.

Parameters:

1

object

Faction, either by faction object or by string key.

Returns:

  1. character highest ranked character

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2919

campaign_manager:remove_all_units_from_general(character general character)

Removes all units from the military force the supplied general character commands.

Parameters:

1

character

general character

Returns:

  1. number number of units removed

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 2961

Back to top

Faction Queries & Modification

campaign_manager:get_faction(string faction key)

Gets a faction object by its string key. If no faction with the supplied key could be found then false is returned.

Parameters:

1

string

faction key

Returns:

  1. faction faction

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3003

campaign_manager:faction_contains_building(faction faction object, string building key)

Returns true if territories controlled by the supplied faction contain the supplied building. This won't work for horde buildings.

Parameters:

1

faction

faction object

2

string

building key

Returns:

  1. faction contains building

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3023

campaign_manager:num_characters_of_type_in_faction(faction faction object, string character type)

Returns the number of characters of the supplied type in the supplied faction.

Parameters:

1

faction

faction object

2

string

character type

Returns:

  1. number number of characters

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3048

campaign_manager:kill_all_armies_for_faction(faction faction object)

Kills all armies in the supplied faction.

Parameters:

1

faction

faction object

Returns:

  1. number number of armies killed

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3076

campaign_manager:get_trespasser_list_for_faction(faction faction object)

Returns a table of cqis of characters that are both at war with the specified faction and also trespassing on its territory.

Parameters:

1

faction

faction object

Returns:

  1. table of character command queue indexes

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3109

campaign_manager:number_of_units_in_faction(faction faction object, [boolean exclude armed citizenry])

Returns the number of units in all military forces in the supplied faction. The optional second parameter, if true, specifies that units in armed citizenry armies should not be considered in the calculation.

Parameters:

1

faction

faction object

2

boolean

optional, default value=false

exclude armed citizenry

Returns:

  1. number number of units

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3151

campaign_manager:faction_is_alive(faction faction object)

Returns true if the supplied faction has a home region or any military forces. Note that what constitutes as "alive" for a faction changes between different projects so use with care.

Parameters:

1

faction

faction object

Returns:

  1. boolean faction is alive

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3177

campaign_manager:faction_of_culture_is_alive(string culture key)

Returns true if any faction with a culture corresponding to the supplied key is alive (uses campaign_manager:faction_is_alive).

Parameters:

1

string

culture key

Returns:

  1. boolean any faction is alive

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3191

campaign_manager:faction_of_subculture_is_alive(string subculture key)

Returns true if any faction with a subculture corresponding to the supplied key is alive (uses campaign_manager:faction_is_alive).

Parameters:

1

string

subculture key

Returns:

  1. boolean any faction is alive

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3217

campaign_manager:faction_has_armies_in_enemy_territory(faction faction)

Returns true if the supplied faction has any armies in the territory of factions it's at war with, false otherwise.

Parameters:

1

faction

faction

Returns:

  1. boolean has armies in enemy territory

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3243

campaign_manager:faction_has_armies_in_region(faction faction, region region)

Returns true if the supplied faction has any armies in the supplied region, false otherwise.

Parameters:

1

faction

faction

2

region

region

Returns:

  1. boolean armies in region

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3275

campaign_manager:faction_has_nap_with_faction(faction faction, region region)

Returns true if the supplied faction has any armies in the supplied region, false otherwise.

Parameters:

1

faction

faction

2

region

region

Returns:

  1. boolean armies in region

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3297

campaign_manager:faction_has_trade_agreement_with_faction(faction faction, region region)

Returns true if the supplied faction has any armies in the supplied region, false otherwise.

Parameters:

1

faction

faction

2

region

region

Returns:

  1. boolean armies in region

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3323

campaign_manager:get_border_regions_of_faction(
  faction
faction,
  boolean
outside_border True returns regions bordering the faction that do not belong to the faction,
  [boolean
return_unique_list]
)

Returns a table of regions at the border of the supplied faction

Parameters:

1

faction

faction

2

boolean

False returns a list of the factions regions at their border

3

boolean

optional, default value=false

return_unique_list

Returns:

  1. table Table of regions

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3349

campaign_manager:get_factions_that_border_faction(faction faction, [boolean return_unique_list])

Returns a table of factions that border the supplied faction

Parameters:

1

faction

faction

2

boolean

optional, default value=false

return_unique_list

Returns:

  1. table Table of factions

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3384

campaign_manager:get_regions_within_distance_of_character(
  character
character interface,
  number
distance,
  boolean
not razed,
  [boolean
return_unique_list]
)

Returns a table of regions within the specified distance of a character

Parameters:

1

character

character interface

2

number

distance

3

boolean

not razed

4

boolean

optional, default value=false

return_unique_list

Returns:

  1. table Table of regions

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3413

Back to top

Garrison Residence Queries

campaign_manager:garrison_contains_building(garrison_residence garrison residence, string building key)

Returns true if the supplied garrison residence contains a building with the supplied key, false otherwise.

Parameters:

1

garrison_residence

garrison residence

2

string

building key

Returns:

  1. boolean garrison contains building

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3462

campaign_manager:garrison_contains_building_chain(
  garrison_residence
garrison residence,
  string
building chain key
)

Returns true if the supplied garrison residence contains a building with the supplied chain key, false otherwise.

Parameters:

1

garrison_residence

garrison residence

2

string

building chain key

Returns:

  1. boolean garrison contains building

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3490

campaign_manager:garrison_contains_building_superchain(
  garrison_residence
garrison residence,
  string
building superchain key
)

Returns true if the supplied garrison residence contains a building with the supplied superchain key, false otherwise.

Parameters:

1

garrison_residence

garrison residence

2

string

building superchain key

Returns:

  1. boolean garrison contains building

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3518

campaign_manager:get_armed_citizenry_from_garrison(
  garrison_residence
garrison residence,
  [boolean
get naval]
)

Returns the garrison army from a garrison residence. By default this returns the land army armed citizenry - an optional flag instructs the function to return the naval armed citizenry instead.

Parameters:

1

garrison_residence

Garrison residence.

2

boolean

optional, default value=false

Returns the naval armed citizenry army, if set to true.

Returns:

  1. boolean armed citizenry army

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3546

Back to top

Military Force Queries

campaign_manager:military_force_average_strength(military_force military force)

Returns the average strength of all units in the military force. This is expressed as a percentage (0-100), so a returned value of 75 would indicate that the military force had lost 25% of its strength through casualties.

Parameters:

1

military_force

military force

Returns:

  1. number average strength percentage

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3587

campaign_manager:num_mobile_forces_in_force_list(military_force_list military force list)

Returns the number of military forces that are not armed-citizenry in the supplied military force list.

Parameters:

1

military_force_list

military force list

Returns:

  1. number number of mobile forces

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3614

campaign_manager:proportion_of_unit_class_in_military_force(
  military_force
military force,
  string
unit class
)

Returns the unary proportion (0-1) of units in the supplied military force which are of the supplied unit class.

Parameters:

1

military_force

military force

2

string

unit class

Returns:

  1. proportion units of unit class

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3636

campaign_manager:military_force_contains_unit_type_from_list(
  military_force
military force,
  table
unit type list
)

Returns true if the supplied military force contains any units of a type contained in the supplied unit type list, false otherwise.

Parameters:

1

military_force

Military force.

2

table

Unit type list. This must be supplied as a numerically indexed table of strings.

Returns:

  1. force contains unit from type list

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3671

campaign_manager:military_force_contains_unit_class_from_list(
  military_force
military force,
  table
unit class list
)

Returns true if the supplied military force contains any units of a class contained in the supplied unit class list, false otherwise.

Parameters:

1

military_force

Military force.

2

table

Unit class list. This must be supplied as a numerically indexed table of strings.

Returns:

  1. force contains unit from class list

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3697

campaign_manager:force_from_general_cqi(number general cqi)

Returns the force whose commanding general has the passed cqi. If no force is found then false is returned.

Parameters:

1

number

general cqi

Returns:

  1. military force force

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3722

campaign_manager:force_gold_value(number force cqi)

Returns the gold value of all of the units in the force.

Parameters:

1

number

force cqi

Returns:

  1. number value

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3738

Back to top

Region Queries & Modification

campaign_manager:get_region(string region name)

Returns a region object with the supplied region name. If no such region is found then false is returned.

Parameters:

1

string

region name

Returns:

  1. region region

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3774

campaign_manager:is_region_owned_by_faction(string region name)

Returns a region object with the supplied region name. If no such region is found then false is returned.

Parameters:

1

string

region name

Returns:

  1. region region

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3794

campaign_manager:region_has_neighbours_of_other_religion(region subject region)

Returns true if a specified region has any neighbouring regions with a different religion, false otherwise.

Parameters:

1

region

subject region

Returns:

  1. boolean region has neighbour of different religion

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3820

campaign_manager:instantly_upgrade_building_in_region(
  SLOT_SCRIPT_INTERFACE
slot,
  string
target building key
)

Instantly upgrades the building in the supplied slot to the supplied building key.

Parameters:

1

SLOT_SCRIPT_INTERFACE

slot

2

string

target building key

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3842

campaign_manager:instantly_dismantle_building_in_region(SLOT_SCRIPT_INTERFACE slot)

Instantly dismantles the building in the supplied slot number of the supplied region.

Parameters:

1

SLOT_SCRIPT_INTERFACE

slot

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3856

campaign_manager:get_most_pious_region_for_faction_for_religion(
  faction
subject faction,
  string
religion key
)

Returns the region held by a specified faction that has the highest proportion of a specified religion. The numeric religion proportion is also returned.

Parameters:

1

faction

subject faction

2

string

religion key

Returns:

  1. region most pious region
  2. number religion proportion

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3864

campaign_manager:create_storm_for_region(
  string
region key,
  number
storm strength,
  number
duration,
  string
storm type
)

Creates a storm of a given type in a given region. This calls the function of the same name on the game interface, but adds validation and output.

Parameters:

1

string

region key

2

number

storm strength

3

number

duration

4

string

storm type

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3890

Back to top

Settlement Queries

campaign_manager:settlement_display_pos(string settlement name)

Returns the display position of a supplied settlement by string name.

Parameters:

1

string

settlement name

Returns:

  1. number x display position
  2. number y display position

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3961

campaign_manager:settlement_logical_pos(string settlement name)

Returns the logical position of a supplied settlement by string name.

Parameters:

1

string

settlement name

Returns:

  1. number x logical position
  2. number y logical position

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 3971

Back to top

Pending Battle Cache

Using the standard game interface it can be difficult to get information about a battle after it has been fought. The only method of querying the forces that fought in a battle is through the character interface (of the respective army commanders), and if they died in battle this will no longer be available.

The pending battle cache system stores information about a battle prior to it being fought, which can be queried after the battle. This allows the factions, characters, and military forces involved to be queried even if they died in the battle. The information will remain available for querying until the next battle occurs.

The data in the cache may also be queried prior to battle. The script triggers a ScriptEventPendingBattle event after a PendingBattle event is received and the pending battle cache has been populated. Scripts that want to query the pending battle cache prior to battle can listen for this.

campaign_manager:pending_battle_cache_num_attackers()

Returns the number of attacking armies in the cached pending battle.

Returns:

  1. number number of attacking armies

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4263

campaign_manager:pending_battle_cache_get_attacker(number index of attacker)

Returns records relating to a particular attacker in the cached pending battle. The attacker is specified by numerical index, with the first being accessible at record 1. This function returns the cqi of the commanding character, the cqi of the military force, and the faction name.

Parameters:

1

number

index of attacker

Returns:

  1. number character cqi
  2. number military force cqi
  3. string faction name

Example - print attacker details:

for i = 1, cm:pending_battle_cache_num_attackers() do
    local char_cqi, mf_cqi, faction_name = cm:pending_battle_cache_get_attacker(i);
    out("Attacker " .. i .. " of faction " .. faction_name .. ":");
    out("\tcharacter cqi: " .. char_cqi);
    out("\tmilitary force cqi: " .. mf_cqi);
end

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4271

campaign_manager:pending_battle_cache_get_attacker_faction_name(number index of attacker)

Returns just the faction name of a particular attacker in the cached pending battle. The attacker is specified by numerical index, with the first being accessible at record 1.

Parameters:

1

number

index of attacker

Returns:

  1. string faction name

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4294

campaign_manager:pending_battle_cache_num_defenders()

Returns the number of defending armies in the cached pending battle.

Returns:

  1. number number of defending armies

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4308

campaign_manager:pending_battle_cache_get_defender(number index of defender)

Returns records relating to a particular defender in the cached pending battle. The defender is specified by numerical index, with the first being accessible at record 1. This function returns the cqi of the commanding character, the cqi of the military force, and the faction name.

Parameters:

1

number

index of defender

Returns:

  1. number character cqi
  2. number military force cqi
  3. string faction name

Example - print defender details:

for i = 1, cm:pending_battle_cache_num_defenders() do
    local char_cqi, mf_cqi, faction_name = cm:pending_battle_cache_get_defender(i);
    out("Defender " .. i .. " of faction " .. faction_name .. ":");
    out("\tcharacter cqi: " .. char_cqi);
    out("\tmilitary force cqi: " .. mf_cqi);
end

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4316

campaign_manager:pending_battle_cache_get_defender_faction_name(number index of defender)

Returns just the faction name of a particular defender in the cached pending battle. The defender is specified by numerical index, with the first being accessible at record 1.

Parameters:

1

number

index of defender

Returns:

  1. string faction name

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4339

campaign_manager:pending_battle_cache_faction_is_attacker(string faction key)

Returns true if the faction was an attacker (primary or reinforcing) in the cached pending battle.

Parameters:

1

string

faction key

Returns:

  1. boolean faction was attacker

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4353

campaign_manager:pending_battle_cache_faction_is_defender(string faction key)

Returns true if the faction was a defender (primary or reinforcing) in the cached pending battle.

Parameters:

1

string

faction key

Returns:

  1. boolean faction was defender

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4375

campaign_manager:pending_battle_cache_faction_is_involved(string faction key)

Returns true if the faction was involved in the cached pending battle as either attacker or defender.

Parameters:

1

string

faction key

Returns:

  1. boolean faction was involved

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4397

campaign_manager:pending_battle_cache_human_is_attacker()

Returns true if any of the attacking factions involved in the cached pending battle were human controlled (whether local or not).

Returns:

  1. boolean human was attacking

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4406

campaign_manager:pending_battle_cache_human_is_defender()

Returns true if any of the defending factions involved in the cached pending battle were human controlled (whether local or not).

Returns:

  1. boolean human was defending

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4424

campaign_manager:pending_battle_cache_human_is_involved()

Returns true if any of the factions involved in the cached pending battle on either side were human controlled (whether local or not).

Returns:

  1. boolean human was involved

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4442

campaign_manager:pending_battle_cache_culture_is_attacker(string culture key)

Returns true if any of the attacking factions in the cached pending battle are of the supplied culture.

Parameters:

1

string

culture key

Returns:

  1. boolean any attacker was culture

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4450

campaign_manager:pending_battle_cache_culture_is_defender(string culture key)

Returns true if any of the defending factions in the cached pending battle are of the supplied culture.

Parameters:

1

string

culture key

Returns:

  1. boolean any defender was culture

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4474

campaign_manager:pending_battle_cache_culture_is_involved(string culture key)

Returns true if any of the factions involved in the cached pending battle on either side match the supplied culture.

Parameters:

1

string

culture key

Returns:

  1. boolean culture was involved

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4498

campaign_manager:pending_battle_cache_subculture_is_attacker(string subculture key)

Returns true if any of the attacking factions in the cached pending battle are of the supplied subculture.

Parameters:

1

string

subculture key

Returns:

  1. boolean any attacker was subculture

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4507

campaign_manager:pending_battle_cache_subculture_is_defender(string subculture key)

Returns true if any of the defending factions in the cached pending battle are of the supplied subculture.

Parameters:

1

string

subculture key

Returns:

  1. boolean any defender was subculture

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4531

campaign_manager:pending_battle_cache_subculture_is_involved(string subculture key)

Returns true if any of the factions involved in the cached pending battle on either side match the supplied subculture.

Parameters:

1

string

subculture key

Returns:

  1. boolean subculture was involved

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4555

campaign_manager:pending_battle_cache_char_is_attacker(object character)

Returns true if the supplied character was an attacker in the cached pending battle.

Parameters:

1

object

Character to query. May be supplied as a character object or as a cqi number.

Returns:

  1. boolean character was attacker

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4564

campaign_manager:pending_battle_cache_char_is_defender(object character)

Returns true if the supplied character was a defender in the cached pending battle.

Parameters:

1

object

Character to query. May be supplied as a character object or as a cqi number.

Returns:

  1. boolean character was defender

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4590

campaign_manager:pending_battle_cache_char_is_involved(object character)

Returns true if the supplied character was an attacker or defender in the cached pending battle.

Parameters:

1

object

Character to query. May be supplied as a character object or as a cqi number.

Returns:

  1. boolean character was involved

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4616

campaign_manager:pending_battle_cache_mf_is_attacker(number cqi)

Returns true if the supplied military force was an attacker in the cached pending battle.

Parameters:

1

number

Command-queue-index of the military force to query.

Returns:

  1. boolean force was attacker

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4634

campaign_manager:pending_battle_cache_mf_is_defender(number cqi)

Returns true if the supplied military force was a defender in the cached pending battle.

Parameters:

1

number

Command-queue-index of the military force to query.

Returns:

  1. boolean force was defender

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4662

campaign_manager:pending_battle_cache_mf_is_involved(number cqi)

Returns true if the supplied military force was an attacker or defender in the cached pending battle.

Parameters:

1

number

Command-queue-index of the military force to query.

Returns:

  1. boolean force was involved

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4690

campaign_manager:pending_battle_cache_get_enemies_of_char(character character to query)

Returns a numerically indexed table of character objects, each representing an enemy character of the supplied character in the cached pending battle. If the supplied character was not present in the pending battle then the returned table will be empty.

Parameters:

1

character

character to query

Returns:

  1. table table of enemy characters

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4708

campaign_manager:pending_battle_cache_is_quest_battle()

Returns true if any of the participating factions in the pending battle are quest battle factions, false otherwise.

Returns:

  1. boolean is quest battle

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4735

campaign_manager:pending_battle_cache_attacker_victory()

Returns true if the pending battle has been won by the attacker, false otherwise.

Returns:

  1. boolean attacker has won

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4757

campaign_manager:pending_battle_cache_defender_victory()

Returns true if the pending battle has been won by the defender, false otherwise.

Returns:

  1. boolean defender has won

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4765

campaign_manager:pending_battle_cache_attacker_value()

Returns the gold value of attacking forces in the cached pending battle.

Returns:

  1. number gold value of attacking forces

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4773

campaign_manager:pending_battle_cache_defender_value()

Returns the gold value of defending forces in the cached pending battle.

Returns:

  1. number gold value of defending forces

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4784

Back to top

Random Numbers

campaign_manager:random_number([integer max], [integer min])

Assembles and returns a random integer between 1 and 100, or other supplied values. The result returned is inclusive of the supplied max/min. This is safe to use in multiplayer scripts.

Parameters:

1

integer

optional, default value=100

Maximum value of returned random number.

2

integer

optional, default value=1

Minimum value of returned random number.

Returns:

  1. number random number

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4806

campaign_manager:random_sort(table numerically-indexed table)

Randomly sorts a numerically-indexed table. This is safe to use in multiplayer, but will destroy the supplied table. It is faster than campaign_manager:random_sort_copy.
Note that records in this table that are not arranged in an ascending numerical index will be lost.
Note also that the supplied table is overwritten with the randomly-sorted table, which is also returned as a return value.

Parameters:

1

table

Numerically-indexed table. This will be overwritten by the returned, randomly-sorted table.

Returns:

  1. table randomly-sorted table

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4877

campaign_manager:random_sort_copy(table numerically-indexed table)

Randomly sorts a numerically-indexed table. This is safe to use in multiplayer, and will preserve the original table, but it is slower than campaign_manager:random_sort as it copies the table first.
Note that records in the source table that are not arranged in an ascending numerical index will not be copied (they will not be deleted, however).

Parameters:

1

table

Numerically-indexed table.

Returns:

  1. table randomly-sorted table

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4906

campaign_manager:shuffle_table(table table)

Randomly shuffles a table with an implementation of the Fisher-Yates shuffle.
Note that unlike the random_sort function this modifies the existing table and doesn't create a new one.

Parameters:

1

table

table

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4929

Back to top

Campaign UI

campaign_manager:get_campaign_ui_manager()

Gets a handle to the campaign_ui_manager (or creates it).

Returns:

  1. campaign_ui_manager

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4957

campaign_manager:highlight_event_dismiss_button([boolean should highlight])

Activates or deactivates a highlight on the event panel dismiss button. This may not work in all circumstances.

Parameters:

1

boolean

optional, default value=true

should highlight

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 4968

campaign_manager:quit()

Immediately exits to the frontend. Mainly used in benchmark scripts.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5000

campaign_manager:enable_ui_hiding([boolean enable hiding])

Enables or disables the ability of the player to hide the UI.

Parameters:

1

boolean

optional, default value=true

enable hiding

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5017

campaign_manager:is_ui_hiding_enabled()

Returns false if ui hiding has been disabled with campaign_manager:enable_ui_hiding, true otherwise.

Returns:

  1. boolean is ui hiding enabled

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5032

Back to top

Camera Movement

The functions in this section allow or automate camera scrolling to some degree. Where camera positions are supplied as arguments, these are given as a table of numbers. The numbers in a camera position table are given in the following order:

  1. x co-ordinate of camera target.
  2. y co-ordinate of camera target.
  3. horizontal distance from camera to target.
  4. bearing from camera to target, in radians.
  5. vertical distance from camera to target.

campaign_manager:scroll_camera_with_direction(boolean correct endpoint, number time, ... positions)

Override function for scroll_camera_wiht_direction that provides output.

Parameters:

1

boolean

Correct endpoint. If true, the game will adjust the final position of the camera so that it's a valid camera position for the game. Set to true if control is being released back to the player after this camera movement finishes.

2

number

Time in seconds over which to scroll.

3

...

Two or more camera positions must be supplied. Each position should be a table with five number components, as described in the description of the Camera Movement section.

Returns:

  1. nil

Example:

Pull the camera out from a close-up to a wider view.
cm:scroll_camera_with_direction(
    true,
    5,
    {132.9, 504.8, 8, 0, 6},
    {132.9, 504.8, 16, 0, 12}
)

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5104

campaign_manager:scroll_camera_from_current(boolean correct endpoint, number time, ... positions)

Scrolls the camera from the current camera position. This is the same as callling campaign_manager:scroll_camera_with_direction with the current camera position as the first set of co-ordinates.

Parameters:

1

boolean

Correct endpoint. If true, the game will adjust the final position of the camera so that it's a valid camera position for the game. Set to true if control is being released back to the player after this camera movement finishes.

2

number

Time in seconds over which to scroll.

3

...

One or more camera positions must be supplied. Each position should be a table with five number components, as described in the description of the Camera Movement section.

Returns:

  1. nil

Example:

cm:scroll_camera_from_current(
    true,
    5,
    {251.3, 312.0, 12, 0, 8}
)

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5134

campaign_manager:scroll_camera_with_cutscene(number time, [function callback], ... positions)

Scrolls the camera from the current camera position in a cutscene. Cinematic borders will be shown (unless disabled with campaign_manager:set_use_cinematic_borders_for_automated_cutscenes), the UI hidden, and interaction with the game disabled while the camera is scrolling. The player will be able to skip the cutscene with the ESC key, in which case the camera will jump to the end position.

Parameters:

1

number

Time in seconds over which to scroll.

2

function

optional, default value=nil

Optional callback to call when the cutscene ends.

3

...

One or more camera positions must be supplied. Each position should be a table with five number components, as described in the description of the Camera Movement section.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5171

campaign_manager:cut_and_scroll_camera_with_cutscene(
  number
time,
  [function
callback],
  ...
positions. One or more camera positions must be supplied. Each position should be a table with five number components
)

Scrolls the camera through the supplied list of camera points in a cutscene. Cinematic borders will be shown (unless disabled with campaign_manager:set_use_cinematic_borders_for_automated_cutscenes), the UI hidden, and interaction with the game disabled while the camera is scrolling. The player will be able to skip the cutscene with the ESC key, in which case the camera will jump to the end position.

Parameters:

1

number

Time in seconds over which to scroll.

2

function

optional, default value=nil

Optional callback to call when the cutscene ends.

3

...

as described in the description of the Camera Movement section.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5208

campaign_manager:scroll_camera_with_cutscene_to_settlement(
  number
time,
  [function
callback],
  string
region key
)

Scrolls the camera in a cutscene to the specified settlement in a cutscene. The settlement is specified by region key. Cinematic borders will be shown (unless disabled with campaign_manager:set_use_cinematic_borders_for_automated_cutscenes), the UI hidden, and interaction with the game disabled while the camera is scrolling. The player will be able to skip the cutscene with the ESC key, in which case the camera will jump to the target.

Parameters:

1

number

Time in seconds over which to scroll.

2

function

optional, default value=nil

Optional callback to call when the cutscene ends.

3

string

Key of region containing target settlement.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5271

campaign_manager:scroll_camera_with_cutscene_to_character(number time, [function callback], number cqi)

Scrolls the camera in a cutscene to the specified character in a cutscene. The character is specified by its command queue index (cqi). Cinematic borders will be shown (unless disabled with campaign_manager:set_use_cinematic_borders_for_automated_cutscenes), the UI hidden, and interaction with the game disabled while the camera is scrolling. The player will be able to skip the cutscene with the ESC key, in which case the camera will jump to the target.

Parameters:

1

number

Time in seconds over which to scroll.

2

function

optional, default value=nil

Optional callback to call when the cutscene ends.

3

number

CQI of target character.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5305

campaign_manager:set_use_cinematic_borders_for_automated_cutscenes([boolean show borders])

Sets whether or not to show cinematic borders when scrolling the camera in an automated cutscene (for example with campaign_manager:scroll_camera_with_cutscene). By default, cinematic borders are displayed.

Parameters:

1

boolean

optional, default value=true

show borders

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5337

campaign_manager:position_camera_at_primary_military_force(string faction key)

Immediately positions the camera at a position looking at the primary military force for the supplied faction. The faction is specified by key.

Parameters:

1

string

faction key

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5450

campaign_manager:cindy_playback(string filepath, [number blend in duration], [number blend out duration])

Starts playback of a cindy scene. This is a wrapper for the cinematics:cindy_playback function, adding debug output.

Parameters:

1

string

File path to cindy scene, from the working data folder.

2

number

optional, default value=nil

Time in seconds over which the camera will blend into the cindy scene when started.

3

number

optional, default value=nil

Time in seconds over which the camera will blend out of the cindy scene when it ends.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5495

campaign_manager:stop_cindy_playback(boolean clear animation scenes)

Stops playback of any currently-playing cindy scene. This is a wrapper for the function of the same name on the cinematic interface, but adds debug output.

Parameters:

1

boolean

clear animation scenes

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5527

Back to top

Camera Position Caching

The functions in this section allow the current position of the camera to be cached, and then for a test to be performed later to determine if the camera has moved. This is useful for determining if the player has moved the camera, which would indicate whether it's appropriate or not to scroll the camera via script in certain circumstances.

campaign_manager:cache_camera_position([string cache name])

Caches the current camera position, so that the camera position may be compared to it later to determine if it has moved. An optional name may be specified for this cache entry so that multiple cache entries may be created. If the camera position was previously cached with the supplied cache name then that cache will be overwritten.

Parameters:

1

string

optional, default value="default"

cache name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5551

campaign_manager:cached_camera_position_exists([string cache name])

Returns whether a camera position is currently cached for the (optional) supplied cache name.

Parameters:

1

string

optional, default value="default"

cache name

Returns:

  1. boolean camera position is cached

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5571

campaign_manager:get_cached_camera_position([string cache name])

Returns the camera position which was last cached with the optional cache name (the default cache name is "default"). If no camera cache has been set with the specified name then a script error is generated.

Parameters:

1

string

optional, default value="default"

cache name

Returns:

  1. number x
  2. number y
  3. number d
  4. number b
  5. number h

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5589

campaign_manager:camera_has_moved_from_cached([string cache name])

Compares the current position of the camera to that last cached with the (optional) specified cache name, and returns true if any of the camera co-ordinates have changed by the (optional) supplied distance, or false otherwise. If no camera cache has been set with the specified name then a script error is generated.

Parameters:

1

string

optional, default value="default"

cache name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5615

campaign_manager:delete_cached_camera_position([string cache name])

Removes the cache for the supplied cache name. If no cache name is specified the default cache (cache name "default") is deleted.

Parameters:

1

string

optional, default value="default"

cache name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5654

Back to top

Cutscenes and Key Stealing

campaign_manager:show_subtitle(string text key, [boolean full text key supplied], [boolean force diplay])

Shows subtitled text during a cutscene. The text is displayed until campaign_manager:hide_subtitles is called.

Parameters:

1

string

Text key. By default, this is supplied as a record key from the scripted_subtitles table. Text from anywhere in the database may be shown, however, by supplying the full localisation key and true for the second argument.

2

boolean

optional, default value=false] boolean full text key supplied, Set to true if the fll localised text key was supplied for the first argument in the form [table]_[field]_[key

Set to true if the fll localised text key was supplied for the first argument in the form [table]_[field]_[key].

3

boolean

optional, default value=false

Forces subtitle display. Setting this to true overrides the player's preferences on subtitle display.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5685

campaign_manager:hide_subtitles()

Hides any subtitles currently displayed with campaign_manager:show_subtitle.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5749

campaign_manager:is_any_cutscene_running()

Returns true if any campaign_cutscene is running, false otherwise.

Returns:

  1. boolean is any cutscene running

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5790

campaign_manager:skip_all_campaign_cutscenes()

Skips any campaign cutscene currently running.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5809

campaign_manager:steal_escape_key(boolean steal)

Steals or releases the escape key. This wraps a function of the same name on the underlying game interface. While the ESC key is stolen by script, presses of the key will cause OnKeyPressed() to be called which goes on to call campaign_manager:on_key_press_up.
To register a function to call when the escape key is pressed use campaign_manager:steal_escape_key_with_callback or campaign_manager:steal_escape_key_and_space_bar_with_callback instead of this function.

Parameters:

1

boolean

steal

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5818

campaign_manager:steal_user_input(boolean steal)

Steals or releases user input. This wraps a function of the same name on the underlying game interface. Stealing user input prevents any player interaction with the game (asides from pressing the ESC key).

Parameters:

1

boolean

steal

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5835

campaign_manager:on_key_press_up(string key pressed)

Called by the campaign model when a key stolen by steal_user_input or steal_escape_key is pressed. Client scripts should not call this!

Parameters:

1

string

key pressed

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5860

campaign_manager:print_key_steal_entries()

Debug output of all current stolen key records.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5874

campaign_manager:steal_key_with_callback(string name, string key, function callback)

Steal a key, and register a callback to be called when it's pressed. It will be un-stolen when this occurs. campaign_manager:steal_user_input will need to be called separately for this mechanism to work, unless it's the escape key that being stolen, where campaign_manager:steal_escape_key should be used instead. In this latter case campaign_manager:steal_escape_key_with_callback can be used instead.

Parameters:

1

string

Unique name for this key-steal entry. This can be used later to release the key with campaign_manager:release_key_with_callback.

2

string

Key name.

3

function

Function to call when the key is pressed.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5892

campaign_manager:release_key_with_callback(string name, string key)

Releases a key stolen with campaign_manager:steal_key_with_callback.

Parameters:

1

string

Unique name for this key-steal entry.

2

string

Key name.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5936

campaign_manager:steal_escape_key_with_callback(string name, function callback)

Steals the escape key and registers a function to call when it is pressed. Unlike campaign_manager:steal_key_with_callback this automatically calls campaign_manager:steal_escape_key if the key is not already stolen.

Parameters:

1

string

Unique name for this key-steal entry.

2

function

Function to call when the key is pressed.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5964

campaign_manager:release_escape_key_with_callback(string name)

Releases the escape key after it's been stolen with campaign_manager:steal_escape_key_with_callback.

Parameters:

1

string

Unique name for this key-steal entry.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5976

campaign_manager:steal_escape_key_and_space_bar_with_callback(string name, function callback)

Steals the escape key and spacebar and registers a function to call when they are pressed.

Parameters:

1

string

Unique name for this key-steal entry.

2

function

Function to call when one of the keys are pressed.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 5990

campaign_manager:release_escape_key_and_space_bar_with_callback(string name, function callback)

Releases the escape key and spacebar after they've been stolen with campaign_manager:steal_escape_key_and_space_bar_with_callback.

Parameters:

1

string

Unique name for this key-steal entry

2

function

Function to call when one of the keys are pressed.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6001

Back to top

Advice

campaign_manager:show_advice(
  string
advice key,
  [boolean
show progress button],
  [boolean
highlight progress button],
  [function
callback],
  [number
playtime],
  [number
delay]
)

Displays some advice. The advice to display is specified by advice_thread key.

Parameters:

1

string

Advice thread key.

2

boolean

optional, default value=false

Show progress/close button on the advisor panel.

3

boolean

optional, default value=false

Highlight the progress/close button on the advisor panel.

4

function

optional, default value=nil

End callback to call once the advice VO has finished playing.

5

number

optional, default value=0

Minimum playtime for the advice VO in seconds. If this is longer than the length of the VO audio, the end callback is not called until after this duration has elapsed. If an end callback is set this has no effect. This is useful during development before recorded VO is ready for simulating the advice being played for a certain duration - with no audio, the advice would complete immediately, or not complete at all.

6

number

optional, default value=0

Delay in seconds to wait after the advice has finished before calling the supplied end callback. If no end callback is supplied this has no effect.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6026

campaign_manager:set_advice_enabled([boolean enable advice])

Enables or disables the advice system.

Parameters:

1

boolean

optional, default value=true

enable advice

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6074

campaign_manager:is_advice_enabled()

Returns true if the advice system is enabled, or false if it's been disabled with campaign_manager:set_advice_enabled.

Returns:

  1. boolean advice is enabled

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6094

campaign_manager:modify_advice([boolean show progress button], [boolean highlight progress button])

Immediately enables or disables the close button that appears on the advisor panel, or causes it to be highlighted.

Parameters:

1

boolean

optional, default value=false

show progress button

2

boolean

optional, default value=false

highlight progress button

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6102

campaign_manager:add_pre_dismiss_advice_callback(function callback)

Registers a callback to be called when/immediately before the advice gets dismissed.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6138

campaign_manager:dismiss_advice()

Dismisses the advice. Prior to performing the dismissal, this function calls any pre-dismiss callbacks registered with campaign_manager:add_pre_dismiss_advice_callback. This function gets called internally when the player clicks the script-controlled advice progression button that appears on the advisor panel.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6151

campaign_manager:progress_on_advice_dismissed(
  function
callback,
  [number
delay],
  [boolean
highlight on finish]
)

Registers a function to be called when the advisor is dismissed. Only one such function can be registered at a time.

Parameters:

1

function

Callback to call.

2

number

optional, default value=0

Delay in seconds after the advisor is dismissed before calling the callback.

3

boolean

optional, default value=false

Highlight on advice finish. If set to true, this also establishes a listener for the advice VO finishing. When it does finish, this function then highlights the advisor close button.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6175

campaign_manager:cancel_progress_on_advice_dismissed()

Cancels any running campaign_manager:progress_on_advice_dismissed process.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6273

campaign_manager:progress_on_advice_finished(
  function
callback,
  [number
delay],
  [number
playtime],
  [boolean
use os clock]
)

Registers a function to be called when the advisor VO has finished playing and the AdviceFinishedTrigger event is sent from the game to script. If this event is not received after a duration (default 5 seconds) the function starts actively polling whether the advice audio is still playing, and calls the callback when it finds that it isn't.
Only one process invoked by this function may be active at a time.

Parameters:

1

function

Callback to call.

2

number

optional, default value=0

Delay in seconds after the advisor finishes before calling the callback. By default, the function does not delay.

3

number

optional, default value=nil

Time in seconds to wait before actively polling whether the advice is still playing. The default value is 5 seconds unless overridden with this parameter. This is useful during development as if no audio has yet been recorded, or if no advice is playing for whatever reason, the function would otherwise continue to monitor until the next time advice is triggered, which is probably not desired.

4

boolean

optional, default value=false

Use OS clock. Set this to true if the process is going to be running during the end-turn sequence, where the normal flow of model time completely breaks down.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6281

campaign_manager:cancel_progress_on_advice_finished()

Cancels any running campaign_manager:progress_on_advice_finished process.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6408

Back to top

Progress on UI Event

campaign_manager:progress_on_panel_dismissed(
  string
unique name,
  string
panel name,
  function
callback,
  [number
callback delay]
)

Calls a supplied callback when a panel with the supplied name is closed.

Parameters:

1

string

Unique descriptive string name for this process. Multiple progress_on_panel_dismissed monitors may be active at any one time.

2

string

Name of the panel.

3

function

Callback to call.

4

number

optional, default value=0

Time in seconds to wait after the panel dismissal before calling the supplied callback.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6431

campaign_manager:cancel_progress_on_panel_dismissed(string unique name)

Cancels a monitor started with campaign_manager:progress_on_panel_dismissed by name.

Parameters:

1

string

Unique descriptive string name for this process.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6487

campaign_manager:progress_on_events_dismissed(string unique name, function callback, [number callback delay])

Calls a supplied callback when all events panels are closed. Analagous to calling campaign_manager:progress_on_panel_dismissed with the panel name "events".

Parameters:

1

string

Unique descriptive string name for this process. Multiple progress_on_panel_dismissed monitors may be active at any one time.

2

function

Callback to call.

3

number

optional, default value=0

Time in seconds to wait after the panel dismissal before calling the supplied callback.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6498

campaign_manager:cancel_progress_on_events_dismissed(string unique name)

Cancels a monitor started with campaign_manager:progress_on_events_dismissed (or campaign_manager:progress_on_panel_dismissed) by name.

Parameters:

1

string

Unique descriptive string name for this process.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6508

campaign_manager:progress_on_fullscreen_panel_dismissed(function callback, [number callback delay])

Calls the supplied callback when all fullscreen campaign panels are dismissed. Only one such monitor may be active at once - starting a second will cancel the first.

Parameters:

1

function

Callback to call.

2

number

optional, default value=0

Time in seconds to wait after the panel dismissal before calling the supplied callback.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6516

campaign_manager:cancel_progress_on_fullscreen_panel_dismissed(function callback, [number callback delay])

Cancels any running monitor started with campaign_manager:progress_on_fullscreen_panel_dismissed.

Parameters:

1

function

Callback to call.

2

number

optional, default value=0

Time in seconds to wait after the panel dismissal before calling the supplied callback.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6541

campaign_manager:start_intro_cutscene_on_loading_screen_dismissed(
  function
callback,
  [number
fade in time]
)

This function provides an easy one-shot method of starting an intro flyby cutscene from a loading screen with a fade effect. Call this function on the first tick (or before), and pass to it a function which starts an intro cutscene.

Parameters:

1

function

Callback to call.

2

number

optional, default value=0

Time in seconds over which to fade in the camera from black.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6550

campaign_manager:progress_on_battle_completed(string name, function callback, [number delay])

Calls the supplied callback when a battle sequence is fully completed. A battle sequence is completed once the pre or post-battle panel has been dismissed and any subsequent camera animations have finished.

Parameters:

1

string

Unique name for this monitor. Multiple such monitors may be active at once.

2

function

Callback to call.

3

number

optional, default value=0

Delay in ms after the battle sequence is completed before calling the callback.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6633

campaign_manager:cancel_progress_on_battle_completed(string name)

Cancels a running monitor started with campaign_manager:progress_on_battle_completed by name.

Parameters:

1

string

Name of monitor to cancel.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6671

campaign_manager:progress_on_camera_movement_finished(function callback, [number delay])

Calls the supplied callback when the campaign camera is seen to have finished moving. The function has to poll the camera position repeatedly, so the supplied callback will not be called the moment the camera comes to rest due to the model tick resolution.
Only one such monitor may be active at once.

Parameters:

1

function

Callback to call.

2

number

optional, default value=0

Delay in ms after the camera finishes moving before calling the callback.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6685

campaign_manager:cancel_progress_on_camera_movement_finished()

Cancels a running monitor started with campaign_manager:progress_on_camera_movement_finished.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6737

campaign_manager:progress_on_post_battle_panel_visible(function callback, [number delay])

Calls the supplied callback when the post-battle panel has finished animating on-screen. The function has to poll the panel state repeatedly, so the supplied callback will not be called the exact moment the panel comes to rest. Don't call this unless you know that the panel is about to animate on, otherwise it will be repeatedly polling in the background!
Only one such monitor may be active at once.

Parameters:

1

function

Callback to call.

2

number

optional, default value=0

Delay in ms after the panel finishes moving before calling the callback.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6744

campaign_manager:cancel_progress_on_post_battle_panel_visible()

Cancels a running monitor started with campaign_manager:progress_on_post_battle_panel_visible.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6772

Back to top

Character Creation and Manipulation

campaign_manager:create_force(
  string
faction key,
  string
unit list,
  string
region key,
  number
x,
  number
y,
  boolean
exclude named characters,
  [function
success callback]
)

Wrapper for create_force function on the underlying game interface, which instantly spawns an army with a general on the campaign map. This wrapper function adds debug output and success callback functionality.
Note that the underlying create_force function supports the call not going through the command queue, but this wrapper forces it to do so as doing otherwise seems to break in multiplayer.

Parameters:

1

string

Faction key of the faction to which the force is to belong.

2

string

Comma-separated list of keys from the land_units table. The force will be created with these units.

3

string

Region key of home region for this force.

4

number

x logical co-ordinate of force.

5

number

y logical co-ordinate of force.

6

boolean

Don't spawn a named character at the head of this force.

7

function

optional, default value=nil

Callback to call once the force is created. The callback will be passed the created military force leader's cqi as a single argument.

Returns:

  1. nil

Example:

cm:create_force(
    "wh_main_dwf_dwarfs",
    "wh_main_dwf_inf_hammerers,wh_main_dwf_inf_longbeards_1,wh_main_dwf_inf_quarrellers_0,wh_main_dwf_inf_quarrellers_0",
    "wh_main_the_silver_road_karaz_a_karak",
    714,
    353,
    "scripted_force_1",
    true,
    function(cqi)
        out("Force created with char cqi: " .. cqi);
    end
);

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6797

campaign_manager:create_force_with_general(
  string
faction key,
  string
unit list,
  string
region key,
  number
x,
  number
y,
  string
agent type,
  string
agent subtype,
  string
forename,
  string
clan name,
  string
family name,
  string
other name,
  boolean
make faction leader,
  [function
success callback]
)

Wrapper for create_force_with_general function on the underlying game interface, which instantly spawn an army with a specific general on the campaign map. This wrapper function adds debug output and success callback functionality.

Parameters:

1

string

Faction key of the faction to which the force is to belong.

2

string

Comma-separated list of keys from the land_units table. The force will be created with these units. This can be a blank string, or nil, if an empty force is desired.

3

string

Region key of home region for this force.

4

number

x logical co-ordinate of force.

5

number

y logical co-ordinate of force.

6

string

Character type of character at the head of the army (should always be "general"?).

7

string

Character subtype of character at the head of the army.

8

string

Localised string key of the created character's forename. This should be given in the localised text lookup format i.e. a key from the names table with "names_name_" prepended.

9

string

Localised string key of the created character's clan name. This should be given in the localised text lookup format i.e. a key from the names table with "names_name_" prepended.

10

string

Localised string key of the created character's family name. This should be given in the localised text lookup format i.e. a key from the names table with "names_name_" prepended.

11

string

Localised string key of the created character's other name. This should be given in the localised text lookup format i.e. a key from the names table with "names_name_" prepended.

12

boolean

Make the spawned character the faction leader.

13

function

optional, default value=nil

Callback to call once the force is created. The callback will be passed the created military force leader's cqi as a single argument.

Returns:

  1. nil

Example:

cm:create_force_with_general(
    "wh_main_dwf_dwarfs",
    "wh_main_dwf_inf_hammerers,wh_main_dwf_inf_longbeards_1,wh_main_dwf_inf_quarrellers_0,wh_main_dwf_inf_quarrellers_0",
    "wh_main_the_silver_road_karaz_a_karak",
    714,
    353,
    "general",
    "dwf_lord",
    "names_name_2147344345",
    "",
    "names_name_2147345842",
    "",
    "scripted_force_1",
    false,
    function(cqi)
        out("Force created with char cqi: " .. cqi);
    end
);

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 6893

campaign_manager:create_force_with_existing_general(
  string
character lookup,
  string
faction key,
  string
unit list,
  string
region key,
  number
x,
  number
y,
  [function
success callback]
)

Wrapper for create_force_with_existing_general function on the underlying game interface, which instantly spawn an army with a specific existing general on the campaign map. The general is specified by character string lookup. This wrapper function adds debug output and success callback functionality.

Parameters:

1

string

Character lookup string for the general character.

2

string

Faction key of the faction to which the force is to belong.

3

string

Comma-separated list of keys from the land_units table. The force will be created with these units.

4

string

Region key of home region for this force.

5

number

x logical co-ordinate of force.

6

number

y logical co-ordinate of force.

7

function

optional, default value=nil

Callback to call once the force is created. The callback will be passed the created military force leader's cqi as a single argument.

Returns:

  1. nil

Example:

cm:create_force_with_existing_general(
    cm:char_lookup_str(char_dwf_faction_leader),
    "wh_main_dwf_dwarfs",
    "wh_main_dwf_inf_hammerers,wh_main_dwf_inf_longbeards_1,wh_main_dwf_inf_quarrellers_0,wh_main_dwf_inf_quarrellers_0",
    "wh_main_the_silver_road_karaz_a_karak",
    714,
    353,
    function(cqi)
        out("Force created with char cqi: " .. cqi);
    end
);

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7044

campaign_manager:kill_character(
  string
character lookup string,
  [boolean
destroy force],
  [boolean
use command queue]
)

Kills the specified character, with the ability to also destroy their whole force if they are commanding one.

Parameters:

1

string

Character string of character to kill. This uses the standard character string lookup system.

2

boolean

optional, default value=false

Will also destroy the characters whole force if true.

3

boolean

optional, default value=true

Send the create command through the command queue.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7173

campaign_manager:add_building_to_force(number military force cqi, object building(s))

Adds one or more buildings to a horde army. The army is specified by the command queue index of the military force. A single building may be specified by a string key, or multiple buildings in a table.

Parameters:

1

number

Command queue index of the military force to add the building(s) to.

2

object

Building key or keys to add to the military force. This can be a single string or a numerically-indexed table.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7209

campaign_manager:create_agent(
  string
faction key,
  string
character type,
  string
character subtype,
  number
x,
  number
y,
  string
id,
  boolean
use command queue,
  [function
success callback]
)

Wrapper for create_agent function on the underlying game interface which adds input validation and debug output. This function creates an agent of a specified type on the campaign map.

Parameters:

1

string

Faction key of the faction to which the agent is to belong.

2

string

Character type of the agent.

3

string

Character subtype of the agent.

4

number

x logical co-ordinate of agent.

5

number

y logical co-ordinate of agent.

6

string

Unique string for agent.

7

boolean

Send the create command through the command queue.

8

function

optional, default value=nil

Callback to call once the character is created. The callback will be passed the created character's cqi as a single argument.

Returns:

  1. nil

Example:

cm:create_agent(
    "wh_main_dwf_dwarfs",
    "wh_main_the_silver_road_karaz_a_karak",
    714,
    353,
    function(cqi)
        out("Force created with char cqi: " .. cqi);
    end
);

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7247

campaign_manager:reposition_starting_character_for_faction(
  string
faction key,
  string
forename key,
  string
forename key,
  number
x,
  number
y
)

Repositions a specified character (the target) for a faction at start of a campaign, but only if another character (the subject) exists in that faction and is in command of an army. Like campaign_manager:teleport_to which underpins this function it is for use at the start of a campaign in a game-created callback (see campaign_manager:add_pre_first_tick_callback). It is intended for use in very specific circumstances.
The characters involved are specified by forename key.

Parameters:

1

string

Faction key of the subject and target characters.

2

string

Forename key of the subject character from the names table using the full localisation format i.e. names_name_[key].

3

string

Forename key of the target character from the names table using the full localisation format i.e. names_name_[key].

4

number

x logical target co-ordinate.

5

number

y logical target co-ordinate.

Returns:

  1. boolean Subject character exists.

Example:

cm:add_pre_first_tick_callback(
    function()
        cm:reposition_starting_character_for_faction(
            "wh_dlc03_bst_beastmen",
            "names_name_2147357619",
            "names_name_2147357619",
            643,
            191
        )
    end
)

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7381

campaign_manager:spawn_army_starting_character_for_faction(
  string
faction key,
  string
forename key,
  string
faction key,
  string
units,
  string
region key,
  number
x,
  number
y,
  boolean
make_immortal
)

Spawns a specified force if a character (the subject) exists within a faction with an army. It is intended for use at the start of a campaign in a game-created callback (see campaign_manager:add_pre_first_tick_callback), in very specific circumstances.

Parameters:

1

string

Faction key of the subject character.

2

string

Forename key of the subject character from the names table using the full localisation format i.e. names_name_[key].

3

string

Faction key of the force to create.

4

string

list of units to create force with (see documentation for campaign_manager:create_force for more information).

5

string

Home region key for the created force.

6

number

x logical target co-ordinate.

7

number

y logical target co-ordinate.

8

boolean

Set to true to make the created character immortal.

Returns:

  1. nil

Example:

cm:add_pre_first_tick_callback(
    function()
        cm:spawn_army_starting_character_for_faction(
            "wh_dlc03_bst_beastmen",
            "names_name_2147352487",
            "wh_dlc03_bst_jagged_horn",
            "wh_dlc03_bst_inf_ungor_herd_1,wh_dlc03_bst_inf_ungor_herd_1,wh_dlc03_bst_inf_ungor_raiders_0",
            "wh_main_estalia_magritta",
            643,
            188,
            true
        )
    end
)

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7466

campaign_manager:move_character(
  number
cqi,
  number
x,
  number
y,
  [boolean
should replenish],
  [boolean
allow post movement],
  [function
success callback],
  [function
fail callback]
)

Helper function to move a character.

Parameters:

1

number

Command-queue-index of the character to move.

2

number

x co-ordinate of the intended destination.

3

number

y co-ordinate of the intended destination.

4

boolean

optional, default value=false

Automatically replenish the character's action points in script should they run out whilst moving. This ensures the character will reach their intended destination in one turn (unless they fail for another reason).

5

boolean

optional, default value=true

Allow the army to move after the order is successfully completed. Setting this to false disables character movement with campaign_manager:disable_movement_for_character should the character successfully reach their destination.

6

function

optional, default value=nil

Callback to call if the character successfully reaches the intended destination this turn.

7

function

optional, default value=nil

Callback to call if the character fails to reach the intended destination this turn.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7564

campaign_manager:cancel_all_move_character()

Cancels any running monitors started by campaign_manager:move_character. This won't actually stop any characters currently moving.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7723

campaign_manager:is_character_moving(number cqi, function moving callback, function not moving callback)

Calls one callback if a specified character is currently moving, and another if it's not. It does this by recording the character's position, waiting half a second and then comparing the current position with that just recorded.

Parameters:

1

number

Command-queue-index of the subject character.

2

function

Function to call if the character is determined to be moving.

3

function

Function to call if the character is determined to be stationary.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7734

campaign_manager:stop_is_character_moving(number cqi)

Stops any running monitor started with campaign_manager:is_character_moving, by character. Note that once the monitor completes (half a second after it was started) it will automatically shut itself down.

Parameters:

1

number

Command-queue-index of the subject character.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7788

campaign_manager:notify_on_character_halt(number cqi, function callback, [boolean must move first])

Calls the supplied callback as soon as a character is determined to be stationary. This uses campaign_manager:is_character_moving to determine if the character moving so the callback will not be called the instant the character halts.

Parameters:

1

number

Command-queue-index of the subject character.

2

function

Callback to call.

3

boolean

optional, default value=false

If true, the character must be seen to be moving before this monitor will begin. In this case, it will only call the callback once the character has stopped again.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7798

campaign_manager:stop_notify_on_character_halt(number cqi)

Stops any monitor started by campaign_manager:notify_on_character_halt, by character cqi.

Parameters:

1

number

Command-queue-index of the subject character.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7846

campaign_manager:notify_on_character_movement(number cqi, function callback, [boolean land only])

Calls the supplied callback as soon as a character is determined to be moving.

Parameters:

1

number

Command-queue-index of the subject character.

2

function

Callback to call.

3

boolean

optional, default value=false

Only movement over land should be considered.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7854

campaign_manager:stop_notify_on_character_movement(number cqi)

Stops any monitor started by campaign_manager:notify_on_character_movement, by character cqi.

Parameters:

1

number

Command-queue-index of the subject character.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7916

campaign_manager:attack(string attacker, string defender, boolean command queue)

Instruct a character at the head of a military force to attack another. This function is a wrapper for attack function on the underlying game interface, which also enables movement for the character and prints debug output.

Parameters:

1

string

Attacker character string, uses standard character lookup string system.

2

string

Defender character string, uses standard character lookup string system.

3

boolean

Order goes via command queue.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7924

campaign_manager:teleport_to(string character string, number x, number y, [boolean command queue])

Teleports a character to a logical position on the campaign map. This is a validation/output wrapper for a function of the same name on the underlying game interface.
This function can also reposition the camera, so it's best used on game creation to move characters around at the start of the campaign, rather than on the first tick or later.

Parameters:

1

string

Character string of character to teleport. This uses the standard character string lookup system.

2

number

Logical x co-ordinate to teleport to.

3

number

Logical y co-ordinate to teleport to.

4

boolean

optional, default value=false

Order goes via command queue.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7936

campaign_manager:enable_movement_for_character(string char lookup string)

Enables movement for the supplied character. Characters are specified by lookup string. This calls the function of the same name on the game interface, but adds validation and output.

Parameters:

1

string

char lookup string

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7967

campaign_manager:disable_movement_for_character(string char lookup string)

Disables movement for the supplied character. Characters are specified by lookup string. This calls the function of the same name on the game interface, but adds validation and output.

Parameters:

1

string

char lookup string

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7982

campaign_manager:enable_movement_for_faction(string faction key)

Enables movement for the supplied faction. This calls the function of the same name on the game interface, but adds validation and output.

Parameters:

1

string

faction key

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 7997

campaign_manager:disable_movement_for_faction(string faction key)

Disables movement for the supplied faction. This calls the function of the same name on the game interface, but adds validation and output.

Parameters:

1

string

faction key

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8012

campaign_manager:force_add_trait(
  string
character string,
  string
trait key,
  [boolean
show message],
  [number
points],
  [command_queue,
if this command goes to the queue]
)

Forceably adds an trait to a character. This calls the function of the same name on the game interface, but adds validation and output. This output will be shown in the Lua - Traits debug console spool.

Parameters:

1

string

Character string of the target character, using the standard character string lookup system.

2

string

Trait key to add.

3

boolean

optional, default value=false

Show message.

4

number

optional, default value=1

Trait points to add. The underlying force_add_trait function is called for each point added.

5

command_queue,

optional, default value=true

if this command goes to the queue

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8027

campaign_manager:force_add_skill(string character string, string skill key)

Forceably adds a skill to a character. This calls the function of the same name on the game interface, but adds validation and output. This output will be shown in the Lua - Traits debug console spool.

Parameters:

1

string

Character string of the target character, using the standard character string lookup system.

2

string

Skill key to add.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8062

campaign_manager:add_agent_experience(string character string, number experience, [boolean by_level])

Forceably adds experience to a character. This calls the function of the same name on the game interface, but adds output.

Parameters:

1

string

Character string of the target character, using the standard character string lookup system.

2

number

Experience to add.

3

boolean

optional, default value=false

If set to true, the level/rank can be supplied instead of an exact amount of experience which is looked up from a table in the campaign manager

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8082

Back to top

Co-ordinates

campaign_manager:log_to_dis(number x, number y)

Converts a set of logical co-ordinates into display co-ordinates.

Parameters:

1

number

Logical x co-ordinate.

2

number

Logical y co-ordinate.

Returns:

  1. number Display x co-ordinate.
  2. number Display y co-ordinate.

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8123

campaign_manager:distance_squared(number first x, number first y, number second x, number second y)

Returns the distance squared between two positions. The positions can be logical or display, as long as they are both in the same co-ordinate space. The squared distance is returned as it's faster to compare squared distances rather than taking the square-root.

Parameters:

1

number

x co-ordinate of the first position.

2

number

y co-ordinate of the first position.

3

number

x co-ordinate of the second position.

4

number

y co-ordinate of the second position.

Returns:

  1. number distance between positions squared.

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8147

Back to top

Restricting Units, Buildings, and Technologies

The game allows the script to place or lift restrictions on factions recruiting certain units, constructing certain buildings and researching certain technologies. Note that lifting a restriction with one of the following commands does not grant the faction access to that unit/building/technology, as standard requirements will still apply (e.g. building requirements to recruit a unit).

campaign_manager:restrict_units_for_faction(string faction name, table unit list, [boolean should restrict])

Applies a restriction to or removes a restriction from a faction recruiting one or more unit types.

Parameters:

1

string

Faction name.

2

table

Numerically-indexed table of string unit keys.

3

boolean

optional, default value=true

Set this to true to apply the restriction, false to remove it.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8173

campaign_manager:restrict_buildings_for_faction(
  string
faction name,
  table
building list,
  [boolean
should restrict]
)

Restricts or unrestricts a faction from constructing one or more building types.

Parameters:

1

string

Faction name.

2

table

Numerically-indexed table of string building keys.

3

boolean

optional, default value=true

Set this to true to apply the restriction, false to remove it.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8211

campaign_manager:restrict_technologies_for_faction(
  string
faction name,
  table
building list,
  [boolean
should restrict]
)

Restricts or unrestricts a faction from researching one or more technologies.

Parameters:

1

string

Faction name.

2

table

Numerically-indexed table of string technology keys.

3

boolean

optional, default value=true

Set this to true to apply the restriction, false to remove it.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8251

Back to top

Effect Bundles

These this section contains functions that add and remove effect bundles from factions, military forces and regions. In each case they wrap a function of the same name on the underlying game interface, providing input validation and debug output.

campaign_manager:apply_effect_bundle(string effect bundle key, string faction key, number turns)

Applies an effect bundle to a faction for a number of turns (can be infinite).

Parameters:

1

string

Effect bundle key from the effect bundles table.

2

string

Faction key of the faction to apply the effect to.

3

number

Number of turns to apply the effect bundle for. Supply 0 here to apply the effect bundle indefinitely (it can be removed later with campaign_manager:remove_effect_bundle if required).

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8306

campaign_manager:remove_effect_bundle(string effect bundle key, string faction key)

Removes an effect bundle from a faction.

Parameters:

1

string

Effect bundle key from the effect bundles table.

2

string

Faction key of the faction to remove the effect from.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8338

campaign_manager:apply_effect_bundle_to_force(string effect bundle key, string number cqi, number turns)

Applies an effect bundle to a military force by cqi for a number of turns (can be infinite).

Parameters:

1

string

Effect bundle key from the effect bundles table.

2

string

Command queue index of the military force to apply the effect bundle to.

3

number

Number of turns to apply the effect bundle for. Supply 0 here to apply the effect bundle indefinitely (it can be removed later with campaign_manager:remove_effect_bundle_from_force if required).

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8359

campaign_manager:remove_effect_bundle_from_force(string effect bundle key, string number cqi)

Removes an effect bundle from a military force by cqi.

Parameters:

1

string

Effect bundle key from the effect bundles table.

2

string

Command queue index of the military force to remove the effect from.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8391

campaign_manager:apply_effect_bundle_to_characters_force(
  string
effect bundle key,
  string
number cqi,
  number
turns
)

This function applies an effect bundle to a military force for a number of turns (can be infinite). It differs from campaign_manager:apply_effect_bundle_to_force by referring to the force by its commanding character's cqi.

Parameters:

1

string

Effect bundle key from the effect bundles table.

2

string

Command queue index of the military force's commanding character to apply the effect bundle to.

3

number

Number of turns to apply the effect bundle for. Supply 0 here to apply the effect bundle indefinitely (it can be removed later with campaign_manager:remove_effect_bundle_from_characters_force if required).

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8412

campaign_manager:remove_effect_bundle_from_characters_force(string effect bundle key, string number cqi)

Removes an effect bundle from a military force by its commanding character's cqi.

Parameters:

1

string

Effect bundle key from the effect bundles table.

2

string

Command queue index of the character commander of the military force to remove the effect from.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8446

campaign_manager:apply_effect_bundle_to_region(string effect bundle key, string region key, number turns)

Applies an effect bundle to a region for a number of turns (can be infinite).

Parameters:

1

string

Effect bundle key from the effect bundles table.

2

string

Key of the region to add the effect bundle to.

3

number

Number of turns to apply the effect bundle for. Supply 0 here to apply the effect bundle indefinitely (it can be removed later with campaign_manager:remove_effect_bundle_from_region if required).

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8467

campaign_manager:remove_effect_bundle_from_region(string effect bundle key, string number cqi)

Removes an effect bundle from a region.

Parameters:

1

string

Effect bundle key from the effect bundles table.

2

string

Command queue index of the character commander of the military force to remove the effect from.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8499

Back to top

Shroud Manipulation

campaign_manager:lift_all_shroud()

Lifts the shroud on all regions. This may be useful for cutscenes in general and benchmarks in-particular.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8532

Back to top

Diplomacy

The campaign_manager:force_diplomacy function can be used to restrict or unrestrict diplomacy between factions. The following types of diplomacy are available to restrict - not all of them may be supported by each project:

  • "trade agreement"
  • "hard military access"
  • "cancel hard military access"
  • "military alliance"
  • "regions"
  • "technology"
  • "state gift"
  • "payments"
  • "vassal"
  • "peace"
  • "war"
  • "join war"
  • "break trade"
  • "break alliance"
  • "hostages"
  • "marriage"
  • "non aggression pact"
  • "soft military access"
  • "cancel soft military access"
  • "defensive alliance"
  • "client state"
  • "form confederation"
  • "break non aggression pact"
  • "break soft military access"
  • "break defensive alliance"
  • "break vassal"
  • "break client state"
  • "state gift unilateral"
  • "all"

campaign_manager:force_diplomacy(
  string
source,
  string
target,
  string
type,
  boolean
can offer,
  boolean
can accept,
  [both
directions],
  [do
not enable payments]
)

Restricts or unrestricts certain types of diplomacy between factions or groups of factions. Groups of factions may be specified with the strings "all", "faction:faction_key", "subculture:subculture_key" or "culture:culture_key". A source and target faction/group of factions must be specified.
Note that the game interface function that this function calls is force_diplomacy_new, not force_diplomacy.

Parameters:

1

string

Source faction/factions identifier.

2

string

Target faction/factions identifier.

3

string

Type of diplomacy to restrict. See the documentation for the Diplomacy section for available diplomacy types.

4

boolean

Can offer - set to false to prevent the source faction(s) from being able to offer this diplomacy type to the target faction(s).

5

boolean

Can accept - set to false to prevent the target faction(s) from being able to accept this diplomacy type from the source faction(s).

6

both

optional, default value=false

Causes this function to apply the same restriction from target to source as from source to target.

7

do

optional, default value=false

The AI code assumes that the "payments" diplomatic option is always available, and by default this function keeps payments available, even if told to restrict it. Set this flag to true to forceably restrict payments, but this may cause crashes.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8594

campaign_manager:enable_all_diplomacy(boolean enable diplomacy)

Enables or disables all diplomatic options between all factions.

Parameters:

1

boolean

enable diplomacy

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8692

campaign_manager:force_declare_war(
  string
faction key,
  string
faction key,
  boolean
invite faction a allies,
  boolean
invite faction b allies,
  boolean
command queue or not
)

Forces war between two factions. This calls the function of the same name on the game interface, but adds validation and output. This output will be shown in the Lua - Design console spool.

Parameters:

1

string

Faction A key

2

string

Faction B key

3

boolean

Invite faction A's allies to the war

4

boolean

Invite faction B's allies to the war

5

boolean

command queue or not

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8706

Back to top

Objectives and Infotext

Upon creation, the campaign manager automatically creates objectives manager and infotext manager objects which it stores internally. These functions provide a passthrough interface to the most commonly-used functions on these objects. See the documentation on the objectives_manager and infotext_manager pages for more details.

campaign_manager:set_objective(string objective key, [number param a], [number param b])

Pass-through function for objectives_manager:set_objective on the objectives manager. Sets up a scripted objective for the player, which appears in the scripted objectives panel. This objective can then be updated, removed, or marked as completed or failed by the script at a later time.
A key to the scripted_objectives table must be supplied with set_objective, and optionally one or two numeric parameters to show some running count related to the objective. To update these parameter values later, set_objective may be re-called with the same objective key and updated values.

Parameters:

1

string

Objective key, from the scripted_objectives table.

2

number

optional, default value=nil] number param a, First numeric objective parameter. If set, the objective will be presented to the player in the form [objective text]: [param a

First numeric objective parameter. If set, the objective will be presented to the player in the form [objective text]: [param a]. Useful for showing a running count of something related to the objective.

3

number

optional, default value=nil] number param b, Second numeric objective parameter. A value for the first must be set if this is used. If set, the objective will be presented to the player in the form [objective text]: [param a] / [param b

Second numeric objective parameter. A value for the first must be set if this is used. If set, the objective will be presented to the player in the form [objective text]: [param a] / [param b]. Useful for showing a running count of something related to the objective.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8929

campaign_manager:complete_objective(string objective key)

Pass-through function for objectives_manager:complete_objective on the objectives manager. Marks a scripted objective as completed for the player to see. Note that it will remain on the scripted objectives panel until removed with campaign_manager:remove_objective.
Note also that is possible to mark an objective as complete before it has been registered with campaign_manager:set_objective - in this case, it is marked as complete as soon as campaign_manager:set_objective is called.

Parameters:

1

string

Objective key, from the scripted_objectives table.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8940

campaign_manager:fail_objective(string objective key)

Pass-through function for objectives_manager:fail_objective on the objectives manager. Marks a scripted objective as failed for the player to see. Note that it will remain on the scripted objectives panel until removed with campaign_manager:remove_objective.

Parameters:

1

string

Objective key, from the scripted_objectives table.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8949

campaign_manager:remove_objective(string objective key)

Pass-through function for objectives_manager:remove_objective on the objectives manager. Removes a scripted objective from the scripted objectives panel.

Parameters:

1

string

Objective key, from the scripted_objectives table.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8957

campaign_manager:activate_objective_chain(
  string
chain name,
  string
objective key,
  [number
number param a],
  [number
number param b]
)

Pass-through function for objectives_manager:activate_objective_chain. Starts a new objective chain - see the documentation on the objectives_manager page for more details.

Parameters:

1

string

Objective chain name.

2

string

Key of initial objective, from the scripted_objectives table.

3

number

optional, default value=nil

First numeric parameter - see the documentation for campaign_manager:set_objective for more details

4

number

optional, default value=nil

Second numeric parameter - see the documentation for campaign_manager:set_objective for more details

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8965

campaign_manager:update_objective_chain(
  string
chain name,
  string
objective key,
  [number
number param a],
  [number
number param b]
)

Pass-through function for objectives_manager:update_objective_chain. Updates an existing objective chain - see the documentation on the objectives_manager page for more details.

Parameters:

1

string

Objective chain name.

2

string

Key of initial objective, from the scripted_objectives table.

3

number

optional, default value=nil

First numeric parameter - see the documentation for campaign_manager:set_objective for more details

4

number

optional, default value=nil

Second numeric parameter - see the documentation for campaign_manager:set_objective for more details

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8976

campaign_manager:end_objective_chain(string chain name)

Pass-through function for objectives_manager:end_objective_chain. Ends an existing objective chain - see the documentation on the objectives_manager page for more details.

Parameters:

1

string

Objective chain name.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8987

campaign_manager:reset_objective_chain(string chain name)

Pass-through function for objectives_manager:reset_objective_chain. Resets an objective chain so that it may be called again - see the documentation on the objectives_manager page for more details.

Parameters:

1

string

Objective chain name.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 8995

campaign_manager:add_infotext(object first param, ... additional infotext strings)

Pass-through function for infotext_manager:add_infotext. Adds one or more lines of infotext to the infotext panel - see the documentation on the infotext_manager page for more details.

Parameters:

1

object

Can be a string key from the advice_info_texts table, or a number specifying an initial delay in ms after the panel animates onscreen and the first infotext item is shown.

2

...

Additional infotext strings to be shown. add_infotext fades each of them on to the infotext panel in a visually-pleasing sequence.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9003

campaign_manager:remove_infotext(string infotext key)

Pass-through function for infotext_manager:remove_infotext. Removes a line of infotext from the infotext panel.

Parameters:

1

string

infotext key

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9012

campaign_manager:clear_infotext()

Pass-through function for infotext_manager:clear_infotext. Clears the infotext panel.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9020

Back to top

Missions and Events

campaign_manager:trigger_custom_mission(
  string
faction key,
  string
mission key,
  [
boolean use command queue],
  [boolean
do not cancel],
  [boolean
whitelist]
)

Triggers a specific custom mission from its database record key. This mission must be defined in the missions.txt file that accompanies each campaign. This function wraps the cm:trigger_custom_mission function on the game interface, adding debug output and event type whitelisting.

Parameters:

1

string

Faction key.

2

string

Mission key, from missions.txt file.

3

boolean

optional, default value=false

Trigger the mission via the command queue or not.

4

boolean

optional, default value=false

By default this function cancels this custom mission before issuing it, to avoid multiple copies of the mission existing at once. Supply true here to prevent this behaviour.

5

boolean

optional, default value=false

Supply true here to also whitelist the mission event type, so that it displays even if event feed restrictions are in place (see campaign_manager:suppress_all_event_feed_messages and campaign_manager:whitelist_event_feed_event_type).

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9040

campaign_manager:trigger_custom_mission_from_string(
  string
faction key,
  string
mission,
  [
boolean use command queue],
  [boolean
whitelist]
)

Triggers a custom mission from a string passed into the function. The mission string must be supplied in a custom format - see the missions.txt that commonly accompanies a campaign for examples. Alternatively, use a mission_manager which is able to construct such strings internally.
This wraps a function of the same name on the underlying game interface.

Parameters:

1

string

faction key

2

string

Mission definition string.

3

boolean

optional, default value=false

Trigger the mission via the command queue or not.

4

boolean

optional, default value=false

Supply true here to also whitelist the mission event type, so that it displays even if event feed restrictions are in place (see campaign_manager:suppress_all_event_feed_messages and campaign_manager:whitelist_event_feed_event_type).

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9071

campaign_manager:trigger_mission(
  string
faction key,
  string
mission key,
  [
boolean fire immediately],
  [boolean
use command queue],
  [boolean
whitelist]
)

Instructs the campaign director to attempt to trigger a mission of a particular type, based on a mission record from the database. The mission will be triggered if its conditions, defined in the cdir_events_mission_option_junctions, pass successfully. The function returns whether the mission was successfully triggered or not. Note that if the command is sent via the command queue then true will always be returned, regardless of whether the mission successfully triggers.
This function wraps the cm:trigger_mission function on the game interface, adding debug output and event type whitelisting.

Parameters:

1

string

Faction key.

2

string

Mission key, from the missions table.

3

boolean

optional, default value=false

Fire immediately - if this is set, then any turn delay for the mission set in the cdir_event_mission_option_junctions table will be disregarded.

4

boolean

optional, default value=false

Trigger the mission via the command queue or not.

5

boolean

optional, default value=false

Supply true here to also whitelist the mission event type, so that it displays even if event feed restrictions are in place (see campaign_manager:suppress_all_event_feed_messages and campaign_manager:whitelist_event_feed_event_type).

Returns:

  1. boolean mission triggered successfully

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9093

campaign_manager:trigger_dilemma(string faction key, string dilemma key, [function trigger callback])

Triggers dilemma with a specified key, based on a record from the database, preferentially wrapped in an intervention. The delivery of the dilemma will be wrapped in an intervention in singleplayer mode, whereas in multiplayer mode the dilemma is triggered directly. It is preferred to use this function to trigger a dilemma, unless the calling script is running from within an intervention in which case campaign_manager:trigger_dilemma_raw should be used.

Parameters:

1

string

Faction key, from the factions table.

2

string

Dilemma key, from the dilemmas table.

3

function

optional, default value=nil

Callback to call when the intervention actually gets triggered.

Returns:

  1. boolean Dilemma triggered successfully. true is always returned if an intervention is generated.

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9119

campaign_manager:trigger_dilemma_raw(
  
string faction key,
  string
dilemma key,
  [boolean
fire immediately],
  [boolean
whitelist]
)

Compels the campaign director to trigger a dilemma of a particular type, based on a record from the database. This function is a raw wrapper for the cm:trigger_dilemma function on the game interface, adding debug output and event type whitelisting, but not featuring the intervention-wrapping behaviour of campaign_manager:trigger_dilemma. Use this function if triggering the dilemma from within an intervention, but campaign_manager:trigger_dilemma for all other instances.

Parameters:

1

string

Faction key, from the factions table.

2

string

Dilemma key, from the dilemmas table.

3

boolean

optional, default value=false

Fire immediately. If set, the dilemma will fire immediately, otherwise the dilemma will obey any wait period set in the cdir_events_dilemma_options table.

4

boolean

optional, default value=false

Supply true here to also whitelist the dilemma event type, so that it displays even if event feed restrictions are in place (see campaign_manager:suppress_all_event_feed_messages and campaign_manager:whitelist_event_feed_event_type).

Returns:

  1. boolean Dilemma triggered successfully.

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9199

campaign_manager:trigger_dilemma_with_targets(
  
number faction cqi,
  string
dilemma key,
  [number
target faction cqi],
  [number
secondary faction cqi],
  [number
character cqi],
  [number
military force cqi],
  [number
region cqi],
  [number
settlement cqi],
  function
trigger callback
)

Triggers a dilemma with a specified key and one or more target game objects, preferentially wrapped in an intervention. The delivery of the dilemma will be wrapped in an intervention in singleplayer mode, whereas in multiplayer mode the dilemma is triggered directly. It is preferred to use this function to trigger a dilemma with targets, unless the calling script is running from within an intervention in which case campaign_manager:trigger_dilemma_with_targets_raw should be used.
The game object or objects to associate the dilemma with are specified by command-queue index. The dilemma will need to pass any conditions set up in the cdir_events_dilemma_option_junctions table in order to trigger.

Parameters:

1

number

Command-queue index of the faction to which the dilemma is issued. This must be supplied.

2

string

Dilemma key, from the dilemmas table.

3

number

optional, default value=0

Command-queue index of a target faction.

4

number

optional, default value=0

Command-queue index of a second target faction.

5

number

optional, default value=0

Command-queue index of a target character.

6

number

optional, default value=0

Command-queue index of a target military force.

7

number

optional, default value=0

Command-queue index of a target region.

8

number

optional, default value=0

Command-queue index of a target settlement.

9

function

Callback to call when the intervention actually gets triggered.

Returns:

  1. boolean Dilemma triggered successfully. true is always returned if an intervention is generated.

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9230

campaign_manager:trigger_dilemma_with_targets_raw(
  
number faction cqi,
  string
dilemma key,
  [number
target faction cqi],
  [number
secondary faction cqi],
  [number
character cqi],
  [number
military force cqi],
  [number
region cqi],
  [number
settlement cqi],
  function
trigger callback
)

Directly triggers a dilemma with a specified key and one or more target game objects. This function is a raw wrapper for the cm:trigger_dilemma_with_targets function on the game interface, adding debug output and event type whitelisting, but not featuring the intervention-wrapping behaviour of campaign_manager:trigger_dilemma_with_targets. Use this function if triggering the dilemma from within an intervention, but campaign_manager:trigger_dilemma_with_targets (or campaign_manager:trigger_dilemma) in all other instances.
The game object or objects to associate the dilemma with are specified by command-queue index. The dilemma will need to pass any conditions set up in the cdir_events_dilemma_option_junctions table in order to trigger.

Parameters:

1

number

Command-queue index of the faction to which the dilemma is issued. This must be supplied.

2

string

Dilemma key, from the dilemmas table.

3

number

optional, default value=0

Command-queue index of a target faction.

4

number

optional, default value=0

Command-queue index of a second target faction.

5

number

optional, default value=0

Command-queue index of a target character.

6

number

optional, default value=0

Command-queue index of a target military force.

7

number

optional, default value=0

Command-queue index of a target region.

8

number

optional, default value=0

Command-queue index of a target settlement.

9

function

Callback to call when the intervention actually gets triggered.

Returns:

  1. boolean Dilemma triggered successfully.

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9307

campaign_manager:trigger_incident(
  
string faction key,
  string
incident key,
  [boolean
fire immediately],
  [boolean
whitelist]
)

Instructs the campaign director to attempt to trigger a specified incident, based on record from the database. The incident will be triggered if its conditions, defined in the cdir_events_incident_option_junctions, pass successfully. The function returns whether the incident was successfully triggered or not.
This function wraps the cm:trigger_incident function on the game interface, adding debug output and event type whitelisting.

Parameters:

1

string

Faction key.

2

string

Incident key, from the incidents table.

3

boolean

optional, default value=false

Fire immediately - if this is set, then any turn delay for the incident set in the cdir_event_incident_option_junctions table will be disregarded.

4

boolean

optional, default value=false

Supply true here to also whitelist the dilemma event type, so that it displays even if event feed restrictions are in place (see campaign_manager:suppress_all_event_feed_messages and campaign_manager:whitelist_event_feed_event_type).

Returns:

  1. boolean incident was triggered

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9468

campaign_manager:suppress_all_event_feed_messages([boolean activate suppression])

Suppresses or unsuppresses all event feed message from being displayed. With this suppression in place, event panels won't be shown on the UI at all but will be queued and then shown when the suppression is removed. The suppression must not be kept on during the end-turn sequence.
When suppressing, we whitelist dilemmas as they lock the model, and also mission succeeded event types as the game tends to flow better this way.

Parameters:

1

boolean

optional, default value=true

activate suppression

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9591

campaign_manager:whitelist_event_feed_event_type(string event type)

While suppression has been activated with campaign_manager:suppress_all_event_feed_messages an event type may be whitelisted and allowed to be shown with this function. This allows scripts to hold all event messages from being displayed except those of a certain type. This is useful for advice scripts which may want to talk about those messages, for example.
If event feed suppression is not active then calling this function will have no effect.

Parameters:

1

string

Event type to whitelist. This is compound key from the event_feed_targeted_events table, which is the event field and the target field of a record from this table, concatenated together.

Returns:

  1. nil

Example - Whitelisting the "enemy general dies" event type:

cm:whitelist_event_feed_event_type("character_dies_battleevent_feed_target_opponent")

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9624

campaign_manager:disable_event_feed_events(
  boolean
should disable,
  [string
event categories],
  [string
event subcategories],
  [string
event]
)

Wrapper for the function of the same name on the underlying game interface. Disables event feed events by category, subcategory or individual event type. Unlike campaign_manager:suppress_all_event_feed_messages the events this call blocks are discarded. Use this function to prevent certain events from appearing.

Parameters:

1

boolean

Should disable event type(s).

2

string

optional, default value=""

Event categories to disable. Supply "" or false/nil to not disable/enable events by categories in this function call. Supply "all" to disable all event types.

3

string

optional, default value=""

Event subcategories to disable. Supply "" or false/nil to not disable/enable events by subcategories in this function call.

4

string

optional, default value=""

Event to disable. Supply "" or false/nil to not disable/enable an individual event in this function call.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9637

campaign_manager:show_message_event(
  string
faction key,
  string
title loc key,
  string
primary loc key,
  string
secondary loc key,
  boolean
persistent,
  number
index,
  [function
end callback],
  [number
callback delay],
  [boolean
dont whitelist]
)

Constructs and displays an event. This wraps a the cm:show_message_event function of the same name on the underlying episodic_scripting, although it provides input validation, output, whitelisting and a progression callback.

Parameters:

1

string

Faction key to who the event is targeted.

2

string

Localisation key for the event title. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.

3

string

Localisation key for the primary detail of the event. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.

4

string

Localisation key for the secondary detail of the event. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.

5

boolean

Sets this event to be persistent instead of transient.

6

number

Index indicating the type of event.

7

function

optional, default value=false

Specifies a callback to call when this event is dismissed. Note that if another event message shows first for some reason, this callback will be called early.

8

number

optional, default value=0

Delay in seconds before calling the end callback, if supplied.

9

boolean

optional, default value=false

By default this function will whitelist the scripted event message type with campaign_manager:whitelist_event_feed_event_type. Set this flag to true to prevent this.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9659

campaign_manager:show_message_event_located(
  string
faction key,
  string
title loc key,
  string
primary loc key,
  string
secondary loc key,
  number
x,
  number
y,
  boolean
persistent,
  number
index,
  [function
end callback],
  [number
callback delay]
)

Constructs and displays a located event. This wraps a function of the same name on the underlying game interface, although it provides input validation, output, whitelisting and a progression callback.

Parameters:

1

string

Faction key to who the event is targeted.

2

string

Localisation key for the event title. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.

3

string

Localisation key for the primary detail of the event. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.

4

string

Localisation key for the secondary detail of the event. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.

5

number

Logical x co-ordinate of event target.

6

number

Logical y co-ordinate of event target.

7

boolean

Sets this event to be persistent instead of transient.

8

number

Index indicating the type of event.

9

function

optional, default value=false

Specifies a callback to call when this event is dismissed. Note that if another event message shows first for some reason, this callback will be called early.

10

number

optional, default value=0

Delay in seconds before calling the end callback, if supplied.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9744

Back to top

Transient Interventions

intervention offer a script method for locking the campaign UI and progression until the sequence of scripted events has finished. The main intervention interface should primarily be used when creating interventions, but this section lists functions that can be used to quickly create transient throwaway interventions, whose state is not saved into the savegame. See Transient Interventions for more information.

campaign_manager:trigger_transient_intervention(
  
string name,
  function
callback,
  [boolean
debug],
  [function
configuration callback]
)

Creates, starts, and immediately triggers a transient intervention with the supplied paramters. This should trigger immediately unless another intervention is running, in which case it should trigger afterwards.
The trigger callback that is supplied to this function will be passed the intervention object when it is called. This callback must call intervention:complete on this object, or cause it to be called, as the UI will be softlocked until the intervention is completed. See intervention documentation for more information.

Parameters:

1

string

Name for intervention. This should be unique amongst interventions.

2

function

Trigger callback to call.

3

boolean

optional, default value=true

Sets the intervention into debug mode, in which it will produce more output. Supply false to suppress this behaviour.

4

function

optional, default value=nil

If supplied, this function will be called with the created intervention supplied as a single argument before the intervention is started. This allows calling script to configure the intervention before being started.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9843

Back to top

Turn Countdown Events

The turn countdown event system allows client scripts to register a string event with the campaign manager. The campaign manager will then trigger the event at the start of turn, a set number of turns later. This works even if the game is saved and reloaded. It is intended to be a secure mechanism for causing a scripted event to occur a number of turns in the future.

campaign_manager:add_turn_countdown_event(
  string
faction key,
  integer
turns,
  string
event,
  [string
context string]
)

Registers a turn countdown event.

Parameters:

1

string

Key of the faction on whose turn start the event will be triggered.

2

integer

Number of turns from now to trigger the event.

3

string

Event to trigger. By convention, script event names begin with "ScriptEvent"

4

string

optional, default value=""

Optional context string to trigger with the event.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 9903

Back to top

Pre and Post-Battle Events

In single-player mode the campaign manager automatically monitors battles involving the player starting and finishing, and fires events at certain key times during a battle sequence that client scripts can listen for.

The campaign manager fires the following pre-battle events:

EventTrigger Condition
ScriptEventPreBattlePanelOpenedThe pre-battle panel has opened.
ScriptEventPreBattlePanelOpenedAmbushPlayerDefenderThe pre-battle panel has opened and the player is the defender in an ambush.
ScriptEventPreBattlePanelOpenedAmbushPlayerAttackerThe pre-battle panel has opened and the player is the attacker in an ambush.
ScriptEventPreBattlePanelOpenedMinorSettlementThe pre-battle panel has opened and the battle is at a minor settlement.
ScriptEventPreBattlePanelOpenedProvinceCapitalThe pre-battle panel has opened and the battle is at a province capital.
ScriptEventPreBattlePanelOpenedFieldThe pre-battle panel has opened and the battle is a field battle.
ScriptEventPlayerBattleStartedTriggered when player initiates a battle from the pre-battle screen, either by clicking the attack or autoresolve buttons.

    

It also fires the following events post-battle:

Back to top

Values Passed to Battle

Prior to battle, the campaign manager saves certain data into the Scripted Value Registry which can be accessed by battle scripts:

EventTrigger Condition
ScriptEventPlayerWinsBattleThe post-battle panel has opened and the player has won.
ScriptEventPlayerWinsFieldBattleThe post-battle panel has opened and the player won a field battle (including a battle where a settlement defender sallied against them).
ScriptEventPlayerWinsSettlementDefenceBattleThe post-battle panel has opened and the player won a settlement defence battle as the defender (including a battle where the player sallied).
ScriptEventPlayerLosesSettlementDefenceBattleThe post-battle panel has opened and the player lost a settlement defence battle as the defender.
ScriptEventPlayerWinsSettlementAttackBattleThe post-battle panel has opened and the player won a settlement defence battle as the attacker.
ScriptEventPlayerLosesFieldBattleThe post-battle panel has opened and the player has lost a field battle.
ScriptEventPlayerFoughtBattleSequenceCompletedThis event is triggered after a battle sequence in which the player fought a battle has been completed, and the camera has returned to its normal completion.
ScriptEventPlayerBattleSequenceCompletedThis event is triggered after a battle sequence has been completed and the camera has returned to its normal completion, whether an actual battle was fought or not. This would get triggered and not ScriptEventPlayerFoughtBattleSequenceCompleted if the player were maintaining siege or retreating, for example.
Variable NameData TypeDescription
battle_typestringThe string battle type.
primary_attacker_faction_namestringThe faction key of the primary attacking army.
primary_attacker_subculturestringThe subculture key of the primary attacking army.
primary_defender_faction_namestringThe faction key of the primary defending army.
primary_defender_subculturestringThe subculture key of the primary defending army.
primary_attacker_is_playerbooleanWhether the local player is the primary attacker.
primary_defender_is_playerbooleanWhether the local player is the primary defender.

These values can be accessed in battle scripts using core:svr_load_string and core:svr_load_bool.

Back to top

Region Change Monitor

When started, a region change monitor stores a record of what regions a faction holds when their turn ends and compares it to the regions the same faction holds when their next turn starts. If the two don't match, then the faction has gained or lost a region and this system fires some custom script events accordingly to notify other script.

If the monitored faction has lost a region, the event ScriptEventFactionLostRegion will be triggered at the start of that faction's turn, with the region lost attached to the context. Should the faction have gained a region during the end-turn sequence, the event ScriptEventFactionGainedRegion will be triggered, with the region gained attached to the context.

Region change monitors are disabled by default, and have to be opted-into by client scripts with campaign_manager:start_faction_region_change_monitor each time the scripts load.

campaign_manager:start_faction_region_change_monitor(string faction key)

Starts a region change monitor for a faction.

Parameters:

1

string

faction key

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 10546

campaign_manager:stop_faction_region_change_monitor(string faction key)

Stops a running region change monitor for a faction.

Parameters:

1

string

faction key

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 10591

Back to top

Miscellaneous Monitors

campaign_manager:find_lowest_public_order_region_on_turn_start(string faction key)

Starts a monitor for a faction which, on turn start for that faction, triggers a event with the faction and the region they control with the lowest public order attached. This is useful for advice scripts that may wish to know where the biggest public order problems for a faction are. This function will need to be called by client scripts each time the script starts.
The event triggered is ScriptEventFactionTurnStartLowestPublicOrder, and the faction and region may be returned by calling faction() and region() on the context object supplied with it.

Parameters:

1

string

faction key

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 10819

campaign_manager:generate_region_rebels_event_for_faction(string faction key)

RegionRebels events are sent as a faction ends their turn but before the FactionTurnEnd event is received. If called, this function listens for RegionRebels events for the specified faction, then waits for the FactionTurnEnd event to be received and sends a separate event. This flow of events works better for advice scripts.
The event triggered is ScriptEventRegionRebels, and the faction and region may be returned by calling faction() and region() on the context object supplied with it.

Parameters:

1

string

faction key

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 10865

campaign_manager:start_hero_action_listener(string faction key)

This fuction starts a listener for hero actions committed against a specified faction and sends out further events based on the outcome of those actions. It is of most use for listening for hero actions committed against a player faction.
This function called each time the script starts for the monitors to continue running. Once started, the function triggers the following events:
Event NameContext FunctionsDescription
ScriptEventAgentActionSuccessAgainstCharactercharacter
target_character
A foreign agent (character) committed a successful action against a character (target_character) of the subject faction.
ScriptEventAgentActionFailureAgainstCharactercharacter
target_character
A foreign agent (character) failed when attempting an action against a character (target_character) of the subject faction.
ScriptEventAgentActionSuccessAgainstCharactercharacter
garrison_residence
A foreign agent (character) committed a successful action against a garrison residence (garrison_residence) of the subject faction.
ScriptEventAgentActionFailureAgainstCharactercharacter
garrison_residence
A foreign agent (character) failed when attempting an action against a garrison residence (garrison_residence) of the subject faction.

Parameters:

1

string

faction key

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 10899

Back to top

Campaign Audio Triggers

campaign_manager:trigger_campaign_vo(
  string
vo event name,
  character
character,
  delay
delay in seconds (as float i.e. 0.0)
)

This fuction attempts to trigger campaign vo for the given character, the event name to play is passed as a string
which is then given to the sound engine, along with the character, to trigger and call the correct dialogue path.

Parameters:

1

string

looked up in code against wwise IDs

2

character

character

3

delay

delay in seconds (as float i.e. 0.0)

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 10952

Back to top

Benchmark Scripts

campaign_manager:show_benchmark_if_required(
  function
non-benchmark callback,
  string
cindy file,
  number
benchmark duration,
  number
cam x,
  number
cam y,
  number
cam d,
  number
cam b,
  number
cam h
)

Shows a benchmark constructed from supplied parameters if the campaign loaded in benchmark mode, otherwise calls a supplied callback. The intention is for this to be called on or around the first tick of the script that's loaded when playing as the benchmark faction (the benchmark loads with the player as a certain faction). If benchmark mode is set, this function plays the supplied cindy scene for the supplied duration, then quits the campaign.

Parameters:

1

function

Function to call if this campaign has not been loaded in benchmarking mode.

2

string

Cindy file to show for the benchmark.

3

number

Benchmark duration in seconds.

4

number

Start x position of camera.

5

number

Start y position of camera.

6

number

Start distance of camera.

7

number

Start bearing of camera (in radians).

8

number

Start height of camera.

Returns:

  1. nil

Example:

cm:add_first_tick_callback_sp_new(
    function()
        cm:start_intro_cutscene_on_loading_screen_dismissed(
            function()
                cm:show_benchmark_if_required(
                    function() cutscene_intro_play() end,
                    "script/benchmarks/scenes/campaign_benchmark.CindyScene",
                    92.83,
                    348.7,
                    330.9,
                    10,
                    0,
                    10
                );
            end
        );
    end
);

defined in ../working_data/script/_lib/lib_campaign_manager.lua, line 10969

Last updated 05/25/20 01:02:54