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. See the Model Hierarchy documentation for more information.

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 526

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 540

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 563

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 571

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 585

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_name(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 610

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 671

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 718

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 825

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 910

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 956

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 966

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 1092

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 1105

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 1180

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 1252

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 1289

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 1330

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 1387

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 1400

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 1413

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 1426

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 1439

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 1452

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 1465

Back to top

FactionTurnStart Lookup Listeners

It's common for campaign scripts to want to execute some code when a faction starts its turn. Client scripts will typically use core:add_listener to listen for the FactionTurnStart event and then query the event context to determine if it's the correct faction, usually by comparing the faction's name with a known string. This straightforward approach becomes more problematic as more listeners are added, and with a game full of content several dozen listeners can all be responding each time a faction starts its turn, all querying the faction name.

To circumvent this problem, client scripts can instead register listeners with campaign_manager:add_faction_turn_start_listener_by_name. The campaign manager stores these in a lookup table internally, which a lot more computationally efficient than having several dozen client scripts all query the faction name every time a faction starts a turn.

campaign_manager:add_faction_turn_start_listener_by_name(
  string listener name,
  string faction name,
  function callback,
  boolean persistent
)

Adds a listener for the FactionTurnStart event which triggers if a faction with the supplied faction name starts a turn.

Parameters:

1

string

Name by which this listener can be later cancelled using campaign_manager:remove_faction_turn_start_listener_by_name if necessary. It is valid to have multiple listeners with the same name.

2

string

Faction name to watch for, from the factions database table.

3

function

Callback to call if a faction with the specified name starts a turn.

4

boolean

Is this a persistent listener. If this value is false the listener will stop the first time the callback is triggered. If true, the listener will continue until cancelled with campaign_manager:remove_faction_turn_start_listener_by_name.

Returns:

  1. nil

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

campaign_manager:remove_faction_turn_start_listener_by_name(string listener name)

Removes a listener that was previously added with campaign_manager:add_faction_turn_start_listener_by_name. Calling this won't affect other faction turn start listeners.

Parameters:

1

string

listener name

Returns:

  1. nil

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

campaign_manager:add_faction_turn_start_listener_by_culture(
  string listener name,
  string culture key,
  function callback,
  boolean persistent
)

Adds a listener for the FactionTurnStart event which triggers if a faction with the supplied culture key starts a turn.

Parameters:

1

string

Name by which this listener can be later cancelled using campaign_manager:remove_faction_turn_start_listener_by_culture if necessary. It is valid to have multiple listeners with the same name.

2

string

Culture key to watch for, from the cultures database table.

3

function

Callback to call if a faction of the specified culture starts a turn.

4

boolean

Is this a persistent listener. If this value is false the listener will stop the first time the callback is triggered. If true, the listener will continue until cancelled with campaign_manager:remove_faction_turn_start_listener_by_culture.

Returns:

  1. nil

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

campaign_manager:remove_faction_turn_start_listener_by_culture(string listener name)

Removes a listener that was previously added with campaign_manager:add_faction_turn_start_listener_by_culture. Calling this won't affect other faction turn start listeners.

Parameters:

1

string

listener name

Returns:

  1. nil

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

campaign_manager:add_faction_turn_start_listener_by_subculture(
  string listener name,
  string subculture key,
  function callback,
  boolean persistent
)

Adds a listener for the FactionTurnStart event which triggers if a faction with the supplied subculture key starts a turn.

Parameters:

1

string

Name by which this listener can be later cancelled using campaign_manager:remove_faction_turn_start_listener_by_subculture if necessary. It is valid to have multiple listeners with the same name.

2

string

Subculture key to watch for, from the subcultures database table.

3

function

Callback to call if a faction of the specified subculture starts a turn.

4

boolean

Is this a persistent listener. If this value is false the listener will stop the first time the callback is triggered. If true, the listener will continue until cancelled with campaign_manager:remove_faction_turn_start_listener_by_culture.

Returns:

  1. nil

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

campaign_manager:remove_faction_turn_start_listener_by_subculture(string listener name)

Removes a listener that was previously added with campaign_manager:add_faction_turn_start_listener_by_subculture. Calling this won't affect other faction turn start listeners.

Parameters:

1

string

listener name

Returns:

  1. nil

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

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 1717

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 2006

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 2056

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 2067

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 2109

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 2129

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 2164

Back to top

Local Player Faction

The functions in this section report information about the local player faction. Beware of using them in in multiplayer, for making changes to the model based on the identity of the local faction is likely to cause a desync because changes will happen on one machine and not the other. Each function listed here, if called in multiplayer, will throw a script error and fail, unless true is passed in as an argument to force the result. In doing so, the calling script acknowledges the risks described here.

Each function here can only be called on or after the first model tick.

campaign_manager:get_local_faction_name([boolean force result])
Returns the local player faction name.

Parameters:

1

boolean

optional, default value=false

Force the result to be returned instead of erroring in multiplayer.

Returns:

  1. string local faction name

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

campaign_manager:get_local_faction([boolean force result])

Returns the local player faction object.

Parameters:

1

boolean

optional, default value=false

Force the result to be returned instead of erroring in multiplayer.

Returns:

  1. FACTION_SCRIPT_INTERFACE faction

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

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 2234

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 2256

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 2269

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 2283

campaign_manager:model()
Returns a handle to the game model at any time (after the game has been created). See the Model Hierarchy pages for more information about the game model interface.

Returns:

  1. object model

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

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 2304

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 2317

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 2373

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 2392

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 2429

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 2437

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 2445

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 2453

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 2466

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 2478

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 2500

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 2543

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 2578

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 2590

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 2654

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 2684

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 2707

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 2730

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 2745

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 2760

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 2775

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 2795

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 2813

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 2822

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 2831

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 2840

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 2849

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 2858

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 2867

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 2876

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 2885

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 2894

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 2903

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 2912

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 2922

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 2973

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 2999

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 3019

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 3039

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 3065

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 3107

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 3136

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 3184

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 3204

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 3229

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 3257

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 3290

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 3332

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 3358

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 3372

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 3398

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 3424

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 3456

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 3478

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 3504

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 3530

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 3565

campaign_manager:heal_all_units_for_faction(faction faction, [number unary health])

Heals all units in military forces owned by the supplied faction to the specified health. The health may be supplied as a unary value i.e. 0 - 1.

Parameters:

1

faction

faction

2

number

optional, default value=1

unary health

Returns:

  1. nil

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

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 3628

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 3656

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 3684

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 3712

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 3753

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 3780

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 3802

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 3837

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 3863

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 3888

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 3904

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 3940

campaign_manager:is_region_owned_by_faction(string region name, string faction name)

Returns true if the specified region is owned by the specified faction.

Parameters:

1

string

region name

2

string

faction name

Returns:

  1. boolean region is owned by faction

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

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 3987

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 4009

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 4023

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 4031

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 cm:create_storm_for_region function of the same name on the underlying episodic scripting 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 4057

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 4128

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 4138

Back to top

Pending Battle Cache

Using the standard Model Hierarchy interfaces 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 4456

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 4464

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 4487

campaign_manager:pending_battle_cache_get_attacker_subtype(number index of attacker)

Returns just the subtype 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 subtype

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

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 4515

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 4523

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 4546

campaign_manager:pending_battle_cache_get_defender_subtype(number index of defender)

Returns just the subtype 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 subtype

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

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 4574

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 4596

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 4618

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 4627

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 4645

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 4663

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 4671

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 4695

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 4719

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 4728

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 4752

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 4776

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 4785

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 4811

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 4837

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 4855

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 4883

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 4911

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 4929

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 4956

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 4978

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 4986

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 4994

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 5005

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 5027

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 5098

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 5127

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 5150

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 5178

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 5189

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 5221

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 5238

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 5253

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 5325

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 5355

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 5392

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 5429

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 5492

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 5526

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 5558

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 5671

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 5716

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 5748

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 5772

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 5792

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 5810

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 5836

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 5875

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 5906

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 5970

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 6011

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 6030

campaign_manager:steal_escape_key(boolean steal)
Steals or releases the escape key. This wraps the function cm:steal_escape_key function of the same name on the underlying episodic scripting 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 6039

campaign_manager:steal_user_input(boolean steal)
Steals or releases user input. This wraps the cm:steal_user_input function of the same name on the underlying episodic scripting 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 6060

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 6085

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 6099

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 6117

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 6161

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 6189

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 6201

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 6215

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 6226

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 6251

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 6299

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 6319

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 6327

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 6363

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 6376

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 6400

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 6498

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 6506

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 6633

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 6656

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 6712

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 6723

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 6733

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 6741

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 6766

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 6775

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 6858

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 6896

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 6910

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 6962

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 6969

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 6997

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],
  [boolean command queue]
)

