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. The model hierarchy interfaces allow scripts to query the state of the model at any time.

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

Loaded in Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 234

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 661

campaign_manager:get_campaign_name()
Returns the name of the campaign.

Returns:

  1. string campaign name

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 675

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 698

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 706

campaign_manager:require_path_to_campaign_faction_folder()
Adds all player factions' 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 720

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.
See also core:load_global_script, which this function calls.

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 747

campaign_manager:load_local_faction_script(string script name appellation)
Loads a script file in the factions subfolder that corresponds to the name of each 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. boolean file loaded successfully

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 782

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 841

Back to top

Loading Linear Sequence Campaign Files

It's sometimes desirable to set up a linear sequence of campaign content that involves a series of different loading configurations. The most common example of this would be some introductory content for a campaign - for example a short campaign tutorial, followed by a scripted battle, followed by a wider campaign tutorial, followed by another scripted battle, followed by the open world campaign. The various campaign sections in such a setup will likely be housed in different files, and for this kind of gameplay sequence to work the loading scripts must be able to work out which files to load in each case, based on values saved into both the savegame and the scripted value registry. This quickly becomes an involved problem to solve as the system has to cope with being loaded into from a savegame, surviving a handler reset, loading into a specified state because of tweaker values (for debugging), as well as handling normal progression.

The functions described in this section provide a simple interface to set up such linear sequences of campaign gameplay, where A leads to B leads to C and so on. There is no limit to the number of campaign segments that may be chained together using this system.

Client scripts may establish one or more configurations by making calls to campaign_manager:add_linear_sequence_configuration. When all configurations are established campaign_manager:load_linear_sequence_configuration may be called, which picks a configuration and loads the local faction script file specified in that configuration. During the running of that script (or any scripted battle that subsequently loads), another configuration may be set up as the next configuration to load by setting the svr boolean of that second configuration to true. When the campaign script next loads (unless from the frontend or a savegame) it will pick the new configuration based on the value of the svr boolean.

When adding a configuration a tweaker may be specified in the call to campaign_manager:add_linear_sequence_configuration. By setting this same tweaker prior to the game starting the configuration loader can be forced to load that configuration.

campaign_manager:add_linear_sequence_configuration(
  string name,
  string filename,
  string svr bool,
  [boolean is default],
  [string tweaker]
)

Adds a linear sequence configuration. All added linear sequences will be queried when campaign_manager:load_linear_sequence_configuration is called, with one being picked and loaded based on the game state.
The name, svr boolean, and tweaker name (where set) of each configuration must be unique compared to other configurations.

Parameters:

1

string

Script name for this configuration. This must not contain spaces. The name of a saved value which gets saved with the campaign is derived from this name.

2

string

Appellation of script file to be passed to campaign_manager:load_local_faction_script (which performs the actual script loading) if this configuration is chosen by campaign_manager:load_linear_sequence_configuration.

3

string

Name of a scripted value registry boolean which, if set, causes this configuration to be loaded. When the transition from some other configuration to this configuration is desired, the game scripts should set this boolean value to true with ScriptedValueRegistry:SaveBool. The next time the campaign scripts load and campaign_manager:load_linear_sequence_configuration, this configuration will be chosen. Once chosen in this manner, the svr boolean is set back to false again.

4

boolean

optional, default value=false

Make this the default configuration if no other is chosen. Only one default configuration may be set.

5

string

optional, default value=false

Name of tweaker value which, if set, forces this configuration to be chosen for loading. This is used for debugging scripts and forcing the game to start in a particular configuration.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 941

campaign_manager:load_linear_sequence_configuration()
Picks a configuration previously added with campaign_manager:add_linear_sequence_configuration and loads it, based on certain values:
  • The function first looks at svr boolean values for each configuration. If one is set then that configuration is chosen, and the boolean is set back to false. These booleans should be individually set to true by client scripts when they wish to transition from loading scripts in one configuration to another.

  • If no svr boolean is set and it's a new game, the function checks the value of the tweaker specified by each configuration. If any tweaker is set then that configuration is loaded.

  • If no svr boolean is set and it's a not a new game, the function checks to see if a saved value exists corresponding to any configuration. If one is found then that configuration is loaded.

  • If no configuration has been loaded so far then a registry value derived from the name of each configuration is checked, which would indicate that the handler has been forceably reset. If any configuration matches then that configuration is loaded.

  • If still no configuration has been loaded then all configurations are checked to see if there's a default. If there is a default configuration then it is loaded.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 1009

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 1155

campaign_manager:load_named_value(
  string value name,
  object default value,
  userdata context,
  [boolean allow default value to be nil]
)

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.

4

boolean

optional, default value=false

If set to true, the default value can be nil.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 1288

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 1369

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 1379

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 1582

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 1595

campaign_manager:save_named_value(
  string value name,
  object value,
  userdata context,
  [boolean value can be nil]
)

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.

4

boolean

optional, default value=false

If set to true, the value can be nil.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 1680

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 of type boolean, number, string or table, where that table itself contains only booleans, numbers, string or other tables. 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, string or table.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 1779

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 1901

Back to top

UI Creation

The UI is loaded after the game model during the game load sequence, and is the first point in the load sequence at which all script interfaces can be guaranteed to be present. Client scripts can register functions to be called when the UI is loaded with any of the functions listed below. They in turn make use of the equivalent functionality provided by the core object, documented here: UI Creation and Destruction.

Please note that it's strongly preferred to start game scripts from the first tick, using the functions listed in the First Tick section below. The first tick is synchronised to model updates, where UI events such as UICreated are not, so scripts called from the latter may desync in multiplayer games. Be sure not to make calls to the model from within callbacks registered to UI events that could be called in multiplayer games.

campaign_manager:add_ui_created_callback(function callback)

Registers a function to be called when the UI is created. 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2035

campaign_manager:add_ui_created_callback_sp_new(function callback)

Registers a function to be called when the ui is created in a new singleplayer game.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2052

campaign_manager:add_ui_created_callback_sp_each(function callback)

Registers a function to be called when the ui is created in any singleplayer game.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2069

campaign_manager:add_ui_created_callback_mp_new(function callback)

Registers a function to be called when the ui is created in a new multiplayer game. Be sure not to make any calls to the model from within this callback.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2086

campaign_manager:add_ui_created_callback_mp_each(function callback)

Registers a function to be called when the ui is created in any multiplayer game. Be sure not to make any calls to the model from within this callback.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2103

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2157

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2170

campaign_manager:add_post_first_tick_callback(function callback)

Registers a function to be called when the first tick occurs, but after 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2183

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2196

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2209

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2222

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2235

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2248

Back to top

Faction Intro Cutscenes

campaign_manager:setup_campaign_intro_cutscene(
  string faction key,
  table default camera position,
  [string cindy key or duration],
  [table advice keys],
  [function end callback],
  [function cutscene configurator],
  [string movie],
  [number hide faction leader],
  [function pre-cindyscene callback],
  [boolean is the intro exclusive to the Realm of Chaos victory conditions. If supplied as true]
)

Sets up defines common behaviour for intro cutscenes that factions scripts can use invoke of defining their own behaviour manually. In singleplayer mode, an intro cutscene will be started when the loading screen is dismised that will play the supplied cindyscene. In multiplayer mode, the camera is positioned at the default camera position. In both cases the script event ScriptEventIntroCutsceneFinished event is triggered when the sequence completes.

Parameters:

1

string

The faction key that this cutscene is triggering for

2

table

Default camera position. This should be a lua table containing x, y, d, b and h fields.

3

string

optional, default value=nil

