Campaign Manager

The campaign manager is the main interface object in the campaign scripting environment. It provides a number of features and quality-of-life improvements in its own right, and also wraps the game interface that the campaign model provides to script. Any calls made to the campaign manager that the campaign manager doesn't provide itself are passed through to this game interface.

The underlying game interface (the episodic scripting interface) is documented separately, in an html file that is generated when a campaign is run. It may be viewed here. If this link is dead, start a campaign and try again.

Some of the features and quality-of-life improvements that the campaign manager offers:

  • Support functions for saving and loading persistent values to and from the savegame.

  • Registering functions to be called when game creation events occur (new/existing game, single/multiplayer).

  • Stores information about the game for easy retrieval, such as the key of the local player faction.

  • Functions to scroll the camera.

  • Registering timer callbacks to call functions in the future.

  • Showing advice.

  • Faction turn start events.

  • Helper functions for moving and creating armies and agents.

  • Random number generation.

  • Triggering events a number of turns in the future.

  • Validation/output wrappers for a variety of game interface functions.

    • And more!

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

    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 197

    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 561

    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 575

    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 598

    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 606

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

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 620

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

    Parameters:

    1

    string

    script name

    2

    boolean

    optional, default value=false

    single player only

    Returns:

    1. nil

    Example - Loading faction script:

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

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

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 645

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

    Parameters:

    1

    string

    script name appellation

    Returns:

    1. 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 706

    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 763

    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 893

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

    Parameters:

    1

    string

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

    2

    object

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

    3

    userdata

    Context object supplied by the LoadingGame event.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 1021

    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 1095

    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 1105

    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 1382

    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 1395

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

    Parameters:

    1

    string

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

    2

    object

    Value to save.

    3

    userdata

    Context object supplied by the SavingGame event.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 1480

    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 1572

    campaign_manager:save(
      [    string filename],
      [function     callback],
      [boolean     lock afterwards],
      [boolean     suppress callback on failure]
    )

    Instructs the campaign game to save, either with a supplied filename or, if no filename is supplied, as an autosave at the next opportunity. An optional completion callback may be supplied.
    The function returns whether the save operation succeeded. This return value is always true if no filename was supplied to the function, as the underlying function cm:autosave_at_next_opportunity is used for saving and this will succeed eventually. When a filename is supplied the underlying function cm:save_game is used to make a single attempt to save the game. This can fail if the game is not in the correct state at the time the save is attempted.

    Parameters:

    1

    string

    optional, default value=nil

    Filename to save as. If nil or a blank string is supplied then the game will be autosaved.

    2

    function

    optional, default value=nil

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

    3

    boolean

    optional, default value=nil

    Lock saving functionality after saving is completed. If true is supplied here then the saving is disabled, if false is supplied then saving is enabled. If nil is supplied, then the restriction on saving is restored to what it was prior to this function being called.

    4

    boolean

    optional, default value=false

    Don't call the supplied completion callback if the save operation fails. Save operations can fail if a filename is supplied (so autosaving is not used, which would wait for an opportunity to save) and the game is not in a position to save at this time. By default, the completion callback is called if the operation fails.

    Returns:

    1. boolean save operation succeeded

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 1694

    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 1872

    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 1885

    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 1898

    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 1911

    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 1924

    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 1937

    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 1950

    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 2153

    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 2164

    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 2172

    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 2183

    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 2191

    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 2202

    Back to top

    Output

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

    Parameters:

    1

    function

    callback

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2223

    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 2512

    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 2563

    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 2574

    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 2588

    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 2597

    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 2608

    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 2619

    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 2647

    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 individual 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 2715

    Back to top

    Linear Sequence Checkpoints

    Within a linear sequence of gameplay, such as a tutorial campaign, it's common to want to allow the game to be saved (either manually by the player, or automatically by script) and reloaded. Such gameplay sequences are often tightly scripted, and to be able to rebuild the script from a savegame in the correct state and allow it to seamlessly resume is not always trivial.

    The linear sequence checkpoint functions aim to provide a toolset to help solve this problem. They grant support for scripts to add, pass through and reload from checkpoints, which should be sequentially encountered as the script progresses.

    • Checkpoints may be declared with campaign_manager:add_checkpoint. Checkpoints are re-entry points, from which the script may start after loading from a savegame (or a new game). Each checkpoint is set up with a callback that is called if that checkpoint is reloaded in to, which should resume the game from that point.

    • As well as a callback, each checkpoint is also associated with a numeric id value. As the script progresses through the linear sequence/tutorial and passes through successive checkpoints, the numeric id associated with each checkpoint should increase. It would be illegal for the script to reach a checkpoint with id 100 on turn two and to then reach a checkpoint with id 50 on turn three, for example.

    • To opt-in to the checkpoint system, the function campaign_manager:start_from_checkpoint can be called somewhere on the first tick. This calls the callback associated with the last checkpoint reached. If no checkpoints have been marked as reached yet, then the callback associated with the checkpoint with the lowest numeric id is called.

    • As the script progresses through the tutorial/linear sequence, it can mark that a checkpoint has been reached with the campaign_manager:checkpoint_reached function. By default, the game gets automatically saved when this happens.

    • Zero or more setup functions may also also be associated with a checkpoint with the campaign_manager:add_checkpoint_setup_callback function. If the game is reloaded in to a checkpoint, then any setup functions associated with it and all previously-reached checkpoints are called in sequence. This is different to the main checkpoint functions set up with campaign_manager:add_checkpoint, of which exactly one will be called when campaign_manager:start_from_checkpoint is invoked.

    • Calls to campaign_manager:add_checkpoint and campaign_manager:add_checkpoint_setup_callback should be made in the root of the script, or in some other place that ensures that checkpoint data is all set up correctly before campaign_manager:start_from_checkpoint is called.

    • campaign_manager:get_current_checkpoint can be called which returns the id of the most recently reached checkpoint.

    Example:

    cm:add_first_tick_callback(
        function()
        -- Start from a checkpoint when the first tick occurs. If no checkpoint has been reached
        -- in the savegame, the callback of the checkpoint with the lowest ID is called.
        cm:start_from_checkpoint()
    end
    );

    -- START CHECKPOINT 1 DECLARATION --
    cm:add_checkpoint(
        1,
        function(is_loading_game, checkpoint_id)
            out("*** Loading first checkpoint - the script should start here!")
            
            -- Wait 10 seconds to simulate some scripted stuff happening and then reach the second checkpoint
            cm:callback(
                function()
                    out("*** Reaching second checkpoint after ten seconds, game will now save")
                    cm:checkpoint_reached(2, continue_from_second_checkpoint)
                end,
                10
            )
        end
    )

    cm:add_checkpoint_setup_callback(
        1,
        function(is_loading_game, checkpoint_id)
            out("*** Setup function associated with first checkpoint called - we're loading in to checkpoint " .. checkpoint_id)
        end
    )
    -- END CHECKPOINT 1 DECLARATION --


    -- START CHECKPOINT 2 DECLARATION --
    cm:add_checkpoint(
        2,
        function(is_loading_game, checkpoint_id)
            out("*** Loading from second checkpoint")
            continue_from_second_checkpoint(is_loading_game, checkpoint_id)
        end
    )

    cm:add_checkpoint_setup_callback(
        2,
        function(is_loading_game, checkpoint_id)
            out("*** Setup function associated with second checkpoint called - we're loading in to checkpoint " .. checkpoint_id)
        end
    )
    -- END CHECKPOINT 2 DECLARATION --

    function continue_from_second_checkpoint(is_loading_game, checkpoint_id)
        out("*** Continuing from second checkpoint, have we just loaded in: " .. tostring(is_loading_game))
    end
    on first load, output from system omitted:

    *** Setup function associated with first checkpoint called - we're loading in to checkpoint 1
    *** Loading first checkpoint - the script should start here!
    *** Reaching second checkpoint after ten seconds, game will now save
    *** Continuing from second checkpoint, have we just loaded in: false

    on load of savegame:

    *** Setup function associated with first checkpoint called - we're loading in to checkpoint 2
    *** Setup function associated with second checkpoint called - we're loading in to checkpoint 2
    *** Loading from second checkpoint
    *** Continuing from second checkpoint, have we just loaded in: true

    campaign_manager:add_checkpoint(
          number checkpoint id,
      function     callback,
      [boolean     call when checkpoint reached],
      [string     name]
    )

    Adds a checkpoint, from which a linear sequence script (such as a tutorial) may potentially reload. The checkpoint is associated with a numeric id, a callback, and optionally a string name. If supplied, the name is used for output.
    Checkpoints should be added using calls to this function when a linear sequence script loads. As such a script progresses through its events over time, it may mark checkpoints that have been added as reached by calling campaign_manager:checkpoint_reached. If the script is saved and reloaded, and campaign_manager:start_from_checkpoint is called after reloading, then the callback associated with the checkpoint most recently reached will be called. This callback should aim to resume the linear scripted sequence from the correct place.

    Parameters:

    1

    number

    Numeric checkpoint id. This should be a positive number, unique amongst added checkpoints. As a linear script progresses, each checkpoint it reaches should be associated with an ascending id value e.g. 10, 11, 12 on turn one, 20, 21, 22, 23 on turn two and so on. ID values do not have to be sequential - it is up to the scripter how they are spaced - but they must be ascending in the order that the checkpoints are reached. For example, if the script reaches a checkpoint with id 10, it is illegal to try and later reach a checkpoint with id 5.

    2

    function

    Callback associated with the checkpoint. This callback is called if the system decides to restart from this checkpoint when campaign_manager:start_from_checkpoint is called. It may optionally be called when the checkpoint is reached.

    The callback, when called, will be passed two arguments - a boolean indicating whether the game is loading (if false then this means that the checkpoint has been reached without reloading), and the number checkpoint id value.

    3

    boolean

    optional, default value=false

    Call the checkpoint callback when the checkpoint is reached, as well as when the checkpoint is restarted-from. By default, when campaign_manager:checkpoint_reached is called to mark a checkpoint as reached the associated callbacks are not called - they are only called if the game is subsequently reloaded. Pass true in here to also call the callbacks associated with a checkpoint when the checkpoint is reached.

    4

    string

    optional, default value=nil

    Checkpoint name. This is only used for output and doesn't affect the checkpoint behaviour.

    Returns:

    1. nil

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

    campaign_manager:add_checkpoint_setup_callback(
          number checkpoint id,
      function     callback,
      [boolean     call when checkpoint reached]
    )

    Adds a setup callback, associated with a previously-added checkpoint. The checkpoint is specified by numeric id, which should match the id given when the checkpoint was set up with campaign_manager:add_checkpoint.
    When campaign_manager:start_from_checkpoint is called, the main callback associated with the checkpoint most recently reached is called. Before that resumption callback is called, however, any setup callbacks added with this function that are associated with the most-recently reached callback and all checkpoints prior to it are called. The setup callbacks are called in ascending order of checkpoint id. For example, if the script resumes from a checkpoint with id 50, any setup callbacks associated with checkpoint 10 are called first, then any with checkpoint 20, checkpoint 30, checkpoint 40 and finally checkpoint 50 (assuming checkpoints with these ids are set up).
    When called, each setup checkpoint is passed a boolean value that indicates whether the script has reloaded, and also the numeric id of the most recently reached checkpoint.

    Parameters:

    1

    number

    Numeric id of the checkpoint to associate this setup callback with.

    2

    function

    Setup callback.

    3

    boolean

    optional, default value=false

    Call this setup callback when the associated checkpoint is reached, not just when the script is restarting.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 2970

    campaign_manager:set_checkpoint_prefix(string checkpoint prefix)

    Sets a prefix to use for constructed savegame names in the checkpoint system. If a checkpoint has been set to save the game with a constructed name (set via arguments to campaign_manager:checkpoint_reached when it is called) then a prefix is added to the savegame name. By default this is the player's faction name in singleplayer, and "MP Campaign" in multiplayer, but an alternative may be set with this function.

    Parameters:

    1

    string

    checkpoint prefix

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3004

    campaign_manager:set_checkpoint_names_use_checkpoint_id([boolean value])

    Sets whether the checkpoint system should insert the checkpoint ID in any constructed checkpoint names. This behaviour is disabled by default, but may be enabled with this function.

    Parameters:

    1

    boolean

    optional, default value=true

    value

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3016

    campaign_manager:checkpoint_reached(
          number checkpoint id,
      [function     continue callback],
      [boolean     should save],
      [boolean     save with name]
    )

    Marks a checkpoint as reached. The checkpoint should have been previously set up with campaign_manager:add_checkpoint. The checkpoint reached is specified by numeric id.
    When a checkpoint is reached, the id of that checkpoint is updated within the savegame data, and by default the game is also saved which commits that update to file. Should the saved game get saved (either by checkpoint_reached, later in script, or by the player) and subsequently reloaded, and should campaign_manager:start_from_checkpoint be called in script during the loading sequence, then the callback associated with the last-reached checkpoint by campaign_manager:add_checkpoint is called. Each callback associated with a checkpoint should aim to resume the script from that checkpoint.
    When a checkpoint is reached the system may optionally call callbacks associated with that checkpoint that were added with campaign_manager:add_checkpoint or campaign_manager:add_checkpoint_setup_callback. Callbacks added with those functions are normally only called when the game is reloaded, but may be flagged to also get called when the associated checkpoint is reached.
    If a continue callback is supplied to this function then it is called after the checkpoint data is updated and (optionally) the campaign is saved. This callback should continue the script after the checkpoint is reached. It is not called when the game is reloaded - the callback supplied by campaign_manager:add_checkpoint is called in this case.

    Parameters:

    1

    number

    ID value of checkpoint reached.

    2

    function

    optional, default value=nil

    Callback to call once the game is successfully saved. This callback should continue the script. If no value is provided here then but no post-update callback will be called.

    3

    boolean

    optional, default value=true

    Specifies whether the game should be saved as the checkpoint is reached. The game is saved by default, but this operation will cause a noticeable pause in the game so it may not be desirable to save at each and every checkpoint. Supply false as argument here to not save the game after this checkpoint is reached.

    4

    boolean

    optional, default value=false

    Specifies whether the game should save with a named savegame. If the game is to be saved (set by the previous parameter) and this argument is set to true, then the game will be saved with a name constructed by the a prefix (which can be set with campaign_manager:set_checkpoint_prefix), the checkpoint id if campaign_manager:set_checkpoint_names_use_checkpoint_id has been set, and the checkpoint name. If the argument is set to false then the game is autosaved.

    Returns:

    1. boolean save succeeded - save operation succeeded, if it was attempted. If no save was attempted then true is returned. Save operations can fail if a filename was supplied to this function - this prompts the function to attempt a single direct save with cm:save_game instead of an autosave with cm:autosave_at_next_opportunity, and direct save operations can fail if the game is in the wrong state at that moment. A script error is also thrown if the save fails.

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3028

    campaign_manager:start_from_checkpoint()
    Attempt to start from a checkpoint. If using the checkpoint system, it is recommended to call this function somewhere on the first tick.
    The checkpoint that was most recently marked as reached with campaign_manager:checkpoint_reached in the savegame will be looked up. If no checkpoint was marked as reached in the savegame then the checkpoint with the lowest numeric id is looked up instead. If no checkpoints have been added, then an error is generated.
    When starting from a particular checkpoint, any setup callbacks associated with all checkpoints leading up to that particular checkpoint are called in sequence. For example, when starting from checkpoint 3, all setup functions associated with checkpoint 1, then with checkpoint 2, then with checkpoint 3 are called. Finally, the main callback associated with checkpoint 3 is called, which should aim to resume the script from that point.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3137

    campaign_manager:get_current_checkpoint()
    Returns the id of the most recently reached checkpoint. If no checkpoint has been reached then nil is returned.

    Returns:

    1. number checkpoint id

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3200

    Back to top

    General Querying

    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 3223

    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 3237

    campaign_manager:is_game_loaded()
    Returns whether the LoadingGame has been received. If this is true, then data from the savegame will have been loaded and will be ready to query.

    Returns:

    1. boolean game is loaded

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3251

    campaign_manager:is_model_created()
    Returns whether the campaign model and game interfaces have been created. This becomes true when the WorldCreated event is received.

    Returns:

    1. boolean model is created

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3259

    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 3267

    campaign_manager:model()
    Returns a handle to the game model at any time (after the game has been created).

    Returns:

    1. object model

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

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

    Returns:

    1. object game_interface

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3289

    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 3302

    campaign_manager:local_faction_exists()
    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 3358

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

    Parameters:

    1

    boolean

    optional, default value=false

    force result

    Returns:

    1. string local faction name

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3366

    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 3385

    campaign_manager:get_human_factions()
    Returns a numerically-indexed table containing the string keys of all human factions within the game.

    Returns:

    1. table human factions

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3411

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

    Returns:

    1. boolean is any human faction's turn

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3430

    campaign_manager:get_factions_at_campaign_start()
    Returns a numerically-indexed table containing the string keys of all factions at the start of the game.

    Returns:

    1. table factions at campaign start

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3438

    campaign_manager:get_local_faction_culture()
    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.

    Returns:

    1. string local faction culture

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3457

    campaign_manager:get_local_faction_subculture()
    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.

    Returns:

    1. string local faction subculture

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3464

    campaign_manager:whose_turn_is_it()
    Returns the faction key of the faction whose turn it is currently.

    Returns:

    1. string faction key

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3472

    campaign_manager:is_local_players_turn()
    Returns true if it's the local player's turn.

    Returns:

    1. boolean is local player's turn

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3480

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

    Returns:

    1. boolean battle is happening

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3488

    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 3496

    campaign_manager:get_pending_battle_general_for_faction(
          faction faction,
      [boolean     should_include_secondary_participants]
    )

    Returns the pending battle general for the specified faction if it is participant in the battle or false

    Parameters:

    1

    faction

    faction

    2

    boolean

    optional, default value=true

    Whether we should check in the secondary participants list too

    Returns:

    1. character the general from the specified faction or false if the faction is not participant in the battle
    2. boolean is_from_attacking_side, is the returned general from the attacking side

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3510

    campaign_manager:is_faction_participant_in_pending_battle(
          faction faction,
      [boolean     should_include_secondary_participants]
    )

    Checks whether the specified faction is participant in the pending battle

    Parameters:

    1

    faction

    faction

    2

    boolean

    optional, default value=true

    Whether we should check in the secondary participants list too

    Returns:

    1. boolean is the specified faction participant in the pending battle
    2. boolean is_from_attacking_side, is the specified faction from the attacking side

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3555

    campaign_manager:get_pending_battle_general_for_primary_enemy_faction(faction our_faction)

    Returns the pending battle general of the primary enemy army of the specified faction or false if the specified faction is not participant in the battle

    Parameters:

    1

    faction

    our_faction

    Returns:

    1. character the general for the enemy of the specified faction or false if the specified faction is not participant in the battle
    2. boolean is_from_attacking_side, is the returned general from the attacking side

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3566

    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 3585

    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 3593

    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 3606

    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 3618

    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 3640

    campaign_manager:building_chain_exists_in_region(string chain key, region region)

    Returns whether the supplied building chain exists in the supplied region.

    Parameters:

    1

    string

    chain key

    2

    region

    region

    Returns:

    1. false or the level of the building from this chain if such building exists

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3668

    campaign_manager:max_chain_level_in_faction(string chain key, faction faction)

    Returns the level of the highest tier building from the supplied chain in all of the regions of the supplied faction or false if a building from this chain doesn't exist in the faction

    Parameters:

    1

    string

    chain key

    2

    faction

    faction

    Returns:

    1. number -1 if there is no building from this chain or the level of the highest tier building from the supplied chain in all of the regions of the supplied faction

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3698

    campaign_manager:get_building_from_building_chain(string chain key, number level)
    Returns the building level name for the building from the supplied chain at the supplied level

    Parameters:

    1

    string

    chain key

    2

    number

    level

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3731

    campaign_manager:get_building_create_cost(string building level key)
    Returns the creation cost record key for the building level with the given key

    Parameters:

    1

    string

    building level key

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3748

    campaign_manager:get_building_conversion_cost(string building level key)
    Returns the conversion cost record key for the building level with the given key

    Parameters:

    1

    string

    building level key

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3760

    campaign_manager:get_building_repair_override_cost_record_key(string building level key)
    Returns the repair override cost record key for the building level with the given key

    Parameters:

    1

    string

    building level key

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3772

    campaign_manager:is_building_excluded_from_corvee_labour(string building level key)
    Returns whether building level with key is excluded from corvee labour

    Parameters:

    1

    string

    building level key

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3784

    campaign_manager:get_building_refund_cost(
      string     building_interface the script interface of the building
    )
    Returns how much resources would be refunded for the building

    Parameters:

    1

    string

    building_interface the script interface of the building

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3796

    Back to top

    Character Queries & Modification

    campaign_manager:get_garrison_commander_of_region(region region object)
    Returns the garrison commander character of the settlement in the supplied region.

    Parameters:

    1

    region

    region object

    Returns:

    1. character garrison commander

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3832

    campaign_manager:get_closest_general_to_position_from_faction(
      object     faction,
      number     x,
      number     y,
      [boolean     include garrison commanders]
    )
    Returns the general within the supplied faction that's closest to the supplied logical co-ordinates.

    Parameters:

    1

    object

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

    2

    number

    Logical x co-ordinate.

    3

    number

    Logical y co-ordinate.

    4

    boolean

    optional, default value=false

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

    Returns:

    1. character closest character

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3866

    campaign_manager:get_closest_character_to_position_from_faction(
      object     faction,
      number     x,
      number     y,
      [boolean     general characters only],
      [boolean     include garrison commanders]
    )
    Returns the character within the supplied faction that's closest to the supplied logical co-ordinates.

    Parameters:

    1

    object

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

    2

    number

    Logical x co-ordinate.

    3

    number

    Logical y co-ordinate.

    4

    boolean

    optional, default value=false

    Restrict search results to generals.

    5

    boolean

    optional, default value=false

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

    Returns:

    1. character closest character

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3878

    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 3942

    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 3972

    campaign_manager:get_family_member_by_cqi(number cqi, character character)
    Returns a family member by it's command queue index. If no character with the supplied cqi is found then false is returned.
    Returns the supplied character's full localised name as a string for output.

    Parameters:

    1

    number

    cqi

    2

    character

    character

    Returns:

    1. family_member family_member
    2. string character name

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 3995

    campaign_manager:get_character(string character lookup string)
    Returns a character by character lookup string. If no character with the supplied character lookup string is found then first is returned.

    Parameters:

    1

    string

    character lookup string

    Returns:

    1. character character

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

    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 4060

    campaign_manager:get_character_by_fm_cqi(number family member cqi)

    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.

    Parameters:

    1

    number

    family member cqi

    Returns:

    1. character character

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4075

    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 4093

    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 4108

    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 4123

    campaign_manager:char_lookup_str(character character)

    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

    character

    Character or character cqi. A family_member script interface may also be supplied.

    Returns:

    1. string lookup string

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4143

    campaign_manager:char_lookup_str_fm(family_member family member)

    Various game interface functions lookup characters using a lookup string. This function converts a family_member into a lookup string that can be used by code functions to find the related character. It may also be supplied a family member cqi in place of a family member object.
    This function is related to and does the same job as campaign_manager:char_lookup_str. The main difference between them is that a number or string supplied to campaign_manager:char_lookup_str is assumed to be a cqi identifying a character interface, while a number/string supplied to this function is assumed to be a cqi identifying a family member interface.

    Parameters:

    1

    family_member

    Family member or number/string family member cqi. A character script interface may also be supplied.

    Returns:

    1. string lookup string

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4161

    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 4180

    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 4189

    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 4198

    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 4207

    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 4216

    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 4225

    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 4234

    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 4243

    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 4252

    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 4261

    campaign_manager:char_is_governor(character character)
    Returns true if the supplied character is the governor of a region, false otherwise.

    Parameters:

    1

    character

    character

    Returns:

    1. boolean is governor

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4270

    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 4279

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

    Parameters:

    1

    string

    faction key

    2

    string

    subculture key

    Returns:

    1. character closest visible character

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4289

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

    Parameters:

    1

    faction

    faction

    2

    number

    x

    3

    number

    y

    Returns:

    1. character closest character

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4340

    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 4366

    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 4386

    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 4406

    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 4432

    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 4474

    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 4503

    Back to top

    Dynasty Helpers

    campaign_manager:is_character_ruler_of_dynasty(character general character)
    Returns whether the character is a ruler of a dynasty

    Parameters:

    1

    character

    general character

    Returns:

    1. boolean is the character a ruler

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4565

    campaign_manager:get_dynasty_ruled_by_character(character general character)
    Returns the dynasty of which this character is a ruler

    Parameters:

    1

    character

    general character

    Returns:

    1. string key of the dynasty

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

    campaign_manager:is_faction_ruler_of_dynasty(faction faction)
    Returns whether the faction is a ruler of a dynasty

    Parameters:

    1

    faction

    faction

    Returns:

    1. boolean key is the faction a ruler of a dynasty

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4595

    campaign_manager:get_dynasty_ruled_by_faction(faction faction)
    Returns the dynasty of which this faction is a ruler

    Parameters:

    1

    faction

    faction

    Returns:

    1. string key of the dynasty

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4612

    Back to top

    Faction Queries & Modification

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

    Parameters:

    1

    string

    faction key

    Returns:

    1. faction faction

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4632

    campaign_manager:faction_can_afford_resource_cost(
      faction     faction object,
      table     in the format {{"res_key1"
    )
    Returns true if the specified faction has access to all listed resources and has the required amount of them

    Parameters:

    1

    faction

    faction object

    2

    table

    val1}, {"res_key2", val1} ... } or {{key = "res_key1", amount = 5} ... }

    Returns:

    1. faction can afford the specified resource cost

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4656

    campaign_manager:faction_contains_building(faction faction object, string building key)
    Returns true if territories controlled by the supplied faction contain the supplied building. This won't work for horde buildings.

    Parameters:

    1

    faction

    faction object

    2

    string

    building key

    Returns:

    1. faction contains building

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4681

    campaign_manager:num_characters_of_type_in_faction(faction faction object, string character type)
    Returns the number of characters of the supplied type in the supplied faction.

    Parameters:

    1

    faction

    faction object

    2

    string

    character type

    Returns:

    1. number number of characters

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4706

    campaign_manager:num_characters_with_skill_in_faction(faction faction object, string skill record key)
    Returns the number of characters in the supplied faction which have the supplied skill

    Parameters:

    1

    faction

    faction object

    2

    string

    skill record key

    Returns:

    1. number number of characters

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

    campaign_manager:kill_all_armies_for_faction(faction faction object)
    Kills all armies in the supplied faction.

    Parameters:

    1

    faction

    faction object

    Returns:

    1. number number of armies killed

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4761

    campaign_manager:get_trespasser_list_for_faction(faction faction object)
    Returns a table of cqis of characters that are both at war with the specified faction and also trespassing on its territory.

    Parameters:

    1

    faction

    faction object

    Returns:

    1. table of character command queue indexes

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4794

    campaign_manager:number_of_units_in_faction(faction faction object, [boolean exclude armed citizenry])
    Returns the number of units in all military forces in the supplied faction. The optional second parameter, if true, specifies that units in armed citizenry armies should not be considered in the calculation.

    Parameters:

    1

    faction

    faction object

    2

    boolean

    optional, default value=false

    exclude armed citizenry

    Returns:

    1. number number of units

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4836

    campaign_manager:faction_has_full_military_force(faction faction object)
    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 object

    Returns:

    1. boolean has full military force

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4862

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

    Parameters:

    1

    faction

    faction object

    Returns:

    1. boolean faction is alive

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 4883

    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 4897

    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 4923

    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 4949

    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 4981

    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 5003

    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 5029

    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 5055

    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 5075

    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

    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 5115

    campaign_manager:faction_contains_character_of_subtype(
      faction     faction,
      [    string character subtype],
      [boolean     return characters]
    )

    Returns true if the supplied faction contains any character of the supplied subtype, or false otherwise. If the return characters flag is set, then a table containing all matching characters is also returned.

    Parameters:

    1

    faction

    faction

    2

    string

    optional, default value=nil

    Character subtype key, from the agent_subtypes table.

    3

    boolean

    optional, default value=false

    Instructs the function to return a list containing all characters.

    Returns:

    1. boolean faction contains matching characters
    2. table list of matching character objects, if option is set

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5154

    campaign_manager:faction_set_free_instant_constructions(
      faction_key     which faction we want to modify,
      free_instant_constructions     new value for number of free instant constructions available to the supplied faction
    )
    Sets number of free instant constructions available to a faction

    Parameters:

    1

    faction_key

    which faction we want to modify

    2

    free_instant_constructions

    new value for number of free instant constructions available to the supplied faction

    Returns:

    1. boolean whether the call was successful

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5192

    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 5226

    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 5254

    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 5282

    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 5310

    Back to top

    Military Force Queries and Modifications

    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 5361

    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 5384

    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 5423

    campaign_manager:num_mobile_forces_in_force_list(military_force_list military force list)
    Returns the number of military forces that are not armed-citizenry in the supplied military force list.

    Parameters:

    1

    military_force_list

    military force list

    Returns:

    1. number number of mobile forces

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

    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 5472

    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 5507

    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 5533

    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 5558

    campaign_manager:military_force_monetary_value(number military force cqi)

    Returns the monetary value of all of the units in the force. This would be the cost of this force in a custom battle.

    Parameters:

    1

    number

    military force cqi

    Returns:

    1. number value

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5574

    campaign_manager:disallow_army_occupation_decision(number force cqi, string occupation decision)

    Disallows the army from performing one or more specific occupation decisions.

    Parameters:

    1

    number

    Command-queue index value of subject military force.

    2

    string

    Occupation decision or decisions. This can be a single string, or a table of string occupation decisions.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5596

    Back to top

    Region and Province Queries & Modification

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

    Parameters:

    1

    string

    region name

    Returns:

    1. region region

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5643

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

    Parameters:

    1

    string

    province name

    Returns:

    1. province province

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5662

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

    Parameters:

    1

    string

    region name

    2

    string

    faction name

    Returns:

    1. region region

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5682

    campaign_manager:region_has_neighbours_of_other_religion(region subject region)
    Returns true if a specified region has any neighbouring regions with a different religion, false otherwise.

    Parameters:

    1

    region

    subject region

    Returns:

    1. boolean region has neighbour of different religion

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5709

    campaign_manager:instantly_upgrade_building_in_region_slot(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 5731

    campaign_manager:instantly_upgrade_building_in_region(
      string     region key,
      number     slot number,
      string     target building key
    )
    Instantly upgrades the building in the supplied slot number of the supplied region to the supplied building key.

    Parameters:

    1

    string

    region key

    2

    number

    slot number

    3

    string

    target building key

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5745

    campaign_manager:instantly_build_building_in_region(
      string     region key,
      number     slot number,
      string     target building key,
      [boolean     ignore_costs]
    )
    Instantly builds the building in the supplied slot number of the supplied region to the supplied building key.

    Parameters:

    1

    string

    region key

    2

    number

    slot number

    3

    string

    target building key

    4

    boolean

    optional, default value=false

    whether to ignore the costs and build for free, or expend the resources and dev points

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5785

    campaign_manager:instantly_downgrade_building_in_region(
      string     region key,
      number     slot number,
      [boolean     recoup_costs],
      [boolean     silent]
    )
    Instantly downgrades the building in the supplied slot number of the supplied region.

    Parameters:

    1

    string

    region key

    2

    number

    slot number

    3

    boolean

    optional, default value=false

    recoup_costs

    4

    boolean

    optional, default value=false

    silent

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5813

    campaign_manager:queue_building_construction_in_region(
      string     region key,
      number     slot number,
      string     target building key,
      [number     turns_to_complete],
      [boolean     ignore_costs]
    )
    Builds the building in the supplied slot number of the supplied region to the supplied building key. It automatically substracts the building cost or convertion cost for that building. Will expend conversion cost rather than building cost if conversion is possible. Turns to complete will override the construction time, use 0 for instant construction.

    Parameters:

    1

    string

    region key

    2

    number

    slot number

    3

    string

    target building key

    4

    number

    optional, default value=-1

    override the number of turns to complete the building, 0 - for instant completion, -1 - do not override

    5

    boolean

    optional, default value=false

    whether to ignore the costs and build for free, or expend the resources and dev points

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5837

    campaign_manager:queue_building_construction_in_force(
      string     force_cqi,
      number     slot_index,
      string     target_building_key,
      [number     turns_to_complete],
      [boolean     ignore_costs]
    )
    Builds the supplied building key in the supplied slot index number in the supplied military force. It automatically substracts the building cost or convertion cost for that building. Will expend conversion cost rather than building cost if conversion is possible. Turns to complete will override the construction time, use 0 for instant construction.

    Parameters:

    1

    string

    military force command queue index

    2

    number

    military force slot index

    3

    string

    the building key to queue construction

    4

    number

    optional, default value=-1

    override the number of turns to complete the building, 0 - for instant completion, -1 - do not override

    5

    boolean

    optional, default value=false

    whether to ignore the costs and build for free, or expend the resources and dev points

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5895

    campaign_manager:queue_building_dismantle(string region key, number slot number)
    Queues the building in the supplied slot number of the supplied region for dismantling.

    Parameters:

    1

    string

    region key

    2

    number

    slot number

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5951

    campaign_manager:queue_building_repair(string region key, number slot number, [boolean ignore_cost])
    Queues the building in the supplied slot number of the supplied region for repair.

    Parameters:

    1

    string

    region key

    2

    number

    slot number

    3

    boolean

    optional, default value=false

    whether to ignore the cost and repair for free, or expend the resources and dev points

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 5985

    campaign_manager:get_building_create_time(string building level key)

    Get the creation time for a building by a building level record key.

    Parameters:

    1

    string

    Building level record key, from the building_levels database table.

    Returns:

    1. number creation time in turns

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6030

    campaign_manager:instantly_dismantle_building_in_region_slot(slot slot)

    Instantly dismantles the building in the supplied region slot

    Parameters:

    1

    slot

    slot

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6044

    campaign_manager:instantly_dismantle_building_in_region(
      string     region key,
      number     slot number,
      [boolean     recoup_resources],
      [boolean     silent]
    )
    Instantly dismantles the building in the supplied slot number of the supplied region.

    Parameters:

    1

    string

    region key

    2

    number

    slot number

    3

    boolean

    optional, default value=true

    whether to recoup the resources for the dismantled building

    4

    boolean

    optional, default value=false

    whether to suppress the firing of an event feed event for the dismantled building

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6052

    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 6096

    campaign_manager:create_storm_for_region(
      string     region key,
      number     storm strength,
      number     duration,
      string     storm type
    )
    Creates a storm of a given type in a given region. This calls the function of the same name on the game interface, but adds validation and output.

    Parameters:

    1

    string

    region key

    2

    number

    storm strength

    3

    number

    duration

    4

    string

    storm type

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6122

    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 6155

    campaign_manager:region_contains_building(region region, string building key)
    Returns true if the supplied region contains a building with the supplied key, false otherwise.

    Parameters:

    1

    region

    region

    2

    string

    building key

    Returns:

    1. boolean region contains building

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6173

    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 6235

    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 6245

    Back to top

    Pending Battle Cache

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

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

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

    campaign_manager:pending_battle_cache_num_attackers()
    Returns the number of attacking armies in the cached pending battle.

    Returns:

    1. number number of attacking armies

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6639

    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 related family member interface, 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 family member cqi
    3. number military force cqi
    4. string faction name

    Example - print attacker details:

    for i = 1, cm:pending_battle_cache_num_attackers() do
        local char_cqi, fm_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("\tfamily_member cqi: " .. fm_cqi);
    out("\tmilitary force cqi: " .. mf_cqi);
    end

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6647

    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 6675

    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. If no army index is specified, then the total number of units across all attacking armies is returned.

    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 6691

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

    Returns the cqi and unit key of a specified unit on the specified attacker in the pending battle cache, by 1-based 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 6711

    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 6738

    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 related family member interface, the cqi of the military force, and the faction name.

    Parameters:

    1

    number

    index of defender

    Returns:

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

    Example - print defender details:

    for i = 1, cm:pending_battle_cache_num_defenders() do
        local char_cqi, fm_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("\tfamily_member cqi: " .. fm_cqi);
    out("\tmilitary force cqi: " .. mf_cqi);
    end

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6746

    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 6773

    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. If no army index is specified, then the total number of units across all defending armies is returned.

    Parameters:

    1

    number

    optional, default value=nil

    index of defender

    Returns:

    1. number number of defender units

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6789

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

    Returns the cqi and unit key of a specified unit on the specified defender in the pending battle cache, by 1-based 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 6809

    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 6836

    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 6858

    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 6880

    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 6889

    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 6912

    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 6935

    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. This may be supplied as a character object or as a character cqi number.

    Returns:

    1. boolean character was attacker

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6951

    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. This may be supplied as a character object or as a character cqi number.

    Returns:

    1. boolean character was defender

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 6977

    campaign_manager:pending_battle_cache_char_is_involved(object character)
    Returns true if the supplied character was an attacker or defender in the cached pending battle.

    Parameters:

    1

    object

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

    Returns:

    1. boolean character was involved

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7003

    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 7021

    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 7046

    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 7071

    campaign_manager:pending_battle_cache_get_enemies_of_char(character character)

    Returns a numerically indexed table of family member cqis, each representing an enemy character of the supplied character in the cached pending battle. Note that if the battle has already been fought, the character associated with the family member interface may be dead.
    If the supplied character was not present in the pending battle then the returned table will be empty.

    Parameters:

    1

    character

    Character to query. This may be supplied as either a character interface or a character cqi number.

    Returns:

    1. table table of enemy family member cqis

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7089

    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 7119

    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 7127

    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 7135

    campaign_manager:pending_battle_cache_attacker_value()
    Returns the gold value of attacking forces in the cached pending battle.

    Returns:

    1. number gold value

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7143

    campaign_manager:pending_battle_cache_defender_value()
    Returns the gold value of defending forces in the cached pending battle.

    Returns:

    1. number gold value

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7151

    campaign_manager:pending_battle_cache_attacker_strength()
    Returns the total summed strength of all attacking armies in the pending battle cache. This strength is an arbitrary numeric value indicating the fighting strength of the armies present.

    Returns:

    1. number strength

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7159

    campaign_manager:pending_battle_cache_defender_strength()
    Returns the total summed strength of all defending armies in the pending battle cache. This strength is an arbitrary numeric value indicating the fighting strength of the armies present.

    Returns:

    1. number strength

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7167

    campaign_manager:pending_battle_cache_attackers_contained_unit(string unit key)

    Returns true if any of the attacking armies in the pending battle cache contained a unit with the supplied key, or false otherwise.

    Parameters:

    1

    string

    Unit key, from the land_units database table.

    Returns:

    1. boolean unit was involved as attacker

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7175

    campaign_manager:pending_battle_cache_defenders_contained_unit(string unit key)

    Returns true if any of the defending armies in the pending battle cache contained a unit with the supplied key, or false otherwise.

    Parameters:

    1

    string

    Unit key, from the land_units database table.

    Returns:

    1. boolean unit was involved as defender

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7201

    campaign_manager:pending_battle_cache_unit_is_involved(string unit key)

    Returns true if any of the attacking armies in the pending battle cache contained a unit with the supplied key.

    Parameters:

    1

    string

    Unit key, from the land_units database table.

    Returns:

    1. boolean unit was involved

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7227

    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
    ScriptEventPlayerWinsBattleA human player has won a battle.
    ScriptEventPlayerWinsFieldBattleA 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.
    ScriptEventPlayerWinsSettlementDefenceBattleA human player has won a settlement defence battle as the defender (including a battle where the player sallied).
    ScriptEventPlayerWinsSettlementAttackBattleA human player has won a settlement defence battle as the attacker. They should have captured the settlement if this event has been received.
    ScriptEventPlayerLosesSettlementDefenceBattleA human player has lost a settlement defence battle as the defender.
    ScriptEventPlayerLosesSettlementAttackBattleA human player has lost a settlement defence battle as the attacker.
    ScriptEventPlayerLosesFieldBattleA human player has lost a field (non-settlement) battle.

    Back to top

    Values Passed to Battle

    Prior to battle, the campaign manager saves certain data into the Scripted Value Registry which can be accessed by battle scripts:

    Variable NameData TypeDescription
    battle_typestringThe string battle type.
    primary_attacker_faction_namestringThe faction key of the primary attacking army.
    primary_attacker_subculturestringThe subculture key of the primary attacking army.
    primary_defender_faction_namestringThe faction key of the primary defending army.
    primary_defender_subculturestringThe subculture key of the primary defending army.
    primary_attacker_is_playerbooleanWhether the local player is the primary attacker.
    primary_defender_is_playerbooleanWhether the local player is the primary defender.

    These values can be accessed in battle scripts using core:svr_load_string and core:svr_load_bool.

    Back to top

    Random Numbers

    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 7778

    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 7814

    Back to top

    Campaign UI

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

    Returns:

    1. campaign_ui_manager

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7853

    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 7864

    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 7896

    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 7913

    campaign_manager:disable_shortcut(string object_id, string function_id, bool disabled)
    Disables/Enables a shortcut in the underlaying SHORTCUT_HANDLER. This is a wrapper of a c++ function with the same name.

    Parameters:

    1

    string

    ui_component id matching the function from the default_keys.xml.

    2

    string

    function id matching the function shortcut from the default_keys.xml.

    3

    bool

    true for disable, false for enable.

    Returns:

    1. nil

    Example:

    cm:disable_shortcut("object_id", "function_id", true)

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 7928

    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 7953

    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.

    In campaign, the game will print the current camera co-ordinates if the camera_position command is entered on the console. The position is printed on the Command tab of the console.

    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 8026

    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 8061

    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 8098

    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 8135

    campaign_manager:scroll_camera_to_settlement(string region key, [number time])
    Scrolls the camera to a settlement, specified by region key.

    Parameters:

    1

    string

    Key of region containing target settlement.

    2

    number

    optional, default value=1

    Time in seconds over which to scroll.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8200

    campaign_manager:scroll_camera_to_region_slot(string slot key, [number time])
    Scrolls the camera to the specified region slot. The region slot is specified by its slot key.

    Parameters:

    1

    string

    Key of target slot.

    2

    number

    optional, default value=1

    Time in seconds over which to scroll.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8220

    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 8240

    campaign_manager:scroll_camera_to_character(number cqi, [number time])
    Scrolls the camera to the specified character. The character is specified by its command queue index (cqi).

    Parameters:

    1

    number

    CQI of target character.

    2

    number

    optional, default value=1

    Time in seconds over which to scroll.

    Returns:

    1. nil

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

    campaign_manager:scroll_camera_to_force(number cqi, [number time])
    Scrolls the camera to the specified military force. The military force is specified by its command queue index (cqi).

    Parameters:

    1

    number

    CQI of target military force.

    2

    number

    optional, default value=1

    Time in seconds over which to scroll.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8315

    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 8336

    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 8449

    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 8494

    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 console output.

    Parameters:

    1

    boolean

    clear animation scenes

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8526

    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 8535

    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:get_camera_position_cindy_format()
    Returns camera position and target as it would in battle. Useful for setting cindy cameras.

    Returns:

    1. number posx
    2. number posy
    3. number posz
    4. number tarx
    5. number tary
    6. number tarz

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8582

    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 8596

    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 8616

    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 8634

    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 8660

    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 8699

    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 8730

    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 8794

    campaign_manager:set_active_cutscene([campaign_cutscene active cutscene])

    Sets the active cutscene on the campaign manager, so the campaign manager knows which cutscene (if any) is currently playing. If no campaign cutscene is supplied, then the active cutscene is cleared. This should only be called by the campaign cutscene library and should not be called by client scripts.

    Parameters:

    1

    campaign_cutscene

    optional, default value=nil

    active cutscene

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8824

    campaign_manager:get_active_cutscene()
    Returns the campaign cutscene currently playing. If no cutscene is currently playing then nil is returned.

    Returns:

    1. campaign_cutscene active cutscene, or nil if no cutscene is active

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8848

    campaign_manager:skip_active_cutscene()
    Skips any campaign cutscene currently active.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8856

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

    Parameters:

    1

    boolean

    steal

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8865

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

    Parameters:

    1

    boolean

    steal

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8882

    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 8907

    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 8924

    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. campaign_manager:steal_user_input will need to be called separately for this mechanism to work, unless it's the escape key that being stolen, where campaign_manager:steal_escape_key should be used instead. In this latter case campaign_manager:steal_escape_key_with_callback can be used instead.

    Parameters:

    1

    string

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

    2

    string

    Key name.

    3

    function

    Function to call when the key is pressed.

    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 8942

    campaign_manager:release_key_with_callback(string name, string key)
    Releases a key stolen with campaign_manager:steal_key_with_callback.

    Parameters:

    1

    string

    Unique name for this key-steal entry.

    2

    string

    Key name.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 8988

    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 campaign_manager:steal_escape_key if the key is not already stolen.

    Parameters:

    1

    string

    Unique name for this key-steal entry.

    2

    function

    Function to call when the key is pressed.

    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 9018

    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 9031

    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 9045

    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 9057

    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=1

    Minimum playtime for the advice VO in seconds. This must be a positive number. 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 9082

    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 9192

    campaign_manager:set_exclusive_visible_labels(faction_keys array of strings)
    Sets which factions labels should only be visible.

    Parameters:

    1

    faction_keys

    each string represents faction key from the factions table

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9211

    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 9222

    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 9242

    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 9250

    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 9270

    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 9283

    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 9307

    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 9414

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

    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=5

    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. The value must be positive.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9436

    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 9583

    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 9614

    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 9672

    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 9683

    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 9693

    campaign_manager:progress_on_fullscreen_panel_dismissed(function callback, [number callback delay])
    Calls the supplied callback when all fullscreen campaign panels are dismissed. Only one such monitor may be active at once - starting a second will cancel the first.

    Parameters:

    1

    function

    Callback to call.

    2

    number

    optional, default value=0

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

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9701

    campaign_manager:cancel_progress_on_fullscreen_panel_dismissed(function callback, [number callback delay])
    Cancels any running monitor started with campaign_manager:progress_on_fullscreen_panel_dismissed.

    Parameters:

    1

    function

    Callback to call.

    2

    number

    optional, default value=0

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

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9726

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

    Parameters:

    1

    function

    Callback to call.

    2

    number

    optional, default value=0

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

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9736

    campaign_manager:progress_on_battle_completed(string name, function callback, [number delay])
    Calls the supplied callback when a battle sequence is fully completed. A battle sequence is completed once the pre or post-battle panel has been dismissed and any subsequent camera animations have finished.

    Parameters:

    1

    string

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

    2

    function

    Callback to call.

    3

    number

    optional, default value=0

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

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 9819

    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 9857

    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 9871

    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 9923

    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 9930

    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 9958

    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 10044

    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_fullscreen_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 10174

    Back to top

    Character Locomotion Wrappers

    It can traditionally be tricky to get characters locomotion orders such as cm:move_to and cm:attack to work reliably. Locomotion orders require several conditions to be true before they will work successfully, such as it being the locomoting character's faction's turn and for the turn to be in the correct (normal) phase.

    The locomotion orders listed in this section all run through some central functionality that performs pre and post-locomotion checks to catch and either bypass or report any possible errors. If a movement order is issued before the normal turn phase (as is the case at the moment when the FactionTurnStarts event is triggered), the order will be delayed until the normal turn phase starts, for example.

    campaign_manager:enable_locomotion_failed_warning([boolean enable warning])

    Enables or disables the script error that appears by default when a character locomotion order such as campaign_manager:move_to or campaign_manager:attack fails for some reason. This script error can be suppressed globally for all locomotion orders by calling this function with false as an argument.

    Parameters:

    1

    boolean

    optional, default value=true

    enable warning

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10286

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

    Instructs a character heading a military force to attack another. This function wraps the episodic scripting function cm:attack.
    This wrapper function will perform certain checks before issuing the order - see the documentation on Character Locomotion Wrappers for more information.

    Parameters:

    1

    string

    Attacker character string - see Character Lookups.

    2

    string

    Defender character string - see Character Lookups.

    3

    boolean

    optional, default value=false

    Instructs the attacker to lay siege to the garrison of the target character.

    Returns:

    1. boolean command succeeded

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10380

    campaign_manager:attack_queued(string attacker, string defender, [boolean lay siege])

    Instructs a character heading a military force to attack another with a queued order. This function wraps the episodic scripting function cm:attack_queued.
    This wrapper function will perform certain checks before issuing the order - see the documentation on Character Locomotion Wrappers for more information.

    Parameters:

    1

    string

    Attacker character string - see Character Lookups.

    2

    string

    Defender character string - see Character Lookups.

    3

    boolean

    optional, default value=nil

    Instructs the attacker to lay siege to the garrison of the target character.

    Returns:

    1. boolean command succeeded

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10405

    campaign_manager:attack_region(string attacker, string region name, [boolean should_attack_immediately])

    Instructs a character heading a military force to attack a region. This function wraps the episodic scripting function cm:attack_region.
    This wrapper function will perform certain checks before issuing the order - see the documentation on Character Locomotion Wrappers for more information.

    Parameters:

    1

    string

    Attacker character string - see Character Lookups.

    2

    string

    Target region name, from the campaign_map_regions database table.

    3

    boolean

    optional, default value=true

    Specify if the command should besiege the settlement or start the battle immediately.

    Returns:

    1. boolean command succeeded

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10430

    campaign_manager:attack_garrison_by_cqi(
          string attacker,
      number     garrison cqi,
      [boolean     should_attack_immediately]
    )

    Instructs a character leading a military force to attack a garrison residence, specified by cqi. This function wraps the episodic scripting function cm:attack_garrison_by_cqi.
    This wrapper function will perform certain checks before issuing the order - see the documentation on Character Locomotion Wrappers for more information.

    Parameters:

    1

    string

    Attacker character string - see Character Lookups.

    2

    number

    Garrison residence cqi.

    3

    boolean

    optional, default value=true

    Specify if the garrison should be besieged or attacked immediately. Note that if siege equipment is required and you don't have any, the game will soft lock

    Returns:

    1. boolean command succeeded

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10459

    campaign_manager:seek_exchange(string exchanging character, string target character, boolean show ui)

    Instructs a character at the head of a military force to seek to exchange forces with another. This function wraps the episodic scripting function cm:seek_exchange.
    This wrapper function will perform certain checks before issuing the order - see the documentation on Character Locomotion Wrappers for more information.

    Parameters:

    1

    string

    Exchanging character string - see Character Lookups.

    2

    string

    Target character string - see Character Lookups.

    3

    boolean

    Show the exchange UI or not.

    Returns:

    1. boolean command succeeded

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10488

    campaign_manager:move_to(string moving character, number x, number y)

    Instructs a character to move to a specified location. This function wraps the episodic scripting function cm:move_to.
    This wrapper function will perform certain checks before issuing the order - see the documentation on Character Locomotion Wrappers for more information.

    Parameters:

    1

    string

    Moving character string - see Character Lookups.

    2

    number

    Logical x co-ordinate of target position.

    3

    number

    Logical y co-ordinate of target position.

    Returns:

    1. boolean command succeeded

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10515

    campaign_manager:move_to_queued(string moving character, number x, number y)

    Instructs a character to move to a specified location with a queued action. This function wraps the episodic scripting function cm:move_to_queued.
    This wrapper function will perform certain checks before issuing the order - see the documentation on Character Locomotion Wrappers for more information.

    Parameters:

    1

    string

    Moving character string - see Character Lookups.

    2

    number

    Logical x co-ordinate of target position.

    3

    number

    Logical y co-ordinate of target position.

    Returns:

    1. boolean command succeeded

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10540

    campaign_manager:teleport_to(string teleporting character, number x, number y)

    Teleports a character to a logical position on the campaign map. This function wraps the episodic scripting function cm:teleport_to.
    This wrapper function will perform certain checks before issuing the order - see the documentation on Character Locomotion Wrappers for more information.
    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

    Teleporting character string - see Character Lookups.

    2

    number

    Logical x co-ordinate to teleport to.

    3

    number

    Logical y co-ordinate to teleport to.

    Returns:

    1. boolean command succeeded

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10565

    campaign_manager:join_garrison(string character string, string garrison string)

    Instructs a character leading a military force to join a garrison, specified by settlement key. This function wraps the episodic scripting function cm:join_garrison.
    This wrapper function will perform certain checks before issuing the order - see the documentation on Character Locomotion Wrappers for more information.

    Parameters:

    1

    string

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

    2

    string

    String of target garrison, from the campaign_map_settlements database table.

    Returns:

    1. boolean command succeeded

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10591

    Back to top

    Character Creation and Manipulation

    campaign_manager:create_force(
      string     faction key,
      string     unit list,
      string     region key,
      number     x,
      number     y,
      boolean     exclude named characters,
      [function     success callback]
    )
    Wrapper for create_force function on the underlying game interface, which instantly spawns an army with a general on the campaign map. This wrapper function adds debug output and success callback functionality.

    Parameters:

    1

    string

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

    2

    string

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

    3

    string

    Region key of home region for this force.

    4

    number

    x logical co-ordinate of force.

    5

    number

    y logical co-ordinate of force.

    6

    boolean

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

    7

    function

    optional, default value=nil

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

    Returns:

    1. boolean force created

    Example:

    cm:create_force(
        "troy_main_dan_apteron",        
        "troy_club_warriors,troy_club_warriors,troy_club_warriors,",
        "troy_main_zonaea_aenos",
        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 10631

    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     surpress_ui_messages]
    )

    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

    Surpress ui messages and statistics upgrade

    Returns:

    1. boolean force created

    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 10733

    campaign_manager:create_force_with_budget(
          string faction key,
      string     region key,
      number     budget,
      number     unit count,
      boolean     attacking,
      number     x,
      number     y,
      string     id,
      [function     success callback]
    )

    Instantly spawn an army with a certain budget with a general on the campaign map. This function is a wrapper for the cm:create_force_with_budget 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

    Region key of home region for this force.

    3

    number

    Budget of the force

    4

    number

    Number of units in the force

    5

    boolean

    Is the force on the attacking side

    6

    number

    x logical co-ordinate of force.

    7

    number

    y logical co-ordinate of force.

    8

    string

    id of the force

    9

    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_budget(
        "phar_main_irsu",
        "phar_main_east_sinai_beersheba",
        1000,
        5,
        true,
        525,
        325,
        function(cqi)
            out("Force created with char cqi: " .. cqi)
        end
    )

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 10841

    campaign_manager:create_force_with_general(
      string     faction key,
      string     unit list,
      string     region key,
      number     x,
      number     y,
      string     agent type,
      string     agent subtype,
      string     forename,
      string     clan name,
      string     family name,
      string     other name,
      boolean     make faction leader,
      [function     success callback]
    )
    Wrapper for create_force_with_general function on the underlying game interface, which instantly spawn an army with a specific general on the campaign map. This wrapper function adds debug output and success callback functionality.

    Parameters:

    1

    string

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

    2

    string

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

    3

    string

    Region key of home region for this force.

    4

    number

    x logical co-ordinate of force.

    5

    number

    y logical co-ordinate of force.

    6

    string

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

    7

    string

    Character subtype of character at the head of the army.

    8

    string

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

    9

    string

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

    10

    string

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

    11

    string

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

    12

    boolean

    Make the spawned character the faction leader.

    13

    function

    optional, default value=nil

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

    Returns:

    1. boolean force created

    Example:

    cm:create_force_with_general(
        "troy_main_dan_apteron",        
        "troy_club_warriors,troy_club_warriors,troy_club_warriors,troy_club_warriors,troy_club_warriors,troy_club_warriors,troy_club_warriors,troy_club_warriors,troy_club_warriors,troy_club_warriors,",
        "troy_main_zonaea_aenos"
        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 10947

    campaign_manager:create_force_with_existing_general(
      string     character lookup,
      string     faction key,
      string     unit list,
      string     region key,
      number     x,
      number     y,
      [function     success callback]
    )
    Wrapper for create_force_with_existing_general function on the underlying game interface, which instantly spawn an army with a specific existing general on the campaign map. The general is specified by character string lookup. This wrapper function adds debug output and success callback functionality.

    Parameters:

    1

    string

    Character lookup string for the general character.

    2

    string

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

    3

    string

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

    4

    string

    Region key of home region for this force.

    5

    number

    x logical co-ordinate of force.

    6

    number

    y logical co-ordinate of force.

    7

    function

    optional, default value=nil

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

    Returns:

    1. boolean force created

    Example:

    cm:create_force_with_existing_general(
        cm:char_lookup_str(char_dwf_faction_leader),
        "troy_main_dan_apteron",        
        "troy_club_warriors,troy_club_warriors,troy_club_warriors,",
        "troy_main_zonaea_aenos"
        714,
        353,
        function(cqi)
            out("Force created with char cqi: " .. cqi);
        end
    );

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11104

    campaign_manager:create_force_from_family_member(
          number family member cqi,
      string     faction key,
      string     unit list,
      string     region key,
      number     x,
      number     y,
      [function     success callback]
    )

    Wrapper for cm:create_force_from_family_member, which instantly spawn an army with a general from the recruitment pool, specified by the cqi value of a family_member. This wrapper function adds debug output and success callback functionality.

    Parameters:

    1

    number

    Family member command queue index value.

    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. boolean force successfully created

    Example:

    cm:create_force_from_family_member(
        123,
        "troy_main_dan_apteron",        
        "troy_club_warriors,troy_club_warriors,troy_club_warriors,",
        "troy_main_zonaea_aenos"
        714,
        353,
        function(cqi)
            out("Force created with char cqi: " .. cqi);
        end
    );

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11214

    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 11336

    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 11374

    campaign_manager:create_agent(
      string     faction key,
      string     character type,
      string     character subtype,
      number     x,
      number     y,
      string     id,
      [function     success callback]
    )
    Wrapper for create_agent function on the underlying game interface which adds input validation and console output. This function creates an agent of a specified type on the campaign map.

    Parameters:

    1

    string

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

    2

    string

    Character type of the agent.

    3

    string

    Character subtype of the agent.

    4

    number

    x logical co-ordinate of agent.

    5

    number

    y logical co-ordinate of agent.

    6

    string

    Unique string for agent.

    7

    function

    optional, default value=nil

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

    Returns:

    1. nil

    Example:

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

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11412

    campaign_manager:respawn_convalescing_agent(
      string     faction key,
      number     x,
      number     y,
          string character lookup,
      [function     success callback]
    )

    Wrapper for respawn_convalescing_agent function on the underlying game interface which adds input validation, text output, and a success callback. This function respawns an immortal agent that has been wounded.

    Parameters:

    1

    string

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

    2

    number

    x logical co-ordinate of agent.

    3

    number

    y logical co-ordinate of agent.

    4

    string

    Character lookup string - see Character Lookups for more information.

    5

    function

    optional, default value=nil

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

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11493

    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(
                "troy_main_dan_apteron",
                "names_name_2147357619",
                "names_name_2147357619",
                643,
                191
            )
        end
    )

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11579

    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(
                "troy_main_dan_apteron",
                "names_name_2147352487",
                "troy_main_dan_apteron",        
                "troy_club_warriors,troy_club_warriors,,troy_club_warriors,",
                "troy_main_zonaea_aenos",
                643,
                188,
                true
            )
        end
    )

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 11664

    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 11761

    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 11869

    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 11923

    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 11933

    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 11973

    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 11984

    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 12042

    campaign_manager:teleport_characters_to(forename_ids - array of strings, positions - array of tables)
    Teleports characters to a logical position on the campaign map.
    If only 1 position is passed as argument, then all characters will be teleported to that position

    Parameters:

    1

    forename_ids

    - array of strings

    2

    positions

    each table represents Vector2 that have x and y as keys. Positions length should be 1 or length of forename_ids

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12060

    campaign_manager:find_valid_spawn_location_for_character_from_character(
      faction_key     - strings,
      character_lookup_str     - character lookup string,
      in_same_region     - boolean,
      preferred_spawn_distance     - optional number
    )
    Utilise the pathfinder to locate a valid spawn point for a character, based around another character.
    Returns (-1, -1) if invalid, otherwise (x, y).

    Parameters:

    1

    faction_key

    - strings

    2

    character_lookup_str

    - character lookup string

    3

    in_same_region

    - boolean

    4

    preferred_spawn_distance

    - optional number

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12135

    campaign_manager:find_valid_spawn_location_for_character_from_settlement(
      faction_key     - strings,
      region_key     - region_key string,
      on_sea     - boolean,
      in_same_region     - boolean,
      preferred_spawn_distance     - optional number
    )
    Utilise the pathfinder to locate a valid spawn point for a character, based around settlement.
    Returns (-1, -1) if invalid, otherwise (x, y).

    Parameters:

    1

    faction_key

    - strings

    2

    region_key

    - region_key string

    3

    on_sea

    - boolean

    4

    in_same_region

    - boolean

    5

    preferred_spawn_distance

    - optional number

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12161

    campaign_manager:character_forced_invisible(
      character_lookup     - character lookup string,
      forced_invisible     - boolean
    )
    Sets charcater forced_invisible property.

    Parameters:

    1

    character_lookup

    - character lookup string

    2

    forced_invisible

    - boolean

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12196

    campaign_manager:characters_forced_invisible(
      forename_ids     - array of lookup strings by character forename ,
      forced_invisible     - boolean
    )
    Calls characters_forced_invisible for each forename id

    Parameters:

    1

    forename_ids

    - array of lookup strings by character forename

    2

    forced_invisible

    - boolean

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12211

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

    Parameters:

    1

    string

    char lookup string

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12226

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

    Parameters:

    1

    string

    char lookup string

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12241

    campaign_manager:enable_movement_for_faction(string faction key)
    Enables movement for the supplied faction. This calls the function of the same name on the game interface, but adds validation and output.

    Parameters:

    1

    string

    faction key

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12256

    campaign_manager:disable_movement_for_faction(string faction key)
    Disables movement for the supplied faction. This calls the function of the same name on the game interface, but adds validation and output.

    Parameters:

    1

    string

    faction key

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12271

    campaign_manager:force_add_ancillary(
      string     character string,
      string     ancillary key,
      [    boolean suppress event message]
    )

    Forceably adds an ancillary to a character. This calls the function of the same name on the game interface, but adds validation and output. This output will be shown on the traits tab of the console.

    Parameters:

    1

    string

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

    2

    string

    Ancillary key to add.

    3

    boolean

    optional, default value=false

    Whether to suppress the event message that the ancillary was added.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12315

    campaign_manager:force_add_and_equip_ancillary(
          string character lookup,
      string     ancillary key,
      [boolean     suppress event message]
    )

    Grant the specified ancillary to the specified character and equips it. If another ancillary is equipped in the relevant slot then that ancillary is unequipped.

    Parameters:

    1

    string

    Character lookup string. For more information, see Character Lookups.

    2

    string

    Ancillary key, from the ancillaries table.

    3

    boolean

    optional, default value=false

    Whether to suppress the event message that the ancillary was added.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12325

    campaign_manager:force_add_trait(
      string     character string,
      string     trait key,
      [boolean     show message],
      [number     points]
    )
    Forceably adds an trait to a character. This calls the function of the same name on the game interface, but adds validation and output. This output will be shown on the traits tab of the console.

    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 12335

    campaign_manager:add_trait_to_character_by_family_member(
      number     family_member_cqi,
      string     trait key,
      [boolean     show message],
      [number     points]
    )
    Grants the specified trait to a character specified by a family member. If character object doesn't exist, the trait is added to the persistent data of the character. If the character already has the trait, a trait point will be added. This calls the function of the same name on the game interface, but adds validation and output. This output will be shown on the traits tab of the console.

    Parameters:

    1

    number

    CQI of the family member of the target character

    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 12360

    campaign_manager:force_add_skill(string character string, string skill key)
    Forceably adds a skill to a character. This calls the function of the same name on the game interface, but adds validation and output. This output will be shown on the traits tab of the console.

    Parameters:

    1

    string

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

    2

    string

    Skill key to add.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12386

    campaign_manager:force_remove_skill(string character string, string skill key, [boolean refund skill point])
    Forcibly removes a skill from a character. This calls the function of the same name on the game interface, but adds validation and output. This output will be shown on the traits tab of the console.

    Parameters:

    1

    string

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

    2

    string

    Skill key to remove.

    3

    boolean

    optional, default value=true

    Whether to refund a skill point when the skill is successfully removed

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12406

    campaign_manager:reset_skills_for_character(number character cqi(command q index))
    Forceably resets skilsl of a character. This calls the function force_reset_skills(), but adds validation and output. This output will be shown on the traits tab of the console.

    Parameters:

    1

    number

    character cqi(command q index)

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12431

    campaign_manager:rank_up_agent(string cqi, number rank)
    Forceably adds experience to a character in order for it to reach a certain rank (no downgrading is supported). This calls a couple of times the function add_agent_experience on the game interface.

    Parameters:

    1

    string

    Character CQI as a string.

    2

    number

    Rank to be reached.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12447

    campaign_manager:add_agent_experience(
      string     character string,
      number     experience,
      [boolean     by_level],
      [boolean     suppress_output]
    )
    Forceably adds experience to a character. This calls the function of the same name on the game interface, but adds output.

    Parameters:

    1

    string

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

    2

    number

    Experience to add.

    3

    boolean

    optional, default value=false

    If set to true, the level/rank can be supplied instead of an exact amount of experience which is looked up from a table in the campaign manager. Note that this is not advised as this table is easily going out of sink with the DB. Use rank_up_agent function instead!

    4

    boolean

    optional, default value=false

    If set to true output is added.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12475

    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 x co-ordinate.

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12518

    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 12542

    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 12563

    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 12587

    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 12606

    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 12634

    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 12662

    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 to display the text for.

    6

    number

    optional, default value=255

    Red value

    7

    number

    optional, default value=255

    Green value

    8

    number

    optional, default value=255

    Blue value

    9

    number

    optional, default value=255

    Alpha value

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12696

    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 to display the text for.

    5

    number

    optional, default value=255

    Red value

    6

    number

    optional, default value=255

    Green value

    7

    number

    optional, default value=255

    Blue value

    8

    number

    optional, default value=255

    Alpha value

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12726

    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 to display the text for.

    8

    number

    optional, default value=255

    Red value

    9

    number

    optional, default value=255

    Green value

    10

    number

    optional, default value=255

    Blue value

    11

    number

    optional, default value=255

    Alpha value

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 12754

    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 12796

    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 12838

    campaign_manager:restrict_building_chains_for_faction(
      string     faction name,
      table     building chain list,
      [boolean     should restrict]
    )
    Restricts or unrestricts a faction from constructing buildings from one or more building chains.

    Parameters:

    1

    string

    Faction name.

    2

    table

    Numerically-indexed table of string building chain 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 12881

    campaign_manager:restrict_buildings_for_faction_with_manual_conversion(
      string     faction name,
      table     building list,
      [boolean     should restrict]
    )
    Restricts or unrestricts a faction from constructing one or more building types, but sets them to be manualy converted for human factions if they acquire a region with them in it.

    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 12924

    campaign_manager:restrict_building_chains_for_faction_with_manual_conversion(
      string     faction name,
      table     building chain list,
      [boolean     should restrict]
    )
    Restricts or unrestricts a faction from constructing buildings from one or more building chains, but sets them to be manualy converted for human factions if they acquire a region with them in it.

    Parameters:

    1

    string

    Faction name.

    2

    table

    Numerically-indexed table of string building chain 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 12967

    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 13010

    Back to top

    Effect Bundles

    These this section contains functions that add and remove effect bundles from factions, military forces and regions. In each case they wrap a function of the same name on the underlying game interface, providing input validation and console 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 13069

    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 13101

    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 13122

    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 13154

    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 13175

    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 13207

    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 13228

    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 13260

    campaign_manager:apply_effect_bundle_to_province(string effect bundle key, string region key, number turns)
    Applies an effect bundle to a province 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 13280

    campaign_manager:remove_effect_bundle_from_province(string effect bundle key, string number cqi)
    Removes an effect bundle from a province.

    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 13311

    campaign_manager:clone_or_create_custom_effect_bundle(string faction key, string effect bundle key)
    Checks if the provided faction already has an active effect bundle with that key and returns a custom variant with cloned effects. Otherwise acts as create_custom_effect_bundle.

    Parameters:

    1

    string

    Faction name from the factions table.

    2

    string

    Effect bundle key from the effect bundles table.

    Returns:

    1. custom_effect_bundle custom effect bundle

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13332

    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 13372

    campaign_manager:make_regions_visible_in_shroud_for_faction(string faction key, table region keys)

    Lifts the shroud for a supplied faction from each region in a supplied list.

    Parameters:

    1

    string

    Faction key, from the factions database table.

    2

    table

    Table of region keys, each from the regions database table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13385

    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"

    • "subjugate"

    • "become subject"

    • "peace"

    • "war"

    • "join war"

    • "break trade"

    • "break alliance"

    • "hostages"

    • "marriage"

    • "non aggression pact"

    • "soft military access"

    • "cancel soft military access"

    • "defensive alliance"

    • "client state"

    • "form confederation"

    • "break non aggression pact"

    • "break soft military access"

    • "break defensive alliance"

    • "break vassal"

    • "break subject"

    • "break client state"

    • "state gift unilateral"

    • "diplomatic gift"

    • "single barters"

    • "barter agreements"

    • "cancel barters"

    • "dominance"

    • "adoption in dynasty"

    • "forced inheritance"

    • "legitimacy support"

    • "political marriage"

    • "diplomatic marriage"

    • "all"

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

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

    Parameters:

    1

    string

    Source faction/factions identifier.

    2

    string

    Target faction/factions identifier.

    3

    string

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

    4

    boolean

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

    5

    boolean

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

    6

    boolean

    optional, default value=false

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

    7

    boolean

    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 13468

    campaign_manager:force_diplomacy_via_string(
      string     source,
      string     target,
      string     type,
      boolean     can offer,
      boolean     can accept,
      [both     directions],
      [do     not enable payments]
    )
    A lightweight version of the force_diplomacy function that can be called without performance concerns.
    Note that the game interface function that this function calls is force_diplomacy_new_s, not force_diplomacy.

    Parameters:

    1

    string

    Source faction/factions identifier.

    2

    string

    Target faction/factions identifier.

    3

    string

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

    4

    boolean

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

    5

    boolean

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

    6

    both

    optional, default value=false

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

    7

    do

    optional, default value=false

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

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13671

    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 13708

    campaign_manager:force_declare_war(
      string     faction key,
      string     faction key,
      boolean     invite faction a allies,
      boolean     invite faction b allies,
      boolean     forced choice
    )
    Forces war between two factions. This calls the function of the same name on the game interface, but adds validation and output. This output will be shown on the design tab of the console.

    Parameters:

    1

    string

    Faction A key

    2

    string

    Faction B key

    3

    boolean

    Invite faction A's allies to the war

    4

    boolean

    Invite faction B's allies to the war

    5

    boolean

    faction A will have lower treachery penalties if they have any treaties with faction B if this is true

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 13722

    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 13936

    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 13948

    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 13961

    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 13970

    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 13978

    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 13986

    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 13997

    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 14008

    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 14019

    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 14027

    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 14035

    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 14044

    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 14053

    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 14062

    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 14071

    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 14079

    campaign_manager:set_infotext_auto_clear_timer(
          number seconds,
      [boolean     should_dismiss_advice_on_infotext_auto_hide_time_elapsed]
    )

    Pass-through function for infotext_manager:set_auto_clear_timer. Clears all infotexts after the specified time. Mouse over the infotext panel will freeze the timer. A value <= 0 will cancel any current timer

    Parameters:

    1

    number

    seconds

    2

    boolean

    optional, default value=false

    should_dismiss_advice_on_infotext_auto_hide_time_elapsed

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14086

    Back to top

    Missions and Events

    campaign_manager:cancel_mission(string faction key, string mission key)
    Cancels (aborts) a specific custom mission from its database record key. This function wraps the cm:cancel_mission function on the game interface, adding console output.

    Parameters:

    1

    string

    Faction key.

    2

    string

    Mission key.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14106

    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 console 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=false

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

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14124

    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 a function of the same name on the underlying game interface.

    Parameters:

    1

    string

    faction key

    2

    string

    Mission definition string.

    3

    boolean

    optional, default value=false

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

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14150

    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.
    This function wraps the cm:trigger_mission function on the game interface, adding console output and event type whitelisting.

    Parameters:

    1

    string

    Faction key.

    2

    string

    Mission key, from the missions table.

    3

    boolean

    optional, default value=false

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

    4

    boolean

    optional, default value=false

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

    Returns:

    1. boolean mission triggered successfully

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14167

    campaign_manager:trigger_custom_dilemma(
      string     faction_key,
      string     dilemma_key,
      string     payload1,
      string     payload2,
      [string     payload3],
      [string     payload4]
    )
    Compels the campaign director to trigger a custom dilemma, 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.

    Parameters:

    1

    string

    Faction key.

    2

    string

    Dilemma key, from the dilemma table.

    3

    string

    Payload string for first choice.

    4

    string

    Payload string for second choice.

    5

    string

    optional, default value=nil

    Payload string for third choice.

    6

    string

    optional, default value=nil

    Payload string for fourth choice.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14188

    campaign_manager:trigger_custom_dilemma_raw(
      string     faction_key,
      string     dilemma_key,
      string     payload1,
      string     payload2,
      [string     payload3],
      [string     payload4]
    )
    Compels the campaign director to trigger a custom dilemma, based on a record from the database. This wraps a function of the same name on the underlying game interface.

    Parameters:

    1

    string

    Faction key.

    2

    string

    Dilemma key, from the dilemma table.

    3

    string

    Payload string for first choice.

    4

    string

    Payload string for second choice.

    5

    string

    optional, default value=nil

    Payload string for third choice.

    6

    string

    optional, default value=nil

    Payload string for fourth choice.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14249

    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

    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 14267

    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 console 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 14357

    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,
      [number     family_member_cqi]
    )

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

    Parameters:

    1

    number

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

    2

    string

    Dilemma key, from the dilemmas table.

    3

    number

    optional, default value=0

    Command-queue index of a target faction.

    4

    number

    optional, default value=0

    Command-queue index of a second target faction.

    5

    number

    optional, default value=0

    Command-queue index of a target character.

    6

    number

    optional, default value=0

    Command-queue index of a target military force.

    7

    number

    optional, default value=0

    Command-queue index of a target region.

    8

    number

    optional, default value=0

    Command-queue index of a target settlement.

    9

    function

    Callback to call when the intervention actually gets triggered.

    10

    number

    optional, default value=0

    Command-queue index of a target family member.

    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 14393

    campaign_manager:trigger_dilemma_with_targets_raw(
          number faction cqi,
      string     dilemma key,
      [number     target faction cqi],
      [number     secondary faction cqi],
      [number     character cqi],
      [number     military force cqi],
      [number     region cqi],
      [number     settlement cqi],
      [boolean     whitelist],
      [number     family_member_cqi]
    )

    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 console output and event type whitelisting, but not featuring the intervention-wrapping behaviour of campaign_manager:trigger_dilemma_with_targets. Use this function if triggering the dilemma from within an intervention, but campaign_manager:trigger_dilemma_with_targets (or campaign_manager:trigger_dilemma) in all other instances.
    The game object or objects to associate the dilemma with are specified by command-queue index. The dilemma will need to pass any conditions set up in the cdir_events_dilemma_option_junctions table in order to trigger.

    Parameters:

    1

    number

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

    2

    string

    Dilemma key, from the dilemmas table.

    3

    number

    optional, default value=0

    Command-queue index of a target faction.

    4

    number

    optional, default value=0

    Command-queue index of a second target faction.

    5

    number

    optional, default value=0

    Command-queue index of a target character.

    6

    number

    optional, default value=0

    Command-queue index of a target military force.

    7

    number

    optional, default value=0

    Command-queue index of a target region.

    8

    number

    optional, default value=0

    Command-queue index of a target settlement.

    9

    boolean

    optional, default value=false

    bool to whitelist the event feed event even if events are suppressed

    10

    number

    optional, default value=0

    Command-queue index of a target family member.

    Returns:

    1. boolean Dilemma triggered successfully.

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14476

    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 console 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 14666

    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 14863

    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 14893

    campaign_manager:disable_event_feed_events(
      boolean     should disable,
      [string     event categories],
      [string     event subcategories],
      [string     event]
    )
    Wrapper for the function of the same name on the underlying game interface. Disables event feed events by category, subcategory or individual event type. Unlike campaign_manager:suppress_all_event_feed_messages the events this call blocks are discarded. Use this function to prevent certain events from appearing.

    Parameters:

    1

    boolean

    Should disable event type(s).

    2

    string

    optional, default value=""

    Event categories to disable. Supply "" or false/nil to not disable/enable events by categories in this function call. Supply "all" to disable all event types.

    3

    string

    optional, default value=""

    Event subcategories to disable. Supply "" or false/nil to not disable/enable events by subcategories in this function call.

    4

    string

    optional, default value=""

    Event to disable. Supply "" or false/nil to not disable/enable an individual event in this function call.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14906

    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],
      [    number param 1],
      [number     param 2],
      [number     param 3],
      [string     str_param 1],
      [string     str_param 2],
      [string     str_param 3]
    )

    Constructs and displays an event. This wraps a the cm:show_message_event function of the same name on the underlying episodic_scripting, although it provides input validation, output, whitelisting and a progression callback.

    Parameters:

    1

    string

    Faction key to who the event is targeted.

    2

    string

    Localisation key for the event title. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.

    3

    string

    Localisation key for the primary detail of the event. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.

    4

    string

    Localisation key for the secondary detail of the event. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.

    5

    boolean

    Sets this event to be persistent instead of transient.

    6

    number

    Index indicating the type of event.

    7

    function

    optional, default value=false

    Specifies a callback to call when this event is dismissed. Note that if another event message shows first for some reason, this callback will be called early.

    8

    number

    optional, default value=0

    Delay in seconds before calling the end callback, if supplied.

    9

    boolean

    optional, default value=false

    By default this function will whitelist the scripted event message type with campaign_manager:whitelist_event_feed_event_type. Set this flag to true to prevent this.

    10

    number

    optional, default value=0

    1st numeric parameter to pass through to the underlying message event generator. This is only used in specific circumstances.

    11

    number

    optional, default value=0

    2nd numeric parameter to pass through to the underlying message event generator. This is only used in specific circumstances.

    12

    number

    optional, default value=0

    3rd numeric parameter to pass through to the underlying message event generator. This is only used in specific circumstances.

    13

    string

    optional, default value=0

    1st string parameter to pass through to the underlying message event generator. This is only used in specific circumstances.

    14

    string

    optional, default value=0

    2nd string parameter to pass through to the underlying message event generator. This is only used in specific circumstances.

    15

    string

    optional, default value=0

    3rd string parameter to pass through to the underlying message event generator. This is only used in specific circumstances.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 14928

    campaign_manager:show_message_event_located(
      string     faction key,
      string     title loc key,
      string     primary loc key,
      string     secondary loc key,
      number     x,
      number     y,
      boolean     persistent,
      number     index,
      [function     end callback],
      [number     callback delay]
    )
    Constructs and displays a located event. This wraps a function of the same name on the underlying game interface, although it provides input validation, output, whitelisting and a progression callback.

    Parameters:

    1

    string

    Faction key to who the event is targeted.

    2

    string

    Localisation key for the event title. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.

    3

    string

    Localisation key for the primary detail of the event. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.

    4

    string

    Localisation key for the secondary detail of the event. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.

    5

    number

    Logical x co-ordinate of event target.

    6

    number

    Logical y co-ordinate of event target.

    7

    boolean

    Sets this event to be persistent instead of transient.

    8

    number

    Index indicating the type of event.

    9

    function

    optional, default value=false

    Specifies a callback to call when this event is dismissed. Note that if another event message shows first for some reason, this callback will be called early.

    10

    number

    optional, default value=0

    Delay in seconds before calling the end callback, if supplied.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15123

    Back to top

    Transient Interventions

    intervention offer a script method for locking the campaign UI and progression until the sequence of scripted events has finished. The main intervention interface should primarily be used when creating interventions, but this section lists functions that can be used to quickly create transient throwaway interventions, whose state is not saved into the savegame. See Transient Interventions for more information.

    campaign_manager:trigger_transient_intervention(
          string name,
      function     callback,
      [boolean     debug],
      [function     configuration callback]
    )

    Creates, starts, and immediately triggers a transient intervention with the supplied paramters. This should trigger immediately unless another intervention is running, in which case it should trigger afterwards.
    The trigger callback that is supplied to this function will be passed the intervention object when it is called. This callback must call intervention:complete on this object, or cause it to be called, as the UI will be softlocked until the intervention is completed. See intervention documentation for more information.

    Parameters:

    1

    string

    Name for intervention. This should be unique amongst interventions.

    2

    function

    Trigger callback to call.

    3

    boolean

    optional, default value=true

    Sets the intervention into debug mode, in which it will produce more output. Supply false to suppress this behaviour.

    4

    function

    optional, default value=nil

    If supplied, this function will be called with the created intervention supplied as a single argument before the intervention is started. This allows calling script to configure the intervention before being started.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15222

    Back to top

    Turn Countdown Events

    The turn countdown event system allows client scripts to register a string event with the campaign manager. The campaign manager will then trigger the event at the start of turn, a set number of turns later. This works even if the game is saved and reloaded. It is intended to be a secure mechanism for causing a scripted event to occur a number of turns in the future.

    campaign_manager:add_turn_countdown_event(
          string faction key,
      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 15281

    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 15304

    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 the game has already advanced past the turn specified then the event will never trigger.

    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 15329

    Back to top

    Interventions

    campaign_manager:get_active_intervention()
    Gets the currently-active intervention, or false if no intervention is currently active.

    Returns:

    1. intervention active intervention

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 15545

    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 15595

    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 15640

    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 15868

    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 15914

    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 15948

    Back to top

    Region slot modifiers

    campaign_manager:replace_building_in_region_slot(
      string     region_key,
      number     slot_num,
      string     building_level_key,
      string     constructing_building_level_key
    )
    Instantly destroys the current building in the slot and instantly builds the new building in the slot. Uses instantly_upgrade_building_in_region and instantly_dismantle_building_in_region. Will not expend resources.
    Will also update the building level record for the currently-constructing building if such in the slot and constructing_building_level_key is supplied

    Parameters:

    1

    string

    region key

    2

    number

    slot index

    3

    string

    building_level_key of the building to build

    4

    string

    (optional) building_level_key of the currently-constructed building

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16045

    Back to top

    Military Force slot modifiers

    campaign_manager:instantly_dismantle_building_in_force(
      number     force_cqi,
      number     slot_index,
      [boolean     recoup_resources],
      [boolean     silent]
    )
    Instantly dismantles the building in the supplied slot index of the supplied force.

    Parameters:

    1

    number

    military force command queue index

    2

    number

    military force slot index

    3

    boolean

    optional, default value=true

    whether to recoup the resources for the dismantled building

    4

    boolean

    optional, default value=false

    whether to suppress the firing of an event feed event for the dismantled building

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16092

    campaign_manager:instantly_upgrade_building_in_force(
      number     force_cqi,
      number     slot_index,
      string     target_building_key
    )
    Instantly upgrades the supplied building key in the supplied slot index of the supplied force.

    Parameters:

    1

    number

    military force command queue index

    2

    number

    military force slot index

    3

    string

    the building key to upgrade the current building/slot in slot_index to

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16133

    campaign_manager:replace_building_in_force_slot(
      number     force_cqi,
      number     slot_index,
      string     building_level_key,
      boolean     recoup_resources
    )
    Instantly destroys the current building in the slot and instantly builds the new building in the slot. Uses instantly_dismantle_building_in_force and instantly_upgrade_building_in_force. Will not expend resources.

    Parameters:

    1

    number

    military force command queue index

    2

    number

    military force slot index

    3

    string

    building_level_key of the building to build

    4

    boolean

    whether to recoup the resources for the dismantled building

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16172

    Back to top

    Benchmark Scripts

    campaign_manager:show_benchmark_if_required(
      function     non-benchmark callback,
      string     cindy file,
      number     benchmark duration,
      number     cam x,
      number     cam y,
      number     cam d,
      number     cam b,
      number     cam h
    )
    Shows a benchmark constructed from supplied parameters if the campaign loaded in benchmark mode, otherwise calls a supplied callback. The intention is for this to be called on or around the first tick of the script that's loaded when playing as the benchmark faction (the benchmark loads with the player as a certain faction). If benchmark mode is set, this function plays the supplied cindy scene for the supplied duration, then quits the campaign.

    Parameters:

    1

    function

    Function to call if this campaign has not been loaded in benchmarking mode.

    2

    string

    Cindy file to show for the benchmark.

    3

    number

    Benchmark duration in seconds.

    4

    number

    Start x position of camera.

    5

    number

    Start y position of camera.

    6

    number

    Start distance of camera.

    7

    number

    Start bearing of camera (in radians).

    8

    number

    Start height of camera.

    Returns:

    1. nil

    Example:

    cm:add_first_tick_callback_sp_new(
        function()
            cm:start_intro_cutscene_on_loading_screen_dismissed(
                function()
                    cm:show_benchmark_if_required(
                        function() cutscene_intro_play() end,
                        "script/benchmarks/scenes/campaign_benchmark.CindyScene",
                        92.83,
                        348.7,
                        330.9,
                        10,
                        0,
                        10
                    );
                end
            );
        end
    );

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16190

    Back to top

    Iteration Helpers

    campaign_manager:recursive_iterate(function iterate_function, object object, table iteration_instructions)
    Iterates through an object with specific instructions on iteration steps. The goal is to go through multiple lists and to reach only what is relevant for you. For example, you can iterate through all building slots without having to write a lot of for loops

    Parameters:

    1

    function

    Function to call for each object when iterating. Should accept 1 argument, the object

    2

    object

    The starting object from where we begin the iteration

    3

    table

    A list of instructions on how to iterate through the object

    Returns:

    1. nil

    Example:

    cm:recursive_iterate(
        function(slot)
            out("slot name="..slot:name()..", slot type="..slot:type())
        end,
        cm:model():world(),
        { "faction_list", "region_list", "slot_list" }
    );

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16300

    campaign_manager:iterate(function iterate_function, object objects)
    Iterates through a regular table with ipairs or through a list script interface object.

    Parameters:

    1

    function

    Function to call for each object when iterating. Should accept 1 argument, the object

    2

    object

    The objects we are iterating through

    Returns:

    1. nil

    Example:

    cm:iterate(
        function(faction)
            out(faction:name())
        end,
        (using_all_factions and cm:model():world():faction_list()) or { faction1, faction2, faction3 }
    );

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16329

    campaign_manager:iterate_list_script_interface(function iterate_function, object objects)
    Iterates through a list script interface object.

    Parameters:

    1

    function

    Function to call for each object when iterating. Should accept 1 argument, the object

    2

    object

    The objects we are iterating through

    Returns:

    1. nil

    Example:

    cm:iterate(
        function(faction)
            out(faction:name())
        end,
        cm:model():world():faction_list()
    );

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16347

    campaign_manager:iterate_list(function iterate_function, object objects)
    Iterates through a regular lua array with ipairs

    Parameters:

    1

    function

    Function to call for each object when iterating. Should accept 1 argument, the object

    2

    object

    The objects we are iterating through

    Returns:

    1. nil

    Example:

    cm:iterate(
        function(it)
            out(it)
        end,
        { "string1", "string2", "string3" }
    );

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16376

    campaign_manager:iterate_factions(function iterate_function, [object list])
    Iterates through factions in a list or through all in the game's model

    Parameters:

    1

    function

    Function to call for each faction when iterating. Should accept 1 argument, the faction

    2

    object

    optional, default value=nil

    A list of factions we're iterating through. If nil will iterate through ALL factions

    Returns:

    1. nil

    Example:

    cm:iterate_factions(
        function(faction)
            out(faction:name())
        end
    );

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16402

    campaign_manager:iterate_forces(function iterate_function, [object list])
    Iterates through forces in a list, faction or through all in the game's model

    Parameters:

    1

    function

    Function to call for each force when iterating. Should accept 1 argument, the force

    2

    object

    optional, default value=nil

    A list of forces we're iterating through or a faction script interface. If nil will iterate through ALL forces

    Returns:

    1. nil

    Example:

    cm:iterate_forces(
        function(force)
            out(tostring(force:command_queue_index()))
        end
    );

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16419

    campaign_manager:iterate_regions(function iterate_function, [object list])
    Iterates through regions in a list, faction or through all in the game's model

    Parameters:

    1

    function

    Function to call for each region when iterating. Should accept 1 argument, the region

    2

    object

    optional, default value=nil

    A list of regions we're iterating through or a faction script interface. If nil will iterate through ALL regions

    Returns:

    1. nil

    Example:

    cm:iterate_regions(
        function(region)
            out(region:name())
        end
    );

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16456

    campaign_manager:iterate_characters(function iterate_function, [object list])
    Iterates through characters in a list, faction or through all in the game's model

    Parameters:

    1

    function

    Function to call for each character when iterating. Should accept 1 argument, the character

    2

    object

    optional, default value=nil

    A list of characters we're iterating through or a faction script interface. If nil will iterate through ALL characters

    Returns:

    1. nil

    Example:

    cm:iterate_characters(
        function(character)
            out(character:get_forename())
        end
    );

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16493

    campaign_manager:iterate_break([number num_levels])
    Breaks through an iteration, default of 1 level

    Parameters:

    1

    number

    optional, default value=nil

    Number of levels to break through. 1 by default

    Returns:

    1. nil

    Example:

    cm:iterate_characters(
        function(character)
            out(character:get_forename())
            if character:get_forename() == "cool_guy_666" then
                -- Iteration will break here
                cm:iterate_break()
                return
            end
        end
    );

    cm:recursive_iterate(
        function(slot)
            if slot:name() == "cool_slot_322" then
                -- Iteration will break for slots and we will go to the next region here
                cm:iteration_break()
                return
            elseif slot:name() == "very_cool_slot_1337" then
                -- Iteration will break for slots and for regions, and we will go to the next faction
                cm:iteration_break(2)
                return
            end
        end,
        cm:model():world(),
        { "faction_list", "region_list", "slot_list" }
    );

    defined in ../../Warhammer/working_data/script/_lib/lib_campaign_manager.lua, line 16530

Last updated 8/23/2024 4:55:15 PM