Instantly spawn an army with a general on the campaign map. This function is a wrapper for the cm:create_force function provided by the episodic scripting interface, adding 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.

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.

8

boolean

optional, default value=false

Use command queue.

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 7022

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]
)
Instantly spawns an army with a specific general on the campaign map. This function is a wrapper for the cm:create_force_with_general function provided by the underlying episodic scripting interface, adding 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 7118

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]
)
Instantly spawn an army with a specific existing general on the campaign map. This function is a wrapper for the cm:create_force_with_existing_general function provided by the underlying episodic scripting interface, adding debug output and success callback functionality. The general character is specified by character string lookup.

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 7269

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 7398

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 7434

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]
)
Creates an agent of a specified type on the campaign map. This function is a wrapper for the cm:create_agent function provided by the underlying episodic scripting interface. This wrapper function adds validation and success callback functionality.

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 7472

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 7606

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 7691

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 7789

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 7948

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 7959

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 8013

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 8023

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 8071

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 8079

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 8141

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 the cm:attack function on the underlying episodic scripting interface. The wrapper 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 8149

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 function is a wrapper for the cm:teleport_to function on the underlying episodic scripting interface. This wrapper adds debug output and argument validation.
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 8161

campaign_manager:enable_movement_for_character(string char lookup string)
Enables movement for the supplied character. Characters are specified by lookup string. This wraps the cm:enable_movement_for_character function on the underlying episodic scripting 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 8192