string key of the cindy scene to play, from table campaign_cinematic_resources, or (if you're building a new cutscene and editing it using cutscene_config_callback) the number duration of that cutscene. If left as nil, then a placeholder non-cindy cutscene will be shown with a duration of 3 seconds.

4

table

optional, default value=nil

Table of advice keys that may be played within the cutscene.

5

function

optional, default value=nil

End callback. If a function is supplied here, it will be called when the intro cutscene ends;

6

function

optional, default value=nil

Cutscene configurator callback. If a function is supplied here, it will be called after the intro cutscene is declared but before campaign_cutscene:start is called, and will be passed the campaign_cutscene as a single argument. The function can therefore make configuration calls to the cutscene before it starts. This is useful if nonstandard behaviour for the cutscene is desired.

7

string

optional, default value=nil

Pre-cindyscene fullscreen movie to play, if one is desired. This should be a key from the videos table.

8

number

optional, default value=false

Hide the faction leader's character model while the intro cutscene is playing. If the boolean value true is supplied here, or 0, the faction leader's model will be hiddent at the start of the cutscene and unhidden at the end. If a positive number is supplied they will be hidden at the start, and then unhidden that many seconds in to the cutscene (or when the cutscene is skipped, whichever comes first).

9

function

optional, default value=nil

Pre-cindyscene progress-blocking callback. If supplied, this callback will be called prior to the cindyscene starting. When called, it will be supplied a progress function as a single argument. The cindyscene will not start until the progress function is called, allowing client scripts to determne when this should happen. The intended usage for this is to show an incident prior to the cindyscene launching, but this mechanism could be put to other uses.

10

boolean

optional, default value=false

the intro will only play when the Realm of Chaos victory conditions are enabled (an option available in MPC).

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2578

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2732

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2743

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2751

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2762

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2770

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2781

Back to top

Post-Battle Listeners

Because the game model can change dramatically after a battle - in particular regarding character instance stability - these functions provide safer listeners that work around this instability.

campaign_manager:add_immortal_character_defeated_listener(
  string listener name,
  function battle condition,
  function callback,
  [boolean fire if faction destroyed]
)

Add a callback that fires when an immortal character is defeated in battle, as well as conditions relating to the battle that can fire the callback.
This is useful as there are some instabilities with waiting for, and responding to, the defeat of an immortal character with the typical 'BattleCompleted' event: an immortal character is liable to die and re-spawn with a new, irreconcilable character instance that may break your listeners.
This function listens for the re-spawning of the temporarily dead immortal character, and performs your provided callback after the respawn.

Parameters:

1

string

The name given to the internal 'BattleCompleted' listener. Should be descriptive but needn't be unique.

2

function

The condition a completed battle must meet to trigger this callback, or true to always pass.

3

function

The callback that will be executed if an immortal character is defeated in a battle meeting the battle condition, immediately after the immortal character respawns. Must have two parameters, for the victorious and defeated generals' family member interfaces: the victorious character is always the winning side's main army.

4

boolean

optional, default value=false

If false, the callback will not fire if an immortal character has been defeated AND their faction has been destroyed.

Returns:

  1. nil

Example:

In this example, when a Norscan army wins an attack, any defeated lords who were immortal get force-killed permanently.
cm:add_immortal_character_defeated_listener(
    "NorscaLordDefeatedConfederateEvent",
    function(context)
        return cm:pending_battle_cache_subculture_is_attacker("wh_dlc08_sc_nor_norsca")
            and cm:pending_battle_cache_attacker_victory();
    end,
    function (victorious_fm, defeated_fm)
        local defeated_character_cqi = defeated_fm:character():command_queue_index();
        out("Immortal character was briefly killed post-battle but has respawned with a new character instance: "
             .. defeated_fm:character_details():get_forename());
        out("Killing them permanently.");
        cm:set_character_immortality("character_cqi:" .. defeated_character_cqi, false);
        cm:kill_character(defeated_character_cqi, false);
    end
);

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2803

Back to top

PooledResourceChanged Lookup Listener

PooledResourceChanged events trigger very frequently, and scripts that wish to know about pooled resource changes usually only want to know about resource changes for a particular faction. As such, a lookup listener which monitors pooled resource changes by faction is provided here.

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

Adds a listener for the PooledResourceChanged event which triggers if a faction with the supplied key experiences a change in a pooled resource value.

Parameters:

1

string

Name by which this listener can be later cancelled using campaign_manager:remove_pooled_resource_changed_listener_by_faction 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 the specified faction experiences a pooled resource change.

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2911

campaign_manager:remove_pooled_resource_changed_listener_by_faction(string listener name)

Removes a listener that was previously added with campaign_manager:add_pooled_resource_changed_listener_by_faction.

Parameters:

1

string

listener name

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2922

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

Adds a listener for the PooledResourceRegularIncome event which triggers if a faction with the supplied key receive a regular income.

Parameters:

1

string

Name by which this listener can be later cancelled using campaign_manager:remove_pooled_resource_regular_income_listener_by_faction 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 the specified faction experiences a pooled resource change.

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2930

campaign_manager:remove_pooled_resource_regular_income_listener_by_faction(string listener name)

Removes a listener that was previously added with campaign_manager:add_pooled_resource_regular_income_listener_by_faction.

Parameters:

1

string

listener name

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2941

Back to top

Faction Pooled Resource Tracking

A pooled resource tracking monitor will attempt to track pooled resource changes for a specified faction and log the total amount of each pooled resource the faction has gained and spent/lost over time. Each pooled resource as a whole, and each factor of each pooled resource are logged. This allows client scripts to query the total amount of a particular pooled resource gained from or spent on a particular factor over the lifetime of the campaign (e.g. how much Meat has been earned from Ogre Camps, or how many Skulls have been sent to the Skull Throne).

When a pooled resource change occurs for a tracked faction a ScriptEventTrackedPooledResourceChanged event or ScriptEventTrackedPooledResourceRegularIncome is triggered by the tracking monitor. Listening scripts can query the context object provided by this event for the following:

Function NameDescription
factionThe faction for which pooled resource has changed
has_factionDoes this pooled resource relate to a faction (this will always be true)
resourceThe pooled resource that's changed
factorThe pooled resource factor of the change
amountThe value of the change
resource_gainedThe total amount gained of the relevant pooled resource over the lifetime of the campaign
resource_spentThe total amount spent of the relevant pooled resource over the lifetime of the campaign
factor_gainedThe total amount gained of the relevant pooled resource factor over the lifetime of the campaign
factor_spentThe total amount spent of the relevant pooled resource factor over the lifetime of the campaign

As well as listening for change events, client scripts can also directly tracked query pooled resource values by calling campaign_manager:get_total_pooled_resource_changed_for_faction, campaign_manager:get_total_pooled_resource_gained_for_faction and campaign_manager:get_total_pooled_resource_spent_for_faction.

The campaign manager currently start a pooled resource tracker for each human-controlled faction automatically.

campaign_manager:start_pooled_resource_tracker_for_faction(string faction key)

Starts a pooled resource tracking monitor for the supplied faction.
A pooled resource tracking monitor for a faction should only be started once per campaign. Once started, tracking monitors will save themselves in to the savegame and then automatically restart on load.

Parameters:

1

string

Key of the faction to track, from the factions database table.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2968

campaign_manager:are_pooled_resources_tracked_for_faction(string faction key)

Returns whether a pooled resource tracker has been started for the specified faction.

Parameters:

1

string

Key of the faction to query, from the factions database table.

Returns:

  1. boolean has tracker been started

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3093

campaign_manager:get_total_pooled_resource_changed_for_faction(
  string faction key,
  string pooled resource key,
  [string factor key]
)

Gets the total spent and gained of a pooled resource or pooled resource factor for a particular faction. A tracking monitor must be started for the specified faction before this function can be called.
If a factor key is specified then the spent and gained values returned relate to the factor for the specified pooled resource. If no factor key is specified, then the total spent and gained for the pooled resource (for all factors) is returned.

Parameters:

1

string

Key of the faction to query, from the factions database table.

2

string

Key of the pooled resource to query, from the pooled_resources database table.

3

string

optional, default value=nil

Key of the pooled resource factor to query, from the pooled_resource_factors database table.

Returns:

  1. number spent
  2. number gained

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3106

campaign_manager:get_total_pooled_resource_gained_for_faction(
  string faction key,
  string pooled resource key,
  [string factor key]
)

Gets the total amount of a pooled resource or pooled resource factor gained by a particular faction. A tracking monitor must be started for the specified faction before this function can be called.
If a factor key is specified then the gained value returned relates to the factor for the specified pooled resource. If no factor key is specified, then the total gained for the pooled resource (for all factors) is returned.

Parameters:

1

string

Key of the faction to query, from the factions database table.

2

string

Key of the pooled resource to query, from the pooled_resources database table.

3

string

optional, default value=nil

Key of the pooled resource factor to query, from the pooled_resource_factors database table.

Returns:

  1. number gained

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3156

campaign_manager:get_total_pooled_resource_spent_for_faction(
  string faction key,
  string pooled resource key,
  [string factor key]
)

Gets the total amount of a pooled resource or pooled resource factor spent/lost by a particular faction. A tracking monitor must be started for the specified faction before this function can be called.
If a factor key is specified then the spent value returned relates to the factor for the specified pooled resource. If no factor key is specified, then the total spent/lost for the pooled resource (for all factors) is returned.

Parameters:

1

string

Key of the faction to query, from the factions database table.

2

string

Key of the pooled resource to query, from the pooled_resources database table.

3

string

optional, default value=nil

Key of the pooled resource factor to query, from the pooled_resource_factors database table.

Returns:

  1. number spent

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3169

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3197

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3474

Back to top

Timer Callbacks

Timer functionality - the ability for scripts to say that a function should be called after a certain interval (e.g. a second) - is provided by the timer_manager object. The functions in this section provide a pass-through interface to the equivalent functions on the timer manager.

During the end-turn sequence the update rate of the campaign model can accelerate wildly. This will cause a function registered to be called after five seconds to happen near-instantly during the end turn sequence, for example. To ameliorate this effect, the timer manager will automatically check the real world time once the interval has completed. If the real world time is less than would be expected then the callback is retried repeatedly until the real world interval has elapsed.

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

Calls the supplied function after the supplied interval in seconds using a timer synchronised to the campaign model. A string name for the callback may optionally be provided to allow the callback to be cancelled later.
This function call is passed through to timer_manager:callback - this campaign_manager alias is provided purely for convenience.

Parameters:

1

function

Callback to call.

2

number

Interval 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 (before it triggers) with campaign_manager:remove_callback.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3525

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

Calls the supplied function repeatedly after the supplied period in seconds using a timer synchronised to the campaign model. 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.
This function call is passed through to timer_manager:callback - this campaign_manager alias is provided purely for convenience.

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.

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3536

campaign_manager:remove_callback(string name)

Removes a callback previously added with campaign_manager:callback or campaign_manager:repeat_callback by name. All callbacks with a name matching that supplied will be cancelled and removed.
This function call is passed through to timer_manager:remove_callback - this campaign_manager alias is provided purely for convenience.

Parameters:

1

string

Name of callback to remove.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3547

campaign_manager:real_callback(function callback, number interval, [string name])

Adds a real callback to be called after the supplied interval has elapsed. Real timers are synchronised to UI updates, not to the game model - see Real Timers for more information.
This function call is passed through to timer_manager:real_callback - this campaign_manager alias is provided purely for convenience.

Parameters:

1

function

Callback to call.

2

number

Interval after which to call the callback. This should be in milliseconds, regardless of game mode.

3

string

optional, default value=nil

Callback name, by which it may be later removed with campaign_manager:remove_real_callback. If omitted the callback may not be cancelled.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3556

campaign_manager:repeat_real_callback(function callback, number interval, [string name])

Adds a repeating real callback to be called each time the supplied interval elapses. Real timers are synchronised to UI updates, not to the game model - see Real Timers for more information.
This function call is passed through to timer_manager:repeat_real_callback - this campaign_manager alias is provided purely for convenience.

Parameters:

1

function

Callback to call.

2

number

Repeating interval after which to call the callback. This should be in milliseconds, regardless of game mode.

3

string

optional, default value=nil

Callback name, by which it may be later removed with campaign_manager:remove_real_callback. If omitted the repeating callback may not be cancelled.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3567

campaign_manager:remove_real_callback(string name)

Removes a real callback previously added with campaign_manager:real_callback or campaign_manager:repeat_real_callback by name. All callbacks with a name matching that supplied will be cancelled and removed.
This function call is passed through to timer_manager:remove_real_callback - this campaign_manager alias is provided purely for convenience.

Parameters:

1

string

Name of callback to remove.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3578

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3601

campaign_manager:has_local_faction()
Returns whether a local faction exists. This should only return false in an autotest without a local faction.

Returns:

  1. boolean local faction exists

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3620

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 faction

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3628

campaign_manager:get_local_faction_culture([boolean force result])
Returns the cached culture key of the local human player. If no local faction has been set then a blank string is returned - this should only happen in autoruns.

Parameters:

1

boolean

optional, default value=false

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

Returns:

  1. string local faction culture

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3652

campaign_manager:get_local_faction_subculture([boolean force result])
Returns the cached subculture key of the local human player. If no local faction has been set then a blank string is returned - this should only happen in autoruns.

Parameters:

1

boolean

optional, default value=false

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

Returns:

  1. string local faction subculture

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3670

campaign_manager:is_local_players_turn([boolean force result])
Returns whether it's currently the local player's turn.

Parameters:

1

boolean

optional, default value=false

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

Returns:

  1. boolean is local player's turn

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3689

Back to top

General Querying

campaign_manager:is_faction_human(string faction key)

Returns whether the specified faction is human.

Parameters:

1

string

Faction key, from the factions database table.

Returns:

  1. table human factions

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3714

campaign_manager:get_human_factions()
Returns a numerically-indexed table containing the string keys of all human player-controlled factions within the game. This includes idle human factions, which are factions that started as player-controlled but where the human player has dropped and not yet resumed.

Returns:

  1. table human faction keys

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3729

campaign_manager:get_human_factions_of_culture(string culture)

Returns a numerically-indexed table containing the string keys of all human player-controlled factions in the game that match the provided culture, including idle human factions.

Parameters:

1

string

Key of the culture of human players to get.

Returns:

  1. table human factions matching specified culture.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3743

campaign_manager:get_human_factions_of_subculture(string subculture)

Returns a numerically-indexed table containing the string keys of all human player-controlled factions in the game that match the provided subculture, including idle human factions.

Parameters:

1

string

Key of the subculture of human players to get.

Returns:

  1. table human factions matching specified subculture.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3752

campaign_manager:get_active_human_factions()
Returns a numerically-indexed table containing the string keys of all active human player-controlled factions in the game. This does not include idle human factions - see campaign_manager:get_human_factions.

Returns:

  1. table active human factions

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3793

campaign_manager:get_factions_by_filter(function filter)

Returns an indexed table of faction objects the pass the supplied filter condition function.

Parameters:

1

function

Filter function. This should be a function that accepts a single faction argument and returns a boolean value. If the value equates to true then the faction is added to the table of factions to return.

Returns:

  1. table factions that pass the filter

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3817

campaign_manager:get_factions_by_culture(string culture key)

Returns an indexed table of faction objects that belong to the supplied culture.

Parameters:

1

string

Culture key, from the cultures database table.

Returns:

  1. table factions belonging to culture

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3839

campaign_manager:get_factions_by_subculture(string subculture key)

Returns an indexed table of faction objects that belong to the supplied subculture.

Parameters:

1

string

Subulture key, from the cultures_subcultures database table.

Returns:

  1. table factions belonging to subculture

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

campaign_manager:are_any_factions_human([table faction list], [string culture], [string subculture])

Returns true if any factions in the supplied list are human. If no list is provided, all factions in the game are checked.
Culture and/or subculture keys may optionally be provided, in which case if any faction of that culture/subculture is human, true is returned.

Parameters:

1

table

optional, default value=nil

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

2

string

optional, default value=nil

The key of the culture we want to check.

3

string

optional, default value=nil

The key of the subculture we want to check.

Returns:

  1. boolean Whether a human faction of the specified criteria and/or in the provided list was found.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3873

campaign_manager:are_any_factions_ai([table faction list], [string culture], [string subculture])

Returns true if any factions in the supplied list are ai. If no list is provided, all factions in the game are checked.
Culture and/or subculture keys may optionally be provided, in which case if any faction of that culture/subculture is ao, true is returned.

Parameters:

1

table

optional, default value=nil

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

2

string

optional, default value=nil

The key of the culture we want to check.

3

string

optional, default value=nil

The key of the subculture we want to check.

Returns:

  1. boolean Whether an ai faction of the specified criteria and/or in the provided list was found.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3885

campaign_manager:are_all_factions_human([table faction list], [string culture], [string subculture])

Returns true if all factions in the supplied list are human. If no list is provided, all factions in the game are checked.
Culture and/or subculture keys may optionally be provided, in which case if all factions of that culture/subculture are human, true is returned.

Parameters:

1

table

optional, default value=nil

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

2

string

optional, default value=nil

The key of the culture we want to check.

3

string

optional, default value=nil

The key of the subculture we want to check.

Returns:

  1. boolean Whether all factions in the specified criteria are human.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3897

campaign_manager:are_all_factions_ai([table faction list], [string culture], [string subculture])

Returns true if all factions in the supplied list are ai. If no list is provided, all factions in the game are checked.
Culture and/or subculture keys may optionally be provided, in which case if all factions of that culture/subculture are ai, true is returned.

Parameters:

1

table

optional, default value=nil

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

2

string

optional, default value=nil

The key of the culture we want to check.

3

string

optional, default value=nil

The key of the subculture we want to check.

Returns:

  1. boolean Whether all factions in the specified criteria are ai.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3909

campaign_manager:whose_turn_is_it_single()
Returns faction object of the faction whose turn it is currently. This only works in singleplayer mode - in scripts that may be run in multiplayer mode call campaign_manager:whose_turn_is_it, which returns a particular faction of the many currently taking their turn.

Returns:

  1. faction faction

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3988

campaign_manager:whose_turn_is_it()
Returns a list of all factions whose turn it is currently. This can be used in singleplayer or multiplayer.

Returns:

  1. faction_list faction list

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4006

campaign_manager:is_factions_turn_by_key(string faction key)

Returns true if it's the supplied faction turn. The faction is specified by key.

Parameters:

1

string

Faction key, from the factions database table.

Returns:

  1. boolean is faction's turn

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4019

campaign_manager:is_human_factions_turn()
Returns whether it's currently the turn of any human-controlled faction.

Returns:

  1. boolean is any human faction's turn

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4033

campaign_manager:is_multiplayer()
Returns true if the campaign is multiplayer.

Returns:

  1. boolean is multiplayer campaign

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4047

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4060

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4079

campaign_manager:is_first_tick()
Returns whether or not we're actively processing the first tick callbacks.

Returns:

  1. boolean is first tick

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4087

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 game model interfaces such as model.

Returns:

  1. model model

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4095

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. episodic_scripting game interface

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4108

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4121

campaign_manager:is_processing_battle()
Returns true if a battle sequence is currently happening. Scripts can query whether a battle sequence is happening to know whether to proceed with gameplay events that should only happen outside of a battle. In particular, campaign_manager:progress_on_battle_completed uses this mechanism to know when to trigger its callback.
A battle sequence starts when the PendingBattle event is received, and ends when either the BattleCompleted event is received for battles not involving a human participant, or two seconds after the BattleCompletedCameraMove event is received if the battle did involve a human participant. It is safe to use in multiplayer, and also works for battles that aren't fought (withdrawal, maintain siege etc).

Returns:

  1. boolean battle is happening

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4177

campaign_manager:is_pending_battle_active()
Returns whether a pending battle is active (i.e. we are immediately pre-battle or post-battle). If the pending battle is active the function will also return whether the battle has been fought (note however that on the first tick when returning from battle this will still be false).

Returns:

  1. boolean is a pending battle active
  2. boolean active pending battle has been fought already

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4186

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4201

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4209

campaign_manager:null_interface()
Returns a scripted-generated object that emulates a campaign null interface.

Returns:

  1. null_interface

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4222

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4234

campaign_manager:tol_campaign_key()
Returns the Time of Legends campaign key. If the current campaign is not a Time of Legends campaign, then nil is returned.

Returns:

  1. string time of legends campaign key or nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4243

campaign_manager:is_subculture_in_campaign(string subculture key, [boolean factions present now])

Returns whether the subculture is present in the campaign. By default, this will check the cached data of subcultures present on turn one of the campaign.

Parameters:

1

string

Subculture key, from the cultures_subcultures database table.

2

boolean

optional, default value=false

Set to true to actively check the factions on the map right now, instead of looking in the cached data. This check is more expensive.

Returns:

  1. boolean subculture is present

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4251

campaign_manager:is_intro_cutscene_playing()
Returns whether an intro cutscene is currently playing.

Returns:

  1. is intro cutscene playing

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4302

campaign_manager:set_cutscene_playing_allowed()
Sets a flag which will block the starting of cutscenes if they are not allowed.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4309

campaign_manager:is_cutscene_playing_allowed()
Returns whether we allow the starting of cutscenes.

Returns:

  1. is cutscene playing allowed

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

campaign_manager:has_intro_cutscene_played()
Returns whether an intro cutscene has been played this campaign playthrough at all.

Returns:

  1. has intro cutscene played

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4323

Back to top

DLC Ownership

campaign_manager:faction_has_dlc_or_is_ai(string dlc key, string faction key)

Returns true if the provided faction key is a player and owns the specified DLC key

Parameters:

1

string

The product key being checked, from the ownership_products table

2

string

The key of the faction being checked

Returns:

  1. boolean true if the faction was player-controlled and owns the DLC, or if the faction was AI, otherwise false.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4341

campaign_manager:is_dlc_flag_enabled_by_anyone(string dlc key)

Returns true if any human players own the provided DLC key, or if we're in autotest.

Parameters:

1

string

The product key being checked, from the ownership_products table

Returns:

  1. boolean true if any players own the product key, or if we're in autotest, otherwise false.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4358

campaign_manager:is_dlc_flag_enabled_by_everyone(string dlc key)

Returns true if all human players own the provided DLC key, or if we're in autotest.

Parameters:

1

string

The product key being checked, from the ownership_products table

Returns:

  1. boolean true if all players own the product key, or if we're in autotest, otherwise false.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4377

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4407

campaign_manager:dis_to_log(number x, number y)
Converts a set of display co-ordinates into logical co-ordinates.

Parameters:

1

number

Display x co-ordinate.

2

number

Display y co-ordinate.

Returns:

  1. number Logical x co-ordinate.
  2. number Logical x co-ordinate.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4428

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4449

Back to top

Bonus Values

campaign_manager:get_characters_bonus_value(
  character character interface,
  string Scripted bonus value key
)

Returns the scripted bonus value a supplied character has of a supplied id.

Parameters:

1

character

character interface

2

string

from the scripted_bonus_value_ids database table.

Returns:

  1. number Bonus value amount.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4495

campaign_manager:get_regions_bonus_value(
  object region interface or region key,
  string Scripted bonus value key
)

Returns the scripted bonus value a supplied region object has of a supplied id. It may also be supplied a region key in place of a region object.

Parameters:

1

object

region interface or region key

2

string

from the scripted_bonus_value_ids database table.

Returns:

  1. number Bonus value amount.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4512

campaign_manager:get_provinces_bonus_value(
  object faction province interface,
  string Scripted bonus value key
)

Returns the scripted bonus value a supplied faction province object has of a supplied id.

Parameters:

1

object

faction province interface

2

string

from the scripted_bonus_value_ids database table.

Returns:

  1. number Bonus value amount.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4538

campaign_manager:get_factions_bonus_value(
  object faction interface or faction key,
  string Scripted bonus value key
)

Returns the scripted bonus value a supplied faction object has of a supplied id. It may also be supplied a faction key in place of a faction object.

Parameters:

1

object

faction interface or faction key

2

string

from the scripted_bonus_value_ids database table.

Returns:

  1. number Bonus value amount.

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

campaign_manager:get_forces_bonus_value(
  military_force military force interface,
  string Scripted bonus value key
)

Returns the scripted bonus value a supplied character has of a supplied id.

Parameters:

1

military_force

military force interface

2

string

from the scripted_bonus_value_ids database table.

Returns:

  1. number Bonus value amount.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4581

Back to top

Area Triggers

The functions in this section allow areas to be drawn on the campaign map which, when entered and exited by a character, will fire events.

campaign_manager:add_hex_area_trigger(
  string id,
  number x,
  number y,
  number radius,
  [string faction key],
  [string subculture key]
)
Creates a hex based area trigger at a given set of logical co-ordinates with a supplied radius. Faction and subculture filtering is optional. The area will trigger "AreaEntered" and "AreaExited" events when a character enters and exits the trigger.

Parameters:

1

string

The ID of the area trigger. Multiple area triggers with the same name will act as a single area trigger.

2

number

Logical x co-ordinate.

3

number

Logical y co-ordinate.

4

number

Radius of the area trigger (code supports a max of 20).

5

string

optional, default value=""

Optional filter for faction (events will only trigger if the character belongs to this faction).

6

string

optional, default value=""

Optional filter for subculture (events will only trigger if the character belongs to this subculture).

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4613

campaign_manager:remove_hex_area_trigger(string id)
Removes a previously added hex based area trigger with the specified ID.

Parameters:

1

string

The ID of the area trigger to remove.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4664

campaign_manager:add_interactable_campaign_marker(
  string id,
  string marker_info_key,
  number x,
  number y,
  number radius,
  [string faction key],
  [string subculture key]
)
Adds an interactable campaign marker (.bmd prefabs - as defined in the database) to the campaign map at a specified position. The marker comes with an attached hex area trigger. The area will trigger "AreaEntered" and "AreaExited" events when a character enters and exits the trigger.

Parameters:

1

string

The ID of the interactable campaign marker. Multiple area triggers with the same name will act as a single area trigger.

2

string

The key of the marker to use as defined in the campaign_interactable_marker_infos table of the database.

3

number

Logical x co-ordinate.

4

number

Logical y co-ordinate.

5

number

Radius of the area trigger (code supports a max of 20).

6

string

optional, default value=""

Optional filter for faction (events will only trigger if the character belongs to this faction).

7

string

optional, default value=""

Optional filter for subculture (events will only trigger if the character belongs to this subculture).

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4677

campaign_manager:remove_interactable_campaign_marker(string id)
Removes a previously added interactable campaign marker with the specified ID.

Parameters:

1

string

The ID of the interactable campaign marker to remove.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4733

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4757

campaign_manager:building_level_for_building(string building key)

Returns the building level for the supplied building key, as looked up from the building_levels database table (i.e. 0 is a "level one" building, 1 is a "level two" building and so on). If no building could be found then nil is returned.

Parameters:

1

string

Building key, from the building_levels database table.

Returns:

  1. number building level, from the building_levels database table.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4786

campaign_manager:building_chain_key_for_building(string building key)

Returns the building chain key for the supplied building key. If no building could be found then nil is returned.

Parameters:

1

string

Building key, from the building_levels database table.

Returns:

  1. string building chain key, from the building_chains database table.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4802

campaign_manager:building_superchain_key_for_building(string building key)

Returns the superchain key for the supplied building key. If no building could be found then nil is returned.

Parameters:

1

string

Building key, from the building_levels database table.

Returns:

  1. string superchain key, from the building_superchains database table.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4818

Back to top

Character Queries

campaign_manager:get_garrison_commander_of_region(region region object)
Returns the garrison commander character of the settlement in the supplied region. If no garrison commander can be found then nil is returned.

Parameters:

1

region

region object

Returns:

  1. character garrison commander

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4888

campaign_manager:get_closest_character_to_position_from_faction(
  object faction,
  number x,
  number y,
  [boolean general characters only],
  [boolean include garrison commanders],
  [boolean is display co-ordinates],
  [string visible to faction]
)

Returns the character within the supplied faction that's closest to the supplied logical co-ordinates. If the is-display-coordinates flag is set then the supplied co-ordinates should be display co-ordinates instead.

Parameters:

1

object

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

2

number

Logical x co-ordinate, or Display x co-ordinate if the is-display-coordinates flag is set.

3

number

Logical y co-ordinate, or Display y co-ordinate if the is-display-coordinates flag is set.

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.

6

boolean

optional, default value=false

Sets the function to use display co-ordinates instead of logical co-ordinates.

7

string

optional, default value=nil

Restricts search results to characters visible to the specified faction, by key from the factions database table.

Returns:

  1. character closest character
  2. number distance

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4920

campaign_manager:get_closest_character_from_filter_to_position_from_faction(
  object faction,
  number x,
  number y,
  [function filter],
  [boolean is display co-ordinates]
)

Returns the character within the supplied faction that's closest to the supplied logical co-ordinates. An optional filter function may be supplied which is called for each character in the faction - the function will be passed the character and should return true if the character is eligible to returned.
If the is-display-coordinates flag is set then the supplied co-ordinates should be display co-ordinates instead.

Parameters:

1

object

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

2

number

Logical x co-ordinate, or Display x co-ordinate if the is-display-coordinates flag is set.

3

number

Logical y co-ordinate, or Display y co-ordinate if the is-display-coordinates flag is set.

4

function

optional, default value=nil

Character filter callback. If supplied, this function will be called for each character in the faction and should return true if the character is to be considered in the results.

5

boolean

optional, default value=false

Sets the function to use display co-ordinates instead of logical co-ordinates.

Returns:

  1. character closest character
  2. number distance

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4952

campaign_manager:get_closest_general_to_position_from_faction(
  object faction,
  number x,
  number y,
  [boolean include garrison commanders],
  [boolean is display co-ordinates],
  [string visible to faction]
)

Returns the general within the supplied faction that's closest to the supplied co-ordinates. Logical co-ordinates should be supplied, unless the is-display-coordinates flag is set, in which case display co-ordinates should be provided.

Parameters:

1

object

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

2

number

x co-ordinate.

3

number

y co-ordinate.

4

boolean

optional, default value=false

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

5

boolean

optional, default value=false

Sets the function to use display co-ordinates instead of logical co-ordinates.

6

string

optional, default value=nil

Restricts search results to characters visible to the specified faction, by key from the factions database table.

Returns:

  1. character closest character
  2. number distance

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4973

campaign_manager:get_closest_character_to_camera_from_faction(
  object faction,
  [boolean general characters only],
  [boolean include garrison commanders],
  [string visible to faction]
)

Returns the character within the supplied faction that's closest to the camera. This function is inherently unsafe to use in multiplayer mode - in this case, the position of the specified faction's faction leader character is used as the position to test from.

Parameters:

1

object

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

2

boolean

optional, default value=false

Restrict search results to generals.

3

boolean

optional, default value=false

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

4

string

optional, default value=nil

Restricts search results to characters visible to the specified faction, by key from the factions database table.

Returns:

  1. character closest character, or nil if none found
  2. number distance, or nil if none found

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4988

campaign_manager:get_closest_character_from_filter_to_camera_from_faction(
  object faction,
  [function filter]
)

Returns the character within the supplied faction that's closest to the camera. An optional filter function may be supplied which is called for each character in the faction - the function will be passed the character and should return true if the character is eligible to returned.
This function is inherently unsafe to use in multiplayer mode - in this case, the position of the specified faction's faction leader character is used as the position to test from.

Parameters:

1

object

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

2

function

optional, default value=nil

Character filter callback. If supplied, this function will be called for each character in the faction and should return true if the character is to be considered in the results.

Returns:

  1. character closest character
  2. number distance

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5016

campaign_manager:get_closest_hero_to_position_from_faction(
  object faction,
  number x,
  number y,
  [boolean is display co-ordinates],
  [table character types],
  [table character subtypes]
)

Returns the hero character from the specified faction that's closest to the specified position. If no hero character is found then nil is returned. The position should be specified by logical co-ordinates unless the is-display-coordinates flag is set, in which case the position is specified by display co-ordinates.
Optional list of character types and subtypes can be provided as tables of strings. If these lists are specified then a character's type/subtype must be present in the relevant list for it to be considered.

Parameters:

1

object

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

2

number

x co-ordinate.

3

number

y co-ordinate.

4

boolean

optional, default value=false

Sets the function to use display co-ordinates instead of logical co-ordinates.

5

table

optional, default value=nil

Table of string hero types. If no table of character types is supplied then all hero types are eligible.

6

table

optional, default value=nil

Table of string hero subtypes. If no table of subtypes is supplied then all subtypes are eligible.

Returns:

  1. character closest eligible hero, or nil if none found
  2. number distance, or nil if none found

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5049

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5130

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5160

campaign_manager:get_family_member_by_cqi(number cqi)
Returns a family member by it's command queue index. If no family member with the supplied cqi is found then false is returned.

Parameters:

1

number

cqi

Returns:

  1. family_member family member

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5183

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5206

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5229

campaign_manager:get_character_by_fm_cqi(number family member cqi, character character)

Returns a character by family member command queue index. If no family member interface with the supplied cqi could be found then false is returned.
Returns the supplied character's full localised name as a string for output.

Parameters:

1

number

family member cqi

2

character

character

Returns:

  1. character character
  2. string character name

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5244

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5288

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5303

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5318

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5338

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5353

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5367

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5381

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5395

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5409

campaign_manager:char_can_recruit_unit(character character, string unit key)

Returns true if the supplied character can recruit the supplied unit key, false otherwise.

Parameters:

1

character

character

2

string

unit key

Returns:

  1. boolean is general

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5423

campaign_manager:char_army_has_unit(character character, string unit key or table of unit keys)

Returns true if the supplied character's army contains the supplied unit key (or table of unit keys), false otherwise.

Parameters:

1

character

character

2

string

unit key or table of unit keys

Returns:

  1. boolean contains unit

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5441

campaign_manager:count_char_army_has_unit(character character, string unit key or table of unit keys)

Returns the number of supplied unit keys (or table of unit keys) the character's army contains

Parameters:

1

character

character

2

string

unit key or table of unit keys

Returns:

  1. number number of units in army

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5477

campaign_manager:char_army_has_unit_category(
  character character,
  string unit category key or table of unit category keys
)

Returns true if the supplied character's army contains a unit with the supplied unit category (or table of unit categories), false otherwise.

Parameters:

1

character

character

2

string

unit category key or table of unit category keys

Returns:

  1. boolean contains unit with category

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5518

campaign_manager:count_char_army_has_unit_category(
  character character,
  string unit category key or table of unit category keys
)

Returns the number of units with the supplied unit category (or table of unit categories) the character's army contains

Parameters:

1

character

character

2

string

unit category key or table of unit category keys

Returns:

  1. number number of units of category in army

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5566

campaign_manager:general_has_caster_embedded_in_army(character character)
Returns true if the supplied character's army contains an embedded character that is a caster, false otherwise.

Parameters:

1

character

character

Returns:

  1. boolean contains caster

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5607

campaign_manager:character_won_battle_against_culture(
  character character,
  string culture or table of cultures
)

Returns true if the supplied character won their last battle against the key specified culture (or table of cultures), false otherwise.

Parameters:

1

character

character

2

string

culture or table of cultures

Returns:

  1. boolean character won against culture

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5630

campaign_manager:character_won_battle_against_unit(
  character character,
  string unit key or table of unit keys
)

Returns true if the supplied character won their last battle against an army containing the key specified unit key (or table of unit keys), false otherwise.

Parameters:

1

character

character

2

string

unit key or table of unit keys

Returns:

  1. boolean character won against unit key

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5677

campaign_manager:character_reinforced_alongside_culture(character character, string culture)

Returns true if the supplied character reinforced alongside the key specified culture in their last battle, false otherwise.

Parameters:

1

character

character

2

string

culture

Returns:

  1. boolean character reinforced alongside culture

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5718

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5785

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5799

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5813

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5827

campaign_manager:char_is_garrison_commander(character character)
Returns true if the supplied character is a general, has an army, and that army is armed citizenry (i.e. a garrison).

Parameters:

1

character

character

Returns:

  1. boolean is general with army

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5841

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5855

campaign_manager:char_is_general_with_embedded_agent(character character)
Returns true if the supplied character is a general with a military force that contains at least one embedded agent, false otherwise.

Parameters:

1

character

character

Returns:

  1. boolean is general with embedded agent

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5869

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5892

campaign_manager:get_all_agent_types()
Retuns a numerically-indexed table containing all agent types. Please copy this table instead of writing to it.

Returns:

  1. table agent types

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5909

campaign_manager:get_all_agent_types_lookup()
Retuns a table containing all agent types as keys (the value of each record being true). Please copy this table instead of writing to it.

Returns:

  1. table agent types

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5917

campaign_manager:get_closest_visible_character_of_culture(
  string faction key,
  string subculture key,
  [function filter]
)

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

Parameters:

1

string

Faction key, from the factions database table.

2

string

Culture key, from the cultures database table.

3

function

optional, default value=nil

Filter function. If supplied, this filter function will be called for each potentially-eligible character, with the character being passed in as a single argument. The character will only be considered eligible if the filter function returns true.

Returns:

  1. character closest visible character

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5925

campaign_manager:get_closest_visible_character_of_subculture(
  string faction key,
  string subculture key,
  [function filter]
)

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, from the factions database table.

2

string

Subculture key, from the cultures_subcultures database table.

3

function

optional, default value=nil

Filter function. If supplied, this filter function will be called for each potentially-eligible character, with the character being passed in as a single argument. The character will only be considered eligible if the filter function returns true.

Returns:

  1. character closest visible character

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5983

campaign_manager:get_closest_character_from_faction(faction faction, number x, number y)
Returns the closest character from the supplied faction to the supplied logical position. This includes characters such as politicians and garrison commanders that are not extant on the map.

Parameters:

1

faction

Faction script interface.

2

number

Logical x position.

3

number

Logical y position.

Returns:

  1. character closest character
  2. number closest character distance

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6041

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6068

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6088

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6108

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6134

campaign_manager:get_most_recently_created_character_of_type(
  string faction key,
  [string type],
  [string subtype]
)

Returns the most recently-created character of a specified type and/or subtype for a given faction. This function makes the assumption that the character with the highest command-queue-index value is the most recently-created.

Parameters:

1

string

Faction specifier supply either a string faction key, from the factions database table, or a faction script interface.

2

string

optional, default value=nil

Character type. If no type is specified then all character types match.

3

string

optional, default value=nil

Character subtype. If no subtype is specified then all character subtypes match.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6176

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 and the military force cqi.

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, force_cqi)
        out("Force created with char cqi:" .. cqi .. " force cqi:" .. force_cqi);
    end
);

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6225

campaign_manager:create_force_with_full_diplomatic_discovery(
  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_with_full_diplomatic_discovery 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_with_full_diplomatic_discovery(
    "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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6327

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],
  [boolean force diplomatic discovery]
)
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.

14

boolean

optional, default value=false

forces the created faction to have diplomatic discovery - set to true if you expect the faction to automatically declare war on factions it meets once spawned.

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6429

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6584

campaign_manager:create_agent(
  string faction key,
  string character type,
  string character subtype,
  number x,
  number y,
  [boolean disable_auto_select]
)
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.

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

boolean

optional, default value=false

if set to true it will prevent the game automatically selecting the agent on creation.

Returns:

  1. character interface Returns newly-created character if successful, false if not.

Example:

cm:create_agent(
    "wh_main_dwf_dwarfs",
    "wh_main_the_silver_road_karaz_a_karak",
    714,
    353
);

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6718

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

Kills the specified character, with the ability to also destroy their whole force if they are commanding one. The character may be specified by a lookup string or by character cqi.

Parameters:

1

string

Character string of character to kill. This uses the standard character string lookup system. Alternatively, a number may be supplied, which specifies a character cqi.

2

boolean

optional, default value=false

Will also destroy the characters whole force if true.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6803

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6848

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6886

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6971

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7069

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7226

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7237

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7291

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7301

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7349