campaign_manager:disable_movement_for_character(string char lookup string)
Disables movement for the supplied character. Characters are specified by lookup string. This wraps the cm:disable_movement_for_character function on the underlying episodic scripting 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 8207

campaign_manager:enable_movement_for_faction(string faction key)
Enables movement for the supplied faction. This wraps the cm:enable_movement_for_faction function on the underlying episodic scripting 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 8222

campaign_manager:disable_movement_for_faction(string faction key)
Disables movement for the supplied faction. This wraps the cm:disable_movement_for_faction function on the underlying episodic scripting 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 8237

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 wraps the cm:force_add_trait function on the underlying episodic scripting 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 8252

campaign_manager:force_add_skill(string character string, string skill key)
Forceably adds a skill to a character. This wraps the cm:force_add_skill function on the underlying episodic scripting 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 8287

campaign_manager:add_agent_experience(string character string, number experience, [boolean by_level])
Forceably adds experience to a character. This wraps the cm:add_agent_experience function on the underlying episodic scripting interface, but adds validation and 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 8307

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 8348

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 8372

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 8398

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 8436

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 8476

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 episodic_scripting 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 8531

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 8563

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 8584

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 8616

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 8637

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 8671

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 8692

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 8724

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 8757

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 this wraps the function cm:force_diplomacy_new on the underlying episodic scripting interface.

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 8819

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 8917

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 wraps the cm:force_declare_war function of the same name on the underlying episodic scripting 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 8931

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 9154

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 9165

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 9174

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 9182

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 9190

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 9201

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 9212

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 9220

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 9228

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 9237

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 9245

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 9265

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 the cm:trigger_custom_mission_from_string function on the underlying episodic scripting interface, adding output and the optional whitelisting functionality.

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 9296

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 9318

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 9344

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 9428

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 9459

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 9536

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 9697

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 9820

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 9853

campaign_manager:disable_event_feed_events(
  boolean should disable,
  [string event categories],
  [string event subcategories],
  [string event]
)
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.
The function wraps the cm:disable_event_feed_events function on the underlying episodic scripting interface.

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 9866

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 9889

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 the cm:show_message_event_located function of the same name on the underlying episodic scripting interface, although it also 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 9974

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 10073

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 10133

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 10777

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 10821

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 11050

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 11096

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 11130

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 11183

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 11200

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