campaign_manager:notify_on_character_movement(string process name, number cqi, function callback)

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

Parameters:

1

string

name for this movement monitor, by which it can be cancelled later with campaign_manager:stop_notify_on_character_movement. It is valid to have multiple notification processes with the same name.

2

number

Command-queue-index of the subject character.

3

function

Callback to call.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7357

campaign_manager:stop_notify_on_character_movement(string process name)

Stops any monitor started by campaign_manager:notify_on_character_movement, by process name.

Parameters:

1

string

process name

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7436

campaign_manager:attack(
  string attacker,
  string defender,
  [boolean lay siege],
  [boolean ignore shroud restrictions]
)

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

optional, default value=false

Should the force lay siege.

4

boolean

optional, default value=true

Should the attack command ignore shroud restrictions. If this is set to false, the attacker must be able to see the target for the attack to commence.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7455

campaign_manager:teleport_to(string character string, number x, number y)
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.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7471

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7499

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7514

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7529

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7544

campaign_manager:force_add_trait(
  string character string,
  string trait key,
  [boolean show message],
  [number points]
)
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.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7559

campaign_manager:add_skill(
  character character,
  string skill key,
  bool ignore_requirements ignore requirements like the need to unlock other skills first.,
  bool ignore_skill_points ignore skill points
)
Adds a skill to a character. This wraps the cm: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

character

Character script interface.

2

string

Skill key to add.

3

bool

ignore_requirements ignore requirements like the need to unlock other skills first.

4

bool

don't decrease the amount which means adding the skill even if the character doesn't have skill points.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7587

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7607

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7622

campaign_manager:grant_units_to_character_by_position_from_faction(
  string faction key,
  number x,
  number y,
  ... units
)

Grants one or more units, specified by string key(s), to a military force by character lookup. The military force is specified by its faction key and logical co-ordinates.

Parameters:

1

string

Faction key.

2

number

Logical x co-ordinate.

3

number

Logical y co-ordinate.

4

...

Units to add, specified by one or more string variables.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7651

Back to top

New Character Entered Recruitment Pool Listener

Game scripts can listen for a new character entering a recruitment pool using the NewCharacterEnteredRecruitmentPool. However, it is often useful for game scripts to know about characters entering a recruitment pool during campaign startup, which is before they are loaded.

The campaign manager now establishes a listener for the NewCharacterEnteredRecruitmentPool event during startup. For any events of this type received during startup, the character details are cached. When the game starts ticking, the system then triggers a ScriptEventNewCharacterEnteredRecruitmentPool event, with the character details available using a character_details method provided by the context.

If a NewCharacterEnteredRecruitmentPool event is received after startup, the campaign manager just retriggers a ScriptEventNewCharacterEnteredRecruitmentPool event with the same character details. The net result is that client game scripts can set up listeners for ScriptEventNewCharacterEnteredRecruitmentPool in place of NewCharacterEnteredRecruitmentPool, and get notifications for recruitment pool events that happened even before the client game scripts were loaded.

Back to top

Faction Queries & Modification

campaign_manager:get_faction(string faction key, [boolean error if not found])

Gets a faction object by its string key. If no faction with the supplied key could be found then false is returned.
If a faction object is supplied then it is returned directly. This functionality is provided to allow other library functions to be flexible enough to accept a faction or faction key from client code, and use get_faction to convert that faction-or-faction-key into a faction object.

Parameters:

1

string

Faction key, from the factions database table. Alternatively a faction object may be supplied.

2

boolean

optional, default value=false

Generate an error if the faction specifier was a string but no faction with a corresponding key could be found.

Returns:

  1. faction faction

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7834

campaign_manager:faction_contains_building(faction faction interface, 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 interface

2

string

building key

Returns:

  1. faction contains building

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7866

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

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

Parameters:

1

faction

faction interface

2

string

character type

Returns:

  1. number number of characters

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7891

campaign_manager:kill_all_armies_for_faction(faction faction interface)

Kills all armies in the supplied faction.

Parameters:

1

faction

faction interface

Returns:

  1. number number of armies killed

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7919

campaign_manager:get_trespasser_list_for_faction(faction faction interface)

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 interface

Returns:

  1. table of character command queue indexes

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7952

campaign_manager:number_of_units_in_faction(
  faction faction interface,
  [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 interface

2

boolean

optional, default value=false

exclude armed citizenry

Returns:

  1. number number of units

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7994

campaign_manager:faction_has_full_military_force(faction faction interface)

Returns true if the supplied faction has a military force with 20 units in it, or false otherwise. Armed citizenry/garrison armies are excluded from this check.

Parameters:

1

faction

faction interface

Returns:

  1. boolean has full military force

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8020

campaign_manager:faction_is_alive(faction faction interface)

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 interface

Returns:

  1. boolean faction is alive

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8041

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8055

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8081

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8107

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8139

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8161

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8187

campaign_manager:num_regions_controlled_in_province_by_faction(province province, faction faction)

Returns the number of regions controlled by a specified faction in a supplied province.

Parameters:

1

province

Province to query.

2

faction

Faction to query.

Returns:

  1. number number of controlled regions
  2. number total number of regions

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8213

campaign_manager:num_provinces_controlled_by_faction(faction faction)

Returns the number of complete provinces controlled by the specified faction, as well as the number of provinces in which the faction owns territory and is only one settlement away from complete control.

Parameters:

1

faction

Faction to query.

Returns:

  1. number number of provinces controlled
  2. number number of provinces almost controlled (one settlement away from completion)

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8233

campaign_manager:faction_contains_agents(faction faction, [boolean return list], [boolean return by cqi])

Returns true if the supplied faction has any agents in its character list, or false otherwise. The function may also be instructed to return a table of all agents in the faction, either by their character interfaces or their command-queue indexes.

Parameters:

1

faction

Faction interface for the subject faction.

2

boolean

optional, default value=false

Instructs the function to also return a table of either their character interfaces or cqi's (which of these to use is set by the third parameter to this function).

3

boolean

optional, default value=false

Instructs the function to return a list of cqis instead of a list of character interfaces. If characters are stored by cqi their character interfaces may later be looked up using campaign_manager:get_character_by_cqi. Character interfaces are volatile and may not be stored over time. This argument is not used if the second argument is not set to true.

Returns:

  1. boolean faction has agents
  2. table list of agents, by either cqi or character interface, or nil if the second argument is not set to true.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8271

campaign_manager:faction_contains_characters_of_type(faction faction)

Returns true if the supplied faction has any agents of the supplied types or subtypes.

Parameters:

1

faction

Interface for the subject faction.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8310

campaign_manager:can_recruit_agent(faction faction, table types)

Returns whether a specified faction can recruit agents, optionally of a type.

Parameters:

1

faction

faction

2

table

Table of string agent types, from the agents database table.

Returns:

  1. boolean can recruit agent

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8355

campaign_manager:faction_can_reach_faction(
  faction source faction specifier,
  faction target faction specifier,
  [boolean include armies]
)

Returns whether any army in a source faction can reach any settlement in a target faction this turn. An optional flag also includes whether the can-reach test should be performed against the target faction's roving armies.

Parameters:

1

faction

Source faction specifier - this can be a faction script interface object, or a string faction key from the factions database table.

2

faction

Target faction specifier - this can be a faction script interface object, or a string faction key from the factions database table.

3

boolean

optional, default value=false

Include the movable armies of the target faction in the can-reach test.

Returns:

  1. boolean source can reach target
  2. character character from source faction that can reach, or nil if no character can reach
  3. character character from target faction that can be reached, or nil if no character can be reached

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8385

campaign_manager:get_highest_level_settlement_for_faction(faction faction)
Returns the highest-level settlement for the specified faction. If the faction has no settlements then nil is returned.

Parameters:

1

faction

faction

Returns:

  1. settlement highest-level settlement
  2. number settlement level

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8432

Back to top

Foreign Slots

campaign_manager:get_closest_foreign_slot_manager_from_faction_to_faction(
  faction owning faction,
  faction foreign faction
)

Returns the closest foreign slot manager belonging to one faction, to the settlements from another faction. The two factions may be the same, in which case the closest foreign slot manager to the faction's own settlements is returned.

Parameters:

1

faction

Owning faction specifier. This can be a faction interface or a string faction key from the factions database table.

2

faction

Foreign faction specifier. This can be a faction object or a string faction key from the factions database table.

Returns:

  1. foreign_slot_manager foreign slot

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8481

campaign_manager:is_foreign_slot_manager_allied(foreign_slot_manager foreign slot manager)

Returns whether the supplied foreign slot manager is allied to the settlement that it's a part of.

Parameters:

1

foreign_slot_manager

foreign slot manager

Returns:

  1. boolean slot is allied

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8519

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8554

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8582

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8610

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8638

Back to top

Military Force Queries

campaign_manager:get_strongest_military_force_from_faction(
  string faction key,
  [boolean include garrisons]
)

Returns the strongest military force from the specified faction. Nil is returned if the faction contains no military forces.

Parameters:

1

string

Faction key, from the factions table.

2

boolean

optional, default value=false

Include garrision armies.

Returns:

  1. military_force strongest military force

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8689

campaign_manager:get_closest_military_force_from_faction(
  string faction key,
  number x,
  number y,
  [boolean include garrisons]
)

Returns the closest military force from the specified faction to a specified logical position. Nil is returned if the faction contains no military forces.

Parameters:

1

string

Faction key, from the factions table.

2

number

Logical x co-ordinate.

3

number

Logical y co-ordinate.

4

boolean

optional, default value=false

Include garrison armies from the subject faction.

Returns:

  1. military_force closest military force
  2. number closest military force distance

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8751

campaign_manager:get_closest_military_force_from_faction_to_faction(
  string subject faction key,
  string foreign faction key,
  [boolean include garrisons]
)

Returns the closest military force from the specified subject faction to a foreign faction. Nil is returned if either faction contains no military forces.

Parameters:

1

string

Subject faction key, from the factions table.

2

string

Foreign faction key, from the factions table.

3

boolean

optional, default value=false

Include garrison armies from the subject faction.

Returns:

  1. military force closest military force

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8786

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8842

campaign_manager:num_mobile_forces_in_force_list(
  military_force_list military force list,
  [table not_including_armies_of_type]
)

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

2

table

optional, default value=nil

Set of army-type keys that will not be counted by this function.

Returns:

  1. number number of mobile forces

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8869

campaign_manager:get_mobile_force_interface_list(
  military_force_list, military force list,
  [table not_including_armies_of_type]
)

Returns a one-based list of military force interfaces in the provided list which are not armed-citizenry.

Parameters:

1

military_force_list,

military force list

2

table

optional, default value=nil

Set of army-type keys that will not be counted by this function.

Returns:

  1. table One-based list of military force interfaces which are not armed-citizenry. Empty list is returned if none are found.

Example:

Getting the mobile forces within a military force list, excluding CARAVAN and OGRE_CAMP
cm:num_mobile_forces_in_force_list(military_force_list, {
CARAVAN = true,
OGRE_CAMP = true,
});

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8886

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8918

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8953

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8979

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9004

campaign_manager:force_gold_value(number or military_force force cqi or force interface)

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

Parameters:

1

number

or military_force force cqi or force interface

Returns:

  1. number value

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

Back to top

Region and Province Queries & Modification

campaign_manager:get_region(string or region region name or interface)

Returns a region object with the supplied region name, or if a region interface was provided simply returns that. If no such region is found then false is returned.

Parameters:

1

string

or region region name or interface

Returns:

  1. region region

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9064

campaign_manager:get_region_data_at_position(number x, number y)

Returns the region_data found at the provided x and y coordinates.

Parameters:

1

number

x

2

number

y

Returns:

  1. region_data region data

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9087

campaign_manager:get_province_at_position(number x, number y)

Returns the province ofthe region found at the provided x and y coordinates.

Parameters:

1

number

x

2

number

y

Returns:

  1. province province

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9106

campaign_manager:get_region_data(string region data name)
Returns a region data object with the supplied region name. If no such region data is found then false is returned.

Parameters:

1

string

region data name

Returns:

  1. region_data region data

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9128

campaign_manager:get_province(string or province province name or interface)

Returns a province object with the supplied province name, or if a province interface is provided then simply returns that instead. If no such province is found then false is returned.

Parameters:

1

string

or province province name or interface

Returns:

  1. province province

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9148

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

Returns whether the region with the supplied key is owned by a faction with the supplied name.

Parameters:

1

string

Region name, from the campaign_map_regions database table.

2

string

Faction name, from the factions database table.

Returns:

  1. boolean region is owned by faction

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9171

campaign_manager:get_owner_of_province(province province)

Returns the faction that has complete control of the supplied province. If no faction holds the entire province, then nil is returned.

Parameters:

1

province

province

Returns:

  1. faction province owner, or nil if province is contested

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9198

campaign_manager:region_adjacent_to_faction(region region, faction region)
Returns whether the supplied region object is adjacent to regions owned by the supplied faction. If the region is owned by the faction then false is returned.

Parameters:

1

region

region

2

faction

region

Returns:

  1. boolean region adjacent to faction

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

campaign_manager:region_has_chain_or_superchain(
  region region,
  string building chain or building superchain key
)

Returns whether the supplied region contains the key specified building chain or superchain

Parameters:

1

region

region

2

string

building chain or building superchain key

Returns:

  1. boolean region has chain or superchain

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9260

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

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

Parameters:

1

slot

slot

2

string

target building key

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9287

campaign_manager:instantly_dismantle_building_in_region(slot slot)

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

Parameters:

1

slot

slot

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9301

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9309

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9341

campaign_manager:get_province_capital_for_region(region region)
Returns the region designated as the province capital, for the supplied region's province.

Parameters:

1

region

region

Returns:

  1. region province capital region

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9374

campaign_manager:get_closest_region_for_faction(
  faction faction,
  [number x],
  [number y],
  [function condition]
)

Returns the region controlled by the specified faction that is closest to a supplied set of logical co-ordinates. If no co-ordinates are supplied then the logical position of the camera is used.
An optional condition function may be supplied which each region must pass in order to be considered eligible in the result. If supplied, this condition function will be called for each region and will be supplied that region object as a single argument. The function should return a value that evaluates to a boolean to determine the result of the condition test.
If the specified faction controls no regions, or none pass the condition, then nil will be returned.

Parameters:

1

faction

Faction object.

2

number

optional, default value=nil

Logical x co-ordinate.

3

number

optional, default value=nil

Logical y co-ordinate.

4

function

optional, default value=nil

Conditional test.

Returns:

  1. region closest eligible region

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9393

campaign_manager:get_regions_adjacent_to_faction(faction faction specifier, [return regions as keys])
Returns an indexed table of all regions or region keys adjacent to those regions held by the supplied faction. The faction may be specified by string faction key or as a faction interface.
If an optional condition function is supplied then it is called for each region with the region supplied as a single argument. In this case, the condition function must return true for the region to be included in the results.

Parameters:

1

faction

Faction specifier - this can be a faction script interface object, or a string faction key from the factions database table.

2

return

optional, default value=false

Populate the returned table with region keys, rather than region interfaces.

Returns:

  1. table table of all adjacent regions

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9447

campaign_manager:get_corruption_value_in_province(
  object province or province key,
  string corruption pooled resource key
)
Returns the value of the key specified corruption in the specified province object. It may also be supplied a province key in place of a province object.

Parameters:

1

object

province or province key

2

string

corruption pooled resource key

Returns:

  1. number corruption value

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9500

campaign_manager:get_corruption_value_in_region(
  object region or region key,
  string corruption pooled resource key
)
Returns the value of the key specified corruption in the specified region object. It may also be supplied a region key in place of a region object.

Parameters:

1

object

region or region key

2

string

corruption pooled resource key

Returns:

  1. number corruption value

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9536

campaign_manager:get_highest_corruption_in_region(object region, [table corruption types to check])

Returns the key and value of the highest value corruption in the specified region object. The region may be specified by string key or supplied as a region script interface object.
A list of specific corruption types to consider can optionally be specified, otherwise all corruption types are considered.
False is returned if no corruption is present.

Parameters:

1

object

Region script interface or string region key.

2

table

optional, default value=DEFAULT_VALUE

Should be numerically indexed list. If unspecified, will use the default table of all corruption types.

Returns:

  1. string corruption pooled resource key
  2. string and number The key of the highest corruption in the region, and the value of that corruption.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9572

campaign_manager:get_total_corruption_value_in_region(object region or region key)
Returns the total value of all corruption types in the specified region object. It may also be supplied a region key in place of a region object.

Parameters:

1

object

region or region key

Returns:

  1. number total corruption value

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9625

campaign_manager:change_corruption_in_province_by(
  province or string province,
  string or nil corruption_type,
  number value,
  [string factor]
)

Applies the specified value (may be positive or negative) to the province's pooled resource manager. The corruption type must be an entry in the campaign manager corruption_types list. Non-corruption pooled resources are not accepted.

Parameters:

1

province

The province interface or province key

2

string

The key of the corruption pooled resource. If nil, will be interpreted as uncorrupted and all other corruptions will be reduced by the value (or increased, if the value is negative).

3

number

The positive or negative value to add to the regiuon's corruption

4

string

optional, default value=nil

The factor to adjust the corruption with.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9690

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9775

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9785

campaign_manager:get_closest_settlement_from_faction_to_faction(
  object subject faction,
  object foreign faction
)
Returns the closest settlement from the specified subject faction to a foreign faction. The function returns the region of the closest settlement, although nil is returned if the source faction contains no settlements or the target faction no military forces.

Parameters:

1

object

Subject faction specifier. This can be a faction object or a string faction key from the factions database table.

2

object

Foreign faction specifier. This can be a faction object or a string faction key from the factions database table.

Returns:

  1. region region containing closest settlement

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9795

campaign_manager:get_closest_settlement_from_table_to_faction(table region keys, object foreign faction)

Returns the closest settlement from the specified table of region keys to a foreign faction. The function returns the region of the closest settlement, although nil is returned if no closest region could be found.

Parameters:

1

table

Table of region keys, each a key from the campaign_map_regions database table.

2

object

Foreign faction specifier. This can be a faction object or a string faction key from the factions database table.

Returns:

  1. region region containing closest settlement
  2. number distance of closest settlement, or nil if none could be found

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9844

campaign_manager:get_closest_settlement_from_faction_to_position(
  object subject faction,
  number x,
  number y,
  [boolean use display co-ordinates]
)

Returns the closest settlement from the specified subject faction to a specified position. The function returns the region of the closest settlement, although nil is returned if the source faction contains no settlements.
By default the supplied co-ordinates should specify a logical position to test against. If the use-display-coordinates flag is set, then the supplied co-ordinates should be a display position.

Parameters:

1

object

Subject faction specifier. This can be a faction object or a string faction key from the factions database table.

2

number

x co-ordinate. This should be a logical co-ordinate by default, or a display co-ordinate if the use-display-coordinates flag is set.

3

number

y co-ordinate. This should be a logical co-ordinate by default, or a display co-ordinate if the use-display-coordinates flag is set.

4

boolean

optional, default value=false

Sets the function to accept display co-ordinates rather than logical co-ordinates.

Returns:

  1. region region containing closest settlement
  2. number distance, or nil if no region is returned

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9888

campaign_manager:get_closest_settlement_from_faction_to_camera(object subject faction)
Returns the closest settlement from the specified subject faction to the camera. The function returns the region of the closest settlement, although nil is returned if the source faction contains no settlements.
If this function is called in multiplayer mode the capital of the specified faction is returned, as testing the camera position in inherently unsafe in multiplayer.

Parameters:

1

object

Subject faction specifier. This can be a faction object or a string faction key from the factions database table.

Returns:

  1. region region containing closest settlement

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9937

Back to top

Pre and Post-Battle Events

The campaign manager automatically monitors battles 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 in singleplayer mode only. The pending battle may be accessed on the context of each with context:pending_battle():

EventTrigger Condition
ScriptEventPreBattlePanelOpenedThe pre-battle panel has opened on the local machine.
ScriptEventPreBattlePanelOpenedAmbushPlayerDefenderThe pre-battle panel has opened on the local machine and the player is the defender in an ambush.
ScriptEventPreBattlePanelOpenedAmbushPlayerAttackerThe pre-battle panel has opened on the local machine and the player is the attacker in an ambush.
ScriptEventPreBattlePanelOpenedMinorSettlementThe pre-battle panel has opened on the local machine and the battle is at a minor settlement.
ScriptEventPreBattlePanelOpenedProvinceCapitalThe pre-battle panel has opened on the local machine and the battle is at a province capital.
ScriptEventPreBattlePanelOpenedFieldThe pre-battle panel has opened on the local machine and the battle is a field battle.
ScriptEventPlayerBattleStartedTriggered when the local player initiates a battle from the pre-battle screen, either by clicking the attack or autoresolve button.

The campaign manager fires the following events post-battle events in singleplayer and multiplayer modes.

EventTrigger Condition
ScriptEventBattleSequenceCompletedThis event is triggered when any battle sequence is completed, whether a battle was fought or not.
ScriptEventPlayerBattleSequenceCompletedThis event is triggered after a battle sequence involving a human player has been completed and the camera has returned to its normal completion, whether a battle was fought or not.

It also fires the following events post-battle in singleplayer and multiplayer modes, for battle victories/defeats involving a human player. If multiple human players are involved in a single battle, then an event is generated for each. The pending battle and the involved human faction can be accessed on the context of each with context:pending_battle() and context:faction() respectively:

EventTrigger Condition
ScriptEventHumanWinsBattleA human player has won a battle.
ScriptEventHumanWinsFieldBattleA human player has won a field battle. A "field" battle is a non-settlement battle, although it would include a battle where a settlement defender sallied against the besieging player.
ScriptEventHumanWinsSettlementDefenceBattleA human player has won a settlement defence battle as the defender (including a battle where the player sallied).
ScriptEventHumanWinsSettlementAttackBattleA human player has won a settlement defence battle as the attacker. They should have captured the settlement if this event has been received.
ScriptEventHumanLosesSettlementDefenceBattleA human player has lost a settlement defence battle as the defender.
ScriptEventHumanLosesSettlementAttackBattleA human player has lost a settlement defence battle as the attacker.
ScriptEventHumanLosesFieldBattleA human player has lost a field (non-settlement) battle.

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 provided by the pending_battle interface to querying the forces that fought in a battle is through the character interface (of the respective army commanders). If those commanders died in battle then these interfaces 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10682

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.
To get records of the units related to an attacker, use campaign_manager:pending_battle_cache_num_attacker_units and campaign_manager:pending_battle_cache_get_attacker_unit.

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10690

campaign_manager:pending_battle_cache_get_attacker_embedded_character_subtypes(
  number index of attacker
)

Returns the agent subtypes of all embedded characrers in a particular attacker's army 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. table agent subtype keys

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10714

campaign_manager:pending_battle_cache_get_attacker_fm_cqi(number index of attacker)

Returns the family member cqi 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. number family member cqi

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10728

campaign_manager:pending_battle_cache_get_attacker_units(number index of attacker)

Returns just a table containing the unit keys 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. table unit keys

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10742

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10756

campaign_manager:pending_battle_cache_get_attacker_subtype(number index of attacker)

Returns just the subtype key 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10770

campaign_manager:pending_battle_cache_num_attacker_units([number index of attacker])

Returns the number of units that a specified attacker in the cached pending battle took into battle, or will take into battle. The total number of units across all attacking armies is returned if no army index is specified.

Parameters:

1

number

optional, default value=nil

index of attacker

Returns:

  1. number number of attacking units

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10786

campaign_manager:pending_battle_cache_num_attacker_embedded_characters([number index of attacker])

Returns the number of embedded characters that a specified attacker in the cached pending battle took into battle, or will take into battle. The total number of embedded characters across all attacking armies is returned if no army index is specified.

Parameters:

1

number

optional, default value=nil

index of attacker

Returns:

  1. number number of attacking embedded characters

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10804

campaign_manager:pending_battle_cache_get_attacker_unit(number attacker index, number unit unit)

Returns the cqi and unit key of a specified unit on the specified attacker in the pending battle cache, by index.

Parameters:

1

number

Index of attacking character within the pending battle cache.

2

number

Index of unit belonging to the attacking character.

Returns:

  1. number cqi of unit
  2. string key of unit

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10828

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10853

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10861

campaign_manager:pending_battle_cache_get_defender_embedded_character_subtypes(
  number index of defender
)

Returns the agent subtypes of all embedded characrers in a particular defender's army 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. table agent subtype keys

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10884

campaign_manager:pending_battle_cache_get_defender_fm_cqi(number index of defender)

Returns the family member cqi 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. number family member cqi

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10898

campaign_manager:pending_battle_cache_get_defender_units(number index of defender)

Returns just a table containing the unit keys 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. table unit keys

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10912

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10926

campaign_manager:pending_battle_cache_get_defender_subtype(number index of defender)

Returns just the subtype key 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10940

campaign_manager:pending_battle_cache_num_defender_units([number index of defender])

Returns the number of units that a specified defender in the cached pending battle took into battle, or will take into battle. The total number of units across all defending armies is returned if no army index is specified.

Parameters:

1

number

optional, default value=nil

index of defender

Returns:

  1. number number of defending units

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10956

campaign_manager:pending_battle_cache_num_defender_embedded_characters([number index of defender])

Returns the number of embedded characters that a specified defender in the cached pending battle took into battle, or will take into battle. The total number of embedded characters across all defending armies is returned if no army index is specified.

Parameters:

1

number

optional, default value=nil

index of defender

Returns:

  1. number number of defending embedded characters

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10974

campaign_manager:pending_battle_cache_get_defender_unit(number defender index, number unit unit)

Returns the cqi and unit key of a specified unit on the specified defender in the pending battle cache, by index.

Parameters:

1

number

Index of attacking character within the pending battle cache.

2

number

Index of unit belonging to the attacking character.

Returns:

  1. number cqi of unit
  2. string key of unit

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10998

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11023

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11045

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11067

campaign_manager:pending_battle_cache_faction_set_member_is_attacker(string faction set key)

Returns true if a faction that is part of the specified faction set was an attacker (primary or reinforcing) in the cached pending battle.

Parameters:

1

string

faction set key

Returns:

  1. boolean faction was set member attacker

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11076

campaign_manager:pending_battle_cache_faction_set_member_is_defender(string faction set key)

Returns true if a faction that is part of the specified faction set was a defender (primary or reinforcing) in the cached pending battle.

Parameters:

1

string

faction set key

Returns:

  1. boolean faction set member was defender

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11100

campaign_manager:pending_battle_cache_faction_set_member_is_involved(string faction set key)

Returns true if a member of the specified faction set was involved in the cached pending battle as either attacker or defender.

Parameters:

1

string

faction set key

Returns:

  1. boolean faction set member was involved

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11123

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11132

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11150

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11168

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11176

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11200

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11224

campaign_manager:pending_battle_cache_human_culture_is_involved()
Returns true if any of the factions involved in the cached pending battle on either side were human controlled and belonging to the supplied culture (whether local or not).

Returns:

  1. boolean human culture was involved

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11233

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11241

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11265

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11289

campaign_manager:pending_battle_cache_char_is_involved(object character)
Returns true if the supplied character fought 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11298

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11307

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11316

campaign_manager:pending_battle_cache_fm_is_involved(object family member)
Returns true if the supplied family member fought in the cached pending battle.

Parameters:

1

object

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

Returns:

  1. boolean family member was involved

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11325

campaign_manager:pending_battle_cache_fm_is_attacker(object family member)
Returns true if the supplied family member was an attacker in the cached pending battle.

Parameters:

1

object

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

Returns:

  1. boolean family member was attacker

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11334

campaign_manager:pending_battle_cache_fm_is_defender(object family member)
Returns true if the supplied family member was a defender in the cached pending battle.

Parameters:

1

object

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

Returns:

  1. boolean family member was defender

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11343

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11387

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11415

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11443

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11461

campaign_manager:pending_battle_cache_get_enemy_fms_of_char_fm(family_member family member to query)
Returns a numerically indexed table of family member objects, each representing an enemy character of the supplied family member in the cached pending battle. If the supplied family member was not present in the pending battle then the returned table will be empty.

Parameters:

1

family_member

family member to query

Returns:

  1. table table of enemy family members

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11487

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11513

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11535

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11543

campaign_manager:pending_battle_cache_human_victory()
Returns true if the pending battle has been won by a human player, false otherwise.

Returns:

  1. boolean human has won

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11551

campaign_manager:pending_battle_cache_faction_won_battle(string faction key)

Returns true if the pending battle has been won by the specified faction key, false otherwise.

Parameters:

1

string

faction key

Returns:

  1. boolean faction has won

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11559

campaign_manager:pending_battle_cache_faction_lost_battle(string faction key)

Returns true if the pending battle has been lost by the specified faction key, false otherwise.

Parameters:

1

string

faction key

Returns:

  1. boolean faction has lost

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11568

campaign_manager:pending_battle_cache_faction_won_battle_against_culture(
  string faction key,
  string culture key
)

Returns true if the pending battle has been won by the specified faction key against the specified culture, false otherwise. A table of culture keys may be supplied instead of a single culture key.

Parameters:

1

string

faction key

2

string

culture key

Returns:

  1. boolean faction has won

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11577

campaign_manager:pending_battle_cache_faction_won_battle_against_unit(
  string faction key,
  string unit key or table of unit keys
)

Returns true if the pending battle has been won by the specified faction key against an army containing the key specified unit, false otherwise. A table of unit keys may be supplied instead of a single unit key.

Parameters:

1

string

faction key

2

string

unit key or table of unit keys

Returns:

  1. boolean faction has won against unit key

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11597

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11633

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11644

campaign_manager:pending_battle_cache_unit_key_exists_in_attackers(string unit key)
Returns true if the supplied unit key was involved in the cached pending battle as attacker.

Parameters:

1

string

unit key

Returns:

  1. boolean unit was involved as attacker

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11655

campaign_manager:pending_battle_cache_unit_key_exists_in_defenders(string unit key)
Returns true if the supplied unit key was involved in the cached pending battle as defender.

Parameters:

1

string

unit key

Returns:

  1. boolean unit was involved as defender

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11679

campaign_manager:pending_battle_cache_unit_key_exists(string unit key)
Returns true if the unit was involved in the cached pending battle as attacker or defender.

Parameters:

1

string

unit key

Returns:

  1. boolean unit was involved

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11703

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11728

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11765

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11794

campaign_manager:shuffle_table(table table)

Randomly shuffles a table with an implementation of the Fisher-Yates shuffle.
Note that, unlike the random_sort and random_sort_copy functions, this modifies the existing table and doesn't destroy the original or create a new table.

Parameters:

1

table

table

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11817

Back to top

Campaign UI

campaign_manager:is_cinematic_ui_enabled()
Returns whether the cinematic UI is currently enabled. The cinematic UI is enabled from script with CampaignUI.ToggleCinematicBorders, and is commonly activated/deactivated by cutscenes.

Returns:

  1. boolean is cinematic ui enabled

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11845

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

Returns:

  1. campaign_ui_manager

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11854

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11865

campaign_manager:quit()
Immediately exits to the frontend. Mainly used in benchmark scripts.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11897

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11914

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11929

campaign_manager:register_instant_movie(string movie path)

Plays a fullscreen movie, by path from the data/Movies directory. This function wraps the underlying cm:register_instant_movie to play the movie and provide output.

Parameters:

1

string

movie path

Returns:

  1. nil

Example:

-- play the movie file data/Movies/Warhammer/chs_rises
cm:register_instant_movie("Warhammer/chs_rises")

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11937

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12012

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12042

campaign_manager:scroll_camera_to_region(string faction_key, string region_key, string time)
Scrolls the camera from the current camera position. This hooks into scroll_camera_from_current, and respects the player's current height/rotation

Parameters:

1

string

which faction to pan the camera for. This is to make sure we're not panning the camera for all players in mp

2

string

the region the camera should pan to.

3

string

Time in seconds over which to scroll.

Returns:

  1. nil

Example:

cm:scroll_camera_to_region(
    "wh_main_emp_empire",
    "wh3_main_combi_region_altdorf",
    5
)

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12078

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12115

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12152

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12215

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12249

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12281

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12394

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12439

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12477

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12501

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12521

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12539

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12565

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12604

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12635

campaign_manager:hide_subtitles()
Hides any subtitles currently displayed with campaign_manager:show_subtitle.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12699

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12740

campaign_manager:skip_all_campaign_cutscenes()
Skips any campaign cutscene currently running.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12759

campaign_manager:steal_escape_key_on_event(
  boolean should steal,
  string event,
  [function condition],
  [number delay],
  [string listener name]
)

Steals or un-steals the escape key if the supplied script event is received, optionally with the specified condition. This function calls cm:steal_escape_key.

Parameters:

1

boolean

Should steal the escape key or not.

2

string

Event to listen for.

3

function

optional, default value=true

Event condition that must return true for the key steal action to take place.

4

number

optional, default value=0

Delay in seconds before key is stolen. Will sometimes need a slight delay after an event.

5

string

optional, default value="steal_escape_key_on_event"

Optional name for the listener.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12768

campaign_manager:steal_user_input_on_event(
  boolean should steal,
  string event,
  [function condition],
  [number delay],
  [string listener name]
)

Steals or un-steals user input if the supplied script event is received, optionally with the specified condition. This function calls cm:steal_user_input().

Parameters:

1

boolean

Should steal user input or not.

2

string

Event to listen for.

3

function

optional, default value=true

Event condition that must return true for the user input action to take place.

4

number

optional, default value=0

Delay in seconds before user input is stolen. Will sometimes need a slight delay after an event.

5

string

optional, default value="steal_user_input_on_event"

Optional name for the listener.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12796

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12834

campaign_manager:print_key_steal_entries()
Debug output of all current stolen key records.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12851

campaign_manager:steal_key_with_callback(
  string name,
  string key,
  function callback,
  [boolean is persistent]
)

Steal a key, and register a callback to be called when it's pressed. It will be un-stolen when this occurs. cm:steal_user_input will need to be called separately for this mechanism to work, unless it's the escape key that being stolen, where cm: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.

4

boolean

optional, default value=false

Key should remain stolen after callback is first called.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12869

campaign_manager:release_key_with_callback(string name, string key)
Releases a key stolen with campaign_manager:steal_key_with_callback, by unique name.

Parameters:

1

string

Unique name for this key-steal entry.

2

string

Key name.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12915

campaign_manager:steal_escape_key_with_callback(string name, function callback, [boolean is persistent])

Steals the escape key and registers a function to call when it is pressed. Unlike campaign_manager:steal_key_with_callback this automatically calls cm: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.

3

boolean

optional, default value=false

Key should remain stolen after callback is first called.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12945

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12958

campaign_manager:steal_escape_key_and_space_bar_with_callback(
  string name,
  function callback,
  [boolean is persistent]
)

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.

3

boolean

optional, default value=false

Keys should remain stolen after callback is first called.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12972

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12984

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 no 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13009

campaign_manager:set_next_advice_location(number x position, number y position)

Sets an x/y display location for the next triggered advice. Once that advice has triggered this position will be cleared, meaning further advice will trigger without a location unless this function is called again.

Parameters:

1

number

X display position.

2

number

Y display position.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13094

campaign_manager:set_advice_debug([boolean enable debug output])

Enables or disables verbose debug output for the advice system. This can be useful as the advice system is difficult to debug using traditional means.

Parameters:

1

boolean

optional, default value=true

enable debug output

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13113

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13125

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13145

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13153

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13189

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13202

campaign_manager:progress_on_advice_dismissed(
  string name,
  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

string

Process name, by which this progress listener may be later cancelled if necessary.

2

function

Callback to call.

3

number

optional, default value=0

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

4

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13226

campaign_manager:cancel_progress_on_advice_dismissed(string name)

Cancels any running campaign_manager:progress_on_advice_dismissed process.

Parameters:

1

string

Name of the progress on advice dismissed process to cancel.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13333

campaign_manager:progress_on_advice_finished(
  string name,
  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

string

Name for this progress on advice finished process, by which it may be later cancelled if necessary.

2

function

Callback to call.

3

number

optional, default value=0

Delay in seconds after the advisor finishes to wait before calling the callback.

4

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.

5

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13350

campaign_manager:cancel_progress_on_advice_finished(string name)

Cancels any running campaign_manager:progress_on_advice_finished process.

Parameters:

1

string

Name of the progress on advice finished process to cancel.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13504

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13535

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13591

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13602

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13612

campaign_manager:progress_on_blocking_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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13620

campaign_manager:cancel_progress_on_blocking_panel_dismissed(function callback, [number callback delay])
Cancels any running monitor started with campaign_manager:progress_on_blocking_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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13649

campaign_manager:start_intro_cutscene_on_loading_screen_dismissed(
  function callback,
  string faction_key,
  [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

string

which faction to start the intro cutscene for. This is to make sure we're not turning on cinematic borders for all players in mp

3

number

optional, default value=0

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13659

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. This mechanism should now work in multiplayer.

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13746

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13784

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13798

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13850

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13857

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13885

Back to top

Progress on UI Trigger

campaign_manager:progress_on_all_clients_ui_triggered(string name, function callback)

This function uses CampaignUI.TriggerCampaignScriptEvent to trigger a UI event over the network which all clients receive. Once the event has been received from all clients then the progress callback is called. This can be used to progress the script in a synchronous manner in a multiplayer game only once an inherently-asynchronous event has been received. For example, a cutscene shown on multiple machines at once could be skipped on one machine and not another - progress_on_all_clients_ui_triggered can be used in this situation to only progress on all machines onces the cutscene has finished on all machines.
The listening process associated with this function begins when the script is started, so it will pick up relevant events generated by progress_on_all_clients_ui_triggered() calls on remote machines even before progress_on_all_clients_ui_triggered() is called on this machine.

Parameters:

1

string

Name for this process by which it may optionally be cancelled.

2

function

Progression callback.

Returns:

  1. nil

Example:

-- play a cutscene in multiplayer and proceed when it's finished on all clients

local cutscene_name = "example_cutscene"
local c = campaign_cutscene:new_from_cindyscene(
    cutscene_name,                                    -- name for cutscene
    "path/to/cindy_scene.CindySceneManager,            -- cindyscene
    function()                                        -- end callback
        cm:progress_on_ui_trigger(
            cutscene_name,
            function()
                out("Cutscene has finished on all clients, progressing...")
            end
        )
    end
)

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13971

Back to top

Multiplayer Queries

The function campaign_manager:progress_on_mp_query can be used to query information that is only available to the script on one machine, and have the result of that sent across the network to all machines.

campaign_manager:progress_on_mp_query(
  string query command,
  string faction key,
  [table query data],
  function callback
)

Calls the supplied callback when the result of a multiplayer query is received from the network. Multiplayer queries allow the scripts on all machines in a multiplayer game to query information that normally on the script on one machine would have access to, such as advice history or the state of the UI.
With each multiplayer query a faction key and some optional query data is specified. The query is run on the machine where the local player's faction matches the faction specified with the query. The results of the query are then broadcast with CampaignUI.TriggerCampaignScriptEvent for all machines in the multiplayer game to receive.
A number of multiplayer queries are supported:

CommandDescription
all_advice_strings_seenReturns true if all the specified advice strings have been seen on the machine where the local player's faction matches the faction specified with the query. The query data should be a table containing a list of advice strings. The result of the query will be a boolean value.
any_advice_strings_seenReturns true if any of the specified advice strings have been seen on the machine where the local player's faction matches the faction specified with the query. The query data should be a table containing a list of advice strings. The result of the query will be a boolean value.
get_open_blocking_panelReturns the result of calling campaign_ui_manager:get_open_blocking_panel on the machine where the local player's faction matches the faction specified with the query. No query data is specified with this query. The result of the query will be a string panel name, or false if no panel is open.
When the query is completed, the function will be called on all machines with the result of the query supplied as a single argument.

Parameters:

1

string

Query command to run. See documentation above for a supported list of query commands.

2

string

Faction key, from the factions database table. The query is run on the machine where the local player's faction matches this key.

3

table

optional, default value=nil

Data required to perform the query. This can be in different forms for different queries, but is often a table.

4

function

Callback that is called when the query is completed. The result of the query will be passed to the callback as a single argument.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14101

Back to top

Debug Drawing

campaign_manager:draw_text(
  string text,
  number x,
  number y,
  number z,
  number duration,
  [number r],
  [number g],
  [number b],
  [number a]
)
Draws debug text in the 3D space.

Parameters:

1

string

Text to write.

2

number

Display x co-ordinate.

3

number

Display y co-ordinate.

4

number

Display z co-ordinate (height).

5

number

Duration in seconds to display the text on screen for.

6

number

optional, default value=255

Red value (0-255).

7

number

optional, default value=255

Green value (0-255).

8

number

optional, default value=255

Blue value (0-255).

9

number

optional, default value=255

Alpha value (0-255).

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14211

campaign_manager:draw_2d_text(
  string text,
  number x,
  number y,
  number duration,
  [number r],
  [number g],
  [number b],
  [number a]
)
Draws debug text to the screen, in 2D.

Parameters:

1

string

Text to write.

2

number

x pixel position.

3

number

y pixel position.

4

number

Duration in seconds to display the text on screen for.

5

number

optional, default value=255

Red value (0-255).

6

number

optional, default value=255

Green value (0-255).

7

number

optional, default value=255

Blue value (0-255).

8

number

optional, default value=255

Alpha value (0-255).

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14264

campaign_manager:draw_line(
  number x_start_pos,
  number y_start_pos,
  number z_start_pos,
  number x_end_pos,
  number y_end_pos,
  number z_end_pos,
  number duration,
  [number r],
  [number g],
  [number b],
  [number a]
)
Draws a debug line in the 3D space.

Parameters:

1

number

Start point display x co-ordinate.

2

number

Start point display y co-ordinate.

3

number

Start point display z co-ordinate (height).

4

number

End point display x co-ordinate.

5

number

End point display y co-ordinate.

6

number

End point display z co-ordinate (height).

7

number

Duration in seconds to display the text on screen for.

8

number

optional, default value=255

Red value (0-255).

9

number

optional, default value=255

Green value (0-255).

10

number

optional, default value=255

Blue value (0-255).

11

number

optional, default value=255

Alpha value (0-255).

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14310

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14389

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14427

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14467

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14522

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14554

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14575

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14607

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14628

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14660

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14681

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14713

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14746

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"

  • "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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14810

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14908

campaign_manager:force_declare_war(
  string faction key,
  string faction key,
  boolean invite faction a allies,
  boolean invite faction b allies
)
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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14922

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

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.
This function passes its arguments through objectives_manager:set_objective on the objectives manager - see the documentation on that function for more information.

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15145

campaign_manager:set_objective_with_leader(
  string objective key,
  [number param a],
  [number param b],
  [function callback]
)

Sets up a scripted objective for the player which appears in the scripted objectives panel, with a topic_leader. 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.
This function passes its arguments through objectives_manager:set_objective_with_leader on the objectives manager - see the documentation on that function for more information.

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.

4

function

optional, default value=nil

Optional callback to call when the objective is shown.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15157

campaign_manager:complete_objective(string objective key)

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. This function passes its arguments through objectives_manager:complete_objective on the objectives manager - see the documentation on that function for more information.
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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15170

campaign_manager:fail_objective(string objective key)

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. This function passes its arguments through objectives_manager:fail_objective on the objectives manager - see the documentation on that function for more information.

Parameters:

1

string

Objective key, from the scripted_objectives table.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15179

campaign_manager:remove_objective(string objective key)

Removes a scripted objective from the scripted objectives panel. This function passes its arguments through objectives_manager:remove_objective on the objectives manager - see the documentation on that function for more information.

Parameters:

1

string

Objective key, from the scripted_objectives table.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15187

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15195

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

Starts a new objective chain, with a topic_leader. This function passes its arguments through objectives_manager:activate_objective_chain_with_leader on the objectives manager - see the documentation on that function for more information.

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15206

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

Updates an existing objective chain. This function passes its arguments through objectives_manager:update_objective_chain on the objectives manager - see the documentation on that function for more information.

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 battle_manager:set_objective for more details

4

number

optional, default value=nil

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15217

campaign_manager:end_objective_chain(string chain name)

Ends an existing objective chain. This function passes its arguments through objectives_manager:end_objective_chain on the objectives manager - see the documentation on that function for more information.

Parameters:

1

string

Objective chain name.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15228

campaign_manager:reset_objective_chain(string chain name)

Resets an objective chain so that it may be called again. This function passes its arguments through objectives_manager:reset_objective_chain on the objectives manager - see the documentation on that function for more information.

Parameters:

1

string

Objective chain name.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15236

campaign_manager:add_infotext(object first param, ... additional infotext strings)
Adds one or more lines of infotext to the infotext panel. This function passes through to infotext_manager:add_infotext - 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15244

campaign_manager:add_infotext_with_leader(object first param, ... additional infotext strings)
Adds one or more lines of infotext to the infotext panel, with a topic_leader. This function passes through to infotext_manager:add_infotext_with_leader - 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15253

campaign_manager:add_infotext_simultaneously(object first param, ... additional infotext strings)
Adds one or more lines of infotext simultaneously to the infotext panel. This function passes through to infotext_manager:add_infotext_simultaneously - 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_simultaneously fades each of them on to the infotext panel in a visually-pleasing sequence.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15262

campaign_manager:add_infotext_simultaneously_with_leader(
  object first param,
  ... additional infotext strings
)
Adds one or more lines of infotext simultaneously to the infotext panel, with a topic_leader. This function passes through to infotext_manager:add_infotext_simultaneously_with_leader - 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_simultaneously fades each of them on to the infotext panel in a visually-pleasing sequence.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15271

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15280

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15288

Back to top

Missions and Events

campaign_manager:trigger_custom_mission(
  string faction key,
  string mission key,
  [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

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.

4

boolean

optional, default value=true

Supply false here to not whitelist the mission event type, so that it does not display 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15309

campaign_manager:trigger_custom_mission_from_string(
  string faction key,
  string mission,
  [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=true

Supply false here to not whitelist the mission event type, so that it does not display 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15336

campaign_manager:trigger_mission(
  string faction key,
  string mission key,
  [boolean fire immediately],
  [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=true

Supply false here to not whitelist the mission event type, so that it does not display 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15353

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15383

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15470

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,
  [boolean trigger callback immediately]
)

Triggers a dilemma with a specified key and one or more target game objects, preferentially wrapped in an intervention.
If calling from within an intervention, force_dilemma_immediately can be specified as true to prevent a nested intervention call. If in multiplayer, the dilemma will never be wrapped in an intervention.
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.

10

boolean

optional, default value=false

If true, will not wrap the dilemma in an intervention. If false, will only wrap the dilemma in an intervention if in singleplayer.

Returns:

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

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15501

campaign_manager:trigger_dilemma_with_targets_and_family_member(
  number faction cqi,
  string dilemma key,
  [number target faction cqi],
  [number secondary faction cqi],
  [number family member cqi],
  [number military force cqi],
  [number region cqi],
  [number settlement cqi],
  function trigger callback,
  [boolean trigger callback immediately]
)

Triggers a dilemma with a specified key and one or more target game objects, including a family member CQI instead of a character CQI (since this should remain constant between character deaths and revivals), preferentially wrapped in an intervention.
If calling from within an intervention, force_dilemma_immediately can be specified as true to prevent a nested intervention call. If in multiplayer, the dilemma will never be wrapped in an intervention.
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's family member interface.

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.

10

boolean

optional, default value=false

If true, will not wrap the dilemma in an intervention. If false, will only wrap the dilemma in an intervention if in singleplayer.

Returns:

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

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15525

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 family member cqi],
  [number military force cqi],
  [number region cqi],
  [number settlement cqi],
  function trigger callback,
  boolean whitelist
)

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 trigger_dilemma_with_targets_internal.
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.
Some parameters are mutually exclusive: for example, either character_cqi or family_member_cqi may be specified, but not both.

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

7

number

optional, default value=0

Command-queue index of a target military force.

8

number

optional, default value=0

Command-queue index of a target region.

9

number

optional, default value=0

Command-queue index of a target settlement.

10

function

Callback to call when the intervention actually gets triggered.

11

boolean

Allows the dilemma to bypass event supression.

Returns:

  1. boolean Dilemma triggered successfully
  2. string Any errors found with the dilemma's targets, if applicable. Otherwise an empty string.

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15651

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15825

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15936

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15969

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. Event categories are listed in the event_feed_categories database table. Additionally, supply "" or false/nil to not suppress by category in this function call. Supply "all" to disable all event types.

3

string

optional, default value=""

Event subcategories to disable. Event subcategories are listed in the event_feed_subcategories database table. Supply "" or false/nil to not suppress by subcategory in this function call.

4

string

optional, default value=""

Event to disable, from the event_feed_events database table. Supply "" or false/nil to not supress by events in this function call.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15982

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 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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16005

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16102

Back to top

Achievements

campaign_manager:award_achievement(string achievement key)

Awards an achievement by string key. This function calls the equivalent function on the episodic scripting interface, adding output and argument-checking.

Parameters:

1

string

Achievement key, from the achievements database table.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16204

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],
  [number intervention priority]
)

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.

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.

5

number

optional, default value=0

Priority value of the intervention.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16228

Back to top

Turn Countdown Events/Messages

The turn countdown event/message system allows client scripts to register a string script event or script message with the campaign manager. The campaign manager will then trigger the event or message at the start of turn for a given faction (or the start of a round if no faction was specified), 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/message to occur a number of turns in the future.

campaign_manager:add_turn_countdown_event(
  string faction key,
  number turns,
  string event,
  [string context string]
)

Registers a turn countdown event. The supplied script event will be triggered after the specified number of turns has passed, when the FactionTurnStart event is received for the specified faction.

Parameters:

1

string

Key of the faction on whose turn start the event will be triggered.

2

number

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16296

campaign_manager:add_round_turn_countdown_event(number turns, string event, [string context string])

Registers a turn countdown event related to a round, rather than a faction. The supplied script event will be triggered after the specified number of turns has passed, when the WorldStartRound event is received.

Parameters:

1

number

Number of turns from now to trigger the event.

2

string

Event to trigger. By convention, script event names begin with "ScriptEvent"

3

string

optional, default value=""

Optional context string to trigger with the event.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16317

campaign_manager:add_turn_countdown_event_on_event(
  [string trigger event],
  [function condition],
  string faction key,
  number turns,
  string event,
  [string context string]
)

Registers a turn countdown event with campaign_manager:add_turn_countdown_event when the supplied trigger event is received by script. Note that while the turn countdown event is saved into the savegame when triggered, the trigger event listener is not, so it will need to be re-established on script load.

Parameters:

1

string

optional, default value=nil

Trigger event. When this event is received by script, the turn countdown event will be registered. If this is nil or a blank string then the turn countdown event is registered immediately.

2

function

optional, default value=nil

Condition that must be met when the trigger event is received, for the turn countdown event to be registered. If the value specified is true then no conditional check is performed and the turn countdown event will be registered as soon as the trigger event is received.

3

string

Key of the faction on whose turn start the event will be triggered.

4

number

Number of turns from now to trigger the event.

5

string

Event to trigger. By convention, script event names begin with "ScriptEvent"

6

string

optional, default value=""

Optional context string to trigger with the event.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16327

campaign_manager:add_absolute_turn_countdown_event(
  [string faction key],
  number turns,
  string event,
  [string context string]
)

Registers a turn coutdown event to trigger on a specified absolute turn. The supplied script event will be triggered when the faction specified starts the supplied turn. If no faction is specified, the script event is triggered when the round starts for the supplied turn.

Parameters:

1

string

optional, default value=nil

Key of the faction on whose turn start the event will be triggered, from the factions database table. If no faction key is specified the event will be triggered when the round starts.

2

number

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16352

campaign_manager:report_turns_until_countdown_event(
  [string faction key],
  [string event name],
  [string context string]
)

Reports the number of turns until the next turn countdown event matching the supplied criteria will trigger.
If a faction key is specified then turn countdown events related to that faction are considered, otherwise turn countdown events related to the start of round are considered.
Any combination of script event name and context string must be supplied. Both may be specified, neither, or just one. If more than one matching turn countdown event is found then information about the next one to trigger will be returned. If no matching turn countdown event is found then nil is returned.

Parameters:

1

string

optional, default value=nil

Faction key, from the factions database table. If no faction key is supplied then countdown events related to the start of round are considered.

2

string

optional, default value=nil

Script event name to filter by.

3

string

optional, default value=nil

Context string to filter by.

Returns:

  1. number Number of turns until this turn countdown event is triggered
  2. number The absolute turn on which this turn countdown event is triggered
  3. string Script event that the turn countdown event will trigger
  4. string Context string that the turn countdown event will supply

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16503

campaign_manager:add_turn_countdown_message(
  string faction key,
  number turns,
  string message,
  [string context string],
  [boolean is narrative message]
)

Registers a turn countdown script message. The supplied script message will be triggered after the specified number of turns has passed, when the FactionTurnStart event is received for the specified faction.
See the script_messager documentation for more information about script messages.

Parameters:

1

string

Key of the faction on whose turn start the event will be triggered, from the factions database table.

2

number

Number of turns from now to trigger the event.

3

string

Message to trigger.

4

string

optional, default value=""

Optional context string to trigger with the event.

5

boolean

optional, default value=false

Sets this message to be a narrative message. If this is set then the context string is actually a faction key, and will be exposed on the context supplied when the message is triggered in the way that the narrative system expects.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16642

campaign_manager:add_absolute_turn_countdown_message(
  string faction key,
  number turns,
  string event,
  [string context string],
  [boolean is narrative message]
)

Registers a turn coutdown message to trigger on a specified absolute turn. The supplied script message will be triggered when the faction specified starts the supplied turn.
See the script_messager documentation for more information about script messages.

Parameters:

1

string

Key of the faction on whose turn start the event will be triggered.

2

number

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.

5

boolean

optional, default value=false

Sets this message to be a narrative message. If this is set then the context string is actually a faction key, and will be exposed on the context supplied when the message is triggered in the way that the narrative system expects.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16665

Back to top

Context Queries

Campaign wrappers for UI context queries, which can allow us to get access to information not otherwise available from script

campaign_manager:faction_has_campaign_feature(string faction key)
Uses the context system to check if a faction has access to the specified campaign feature
Valid feature keys can be found in the campaign_features database table

Parameters:

1

string

faction key

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16841

campaign_manager:faction_has_faction_feature(string faction key)
Uses the context system to check if a faction has access to the specified faction feature
Valid feature keys can be found in the faction_features database table

Parameters:

1

string

faction key

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16871

Back to top

Custom Battlefields

These functions add, remove or clear custom battlefield records, which allow game scripts to override parts or all of the next battle to be fought. Custom battlefield records are saved in to the savegame, as the game code requires that records which modify the autoresolver result must remain active even after the campaign has loaded back in after battle. This can make managing the lifetime of custom battlefield records problematic.

To assist with this management, the campaign manager will defer calls to campaign_manager:add_custom_battlefield, campaign_manager:remove_custom_battlefield and campaign_manager:clear_custom_battlefields if a pending battle is active, and we are in the phase after the battle has been fought. It would not be valid to apply custom battle modifications at this time as they may tamper with the results of the battle just fought. Instead, they are deferred until that battle is completed, allowing the modifications to apply for subsequent battles.

campaign_manager:add_custom_battlefield(
  string id,
  number x,
  number y,
  number radius,
  boolean dump campaign,
  string loading screen override,
  string script override,
  string whole battle override,
  number human alliance,
  boolean launch immediately,
  boolean is land battle,
  boolean force autoresolve result
)

Adds a record which modifies or completely overrides a fought or autoresolved battle, if that battle happens within a certain supplied radius of a supplied campaign anchor position. Aspects of the battle may be specified, such as the loading screen and script to use, or the entire battle may be subsituted with an xml battle.
If a pending battle sequence is already active, and the battle has been fought, then this call is deferred until after the battle is completed to avoid tampering with the running battle.

Parameters:

1

string

Id for this custom battle record. This may be used to later remove this override with cm:remove_custom_battlefield.

2

number

X logical co-ordinate of anchor position.

3

number

Y logical co-ordinate of anchor position.

4

number

Radius around anchor position. If a battle is launched within this radius of the anchor position and it involves the local player, then the battle is modified/overridden.

5

boolean

If set to true, the battle makes no attempt to load back into this campaign after completion.

6

string

Key of a custom loading screen to use, from the custom_loading_screens table. A blank string may be supplied to not override the loading screen. This is ignored if the entire battle is overriden with a battle xml, as that may specify a loading screen override.

7

string

Path to a script file to load with the battle, from the working data folder. A blank string may be supplied to not override the loading screen. This is ignored if the entire battle is overriden with a battle xml, as that may specify a script override.

8

string

Path to an battle xml file which overrides the whole battle.

9

number

Sets the index of the human alliance, 0 or 1, if setting a battle xml to override the whole battle. If not setting a battle xml this number is ignored.

10

boolean

Launch the battle immediately without saving the campaign first.

11

boolean

Sets whether the following battle is a land battle. This is only required if when launching the battle immediately.

12

boolean

If set to true, this forces the application of the autoresolver to the battle result after the battle, regardless of what happened in the battle itself. This is of most use for faking a battle result of an xml battle, which would otherwise return with no result.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16931

campaign_manager:remove_custom_battlefield(string id)

Removes a custom battle override previously set with cm:add_custom_battlefield.
If a pending battle sequence is already active, and the battle has been fought, then this call is deferred until after the battle is completed to avoid tampering with the running battle.

Parameters:

1

string

id

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16955

campaign_manager:clear_custom_battlefields()
Removes all custom battle overrides previously set with cm:add_custom_battlefield.
If a pending battle sequence is already active, and the battle has been fought, then this call is deferred until after the battle is completed to avoid tampering with the running battle.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16968

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:

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.
primary_attacker_is_femalebooleanWhether the primary attacker has a female lord.
primary_defender_is_femalebooleanWhether the primary defender has a female lord.

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 17125

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 17169

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 17398

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 17444

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 ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 17478

Back to top

Benchmark Scripts

campaign_manager:show_benchmark_if_required(
  function non-benchmark callback,
  [string cindy file],
  [number cam x],
  [number cam y],
  [number cam d],
  [number cam b],
  [number cam h],
  [number benchmark duration]
)

Shows a benchmark constructed from supplied parameters if benchmarking mode is active, otherwise calls a supplied callback which should continue the campaign as normal. The intention is for this to be called on or around the first tick, at a critical early point within the benchmark faction's script (each campaign benchmark being associated with a certain faction). If benchmark mode is currently set, this function plays the supplied cindy scene then quits the campaign. If benchmark mode is not set then the supplied callback is called - this should cause the campaign to continue as normal.
An initial position for the camera prior to the cindy scene starting may be set with a set of five numerical arguments specifying camera co-ordinates. All five arguments must be supplied for the camera position to be used.
A duration for the cindy scene may optionally be set. If a duration is not set then the

Parameters:

1

function

Function to call if this campaign has not been loaded in benchmarking mode.

2

string

optional, default value=nil

Cindy file to show for the benchmark.

3

number

optional, default value=nil

Start x position of camera.

4

number

optional, default value=nil

Start y position of camera.

5

number

optional, default value=nil

Start distance of camera.

6

number

optional, default value=nil

Start bearing of camera (in radians).

7

number

optional, default value=nil

Start height of camera.

8

number

optional, default value=nil

Benchmark duration in seconds.

Returns:

  1. nil

Example:

cm:add_first_tick_callback_sp_new(
    function()
        cm:start_intro_cutscene_on_loading_screen_dismissed(
            function()
                -- Either show benchmark and exit, or continue with campaign load as normal
                cm:show_benchmark_if_required(
                    function() cutscene_intro_play() end,
                    "script/benchmarks/scenes/campaign_benchmark.CindyScene",
                    348.7,
                    330.9,
                    10,
                    0,
                    10,
                    92.83
                );
            end
        );
    end
);

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 17546

Back to top

Serialised Army State

The functions in this section allow scripts to save or apply a serialised state from the scriptedvalueregistry, across campaign and battle. This allows battle script to apply health values to units that were set in campaign, or vice-versa. This is chiefly useful for scripted battles that are launched from campaign but are logically actually nothing to do with that campaign, such as a tutorial battle xml loaded from a campaign as if it was a campaign-generated battle. Using this functionality the battle scripts would be able to spoof the approximate health of the army as if it were coming from campaign, and then pass it back to campaign on battle completion.

Campaign scripts can use campaign_manager:save_army_state_to_svr and campaign_manager:load_army_state_from_svr to save and load army states, and in battle script_units:save_state_to_svr and script_units:load_state_from_svr can be used to do the same.

Note that at present this only serialises the health state of units and not their experience, items carried etc.

campaign_manager:serialise_army_state(number mf cqi)

Returns a string which represents the serialised state of the military force specified by the supplied military force cqi. This does not embody the full model state of the units but only selected information. It is mainly intended for use by campaign_manager:save_army_state_to_svr which will save the returned string into the scriptedvalueregistry.

Parameters:

1

number

mf cqi

Returns:

  1. string serialised state

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 17702

campaign_manager:save_army_state_to_svr(number mf cqi, string name)

Saves a string which represents the serialised state of the military force specified by the supplied military force cqi to the scriptedvalueregistry. campaign_manager:serialise_army_state is used to generate the state string, and core:svr_save_string is used to save the string. This string can then be loaded by script_units:load_state_from_svr, allowing scripted battles loaded from a campaign, but not logically related to that campaign (e.g. an xml battle) to spoof the starting state of a battle army to be approximately the same as it was in the campaign.

Parameters:

1

number

mf cqi

2

string

Name for this svr entry, to be passed to core:svr_save_string.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 17736

campaign_manager:load_army_state_from_svr(string name, number mf cqi, [boolean allow partial])

Checks for a scriptedvalueregistry string with the supplied name, and attempts to apply the health values it contains to the units in the military force specified by the supplied cqi. These svr strings would be set by either campaign_manager:save_army_state_to_svr in campaign or script_units:save_state_to_svr in battle.
This is primarily intended to spoof casualties on a campaign army that is coming back from battle, but where the army in battle is not logically related to the army in campaign (such as when loading back from a scripted xml battle).
The function returns whether the application was successful. A successful application is one that modifies all units in the military force (a "modification" from 100% health to 100% health would count), unless the allow_partial flag is set, in which case even a partial application would be considered successful. If the application is not successful then no changes are applied. Output is generated in all cases.

Parameters:

1

string

Name of string saved in the scriptedvalueregistry.

2

number

CQI of military force to apply state to.

3

boolean

optional, default value=false

Allow a partial application of the state string. If this is set to true

Returns:

  1. boolean state was applied successfully

defined in ../../warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 17752

Last updated 7/9/2024 11:45:04 AM